Поиск аэропортов

Три режима поиска помогают пользователям найти аэропорт до того, как вы запросите полные записи через Аэропорты: поиск с подсказками по названию или коду, ближайшие аэропорты к метке на карте или GPS-координатам и ближайшие аэропорты, определённые по IP посетителя. Все три режима возвращают одну и ту же базовую схему элемента аэропорта; режимы по местоположению и по IP добавляют distance_km.

Поиск по тексту

Полнотекстовый поиск по кодам ICAO, кодам IATA, названиям аэропортов и городам. Результаты ранжируются по relevance_score — точные совпадения кода получают наивысшую оценку.

Запрос

Ответ

{
  "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
}

Элемент аэропорта (airports[])

curl -X GET "https://data.skylinkapi.com/v3.1/airports/search/text?q=string"

{
  "query": "London",
  "airports": [
    {
      "ident": "EGLL",
      "type": "large_airport",
      "name": "London Heathrow Airport",
      "latitude_deg": 51.4706,
      "longitude_deg": -0.4619,
      "municipality": "London",
      "iso_country": "GB",
      "iata_code": "LHR",
      "relevance_score": 80
    }
  ],
  "airports_found": 1
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Поиск по местоположению

Возвращает аэропорты в пределах радиуса от координаты, отсортированные от ближайшего. Каждый результат содержит distance_km.

Запрос

Возвращает до 50 аэропортов. Вблизи плотной городской застройки могут попадаться вертодромы и закрытые аэродромы, если вы не передаёте type.

Ответ

{
  "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
}

Элемент аэропорта (airports[])

Те же базовые поля, что и при текстовом поиске, плюс distance_km (расстояние по ортодромии от точки запроса в километрах).

curl -X GET "https://data.skylinkapi.com/v3.1/airports/search/location?lat=-90&lon=-180"

{
  "search_location": {
    "latitude": 40.64,
    "longitude": -73.78,
    "radius_km": 50
  },
  "airports": [
    {
      "id": 3682,
      "ident": "KJFK",
      "type": "large_airport",
      "name": "John F Kennedy International Airport",
      "latitude_deg": 40.6398,
      "longitude_deg": -73.7789,
      "elevation_ft": 13,
      "municipality": "New York",
      "iso_country": "US",
      "iso_region": "US-NY",
      "iata_code": "JFK",
      "distance_km": 0.15
    }
  ],
  "airports_found": 1
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Поиск по IP

Определяет геолокацию IP-адреса и возвращает ближайшие аэропорты в виде того же отсортированного по расстоянию списка, что и поиск по местоположению.

Запрос

Не указывайте ip для серверной функции «Аэропорты рядом со мной», когда RapidAPI получает IP конечного пользователя. Передавайте IP посетителя явно, если ваш бэкенд проксирует запросы.

Ответ

{
  "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
}

Примечание о точности. IP-адреса домашних сетей определяются с точностью до города; IP-адреса VPN и дата-центров могут определяться неточно. Показывайте определённый город и позволяйте пользователю его изменить.

curl -X GET "https://data.skylinkapi.com/v3.1/airports/search/ip"

{
  "ip_address": "8.8.8.8",
  "location": {
    "latitude": 37.751,
    "longitude": -97.822,
    "city": "Wichita",
    "region": "Kansas",
    "country": "United States",
    "country_code": "US",
    "postal": "67202",
    "timezone": "America/Chicago",
    "ip": "8.8.8.8"
  },
  "airports": [],
  "search_radius_km": 100,
  "airports_found": 0
}

{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}

Клиентские типы

"""Text search response types - matches airport-search.mdx field tables."""from __future__ import annotationsfrom dataclasses import dataclass@dataclassclass TextSearchRequest:    q: str    limit: int = 10@dataclassclass TextSearchAirport:    ident: str    name: str    type: str    latitude_deg: float    longitude_deg: float    municipality: str | None    iso_country: str | None    iata_code: str | None    relevance_score: int@dataclassclass TextSearchResponse:    query: str    airports: list[TextSearchAirport]    airports_found: int@dataclassclass LocationSearchRequest:    lat: float    lon: float    radius: float = 50.0    type: str | None = None@dataclassclass LocationAirport:    ident: str    name: str    type: str    latitude_deg: float    longitude_deg: float    municipality: str | None    iso_country: str | None    iata_code: str | None    distance_km: float@dataclassclass LocationSearchResponse:    search_location: dict    airports: list[LocationAirport]    airports_found: int@dataclassclass AirportSuggestion:    """Shape returned by autocomplete_suggestions() in the text-search example."""    icao: str | None    iata: str | None    name: str    municipality: str | None    country: str | None    relevance_score: int

Интеграция

Реализуйте поле автодополнения аэропортов на основе ранжированных результатов текстового поиска.

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

import osimport timefrom dataclasses import dataclassimport requestsHEADERS = {    "x-api-key": os.getenv("SKYLINK_API_KEY", "YOUR_API_KEY")}BASE = "https://data.skylinkapi.com/v3.1"CACHE: dict[str, tuple[dict, float]] = {}TEXT_SEARCH_TTL = 3600  # 1 h - airport names/codes are stable@dataclassclass AirportSuggestion:    icao: str | None    iata: str | None    name: str    municipality: str | None    country: str | None    relevance_score: intdef search_airports_text(query: str, limit: int = 10) -> dict:    cache_key = f"text:{query.lower()}:{limit}"    cached = CACHE.get(cache_key)    if cached and time.time() < cached[1]:        return cached[0]    r = requests.get(        f"{BASE}/airports/search/text",        headers=HEADERS,        params={"q": query, "limit": limit},        timeout=(10, 15),    )    r.raise_for_status()    data = r.json()    CACHE[cache_key] = (data, time.time() + TEXT_SEARCH_TTL)    return datadef autocomplete_suggestions(query: str, limit: int = 8) -> list[AirportSuggestion]:    payload = search_airports_text(query, limit=limit)    out: list[AirportSuggestion] = []    for row in payload.get("airports", []):        out.append(            AirportSuggestion(                icao=row.get("ident"),                iata=row.get("iata_code"),                name=row["name"],                municipality=row.get("municipality"),                country=row.get("iso_country"),                relevance_score=int(row.get("relevance_score") or 0),            )        )    return outif __name__ == "__main__":    import json    result = search_airports_text("JFK", limit=5)    print(json.dumps(result, indent=2, default=str))

Примечания по реализации

Применяйте debounce к вводу пользователя. Подождите ~300 мс после последнего нажатия клавиши, прежде чем вызывать API. Требуйте не менее 2 символов, чтобы избежать ошибок валидации 422.

Ранжирование по релевантности. relevance_score: 100 означает точное совпадение ICAO/IATA — закрепляйте такие результаты в начале списка автодополнения.

Фильтруйте типы аэропортов. Для приложений авиакомпаний отфильтруйте результаты до large_airport / medium_airport после получения или передайте type=large_airport при поиске по местоположению.

Переходите к полному запросу. После выбора вызовите Аэропорты с icao, чтобы получить ВПП и частоты.

Конфиденциальность поиска по IP. Укажите определение геолокации по IP в своей политике конфиденциальности. Если пользователь даёт разрешение, предпочитайте геолокацию браузера + поиск по местоположению.

Ответы с ошибками

Общие ошибки валидации и платформы: Обработка ошибок. Ошибки, специфичные для эндпоинта:

422 - слишком короткий текстовый запрос

{
  "detail": [
    {
      "type": "string_too_short",
      "loc": ["query", "q"],
      "msg": "String should have at least 2 characters"
    }
  ]
}

Не удалось определить GeoIP (поиск по IP)

Если определить геолокацию по IP не удалось, API возвращает HTTP 200 с location: null, airports: [] и заполненной строкой error. Считайте это мягким сбоем — предложите ввести данные вручную или переключитесь на геолокацию браузера.

{
  "ip_address": "203.0.113.10",
  "location": null,
  "search_radius_km": 50.0,
  "airports": [],
  "airports_found": 0,
  "error": "Unable to geolocate IP address"
}

См. также: Аэропорты · METAR · Страны