Обзор

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

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

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

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

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

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

Зарегистрируйтесь в личном кабинете Менеджер Платформы.
Создайте демо-ключ или купите подписку для доступа к 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
      }
  ],
  "bad_point_tolerance": "low"
}

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

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
        }
    ],
    "need_speed_limits": true,
    "bad_point_tolerance": "low"
}'

Где:

lon и lat (обязательные параметры) — координаты точки (долгота и широта).
utc (обязательный параметр) — дата и время записи точки в формате Unix-времени.
speed — скорость движения в точке.
azimuth — направление движения в точке.
need_speed_limits: true — получение информации об ограничениях скорости на участках маршрута.
search_radius — радиус поиска узлов графа для заданной GPS-точки, в метрах. Допустимый диапазон — от 1 до 1000 м, по умолчанию — 40 м.
bad_point_tolerance — уровень «терпимости» к некорректным входным точкам в запросе. Точка считается некорректной, если её записанные координаты оказались удалены от дорожного графа на более чем 40 м (например, из-за проблем с GPS-сигналом). Уровни «терпимости»:
- low — если хотя бы одна точка в запросе некорректна, возвращается ошибка.
- medium — реконструкция маршрута останавливается на первой некорректной точке, возвращается частичный результат.
- high — сервис пытается реконструировать полный маршрут, игнорируя некорректные точки, если только их игнорирование не нарушает критерии алгоритма (например, время фиксации между соседними точками не должно превышать 10 секунд).

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

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

{
    "distance": 60.354,
    "duration": 5,
    "edges": [
        {
            "distance": 96.268,
            "edge_id": 282909495821411,
            "geometry": "LINESTRING(82.914962 55.05097,82.914834 55.05146)",
            "speed_limit": 60,
            "speed_limits": [
                {
                    "end_offset": 96.268,
                    "speed_limit": 60,
                    "start_offset": 0.0
                }
            ]
        }
    ],
    "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,
            "query_point_idx": 0
        },
        {
            "azimuth": 171,
            "edge_id": 282909495821411,
            "lat": 55.051196,
            "lat_matched": 55.051195,
            "lon": 82.914914,
            "lon_matched": 82.914903,
            "speed": 42.0,
            "utc": 1623878773,
            "query_point_idx": 1
        },
        {
            "azimuth": 171,
            "edge_id": 282909495821411,
            "lat": 55.051289,
            "lat_matched": 55.051288,
            "lon": 82.914885,
            "lon_matched": 82.914879,
            "speed": 43.3,
            "utc": 1623878775,
            "query_point_idx": 2
        },
        {
            "azimuth": 171,
            "edge_id": 282909495821411,
            "lat": 55.051404,
            "lat_matched": 55.051403,
            "lon": 82.914866,
            "lon_matched": 82.914849,
            "speed": 42.0,
            "utc": 1623878776,
            "query_point_idx": 3
        }
    ],
    "bad_input_points": [],
    "route": "LINESTRING(82.914929 55.051095,82.914849 55.051403)",
    "status": "OK"
}

Где:

distance — длина маршрута в метрах.
speed_limit — ограничение скорости на участке маршрута. Если на участке несколько ограничений (см. speed_limits), это среднее значение по длине отрезков. Возвращается при need_speed_limits: true.
speed_limits — детализация ограничений скорости на участке по отрезкам. start_offset и end_offset — отступы в метрах от начала участка, между которыми действует указанное ограничение. Возвращается при need_speed_limits: true.
duration — время в пути в секундах.
edges и route — полная геометрия маршрута.
bad_input_points — индексы точек из входного массива в запросе, которые оказались некорректными и были проигнорированы.

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

Тарифы и лимиты

Стоимость сервиса рассчитывается исходя из количества успешных запросов в месяц.
Для демо-ключей и ключей, созданных в рамках подписки, действуют лимиты на использование сервиса.
Актуальную стоимость и лимиты см. в инструкции Тарифы.

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

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

Помощь

Если у вас возникли вопросы при работе с API, задайте их AI-ассистенту (в правом нижнем углу сайта), воспользуйтесь поиском по документации или отправьте электронное письмо на api@2gis.ru.
Если вы хотите обсудить возможности API или его интеграцию с вашим продуктом, обратитесь к менеджеру.

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

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

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

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

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

Тарифы и лимиты​

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

Помощь​