Map Matching API

📘

Please note the request might result multiple sub-traces. Large jumps in the timestamps (> 60s) or improbable transitions lead to trace splits if a complete matching could not be found. The algorithm might not be able to match all points. Outliers are removed if they can not be matched successfully.

Request

Request Format

❗️

Coordinate Order

When using our Routing APIs, the order of coordinates should be entered as longitude,latitude instead of the typical latitude,longitude format.

https://us1.locationiq.com/v1/matching/driving/{coordinates}?key=<YOUR_ACCESS_TOKEN>&steps={true|false}&geometries={polyline|polyline6|geojson}&overview={simplified|full|false}&annotations={true|false}

Optional Parameters

In addition to the general options the following options are supported for this service:

The radius for each point should be the standard error of the location measured in meters from the true location.
Use Location.getAccuracy() on Android or CLLocation.horizontalAccuracy on iOS.
This value is used to determine which points should be considered as candidates (larger radius means more candidates) and how likely each candidate is (larger radius means far-away candidates are penalized less).
The area to search is chosen such that the correct candidate should be considered 99.9% of the time.

Response

Response Example

{
  "code": "ok",
  "tracepoints": {
    "waypoint_index": 0,
    "matchings_index": 0,
    "alternatives_count": 0,
    "distance": 8.414822,
    "location": [
      -0.161136,
      51.523832
    ],
    "name": "Huntsworth Mews"
  },
  "matchings": {
    "duration": 109.3,
    "distance": 752.4,
    "weight": 109.3,
    "geometry": "}fnyHbn^|@_@O_BeDlAw@}G~@uB@WXs@fE}Ab@OxBpU",
    "confidence": 0,
    "weight_name": "routability",
    "legs": {
      "steps": [],
      "weight": 10.2,
      "distance": 36.7,
      "summary": "",
      "duration": 10.2
    }
  }
}

Response Parameters

• code if the request was successful Ok otherwise see the service dependent and general status codes.
• tracepoints: Array of Waypoint objects representing all points of the trace in order.
  If the trace point was omitted by map matching because it is an outlier, the entry will be null.
  Each Waypoint object has the following additional properties:
  • matchings_index: Index to the Route object in matchings the sub-trace was matched to.
  • waypoint_index: Index of the waypoint inside the matched route.
  • alternatives_count: Number of probable alternative matchings for this trace point. A value of zero indicate that this point was matched unambiguously. Split the trace at these points for incremental map matching.
• matchings: An array of Route objects that assemble the trace. Each Route object has the following additional properties:
  • confidence: Confidence of the matching. float value between 0 and 1. 1 is very confident that the matching is correct.

In case of error the following codes are supported in addition to the general ones:

All other properties might be undefined.