About Map Matching API

The Map Matching API returns the route and its details for a list of waypoints (width longitude / latitude coordinates). So, for example GPS tracks, can be matched to roads. The API is extremely useful for route analysis and visualization.

Request example

Map Matching API works via POST request that allows sending a massive amount of points in the request body.

HTTP Post request


POST https://api.geoapify.com/v1/mapmatching?apiKey=YOUR_API_KEY
HEADERS 'Content-Type: application/json'

Request body

{
  "mode": "drive",
  "waypoints": [
    {
      "timestamp": "2019-11-04T07:09:34.000Z",
      "location": [ 10.694703, 47.567028 ]
    },
    {
      "timestamp": "2019-11-04T07:09:45.000Z",
      "location": [ 10.6950319, 47.567783]
    },
    ...
  ]
}

Required parameters:

  • apiKey - your Geoapify key

Request body parameters:

  • mode - routing / transportation mode - 'drive', 'walk', 'bicycle'
  • waypoints - an ordered list of waypoints that contain location information and may contain timestamps and measured bearings

The response returned contains a GeoJSON FeatureCollection object that contain the route feature of MultiLineString type. The route feature properties contain information about route legs, steps and matched waypoints.

Difference with Routing API

Map Matching API is similar to Routing API - it accepts routing mode (drive, walk, bicycle) and generates a route that connects the points. Because of that, they share a very similar response format.

The top differences of Map Matching API, when compared to Routing API are:

  • accepts up to 1000 waypoints per one POST request
  • follows waypoints as close as possible, does not try to optimize the route
  • assumes that waypoints are not stops, but imprecise "via" location measurements (e.g GPS coordinates)
  • waypoints may have recorded timestamps and measured bearings (in degrees clockwise from the north)
  • waypoints can skipped, merged or interpolated if do not match the road network or if located too close to each other
  • if some intermediate points cannot be confidently connected using a road network, the resulting route may be split into several disconnected legs
  • by default does not return turn-by-turn instructions, assuming retrospective route matching and analysis
  • by default returns road attribution and details - including road class (e.g. "motorway"), number of lanes, speed limit, etc.