> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catproxy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Geo Reference

> Look up countries, states, cities, and ZIP codes to use as targeting parameters when creating proxies. Required scope: geo:read.

<Info>
  See the [Swagger UI](https://api.catproxy.io/swagger/index.html) for live request/response schemas and to try endpoints directly in your browser.
</Info>

The geo endpoints return the IDs and codes you need to set geo-targeting on your proxies. The typical lookup flow is:

1. **Countries** - get a country `id` (integer) and `code` (string)
2. **States** - use `code` to get states for that country
3. **Cities** - filter by country and optionally state
4. **ZIP codes** - filter by country and city

Pass country `id` values in the `countries` array when creating or updating a proxy. Use `code` and `extract_parameter` values in proxy username parameters for connection-level geo-targeting.

***

## Get countries

Returns all available countries with their numeric IDs and ISO codes.

```http theme={null}
GET /v1/geo/countries
```

**Query parameters**

| Parameter | Type   | Required | Description                            |
| :-------- | :----- | :------- | :------------------------------------- |
| `search`  | string | No       | Filter by country name (partial match) |

**Scope:** `geo:read`

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.catproxy.io/v1/geo/countries \
    -H "X-API-Key: cat_YOUR_API_KEY"
  ```

  ```bash cURL (with search) theme={null}
  curl "https://api.catproxy.io/v1/geo/countries?search=United" \
    -H "X-API-Key: cat_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  r = requests.get(
      "https://api.catproxy.io/v1/geo/countries",
      headers={"X-API-Key": "cat_YOUR_API_KEY"}
  )
  print(r.json())
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "result": true,
  "data": [
    { "id": 84,  "code": "US", "name": "United States" },
    { "id": 225, "code": "RU", "name": "Russia" },
    { "id": 82,  "code": "GB", "name": "United Kingdom" }
  ]
}
```

***

## Get states

Returns states or regions for a given country.

```http theme={null}
GET /v1/geo/states
```

**Query parameters**

| Parameter      | Type   | Required | Description                 |
| :------------- | :----- | :------- | :-------------------------- |
| `country_code` | string | Yes      | ISO country code, e.g. `US` |
| `search`       | string | No       | Filter by region name       |

**Scope:** `geo:read`

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.catproxy.io/v1/geo/states?country_code=US" \
    -H "X-API-Key: cat_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  r = requests.get(
      "https://api.catproxy.io/v1/geo/states",
      headers={"X-API-Key": "cat_YOUR_API_KEY"},
      params={"country_code": "US"}
  )
  print(r.json())
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "result": true,
  "data": [
    {
      "id": 1,
      "code": 77,
      "name": "California",
      "extract_parameter": "california"
    }
  ]
}
```

***

## Get cities

Returns cities for a given country, optionally filtered by state.

```http theme={null}
GET /v1/geo/cities
```

**Query parameters**

| Parameter      | Type   | Required | Description                                 |
| :------------- | :----- | :------- | :------------------------------------------ |
| `country_code` | string | Yes      | ISO country code, e.g. `US`                 |
| `region`       | string | No       | Region name to filter by, e.g. `California` |
| `search`       | string | No       | Filter by city name                         |

**Scope:** `geo:read`

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.catproxy.io/v1/geo/cities?country_code=US&region=California" \
    -H "X-API-Key: cat_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  r = requests.get(
      "https://api.catproxy.io/v1/geo/cities",
      headers={"X-API-Key": "cat_YOUR_API_KEY"},
      params={"country_code": "US", "region": "California"}
  )
  print(r.json())
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "result": true,
  "data": [
    {
      "id": 32706,
      "name": "Los Angeles",
      "extract_parameter": "losangeles",
      "country_id": 84,
      "region_code": 443
    }
  ]
}
```

***

## Get ZIP codes

Returns ZIP codes for a city within a country.

```http theme={null}
GET /v1/geo/zip
```

**Query parameters**

| Parameter      | Type   | Required | Description                   |
| :------------- | :----- | :------- | :---------------------------- |
| `country_code` | string | Yes      | ISO country code, e.g. `US`   |
| `city`         | string | Yes      | City name, e.g. `Los Angeles` |

**Scope:** `geo:read`

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.catproxy.io/v1/geo/zip?country_code=US&city=Los+Angeles" \
    -H "X-API-Key: cat_YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  r = requests.get(
      "https://api.catproxy.io/v1/geo/zip",
      headers={"X-API-Key": "cat_YOUR_API_KEY"},
      params={"country_code": "US", "city": "Los Angeles"}
  )
  print(r.json())
  ```
</CodeGroup>

**Example response**

```json theme={null}
{
  "result": true,
  "data": [
    { "zip": "90001" },
    { "zip": "90002" },
    { "zip": "90003" }
  ]
}
```