/api/directions — точка вызова сервиса построения маршрутов с возможностью расчёта нескольких альтернативных маршрутов за один запрос и поддержкой пробок.
Запрос передаётся в формате JSON в HTTP body. JSON запроса состоит из обязательных и необязательных полей. В URL запроса должны быть заданы обязательные параметры.
Простой пример JSON запроса:
{
"locations": [
{"lat": 43.133200, "lon": 131.911300},
{"lat": 50.266000, "lon": 127.535600}
],
"costing": "auto",
"costing_options": {
"auto": {"use_border_crossing": 0}
},
"units": "kilometers",
"id": "my_route"
}
Этот запрос строит маршрут между Владивостоком и Благовещенском. Он пытается избежать маршрута через Китай, добавляя штраф за пересечение международных границ.
| Имя параметра | Формат | Описание | Пример |
|---|---|---|---|
api_key |
hex-string | Ключ доступа к сервисам | fa749bace6d8a3b1.... |
| Имя поля | Формат | Описание | Пример |
|---|---|---|---|
locations |
list | Список точек для построения маршрута. Маршрут строится в порядке, заданном в запросе. Каждая точка задаётся параметрами: lat, lon, type, heading. |
[{"lat": 55.796932, "lon": 37.537849, "heading": 150}, ...] |
lat |
float | Широта точки маршрута в градусах (6 знаков после запятой). | "lat": 55.796932 |
lon |
float | Долгота точки маршрута в градусах (6 знаков после запятой). | "lon": 37.537849 |
| Имя поля | Формат | Описание | Пример |
|---|---|---|---|
type |
string | Тип точки маршрута: break (по умолчанию) — развороты разрешены, создаётся отдельная ветка в legs; through — развороты запрещены, ветка не создаётся; via — развороты разрешены, ветка не создаётся; break_through — развороты запрещены, создаётся отдельная ветка. Типы первой и последней точек игнорируются и всегда считаются break. |
"type": "via" |
heading |
float | Предпочтительное направление движения при старте в градусах (север — 0°, восток — 90°, юг — 180°, запад — 270°). | "heading": 150 |
costing |
string | Тип транспорта: auto (по умолчанию), truck, pedestrian, bicycle, taxi. |
"costing": "pedestrian" |
costing_options |
dict | Параметры расчёта маршрута по типу транспорта. Подробнее: Объекты costing options. | {"auto": {"use_border_crossing": 0, "use_tolls": 0}} |
units |
string | Единица измерения расстояния: kilometers (по умолчанию), miles. |
"units": "miles" |
language |
string | Язык ответа: ru-RU (по умолчанию), en-US. |
"language": "en-US" |
id |
string | Идентификатор запроса — возвращается вместе с ответом. | "id": "route_to_airport" |
directions_type |
string | Описание манёвров: none (по умолчанию) — без описания; maneuvers — включить; instructions — с текстовыми инструкциями на выбранном языке. |
"directions_type": "instructions" |
avoid_locations |
list | Точки, которые необходимо избегать при построении маршрута (массив {lat, lon}). |
[{"lat": 55.871899, "lon": 37.457765}] |
date_time |
dict | Дата и время отправления или прибытия. Поле type: 0 — текущее время; 1 — время отправления; 2 — время прибытия. Поле value — дата в формате ISO 8601 (ГГГГ-ММ-ДДТчч:мм) в местном часовом поясе. |
{"type": 2, "value": "2020-12-33T21:00"} |
alternates |
integer | Количество альтернативных маршрутов (0–4). 0 — один маршрут; 4 — пять маршрутов. |
"alternates": 3 |
alternates_multi_points |
boolean | Прокладка альтернативных маршрутов через промежуточные точки. По умолчанию false. |
"alternates_multi_points": true |
completeness |
string | Объём ответа: minimal (по умолчанию) — только манёвры; enriched — со всеми рёбрами маршрута. |
"completeness": "enriched" |
Подробное описание параметров расчёта маршрута для каждого типа транспорта (Auto, Truck, Pedestrian, Bicycle, Taxi) — в разделе Объекты costing options.
| Имя поля | Формат | Описание | Пример |
|---|---|---|---|
trips |
list | Корневой список маршрутов. При запросе альтернатив содержит несколько элементов. | |
trip |
dict | Полное описание маршрута. | |
status |
number | Код ошибки. | "status": 0 |
status_message |
string | Описание ошибки. | "status_message": "Found 2 route(s) between points" |
units |
string | Единица измерения расстояния: kilometers или miles. |
"units": "kilometers" |
language |
string | Язык ответа: ru-RU или en-US. |
"language": "ru-RU" |
locations |
list | Точки маршрута из запроса с дополнительной информацией. | |
original_index |
integer | Порядковый номер точки. | "original_index": 0 |
type |
string | Тип точки: break, through, via, break_through. |
"type": "break" |
lat |
float | Широта точки (6 знаков после запятой). | "lat": 55.796932 |
lon |
float | Долгота точки (6 знаков после запятой). | "lon": 37.537849 |
heading |
float | Направление движения при старте в градусах. | "heading": 150 |
id |
string | Идентификатор запроса. | "id": "route_to_airport" |
| Имя поля | Формат | Описание | Пример |
|---|---|---|---|
summary |
dict | Общая информация о маршруте. | |
ll_boxes |
list | Баундинг-боксы области маршрута. Обычно один элемент; два — при пересечении антимеридиана. | [{"max_lon": 37.546925, "max_lat": 55.962685, "min_lat": 55.793781, "min_lon": 37.406376}] |
max_lon |
float | Максимальная долгота области (6 знаков после запятой). | "max_lon": 37.546925 |
max_lat |
float | Максимальная широта области (6 знаков после запятой). | "max_lat": 55.962685 |
min_lat |
float | Минимальная широта области (6 знаков после запятой). | "min_lat": 55.793781 |
min_lon |
float | Минимальная долгота области (6 знаков после запятой). | "min_lon": 37.406376 |
time |
float | Расчётное время движения по маршруту в секундах. | "time": 2168.574 |
length |
float | Общая длина маршрута в выбранных единицах. | "length": 29.121 |
| Имя поля | Формат | Описание | Пример |
|---|---|---|---|
legs |
dict | Сегменты маршрута между парами точек с "type": "break". Каждый содержит summary, shape и maneuvers. |
|
shape |
string | Кодированная полилиния с координатами маршрута. См. Декодирование ломаной маршрута. | |
edges |
list | Рёбра маршрута (только при "completeness": "enriched"). |
[{"id": 12345}, ...] |
id |
int | Уникальный идентификатор ребра. | "id": 3459922 |
length_km |
float | Длина ребра в км. | "length_km": 0.314 |
use |
string | Тип ребра: road, ramp, turn_channel, track, driveway, alley, parking_aisle, emergency_access, drive_through, culdesac, living_street, service_road, cycleway, mountain_bike, sidewalk, footway, steps, path, pedestrian, bridleway, rest_area, service_area, other, rail-ferry, ferry, rail, bus, egress_connection, platform_connection, transit_connection. |
"use": "cycleway" |
road_class |
string | Класс дороги: motorway, trunk, primary, secondary, tertiary, unclassified, residential, service_other. |
"road_class": "secondary" |
surface |
string | Тип покрытия: paved_smooth, paved, paved_rough, compacted, dirt, gravel, path, impassable. |
"surface": "gravel" |
toll |
boolean | Признак платного участка дороги. Только для типов auto, motorcycle, truck, taxi. |
"toll": true |
speed_limit |
int | Максимально допустимая скорость в км/ч. | "speed_limit": 60 |
iso_code |
string | ISO-код страны (ISO 3166-1 alpha-2) — указывается при пересечении границы. | "iso_code": "RU" |
maneuvers |
list | Список манёвров с точками на полилинии, длительностью и текстовыми подсказками. | |
travel_mode |
string | Режим маршрутизации: drive (для auto и truck), pedestrian, bicycle. |
"travel_mode": "drive" |
travel_type |
string | Тип транспортного средства: car, tractor_trailer, foot, road. |
"travel_type": "car" |
instruction |
string | Текстовая подсказка о манёвре. | |
verbal_pre_transition_instruction |
string | Голосовое сообщение при подготовке к манёвру. | |
verbal_transition_alert_instruction |
string | Голосовое сообщение непосредственно перед манёвром. | |
verbal_post_transition_instruction |
string | Голосовое сообщение сразу после завершения манёвра. | |
verbal_multi_cue |
boolean | true, если сообщение verbal_pre_transition_instruction указывает на несколько последовательных близких манёвров. |
"verbal_multi_cue": true |
length |
float | Длина манёвра в выбранных единицах. | "length": 9.490 |
time |
float | Расчётное время на манёвр в секундах. | "time": 421.573 |
begin_shape_index |
integer | Индекс начала манёвра на полилинии. | "begin_shape_index": 344 |
end_shape_index |
integer | Индекс окончания манёвра на полилинии. | "end_shape_index": 459 |
begin_edge_index |
integer | Индекс первого ребра манёвра (при "completeness": "enriched"). |
"begin_edge_index": 5 |
end_edge_index |
integer | Индекс последнего ребра манёвра (при "completeness": "enriched"). |
"end_edge_index": 9 |
type |
integer | Код типа манёвра. См. таблицу значений. | "type": 8 |
street_names |
list | Названия улиц манёвра. | |
toll |
boolean | true, если манёвр проходит по платному участку. |
"toll": true |
ferry |
boolean | true, если манёвр требует использования парома. |
"ferry": true |
rough |
boolean | true, если манёвр проходит по дороге без покрытия. |
"rough": true |
gate |
boolean | true, если манёвр пересекает ворота или шлагбаум. |
"gate": true |
roundabout_exit_count |
integer | Номер съезда с кругового движения. | "roundabout_exit_count": 2 |
type |
Расшифровка | type |
Расшифровка |
|---|---|---|---|
| 0 | — | 20 | kExitRight |
| 1 | kStart | 21 | kExitLeft |
| 2 | kStartRight | 22 | kStayStraight |
| 3 | kStartLeft | 23 | kStayRight |
| 4 | kDestination | 24 | kStayLeft |
| 5 | kDestinationRight | 25 | kMerge |
| 6 | kDestinationLeft | 26 | kRoundaboutEnter |
| 7 | kBecomes | 27 | kRoundaboutExit |
| 8 | kContinue | 28 | kFerryEnter |
| 9 | kSlightRight | 29 | kFerryExit |
| 10 | kRight | 30 | kTransit |
| 11 | kSharpRight | 31 | kTransitTransfer |
| 12 | kUturnRight | 32 | kTransitRemainOn |
| 13 | kUturnLeft | 33 | kTransitConnectionStart |
| 14 | kSharpLeft | 34 | kTransitConnectionTransfer |
| 15 | kLeft | 35 | kTransitConnectionDestination |
| 16 | kSlightLeft | 36 | kPostTransitConnectionDestination |
| 17 | kRampStraight | 37 | kMergeRight |
| 18 | kRampRight | 38 | kMergeLeft |
| 19 | kRampLeft |
При отсутствии подходящего маршрута сервис вернёт:
{"error_code": 171, "error": "No suitable edges near location", "status_code": 400, "status": "Bad Request"}
curl -X POST \
-H "Content-type: application/json" \
-H "Accept: application/json" \
-d '{
"locations": [
{"lat": 55.796932, "lon": 37.537849, "heading": 150},
{"lat": 55.865625, "lon": 37.462290, "type": "via"},
{"lat": 55.962139, "lon": 37.406377}
],
"costing": "auto",
"language": "ru-RU",
"directions_type": "instructions",
"id": "route_to_airport"
}' \
"/api/directions"
{
"trips": [
{
"trip": {
"locations": [
{
"type": "break",
"lat": 55.796932,
"lon": 37.537849,
"heading": 150,
"original_index": 0
},
{
"type": "via",
"lat": 55.865625,
"lon": 37.46229,
"original_index": 1
},
{
"type": "break",
"lat": 55.962139,
"lon": 37.406377,
"original_index": 2
}
],
"legs": [
{
"maneuvers": [
{
"type": 3,
"instruction": "Повернуть налево.",
"verbal_succinct_transition_instruction": "Налево.",
"verbal_pre_transition_instruction": "Повернуть налево.",
"verbal_post_transition_instruction": "Через 50 м.",
"time": 8.72,
"length": 0.048,
"cost": 364.824,
"begin_shape_index": 0,
"end_shape_index": 3,
"verbal_multi_cue": true,
"travel_mode": "drive",
"travel_type": "car"
},
{
"type": 10,
"instruction": "Повернуть направо.",
"verbal_transition_alert_instruction": "Повернуть направо.",
"verbal_succinct_transition_instruction": "Направо.",
"verbal_pre_transition_instruction": "Повернуть направо.",
"verbal_post_transition_instruction": "Через 600 м.",
"street_names": ["Ленинградский проспект"],
"time": 37.931,
"length": 0.593,
"cost": 72.21,
"begin_shape_index": 3,
"end_shape_index": 12,
"travel_mode": "drive",
"travel_type": "car"
},
{
"type": 4,
"instruction": "Вы прибыли.",
"verbal_transition_alert_instruction": "Вы прибыли.",
"verbal_pre_transition_instruction": "Вы прибыли.",
"time": 0.0,
"length": 0.0,
"cost": 0.0,
"begin_shape_index": 439,
"end_shape_index": 439,
"travel_mode": "drive",
"travel_type": "car"
}
],
"summary": {
"ll_boxes": [
{
"min_lat": 55.79378,
"min_lon": 37.39366,
"max_lat": 55.962686,
"max_lon": 37.546925
}
],
"has_time_restrictions": false,
"time": 1444.743,
"length": 26.583,
"cost": 3019.145
},
"shape": "<encoded_polyline_string>"
}
],
"summary": {
"ll_boxes": [
{
"min_lat": 55.79378,
"min_lon": 37.39366,
"max_lat": 55.962686,
"max_lon": 37.546925
}
],
"has_time_restrictions": false,
"time": 1444.743,
"length": 26.583,
"cost": 3019.145
}
}
}
],
"ll_boxes": [
{
"min_lat": 55.79378,
"min_lon": 37.39366,
"max_lat": 55.962686,
"max_lon": 37.546925
}
],
"status_message": "Found 1 route(s) between points",
"status": 0,
"units": "kilometers",
"language": "ru-RU"
}
Поле
shapeсодержит закодированную строку полилинии. Для преобразования в координаты используйте Декодирование ломаной маршрута.