# 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](https://docs.mapbox.com/api/navigation/map-matching/). 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](https://docs.mapbox.com/cli/reference/#shared-parameters).

-   [`mapbox map-match`](#mapbox-map-match)

## `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:**

```sh
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"
```