Google Ads API (v18) — Overview¶

The Google Ads API sandbox exposes the reporting surface of the Google Ads REST API, version v18, for the YouTube video action campaigns run by the game studio Nova Play. Nova Play promotes 10 mobile games; each game is advertised from its own Google Ads customer account, and all 10 accounts sit under one manager account (9990001111).

Use this API to pull daily ad performance (impressions, clicks, cost, installs, purchase value) at the customer, campaign, ad group or ad level, optionally split by date and by country.


Base URL	`https://googleads.huydata.com/v18`
Protocol	HTTPS, JSON request and response bodies
Query language	GAQL (Google Ads Query Language) — see GAQL
Authentication	OAuth 2.0 access token + developer token + manager customer id — see Authentication
Rate limit	60 requests per minute per access token — see Errors & quotas
Currency	USD. Money is expressed in micros (1 USD = 1,000,000 micros)
Time zone	UTC for every account
Data availability	A report date is available from 00:10 UTC the following day; conversions mature for 3 days — see Reporting

Endpoints¶

All endpoints live under /v18.

Method	Path	Purpose
`GET`	`/customers:listAccessibleCustomers`	List the customer accounts your credentials can query
`POST`	`/customers/{customerId}/googleAds:searchStream`	Run a GAQL query and receive every result in batches of up to 1,000
`POST`	`/customers/{customerId}/googleAds:search`	Run a GAQL query and receive one page (`pageSize`, `pageToken`)

{customerId} is a 10-digit customer id, with or without dashes (5423891542 and 542-389-1542 are equivalent).

Documentation map¶

Page	What you will find
Authentication	The three required headers, how each one is validated, and the error you get when one is missing or wrong
Accounts	The manager account, the 10 game accounts, the campaign / ad group / ad hierarchy and the naming conventions
GAQL	The query grammar: `SELECT`, `FROM`, `WHERE`, `ORDER BY`, `LIMIT`, operators and named date ranges
Fields reference	Every selectable attribute, metric and segment, with type and an example value
Reporting	`searchStream` vs `search`, paging, the result JSON shape, data freshness and the attribution window
Geo targets	How `segments.geo_target_country` maps to a country, and the full list of 14 geo target constants
Errors & quotas	The `google.rpc.Status` error envelope, every error code, HTTP 429 and `Retry-After`

Quickstart¶

1. Set your credentials¶

Your instructor gives you an OAuth access token and a developer token. Export them as environment variables so they never end up in your code:

export GOOGLE_ACCESS_TOKEN="ya29.…"       # OAuth 2.0 access token
export GOOGLE_DEVELOPER_TOKEN="…"         # developer token

2. Find the customer accounts you can query¶

curl -s "https://googleads.huydata.com/v18/customers:listAccessibleCustomers" \
  -H "Authorization: Bearer $GOOGLE_ACCESS_TOKEN" \
  -H "developer-token: $GOOGLE_DEVELOPER_TOKEN" \
  -H "login-customer-id: 9990001111"

{
  "resourceNames": [
    "customers/5423891542",
    "customers/8340496580",
    "customers/2375371730",
    "..."
  ]
}

The customer id is the part after customers/.

3. Pull yesterday's performance per campaign¶

curl -s -X POST "https://googleads.huydata.com/v18/customers/5423891542/googleAds:searchStream" \
  -H "Authorization: Bearer $GOOGLE_ACCESS_TOKEN" \
  -H "developer-token: $GOOGLE_DEVELOPER_TOKEN" \
  -H "login-customer-id: 9990001111" \
  -H "Content-Type: application/json" \
  -d '{"query": "SELECT segments.date, campaign.id, campaign.name, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, metrics.conversions_value FROM campaign WHERE segments.date DURING YESTERDAY"}'

[
  {
    "results": [
      {
        "segments": { "date": "2026-10-29" },
        "campaign": { "id": "22245080429", "name": "DMS_GG_AND_SEA_VALUE_202512" },
        "metrics": {
          "impressions": "199821",
          "clicks": "1733",
          "costMicros": "342840000",
          "conversions": 251.0,
          "conversionsValue": 117.25
        }
      },
      {
        "segments": { "date": "2026-10-29" },
        "campaign": { "id": "26359584284", "name": "DMS_GG_AND_EA_INSTALL_202610" },
        "metrics": {
          "impressions": "89490",
          "clicks": "1056",
          "costMicros": "788600000",
          "conversions": 113.0,
          "conversionsValue": 230.27
        }
      },
      "..."
    ],
    "fieldMask": "segments.date,campaign.id,campaign.name,metrics.impressions,metrics.clicks,metrics.costMicros,metrics.conversions,metrics.conversionsValue",
    "requestId": "25e10e3b420c403cb771"
  }
]

Things to notice in this response, all explained in Reporting:

searchStream returns a JSON array of batches; each batch has results, fieldMask and requestId.
Field names in results are camelCase and nested (metrics.cost_micros becomes metrics.costMicros).
int64 values (id, impressions, clicks, costMicros) are strings; double values (conversions, conversionsValue) are numbers.
costMicros is USD × 1,000,000 — 342840000 means $342.84.
conversions counts app installs; conversionsValue is the attributed purchase value in USD.

4. Go further¶

Add segments.geo_target_country to split by country — Geo targets.
Query FROM ad_group_ad to get creative-level rows — Fields reference.
Replace DURING YESTERDAY with BETWEEN '2026-10-01' AND '2026-10-29' for a backfill — GAQL.
Re-pull the last 3 report dates every day, because conversions keep maturing — Reporting.

Conventions used in this documentation¶

$GOOGLE_ACCESS_TOKEN and $GOOGLE_DEVELOPER_TOKEN stand for your own credentials.
9990001111 is the Nova Play manager account and is always used as login-customer-id.
Example responses are real responses from the sandbox, trimmed to 2–3 results with "...". Ids and numbers in your own responses will be identical for attributes, and will differ for metrics depending on the day you query.