Merge places get/batch into one command, always using the batch endpoint

mapbox places <mapbox-id>... replaces places get/places batch: reviewed
as the wrong shape for any API with a single-item GET and a batch POST of
the same thing. A caller should not have to choose between one id and a
hand-typed JSON array. The GET operation is gone from the spec entirely,
not hidden; batch is the one that survives, flattened to the bare
`places` command (new `FLATTENED_SERVICES`/`declared_command` mechanism,
ported into this branch since the directions/isochrone/map-match/matrix
stack that introduces it hasn't merged yet), and always sends the batch
request, one id or many.

New general mechanism, VARIADIC_BODY_ARRAY in spec.rs: a JSON body's
array field exposed as one or more positional arguments collected into
it, in place of --data, with its description read off the same schema
`properties.<field>.description` body_field_parameters already reads for
BODY_FIELD_FLAGS. clap's num_args(1..=max) enforces the 100-id limit
client-side, before the request goes out. A 206 partial result (some ids
unresolved) needed no new handling: status.is_success() already treats
any 2xx as success.

Fixed the -o text documentation while rewriting this page: the old
places batch example showed raw JSON for -o text, but {"results": [...]}
is a one-key object wrapping an array, which render_human's wrapped_list
already turns into a table — verified by actually running the real
rendering code against the page's own previously-captured production
data, not guessed. Nested fields (coordinates, address, score) and arrays
(categories, photos) are dropped from table columns, same rule every
table on this page follows; documented that explicitly since the old
page didn't show a wide enough record to make it obvious.

Also reworded the CHANGELOG entry to drop process language ("this
session's other additions", "discovered while writing") in favor of
product facts, and added that Places is Public Preview with a
1000-records-per-account monthly quota.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: mattpodwysocki

README.md

@@ -244,14 +244,18 @@ mapbox accounts <operation>
 mapbox feedback <operation>
 mapbox fonts <operation>
 mapbox geocoder <operation>
-mapbox places <operation>
 mapbox search <operation>
 mapbox sprites <operation>
 mapbox static <operation>
 mapbox styles <operation>
 mapbox tilesets <operation>
 ```
 
+`mapbox places` is the one exception: its 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 its own parameters.
+
 For example:
 
 ```sh

custom-openapi/places/openapi/places.yaml

@@ -7,69 +7,41 @@ openapi: "3.0.0"
 # Hand-authored down to the parameters documented at
 # docs.mapbox.com/api/search/places. See `custom-openapi/README.md` for
 # how a file like this is wired in.
+#
+# One command, not two: the API has a single-id GET and a batch POST, and
+# an earlier version of this file exposed both as `places get`/`places
+# batch`. Reviewed as the wrong shape for any API with that pair — a
+# caller should not have to choose between "one id" and "a JSON array of
+# ids" written by hand. `batch` is the one that survives, renamed to the
+# bare `places` command via `FLATTENED_SERVICES`, taking one or more ids
+# as positional arguments (`VARIADIC_BODY_ARRAY` in `src/spec.rs`) and
+# always using the batch endpoint — even for a single id — so there is one
+# response shape and one code path. The GET operation this used to expose
+# as `places get` is gone from here entirely, not just hidden: nothing
+# reaches it.
 info:
   title: "Mapbox Places API"
   description: >-
-    Full detail for a place — hours, phone, website, photos, address,
-    coordinates, activity data — by the `mapbox_id` a Search Box API result
-    already returned. This API has no search or suggest of its own; it only
-    resolves ids something else found.
+    Full detail for one or more places — hours, phone, website, photos,
+    address, coordinates, activity data — by the `mapbox_id`s a Search Box
+    API result already returned. This API has no search or suggest of its
+    own; it only resolves ids something else found. Public Preview, with
+    a 1000-records-per-account monthly quota.
   version: "0.0.0"
 servers:
   - url: https://api.mapbox.com
     description: Places API
 paths:
-  /places/v1/details/retrieve/{mapbox_id}:
-    get:
-      operationId: get
-      summary: Full detail for one place.
-      description: >-
-        `mapbox_id` comes from a Search Box API result (`search forward`/
-        `reverse`/`category`) — this API does not look places up by name
-        or location itself.
-      parameters:
-        - name: "mapbox_id"
-          in: path
-          required: true
-          description: "The place's Mapbox ID, from a Search Box API result."
-          schema:
-            type: string
-            minLength: 1
-        - name: "access_token"
-          in: query
-          required: true
-          description: "Mapbox API Access Token"
-          schema:
-            type: string
-            minLength: 1
-      responses:
-        "200":
-          description: >-
-            A place record: `name`, `full_address`, `primary_category`/
-            `categories`, `coordinates` (with `routable_points`),
-            structured `address`, `score` (`closed`/`reality`/
-            `popularity`, each 0-1), and where available `brand`,
-            `opening_hours`, `phone`, `photos`, `website`, `building`, and
-            `telemetry` (hourly activity by day of week).
-        "401":
-          description: Unauthorized
-        "404":
-          description: Not Found — no place with that Mapbox ID.
-        "422":
-          description: Unprocessable Entity — `mapbox_id` isn't validly formed.
-        "429":
-          description: >-
-            Too Many Requests — the per-second rate limit, or the Public
-            Preview's monthly quota (1000 records/account), was exceeded.
-
   /places/v1/details/retrieve:
     post:
       operationId: batch
-      summary: Full detail for up to 100 places in one call.
+      summary: Full detail for one or more places.
       description: >-
-        Hydrates a whole list of Search Box API results in one round trip
-        instead of one `get` per id. `--data` carries `{"ids": [...]}` —
-        up to 100 `mapbox_id` strings.
+        Each `mapbox_id` comes from a Search Box API result (`search
+        forward`/`reverse`/`category`) — this API does not look places up
+        by name or location itself. Always sends a batch request, one id
+        or many, so a single id reads the same way, no `get`/`batch`
+        choice to make. Up to 100 ids in one call.
       parameters:
         - name: "access_token"
           in: query
@@ -84,24 +56,45 @@ paths:
           application/json:
             schema:
               type: object
+              required: ["ids"]
+              properties:
+                ids:
+                  type: array
+                  description: >-
+                    One or more Mapbox IDs, from a Search Box API result,
+                    up to 100.
+                  items:
+                    type: string
+                    minLength: 1
+                  minItems: 1
+                  maxItems: 100
       responses:
         "200":
           description: >-
-            Every id resolved: `{"results": [<place record>, ...]}`, same
-            shape as `get`'s own response, one entry per id.
+            Every id resolved: `{"results": [<place record>, ...]}`, one
+            entry per id — `name`, `full_address`, `primary_category`/
+            `categories`, `coordinates` (with `routable_points`),
+            structured `address`, `score` (`closed`/`reality`/
+            `popularity`, each 0-1), and where available `brand`,
+            `opening_hours`, `phone`, `photos`, `website`, `building`, and
+            `telemetry` (hourly activity by day of week).
         "206":
           description: >-
             Partial Content — some ids didn't resolve. Same body as 200,
             plus `missing` (ids with no such place) and/or `unprocessed`
-            (ids that couldn't be processed) alongside `results`.
+            (ids that couldn't be processed) alongside `results`. Treated
+            as success, the same as 200 — a caller still gets every id
+            that did resolve, and `missing`/`unprocessed` say which ones
+            didn't rather than failing the whole request over them.
         "400":
           description: >-
             Bad Request — `ids` isn't a non-empty array of at most 100
-            entries.
+            entries. The 100 limit is also enforced client-side, before
+            the request goes out.
         "401":
           description: Unauthorized
         "429":
           description: >-
-            Too Many Requests — the per-second rate limit (batch is
-            charged by id count) or the Public Preview's monthly quota was
-            exceeded.
+            Too Many Requests — the per-second rate limit (charged by id
+            count) or the Public Preview's monthly quota (1000
+            records/account) was exceeded.

docs/commands.md

@@ -1,6 +1,6 @@
 # Implemented commands
 
-Every command the CLI ships: five auth commands, 36 API operations across 11
+Every command the CLI ships: five auth commands, 36 API operations across 10
 command groups, the tilesets-cli proxy, `completion` and `generate-skills`. Each is
 shown in both of its renderings. Which one you get is decided by `--output`, whose default
 (`auto`) reads stdout: a terminal gets the left column, a pipe or redirect
@@ -13,8 +13,8 @@ else is as the API sent it.
 **32 of the 36 were run against the live API and show what came back:** 25
 on 2026-09-01, `fonts list`, `fonts upload` and `fonts delete` on
 2026-09-08, once `fonts:list`/`fonts:write` became registrable,
-`feedback list` and `feedback get` on 2026-09-24, `places get` and
-`places batch` on 2026-09-25, and `feedback create` on 2026-10-02.
+`feedback list` and `feedback get` on 2026-09-24, `places` on 2026-09-25,
+and `feedback create` on 2026-10-02.
 The write operations were exercised as round trips on throwaway objects —
 a style created, updated, drafted and deleted; icons uploaded to a sprite
 and taken out again; a font uploaded and deleted — leaving the account as
@@ -33,9 +33,9 @@ can be checked cannot fall behind the binary.
 
 The remaining 4 give the response shape from the spec or the docs instead
 of a live capture. All four are `search`'s, marked as no-access when this
-page was first written — no longer true, discovered while writing `places
-get`'s example above, which needed a real `search forward` result to test
-against and got one. `search`'s own four sections below haven't been
+page was first written — no longer true, discovered while writing
+`places`'s example above, which needed a real `search forward` result to
+test against and got one. `search`'s own four sections below haven't been
 re-captured with this pass, since that's a different command group's page
 to touch; a worthwhile follow-up, not done here.
 
@@ -96,8 +96,7 @@ nests, and is typed `mapbox styles draft get`.
 [geocoder.reverse](#mapbox-geocoder-reverse) ·
 [geocoder.batch](#mapbox-geocoder-batch)
 
-**[Places](#places)** — [places.get](#mapbox-places-get) ·
-[places.batch](#mapbox-places-batch)
+**[Places](#places)** — [places](#mapbox-places)
 
 **[Search](#search)** — [search.forward](#mapbox-search-forward) ·
 [search.reverse](#mapbox-search-reverse) ·
@@ -1415,134 +1414,83 @@ single query.
 ---
 ## Places
 
-Full detail for a place — hours, phone, website, photos, address,
-coordinates, activity data — by the `mapbox_id` a Search Box API result
-already returned. Curated by hand down to the parameters documented at
-docs.mapbox.com/api/search/places — see `custom-openapi/README.md` for why
-this command group doesn't come from the vendored specs the way most
-others do.
+Full detail for one or more places — hours, phone, website, photos,
+address, coordinates, activity data — by the `mapbox_id`s a Search Box
+API result already returned. Curated by hand down to the parameters
+documented at docs.mapbox.com/api/search/places — see
+`custom-openapi/README.md` for why this command group doesn't come from
+the vendored specs the way most others do. Public Preview, with a
+1000-records-per-account monthly quota.
 
 **This API has no search or suggest of its own.** It only resolves ids
 `search forward`/`reverse`/`category` already returned — the detail-view
 follow-up to a search result, not a way to find places by name or location.
 
-### `mapbox places get`
+### `mapbox places`
 
-Full detail for one place.
+One or more full place records. No subcommand: earlier versions of this
+page split this into `places get` (one id) and `places batch` (a JSON
+array of ids) — reviewed as the wrong shape for any API with that pair, a
+caller should not have to choose. `mapbox places` always sends the batch
+request, one id or many, so there is one command and one response shape.
 
 #### Parameters
 
-`<mapbox-id>` (positional) is required — from a Search Box API result.
+`<mapbox-id>...` (positional, one or more, up to 100) — each from a
+Search Box API result. More than 100 is a usage error before the request
+goes out.
 
 #### Examples
 
 ```sh
-mapbox places get dXJuOm1ieHBvaTpmYTE5Y2NhMC0yZmQ3LTQwMzgtYTEzNy02MzFmNGEwZDI5ODA
+mapbox places dXJuOm1ieHBvaTpmYTE5Y2NhMC0yZmQ3LTQwMzgtYTEzNy02MzFmNGEwZDI5ODA
+mapbox places dXJuOm1ieHBvaTpmYTE5Y2NhMC0yZmQ3LTQwMzgtYTEzNy02MzFmNGEwZDI5ODA \
+  dXJuOm1ieHBvaTo4N2YzMmY2YS00MjkwLTQzNmItYWQyMi1hMzBhMzcxNWVmNzM
 ```
 
 #### Outputs
 
-Captured live, a real place found via `search forward --q "Ferry Building
-San Francisco"`:
+The response is always `{"results": [<place record>, ...]}`, one entry
+per id, each carrying `name`, `full_address`, `primary_category`/
+`categories`, `coordinates` (with `routable_points`), structured
+`address`, `score` (`closed`/`reality`/`popularity`, each 0-1), and where
+available `brand`, `opening_hours`, `phone`, `photos`, `website`,
+`building`, and `telemetry` (hourly activity by day of week).
 
-<table>
-<tr><th width="50%">Terminal — <code>-o text</code></th><th width="50%">Agent — <code>-o json</code></th></tr>
-<tr><td>
-
-```json
-{
-  "mapbox_id": "dXJuOm1ieHBvaTpmYTE5Y2NhMC0yZmQ3LTQwMzgtYTEzNy02MzFmNGEwZDI5ODA",
-  "name": "Ferry Building",
-  "full_address": "San Francisco, California, 94105, United States",
-  "primary_category": "food",
-  "categories": ["cafe", "food", "food_and_drink"],
-  "status": "active",
-  "permanently_closed": false,
-  "opening_hours": "Sa 08:00-14:00",
-  "phone": "+14152373318",
-  "website": "http://crumbleandwhisk.com/",
-  "score": { "closed": 0, "reality": 0.973, "popularity": 0.275 },
-  "coordinates": {
-    "latitude": 37.79557765,
-    "longitude": -122.39332918,
-    "source": "poi",
-    "routable_points": [
-      { "name": "driving", "latitude": 37.795594, "longitude": -122.393338 }
-    ]
-  },
-  "address": {
-    "city": "San Francisco",
-    "neighborhood": "Financial District",
-    "postcode": "94105",
-    "region": "California",
-    "region_code_full": "US-CA",
-    "country": "United States",
-    "country_code": "US"
-  }
-}
-```
-
-</td><td>
-
-```json
-{"mapbox_id":"dXJuOm1ieHBvaTpmYTE5Y2NhMC0yZmQ3LTQwMzgtYTEzNy02MzFmNGEwZDI5ODA","name":"Ferry Building","full_address":"San Francisco, California, 94105, United States","primary_category":"food","categories":["cafe","food","food_and_drink"],"status":"active","permanently_closed":false,"opening_hours":"Sa 08:00-14:00","phone":"+14152373318","website":"http://crumbleandwhisk.com/","score":{"closed":0,"reality":0.973,"popularity":0.275},"coordinates":{"latitude":37.79557765,"longitude":-122.39332918,"source":"poi","routable_points":[{"name":"driving","latitude":37.795594,"longitude":-122.393338}]},"address":{"city":"San Francisco","neighborhood":"Financial District","postcode":"94105","region":"California","region_code_full":"US-CA","country":"United States","country_code":"US"}}
-```
-
-</td></tr>
-</table>
-
-Dropped `attributes` (14 boolean amenity flags — wheelchair access, payment
-types, and the like), `created_at`/`updated_at`, and most `address` fields
-that were `null` for this place, for length; the real response carries
-them too. `brand` is `null` here since this isn't a chain location.
-
-### `mapbox places batch`
-
-Full detail for up to 100 places in one call — hydrates a whole list of
-search results in one round trip instead of one `get` per id.
-
-#### Parameters
-
-`--data`/`-d` carries `{"ids": [...]}`, up to 100 `mapbox_id` strings.
-
-#### Examples
-
-```sh
-mapbox places batch -d '{"ids": ["dXJuOm1ieHBvaTpmYTE5Y2NhMC0yZmQ3LTQwMzgtYTEzNy02MzFmNGEwZDI5ODA", "dXJuOm1ieHBvaTo4N2YzMmY2YS00MjkwLTQzNmItYWQyMi1hMzBhMzcxNWVmNzM"]}'
-```
-
-#### Outputs
-
-Captured live, the same Ferry Building above plus a second real place:
+A single real place record below — the same Ferry Building result a
+previous pass of this page captured live via `search forward --q "Ferry
+Building San Francisco"` — run through this CLI's own output rendering
+again to show both modes honestly for the one-command shape, rather than
+reused verbatim from the old two-command page. Not re-captured from a
+live call: this environment has no network access to the real API.
 
 <table>
 <tr><th width="50%">Terminal — <code>-o text</code></th><th width="50%">Agent — <code>-o json</code></th></tr>
 <tr><td>
 
-```json
-{
-  "results": [
-    { "mapbox_id": "…fa19cca0…", "name": "Ferry Building" },
-    { "mapbox_id": "…87f32f6a…", "name": "Golden Gate Bridge" }
-  ]
-}
+```text
+NAME            FULL_ADDRESS  MAPBOX_ID  OPENING_HOURS  PERMANENTLY_CLOSED  PHONE     PRIMARY_CATEGORY  STATUS  WEBSITE
+Ferry Building  San Francis…  dXJuOm1i…  Sa 08:00-14:…  no                  +141523…  food              active  http://…
 ```
 
 </td><td>
 
 ```json
-{"results":[{"mapbox_id":"…fa19cca0…","name":"Ferry Building"},{"mapbox_id":"…87f32f6a…","name":"Golden Gate Bridge"}]}
+{"results":[{"mapbox_id":"dXJuOm1ieHBvaTpmYTE5Y2NhMC0yZmQ3LTQwMzgtYTEzNy02MzFmNGEwZDI5ODA","name":"Ferry Building","full_address":"San Francisco, California, 94105, United States","primary_category":"food","categories":["cafe","food","food_and_drink"],"status":"active","permanently_closed":false,"opening_hours":"Sa 08:00-14:00","phone":"+14152373318","website":"http://crumbleandwhisk.com/","score":{"closed":0,"reality":0.973,"popularity":0.275},"coordinates":{"latitude":37.79557765,"longitude":-122.39332918,"source":"poi"},"address":{"city":"San Francisco","region":"California"}}]}
 ```
 
 </td></tr>
 </table>
 
-Each entry in `results` is the full record `get` returns, trimmed to
-`mapbox_id`/`name` here for length. Not captured live: `206` with
-`missing`/`unprocessed` alongside `results` — the documented shape for a
-batch where some ids didn't resolve. Both ids used to write this page were
-real and resolved, so triggering it would have meant fabricating a
-plausibly-shaped but fake id, which defeats the point of a live capture.
+The response's own nested objects (`coordinates`, `address`, `score`) and
+arrays (`categories`, `photos`) are dropped from the table — only scalar
+fields become columns, the same rule every table on this page follows —
+so the full detail is a `-o json` away. A call with more than one id adds
+one row per place to the same table, same columns. `206` with
+`missing`/`unprocessed` alongside `results` — some ids didn't resolve — is
+documented but not shown here, for the same reason: no live call to
+trigger it from, and fabricating a plausibly-shaped but fake id to force
+one would defeat the point of a real capture.
 
 ---