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.
A Google Ads account can be viewed as a hierarchy of objects.
The top-level resource of an account is the customer.
Each customer contains one or more active campaigns.
Each campaign contains one or more ad groups, used to group your ads into logical collections.
An ad group ad represents an ad that you're running. Except for app campaigns which can have only one ad group ad per ad group, each ad group contains one or more ad group ads.
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.
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?|
|Ad ID||Ad Group||No, but (
|AdGroupCriterion ID||Ad Group||No, but (
|CampaignCriterion ID||Campaign||No, but (
|Ad Extensions||Campaign||No, but (
|Feed Item ID||Global||Yes|
|Feed Attribute ID||Feed||No|
|Feed Mapping 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
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
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:
So for a campaign with ID
987654 in the Google Ads account with customer ID
resource_name would be:
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
request. They also supply a
get request that retrieves a single resource
instance, which can be useful for examining the structure of a resource.
Examples of services:
mutate request must include corresponding
operation objects. For
CampaignService.MutateCampaigns method expects one or more
Changing and Inspecting Objects for a
detailed discussion of operations.
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
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.
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
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.
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.
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.