Построение маршрута
Для построения маршрута необходимо указать 2 и более географических координат, между которыми будет построен оптимальный маршрут, с учетом пробок на дороге.
Пункты назначения#
Для построения маршрута необходимо указать координаты в качестве JSON-массива. Маршрут будет учитывать координаты в той очередности, в которой они указаны в теле запроса.
Для каждого местоположения необходимо указать долготу и широту. Для конвертации адресов в географические координаты используйте Geocoder API.
Также с помощью параметра type можно указать в каком режиме должен строиться маршрут (от адреса до адреса, проезд через место и т.д.).
| Параметр | Описание |
|---|---|
lat | Долгота |
lon | Широта |
type | Тип местоположения, один из вариантов: break - конечный адрес, through - промежуточный адрес |
heading | (опционально) Предпочтительное направление движения для старта с данного местоположения. Это может быть полезно для мобильной маршрутизации, когда транспортное средство движется в определенном направлении вдоль дороги, и маршрут должен начаться в этом направлении. Heading указывается в градусах от севера по часовой стрелке, где север - 0°, восток - 90°, юг - 180° и запад - 270°. |
По желанию вы можете включить следующую информацию о местоположении, не влияя на маршрутизацию. Эта информация передается в запросе и возвращается для вашего удобства.
name= Название места или организации. Название может использоваться в инструкциях, таких как "Вы прибыли к <НАЗВАНИЕ ЗАВЕДЕНИЯ>."city= Название города.state= Название области/региона.postal_code= Почтовый индекс.country= Название страны.phone= Номер телефона.url= URL с описанием места.side_of_street= (только в ответе) Сторона улицы, на которой будет находится желаемый пункт назначения. Доступные значения:leftиright.
Типы транспорта#
Маршрутизация СтарЛайн Карт поддерживает построение маршрута для разных видов транспорта. Для каждого типа транспорта будут работать свои ограничения и доступные параметры.
| Тип | Описание |
|---|---|
auto | Стандартный тип маршрута для легковых автомобилей |
bicycle | Тип маршрута для велосипедной езды. Велосипедные маршруты следуют по обычным дорогам при необходимости, но избегают дорог без доступа для велосипедов. |
truck | Специальный тип роутинга для грузового транспорта. Расчет маршрута для грузовых автомобилей наследует маршрут легковых, но проверяет наличие доступа для грузовых автомобилей, ограничения по ширине и высоте, а также весовые ограничения на дорогах. |
pedestrian | Режим навигации для пешеходов. В основном, пешеходные маршруты строятся по принципу кратчайшего расстояния с некоторыми исключениями: тротуары и пешеходные дорожки слегка предпочтительны, в то время как ступени или лестницы и переулки слегка избегаются. |
Общие параметры#
Данные параметры доступны в случаях, когда тип транспорта указан auto, bus или truck.
| Параметр | Описание |
|---|---|
use_ferry | Использовать переправы. Возможные значения от 0 до 1. Значения ближе к 0 будут сигналом избегать переправы, а значения ближе к 1 наоборот. |
use_tolls | Стоит ли использовать платные дороги. Доступные значения в интервале от 0 до 1. Значения ближе к 0 сигнализируют об избегании платных дорог, а значения ближе к 1 наоборот. |
top_speed | Максимальная скорость, с которой транспорт может двигаться. Используется для избегания дорог, где максимальная скорость выше скорости вашего транспорта. По умолчанию 140 км/ч. |
Грузовые маршруты#
Данные параметры доступны и учитываются только при построении маршрутов для грузового транспорта (truck)
| Параметр | Описание |
|---|---|
length | Длина грузового транспорта (в метрах). По умолчанию 21.64. |
weight | Вес грузового транспорта (в метрических тоннах). По умолчанию 21.77. |
axle_load | Нагрузка на ось (в метрических тоннах). По умолчанию 9.07. |
axle_count | Количество осей грузового транспорта. По умолчанию 5. |
hazmat | Признак того, что транспорт перевозит опасный груз. По умолчанию false. |
Общие параметры#
Общие параметры необходимо указать в самом начале JSON-объекта в запросе.
| Параметр | Описание |
|---|---|
units | Используемая метрическая система. Возможны мили (miles или mi) и километры (kilometers' или km`). По умолчанию используются километры |
alternates | Количество альтернативных маршрутов, которые будут предложены помимо основного. Максимальное значение - 10. |
Поддерживаемые языки для подсказок#
| Язык | Код языка | Описание |
|---|---|---|
en-US | en | English (Английский) |
ru-RU | ru | Russian (Русский) |
Содержимое ответа на запрос#
В ответ на запрос маршрута в ответе сервера будет содержаться JSON-документ со следующими полями:
| Поле | Описание |
|---|---|
code | Код статуса |
routes | Массив возможных маршрутов |
uuid | Уникальный идентификатор маршрута |
Пример сокращенного ответа:
{ "code": "Ok", "routes": [ { "distance": 8117.764, "duration": 2069.579, "geometry": "...iiyjqBign{x@~Gh{A`Bj^bApTj@rM~Bng@r...", "legs": [ { "distance": 8117.764, "duration": 2069.579, "steps": [ { "distance": 359, "duration": 83.291, "geometry": "iiyjqBign{x@~Gh{A`Bj^bApTj@rM~Bng@rAzYhB~`@xGnyAvAt[n@fN", "maneuver": { "bearing_after": 259, "bearing_before": 0, "instruction": "Двигайтесь на запад по улица Комиссара Смирнова.", "is_toll": false, "is_unpaved": false, "location": [ 30.350981, 59.962533 ], "type": "depart" }, "name": "улица Комиссара Смирнова", "speed_limits": [ 60, 60, 60, 60, 60, 60, 60 ] } ], "summary": "Финляндский проспект, Биржевая площадь", "via_waypoints": [ { "distance_from_start": 4895.597, "geometry_index": 190, "waypoint_index": 1 } ], "weight": 3641.75 } ], "use_toll": false, "use_unpaved": false, "weight": 3641.75, "weight_name": "auto" } ], "uuid": "82cac74b-1a77-4109-908e-ec772ca4d700"}Каждый маршрут содержит следующие параметры:
| Параметр | Описание |
|---|---|
distance | Общая протяженность маршрута в километрах |
duration | Общая продолжительность маршрута в секундах. Используя это значение, вы можете посчитать приблизительное время прибытия в пункт назначения |
geometry | Геометрия всего маршрута, закодированная с помощью google-esque polyline |
legs | Разбивка маршрута на сегменты и маневры |
use_toll | Индикатор того, что маршрут использует платные дороги |
use_unpaved | Индикатор того, что маршрут использует грунтовые дороги |
HTTP коды и условия#
Ниже приведены HTTP-коды ответов API и условия, при которых они могут вернуться. В основном API следует стандартной HTTP спецификации.
| HTTP код | Статус | Описание |
|---|---|---|
| 200 | your_trip_json | Маршрут успешно рассчитан |
| 400 | Failed to parse json request | Некорректный JSON в запросе |
| 400 | Failed to parse location | Некорректные координаты в запросе |
| 400 | Insufficiently specified required parameter 'locations' | Не был передан параметр locations |
| 400 | Insufficient number of locations provided | Необходимо передать минимум 2 координаты |
| 400 | Exceeded max route locations of X | Указано слишком большое количество координат |
| 400 | No suitable edges near location | В данной области построение маршрута пока невозможно |
| 405 | Try a POST or GET request instead | Поддерживаются только GET и POST запросы |