Типы маршрутов
Кратчайший по времени
По умолчанию прокладывается кратчайший по времени автомобильный маршрут с учётом текущих пробок. Чтобы указать тип маршрута явно, нужно добавить в запрос поле type
. Автомобильный маршрут по текущим пробкам.
{
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
],
"type": "jam"
}
Маршрут на определенное время
Вместо текущих пробок можно использовать статистическую информацию по пробкам. Для этого нужно указать тип маршрута statistic
и нужную дату-время в виде Unix-времени в поле utc
. Например, автомобильный маршрут на основе статистических данных по пробкам на 1 декабря 2020 года, 12 часов UTC.
{
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
],
"type": "statistic",
"utc": 1606826131
}
Кратчайший по расстоянию
Чтобы построить самый короткий маршрут, даже если он не является оптимальным по времени из-за пробок, нужно указать тип shortest
. Автомобильный маршрут без учета пробок.
{
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
],
"type": "shortest"
}
С учётом полос общественного транспорта
Также можно строить маршруты с учётом полос общественного транспорта (удобно для такси и автобусов). Для этого нужно к выбранному типу маршрута добавить префикс "taxi_": taxi_jam
, taxi_statistic
, taxi_shortest
.
{
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
],
"type": "taxi_jam"
}
Пешеходный
Чтобы проложить пешеходный маршрут, нужно указать тип pedestrian
.
{
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
],
"type": "pedestrian"
}
Маршруты внутри зданий
Чтобы построить пешеходный маршрут внутри зданий с поэтажными планами, нужно указать параметры "use_indoor": true
и "options": ["pedestrian_instructions"]
. При этом хотя бы одна из конечных точек маршрута должна находиться внутри здания или быть привязана к зданию с помощью параметра object_id
.
Идентификатор этажа для точки можно указать при помощи параметра floor_id
.
{
"points": [
{
"type": "walking",
"x": 82.891385,
"y": 54.983477,
"object_id": "70000001057266023",
"floor_id": "141832716803532"
},
{
"type": "walking",
"x": 82.897328,
"y": 54.980198,
"floor_id": "70030076256452036"
}
],
"type": "pedestrian",
"use_indoor": true,
"options": ["pedestrian_instructions"]
}
Ответ будет содержать маршрут, построенный на основе этажных схем зданий, а также инструкции по пешеходной навигации: входы и выходы из зданий, перемещение между этажами на лифте, эскалаторе или по лестнице.
Велосипедный
Чтобы проложить велосипедный маршрут, нужно указать тип bicycle
.
{
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
],
"type": "bicycle"
}
По умолчанию велосипедные маршруты включают лестницы, автомобильные дороги, подземные и надземные переходы. Чтобы их исключить, можно указать параметр filters
(см. Исключение типов дорог).
Типы точек
Начальные и конечные точки
Если начальная или конечная точка автомобильного маршрута расположена не на дороге, то в маршрут будет добавлен путь, соединяющий её с ближайшей дорогой. Для этого можно использовать два типа точек:
walking
- будет добавлен путь с обходом препятствий, таких как здания (пешеходный);stop
- будет добавлен прямой путь, игнорирующий препятствия.
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "stop",
"x": 82.945039,
"y": 55.033879
}
]
Для любого типа маршрута можно указать несколько начальных и конечных точек. Это может быть удобно в тех случаях, когда у здания есть несколько входов и выходов. При указании нескольких точек будет построен оптимальный маршрут от одной из начальных точек до одной из конечных.
Чтобы отделить начальные точки от конечных в массиве points
, можно использовать параметр start
или добавить промежуточные точки (см. следующий раздел).
"points": [
{
"type": "stop",
"x": 82.93057,
"y": 54.943207,
"start": true
},
{
"type": "stop",
"x": 82.93856,
"y": 54.943112,
"start": true
},
{
"type": "stop",
"x": 82.945039,
"y": 55.033879
}
]
Промежуточные точки
В любой маршрут можно добавить промежуточные точки, указав тип pref
. Общее количество точек в маршруте не должно превышать 10.
"points": [
{
"type": "walking",
"x": 82.93057,
"y": 54.943207
},
{
"type": "pref",
"x": 82.941984,
"y": 54.974563
},
{
"type": "walking",
"x": 82.945039,
"y": 55.033879
}
]
Исключение типов дорог
При построении маршрута можно исключить определенные типы дорог, такие как грунтовые и платные (для автомобильного маршрута) или лестницы и переходы (для велосипедного маршрута). Чтобы это сделать, нужно указать в запросе поле filters
.
Например, чтобы исключить грунтовые дороги из автомобильного маршрута, нужно указать значение "dirt_road":
{
"points": [...],
"filters": ["dirt_road"]
}
Чтобы исключить лестницы, подземные/надземные переходы и автомобильные дороги из велосипедного маршрута, нужно указать следующий массив значений:
{
"points": [...],
"type": "bicycle",
"filters": [
"ban_stairway",
"ban_over",
"ban_car_road"
]
}
Если маршрут без указанных типов дорог получается слишком длинным или его невозможно построить, часть получившегося маршрута может включать исключённые типы дорог.
Также можно исключить некоторые типы дорог из пешеходного маршрута. Полный список возможных значений можно найти в Справочнике API.
Исключение областей
В запросе можно указать области, которые будут избегаться при построении маршрута. Для этого используется поле exclude
.
Область можно указать в виде круга, многоугольника или толстой линии. Для описания области используется три параметра:
type
- форма исключаемой области (круг, многоугольник или линия);points
- координаты области;extent
- размер области в метрах (радиус круга или ширина линии).
{
"points": [...],
"exclude": [
{
"type": "point",
"points": [
{
"x": 82.03057,
"y": 54.043207
}
],
"extent": 100
},
{
"type": "polyline",
"points": [
{
"x": 82.13057,
"y": 54.143207
},
{
"x": 82.23057,
"y": 54.243207
}
],
"extent": 1000
}
]
}
Для каждой области можно дополнительно указать параметр severity
- насколько строго нужно избегать выбранную область (soft
- избегать по возможности; hard
- избегать всегда). Например, исключить область в виде многоугольника.
{
"points": [...],
"exclude": [
{
"type": "polygon",
"points": [
{"x": 55.28770929, "y": 25.22069944},
{"x": 55.28976922, "y": 25.25656786},
{"x": 55.33302789, "y": 25.25687836},
{"x": 55.33096795, "y": 25.22007825},
{"x": 55.28770929, "y": 25.22069944}
],
"severity": "hard"
}
]
}