docs / endpoint

GET /v1/locations

Look up Google Ads geotarget IDs by name — country, state/region, city, or neighborhood.

Credits: Free -- uncharged and unmetered. Timeout: 10s

Parameters

Name	Type	Required	Default	Description
`q`	string	required	—	Name to search for. Required, min 2 chars. Common names match many places worldwide -- narrow multi-match names with a region or country word, e.g. "austin texas" instead of just "austin".
`limit`	integer	optional	`10`	Optional, default 10. 1-100.

Request

→ requestGET /v1/locations

GET /v1/locations?q=austin+texas HTTP/1.1
Authorization: Bearer sof_live_your_key_here

Response

Wrapped in the standard envelope -- id, object, created_at, elapsed_ms, cache, credits -- documented once on The Contract. The body below is a real envelope with this endpoint's data shape; values vary per request, and a … marks an array cut short for display.

← response200

{
  "id": "loca_6demj3npa52efjg6xr4qvkyk",
  "request_id": "req_loohnlonobbf7mobehoijbawma",
  "object": "location_list",
  "created_at": "2026-08-09T07:22:54Z",
  "elapsed_ms": 180,
  "cache": "miss",
  "credits": {
    "charged": 0,
    "balance": 9857
  },
  "data": {
    "locations": [
      {
        "id": 1026201,
        "name": "Austin,Texas,United States",
        "type": "city",
        "country": "US",
        "parent_id": 21176
      },
      {
        "id": 9198393,
        "name": "Central Austin,Texas,United States",
        "type": "neighborhood",
        "country": "US",
        "parent_id": 21176
      },
      {
        "id": 9060225,
        "name": "Downtown Austin,Texas,United States",
        "type": "neighborhood",
        "country": "US",
        "parent_id": 21176
      },
      {
        "id": 9198961,
        "name": "East Austin,Texas,United States",
        "type": "neighborhood",
        "country": "US",
        "parent_id": 21176
      },
      {
        "id": 9194496,
        "name": "Old West Austin,Texas,United States",
        "type": "neighborhood",
        "country": "US",
        "parent_id": 21176
      },
      {
        "id": 9197266,
        "name": "South Austin,Texas,United States",
        "type": "neighborhood",
        "country": "US",
        "parent_id": 21176
      }
    ]
  }
}

Response fields

What each field in data (above) means.

Field	Description
`data.locations`	Matching geotargets, ranked by relevance (exact match, then prefix, then substring), up to limit.
`data.locations[].id`	Google Ads geotarget ID -- pass this as the location param on any other endpoint.
`data.locations[].name`	Canonical name, comma-separated from most to least specific, e.g. "Austin,Texas,United States".
`data.locations[].type`	Geotarget type, e.g. "country", "state", "region", "city", "neighborhood".
`data.locations[].country`	ISO country code this geotarget belongs to.
`data.locations[].parent_id`	Geotarget ID of the immediate parent (e.g. a city's state), or null for a top-level geotarget.