Навигация | Routes API | Обзор | 2GIS Documentation
Routes API

Routes API

Routes API позволяет построить комбинированный маршрут проезда на общественном транспорте и автомобиле.

В отличие от Public Transport API, Routes API соединяет получившиеся варианты проезда на общественном транспорте с точкой отправления или назначения не пешеходным маршрутом, а автомобильным (если остановка находится достаточно далеко).

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

Для доступа к API нужен специальный ключ. Чтобы его получить, заполните форму по адресу dev.2gis.ru/order.

Чтобы проложить маршрут, нужно отправить POST-запрос на endpoint /combo_routes/2.0. В строке запроса укажите ваш ключ API в качестве значения параметра key.

https://catalog.api.2gis.com/combo_routes/2.0?key=YOUR_KEY

Координаты точек маршрута и виды общественного транспорта нужно передать в виде JSON в теле запроса.

Например, чтобы получить варианты комбинированного проезда из точки A в точку B с использованием автобуса или трамвая, можно отправить следующий запрос:

curl --request POST \
 --url 'https://catalog.api.2gis.com/combo_routes/2.0?key=API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
  "enable_schedule": true,
  "locale": "ru",
  "source": {
    "name": "A",
    "point": {
      "lat": 55.74791305339228,
      "lon": 37.664326671417626
    }
  },
  "target": {
    "name": "B",
    "point": {
      "lat": 55.65143816549758,
      "lon": 37.559748347634866
    }
  },
  "transport": [
    "bus",
    "trolleybus",
    "tram",
    "shuttle_bus",
    "metro",
    "suburban_train",
    "funicular_railway",
    "monorail",
    "cable_car",
    "aeroexpress",
    "mcd",
    "mcc"
]
}'

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

Полный список поддерживаемых видов транспорта можно посмотреть в Справочнике API.

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

[
    {
        "id": "1",
        "route_id": "123",
        "total_duration": 1772,
        "transfer_count": 0,
        "crossing_count": 0,
        "pedestrian": false,
        "total_walkway_distance": "on foot 19 min",
        "transport": ["bus"],
        "schedules": [...],
        "schedules_events": [...],
        "movements": [...],
    }
]

Общее время в пути в секундах для варианта проезда указано в поле ответа total_duration. Продолжительность пешеходной части указана в виде локализованной строки в поле total_walkway_distance.

"total_duration": 1772, // общее время в пути составляет около 29 минут
"total_walkway_distance": "on foot 19 min" // из них 19 минут - пешеходный маршрут

В одном варианте проезда может использоваться несколько видов транспорта (в случае пересадок или если один участок маршрута можно проехать на разных видах транспорта). Все используемые виды транспорта перечислены в поле transport.

"transport": [
    "bus", // автобус
    "trolleybus", // троллейбус
    "tram", // трамвай
    "shuttle_bus" // маршрутное такси
]

Количество пересадок, используемых во варианте проезда, указано в двух полях:

  • transfer_count - количество пересадок без перехода на другую платформу (остановку);
  • crossing_count - количество пересадок, для которых нужно перейти на другую платформу.
"transfer_count": 1, // количество пересадок в рамках одной платформы
"crossing_count": 0 // количество переходов с одной платформы на другую

Каждый вариант проезда разделен на несколько перемещений (участков маршрута). Список перемещений указан в поле movements.

Например, комбинированный маршрут с использованием пригородного поезда без дополнительных пересадок будет состоять из пяти перемещений:

  1. Проехать на автомобиле до станции пригородного поезда.
  2. Выйти из автомобиля и дойти до станции.
  3. Проехать на поезде несколько остановок.
  4. Пройти пешком до точки назначения.
  5. Дополнительное перемещение, содержащее только координаты точки назначения.

Тип перемещения (проезд на общественном транспорте, пересадка или автомобильный/пешеходный участок маршрута) указан в поле type. Поле waypoint содержит координаты или название начальной точки перемещения, длину автомобильного/пешеходного участка маршрута и название вида транспорта.

"movements": [
    {
        "id": "1",
        "type": "driving", // автомобильный участок маршрута
        "auto": {
          "distance": 100, // длина участка маршрута в метрах
          "geometry": "POINT 3.123 4.515"
        }
    },
    {
        "id": "2",
        "type": "walkway", // пешеходный участок маршрута
        "geometry": {
            "selection": "LINESTRING(37.642032 55.750778, ...",
            "z_first": 0,
            "z_last": 0
        },
        "waypoint": {
            "comment": "290 m on foot", // пройти 290 метров...
            "name": "36,149328 51,734588"
        }
    },
    {
        "id": "3",
        "platforms": {...},
        "routes": [...],
        "type": "passage", // проезд на общественном транспорте
        "geometry": {
            "selection": "LINESTRING(37.642032 55.750778, ...",
            "z_first": 0,
            "z_last": 0
        },
        "waypoint": {
            "subtype": "train", // вид транспорта
            "name": "Аэродромная", // название посадочной остановки
            "combined": true
        }
    }
]

Для транспортных участков маршрута будут указаны дополнительные поля routes, platforms и metro (в случае метро).

Поле routes содержит список всех транспортных маршрутов, которые можно использовать для прохождения текущего участка. Например, если текущий участок можно проехать на автобусах №26 и №41 или на маршрутном такси №206, поле routes будет выглядеть следующим образом:

"routes": [
    {
        "names": ["26", "41"], // номера маршрутов
        "subtype": "bus", // название вида транспорта
        "subtype_name": "bus" // локализованное название вида транспорта
    },
    {
        "names": ["206"],
        "subtype": "shuttle_bus",
        "subtype_name": "shuttle bus"
    }
]

Поле platforms содержит названия всех промежуточных остановок маршрута, т.е. остановок после посадочной и перед остановкой высадки. Последняя остановка в списке - та, после которой нужно выйти.

"platforms": {
    "names": [
        "Бойцов 9 Дивизии",
        "Большевиков (автобус)",
        "Магазин Колос",
        "50 лет Октября",
        "Павлуновского",
        "Кинотеатр им.Щепкина"
    ]
}

Если участок маршрута можно проехать на метро, в поле metro будет указана информация о линии метро (название, цвет), рекомендованный номер вагона для посадки, подсказки по направлению движения и выходу из метро и другая информация. Полный список полей можно посмотреть в Справочнике API.