# Регионы

Справочные данные регионов ISO 3166-2 (штаты/провинции) для форм аэропортов и валидации: получение списка и поиск по коду.



Административно-территориальные единицы [ISO 3166-2](https://www.iso.org/iso-3166-2-codes.html) (штаты, провинции, территории). Основной сценарий интеграции — преобразование `iso_region` из раздела [Аэропорты](/docs/v31/airports) в понятную человеку подпись, например `US-NY` → `New York`. Две операции: получение списка регионов (с фильтром по стране или континенту) и получение одного региона по коду.

**Используйте фильтры, когда это возможно.** Список без фильтров возвращает около 3900 строк по всему миру. В интерфейсах в продакшне передавайте `country` или `continent`.

| Эндпоинт              | Когда использовать                                     |
| --------------------- | ------------------------------------------------------ |
| `GET /regions`        | Селекторы регионов с фильтром по стране или континенту |
| `GET /regions/{code}` | Преобразование `iso_region` из записи аэропорта        |

<DocJumpNav>
  <DocJumpLink href="#list-regions" icon="solar:list-bold-duotone">
    Список
  </DocJumpLink>

  <DocJumpLink href="#get-region-by-code" icon="solar:map-point-bold-duotone">
    По коду
  </DocJumpLink>
</DocJumpNav>

## Список регионов [#list-regions]

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

### Запрос [#request]

<DocRequirements>
  <DocRequirementAuth />
</DocRequirements>

<DocApiPath method="GET" path="/regions" />

| Параметр    | Тип    | Обязательный | По умолчанию   | Описание                                                  |
| ----------- | ------ | ------------ | -------------- | --------------------------------------------------------- |
| `country`   | string | Нет          | все страны     | Код страны ISO 3166-1 alpha-2, например `US`              |
| `continent` | string | Нет          | все континенты | Код континента (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`) |

### Ответ [#response]

```json
{
  "regions": [
    {
      "id": 306110,
      "code": "US-NY",
      "local_code": "NY",
      "name": "New York",
      "continent": null,
      "iso_country": "US",
      "wikipedia_link": "https://en.wikipedia.org/wiki/New_York",
      "keywords": "Airports in New York"
    }
  ],
  "total": 1
}
```

| Поле      | Тип     | Обязательный | Может быть null? | Описание                         |
| --------- | ------- | ------------ | ---------------- | -------------------------------- |
| `regions` | array   | **Да**       | Никогда          | Подходящие записи регионов       |
| `total`   | integer | **Да**       | Никогда          | Количество возвращённых регионов |

#### Элемент региона (`regions[]`) [#region-item-regions]

| Поле             | Тип            | Обязательный | Может быть null? | Описание                                            |
| ---------------- | -------------- | ------------ | ---------------- | --------------------------------------------------- |
| `id`             | integer        | **Да**       | Никогда          | Числовой идентификатор записи                       |
| `code`           | string         | **Да**       | Никогда          | Код региона ISO 3166-2, например `US-NY`            |
| `local_code`     | string \| null | Нет          | **Да**           | Короткий местный код внутри страны (например, `NY`) |
| `name`           | string         | **Да**       | Никогда          | Название региона                                    |
| `continent`      | string \| null | Нет          | **Да**           | Код континента, если назначен                       |
| `iso_country`    | string         | **Да**       | Никогда          | Код alpha-2 родительской страны                     |
| `wikipedia_link` | string \| null | Нет          | **Да**           | Справочный URL                                      |
| `keywords`       | string \| null | Нет          | **Да**           | Произвольные текстовые теги                         |

## Получение региона по коду [#get-region-by-code]

Получение одного региона по коду [ISO 3166-2](https://www.iso.org/iso-3166-2-codes.html) (например, `US-CA`, `GB-ENG`). Если код не найден, возвращается `404`.

### Запрос [#request-1]

<DocApiPath method="GET" path="/regions/{code}" />

| Параметр | Тип    | Обязательный | Описание                               |
| -------- | ------ | ------------ | -------------------------------------- |
| `code`   | string | Да           | Код региона ISO 3166-2 (параметр пути) |

### Ответ [#response-1]

```json
{
  "id": 306110,
  "code": "US-NY",
  "local_code": "NY",
  "name": "New York",
  "continent": null,
  "iso_country": "US",
  "wikipedia_link": "https://en.wikipedia.org/wiki/New_York",
  "keywords": "Airports in New York"
}
```

Та же структура объекта, что и у элементов списка. Если фильтры списка ничего не нашли, возвращаются `regions: []` и `total: 0` — это не ошибка.

## Клиентские типы [#client-types]

<DocClientTypes id="v31/regions/reference-types" />

## Интеграция [#integration]

Получите справочные данные регионов для выбранной страны и преобразуйте их в варианты выбора для формы.

В примере ниже списки регионов кэшируются на 24 часа, а явные тайм-ауты помогают сохранить отзывчивость форм онбординга.

<DocExample id="v31/regions/list-fetch" />

### Примечания по реализации [#implementation-notes]

**Сначала страна.** По возможности запрашивайте данные по `country` — не отправляйте в браузер полный глобальный список.

**Связь с аэропортами.** Связывайте `airport.iso_region` из раздела [Аэропорты](/docs/v31/airports) напрямую с `regions.code`.

**Формат кода.** Где это практично, проверяйте формат вида `XX-YYY` до отправки запроса, чтобы избежать лишних ответов 404.

## Ответы с ошибками [#error-responses]

Общие ошибки: [Обработка ошибок](/docs/errors). Ошибки, специфичные для эндпоинта:

### 404 - регион не найден [#404---region-not-found]

```json
{
  "detail": "Region 'ZZ-XX' not found"
}
```

<APIPage document="&#x22;https://api.skylinkapi.com/v3.1/openapi.json&#x22;" operations="[{&#x22;path&#x22;:&#x22;/regions&#x22;,&#x22;method&#x22;:&#x22;get&#x22;},{&#x22;path&#x22;:&#x22;/regions/{code}&#x22;,&#x22;method&#x22;:&#x22;get&#x22;}]" />

***

См. также: [Страны](/docs/v31/countries) · [Аэропорты](/docs/v31/airports) · [Поиск аэропортов](/docs/v31/airport-search)