# 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 | yes | — | 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 | no | 10 | Optional, default 10. 1-100. |

## Request

```http
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.

```json
{
  "id": "loca_2r4zqaezkipniebame5llpj7",
  "request_id": "req_i5spehs4njaezhmkdlm5bjsvwe",
  "object": "location_list",
  "created_at": "2026-08-09T08:33:19Z",
  "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. |