Pairs Directions API
Pairs Directions API позволяет просчитать несколько маршрутов за один вызов. Для каждого маршрута можно получить длину, время в пути и полную геометрию.
Каждый маршрут должен состоять из двух точек: отправления и прибытия. Поддерживаются пешеходные и автомобильные маршруты (в том числе с учётом пробок и полос общественного транспорта). Дополнительно можно указать параметры фильтрации дорог, чтобы, например, не прокладывать маршрут по грунтовым дорогам.
Получение ключа
Для доступа к API нужен специальный ключ. Чтобы его получить, заполните анкету по адресу dev.2gis.ru/order.
Пример использования
Чтобы получить информацию о маршрутах, нужно отправить POST-запрос на endpoint /get_pairs/1.0/{routing_type}
, где routing_type
- нужный тип маршрута:
- car - автомобильный маршрут;
- taxi - автомобильный маршрут, включающий полосы общественного транспорта;
- pedestrian - пешеходный маршрут.
В строке запроса укажите ваш ключ API в качестве значения параметра key
.
https://catalog.api.2gis.com/get_pairs/1.0/car?key=API_KEY
Координаты точек маршрута и другие параметры нужно передать в виде JSON.
В самом простом случае JSON может содержать три поля:
- points - массив маршрутов. Каждый объект в массиве должен содержать 4 поля: долгота и широта точки отправления (lon1 и lat1) и долгота и широта точки прибытия (lon2 и lat2).
- type - тип маршрута (оптимальный по времени с учетом пробок или кратчайший по расстоянию).
- output - формат результата (полный или упрощенный).
{
"points": [
{
"lon1": 82.933328,
"lat1": 55.102268,
"lon2": 82.958722,
"lat2": 55.032594
}
],
"type": "jam",
"output": "simple"
}
В таком виде запрос вернет краткую информацию об автомобильном маршруте с учетом текущих пробок, включающую длину маршрута в метрах (distance) и время в пути в секундах (duration).
[
{
"lon1": 82.933328,
"lat1": 55.102268,
"lon2": 82.958722,
"lat2": 55.032594,
"distance": 11146,
"duration": 1509,
"status": "OK"
}
]
Более сложный пример с получением полной информации о двух маршрутах и использованием двух опциональных полей: filters (какие дороги избегать при построении маршрута) и utc (Unix-время, которое будет использовано вместо текущего для определения состояния трафика).
{
"points": [
{
"lon1": 82.933328,
"lat1": 55.102268,
"lon2": 82.958722,
"lat2": 55.032594
},
{
"lon1": 82.92952,
"lat1": 55.079794,
"lon2": 82.907189,
"lat2": 54.981836
}
],
"type": "statistics",
"output": "full",
"filters": ["dirt_road"],
"utc": 1606826131
}
Запрос вернет не только длину и время в пути для каждого маршрута, но и геометрию маршрута (поле route в ответе). При построении маршрута будут проигнорированы грунтовые дороги ("filters": ["dirt_road"]
). Вместо текущей информации о пробках будет использована статистическая информация ("type": "statistics"
) на указанную дату ("utc": 1606826131
).
[
{
"lon1": 82.933328,
"lat1": 55.102268,
"lon2": 82.958722,
"lat2": 55.032594,
"distance": 11146,
"duration": 1509,
"route": {...},
"status": "OK"
},
{
"lon1": 82.92952,
"lat1": 55.079794,
"lon2": 82.907189,
"lat2": 54.981836,
"distance": 13712,
"duration": 1708,
"route": {...},
"status": "OK"
}
]
При построении маршрутов с типами statistics и jam основным приоритетом является минимизация времени в пути. Чтобы посчитать самый короткий маршрут между двумя точками, даже если он не является оптимальным по времени, нужно указать тип shortest. Прогнозируемое время в пути (поле duration) будет посчитано с учетом трафика при любом типе маршрута.
Подробную информацию о полях и возможные значения для каждого поля можно посмотреть в Справочнике API.