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

Public Transport API

Public Transport API позволяет построить маршрут проезда на общественном транспорте.

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

Для доступа к API нужен специальный ключ. Чтобы его получить:

  1. Зарегистрируйтесь в личном кабинете Platform Manager.
  2. Создайте демо-ключ (если вы еще не пользовались продуктами 2ГИС) или запросите боевой ключ по ссылке для связи с менеджером на вкладке Ключи API.

В личном кабинете вы также можете:

  • Просматривать информацию по своим уже созданным ключам: какие сервисы подключены, какой лимит задан по каждому из них, когда ключ будет деактивирован.
  • Задавать ограничения на ключ по HTTP-заголовкам или по IP и подсетям.
  • Изучать статистику распределения запросов по каждому ключу.

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

https://routing.api.2gis.com/public_transport/2.0?key=YOUR_KEY

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

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

curl --request POST \
 --url 'https://routing.api.2gis.com/public_transport/2.0?key=API_KEY' \
 --header 'Content-Type: application/json' \
 --data '{
	"locale": "ru",
	"source":
	{
		"name": "Point A",
		"point":
		{
			"lat": 51.734588,
			"lon": 36.149328
		}
	},
	"target":
	{
		"name": "Point B",
		"point":
		{
			"lat": 51.734183,
			"lon": 36.176865
		}
	},
	"transport": ["bus", "tram"]
}'

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

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

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

[
    {
        "id": "1",
        "total_duration": 1772,
        "transfer_count": 0,
        "crossing_count": 0,
        "pedestrian": false,
        "total_walkway_distance": "on foot 19 min",
        "transport": ["bus"],
        "waypoints": [
            {
                "combined": true,
                "routes_names": ["26", "41", "58а", "95", "99"],
                "subtype": "bus"
            }
        ],
        "movements": [...]
    }
]

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

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

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

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

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

Список возможных транспортных маршрутов для каждого вида транспорта указан в поле waypoints:

"waypoints": [
    {
        // номера автобусов
        "routes_names": ["26", "41", "58а", "95", "99"],
        "subtype": "bus",
        "combined": true
    },
    {
        // номера маршрутных такси
        "routes_names": ["206", "226", "227", "228", "277", "278", "287"],
        "subtype": "shuttle_bus",
        "combined": true
    }
]

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

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

Если маршрут полностью пешеходный, то поле pedestrian будет содержать значение true.

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

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

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

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

"movements": [
    {
        "alternatives": [...],
        "id": "2",
        "moving_duration": 208, // время движения по участку маршрута
        "type": "walkway", // пешеходный участок маршрута
        "waiting_duration": 0, // для пеших перемещений время ожидания всегда равно нулю
        "waypoint": {
            "subtype": "start", // начальное движение
            "comment": "пешком 290 м", // пройти 290 метров...
            "name": "36,149328 51,734588" // ...от точки отправления
        }
    },
    {
        "alternatives": [...],
        "id": "3",
        "moving_duration": 412, // время движения по участку маршрута
        "platforms": {...},
        "routes": [...],
        "type": "passage", // проезд на транспорте
        "waiting_duration": 90, // время ожидания транспорта
        "waypoint": {
            "subtype": "bus", // вид транспорта
            "name": "Аэродромная", // название посадочной остановки
            "combined": true
        }
    },
    {
        "alternatives": [...],
        "id": "21",
        "moving_duration": 860,
        "type": "walkway",
        "waiting_duration": 0,
        "waypoint": {
            "subtype": "pedestrian",
            "comment": "пешком 1,2 км", // пройти 1.3 километра...
            "name": "Центральный рынок" // ...от указанной остановки
        }
    },
    {
        "id": "22",
        "moving_duration": 0,
        "type": "walkway",
        "waiting_duration": 0,
        "waypoint": {
            "subtype": "finish", // конечное движение
            "comment": "Вы на месте!",
            "name": "36,176865 51,734183" // координаты точки назначения
        }
    }
]

Для транспортных участков маршрута будут указаны дополнительные поля 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.

Геометрию участка маршрута в формате WKT можно получить с помощью поля alternatives.

В общем случае геометрия указана в поле alternatives.geometry в виде линии или набора линий (LINESTRING).

"alternatives": [
    {
        "geometry": [
            {
                "selection": "LINESTRING(36.149328 51.734588, 36.149343 51.734574, ...)",
                "z_first": 0,
                "z_last": 0
            }
        ]
    }
]

В случае проезда на транспорте, в поле alternatives.platforms также будут указаны координаты остановок (POINT).

"alternatives": [
    {
        "geometry": [
            {
                "selection": "LINESTRING(36.153062 51.735441, 36.154328 51.733844, ...)",
                "z_first": 0,
                "z_last": 0
            }
        ],
        "platforms": [
            {
                "geometry": "POINT(36.153062 51.735441)",
                "id": 5
            },
            {
                "geometry": "POINT(36.155369 51.731910)",
                "id": 6
            },
            {
                "geometry": "POINT(36.185592 51.727166)",
                "id": 12
            }
        ]
    }
]