Map Matching API

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

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

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

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

Получение ключа

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

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

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

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

Пример запроса

Чтобы восстановить маршрут, нужно отправить 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"
}