Map Matching API

The Mapbox Map Matching API snaps fuzzy, inaccurate traces from a GPS unit or a phone to the OpenStreetMap road and path network using the Directions API. This produces clean paths that can be displayed on a map or used for other analysis.

Retrieve a match

Return a path on the road and path network that is closest to the input traces.

You can further refine the results from this endpoint with the following optional parameters:

Some pre-processing tips to achieve the best results:

• Timestamps improve the quality of the matching and are highly recommended.
• The Map Matching API is limited to processing traces with up to 100 coordinates. If you need to process longer traces, you can split the trace and make multiple requests.
• Clusters of points (like a person waiting at a train crossing for a few minutes) often don't add more information to a trace and can negatively impact map-matching quality. We recommend that you tidy the trace (remove clusters and provide a uniform sample rate). You can use the tidy=true query parameter or pre-process your traces with external tools like geojson-tidy.
• Map matching works best with a sample rate of 5 seconds between points. If your trace has a higher sample rate, you may want to downsample your trace.
• With the waypoints parameter specified, traces that would normally return with sub-matches will error. We recommend tidying traces before using them with the waypoints parameter.

Example request: Retrieve a match

# Basic request that returns a match object with route legs between each waypoint

$ curl "https://api.mapbox.com/matching/v5/mapbox/driving/-117.17282,32.71204;-117.17288,32.71225;-117.17293,32.71244;-117.17292,32.71256;-117.17298,32.712603;-117.17314,32.71259;-117.17334,32.71254?access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Request to access speed limit information using the maxspeed annotation

$ curl "https://api.mapbox.com/matching/v5/mapbox/driving/-122.39636,37.79129;-122.39732,37.79283;-122.39606,37.79349?annotations=maxspeed&overview=full&geometries=geojson&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Request with the approaches parameter set to 'curb' for each waypoint

$ curl "https://api.mapbox.com/matching/v5/mapbox/driving/-117.17282,32.71204;-117.17288,32.71225;-117.17293,32.71244;-117.17292,32.71256?approaches=curb;curb;curb;curb&access_token=YOUR_MAPBOX_ACCESS_TOKEN"


# Request with various parameters, returns a match object with one route leg between the first and last waypoints

$ curl "https://api.mapbox.com/matching/v5/mapbox/driving/2.344003,48.85805;2.34675,48.85727;2.34868,48.85936;2.34955,48.86084;2.34955,48.86088;2.34962,48.86102;2.34982,48.86125?steps=true&tidy=true&waypoints=0;6&waypoint_names=Home;Work&banner_instructions=true&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Request with openlr encoded string as coordinates used `tomtom` specification, return the same response the same as for regular coordinates

$ curl "https://api.mapbox.com/matching/v5/mapbox/driving/CwOiYCUMoBNWAv9P%2F%2BMSBg%3D%3D?openlr_spec=tomtom&openlr_format=tomtom&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

# Request with openlr encoded string as coordinates used `here` specification

$ curl "https://api.mapbox.com/matching/v5/mapbox/driving/Cwe2%2BiJmURNhMPlvCBAbbAAA?openlr_spec=here&access_token=YOUR_MAPBOX_ACCESS_TOKEN"

Supported libraries: Retrieve a match

Mapbox wrapper libraries help you integrate Mapbox APIs into your existing application. The following SDKs support this endpoint:

• Mapbox Directions for Swift
• Mapbox Java SDK
• Mapbox JavaScript SDK

See the SDK documentation for details and examples of how to use the relevant methods to query this endpoint.

Response: Retrieve a match

The match response object contains one or more match objects, as well as one or more tracepoint objects.

With clean matches, only one match object is returned. When the algorithm cannot decide the correct match between two points, it will omit that line and return several sub-matches as match objects. The higher the number of sub-match match objects, the more likely it is that the input traces are poorly aligned to the road network.

Example response: Retrieve a match

{
  "matchings": [{
    "confidence": 4.615758886217236e-10,
    "geometry": {
      "coordinates": [
        [
          -122.397484,
          37.792809
        ],
        [
          -122.39746,
          37.792693
        ],
        [
          -122.39745,
          37.792645
        ],
        [
          -122.397437,
          37.792586
        ],
        [
          -122.397431,
          37.792558
        ],
        [
          -122.39741,
          37.792466
        ],
        [
          -122.397404,
          37.79244
        ],
        [
          -122.397225,
          37.792579
        ],
        [
          -122.396623,
          37.793057
        ],
        [
          -122.39636,
          37.793276
        ],
        [
          -122.396075,
          37.793502
        ]
      ],
      "type": "LineString"
    },
    "legs": [{
      "annotation": {
        "maxspeed": [{
            "speed": 48,
            "unit": "km/h"
          },
          {
            "speed": 48,
            "unit": "km/h"
          },
          {
            "speed": 48,
            "unit": "km/h"
          },
          {
            "speed": 48,
            "unit": "km/h"
          },
          {
            "speed": 48,
            "unit": "km/h"
          },
          {
            "speed": 48,
            "unit": "km/h"
          },
          {
            "unknown": true
          },
          {
            "unknown": true
          },
          {
            "unknown": true
          },
          {
            "unknown": true
          }
        ]
      },
      "summary": "",
      "weight": 153.6,
      "duration": 73.6,
      "steps": [],
      "distance": 207.8
    }],
    "weight_name": "routability",
    "weight": 153.6,
    "duration": 73.6,
    "distance": 207.8
  }],
  "tracepoints": [
    null,
    {
      "alternatives_count": 0,
      "waypoint_index": 0,
      "matchings_index": 0,
      "distance": 14.635568381812668,
      "name": "Davis Street",
      "location": [
        -122.397484,
        37.792809
      ],
      "maxspeed": {
        "speed": 48,
        "unit": "km/h"
      }
    },
    {
      "alternatives_count": 1,
      "waypoint_index": 1,
      "matchings_index": 0,
      "distance": 1.8762601659793365,
      "name": "Market Street",
      "location": [
        -122.396075,
        37.793502
      ],
      "maxspeed": {
        "unknown": true
      }
    }
  ],
  "code": "Ok"
}

Use HTTP POST to retrieve a match

The Map Matching API also supports access using the HTTP POST method. HTTP POST should be used for large requests, since the Map Matching API has a size limit of approximately 8100 bytes on GET request URLs. POST requests are still subject to your account's request size limits.

Learn more about this process in the Using HTTP POST section.

Match object

A match object is a route object with an additional confidence field:

Example match object

{
    "confidence": 0.9548844020537051,
    "distance": 103.7,
    "duration": 16.4,
    "geometry": "gatfEfidjUi@Le@@Y?E??J?^Hf@",
    "legs": []
}

Tracepoint object

A tracepoint object is a waypoint object with three additional fields: matchings_index, waypoint_index, and alternatives_count.

Example tracepoint object

{
    "waypoint_index": 0,
    "location": [-117.172836, 32.71204],
    "name": "North Harbor Drive",
    "matchings_index": 0,
    "alternatives_count": 0
}

Map Matching API errors

On error, the server responds with different HTTP status codes:

• For responses with HTTP status codes lower than 500, the JSON response body includes the code property, which may be used by client programs to manage control flow. The response body may also include a message property, with a human-readable explanation of the error.
• If a server error occurs, the HTTP status code will be 500 or higher and the response will not include a code property.

Map Matching API restrictions and limits

• The Map Matching API is limited to 300 requests per minute.
• Each regular request can have a maximum of 100 coordinates.
• Each OpenLR request can have a maximum of 50 coordinates.
• Results must be displayed on a Mapbox map using one of the Mapbox libraries or SDKs.

Map Matching API pricing

Usage of the Map Matching API is measured in API requests. A request that contains multiple waypoints is billed as a single API request. Details about the number of Map Matching API requests included in the free tier and the cost per request beyond what is included in the free tier are available on the pricing page.