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
• the number of route points in one request must be from 2 to 1000, the recommended minimum number of points is 10.

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

Getting an access key

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

1. Sign in to the Platform Manager.
2. Create a demo key or purchase an access key for using API: see the Access keys instruction.

To work with access keys, you can use the Platform Manager: see the Platform Manager section.

Request example

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://routing.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 (optional)
• azimuth - direction of movement at the route point (optional)

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

Response example

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