# Страны

Справочные данные о странах для интеграций с аэропортами: список по континенту или запись об отдельной стране по коду.



Справочные данные о странах по [ISO 3166-1 alpha-2](https://www.iso.org/iso-3166-country-codes.html) для форм выбора аэропортов, фильтров по континенту и проверки поля `iso_country` в записях аэропортов. Две операции: получение списка всех стран (с необязательной фильтрацией по континенту) и получение одной страны по коду. Если в списке нет совпадений, возвращается `countries: []` с HTTP `200`.

| Эндпоинт                | Когда использовать                                                               |
| ----------------------- | -------------------------------------------------------------------------------- |
| `GET /countries`        | Заполнение списков выбора страны или фильтрация списков аэропортов по континенту |
| `GET /countries/{code}` | Преобразование одного кода ISO в каноническое название                           |

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

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

## Список стран [#list-countries]

Возвращает все страны с необязательной фильтрацией по коду континента (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`).

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

<DocRequirements>
  <DocRequirementAuth />
</DocRequirements>

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

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

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

```json
{
  "countries": [
    {
      "id": 302755,
      "code": "US",
      "name": "United States",
      "continent": null,
      "wikipedia_link": "https://en.wikipedia.org/wiki/United_States",
      "keywords": "American airports"
    }
  ],
  "total": 1
}
```

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

#### Элемент страны (`countries[]`) [#country-item-countries]

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

## Получение страны по коду [#get-country-by-code]

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

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

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

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

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

```json
{
  "id": 302755,
  "code": "US",
  "name": "United States",
  "continent": null,
  "wikipedia_link": "https://en.wikipedia.org/wiki/United_States",
  "keywords": "American airports"
}
```

Структура объекта та же, что и у элементов списка. `continent`, `wikipedia_link` и `keywords` могут быть `null`.

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

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

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

Сформируйте проверенный список стран для фильтров аэропортов или маршрутов.

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

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

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

**Фильтрация по континенту.** Передавайте `continent`, чтобы уменьшить объём данных в продуктах для конкретных регионов (например, только `NA` и `EU`).

**Нормализация кода.** Переводите пользовательский ввод в верхний регистр перед поиском (`us` → `US`), чтобы избежать ложных ошибок 404.

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

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

### 404 - страна не найдена [#404---country-not-found]

```json
{
  "detail": "Country 'XX' not found"
}
```

### 400 - недопустимый фильтр континента [#400---invalid-continent-filter]

```json
{
  "detail": "Invalid continent 'XX'. Valid values: AF, AN, AS, EU, NA, OC, SA"
}
```

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

***

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