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.

Fixed in review

denoise's description was backwards: it said a smaller value removes
more of the smaller contours, when the real API works the other way (a
larger value is more aggressive — 1.0 keeps only the largest contour,
0.5 drops anything under half its area), confirmed against
docs.mapbox.com/api/navigation/isochrone/. Also rewrote it to avoid a
second bug while I was in there: 0.0-1.0/1.0 still has a literal .
that first_sentence() truncates on no matter where in the sentence it
sits, so the "move the qualifier to the end" fix the directions PR (Add mapbox directions route #43)
used for its own eight descriptions doesn't actually fix this one —
confirmed live, --help rendered "...smaller contours, 0". Spelled as
"0 to 1"/"1" instead.
polygons's description implied every contour becomes a polygon; the
real API only does that for a contour that forms a ring, and says so
now.

(The eight directions.yaml description fixes mentioned in earlier review
are #43's own commit, inherited through this branch's stack — not
something this PR adds.)

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).

Full suite, cargo fmt --check and cargo clippy --all-targets -- -D warnings all 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>

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."

Fixed, and confirmed the direction against docs.mapbox.com directly: a larger value is more aggressive (1.0 keeps only the largest contour, 0.5 drops anything under half its area). Also fixed the truncation bug you caught — spelled the bound as "0 to 1"/"1" instead of "0.0-1.0"/"1.0" so first_sentence() has no "." to cut on before the end.

Fixed, it was backwards. Now: "A larger value removes more of the smaller contours, 0 to 1, defaulting to 1. A value of 1 returns only the largest contour for each level; 0.5 drops any contour under half the largest's area." Spelled "0 to 1"/"1" instead of "0.0-1.0"/"1.0" because first_sentence() in src/main.rs cuts --help text at the first literal "." anywhere in the string, not just at the start, so a decimal bound further into the sentence was truncating the help text too. Left a comment explaining this so it doesn't get undone later.

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".

Dropped "smaller" — confirmed the docs only say coarser.

Dropped "smaller", thanks. Now just "A higher value gives a coarser contour."

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.

Confirmed against docs.mapbox.com and added: all five are scoped to mapbox/driving and mapbox/driving-traffic.

Added the driving/driving-traffic scoping: "all five only available for mapbox/driving and mapbox/driving-traffic."

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.

You're right, dropped the restriction and added the actual default (now, in the coordinates' own timezone).

Dropped the driving-traffic restriction and described the real default/traffic behavior instead: "Departure time, ISO 8601, defaulting to now in the coordinates' own timezone, the contours reflect traffic conditions at this time."

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.

Fixed, now points at output/render.rs.

Fixed, docs/commands.md now points at src/output/render.rs.

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>

denoise was described as "a smaller value removes more of the smaller contours," which is the opposite of the real API: a larger value is more aggressive (1.0 keeps only the largest contour; 0.5 drops anything under half its area), confirmed against docs.mapbox.com/api/navigation/isochrone/. Also rewrote it to avoid a second bug: `0.0-1.0`/`1.0` still has a literal `.` that `first_sentence()` truncates on no matter where in the sentence it sits, so the earlier "move the qualifier to the end" fix didn't actually fix this one (confirmed live: --help rendered "...smaller contours, 0"). Spelled as "0 to 1"/"1" instead, with the exact 0.5 figure in a second sentence `--schema` and docs/commands.md still show in full. polygons now says a contour that doesn't form a ring stays a linestring either way, matching the real API rather than implying every contour becomes a polygon. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

…c path generalize: dropped "smaller" — the docs say a higher value gives a coarser contour, not a smaller one. exclude: all five values are only available for mapbox/driving and mapbox/driving-traffic, confirmed against docs.mapbox.com, now says so. depart_at: the docs don't restrict it to mapbox/driving-traffic, and it defaults to now in the coordinates' own timezone when omitted — neither was in the description before. docs/commands.md also still pointed at output.rs, which moved to output/render.rs a while back. 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>

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

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 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

mattpodwysocki force-pushed the feat/directions-api branch from dfc6759 to ed4fd38 Compare October 8, 2026 15:12

mattpodwysocki and others added 4 commits October 8, 2026 11:45

mattpodwysocki force-pushed the feat/isochrone-api branch from daf27f9 to fcb18fe Compare October 8, 2026 15:46

mattpodwysocki changed the base branch from feat/directions-api to main October 8, 2026 16:29

mattpodwysocki requested a review from zmofei October 8, 2026 16:34

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

Fixed in review

Verification

Uh oh!

zmofei left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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