Add mapbox isochrone by mattpodwysocki · Pull Request #44 · mapbox/mapbox-cli

mattpodwysocki · 2026-09-23T22:33:13Z

⚠️ Temporarily based on #43, not main

This reuses the flattening mechanism (spec::FLATTENED_SERVICES),
ARG_NAME_OVERRIDES, and the path_segment_for/UNESCAPED_PATH_PARAMS
fix #43 introduces, since both APIs' profile path parameter hits the
same global-flag collision and the same free-form-profile requirement.
Once #43 merges, this should be retargeted to main (gh pr edit --base main) rather than reviewed against it as a diff. Everything below is
scoped to what this PR actually adds on top of #43.

What

mapbox isochrone, the second Navigation-category API with no prior CLI
coverage. Same shape as #43: hand-authored into custom-openapi/ since
openapi-specs publishes no spec for this API either.

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

How far you can get from a point in a given time or distance, for driving
(with or without live traffic), walking, or cycling, as GeoJSON polygons
or linestrings.

contours_minutes and contours_meters are mutually exclusive but neither
is individually required by this CLI's own validation, the same "not
enforced before the request goes out" precedent search category already
uses for its own proximity/near/bbox/route disjunction. The API answers 422
if both or neither are given.

Routing profile is free-form here too

Same fix as #43: 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 (("isochrone", "profile"))
rather than relying on the enum-implies-safe assumption that stopped
holding once the enum came off.

Also included

A fix for a --help regression found while writing this, in code #43
already merged into this branch: first_sentence() in src/main.rs cuts a
--help line at the first ., and eight parameter descriptions in
directions.yaml led with a complete sentence before the substantive
content (`mapbox/driving` only. etc.), eating everything after it.
isochrone.yaml's own denoise had the same shape (0.0-1.0: ...) and
would have rendered as literally 0. Fixed all nine by moving the
qualifier to the end of the description instead of the front. --schema
and docs/commands.md were never affected, since they show descriptions in
full.

Verification

Smoke-tested against production: real contour polygons and linestrings for
mapbox/driving and mapbox/walking, --polygons, and
--contours-minutes with multiple values, all verified to return the
documented GeoJSON shape, plus the bare mapbox isochrone command shape
itself (no subcommand accepted, --schema reflects the new name).

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

🤖 Generated with Claude Code

Third of the Navigation-category APIs with no prior CLI coverage. Same shape as directions/isochrone (#43, #44): 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 (third row, not a third mechanism). Excludes POST, for the same documented reason directions route does: this spec format can't express "GET or POST, caller's choice" for one operationId, and the API's own POST exists specifically for a trace too long for a URL (~8100 bytes) — a real gap, not a design choice. Smoke-tested against production: a three-point San Francisco trace returned a real match with legs/steps/geometry, including a null tracepoint for a point too far from the road network to match — the documented shape for that case, not a bug. 486 tests, fmt and clippy clean. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Second of the Navigation-category APIs with no prior CLI coverage. Same shape as mapbox directions route (#43): hand-authored into custom-openapi/ since openapi-specs has no spec for this API either, and reuses that PR's fix for a spec parameter named `profile` colliding with the global --profile flag (ARG_NAME_OVERRIDES gets a second row, not a second mechanism). `contours_minutes` and `contours_meters` are mutually exclusive but neither is individually required by this CLI's own validation — same "not enforced before the request goes out" precedent search category already uses for its own proximity/near/bbox/route disjunction. The API answers 422 if both or neither are given. Smoke-tested against production: real contour polygons and linestrings for driving and walking profiles, --polygons, --contours-minutes with multiple values, verified to return the documented GeoJSON shape. Also fixes a self-inflicted --help regression found while writing this: first_sentence() in src/main.rs cuts a --help line at the first '.', and several profile-scoped parameter descriptions in directions.yaml (already merged in this branch) led with a complete sentence before the substantive content, e.g. "`mapbox/driving` only." — eating everything after it in --help. isochrone.yaml's own `denoise` had the same shape ("0.0-1.0: ...") and would have rendered as literally "0". Both fixed by moving the qualifier to the end of the description instead of the front. 485 tests, fmt and clippy clean. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Cascades the fix already shipped on mapbox directions: isochrone's API also has exactly one operation, so mapbox isochrone <args> replaces mapbox isochrone contours <args>, the same shape mapbox usage already has (spec::FLATTENED_SERVICES). And isochrone's own profile path parameter had the same closed four-value enum, which would reject an OEM account's undocumented profiles client-side; it's now free-form and reaches the URL unescaped via UNESCAPED_PATH_PARAMS, same mechanism as directions. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Third of the Navigation-category APIs with no prior CLI coverage. Same shape as directions/isochrone (#43, #44): 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 (third row, not a third mechanism). Excludes POST, for the same documented reason directions route does: this spec format can't express "GET or POST, caller's choice" for one operationId, and the API's own POST exists specifically for a trace too long for a URL (~8100 bytes) — a real gap, not a design choice. Smoke-tested against production: a three-point San Francisco trace returned a real match with legs/steps/geometry, including a null tracepoint for a point too far from the road network to match — the documented shape for that case, not a bug. 486 tests, fmt and clippy clean. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

zmofei

A few parameter descriptions don't match the API docs (https://docs.mapbox.com/api/navigation/isochrone/), and denoise is reversed. Please fix these in both the YAML and docs/commands.md. Also, the "Also included" section of the PR description says this PR fixes eight directions.yaml descriptions, but that change is in #43 (cc7486d), not in this diff.

zmofei · 2026-10-07T09:08:23Z

+          # `0.0-1.0:` on its own left `--help` showing just `0`.
+          # `--schema` and `docs/commands.md` still show it in full.
+          description: >-
+            A smaller value removes more of the smaller contours, 0.0-1.0,


This is reversed. The docs say 1.0 keeps only the largest contour, so a higher value removes more. Also, first_sentence() still cuts at the . in 0.0, so --help shows "…the smaller contours, 0". Maybe "Drops contours smaller than this fraction of the largest one; 1 (the default) keeps only the largest. From 0 to 1."

zmofei · 2026-10-07T09:08:23Z

+          in: query
+          required: false
+          description: >-
+            Douglas-Peucker simplification tolerance in meters. A higher


The docs don't say a higher value makes the contour smaller, only coarser. Please drop "smaller".

zmofei · 2026-10-07T09:08:23Z

+          in: query
+          required: false
+          description: >-
+            Road types to route around, comma-separated. Options are


The docs say all five values work only with mapbox/driving and mapbox/driving-traffic. Worth saying so.

zmofei · 2026-10-07T09:08:23Z

+          in: query
+          required: false
+          description: >-
+            Departure time, ISO 8601 — for `mapbox/driving-traffic`, which


Nit: the Isochrone docs don't limit depart_at to mapbox/driving-traffic. They say the contours reflect traffic at that time, and it defaults to now.

zmofei · 2026-10-07T09:08:23Z

+polygons. This response is a real GeoJSON `FeatureCollection`, unlike
+`mapbox directions`'s response, but isochrone isn't one of the three
+services (`search`, `geocoder`, `tilequery`) this CLI has a bespoke
+list-per-feature rendering for yet (`output.rs`'s `list_rendering` is an


Nit: output.rs no longer exists. list_rendering is in src/output/render.rs.

mattpodwysocki requested a review from a team as a code owner September 23, 2026 22:33

This was referenced Sep 23, 2026

Add mapbox map-matching #45

Open

Add mapbox matrix #48

Open

Add mapbox feedback list/get #49

Merged

Add mapbox optimization submit/get/list #51

Closed

Add mapbox ev-charge-finder search/get/list-operators #52

Closed

Add mapbox places get/batch #53

Closed

mattpodwysocki force-pushed the feat/isochrone-api branch from bd00deb to 16e44ed Compare September 25, 2026 14:52

mattpodwysocki changed the title ~~Add mapbox isochrone contours~~ Add mapbox isochrone Sep 25, 2026

zmofei mentioned this pull request Oct 1, 2026

Add mapbox-cli-geospatial-patterns skill mapbox/mapbox-agent-skills#79

Open

zmofei mentioned this pull request Oct 5, 2026

Add Navigation API support: Directions, Matrix, and Isochrone #75

Open

mattpodwysocki force-pushed the feat/directions-api branch from 63629b3 to dfc6759 Compare October 6, 2026 13:55

mattpodwysocki and others added 2 commits October 6, 2026 09:57

mattpodwysocki force-pushed the feat/isochrone-api branch from 16e44ed to 17ae5e4 Compare October 6, 2026 13:58

zmofei requested changes Oct 7, 2026

View reviewed changes

Navigation Menu

Repository navigation

Add mapbox isochrone - #44

Add mapbox isochrone#44
mattpodwysocki wants to merge 2 commits into
feat/directions-apifrom
feat/isochrone-api

mattpodwysocki commented Sep 23, 2026 •

edited

Loading

Uh oh!

zmofei left a comment

Uh oh!

zmofei Oct 7, 2026

Uh oh!

zmofei Oct 7, 2026

Uh oh!

zmofei Oct 7, 2026

Uh oh!

zmofei Oct 7, 2026

Uh oh!

zmofei Oct 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

mattpodwysocki commented Sep 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ Temporarily based on #43, not main

What

Routing profile is free-form here too

Also included

Verification

Uh oh!

zmofei left a comment

Choose a reason for hiding this comment

Uh oh!

zmofei Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

zmofei Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

zmofei Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

zmofei Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

zmofei Oct 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mattpodwysocki commented Sep 23, 2026 •

edited

Loading