mapbox · mattpodwysocki · Sep 24, 2026
@@ -19,6 +19,19 @@ that may never merge. They are not releases and are not listed here.
 
 ## Unreleased
 
+- `mapbox matrix`, travel time and/or distance between every pair in a set
+  of up to 25 coordinates in one call, for driving (with or without live
+  traffic), walking, or cycling. No subcommand: like `mapbox directions`
+  below, this API has one operation, so there's nothing a second word (the
+  old `compute`) would disambiguate; see `spec::FLATTENED_SERVICES`.
+  Hand-authored into `custom-openapi/` for the same reason the other
+  Navigation commands were: no upstream spec exists yet. Reuses the
+  `profile`-vs-`--profile` collision fix (`ARG_NAME_OVERRIDES` gets a
+  fourth row) and the free-form (not `enum`) routing profile, for the same
+  OEM-account reason. `--sources`/`--destinations` take
+  semicolon-separated indices, not comma; verified against production
+  after the API answered a comma-separated list with a 422.
+
 - `mapbox map-matching`, snapping a noisy GPS trace to the road network and
   returning the route it most likely followed, for driving (with or
   without live traffic), walking, or cycling. No subcommand: like `mapbox

@@ -177,10 +177,11 @@ mapbox styles *
 mapbox tilesets *
 ```
 
-`mapbox directions`, `mapbox isochrone`, and `mapbox map-matching` are the
-exceptions: each API has a single operation, so there's a bare command
-with no subcommand at all, the same shape `mapbox usage` already has, see
-[docs/commands.md](./docs/commands.md) for their own parameters.
+`mapbox directions`, `mapbox isochrone`, `mapbox map-matching`, and `mapbox
+matrix` are the exceptions: each API has a single operation, so there's a
+bare command with no subcommand at all, the same shape `mapbox usage`
+already has, see [docs/commands.md](./docs/commands.md) for their own
+parameters.
 
 A command group is not the same thing as a spec file: which one an operation
 belongs to is decided per operation. So `sprites` and `tilesets` are each

@@ -0,0 +1,165 @@
+openapi: "3.0.0"
+# `parse_spec` turns `info.description` below into this service's clap
+# `long_about`, so it also reaches `mapbox matrix --help`, `--schema` and
+# `generate-skills` output. Keep it to API prose only — the provenance below
+# is for whoever edits this file, not for a CLI user:
+#
+# Hand-authored down to the parameters documented at
+# docs.mapbox.com/api/navigation/matrix. See `custom-openapi/README.md` for
+# how a file like this is wired in, and `directions.yaml`'s header for why
+# `profile` needs `ARG_NAME_OVERRIDES` in `src/spec.rs` — the same reason
+# applies here.
+info:
+  title: "Mapbox Matrix API"
+  description: >-
+    Travel time and distance between every pair in a set of up to 25
+    coordinates, in one call — for driving (with or without live traffic),
+    walking, or cycling.
+  version: "0.0.0"
+servers:
+  - url: https://api.mapbox.com
+    description: Matrix API
+paths:
+  /directions-matrix/v1/{profile}/{coordinates}:
+    get:
+      operationId: compute
+      summary: A travel time/distance matrix across a set of coordinates.
+      description: >-
+        Returns a `durations` and/or `distances` matrix in row-major order —
+        `durations[i][j]` is the time from the ith source to the jth
+        destination — across every source/destination pair. Defaults to
+        every coordinate as both a source and a destination (a full N×N
+        matrix); `--sources`/`--destinations` narrow either side to a
+        subset. Answers "which of these is reachable soonest", not a route
+        through all of them. See `mapbox directions` for a route through
+        fixed stops in order.
+      parameters:
+        - name: "profile"
+          in: path
+          required: true
+          # Not an `enum`: the four documented values are what's public, but
+          # not what's exhaustive. Some customers (OEM agreements, mainly)
+          # have additional profiles never published to docs.mapbox.com.
+          # An `enum` here becomes a clap `PossibleValuesParser` that
+          # rejects anything else client-side, which would break this CLI
+          # for exactly the accounts that most need a routing profile
+          # named beyond `driving`/`walking`/`cycling`. Same fix as
+          # `directions.yaml`'s `profile`.
+          description: >-
+            The routing profile. `mapbox/driving-traffic` (accounts for
+            live traffic, caps at 10 coordinates instead of 25),
+            `mapbox/driving`, `mapbox/walking`, and `mapbox/cycling` are
+            documented, but not necessarily exhaustive: some accounts have
+            additional profiles of their own. Sent exactly as typed, the
+            API is the authority on whether a value is valid, not this
+            description.
+          schema:
+            type: string
+            minLength: 1
+          example: "mapbox/driving"
+        - name: "coordinates"
+          in: path
+          required: true
+          description: >-
+            2-25 coordinates, semicolon-separated, each
+            `{longitude},{latitude}` — 10 max for `mapbox/driving-traffic`.
+          schema:
+            type: string
+            minLength: 1
+          example: "-122.42,37.78;-122.45,37.91;-122.41,37.80"
+        - name: "access_token"
+          in: query
+          required: true
+          description: "Mapbox API Access Token"
+          schema:
+            type: string
+            minLength: 1
+        - name: "annotations"
+          in: query
+          required: false
+          description: >-
+            Which matrix or matrices to return, comma-separated. Options
+            are `duration` (the default) and `distance` — both together
+            returns both matrices.
+          schema:
+            type: string
+          example: "duration,distance"
+        - name: "approaches"
+          in: query
+          required: false
+          description: >-
+            Which side of the road to approach each coordinate from,
+            semicolon-separated — `unrestricted` or `curb` per coordinate.
+          schema:
+            type: string
+        - name: "bearings"
+          in: query
+          required: false
+          description: >-
+            `{angle},{degrees}` per coordinate, semicolon-separated,
+            filtering the road segments considered by direction of travel.
+          schema:
+            type: string
+        - name: "sources"
+          in: query
+          required: false
+          description: >-
+            Which coordinates act as sources (matrix rows) — `all`
+            (the default), or zero-based indices, semicolon-separated.
+            Verified against production: a comma-separated list is a 422,
+            "may be \"all\" or semicolon-separated list of 0-based integer
+            indices" — unlike every other index/value list on this CLI's
+            Navigation commands, which are comma- or semicolon-separated
+            per parameter but never comma where this API wants semicolons.
+          schema:
+            type: string
+          example: "0;2"
+        - name: "destinations"
+          in: query
+          required: false
+          description: >-
+            Which coordinates act as destinations (matrix columns) — `all`
+            (the default), or zero-based indices, semicolon-separated. See
+            `sources` above — comma-separated is a 422 here specifically.
+          schema:
+            type: string
+          example: "1;3"
+        - name: "fallback_speed"
+          in: query
+          required: false
+          # Content before "Legacy", not after: `first_sentence` in
+          # `src/main.rs` cuts a `--help` line at the first `.`, and
+          # "Legacy." on its own left `--help` showing just that word.
+          # `--schema` and `docs/commands.md` still show it in full.
+          description: >-
+            Replaces a `null` (unreachable) cell with a straight-line
+            estimate at this speed, km/h, rather than leaving it `null`.
+            Legacy.
+          schema:
+            type: integer
+            minimum: 1
+        - name: "depart_at"
+          in: query
+          required: false
+          description: >-
+            Departure time, ISO 8601, for future traffic conditions and
+            time-dependent road restrictions.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: >-
+            A JSON object with a `code`, a `durations` and/or `distances`
+            matrix (row-major, seconds and meters respectively — `null` for
+            an unreachable pair), and the snapped `sources`/`destinations`
+            waypoints.
+        "401":
+          description: Unauthorized
+        "403":
+          description: Forbidden
+        "404":
+          description: Not Found — an invalid profile.
+        "422":
+          description: >-
+            Unprocessable Entity — invalid input, or more coordinates than
+            the profile allows.
@@ -85,6 +85,8 @@ nests, and is typed `mapbox styles draft get`.
 
 **[Map Matching](#map-matching)** — [map-matching](#mapbox-map-matching)
 
+**[Matrix](#matrix)** — [matrix](#mapbox-matrix)
+
 **[Search](#search)** — [search.forward](#mapbox-search-forward) ·
 [search.reverse](#mapbox-search-reverse) ·
 [search.category](#mapbox-search-category) ·
@@ -1449,12 +1451,114 @@ enough off the road network to leave its tracepoint `null`.
 </td></tr>
 </table>
 
-Like `directions route`, neither output mode has a bespoke rendering for
+Like `mapbox directions`, neither output mode has a bespoke rendering for
 this response — it isn't GeoJSON at the top level — so both print the same
 JSON, `-o text` pretty-printed and `-o json` on one line. Trimmed to one
 matching and dropped `admins`/`via_waypoints`/`alternatives_count`/`uuid`
 for length; the real response carries them too.
 
+---
+## Matrix
+
+Travel time and distance between every pair in a set of up to 25
+coordinates, in one call, for driving (with or without live traffic),
+walking, or cycling. Curated by hand down to the parameters documented at
+docs.mapbox.com/api/navigation/matrix — see `custom-openapi/README.md` for
+why this command group doesn't come from the vendored specs the way most
+others do.
+
+**vs. `mapbox directions`**: this answers "how far/long between every pair",
+not a route through all of them in order — `mapbox directions` is a route
+through fixed stops; this is an N×N table, useful for ranking or filtering
+many candidates by reachability before committing to a route through any of
+them.
+
+### `mapbox matrix`
+
+A `durations` and/or `distances` matrix in row-major order —
+`durations[i][j]` is the time from the ith source to the jth destination —
+across every source/destination pair, or a subset of either side. No
+subcommand: this API has one operation, so there's nothing a second word
+would disambiguate, the same reason `mapbox directions` has none either.
+
+#### Parameters
+
+`<routing-profile>` and `<coordinates>` (both positional) are required.
+`<routing-profile>` is sent exactly as typed, not checked against a fixed
+list: `mapbox/driving-traffic`, `mapbox/driving`, `mapbox/walking` and
+`mapbox/cycling` are documented, but some accounts (OEM agreements, mainly)
+have additional profiles of their own that were never published, the API
+is the authority on whether a value is valid, not this page.
+`<coordinates>` is 2-25 `{longitude},{latitude}` pairs, semicolon-separated,
+10 max for `mapbox/driving-traffic`.
+
+| Parameter | Effect |
+| --- | --- |
+| `--annotations <duration\|distance>` | Which matrix or matrices to return, comma-separated. `duration` alone is the default; both together returns both. |
+| `--approaches <unrestricted\|curb;...>` | Which side of the road to approach each coordinate from. |
+| `--bearings <angle,degrees;...>` | Filter road segments by direction of travel, one entry per coordinate. |
+| `--sources <indices>` | Which coordinates are matrix rows — `all` (the default) or zero-based indices, **semicolon**-separated. Verified against production: comma-separated is a 422 here, unlike most other index lists on these commands. |
+| `--destinations <indices>` | Which coordinates are matrix columns — same rules as `--sources`. |
+| `--fallback-speed <km/h>` | Replaces a `null` (unreachable) cell with a straight-line estimate at this speed, rather than leaving it `null`. Legacy. |
+| `--depart-at <ISO 8601>` | For future traffic conditions and time-dependent road restrictions. |
+
+#### Examples
+
+```sh
+mapbox matrix mapbox/driving "-122.42,37.78;-122.45,37.91;-122.41,37.80"
+mapbox matrix mapbox/driving "-122.42,37.78;-122.45,37.91;-122.41,37.80" \
+  --sources 0 --destinations "1;2"
+```
+
+#### Outputs
+
+Captured live: a full 3×3 matrix between three San Francisco points, both
+`durations` (seconds) and `distances` (meters).
+
+<table>
+<tr><th width="50%">Terminal — <code>-o text</code></th><th width="50%">Agent — <code>-o json</code></th></tr>
+<tr><td>
+
+```json
+{
+  "code": "Ok",
+  "durations": [
+    [0, 2381.5, 790.1],
+    [2593.8, 0, 2272.5],
+    [994.8, 2269.7, 0]
+  ],
+  "distances": [
+    [0, 25766, 3348.3],
+    [26960.4, 0, 25382],
+    [3781.3, 25174.1, 0]
+  ],
+  "sources": [
+    { "name": "Van Ness Avenue", "location": [-122.420122, 37.779978] },
+    { "name": "Playa Verde", "location": [-122.461997, 37.89621] },
+    { "name": "Columbus Avenue", "location": [-122.409926, 37.800067] }
+  ],
+  "destinations": [
+    { "name": "Van Ness Avenue", "location": [-122.420122, 37.779978] },
+    { "name": "Playa Verde", "location": [-122.461997, 37.89621] },
+    { "name": "Columbus Avenue", "location": [-122.409926, 37.800067] }
+  ]
+}
+```
+
+</td><td>
+
+```json
+{"code":"Ok","durations":[[0,2381.5,790.1],[2593.8,0,2272.5],[994.8,2269.7,0]],"distances":[[0,25766,3348.3],[26960.4,0,25382],[3781.3,25174.1,0]],"sources":[{"name":"Van Ness Avenue","location":[-122.420122,37.779978]},{"name":"Playa Verde","location":[-122.461997,37.89621]},{"name":"Columbus Avenue","location":[-122.409926,37.800067]}],"destinations":[{"name":"Van Ness Avenue","location":[-122.420122,37.779978]},{"name":"Playa Verde","location":[-122.461997,37.89621]},{"name":"Columbus Avenue","location":[-122.409926,37.800067]}]}
+```
+
+</td></tr>
+</table>
+
+Neither output mode has a bespoke rendering for this response, same as
+`mapbox directions` and `mapbox map-matching` — both print the same JSON,
+`-o text` pretty-printed and `-o json` on one line. Dropped each waypoint's
+own snap `distance` for length; the real response carries it too.
+
 ---
 
 ## Search

@@ -92,6 +92,7 @@ const SERVICE_DOCS: &[(&str, &str)] = &[
         "map-matching",
         "https://docs.mapbox.com/api/navigation/map-matching/",
     ),
+    ("matrix", "https://docs.mapbox.com/api/navigation/matrix/"),
     ("search", "https://docs.mapbox.com/api/search/search-box/"),
     // Static Images and Static Tiles merged into one `static` command group
     // (#116); neither upstream page covers both, so this points at Static