API Structure

Video: Check out the Services and Resources talk from the 2019 workshop

This guide introduces the primary components that make up the Google Ads API. The Google Ads API consists of resources and services. A resource represents a Google Ads entity, while services retrieve and manipulate Google Ads entities.

Object hierarchy

A Google Ads account can be viewed as a hierarchy of objects.

• The top-level resource of an account is the customer.

• Each account contains one or more active campaigns.

• Each Campaign contains one or more ad groups, used to group your ads into logical collections.

• Each AdGroup contains one or more ad group ads. An AdGroupAd represents an ad that you're running.

You can attach one or more AdGroupCriterion or CampaignCriterion to an ad group or campaign. These represent criteria that define how ads get triggered.

There are many criterion types, such as keywords, age ranges, and locations. Criteria defined at the campaign level affect all other resources within the campaign. You can also specify campaign-wide budgets and dates.

Finally, you can attach extensions at the account, campaign, or ad group level. Extensions allow you to provide extra information to your ads, like phone number, street address, or promotions.

Resources

Resources represent the entities within your Google Ads account. Campaign and AdGroup are two examples of resources.

Object IDs

Every object in Google Ads is identified by its own ID. Some of these IDs are globally unique across all Google Ads accounts, while others are unique only within a confined scope.

Object ID	Scope of Uniqueness	Globally Unique?
Budget ID	Global	Yes
Campaign ID	Global	Yes
AdGroup ID	Global	Yes
Ad ID	Ad Group	No, but (AdGroupId, AdId) pair is globally unique
AdGroupCriterion ID	Ad Group	No, but (AdGroupId, CriterionId) pair is globally unique
CampaignCriterion ID	Campaign	No, but (CampaignId, CriterionId) pair is globally unique
Ad Extensions	Campaign	No, but (CampaignId, AdExtensionId) pair is globally unique
Feed ID	Global	Yes
Feed Item ID	Global	Yes
Feed Attribute ID	Feed	No
Feed Mapping ID	Global	Yes
Label ID	Global	Yes
UserList ID	Global	Yes

These ID rules can be useful when designing local storage for your Google Ads objects.

Some objects can be used for multiple entity types. In such cases, the object contains a type field that describes its contents. For example, AdGroupAd can refer to a text ad, hotel ad, local ad, etc. This value can be accessed through the AdGroupAd.ad.type field, and returns a value in the AdType enum.

Resource names

Each resource is uniquely identified by a resource_name string, that concatenates the resource and its parents into a path. For instance, campaign resource names have the form:

customers/customer_id/campaigns/campaign_id

So for a campaign with ID 987654 in the Google Ads account with customer ID 1234567, the resource_name would be:

customers/1234567/campaigns/987654

Services

Services let you retrieve and modify your Google Ads entities. There are three types of services: modification, object and stat retrieval, and metadata retrieval services.

Modify (mutate) objects

These services modify instances of an associated resource type using a mutate request. They also supply a get request that retrieves a single resource instance, which can be useful for examining the structure of a resource.

Key Point: get requests are limited to 1,000 per day. For most real-world use cases, you should instead request reports using GoogleAdsService.

Examples of services:

• CustomerService for modifying customers.

• CampaignService for modifying campaigns.

• AdGroupService for modifying ad groups.

Each mutate request must include corresponding operation objects. For example, the CampaignService.MutateCampaigns method expects one or more instances of CampaignOperation. See Changing and Inspecting Objects for a detailed discussion of operations.

Concurrent mutates

A Google Ads object cannot be modified concurrently by more than one source. This could cause errors to arise if you have multiple users updating the same object with your app, or if you're mutating Google Ads objects in parallel using multiple threads. This includes updating the object from multiple threads in the same application, or from different applications (for example, your app and a simultaneous Google Ads UI session).

The API does not provide a way to lock an object before updating; if two sources try to simultaneously mutate an object, the API raises a DatabaseError.CONCURRENT_MODIFICATION_ERROR.

Asynchronous versus synchronous mutates

The Google Ads API mutate methods are synchronous. API calls return a response only after the objects are mutated, requiring you to wait for a response to each request. While this approach is relatively straightforward to code, it could negatively impact load balancing and waste resources if processes are forced to wait for calls to complete.

An alternate approach is to mutate objects asynchronously using BatchJobService, which performs batches of operations on multiple services without waiting for their completion. Once a batch job is submitted, Google Ads API servers execute operations asynchronously, freeing processes to perform other operations. You can periodically check the job status for completion.

See the Batch Processing guide for more on asynchronous processing.

Mutate validation

Most mutate requests can be validated without actually executing the call against real data. You can test the request for missing parameters and incorrect field values without actually executing the operation.

To use this feature, set the request's optional validate_only boolean field to true. The request would then be fully validated as if it were going to be executed, but the final execution is skipped. If no errors are found, an empty response is returned. If validation fails, error messages in the response will indicate the failure points.

validate_only is particularly useful in testing ads for common policy violations. Ads are automatically rejected if they violate policies such as having specific words, punctuation, capitalization, or length. A single bad ad could cause an entire batch to fail. Testing a new ad within a validate_only request can reveal any such violations. Refer to the code example for handling policy violation errors to see this in action.

Get objects and performance stats

GoogleAdsService is the single, unified service for retrieving objects and performance statistics.

All Search and SearchStream requests for GoogleAdsService require a query that specifies the resource to query, the resource attributes and performance metrics to retrieve, the predicates to use for filtering the request, and the segments to use to further break down performance statistics. For more information about query format, check out the Google Ads Query Language guide.

Retrieve metadata

GoogleAdsFieldService retrieves metadata about resources in the Google Ads API, such as the available attributes for a resource and its data type.

This service provides information you'll need in constructing a query to GoogleAdsService. For convenience, the information returned by GoogleAdsFieldService is also available in the fields reference documentation.

Key Point: If you are migrating from the AdWords API, think of GoogleAdsFieldService as a combination of ReportDefinitionService and the list of selector fields in the AdWords API.