Google Ads API is returning to beta status. Please read our blog post for more details.

Format Changes in the Google Ads API

Customer ID format

In the AdWords API, you could specify your customer ID either as a 10-digit number or a string in the format XXX-XXX-XXXX. Now, in the Google Ads API, you must specify your Customer ID as a 10-digit number without dashes.

Request format

In the AdWords API, requests could be made using either a query language or an XML selector. Now, in the Google Ads API, the type of request you're making dictates a specific request format.

When searching, which you would do to find a list of entities that match a specific set of criteria, use the Google Ads Query Language to make a request against the GoogleAdsService. No selector option is supported for this use case and all searches are made against the same service, regardless of entity type.

Get

When fetching all details for a specific entity, say a campaign, use the appropriate service (in this case CampaignService), and provide the resource name of the entity you want to fetch. For example, a campaign's resource name is in the form /customers/XXXXXXXXXX/campaigns/YYYYYYYYYY, where XXXXXXXXXX is your customer ID without dashes, and YYYYYYYYYY is the campaign ID.

Mutate

Mutate calls use the same service as get calls; for example CampaignService is used to mutate campaigns.

In the AdWords API, mutating calls would return the new state of the object upon completion. Now, in the Google Ads API, mutate calls only return the resource name of the mutated entity. If you want to verify the changed state of the object, make another API call to fetch the object.

Mutate calls require an operation, which takes one of three possible parameters:

Create
Requires that you pass a completed object including its resource name, all required fields, and any optional fields you wish to set.
Update

Requires that you pass an object including its resource name and all fields you wish to modify along with their new values.

Requires that you pass an update mask, which is a list of fields that you to modify on that object. This is useful so that you can use the return value from a previous get call and only modify some of the fields, or instantiate a new object and only set the fields you wish to update. Client libraries will provide a tool to help determine the update mask for an update request.

Remove

Requires only a resource name.

Response format

In the AdWords API, searching for and fetching fields for entities was one and the same, but that is no longer the case in the Google Ads API. The difference in request parameters also results in a difference in response formats for the two actions.

When searching using the GoogleAdsService, responses will include one GoogleAdsRow for each entity that matched your search parameters. Each row contains one object, for example a campaign, and the only fields populated on this object are the fields that you specifically requested in your query.

When fetching using a specific service, say CampaignService, you can only request a single entity at a time by resource name, and all fields for that entity will be populated in the response.