POST/v1/route/heritage

Auth	An API key, as `Authorization: Bearer snk_…` or `?api_key=snk_…`. Metered. Needs a full key; a browser (`maps`) key is refused.
Price	1 call per request. Class: standard, or premium for truck and ADR work. Published as `unit_rules.default` in /pricing.json.
Premium	When the body asks for truck routing: `"costing": "truck"`, a top-level `adr` object or `"hazmat": true`

What it does

POST /v1/route/heritage.

Call it

bash

curl -fsS -X POST "https://api.mapmap.ai/v1/route/heritage" \
  -H "Authorization: Bearer $MAPMAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"geometry_polyline6":"string"}'

Request body

application/json · HeritageBody

The route shape as polyline6, ideally its duration, plus an optional silence budget and audio container

Field	Type	Required	Description
duration_s	number	no	The route's own duration in seconds, typically `duration_s` from the same response. Supply it: without it the silence budget falls back to a distance, and "three to five lines an hour" is a claim about time that a distance answers wrongly at both ends.
geometry_polyline6	string	yes	The route shape as a Google encoded polyline, six-digit precision, typically `geometry_polyline6` straight out of a prior `/route` response.
max_lines	integer	no	Ceiling on how many lines come back (1 to 50, default 12).
max_offset_m	number	no	How near a plaque's own recorded coordinate must come to the route before its line may be spoken, metres (default 60, hard ceiling 80). Past about eighty metres the subject stops being something the driver is passing, so the ceiling cannot be lifted from a request body.
min_gap_m	number	no	Least distance between two spoken lines, metres (default 400). A floor under the time budget in every case, and the whole budget when no duration is supplied.
min_gap_s	number	no	Least time between two spoken lines, seconds (default 900, which is four an hour). Applied only when `duration_s` is given.
voice_format	string	no	Container to give each line's audio clip address in: `opus` (Android) or `m4a` (iOS). Given, every line gains a `clip` with the synthesis cache key and the URL to fetch it from. Omitted, no clip is computed and the answer is text only.

Example: A request assembled from this schema's own field examples, enums, defaults and types; not a recorded call

json

{
  "geometry_polyline6": "string"
}

Responses

200Lines in route order, each with at_m, the say sentence, the measured offset_m from the plaque's own coordinate to the route, the plaque_ids the claim rests on, and (when voice_format was given) the clip that speaks it; plus a census of what was not said, the attribution the source dataset is owed, and the standing caveat

Field	Type	Required	Description
attribution	string	no	Plaque data attribution.
caveat	string	no	What the lines are and are not.
census	object	no	How the lines were budgeted: entries in reach, spoken, silenced by the gap and the gap used.
corridor	object	no	The reviewed corridor the route was matched to: `id`, `name`, `road` and `reviewed_on`.
lines	object[]	no	The lines to speak, in route order: `at_m`, `offset_m`, `say`, `subject`, `basis`, `plaque_ids`, `id`, and a voice `clip` where one exists. Empty when no reviewed line is in reach.
route	object	no	The route read: `length_m` and `shape_points`.

Example: Recorded from the hosted gateway on 2026-11-05 with a test key: POST /v1/route/heritage on a central London route shape; lists trimmed to their first items

json

{
  "attribution": "Plaque inscriptions from the OpenPlaques United Kingdom dataset (snapshot of 14 December 2025), dedicated to the public domain under PDDL 1.0. Spoken lines written from those inscriptions by MapMap. Photographs in the source dataset are NOT covered by that licence and none is used here.",
  "caveat": "Every line is a sentence written and reviewed by a person from the inscription on a commemorative plaque, and nothing is generated during a drive. A plaque records that a person or an event was at a place. It does NOT record that the building still stands, that anything is visible from the road, or which side of the road it is on, and no line here claims any of those. `offset_m` is the measured distance from the plaque's own recorded coordinate to the nearest point of the route, and it is the whole of what \"along here\" rests on: the coordinate is as the source dataset recorded it and is not independently surveyed. Plaques beyond the offset gate, and plaques whose address is a side street, are counted in `census` and not spoken. The corpus covers ONE corridor and is silent everywhere else; silence is never evidence that a place has no history.",
  "census": {
    "beyond_reach": 18,
    "corpus_entries": 18,
    "corridor": "chelsea-riverside",
    "gap_basis": "time",
    "gap_m": 1457.6,
    "mean_speed_kph": 5.8,
    "silenced_by_budget": 0,
    "spoken": 0,
    "within_reach": 0
  },
  "corridor": {
    "id": "chelsea-riverside",
    "name": "Chelsea riverside",
    "reviewed_on": "2026-09-21",
    "road": "A3220 and A3212, Lots Road to Millbank"
  },
  "lines": [],
  "route": {
    "length_m": 934.5,
    "shape_points": 113
  }
}

400Invalid request