google_ads_get_geo_performance

Get Google Ads Geographic Performance

Google

Description

Get geographic performance data from the geographic_view resource. Only ONE geo level per query. Returns both AREA_OF_INTEREST and LOCATION_OF_PRESENCE location types with auto-resolved location names. Includes a conversion action breakdown for the accounts, campaigns or ad groups in the returned rows. Location names are resolved automatically from criterion IDs. Paginated: \

Read-onlyIdempotentOpen-world

Usage

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "google_ads_get_geo_performance",
    "arguments": {
      "customer_id": "1234567890",
      "date_preset": "LAST_7_DAYS",
      "geo_level": "country",
      "reason": "Compare spend by country"
    }
  }
}

Parameters

NameTypeRequiredDescription
customer_id string Required The Google Ads Customer ID (10 digits, with or without dashes)maxLength: 20, pattern: ^[\d-]+$
reason string Required Why this tool call is neededminLength: 1, maxLength: 500
Optional parameters (12)
NameTypeRequiredDescription
login_customer_id string Optional MCC (Manager) Customer ID; required for managed accountsmaxLength: 20, pattern: ^[\d-]+$
date_preset string Optional Predefined date range: TODAY, YESTERDAY, LAST_7_DAYS, LAST_30_DAYS, THIS_MONTH, LAST_MONTH. LAST_7_DAYS / LAST_30_DAYS are the 7 / 30 complete days ending yesterday (account time zone), as in Google Ads; THIS_MONTH runs through today.
TODAY YESTERDAY LAST_7_DAYS LAST_30_DAYS THIS_MONTH LAST_MONTH
date_range object Optional Custom date range {start_date, end_date} in YYYY-MM-DD
geo_level string Optional Geographic granularity. "country" uses geographic_view.country_criterion_id; others add a segments.geo_target_* drill-down. Only one geo level per query.
country geo_target_city geo_target_region geo_target_state geo_target_metro geo_target_province geo_target_county geo_target_district geo_target_most_specific_location geo_target_postal_code geo_target_airport geo_target_canton
level string Optional Entity breakdown level
ACCOUNT CAMPAIGN AD_GROUP
segments array Optional Additional non-geo segments: date, device, ad_network_type. Rows are totals over the date window unless "date" is included, which returns one row per day. conversion_breakdown is always window totals per entity.
campaign_id string Optional Filter to a specific campaign IDmaxLength: 20, pattern: ^\d+$
ad_group_id string Optional Filter to a specific ad group IDmaxLength: 20, pattern: ^\d+$
limit integer Optional Page size: rows per page (1-1000, default 25). The response `count` is the total across all pages — a city-level report runs to tens of thousands of rows. To get more rows, pass `nextCursor` back as `cursor` rather than raising `limit`: pages much larger than the default can exceed what an MCP client accepts.min: 1, max: 1000
cursor string Optional Opaque pagination cursor: pass the `nextCursor` value from the previous response unchanged, with every other parameter the same, to fetch the next page. Omit for the first page. Never construct one. Each page carries the conversion breakdown only of the campaigns or ad groups it introduces, so a full crawl adds up rather than double-counting. Pages are positions in a ranking by spend that is re-read live on every call, and Google revises conversions for past days for some time afterwards, so a row near a page boundary can still move between pages — a crawl is a good sample of a large report, not a guaranteed exact snapshot of one.
include_all_conversions boolean Optional When true, includes an additional all-conversions breakdown (metrics.all_conversions, all_conversions_value, value_per_all_conversions) segmented by conversion_action_name. This captures ALL conversion actions including those not marked "Include in Conversions".
connection_id string Optional Optional ID of a specific connection to use for this call. Omit to use the actor's default connection for this network. Call <platform>_list_connections to discover available connection IDs.

Examples

Country performance

{
  "customer_id": "1234567890",
  "date_preset": "LAST_7_DAYS",
  "geo_level": "country",
  "reason": "Compare spend by country"
}

hopkin google geo-performance get --customer-id 1234567890 --date-preset LAST_7_DAYS --geo-level country

City-level breakdown

{
  "customer_id": "1234567890",
  "date_preset": "LAST_30_DAYS",
  "geo_level": "geo_target_city",
  "level": "CAMPAIGN",
  "reason": "City performance analysis"
}

hopkin google geo-performance get --customer-id 1234567890 --date-preset LAST_30_DAYS --geo-level geo_target_city --level CAMPAIGN

Country by campaign

{
  "customer_id": "1234567890",
  "date_preset": "LAST_7_DAYS",
  "geo_level": "country",
  "level": "CAMPAIGN",
  "segments": [
    "date"
  ],
  "reason": "Daily country trends per campaign"
}

hopkin google geo-performance get --customer-id 1234567890 --date-preset LAST_7_DAYS --geo-level country --level CAMPAIGN --segments date

Next page of a city report

{
  "customer_id": "1234567890",
  "date_preset": "LAST_30_DAYS",
  "geo_level": "geo_target_city",
  "level": "CAMPAIGN",
  "cursor": "<nextCursor from the previous response>",
  "reason": "Walk every city in the account"
}

hopkin google geo-performance get --customer-id 1234567890 --date-preset LAST_30_DAYS --geo-level geo_target_city --level CAMPAIGN --cursor <nextCursor from the previous response>