Skip to main content

Overview

Map Matching API allows you to build a car route by using a set of route points recorded by a vehicle. As a result, you will get a reconstructed route with corrected inaccuracies and imprecisions of the recording, which is tied to public roadways.

To reconstruct a route from the set of points, follow the requirements:

  • The vehicle is driven in a city or settlement on public roadways in compliance with driving regulations.
  • All the points are recorded sequentially and belong to one device and one trip.
  • The fixation time between nearby points is from 1 to 10 seconds.
  • Points are not located far from roads. If a point is significally far from the road graph, it may not be included in the route reconstruction.
  • The number of points in one request is from 2 to 1000. The recommended minimum number is 10.

If some of the requirements are not met, the request may result in an error or reduce the accuracy of the result.

Getting started​

To work with the API of the service, get an access key:

1. Get an access key​

To work with the API of the service, get an access key:

  1. Sign in to the Platform Manager.
  2. Create a demo key or purchase a subscription for using API. For details on service prices, see the Tariffs section.

To work with access keys, you can use the Platform Manager: for details, see the account documentation.

2. Send a request​

To reconstruct a route, send a POST request to the /map_matching/1.0.0 endpoint:

  1. In the query string, pass the API key value in the key parameter:

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

  2. In the request body, pass the JSON with a set of points:

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

Request example:

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

Where:

  • lon and lat (mandatory parameters) - coordinates of the route point (longitude and latitude)

  • utc (mandatory parameter) - date and time of the point recording in Unix time format

  • speed - movement speed at the point

  • azimuth - direction of movement at the point

  • bad_point_tolerance - level of tolerance for incorrect input points in the request. A point is considered incorrect if its recorded coordinates are more than 40 m away from the road graph (for example, due to GPS signal issues). Tolerance levels:

    • low - if at least one point is incorrect, the error is returned.
    • medium - the route reconstruction stops on the first incorrect point, and a partial result is returned.
    • high - the algorithm attempts to reconstruct the complete route, ignoring incorrect points, unless their removal violates the criteria of the algorithm (for example, the recording time between nearby points must not exceed 10 seconds).

Response example:

The response returns the reconstructed route:

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

Where:

  • distance - route length in meters
  • duration - travel time in seconds
  • edges and route - full route geometry
  • bad_input_points - indexes of points from the input array that were considered incorrect and were ignored.

For more information about the parameters, see the API Reference.

Tariffs​

  • The service fee is calculated based on the number of requests per month.
  • Current prices for services are available in the Platform Manager.

Deployment options​

  • Cloud-based: all Map Matching API methods are available through public 2GIS endpoints.
  • On-Premise: all Map Matching API methods are available when the 2GIS API Platform is installed in a private network. For more information, see the API Platform for server.