Обзор

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

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

Транспортное средство движется в городе или населённом пункте по дорогам общего пользования с соблюдением ПДД.
Все точки записаны последовательно, принадлежат одному устройству и одной поездке.
Время фиксации между соседними точками — от 1 до 10 секунд.
Точки не расположены далеко от дорог. Если точка существенно удалена от дорожного графа, она может быть не учтена при восстановлении маршрута.
Количество точек в одном запросе — от 2 до 1000. Рекомендуемое минимальное количество — 10.

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

Начало работы

1. Получите ключ доступа

Чтобы работать с API сервиса, получите ключ доступа:

Зарегистрируйтесь в личном кабинете Менеджер Платформы.
Создайте демо-ключ или купите подписку для доступа к API. Подробнее о стоимости сервиса см. в разделе Тарифы.

Работать с ключами можно в Менеджере Платформы: подробнее см. в документации личного кабинета.

2. Отправьте запрос

Чтобы восстановить маршрут, отправьте POST-запрос на endpoint /map_matching/1.0.0:

В строке запроса укажите ваш ключ API в качестве значения параметра key:
```
https://routing.api.2gis.com/map_matching/1.0.0?key=API_KEY
```

В теле запроса передайте JSON с набором точек:

{
  "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
      }
  ]
}

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

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
        }
    ]
}'

Где:

lon и lat (обязательные параметры) — координаты точки (долгота и широта).
utc (обязательный параметр) — дата и время записи точки в формате Unix-времени.
speed — скорость движения в точке.
azimuth — направление движения в точке.

Пример ответа:

Запрос вернёт восстановленный маршрут:

{
    "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"
}

Где:

distance — длина маршрута в метрах.
duration — время в пути в секундах.
edges и route — полная геометрия маршрута.

Подробнее о параметрах см. в Справочнике API.

Тарифы

Стоимость сервиса рассчитывается исходя из количества запросов в месяц.
Актуальные тарифы можно посмотреть в Менеджере Платформы, в блоке Базовые сервисы.

Варианты размещения

Облако: все методы Map Matching API доступны через публичные endpoint-ы 2ГИС.
On-Premise: все методы Map Matching API доступны при установке API-платформы 2ГИС в закрытом контуре. Подробнее см. в разделе API-платформа для сервера.

Начало работы​

1. Получите ключ доступа​

2. Отправьте запрос​

Тарифы​

Варианты размещения​

Начало работы

1. Получите ключ доступа

2. Отправьте запрос

Тарифы

Варианты размещения