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

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

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

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

Where:

• distance - route length in meters
• duration - travel time in seconds
• edges and route - full route geometry

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

Tariffs

• The service fee is calculated based on the number of requests per month.
• To find out the current prices for services, contact the 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.