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
  • 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.

Usage of this API requires an API key. To obtain the key:

  1. Sign in to the Platform Manager.
  2. Create a demo key (if you have not used Urbi products before) or request a production key: follow the link to contact a manager on the API Keys tab.

In the Platform Manager, you can also:

  • See information on your current keys: which services are enabled, which limit is set for each, when a key will be deactivated, and more.
  • Set restrictions for a key by HTTP headers or by IP and subnet.
  • Check the statistics of request distribution for each key.

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

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