# Маршрут

Рассчитайте автомобильный маршрут с остановками в заданном порядке.

## Маршрут по координатам

`POST /v1/route` требует право `route`. Передайте начальную и конечную точки; промежуточные остановки задаются в `via`.

```json
{
  "start": {"latitude":55.75,"longitude":37.61},
  "end": {"latitude":55.76,"longitude":37.62},
  "via": [],
  "profile": "car"
}
```

Замените координаты в примере на свои начальную и конечную точки. Порядок остановок сохраняется: автоматическая оптимизация порядка посещения не выполняется. Расчётное время не учитывает пробки.

## Вызов из SDK

Создайте клиент с `apiBaseUrl: 'https://mmapps.ru'` и [браузерным ключом](https://mmapps.ru/docs/keys). Используйте координаты, выбранные пользователем:

```javascript
const operationKey = crypto.randomUUID();
const result = await geo.routes.calculate({
  start: selectedStart,
  end: selectedEnd,
  via: orderedStops,
  profile: 'car',
}, { operationKey });
```

Сохраняйте `operationKey` для повтора того же запроса. При изменении точек или порядка остановок создайте новый ключ операции.

## Маршрут по адресам

`POST /v1/route/geocode` и `geo.routes.geocode()` принимают для каждой точки один из вариантов: `{q: 'адрес'}`, `{ref: selectedRef}` или `{point: selectedPoint}`.

1. Отправьте адреса в `start`, `end` и при необходимости `via`.
2. Покажите кандидатов из `waypoints` и попросите пользователя подтвердить каждый адрес. Даже единственный кандидат из текстового поиска требует выбора.
3. Замените текст выбранными `ref` или `point` и отправьте запрос с новым ключом операции.

Пока требуется выбор, ответ содержит `outcome: 'needs_confirmation'`, а `route` равен `null`. Устаревший `ref` требует повторного поиска и выбора. Права: `route:geocode`, а также `geocode` для текста, `resolve` для ссылок и `route` для расчёта.

## Отображение результата

Исходные координаты сохраняются в `input_points`, точки привязки к дороге — отдельно в `snapped_points`. Не перемещайте выбранные пользователем маркеры автоматически.

При `outcome: 'no_route'` дорожный путь не найден, `geometry` равна `null`. Сообщите об этом пользователю. Прямую линию между точками нельзя выдавать за рассчитанный маршрут.

Готовую геометрию можно отобразить средствами [SDK](https://mmapps.ru/docs/sdk) без нового расчёта. Проверяйте ошибки запроса по [OpenAPI](https://mmapps.ru/gateway.openapi.yaml). `ROUTING_UNAVAILABLE` означает, что расчёт сейчас недоступен.

## Стоимость

Расчёт — одна операция `route`. В запросе по адресам каждый выполненный текстовый поиск учитывается отдельно как `geocode`. Подтверждённые координаты и ссылки не создают нового списания за геокодинг. До подтверждения всех адресов маршрут не рассчитывается и не оплачивается.

[Тарифы, повторные запросы и учёт расходов](https://mmapps.ru/docs/billing).