/api/optimal_route — точка вызова сервиса расчёта оптимального маршрута.
Сервис позволяет решить задачу коммивояжёра и осуществить расчёт оптимального маршрута для набора произвольных целевых точек. Для расчёта могут быть использованы автомобильный, пешеходный и велосипедный графы.
Для входного набора координат строит оптимизированный по времени либо по расстоянию маршрут и формирует список координат в порядке их посещения.
Запрос передаётся в формате JSON в HTTP body. JSON запроса состоит из обязательных и необязательных полей. В URL запроса должны быть заданы обязательные параметры.
Простой пример JSON запроса:
{
"locations": [
{"lon": 49.22088, "lat": 55.77055},
{"lon": 49.21999, "lat": 55.77246},
{"lon": 49.21933, "lat": 55.77222},
{"lon": 49.22999, "lat": 55.78246},
{"lon": 49.26842, "lat": 55.75043}
],
"costing": "pedestrian",
"directions_options": {
"units": "miles"
},
"id": "optimal_route_test"
}
Этот запрос рассчитывает оптимальный пеший маршрут со стартом в первой точке из списка locations и финишем в последней точке.
| Имя параметра | Формат | Описание | Пример |
|---|---|---|---|
api_key |
hex-string | Ключ доступа к сервисам | fa749bace6d8a3b1.... |
| Имя поля | Формат | Описание | Пример |
|---|---|---|---|
locations |
list | Список точек, которые нужно отсортировать в соответствии с порядком их посещения. Первая и последняя точки остаются фиксированными, а точки между ними могут быть переставлены для оптимизации маршрута по времени. Минимальное количество точек: 2. | [{"lat": 55.77055, "lon": 49.22088}, ...] |
| Имя поля | Формат | Описание | Пример |
|---|---|---|---|
costing |
string | Тип транспорта для построения маршрута: auto (по умолчанию) — автомобильный; truck — грузовой; pedestrian — пешеходный; bicycle — велосипедный. |
"costing": "pedestrian" |
id |
string | Идентификатор запроса, который возвращается вместе с ответом — позволяет точно установить соответствие запроса и ответа | "id": "optimal_route_test" |
costing_options |
dict | Параметры расчёта маршрута. Для различных типов транспорта используются различные опции и ограничения, аналогичные тем, которые используются в сервисе Построение маршрута. Дополнительно поддерживается опция shortest (по умолчанию false): если false — маршрут оптимизируется по времени; если true — по расстоянию. |
{"auto": {"shortest": true, "use_tolls": 0}} |
units |
string | Единица измерения расстояния в ответе: kilometers (по умолчанию) — километры; miles — мили. |
"units": "miles" |
fix_destination |
bool | Флаг, указывающий, нужно ли фиксировать последнюю из перечисленных координат в locations в качестве финиша. Если true — последняя точка гарантированно является финишем. Если false — последняя точка может оказаться промежуточной. Значение по умолчанию: true. |
"fix_destination": false |
Возвращаемый ответ соответствует структуре GeoJSON.
| Имя поля | Формат | Описание | Пример |
|---|---|---|---|
id |
string | Идентификатор запроса | "id": "optimal_route_test" |
trip |
object | Информация о маршруте | |
trip.locations |
list | Список точек маршрута, отсортированных для оптимального прохождения маршрута. Каждая точка содержит type, lat, lon, original_index — исходный порядковый номер точки из запроса. |
|
trip.legs |
list | Информация о полилинии маршрута. Каждый сегмент содержит summary и shape. Подробнее о декодировании полилинии: Декодирование ломаной маршрута. |
|
trip.summary |
dict | Краткая информация о маршруте: min_lat, min_lon, max_lat, max_lon, time, length, cost. |
|
trip.status_message |
string | Текстовая расшифровка статуса выполнения запроса | "Found route between points" |
trip.status |
integer | Статус выполнения запроса | 0 |
trip.units |
string | Единицы измерения | "kilometers" |
trip.language |
string | Язык, на котором представлена информация о манёврах | "ru-RU" |
При отсутствии результата сервис вернёт:
{"status_code": 400, "status": "Bad Request"}
curl -X POST \
-H "Content-type: application/json" \
-H "Accept: application/json" \
-d '{
"locations": [
{"lon": 49.22088, "lat": 55.77055},
{"lon": 49.21999, "lat": 55.77246},
{"lon": 49.26842, "lat": 55.75043}
],
"costing": "pedestrian",
"directions_options": {"units": "miles"},
"id": "optimal_route_test"
}' \
"/api/optimal_route"
{
"trip": {
"locations": [
{"type": "break", "lat": 55.77055, "lon": 49.22088, "original_index": 0},
{"type": "break", "lat": 55.77246, "lon": 49.21999, "original_index": 1},
{"type": "break", "lat": 55.75043, "lon": 49.26842, "original_index": 2}
],
"legs": [
{
"summary": {
"min_lat": 55.77065,
"min_lon": 49.21999,
"max_lat": 55.772514,
"max_lon": 49.220883,
"time": 188.317,
"length": 0.164,
"cost": 193.317
},
"shape": "u`~jiBepe{|AMlh@gq@o@or@m@eMMAtP"
},
{
"summary": {
"min_lat": 55.750237,
"min_lon": 49.21999,
"max_lat": 55.772515,
"max_lon": 49.269982,
"time": 3543.527,
"length": 3.113,
"cost": 3644.115
},
"shape": "<encoded_polyline_string>"
}
],
"summary": {
"min_lat": 55.750237,
"min_lon": 49.21999,
"max_lat": 55.772515,
"max_lon": 49.269982,
"time": 3731.844,
"length": 3.278,
"cost": 3837.433
},
"status_message": "Found route between points",
"status": 0,
"units": "miles",
"language": "ru-RU"
},
"id": "optimal_route_test"
}
Поле
shapeсодержит закодированную строку полилинии. Для преобразования в координаты используйте Декодирование ломаной маршрута.