Map Match
Snaps a noisy GPS trace to the road network and returns the route it most
likely followed, for driving (with or without live traffic), walking, or
cycling, from the
Map Matching API.
Only the API's GET form is exposed, so a trace too long to fit in a URL
(about 8,100 bytes) won't work. The command also takes the common flags
— --username/-u, --token/-t, --profile, --id — described in
Shared parameters.
mapbox map-match
One or more matched routes — more than one where the trace is ambiguous
enough to split — each with a confidence the API assigns, plus one
tracepoint per input coordinate (null for a coordinate too far from any
road to match).
Parameters:
| Parameter | Description |
|---|---|
<routing-profile> | Required. mapbox/driving-traffic (accounts for live traffic), mapbox/driving, mapbox/walking, or mapbox/cycling. Sent as typed rather than checked against a list, since some accounts have additional profiles of their own. |
<coordinates> | Required. 2-100 {longitude},{latitude} trace points, semicolon-separated, or an OpenLR-encoded string of up to 50 points (pair it with --openlr-spec and --openlr-format). |
--annotations | Segment-level metadata per leg, comma-separated: distance, duration, speed, congestion and congestion_numeric (both mapbox/driving-traffic only), maxspeed (mapbox/driving and mapbox/driving-traffic only). Requires --overview full. |
--approaches | Which side of the road to approach each waypoint from, semicolon-separated: unrestricted or curb per coordinate. Requires --steps. |
--geometries | Route geometry format. Defaults to polyline. Values: geojson, polyline, polyline6. |
--overview | How much geometry detail the response carries. Defaults to simplified. Values: full, simplified, false. |
--radiuses | Maximum distance in meters, 0-50, each coordinate may snap to the road network, semicolon-separated. Defaults to 5. |
--steps | Return turn-by-turn instructions. Several parameters below only take effect with this set. |
--banner-instructions | Return banner objects for display. Requires --steps. |
--language | The language of turn-by-turn instructions. Defaults to en. Requires --steps. |
--roundabout-exits | Separate instructions for entering and exiting a roundabout. Requires --steps. |
--voice-instructions | Return SSML-marked-up voice guidance text. Requires --steps. |
--voice-units | Units for voice instructions. Requires --steps and --voice-instructions. Values: imperial, british_imperial, metric. |
--tidy | Remove clusters and resample the trace before matching, for a trace recorded at an inconsistent sample rate. |
--timestamps | A Unix timestamp per coordinate, semicolon-separated and ascending: when the trace was recorded, rather than assuming even spacing. |
--waypoint-names | A name per waypoint, semicolon-separated, used in its arrival instruction instead of the road name. Requires --steps. |
--waypoints | Zero-based indices of the coordinates that get their own arrival instruction, semicolon-separated. Must include 0 and the last index. Most useful with --steps, but doesn't require it. |
--ignore | Restrictions to ignore while matching, comma-separated: access, oneways, restrictions. mapbox/driving only. |
--linear-references | Return an OpenLR reference (base64) per matched leg alongside the ordinary geometry. mapbox/driving and mapbox/driving-traffic only. |
--openlr-spec | Which OpenLR specification <coordinates> is encoded with, when it's an OpenLR string. Defaults to tomtom. Values: tomtom, here. |
--openlr-format | The OpenLR binary format <coordinates> is encoded in, when it's an OpenLR string. Values: tomtom. |
--depart-at | Departure time from the first coordinate, as YYYY-MM-DDThh:mm, YYYY-MM-DDThh:mm:ssZ, or YYYY-MM-DDThh:mm:ss±hh:mm. Other ISO 8601 forms are rejected by the API. |
Examples:
mapbox map-match mapbox/driving "-122.42,37.78;-122.421,37.781;-122.422,37.782"
mapbox map-match mapbox/driving "-122.42,37.78;-122.421,37.781;-122.422,37.782" \
--steps --geometries geojson
mapbox map-match mapbox/walking "-122.42,37.78;-122.421,37.781;-122.422,37.782" \
--tidy --timestamps "1700000000;1700000010;1700000020"
Was this page helpful?