Расстояние и азимут

Рассчитывайте расстояние по ортодромии (кратчайший путь между двумя точками на сфере, а не прямая линия на плоской карте), начальный азимут (направление от точки отправления к точке назначения в градусах относительно истинного меридиана), направление по восьми румбам и географическую среднюю точку между двумя точками. Каждая из сторон может быть кодом аэропорта или координатами WGS-84 — поддерживается и смешанный режим.

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

Запрос

Задайте каждую сторону либо парой кодов, либо парой координат:

Ответ

{
  "from": "KJFK",
  "to": "EGLL",
  "distance_nm": 2991.61,
  "distance_km": 5539.91,
  "distance_mi": 3442.19,
  "bearing_deg": 51.35,
  "cardinal": "NE",
  "midpoint_lat": 52.216,
  "midpoint_lon": -41.306
}

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

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

"""Distance endpoint response models for /distance."""from __future__ import annotationsfrom dataclasses import dataclass@dataclassclass DistanceRequest:    from_icao: str | None = None    to_icao: str | None = None    from_lat: float | None = None    from_lon: float | None = None    to_lat: float | None = None    to_lon: float | None = None    unit: str | None = None@dataclassclass DistanceResponse:    from_: str    to: str    distance_nm: float    distance_km: float    distance_mi: float    bearing_deg: float    cardinal: str    midpoint_lat: float    midpoint_lon: float

Интеграция

Рассчитайте геометрию маршрута для карточки предпросмотра с явной обработкой тайм-аутов.

import osimport requestsBASE = "https://data.skylinkapi.com/v3.1"HEADERS = {    "x-api-key": os.getenv("SKYLINK_API_KEY", "YOUR_API_KEY")}def fetch_distance(from_icao: str, to_icao: str) -> dict:    """Fetch great-circle distance and initial bearing between two airports."""    r = requests.get(        f"{BASE}/distance",        headers=HEADERS,        params={"from_icao": from_icao, "to_icao": to_icao},        timeout=(10, 15),    )    r.raise_for_status()    return r.json()if __name__ == "__main__":    import json    data = fetch_distance("KJFK", "KLAX")    print(json.dumps(data, indent=2, default=str))

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

Валидация входных данных. Проверяйте границы широты и долготы на стороне клиента, чтобы избежать лишних ответов 422.

Направление по румбам. cardinal отражает только начальный азимут — без учёта ветра и опубликованных маршрутов по воздушным трассам.

Определение маршрута. Чтобы получить пару «пункт отправления — пункт назначения» по позывному, используйте Маршруты. Блочное время, предсказанное ML-моделью, см. на странице Время полёта.

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

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

422 — некорректно заданная точка

{
  "detail": [
    {
      "type": "value_error",
      "loc": ["query", "from_lat"],
      "msg": "from_lat must be between -90 and 90"
    }
  ]
}

curl -X GET "https://data.skylinkapi.com/v3.1/distance"

{
  "from_point": {
    "latitude": 40.639751,
    "longitude": -73.778925,
    "icao_code": "KJFK",
    "iata_code": "JFK",
    "name": "John F Kennedy International Airport"
  },
  "to_point": {
    "latitude": 51.4706,
    "longitude": -0.461941,
    "icao_code": "EGLL",
    "iata_code": "LHR",
    "name": "London Heathrow Airport"
  },
  "distance": 2991.01,
  "unit": "nm",
  "bearing": 51.35,
  "bearing_cardinal": "NE",
  "midpoint": {
    "latitude": 52.216674,
    "longitude": -41.302671
  }
}

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

См. также: Аэропорты · Маршруты · Брифинг полёта