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

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:

Option	Values	Description
steps	`true`, `false` (default)	Returned route steps for each route
geometries	`polyline` (default), `polyline6`, `geojson`	Returned route geometry format (influences overview and per step)
annotations	`true`, `false` (default), `nodes`, `distance`, `duration`, `datasources`, `weight`, `speed`	Returns additional metadata for each coordinate along the route geometry.
overview	`simplified` (default), `full`, `false`	Add overview geometry either full, simplified according to highest zoom level it could be display on, or not at all.
timestamps	`{timestamp};{timestamp}[;{timestamp} ...]`	Timestamps for the input locations in seconds since UNIX epoch. Timestamps need to be monotonically increasing.
radiuses	`{radius};{radius}[;{radius} ...]`	Standard deviation of GPS precision used for map matching. If applicable use GPS accuracy.
gaps	`split` (default), `ignore`	Allows the input track splitting based on huge timestamp gaps between points.
tidy	`true`, `false` (default)	Allows the input track modification to obtain better matching quality for noisy tracks.
waypoints	`{index};{index};{index}...`	Treats input coordinates indicated by given indices as waypoints in returned Match object. Default is to treat all input coordinates as waypoints.

Parameter	Values
timestamp	`integer` seconds since UNIX epoch
radius	`double >= 0` (default 5m)

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:

Type	Description
`NoMatch`	No matchings found.

All other properties might be undefined.