API Яндекс Маршрутизации: справочник методов, примеры curl-запросов и разбор ошибок

API Яндекс Маршрутизации даёт программам доступ к построению маршрутов: вы отправляете HTTP-запрос с координатами точек, а получаете JSON с длиной пути, временем в пути и геометрией. Ключ API подставляется в каждый вызов, расстояние приходит в метрах, время - в секундах. Время можно запросить для свободной дороги или с учётом текущей дорожной ситуации.

Интерфейс закрывает четыре частые задачи: расчёт ETA для курьеров и водителей, построение пути в корпоративной панели, показ времени поездки в мобильном приложении, планирование поездки на конкретный час. Карту для конечного пользователя этот API не рисует: за отображение отвечают картографические SDK и JS-библиотеки, а сервис маршрутизации возвращает данные для вашей логики.

Ограничение по источникам. В публичных материалах, доступных на момент публикации, нет подтверждённого разбора методов API Яндекс Маршрутизации. Имена параметров, пути методов и поля ответа ниже даны как рабочий шаблон, который нужно сверить с документацией сервиса. Проверяйте версию API и названия полей перед копированием примеров в рабочее окружение.

Что такое API Яндекс Маршрутизации и какие задачи он решает

С точки зрения интеграции это обычный REST-сервис: метод, путь, параметры, ключ и JSON в ответе. Для проверки хватает curl, для рабочего кода подойдёт любой HTTP-клиент. Схема вызова почти всегда одинаковая: определить координаты, выбрать режим движения, отправить запрос, разобрать ответ.

Кому и когда нужен этот API

• Backend-разработчик встраивает расчёт времени доставки в чекаут или в приложение курьера.
• DevOps-инженер и сисадмин подключает сервис к внутренним панелям, настраивает секреты, квоты и мониторинг ошибок.
• Интегратор логистики сравнивает варианты объезда для парка машин и считает расход топлива по километражу.
• Аналитик получает массив расстояний и длительностей, чтобы оценить зоны обслуживания.

Спрос на такие сценарии виден по поведению мобильной аудитории: по данным сайта Koto о локальной рекламе на картах, значительная часть пользователей после поиска организации поблизости совершает действие в тот же день: звонит, строит маршрут или приезжает в точку. Если бизнес ждёт этих действий, время в пути показывают прямо в интерфейсе.

API не нужен, когда задача ограничена показом карты без расчёта пути и когда маршрут строит человек в навигаторе. Для этих случаев берут картографические библиотеки и готовые клиенты.

Что понадобится для начала работы

• Аккаунт в кабинете разработчика и действующий ключ с доступом к сервису маршрутизации.
• curl или HTTP-клиент для проверки; для разбора ответа удобен jq.
• Координаты всех точек в едином формате, чаще всего пара чисел через запятую.
• Переменная окружения для ключа, чтобы он не попадал в репозиторий и логи.

Ключ выпускают в кабинете разработчика, и он обычно ограничен списком сервисов и квотами. В части продуктов доступ оформляют через сервисный аккаунт и OAuth-токен, в части - через ключ приложения; порядок выдачи и доступные типы ключей уточняйте в консоли. Разбор шагов и проверка соединения собраны в пошаговой инструкции по подключению сервиса маршрутизации.

Аутентификация: как получить и использовать ключ API Яндекс Маршрутизации

Все запросы авторизуются ключом. Если ключ не передан или отозван, маршрут не построится: вместо JSON придёт 401 или 403. Проверка ключа занимает минуту, поэтому первый тестовый вызов делайте на паре точек с известным расстоянием.

Где взять ключ и какие ограничения учесть

1. Войдите в кабинет разработчика того продукта, к которому подключён сервис маршрутизации.
2. Создайте приложение или сервисный аккаунт.
3. Подключите сервис маршрутизации к этому приложению.
4. Выпустите ключ и скопируйте его в защищённое хранилище.
5. Задайте ограничения: список IP серверов или referer для браузерных вызовов.
6. Проверьте тариф, квоты и лимит запросов в секунду.

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

Способы передачи ключа в запросе

Ключ передают двумя способами: параметром в строке запроса или заголовком. Для серверных вызовов выбирайте заголовок, тогда ключ не окажется в логах веб-сервера, в истории браузера и в аналитике.

# Вариант 1: параметр в строке запроса
curl -G "${ROUTING_BASE_URL}/route?apikey=${YANDEX_ROUTING_API_KEY}&mode=auto&points=55.7558,37.6173;59.9343,30.3061"

# Вариант 2: заголовок
curl -G "${ROUTING_BASE_URL}/route" \
  -H "Authorization: Bearer ${YANDEX_ROUTING_API_KEY}" \
  --data-urlencode "mode=auto" \
  --data-urlencode "points=55.7558,37.6173;59.9343,30.3061"

Заголовок Authorization со схемой Bearer - распространённый шаблон HTTP-API. В API перевода Polytranslator ключ передают так же, а к запросу добавляют Idempotency-Key, чтобы повтор не создавал дубль. Для маршрутизации логика похожая: повторный POST после таймаута безопаснее помечать ключом идемпотентности. Точное имя схемы и параметра сверяйте в документации сервиса.

Ключ храните в переменных окружения или в секрет-хранилище. Пример запуска:

export YANDEX_ROUTING_API_KEY="ваш_ключ"
export ROUTING_BASE_URL="https://ХОСТ_ИЗ_ДОКУМЕНТАЦИИ"

curl -s -G "${ROUTING_BASE_URL}/route" \
  -H "Authorization: Bearer ${YANDEX_ROUTING_API_KEY}" \
  --data-urlencode "mode=auto" \
  --data-urlencode "points=55.7558,37.6173;59.9343,30.3061" | jq .

Базовые эндпоинты и структура запроса

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

GET подходит для двух-трёх точек и простых условий, POST - когда точек десятки или тело запроса большое. В GET данные идут в строке запроса, в POST - в JSON-теле.

# GET: короткий вызов
curl -G "${ROUTING_BASE_URL}/route" \
  -H "Authorization: Bearer ${YANDEX_ROUTING_API_KEY}" \
  --data-urlencode "mode=auto" \
  --data-urlencode "points=55.7558,37.6173;59.9343,30.3061"

# POST: точки и опции в теле
curl -X POST "${ROUTING_BASE_URL}/route" \
  -H "Authorization: Bearer ${YANDEX_ROUTING_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"mode":"auto","traffic":true,"points":["55.7558,37.6173","59.9343,30.3061"]}'

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

Обязательные и опциональные параметры

Названия параметров отличаются между версиями, поэтому таблица ниже дана как ориентир: сверьте каждое имя в документации перед запуском.

Формат ответа и ключевые поля

Ответ приходит в JSON и обычно содержит массив маршрутов. Внутри маршрута: общая длина, общее время, массив участков между парами точек, пошаговые инструкции и геометрия для отрисовки. Условный пример структуры:

{
  "routes": [
    {
      "distance": {"value": 705000, "text": "705 км"},
      "duration": {"value": 27000, "text": "7 ч 30 мин"},
      "legs": [
        {"steps": [{"instruction": "Двигайтесь на север", "distance": {"value": 400}}]}
      ],
      "geometry": "..."
    }
  ]
}

Числа в метрах и секундах лежат в отдельных полях, текст нужен для интерфейса. ETA считают так: к текущему времени прибавляют длительность, если запрос учитывает дорожную ситуацию, или берут время отправления как точку отсчёта. Геометрия может прийти строкой в кодировке polyline или массивом координат, и это ещё одна причина сверять формат в документации: парсер для одной версии молча вернёт пустую карту на другой.

Построение маршрута между точками: примеры запросов

Порядок действий для первого рабочего вызова:

1. Получите ключ и положите его в переменную окружения.
2. Определите координаты всех точек и запишите их в том порядке, в котором собираетесь ехать.
3. Выберите режим движения и нужные опции: пробки, избегание платных дорог, время отправления.
4. Отправьте запрос и проверьте HTTP-код: 200 означает, что маршрут найден.
5. Разберите JSON и заберите числовые поля длины и времени.

Маршрут между двумя точками

curl -s -G "${ROUTING_BASE_URL}/route" \
  -H "Authorization: Bearer ${YANDEX_ROUTING_API_KEY}" \
  --data-urlencode "mode=auto" \
  --data-urlencode "points=55.7558,37.6173;59.9343,30.3061" | jq '.routes[0].distance, .routes[0].duration'

Пара точек в примере - Москва и Санкт-Петербург, между ними по трассе около 700 км. Такая пара удобна для проверки гипотез: время в ответе приходит в секундах, и 27000 секунд превращаются в 7 часов 30 минут делением на 3600. Если в ответе десятки километров, значит порядок координат или режим движения заданы неверно.

Маршрут с промежуточными точками

curl -s -G "${ROUTING_BASE_URL}/route" \
  -H "Authorization: Bearer ${YANDEX_ROUTING_API_KEY}" \
  --data-urlencode "mode=auto" \
  --data-urlencode "points=55.7558,37.6173;56.3269,44.0059;59.9343,30.3061"

Точки перечисляются через разделитель в том порядке, в котором должны быть посещены, и сервис сохраняет его, если вы не запросили перебор вариантов. Количество участков равно числу точек минус один: три точки дают два участка, четыре - три. Чтобы сервис сам подобрал порядок объезда, нужен отдельный метод или явный параметр, а верхняя граница числа точек зависит от тарифа и версии API.

Расчёт времени в пути и учёт пробок

Ответ без учёта дорожной ситуации описывает свободную дорогу: время окажется оптимистичным, и курьер опоздает. Разница между двумя режимами в час пик измеряется десятками процентов, поэтому для городских маршрутов учёт пробок включают по умолчанию.

Как включить учёт пробок в запросе

curl -s -G "${ROUTING_BASE_URL}/route" \
  -H "Authorization: Bearer ${YANDEX_ROUTING_API_KEY}" \
  --data-urlencode "mode=auto" \
  --data-urlencode "traffic=true" \
  --data-urlencode "points=55.7558,37.6173;55.7900,37.5300" | jq '.routes[0].duration'

Параметр с именем вида traffic включает расчёт по текущей дорожной ситуации. Сравните два вызова, с ним и без него, на одном и том же маршруте: разница покажет вклад пробок в вашем городе. Для общественного транспорта логика другая, там время зависит от расписания, а не только от загрузки дорог.

Прогноз времени в пути на будущее

curl -s -G "${ROUTING_BASE_URL}/route" \
  -H "Authorization: Bearer ${YANDEX_ROUTING_API_KEY}" \
  --data-urlencode "mode=auto" \
  --data-urlencode "departure_time=2026-09-20T08:00:00+03:00" \
  --data-urlencode "points=55.7558,37.6173;56.3269,44.0059" | jq '.routes[0].duration'

Время отправления передают строкой в формате ISO 8601 со смещением часового пояса или числом Unix timestamp. Сервис вернёт прогноз с учётом типичной загрузки дорог на этот час. Горизонт прогноза ограничен, точность падает на дальних датах и в регионах с редкими данными о трафике, поэтому для расписаний на неделю вперёд закладывайте запас времени. Формат поля сверяйте в документации: ошибка в часовом поясе сдвигает весь прогноз.

Примеры curl-запросов для типовых сценариев

Шаблоны ниже закрывают большинство задач: маршрут с пробками, путь через промежуточную точку и запрет платных участков. Во всех примерах ключ берётся из переменной окружения, поэтому команды копируются в терминал без правки.

Автомобильный маршрут с пробками

export YANDEX_ROUTING_API_KEY="ваш_ключ"
export ROUTING_BASE_URL="https://ХОСТ_ИЗ_ДОКУМЕНТАЦИИ"

curl -s -G "${ROUTING_BASE_URL}/route" \
  -H "Authorization: Bearer ${YANDEX_ROUTING_API_KEY}" \
  --data-urlencode "mode=auto" \
  --data-urlencode "traffic=true" \
  --data-urlencode "language=ru_RU" \
  --data-urlencode "points=55.7558,37.6173;55.7900,37.5300" \
  | jq '{distance: .routes[0].distance.value, seconds: .routes[0].duration.value}'

mode=auto задаёт автомобильный маршрут, traffic=true включает пробки, language управляет языком подсказок. Вывод jq оставляет два числа: метры и секунды. Делите секунды на 60 для минут и на 3600 для часов, метры на 1000 для километров.

Маршрут с избеганием платных дорог

curl -s -G "${ROUTING_BASE_URL}/route" \
  -H "Authorization: Bearer ${YANDEX_ROUTING_API_KEY}" \
  --data-urlencode "mode=auto" \
  --data-urlencode "avoid=tolls" \
  --data-urlencode "points=55.7558,37.6173;59.9343,30.3061" | jq '.routes[0].distance.value, .routes[0].duration.value'

Список исключаемых типов дорог зависит от версии API, и строка tolls приведена как пример. При жёстких ограничениях путь удлиняется, а если объезд невозможен, сервис вернёт ошибку или пустой результат. Проверяйте, что маршрут с ограничением существует, прежде чем показывать его клиенту.

Типичные ошибки при интеграции и как их исправить

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

Ошибки аутентификации и прав доступа

403 Forbidden значит, что ключ распознан, но прав нет: сервис маршрутизации не подключён к приложению, ключ отозван, ограничение по IP не совпало или запрос ушёл не с того сервера. 401 Unauthorized обычно указывает на формат: пустая переменная окружения, лишние кавычки в заголовке, схема авторизации написана с ошибкой.

Проверка по шагам:

echo "длина ключа: ${#YANDEX_ROUTING_API_KEY}"
curl -s -o /dev/null -w "%{http_code}\n" -G "${ROUTING_BASE_URL}/route" \
  -H "Authorization: Bearer ${YANDEX_ROUTING_API_KEY}" \
  --data-urlencode "mode=auto" \
  --data-urlencode "points=55.7558,37.6173;55.7900,37.5300"

Если ключ попал в репозиторий или логи, его отзывают и выпускают новый: ротация занимает минуту, разбор инцидента - часы.

Ошибки в параметрах запроса

400 Bad Request приходит, когда пропущено обязательное поле, координаты записаны в неверном формате или режим движения не поддерживается. Частая причина - десятичная запятая вместо точки, ведь запятая уже разделяет широту и долготу.

# Ошибка: десятичная запятая и лишний пробел
points=55,7558, 37,6173

# Исправлено
points=55.7558,37.6173

Второй источник 400 - пустая точка в списке: двойной разделитель подряд сервис читает как отсутствующую координату. Проверяйте список разбором в коде, прежде чем отправлять запрос.

Лимиты и квоты

429 Too Many Requests означает превышение лимита запросов в секунду или суточной квоты. Три рабочих приёма: кэшировать результат для повторяющихся пар точек на 5-15 минут, повторять запрос с нарастающей задержкой (1, 2, 4, 8 секунд), запросить увеличение квоты в кабинете. Для партийных задач добавляйте ограничитель одновременных вызовов: 5-10 параллельных запросов безопаснее, чем сотня.

Ограничения API и что проверить перед продакшеном

Ограничения делятся на четыре группы: число точек в одном запросе, лимиты запросов в секунду и сутки, доступность прогноза трафика по регионам, требования к атрибуции данных. Точные значения зависят от тарифа и версии API, поэтому перед запуском выпишите их из своей консоли. Если нужна альтернатива, сравнивайте по покрытию, свежести данных о пробках и стоимости: Google Directions API, OpenRouteService и GraphHopper решают похожую задачу, но условия у каждого свои.

Чек-лист перед продакшеном

• Ключ лежит в секрет-хранилище или переменной окружения, в репозитории только пример файла.
• Обработаны 4xx и 5xx: пользователь видит понятное сообщение, а не пустой экран.
• Повторяющиеся маршруты кэшируются, срок жизни кэша согласован с частотой обновления данных о пробках.
• Логи не содержат ключ и полные координаты клиентов, если это чувствительные данные.
• Настроен алерт на рост доли 429 и 5xx.
• Разделены окружения: тестовый ключ с малой квотой и рабочий ключ.
• Проверены граничные случаи: одна точка в запросе, недоступный маршрут, точка за границей покрытия, очень длинный маршрут.
• Соблюдены требования к атрибуции данных на картах и в интерфейсах.

Куда смотреть за обновлениями

Версии API и названия параметров меняются, поэтому подпишитесь на changelog сервиса и прогоняйте свою коллекцию запросов перед каждым обновлением. Практичный приём - контрактный тест: один запрос с фиксированными точками и проверка, что в ответе есть длина, время и участки маршрута. Такой тест ловит переименование полей до того, как это заметят пользователи. Все шаблоны из статьи сверяйте с документацией: подтверждённого публичного разбора методов API Яндекс Маршрутизации на момент публикации нет, поэтому единственный надёжный источник имён и лимитов - официальная документация и ваша консоль.