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

Map Matching API

Map Matching API позволяет построить автомобильный маршрут из набора точек, записанных транспортным средством. Результатом является восстановленный маршрут с исправленными неточностями и погрешностями записи, привязанный к автомобильным дорогам общего пользования.

Чтобы успешно восстановить маршрут из набора точек, нужно соблюсти несколько условий:

  • транспортное средство должно двигаться в городе или населённом пункте по дорогам общего пользования с соблюдением ПДД;
  • все точки должны быть записаны последовательно, принадлежать одному устройству и одной поездке;
  • время фиксации между соседними точками должно быть от 1 до 10 секунд;
  • расстояние между соседними точками должно быть не более 30 метров;
  • количество точек в одном запросе не должно превышать 1000.

Несоблюдение этих условий приведёт к ошибке или ухудшит точность результата.

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

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

https://catalog.api.2gis.com/map_matching/1.0.0?key=API_KEY

Набор точек для восстановления маршрута нужно передать в виде JSON в теле запроса.

Для каждой точки нужно указать несколько параметров:

  • lon и lat - географические координаты точки.
  • utc - дата и время записи точки. Указывается как Unix-время.
  • speed - скорость движения в точке.
  • azimuth - направления движения в точке.
curl --request POST \
 --url `https://catalog.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"
}