Skip to content

Add mapbox matrix - #48

Open
mattpodwysocki wants to merge 1 commit into
feat/map-matching-apifrom
feat/matrix-api
Open

mattpodwysocki wants to merge 1 commit into
feat/map-matching-apifrom
feat/matrix-api

Conversation

@mattpodwysocki

@mattpodwysocki mattpodwysocki commented Sep 24, 2026 •

Copy link
Copy Markdown
Contributor

⚠️ Temporarily based on #45, not main

Same stacking situation as #44 on #43 and #45 on #44. This reuses the
flattening mechanism (spec::FLATTENED_SERVICES), ARG_NAME_OVERRIDES,
and the path_segment_for/UNESCAPED_PATH_PARAMS fix #43 introduces,
since every one of these Navigation APIs' profile path parameter hits
the same global-flag collision and needs the same free-form profile. Once
#43/#44/#45 merge in order, this should be retargeted to main (gh pr edit --base main). Everything below is scoped to what this PR actually
adds on top of #45.

What

mapbox matrix, the fourth Navigation-category API with no prior CLI
coverage. Same shape as #43/#44/#45: hand-authored into custom-openapi/
since openapi-specs publishes no spec for it either.

No subcommand: like mapbox directions, mapbox isochrone, and mapbox map-matching, this API has one operation, so there's nothing a second
word (the old compute) would disambiguate. Same shape mapbox usage
already has.

Travel time and/or distance between every pair in a set of up to 25
coordinates, in one call. An N×N table, useful for ranking or filtering
many candidates by reachability before committing to a route through any
of them (as opposed to mapbox directions, a route through fixed stops in
order).

Routing profile is free-form here too

Same fix as #43, #44, and #45: an earlier version of this command
validated profile against the four documented values client-side, via a
clap enum. Some OEM accounts have additional profiles that aren't
published, so that validation would have broken this command for exactly
the accounts that most need it. profile is now sent exactly as typed,
and reaches the URL unescaped through UNESCAPED_PATH_PARAMS
(("matrix", "profile")).

A real discrepancy found and documented, not just worked around

--sources/--destinations take semicolon-separated indices, not comma,
confirmed by testing, not assumed. A comma-separated list gets a 422 from
the live API ("may be \"all\" or semicolon-separated list of 0-based integer indices"), which is the opposite of most other index/value lists
on this CLI's Navigation commands. Documented in the spec's own
description and in docs/commands.md, called out explicitly rather than
left as a surprise for the next person to hit.

Also fixes a --help truncation on --fallback-speed ("Legacy." as a
leading sentence, same class of bug fixed in directions.yaml earlier),
by moving the qualifier to the end of the description.

Verification

Smoke-tested against production: a full 3x3 matrix and a subsetted 1x2
matrix via --sources/--destinations, both verified to return the
documented shape, plus the bare mapbox matrix command shape itself (no
subcommand accepted, --schema reflects the new name).

490 tests, cargo fmt --check and cargo clippy --all-targets -- -D warnings both clean.

🤖 Generated with Claude Code

Fourth of the Navigation-category APIs with no prior CLI coverage. Same
shape as directions/isochrone/map-matching: hand-authored into
custom-openapi/ since openapi-specs has no spec for this API either,
reusing ARG_NAME_OVERRIDES for the same profile-vs-global-flag collision
(fourth row, not a fourth mechanism).

Named `compute` rather than the API-naming doc's proposed `get`, matching
the precedent set by the three commands before it (route/contours/match) —
this returns a matrix computed fresh from the request, not a stored
resource.

Verified a real discrepancy against production while testing: the API
answers a comma-separated --sources/--destinations list with a 422
("may be \"all\" or semicolon-separated list of 0-based integer indices"),
unlike this CLI's own convention elsewhere of comma-separating index lists.
Documented in the spec and in --help, not just discovered and left as a
surprise.

Also fixes a --help truncation on --fallback-speed ("Legacy." as a leading
sentence, same class of bug as directions.yaml's earlier ones) by moving
the qualifier to the end of the description.

Smoke-tested against production: a full 3x3 matrix and a subsetted 1x2
matrix via --sources/--destinations, both verified to return the
documented shape.

487 tests, fmt and clippy clean.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant