How to use the Map Matching API

If you’ve collected data with a GPS unit, either through a fitness device, mobile phone or dedicated GPS unit, chances are good that it doesn’t line up perfectly with other data. The Map Matching API allows you to correct the GPS traces against a common base map, OpenStreetMap.

Be sure to read the Map Matching API documentation to learn more.

Prepping your data

You will need to convert your data to JSON. If you have KML or GPX files, you can use toGeoJSON to easily convert from one file type to another.

After the data is in a GeoJSON format, you may need to preprocess the data in order to get GeoJSON linestring features. The body JSON is one GeoJSON feature with a LineString geometry. The LineString may have up to 100 positions.

This is what the Map Matching API expects. The data does not need coordTimes but it helps to have them.

{
  "type": "Feature",
  "properties": {
    "coordTimes": [
      "2015-04-21T06:00:00Z",
      "2015-04-21T06:00:05Z",
      "2015-04-21T06:00:10Z",
      "2015-04-21T06:00:15Z",
      "2015-04-21T06:00:20Z"
    ]
    },
  "geometry": {
    "type": "LineString",
    "coordinates": [
      [ 13.418946862220764, 52.50055852688439 ],
      [ 13.419011235237122, 52.50113000479732 ],
      [ 13.419756889343262, 52.50171780290061 ],
      [ 13.419885635375975, 52.50237416816131 ],
      [ 13.420631289482117, 52.50294888790448 ]
    ]
  }
}

Request using curl

In this case, we are sending our file as trace.json.

This can be put into your command line or terminal from within the same directory using curl:

curl -X POST \
  --header "Content-Type:application/json" \
  -d @trace.json \
  "https://api.mapbox.com/matching/v4/mapbox.driving.json?access_token=<your token here>"

The response is returned as a GeoJSON Feature Collection. Each feature includes a confidence value which is a number between 0 and 1, with 0 being very low confidence and 1 being very high confidence. More information about the response format can be found in the documentation.

{
  "code": "Ok",
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "confidence": 0.81655043187186,
        "matchedPoints": [
          [
            13.418805122375,
            52.500598907471
          ],
          [
            13.419145584106,
            52.501094818115
          ],
          [
            13.419618606567,
            52.501750946045
          ],
          [
            13.420042037964,
            52.502334594727
          ],
          [
            13.42049407959,
            52.502983093262
          ]
        ],
        "indices": [
          0,
          1,
          2,
          3,
          4
        ]
      },
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [
            13.418805,
            52.500599
          ],
          [
            13.418851,
            52.500659
          ],
          [
            13.419121,
            52.501057
          ],
          [
            13.419146,
            52.501095
          ],
          [
            13.419276,
            52.501286
          ],
          [
            13.419446,
            52.501518
          ],
          [
            13.419619,
            52.501753
          ],
          [
            13.419981,
            52.502249
          ],
          [
            13.420042,
            52.502335
          ],
          [
            13.420494,
            52.502984
          ]
        ]
      }
    }
  ]
}

If there are any errors, possible explanations can be found in the documentation.

Results

Before Map Matching trace

After Map Matching tracenew

Be sure to show us the cool things you make by tweeting @Mapbox.

Additional questions? Ask our support team or learn more about How Mapbox Works.