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.