Map Matching API

Matching API matches or snaps given GPS points to the road network in the most plausible way.

📘

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:

OptionValuesDescription
stepstrue, false (default)Returned route steps for each route
geometriespolyline (default), polyline6, geojsonReturned route geometry format (influences overview and per step)
annotationstrue, false (default), nodes, distance, duration, datasources, weight, speedReturns additional metadata for each coordinate along the route geometry.
overviewsimplified (default), full, falseAdd 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.
gapssplit (default), ignoreAllows the input track splitting based on huge timestamp gaps between points.
tidytrue, 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.
ParameterValues
timestampinteger seconds since UNIX epoch
radiusdouble >= 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:

TypeDescription
NoMatchNo matchings found.

All other properties might be undefined.