Map Matching API
Map Matching API позволяет построить автомобильный маршрут из набора точек, записанных транспортным средством. Результатом является восстановленный маршрут с исправленными неточностями и погрешностями записи, привязанный к автомобильным дорогам общего пользования.
Чтобы успешно восстановить маршрут из набора точек, нужно соблюсти несколько условий:
- транспортное средство должно двигаться в городе или населённом пункте по дорогам общего пользования с соблюдением ПДД;
- все точки должны быть записаны последовательно, принадлежать одному устройству и одной поездке;
- время фиксации между соседними точками должно быть от 1 до 10 секунд;
- расстояние между соседними точками должно быть не более 30 метров;
- количество точек в одном запросе должно быть от 2 до 1000, рекомендуемое минимальное количество точек 10.
Несоблюдение этих условий приведёт к ошибке или ухудшит точность результата.
Получение ключа доступа
Чтобы работать с API сервиса, нужно получить ключ доступа:
- Зарегистрируйтесь в личном кабинете Platform Manager.
- Создайте демо-ключ или купите ключ для доступа к API: см. инструкцию Ключи доступа.
Работать с ключами можно в личном кабинете Platform Manager: подробнее см. в разделе Platform Manager.
Пример запроса
Чтобы восстановить маршрут, нужно отправить POST-запрос на endpoint /map_matching/1.0.0
. В строке запроса укажите ваш ключ API в качестве значения параметра key
.
https://routing.api.2gis.com/map_matching/1.0.0?key=API_KEY
Набор точек для восстановления маршрута нужно передать в виде JSON в теле запроса.
Для каждой точки нужно указать несколько параметров:
lon
иlat
- географические координаты точки.utc
- дата и время записи точки. Указывается как Unix-время.speed
- скорость движения в точке (опциональный параметр).azimuth
- направления движения в точке (опциональный параметр).
curl --request POST \
--url 'https://routing.api.2gis.com/map_matching/1.0.0?key=API_KEY' \
--header 'Content-Type: application/json' \
--data '{
"query": [
{
"lon": 82.914948,
"lat": 55.051097,
"utc": 1623878771,
"speed": 41,
"azimuth": 171
},
{
"lon": 82.914914,
"lat": 55.051196,
"utc": 1623878773,
"speed": 42,
"azimuth": 171
},
{
"lon": 82.914885,
"lat": 55.051289,
"utc": 1623878775,
"speed": 43.3,
"azimuth": 171
},
{
"lon": 82.914866,
"lat": 55.051404,
"utc": 1623878776,
"speed": 42,
"azimuth": 171
}
]
}'
Пример ответа
Запрос вернёт объект, включающий длину маршрута в метрах (distance
), время в пути в секундах (duration
), а также полную геометрию маршрута (edges
и route
). Информацию о каждом поле можно посмотреть в Справочнике API.
{
"distance": 60.354,
"duration": 5,
"edges": [
{
"distance": 96.268,
"edge_id": 282909495821411,
"geometry": "LINESTRING(82.914962 55.05097,82.914834 55.05146)"
}
],
"query": [
{
"azimuth": 171,
"edge_id": 282909495821411,
"lat": 55.051097,
"lat_matched": 55.051095,
"lon": 82.914948,
"lon_matched": 82.914929,
"speed": 41.0,
"utc": 1623878771
},
{
"azimuth": 171,
"edge_id": 282909495821411,
"lat": 55.051196,
"lat_matched": 55.051195,
"lon": 82.914914,
"lon_matched": 82.914903,
"speed": 42.0,
"utc": 1623878773
},
{
"azimuth": 171,
"edge_id": 282909495821411,
"lat": 55.051289,
"lat_matched": 55.051288,
"lon": 82.914885,
"lon_matched": 82.914879,
"speed": 43.3,
"utc": 1623878775
},
{
"azimuth": 171,
"edge_id": 282909495821411,
"lat": 55.051404,
"lat_matched": 55.051403,
"lon": 82.914866,
"lon_matched": 82.914849,
"speed": 42.0,
"utc": 1623878776
}
],
"route": "LINESTRING(82.914929 55.051095,82.914849 55.051403)",
"status": "OK"
}