Перейти к основному содержимому

Обзор

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

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

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

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

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

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

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

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

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

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

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

  1. В строке запроса укажите ваш ключ API в качестве значения параметра key:

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

  2. В теле запроса передайте 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
        }
    ],
    "bad_point_tolerance": "low"
}'

Где:

  • lon и lat (обязательные параметры) — координаты точки (долгота и широта).

  • utc (обязательный параметр) — дата и время записи точки в формате Unix-времени.

  • speed — скорость движения в точке.

  • azimuth — направление движения в точке.

  • 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)"
        }
    ],
    "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 — длина маршрута в метрах.
  • duration — время в пути в секундах.
  • edges и route — полная геометрия маршрута.
  • bad_input_points — индексы точек из входного массива в запросе, которые оказались некорректными и были проигнорированы.

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

Тарифы​

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

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

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