# Поиск аэропортов Поиск аэропортов по тексту, координатам или IP — ранжированные результаты для автодополнения и функций поиска ближайшего аэропорта. Три режима поиска помогают пользователям найти аэропорт до того, как вы запросите полные записи через [Аэропорты](/docs/v31/airports): поиск с подсказками по названию или коду, ближайшие аэропорты к метке на карте или GPS-координатам и ближайшие аэропорты, определённые по IP посетителя. Все три режима возвращают одну и ту же базовую схему элемента аэропорта; режимы по местоположению и по IP добавляют `distance_km`. | Эндпоинт | Когда использовать | | ------------------------------- | ------------------------------------------------------------------- | | `GET /airports/search/text` | Автодополнение — пользователь вводит название, город или часть кода | | `GET /airports/search/location` | Метка на карте или GPS-координаты — аэропорты в пределах радиуса | | `GET /airports/search/ip` | «Аэропорты рядом со мной» без разрешения на геолокацию в браузере | Текст Местоположение IP ## Поиск по тексту [#search-by-text] Полнотекстовый поиск по кодам ICAO, кодам IATA, названиям аэропортов и городам. Результаты ранжируются по `relevance_score` — точные совпадения кода получают наивысшую оценку. ### Запрос [#request] | Параметр | Тип | Обязательный | По умолчанию | Описание | | -------- | ------- | ------------ | ------------ | ------------------------------------------- | | `q` | string | Да | - | Строка поиска — минимум **2** символа | | `limit` | integer | Нет | `10` | Максимальное число возвращаемых результатов | ### Ответ [#response] ```json { "query": "jfk", "airports": [ { "id": 3622, "ident": "KJFK", "type": "large_airport", "name": "John F. Kennedy International Airport", "latitude_deg": 40.639447, "longitude_deg": -73.779317, "municipality": "New York", "iso_country": "US", "iata_code": "JFK", "relevance_score": 100 } ], "airports_found": 1 } ``` | Поле | Тип | Обязательный | Описание | | ---------------- | ------- | ------------ | -------------------------------------------- | | `query` | string | **Да** | Повтор строки поиска | | `airports` | array | **Да** | Ранжированные совпадения (может быть пустым) | | `airports_found` | integer | **Да** | Количество элементов в `airports` | #### Элемент аэропорта (`airports[]`) [#airport-item-airports] | Поле | Тип | Обязательный | Может быть null? | Описание | | ----------------- | -------------- | ------------ | ---------------- | --------------------------------------------------------------------------------------------- | | `ident` | string | **Да** | Никогда | Основной идентификатор (обычно ICAO) | | `name` | string | **Да** | Никогда | Название аэропорта | | `type` | string | **Да** | Никогда | Класс аэропорта (те же значения, что и в [Аэропорты](/docs/v31/airports#airport-type-values)) | | `latitude_deg` | number | **Да** | Никогда | Широта WGS-84 | | `longitude_deg` | number | **Да** | Никогда | Долгота WGS-84 | | `municipality` | string \| null | Нет | **Да** | Обслуживаемый город | | `iso_country` | string \| null | Нет | **Да** | Код страны ISO | | `iata_code` | string \| null | Нет | **Да** | Код IATA, если присвоен | | `relevance_score` | integer | **Да** | Никогда | Чем выше, тем лучше совпадение (`100` = точное совпадение кода) | ## Поиск по местоположению [#search-by-location] Возвращает аэропорты в пределах радиуса от координаты, отсортированные от ближайшего. Каждый результат содержит `distance_km`. ### Запрос [#request-1] | Параметр | Тип | Обязательный | По умолчанию | Описание | | -------- | ------ | ------------ | ------------ | ------------------------------------------------------- | | `lat` | number | Да | - | Широта (от `-90` до `90`, десятичные градусы WGS-84) | | `lon` | number | Да | - | Долгота (от `-180` до `180`, десятичные градусы WGS-84) | | `radius` | number | Нет | `50` | Радиус поиска в **километрах** (должен быть > 0) | | `type` | string | Нет | все типы | Фильтр по `type` аэропорта, например `large_airport` | Возвращает до **50** аэропортов. Вблизи плотной городской застройки могут попадаться вертодромы и закрытые аэродромы, если вы не передаёте `type`. ### Ответ [#response-1] ```json { "search_location": { "latitude": 40.64, "longitude": -73.78, "radius_km": 50.0, "type_filter": null }, "airports": [ { "ident": "KJFK", "name": "John F. Kennedy International Airport", "type": "large_airport", "latitude_deg": 40.639447, "longitude_deg": -73.779317, "municipality": "New York", "iso_country": "US", "iata_code": "JFK", "distance_km": 0.08 } ], "airports_found": 42 } ``` | Поле | Тип | Обязательный | Описание | | ----------------- | ------- | ------------ | ----------------------------------------- | | `search_location` | object | **Да** | Повтор параметров запроса | | `airports` | array | **Да** | Совпадения, отсортированные по расстоянию | | `airports_found` | integer | **Да** | Количество возвращённых (≤ 50) | #### Элемент аэропорта (`airports[]`) [#airport-item-airports-1] Те же базовые поля, что и при текстовом поиске, плюс `distance_km` ([расстояние по ортодромии](https://en.wikipedia.org/wiki/Great-circle_distance) от точки запроса в километрах). ## Поиск по IP [#search-by-ip] Определяет геолокацию IP-адреса и возвращает ближайшие аэропорты в виде того же отсортированного по расстоянию списка, что и [поиск по местоположению](#search-by-location). ### Запрос [#request-2] | Параметр | Тип | Обязательный | По умолчанию | Описание | | -------- | ------ | ------------ | --------------------- | -------------------------------------------------------------------------------------------------------------------------------- | | `ip` | string | Нет | IP вызывающей стороны | IPv4/IPv6 для определения геолокации. Не указывайте, чтобы использовать IP отправителя запроса (RapidAPI передаёт адрес клиента) | | `radius` | number | Нет | `50` | Радиус поиска в километрах | Не указывайте `ip` для серверной функции «Аэропорты рядом со мной», когда RapidAPI получает IP конечного пользователя. Передавайте IP посетителя явно, если ваш бэкенд проксирует запросы. ### Ответ [#response-2] ```json { "ip_address": "203.0.113.10", "location": { "latitude": 40.7128, "longitude": -74.006, "city": "New York", "region": "New York", "country": "United States", "country_code": "US" }, "search_radius_km": 50.0, "airports": [ { "ident": "KJFK", "name": "John F. Kennedy International Airport", "distance_km": 20.5 } ], "airports_found": 38 } ``` | Поле | Тип | Обязательный | Может быть null? | Описание | | ------------------ | -------------- | ------------ | ---------------- | ------------------------------------------------------------------------------------------ | | `ip_address` | string | **Да** | Никогда | IP, для которого определялась геолокация | | `location` | object \| null | Нет | **Да** | Определённая геолокация; `null`, если определение не удалось | | `search_radius_km` | number | **Да** | Никогда | Применённый радиус поиска | | `airports` | array | **Да** | Никогда | Аэропорты, отсортированные по расстоянию (та же форма, что и при поиске по местоположению) | | `airports_found` | integer | **Да** | Никогда | Количество возвращённых | | `error` | string \| null | Нет | **Да** | Сообщение об ошибке, если определить геолокацию не удалось | **Примечание о точности.** IP-адреса домашних сетей определяются с точностью до города; IP-адреса VPN и дата-центров могут определяться неточно. Показывайте определённый город и позволяйте пользователю его изменить. ## Клиентские типы [#client-types] ## Интеграция [#integration] Реализуйте поле автодополнения аэропортов на основе ранжированных результатов текстового поиска. Пример ниже кэширует ответы текстового поиска на один час и использует таймауты подключения и чтения, чтобы ввод в поле поиска не мог «подвесить» ваш интерфейс. ### Примечания по реализации [#implementation-notes] **Применяйте debounce к вводу пользователя.** Подождите \~300 мс после последнего нажатия клавиши, прежде чем вызывать API. Требуйте не менее 2 символов, чтобы избежать ошибок валидации 422. **Ранжирование по релевантности.** `relevance_score: 100` означает точное совпадение ICAO/IATA — закрепляйте такие результаты в начале списка автодополнения. **Фильтруйте типы аэропортов.** Для приложений авиакомпаний отфильтруйте результаты до `large_airport` / `medium_airport` после получения или передайте `type=large_airport` при поиске по местоположению. **Переходите к полному запросу.** После выбора вызовите [Аэропорты](/docs/v31/airports) с `icao`, чтобы получить ВПП и частоты. **Конфиденциальность поиска по IP.** Укажите определение геолокации по IP в своей политике конфиденциальности. Если пользователь даёт разрешение, предпочитайте геолокацию браузера + [поиск по местоположению](#search-by-location). ## Ответы с ошибками [#error-responses] Общие ошибки валидации и платформы: [Обработка ошибок](/docs/errors). Ошибки, специфичные для эндпоинта: ### 422 - слишком короткий текстовый запрос [#422---text-query-too-short] ```json { "detail": [ { "type": "string_too_short", "loc": ["query", "q"], "msg": "String should have at least 2 characters" } ] } ``` ### Не удалось определить GeoIP (поиск по IP) [#geoip-lookup-failed-ip-search] Если определить геолокацию по IP не удалось, API возвращает HTTP `200` с `location: null`, `airports: []` и заполненной строкой `error`. Считайте это мягким сбоем — предложите ввести данные вручную или переключитесь на геолокацию браузера. ```json { "ip_address": "203.0.113.10", "location": null, "search_radius_km": 50.0, "airports": [], "airports_found": 0, "error": "Unable to geolocate IP address" } ``` *** См. также: [Аэропорты](/docs/v31/airports) · [METAR](/docs/v31/weather-metar) · [Страны](/docs/v31/countries)