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

Расстояние по ортодромии и начальный азимут между аэропортами или координатами: морские мили, километры, мили и средняя точка.



Рассчитывайте **[расстояние по ортодромии](https://en.wikipedia.org/wiki/Great-circle_distance)** (кратчайший путь между двумя точками на сфере, а не прямая линия на плоской карте), начальный **азимут** (направление от точки отправления к точке назначения в градусах относительно истинного меридиана), направление по восьми румбам и географическую среднюю точку между двумя точками. Каждая из сторон может быть кодом аэропорта или координатами [WGS-84](https://en.wikipedia.org/wiki/World_Geodetic_System) — поддерживается и смешанный режим.

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

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

<DocRequirements>
  <DocRequirementAuth />
</DocRequirements>

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

| Параметр    | Тип    | Обязательный | По умолчанию | Описание                                                |
| ----------- | ------ | ------------ | ------------ | ------------------------------------------------------- |
| `from_icao` | string | Условно      | -            | Код ICAO или IATA аэропорта отправления                 |
| `to_icao`   | string | Условно      | -            | Код ICAO или IATA аэропорта назначения                  |
| `from_lat`  | number | Условно      | -            | Широта точки отправления (от `-90` до `90`)             |
| `from_lon`  | number | Условно      | -            | Долгота точки отправления (от `-180` до `180`)          |
| `to_lat`    | number | Условно      | -            | Широта точки назначения (от `-90` до `90`)              |
| `to_lon`    | number | Условно      | -            | Долгота точки назначения (от `-180` до `180`)           |
| `unit`      | string | Нет          | `nm`         | Предпочтительная единица отображения (`nm`, `km`, `mi`) |

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

| Режим                   | Пример                                                     |
| ----------------------- | ---------------------------------------------------------- |
| Аэропорт → аэропорт     | `from_icao=KJFK&to_icao=EGLL`                              |
| Координаты → аэропорт   | `from_lat=40.6413&from_lon=-73.7781&to_icao=EGLL`          |
| Координаты → координаты | `from_lat=40.64&from_lon=-73.78&to_lat=51.47&to_lon=-0.46` |

## Ответ [#response]

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

| Поле           | Тип    | Обязательный | Описание                                                                           |
| -------------- | ------ | ------------ | ---------------------------------------------------------------------------------- |
| `from`         | string | **Да**       | Распознанный идентификатор точки отправления                                       |
| `to`           | string | **Да**       | Распознанный идентификатор точки назначения                                        |
| `distance_nm`  | number | **Да**       | Расстояние в **морских милях** (1 NM ≈ 1.852 km — стандартная авиационная единица) |
| `distance_km`  | number | **Да**       | Расстояние в километрах                                                            |
| `distance_mi`  | number | **Да**       | Расстояние в сухопутных (уставных) милях                                           |
| `bearing_deg`  | number | **Да**       | Начальный истинный азимут (0–360)                                                  |
| `cardinal`     | string | **Да**       | Направление по восьми румбам (`N`, `NE`, `E`, …), вычисленное по азимуту           |
| `midpoint_lat` | number | **Да**       | Широта географической средней точки                                                |
| `midpoint_lon` | number | **Да**       | Долгота географической средней точки                                               |

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

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

<DocClientTypes id="v31/distance/distance-types" />

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

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

<DocExample id="v31/distance/distance-fetch" />

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

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

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

**Определение маршрута.** Чтобы получить пару «пункт отправления — пункт назначения» по позывному, используйте [Маршруты](/docs/v31/routes). Блочное время, предсказанное ML-моделью, см. на странице [Время полёта](/docs/v31/flight-time).

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

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

### 422 — некорректно заданная точка [#422---invalid-point-definition]

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

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

***

См. также: [Аэропорты](/docs/v31/airports) · [Маршруты](/docs/v31/routes) · [Брифинг полёта](/docs/v31/flight-briefing)