Google Ads API Beta(v2.1) Short Notes


  • Developer token
    • generate from a Google Ads Manager Account
    • you can use the same token for not linked account
    • token state: pending, approved
    • only approved token can connect to the API for production
    • Use any developer token if you using Test Manager Account view doc
  • Custermer ID
    • the account number of an Google Ads account
    • can be set or replace programmatically in the SDK
  • OAuth2 client credential
    • generate from a GCP Project/API Console
    • use for managing the API users
  • Client Library

Basic first call (installed application flow)

Step 1

  1. register an Google Ads Manager Account for production use
  2. take the developer token from UI
    > TOOL > SETTINGS > API Center

step refs:

You must use a production (non-test) manager account’s developer token to make API calls against a test account. Even if the token is pending approval, you can still use it to make calls against test accounts.

Step 2

  1. create a Google Account for testing
  2. use the Google Account to register a Google Ads Manager Account
  3. login and create one customer account (the customer created by test manager account will be test only)
  4. create a campaign under the customer account

step refs:


Step 3

If already has an OAuth client:

  1. assume the client ID is
  2. go to API console, find the OAuth2.0 client ID then download the client secret json file
  3. use this secret to request a generate refresh token


  1. create a GCP project
  2. enable the GoogleAds API in API console page
  3. create a OAuth client, assume the client ID is
  4. download the client secret json file
  5. use this secret to request a generate refresh token

step refs:


When requesting an OAuth2 refresh token, make sure you’re logged in as the test manager account user

To access a test account using OAuth2, the test manager account user must grant permission to your client application. Therefore, when requesting a refresh token, ensure you’re logged in as the test manager account rather than the production manager account.

you want to switch from the test manager account to the production manager account, simply reconfigure the client library to use the production manager account’s refresh token.

Step 4

  1. install client library
  2. create an sdk config file google-ads.yml and insert the values:
    • developer_token
    • client_id
    • client_secret
    • refresh_token
    • logincustomerid
  3. initial a client object that loads the config file
  4. make the first call to search the campaign we just created


API Structure


  • represents a Google Ads entity e.g. Campaign
  • each resources uniquely identified by a resource_name
  • top-level and non-top-level
    • Campaign is top-level
    • Campaign.NetworkSettings is non-top-level


  • object modifier services
    • CustormerService
    • CampaignService
    • AdGroupService
  • object retrieving serviceGoogleAdsService (as an single, unified interface)

    require a query that specifies the resource to query

Object modifying

An object modify request contains:

  • customer ID
  • a mutation object

An mutate object contains:

  • multiple operation object

A mutate response contains:

  • resource names of each CUD object (not corresponding)

An operation object contains:

  • an OneOf field
    > Oneof fields are like optional fields except all the fields in a oneof share memory, and at most one field can be set at the same time
    > you cannot use a single operation to modify multiple objects
  • get, create, update, remove methods
    > the get method accepts a get request whose only attribute is resource_name for mutate response
    > you should not use get methods to retrieve objects for processing or reporting. Instead, use GoogleAdsService search method.


a single operation can only either create, update, or remove a single resource
you should combine your operations into a single mutate request instead of sending multiple mutate requests that each contain a single operation

Object retrieving

Using search method

  • get object’s specific attributes
  • get performance metrics for objects
  • ordering objects
  • filtering objects
  • paging objects
  • limiting objects

A search request object SearchGoogleAdsRequest contains:

  • customer ID
  • query
  • page size

A search response object SearchGoogleAdsResponse contains:

  • GoogleAdsRow objects as result
  • the total request count (ignore LIMIT)
  • the next page token
  • a field mask which defined by the query SELECT


  • page_size default to 1,000, between 1 and 10,000
  • for faster overall performance, you should use a larger page_size due to fewer round trips in your responses


  • search result are implicitly segmented by each instance of main resource

Resource Metadata

use GoogleAdsFieldService to dynamically request what’s available in the GoogleAdsService.Search interface:

  • resource’s catalog, GoogleAdsFieldCategoryEnum
  • resource’s data type, GoogleAdsFieldDataTypeEnum
  • resource’s fields
  • segmentation keys
  • metrics


Optimizing requests

If your app doesn’t share credentials across servers, processes, and threads, it may be sending an excessive number of requests to Google. This can cause our servers to enforce rate limits on your app, resulting in performance degradation.

Multithreaded apps

the credential should be shared between threads. Refreshing of the credential should be performed synchronously to avoid a race condition.

Multiprocess or distributed apps

a shared credential should be used. To ensure multiple processes or servers don’t attempt to refresh the credential at the same time (resulting in excessive refresh requests)

  • a credential refresh job
    • shouldn’t wait until the current credential expires
    • Every 15 minutes is a good starting point.
  • a credential datastore


Criteria Metrics

retrieve metrics (performance data) for different criteria from various reports

criteria report is represented by a resource

metric fields can be exclusively selected for a given resource


Direct segment in SELECT

Google Ads UI only one segment at a time can be used, with the API you can specify multiple segments in the same query
Keep in mind that the amount of rows can increase exponentially for each additional segment field included in your report query

Implicit segment in FROM

Every report is segmented by the resource specified in the FROM clause. For example, when you specify adgroup as the resource in the FROM clause, it will implicitly segment data by the resource name of ad group, even though the adgroup.resource_name field is not included in the query.

Note that for the searchtermview resource, it’s also implicitly segmented by ad group (Technically also implicitly segmented by a campaign. However, an ad group must always belong to a campaign, so using only ad group to de-dupe data rows is acceptable since an ad group is the most basic unit)

segment fields can be exclusively selected for a given resource

Zero Impressions

Zero impressions are always excluded when segmenting a report.

Segmenting a report is done by including any segments field in the search query.

Query Language


  • for retrieving resources / metrics
  • the FROM clause is required
  • return a list of GoogleAdsRow instances

query multiple resources simultaneously since all services return only one resource at a time

each GoogleAdsRow representing one or more seleted resources


  • for retrieving resource’s catalog, compatibility and type
  • the FROM clause should not specified
  • return a list of GoogleAdsField instances

Query Structure

The resource_name field of the main resource is always returned


  1. Automic Endpoint
    • CampaignService.MutateCampaign
    • AdGroupService.MutateAdGroups

    Using a resource’s individual service is the most straightforward way to mutate it, but also the least flexible

    each operation in a mutate is treated independently from all the others, so no cross-referencing is allowed

  2. Bulk Endpoint – GoogleAdsService.MutateWraps a series of individual mutate calls, create entities if and only if every step along the way succeeds
    • atomic transactions across different resource types
    • temporary resource names that can be referenced later on in the same request

      must use a unique negative number

      can only be used after it’s been defined in a resource, the ordering matters

      can not remembered across jobs

      slower API performance if bad operation weaving, e.g. campaign, campaign, ad group, ad group, campaign, ad group, campaign, ad group

    operations within the same request can reference entities from other operations.

    also supports partial failure and validate-only


A set of one ore more ad groups that shared a setting (budget, location target …), typically used to organize product or services

Campaign Types

  • Search Network with Display Select
  • Search Network
  • Display Network
  • Shopping Smart

Not supported: Video Campaigns


Just for helping UI users find relevant campaign options, but there is no corresponding attribute in the API’s perspective

  • Standard
  • All features

Create Campaigns

Recommendation: Set the campaign to PAUSED when creating it to prevent
the ads from immediately serving. Set to ENABLED once you’ve added
targeting and the ads are ready to serve.



Ad customizer is a feed-based solution:

  1. Set up the feed and its attributes
  2. Map the feed to the “Ad Customizer” placeholder type by AdCustomer
  3. Create feed items with the values you want to appear in your ads by FeedItemOperation
  4. Target feed items to a specific campaign, ad group or keyword by FeedItemTarget
  5. Use the feed in an ad by name
  6. Add a countdown
  7. Add an IF function

Common use cases:

  • reuse the ad: updating feed item’s price and end date values instead of creating a new ad

If you don’t have a default value, you must have an ad in each ad group that doesn’t use ad customization parameters

The API validates ads that include references to ad customizers, feed items and ads can both be disapproved separately


  • Target or exclude criteria at the campaign or ad group level.
  • Set absolute bids for specific criteria at the ad group level.
  • Modify bids for criteria at the campaign or ad group level.

# Criteria

  • CampaignCriterionServiceSpecify targeting at campaign level
    • AdScheduleInfo
    • AgeRangeInfo
    • CarrierInfo
    • ContentLabelInfo
    • DeviceInfo
  • AdGroupCriterionServiceSpecify targeting at ad group level

Bid modifiers

Adjust bids for a specific criterion without changing the target campaign or ad group.

Location Targeting

Serving ads to users in a particular geographical region

  • country, state, city, or a postal region
  • proximity to a location

Each targetable location is uniquely identified by a Criterion ID


  • Billing setup: link a Ads account to a Payment account
  • Account Budget: account-level budget, by submit multiple account budget proposals

Shopping Ads

An ad type features better detailed product informations

Can refer to

  • Product Shopping ads: feature one product
  • Showcase Shopping ads: feature serveral related products
  • Smart Shopping ads: combine the standard Shopping and display remarketing ads for better promotion


  1. Submit product data to Google Merchant Center by
    • Feed: upload multiple products at once
    • Content API: upload products individually
  2. Link accounts
  3. Create Campaign
  4. Create Ad Group
  5. Create Ad
  6. Create Listing Groups
  7. Reporting

A feed is a file made up of a list of products which use groupings of attributes that define each one of your products in a unique way

Limitations with beta version of Ads API, can only be done by UI or Adwards API:

  • Showcase Shopping ads CRUD
  • Grouping products by bidding category
  • Downloading certain performance data in Shopping Performance Report and Product Partition Report

Shopping Campaign

Allow users to see Ads that show an image of the product including title, price, store name and more.

you will need to set its budget, bidding strategy and the shopping settings

There are two types of shopping campaigns:


  • required to create Product Shopping ads
  • allow you to include product infos inside your ads,
  • without creating unique ads for each product

Bit strategies:

  • Portfolio bit stategy: enhance_cpc, target_spend, target_roas
  • Campaign bit stategy: manual_cpc, target_spend, target_roas


  • required to configure Smart Shopping ads
  • combines standard Shopping and display remarketing campaigns
  • automated bidding
  • automated ad placement

Bit strategies:

  • Campaign bit stategy: maximize_conversion_value

Portfolio bid strategies created using the BiddingStrategyService are not supported by Smart Shopping Campaigns

Ad Group

Standard Shopping Campaign

  • can contain multiple ad groups(SHOPPING_PRODUCT_ADS), each containing at least one ad

Smart Shopping Campaign

  • can only contain a single ad group(SHOPPING_SMART_ADS) and a single ad

Standard Shopping Campaign

  1. create a Ad object
  2. create a ShoppingProductAdInfo, set shopping_product_ad to the ad object
  3. create a AdGroupAd, set ad to the ad object

Smart Shopping Campaign

  1. create a Ad object
  2. create a ShoppingSmartAdInfo, set shopping_smart_ad to the ad object
  3. create a AdGroupAd, set ad to the ad object

Shopping Listing Groups

  • Partition products into groups (referred to as product groups in the UI)

In Shopping campaigns, listing groups are not used to set bids but rather to include a set of products or to exclude them

Tree like sturcture:

  • Each node in the tree is a ListingGroupInfo, which contains the ListingGroupType that can be subdivision or unit
  • A subdivision introduces a new level in the tree
  • Units are leaves of the tree
  • Each subdivision must be completely partitioned, so it must contain a other subdivision node

Setting cpc_bid_micros is applicable to standard Shopping campaigns. Bidding per listing group is not supported for Smart Shopping campaigns.