Navigation | Map Matching API | Overview | 2GIS Documentation

Map Matching API

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 successfully reconstruct a route from the set of route points, the following conditions must be met:

  • the vehicle must be driven in a city or town on public roadways in compliance with driving regulations
  • all the points must be recorded sequentially and must belong to one device and one trip
  • the fixation time between nearby points must be from 1 to 10 seconds
  • the distance between nearby points must not be more than 30 meters
  • one request must not contain more than 1000 route points

If some of these conditions are not met, the request may result in an error or return a significantly less accurate route.

Usage of this API requires an API key. To obtain the key, fill out the form at dev.2gis.com/order.

To reconstruct a route, send a POST request to the /map_matching/1.0.0 endpoint. Specify your API key as the key parameter in the query string.

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

Coordinates for the route and other parameters must be sent as a JSON string in the request body.

For each route point, specify the following parameters:

  • lon and lat - geographical coordinates of the route point
  • utc - date and time of the recording specified as Unix time
  • speed - movement speed at the route point
  • azimuth - direction of movement at the route point
curl --request POST \
 --url `https://catalog.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
        }
    ]
}'

The response will return an object containing route length in meters (distance), travel time in seconds (duration), and complete geometry of the route (edges and route). You can find information about each field in API Reference.

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