Geo targets¶

Country-level reporting in the Google Ads API works through geo target constants. When you add segments.geo_target_country to a query, each row carries a resource name such as geoTargetConstants/2840 instead of a country name or ISO code. The geo_target_constant resource is the lookup table that turns that id into a country.

Getting country-level metrics¶

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, segments.geo_target_country, campaign.id, metrics.impressions, metrics.cost_micros, metrics.conversions FROM campaign WHERE segments.date = '\''2026-10-25'\'' AND campaign.id = 26359584284 ORDER BY metrics.cost_micros DESC"}'

[
  {
    "results": [
      {
        "segments": { "date": "2026-10-25", "geoTargetCountry": "geoTargetConstants/2392" },
        "campaign": { "id": "26359584284" },
        "metrics": { "impressions": "47497", "costMicros": "510240000", "conversions": 51.0 }
      },
      {
        "segments": { "date": "2026-10-25", "geoTargetCountry": "geoTargetConstants/2410" },
        "campaign": { "id": "26359584284" },
        "metrics": { "impressions": "36633", "costMicros": "323170000", "conversions": 52.0 }
      },
      {
        "segments": { "date": "2026-10-25", "geoTargetCountry": "geoTargetConstants/2158" },
        "campaign": { "id": "26359584284" },
        "metrics": { "impressions": "33583", "costMicros": "282500000", "conversions": 48.0 }
      }
    ],
    "fieldMask": "segments.date,segments.geoTargetCountry,campaign.id,metrics.impressions,metrics.costMicros,metrics.conversions",
    "requestId": "39d274ec78d140a1b968"
  }
]

Campaign DMS_GG_AND_EA_INSTALL_202610 targets the EA group, so its rows are split across Japan (2392), South Korea (2410) and Taiwan (2158). A campaign only produces rows for the countries its ad groups actually served; there are never rows with zero activity.

Resolving the id: the geo_target_constant resource¶

Query FROM geo_target_constant once and cache the result; it is static. The customer id in the URL can be any accessible customer — the table is the same for all.

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 geo_target_constant.id, geo_target_constant.name, geo_target_constant.country_code, geo_target_constant.target_type, geo_target_constant.status, geo_target_constant.canonical_name, geo_target_constant.resource_name FROM geo_target_constant"}'

[
  {
    "results": [
      {
        "geoTargetConstant": {
          "id": "2036",
          "name": "Australia",
          "countryCode": "AU",
          "targetType": "Country",
          "status": "ENABLED",
          "canonicalName": "Australia",
          "resourceName": "geoTargetConstants/2036"
        }
      },
      {
        "geoTargetConstant": {
          "id": "2076",
          "name": "Brazil",
          "countryCode": "BR",
          "targetType": "Country",
          "status": "ENABLED",
          "canonicalName": "Brazil",
          "resourceName": "geoTargetConstants/2076"
        }
      },
      "..."
    ],
    "fieldMask": "geoTargetConstant.id,geoTargetConstant.name,geoTargetConstant.countryCode,geoTargetConstant.targetType,geoTargetConstant.status,geoTargetConstant.canonicalName,geoTargetConstant.resourceName",
    "requestId": "b1d0a9e9e01b4e1f8097"
  }
]

To join, take the number after geoTargetConstants/ in segments.geoTargetCountry and match it to geoTargetConstant.id, or compare the full string to geoTargetConstant.resourceName.

Complete mapping¶

Nova Play advertises in 14 countries. These are the only values segments.geo_target_country can take and the only rows geo_target_constant returns (sorted by id, as the API returns them).

`geo_target_constant.id`	`resource_name`	`country_code`	`name` / `canonical_name`	Country group
`2036`	`geoTargetConstants/2036`	`AU`	Australia	T1
`2076`	`geoTargetConstants/2076`	`BR`	Brazil	LATAM
`2124`	`geoTargetConstants/2124`	`CA`	Canada	T1
`2158`	`geoTargetConstants/2158`	`TW`	Taiwan	EA
`2276`	`geoTargetConstants/2276`	`DE`	Germany	T1
`2360`	`geoTargetConstants/2360`	`ID`	Indonesia	SEA
`2392`	`geoTargetConstants/2392`	`JP`	Japan	EA
`2410`	`geoTargetConstants/2410`	`KR`	South Korea	EA
`2484`	`geoTargetConstants/2484`	`MX`	Mexico	LATAM
`2608`	`geoTargetConstants/2608`	`PH`	Philippines	SEA
`2704`	`geoTargetConstants/2704`	`VN`	Vietnam	SEA
`2764`	`geoTargetConstants/2764`	`TH`	Thailand	SEA
`2826`	`geoTargetConstants/2826`	`GB`	United Kingdom	T1
`2840`	`geoTargetConstants/2840`	`US`	United States	T1

target_type is Country and status is ENABLED for every row.

Country groups¶

Campaign names carry a GEO token that names the group of countries the campaign targets (see Accounts › Naming conventions). Each ad group inside the campaign targets 2–5 countries from that group, listed at the end of the ad group name.

Group	Countries
`T1`	US, GB, CA, AU, DE
`SEA`	VN, ID, PH, TH
`LATAM`	BR, MX
`EA`	JP, KR, TW

Filtering by country¶

segments.geo_target_country accepts =, !=, IN and NOT IN in WHERE, with full resource names as values. Any other operator returns OPERATOR_FIELD_MISMATCH. Values that do not match one of the 14 constants (for example an ISO code like 'US') match no traffic and silently return zero rows, so always use the geoTargetConstants/<id> form.

SELECT segments.date, segments.geo_target_country, metrics.cost_micros
FROM customer
WHERE segments.date = '2026-10-25'
  AND segments.geo_target_country IN ('geoTargetConstants/2392', 'geoTargetConstants/2410')

[
  {
    "results": [
      { "segments": { "date": "2026-10-25", "geoTargetCountry": "geoTargetConstants/2392" }, "metrics": { "costMicros": "510240000" } },
      { "segments": { "date": "2026-10-25", "geoTargetCountry": "geoTargetConstants/2410" }, "metrics": { "costMicros": "323170000" } }
    ],
    "fieldMask": "segments.date,segments.geoTargetCountry,metrics.costMicros",
    "requestId": "2d32d79018ee410cbe3a"
  }
]

The filter also works without selecting the segment, in which case the metrics are the total for the chosen countries only.