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 typicallatitude,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:
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 successfulOk
otherwise see the service dependent and general status codes.tracepoints
: Array ofWaypoint
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 benull
.
EachWaypoint
object has the following additional properties:matchings_index
: Index to theRoute
object inmatchings
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 ofRoute
objects that assemble the trace. EachRoute
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 code
s are supported in addition to the general ones:
Type | Description |
---|---|
NoMatch | No matchings found. |
All other properties might be undefined.
Updated 4 months ago