Skip to content

Google Ads API Beta(v2.1) Short Notes

Google Ads API


  • 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 service

    GoogleAdsService (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

Request Quota

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.Mutate

    Wraps 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