> ## 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.

# Геосправочник

> Поиск стран, регионов, городов и ZIP-кодов для использования в параметрах таргетинга при создании прокси. Необходимое разрешение: geo:read.

<Info>
  Полные схемы запросов и ответов, а также возможность тестирования эндпоинтов доступны в [Swagger UI](https://api.catproxy.io/swagger/index.html).
</Info>

Гео-эндпоинты возвращают ID и коды, необходимые для настройки геотаргетинга прокси. Стандартный порядок поиска:

1. **Страны** - получить `id` страны (integer) и `code` (string)
2. **Регионы** - использовать `code` для получения регионов страны
3. **Города** - фильтровать по стране и опционально по региону
4. **ZIP-коды** - фильтровать по стране и городу

Передавайте значения `id` стран в массиве `countries` при создании или обновлении прокси. Значения `code` и `extract_parameter` используйте в параметрах имени пользователя прокси для таргетинга на уровне подключения.

***

## Получить страны

Возвращает все доступные страны с числовыми ID и кодами ISO.

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

**Параметры запроса**

| Параметр | Тип    | Обязательный | Описание                                         |
| :------- | :----- | :----------- | :----------------------------------------------- |
| `search` | string | Нет          | Фильтр по названию страны (частичное совпадение) |

**Разрешение:** `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 (с поиском) 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>

**Пример ответа**

```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" }
  ]
}
```

***

## Получить регионы

Возвращает штаты или регионы для указанной страны.

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

**Параметры запроса**

| Параметр       | Тип    | Обязательный | Описание                      |
| :------------- | :----- | :----------- | :---------------------------- |
| `country_code` | string | Да           | Код страны ISO, например `US` |
| `search`       | string | Нет          | Фильтр по названию региона    |

**Разрешение:** `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>

**Пример ответа**

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

***

## Получить города

Возвращает города для указанной страны с возможностью фильтрации по региону.

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

**Параметры запроса**

| Параметр       | Тип    | Обязательный | Описание                                               |
| :------------- | :----- | :----------- | :----------------------------------------------------- |
| `country_code` | string | Да           | Код страны ISO, например `US`                          |
| `region`       | string | Нет          | Название региона для фильтрации, например `California` |
| `search`       | string | Нет          | Фильтр по названию города                              |

**Разрешение:** `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>

**Пример ответа**

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

***

## Получить ZIP-коды

Возвращает ZIP-коды для города в указанной стране.

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

**Параметры запроса**

| Параметр       | Тип    | Обязательный | Описание                                |
| :------------- | :----- | :----------- | :-------------------------------------- |
| `country_code` | string | Да           | Код страны ISO, например `US`           |
| `city`         | string | Да           | Название города, например `Los Angeles` |

**Разрешение:** `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>

**Пример ответа**

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