Оптимизация маршрута v.2

Описание

/v2/optimal_route/ - точка вызова сервиса расчета оптимального маршрута. Для входного набора координат строит оптимизированный по времени, либо по расстоянию маршрут и формирует список координат в порядке их посещения. 

Запрос

Запрос передается в виде 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

Доступ к сервисам

api_key=fa749bace6d8a3b1....
locations list

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

Минимальное количество точек: 2.

"locations":
[
    {
        "lat":55.77055,
        "lon":49.22088
    },
    {
        "lat":55.796932,
        "lon":37.537849
    }
]

Дополнительные параметры запроса

Имя поля
Формат
Описание
Пример
costing string

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

  • auto (по умолчанию) - автомобильный;
  • truck - грузовики;
  • pedestrian - пешеходный;
  • bicycle - велосипедный.
"costing":"pedestrian"
id string Идентификатор запроса, который возвращается вместе с ответом, что позволяет точно установить соответствие запроса и ответа
"id":"optimal_route_test"
costing_options dict

Список параметров расчёта маршрута. Для различных типов транспорта используются различные опции и ограничения, аналогичные тем, которые используются в сервисе Построение маршрута v.2

Дополнительно присутствует опция "shortest", по умолчанию выставленная в false. Если shortest=false, то маршрут оптимизируется по времени. Если shortest=true, то маршрут оптимизируется по расстоянию.

"costing_options":{
   "auto":{
      "shortest":true,
      "use_tolls":0
   }
}
units string

Единица измерения расстояния в ответе:

  • kilometers (по умолчанию) - километры;
  • miles - мили.
"units":"miles"
fix_destination bool

Флаг, указывающий на то, нужно ли фиксировать последнюю из перечисленных координат в locations в качестве финиша. Если fix_destination=true, то последняя из указанных локаций в ответе сервиса гарантированно будет являться точкой финиша. Если fix_destination=false, то последняя из указанных локаций может оказаться одной из промежуточных точек маршрута.

Значение по умолчанию: true.

"fix_destination":"false"

Ответ

Возвращаемый ответ соответствует структуре GeoJSON и содержит:

Имя поля
Формат
Описание
Пример
id string Идентификатор запроса, который возвращается вместе с ответом, что позволяет точно установить соответствие запроса и ответа
"id": "optimal_route_test"
trip object map

Информация о маршруте определяется параметрами:

  • locations - список точек маршрута, отсортированных для оптимального по времени прохождения маршрута;
  • legs - информация о полилинии маршрута (см. также: Декодирование полилинии);
  • summary - краткая информация о маршруте;
  • status_message - текстовая расшифровка статуса выполнения запроса;
  • status - статус выполнения запроса; 
  • units - единицы измерения;
  • language - язык, на котором представлена информация о маневрах.
{
   "trip":{
      "locations":[
         {
            "type":"break",
            "lat":43.1332,
            "lon":131.9113,
            "original_index":0
         },
         {
            "type":"break",
            "lat":50.266,
            "lon":127.5356,
            "original_index":1
         }
      ],
      "legs":[
         {
            "summary":{
               "min_lat":43.131777,
               "min_lon":127.535648,
               "max_lat":50.291427,
               "max_lon":132.040931,
               "time":58965.898,
               "length":1424.861,
               "cost":54399.585
            },
            "shape":"shape. In this example we skip it."
         }
      ],
      "summary":{
         "min_lat":43.131777,
         "min_lon":127.535648,
         "max_lat":50.291427,
         "max_lon":132.040931,
         "time":58965.898,
         "length":1424.861,
         "cost":54399.585
      },
      "status_message":"Found route between points",
      "status":0,
      "units":"kilometers",
      "language":"ru-RU"
   },
   "id":"my_route"
}

В случае, если по запросу ничего не найдено, ответ будет выглядеть как представлено ниже:

{"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"}' \

Ответ

{
    "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": "cuakiBmxc{|A@uPEiUHgkAF_n@BgYHghAPwvBFgr@XcrD@{ZBmGJupAG_SHw\\D}RNoaC`@cNfAyGxHaGja@Y~JmFxKyLlBuBfUy[pI_Ux@uBfNkb@rFwTvMgx@dBkKlD}SrFs]bFa`@pCgTdI{i@fC}R`@aD~PklAzBwObLqw@vIuf@lLop@p@oBrJuYfNmYbAwBtJwPfCuBxIkHzMqIh_@sRfCWb@}SqAu`@_GcfB_Bqh@yBmk@w@}M{D}}@qG}yAuBqZ|D_G~oCshAhQmAzWiRla@wYlbAw}@fCsFj{@ijBjWij@zZsp@fm@eqAdAgD`Ssn@dBqFNea@xVavAdZajBxEomA|AeeBhHiNbLcAnAuGpT|VlD~DpaBf|@vkA|q@|eBjOv`@b[tPwGzDtA`s@`_AtGUjo@{vAvUmm@iJyL"
        }],
        "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"
}