MapMap is an MCP server published by ai.mapmap, hosted at mcp.mapmap.ai. When last checked on 2026-11-22 it was working: it answers and lists its tools. It declares 57 tools, including camera_incidents, cheapest_charging_along_route, cheapest_fuel_along_route, check_adr_tunnel, check_clearance_on_route.
Maps for agents: truck/ADR routing, geocoding, places, matrices, isochrones, EV and fleet planning.
Nothing else in the archive shares these values.
Squares are this server's values; dots are other servers sharing them. A shared address or publisher is a lead, not proof of a common operator.
Inferred from the host name and headers: what a server runs on, not who runs it.
Road incidents a TRAFFIC CAMERA SAW and a vision model CONFIRMED, in force now: near a point (`near` [lat, lon] with `radius_m`, default 1000, at most 10000), in a `bbox` [min_lon, min_lat, max_lon, max_lat], or along a route `shape` (polyline6 from `route`, corridor `buffer_m` default 60). Give exactly one. Each record says what it asserts (`closed` or a `speed_override` in km/h) on which OSM ways and carriageway, what was seen (collision, stalled vehicle, wrong-way vehicle), the camera, the clip URL the verdict was made on (`evidence_url`), the verifier and its `confidence`, and when it lifts (`end`, always within minutes: these records expire on their own). Camera records RANK BELOW official closures and never retract one. READ `coverage_note` ALOUD: an empty list means no camera-verified incident here, NEVER a clear road. Show `attribution` verbatim (Powered by TfL Open Data). Off unless the deployment arms camera incidents (SN_CAMERA_INCIDENTS_ENABLED): an unarmed gateway answers 501 and says so. Requires the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY).
| Parameter | Type | Description |
|---|---|---|
| bbox | ["array","null"] | `[min_lon, min_lat, max_lon, max_lat]`. |
| near | ["array","null"] | `[lat, lon]` plus `radius_m` (default 1000). |
| shape | ["string","null"] | A route shape as polyline6; the corridor rule of `/v1/incidents/along` applies (`buffer_m` default 60). |
| buffer_m | ["number","null"] | Corridor half-width for `shape`, metres. |
| radius_m | ["number","null"] | Radius for `near`, metres, at most 10000. |
| min_confidence | ["number","null"] | Drop records below this confidence (default 0). |
| include_recently_expired | boolean | Include records that have expired in the last hour, for the operator's timeline (default false). |
{
"name": "camera_incidents",
"description": "Road incidents a TRAFFIC CAMERA SAW and a vision model CONFIRMED, in force now: near a point (`near` [lat, lon] with `radius_m`, default 1000, at most 10000), in a `bbox` [min_lon, min_lat, max_lon, max_lat], or along a route `shape` (polyline6 from `route`, corridor `buffer_m` default 60). Give exactly one. Each record says what it asserts (`closed` or a `speed_override` in km/h) on which OSM ways and carriageway, what was seen (collision, stalled vehicle, wrong-way vehicle), the camera, the clip URL the verdict was made on (`evidence_url`), the verifier and its `confidence`, and when it lifts (`end`, always within minutes: these records expire on their own). Camera records RANK BELOW official closures and never retract one. READ `coverage_note` ALOUD: an empty list means no camera-verified incident here, NEVER a clear road. Show `attribution` verbatim (Powered by TfL Open Data). Off unless the deployment arms camera incidents (SN_CAMERA_INCIDENTS_ENABLED): an unarmed gateway answers 501 and says so. Requires the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY).",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"bbox": {
"type": [
"array",
"null"
],
"items": {
"type": "number",
"format": "double"
},
"maxItems": 4,
"minItems": 4,
"description": "`[min_lon, min_lat, max_lon, max_lat]`."
},
"near": {
"type": [
"array",
"null"
],
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "`[lat, lon]` plus `radius_m` (default 1000)."
},
"shape": {
"type": [
"string",
"null"
],
"description": "A route shape as polyline6; the corridor rule of\n`/v1/incidents/along` applies (`buffer_m` default 60)."
},
"buffer_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Corridor half-width for `shape`, metres."
},
"radius_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Radius for `near`, metres, at most 10000."
},
"min_confidence": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Drop records below this confidence (default 0)."
},
"include_recently_expired": {
"type": "boolean",
"default": false,
"description": "Include records that have expired in the last hour, for the\noperator's timeline (default false)."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"WayOut": {
"type": "object",
"required": [
"way_id",
"direction"
],
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "Road name, when known."
},
"way_id": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "OSM way id."
},
"direction": {
"$ref": "#/$defs/Direction",
"description": "Carriageway."
}
},
"description": "One road asserted."
},
"Direction": {
"oneOf": [
{
"type": "string",
"const": "forward",
"description": "Along the way's node order."
},
{
"type": "string",
"const": "backward",
"description": "Against it."
},
{
"type": "string",
"const": "both",
"description": "Both carriageways."
}
],
"description": "Carriageway of a way, spelled as the artefact spells it. A serde\ntwin of [`WayDirection`], which deliberately carries no serde."
},
"IncidentKind": {
"oneOf": [
{
"type": "string",
"const": "collision",
"description": "Two or more vehicles made contact."
},
{
"type": "string",
"const": "stalled-vehicle",
"description": "A vehicle stopped where it should not have."
},
{
"type": "string",
"const": "wrong-way",
"description": "A vehicle travelling against the carriageway direction."
},
{
"type": "object",
"required": [
"other"
],
"properties": {
"other": {
"type": "string"
}
},
"description": "Anything else, carrying the raw category for logs.",
"additionalProperties": false
}
],
"description": "What kind of road event an incident describes, as far as a closure\ndecision cares."
},
"CameraIncidentOut": {
"type": "object",
"required": [
"id",
"source",
"kind",
"incident_kind",
"camera_name",
"camera_position",
"ways",
"start",
"end",
"confidence",
"verifier"
],
"properties": {
"id": {
"type": "string",
"description": "Override record id."
},
"end": {
"type": "string",
"description": "Lifts at, RFC 3339."
},
"kind": {
"type": "string",
"description": "`closed` or `speed_override`."
},
"ways": {
"type": "array",
"items": {
"$ref": "#/$defs/WayOut"
},
"description": "Roads asserted."
},
"arc_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Distance along the route, metres, when queried by `shape`."
},
"start": {
"type": "string",
"description": "In force from, RFC 3339."
},
"source": {
"type": "string",
"description": "`cam-<provider>-<camera id>`."
},
"verifier": {
"type": "string",
"description": "Which verifier answered."
},
"speed_kph": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Speed in force, km/h, for `speed_override`."
},
"confidence": {
"type": "number",
"format": "double",
"description": "Verifier confidence, `0..=1`."
},
"camera_name": {
"type": "string",
"description": "Camera name."
},
"evidence_url": {
"type": [
"string",
"null"
],
"description": "The clip the decision was made on."
},
"incident_kind": {
"$ref": "#/$defs/IncidentKind",
"description": "What was seen."
},
"camera_position": {
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "Camera position `[lat, lon]`."
}
},
"description": "One camera-verified incident in force."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"incidents",
"coverage_note",
"attribution"
],
"properties": {
"incidents": {
"type": "array",
"items": {
"$ref": "#/$defs/CameraIncidentOut"
},
"description": "Records in force (and recently expired, if asked)."
},
"attribution": {
"type": "array",
"items": {
"type": "string"
},
"description": "Attribution lines required by the camera providers, verbatim."
},
"coverage_note": {
"type": "string",
"description": "Plain-language statement of which cameras are covered and that\ncamera records rank below official closures. Agents must read it\naloud: an empty list means \"no camera-verified incident\", never\n\"road clear\"."
}
}
}
}Find the best EV charge points along a route, with the REAL extra travel time of stopping at each one, never a straight-line guess. Provide `origin` + `destination` (a route is computed) or an existing route's `geometry_polyline6`, plus optional `connectors` ("ccs", "type2", "chademo", "type1", "tesla", "domestic", "other"), `min_kw` (e.g. 50 for rapid only), `available_only` and `max_detour_minutes` (default 10). Charge points come from operator-published feeds, are costed through the routing engine with your costing (a `truck` profile makes detours respect dimensional/ADR restrictions) and ranked most powerful first, since minutes off the clock are bought with kilowatts. Each result carries max_power_kw, connector_standards, best_connector, evse_count, detour_minutes/detour_km and, where a live feed backs it, available_now. IMPORTANT: there is no national charge-point registry, every deployment covers only the operators it has onboarded, so ALWAYS show the returned `coverage_note` alongside the results. An empty `results` means "none from these operators within the detour budget", NEVER "there are no chargers here". Statuses are live only when availability_live is true; otherwise they are the values captured at the last ingest and must not be described as current. `say` is ALWAYS present and is the whole answer as one short spoken line, composed by the gateway with the coverage already inside the claim rather than appended to it: it scopes its superlative to the operators this deployment holds, and an empty result's line says the emptiness is about those operators. Prefer reading it verbatim to writing your own summary. Requires the MapMap gateway; answers a clear error when the deployment has no charge-point dataset. Display the returned charging_attribution with the results.
| Parameter | Type | Description |
|---|---|---|
| truck | any | Truck profile (dimensions + ADR declaration). Requires costing "truck"; the detours then respect dimensional/ADR restrictions. |
| min_kw | ["number","null"] | Keep only charge points whose best connector is rated at least this many kW (e.g. 50 for rapid charging only). |
| origin | any | Route origin (with `destination`, when no geometry is given). |
Find the cheapest fuel along a route, with the REAL extra travel time of stopping at each station, never a straight-line guess. Provide `origin` + `destination` (a route is computed) or an existing route's `geometry_polyline6`, plus a `fuel` code ("diesel" default, "petrol_95", "petrol_98", "premium_diesel", "e85", "lpg") and `max_detour_minutes` (default 10). Stations come from the live open-data price feeds (UK retailer feeds of the closed CMA interim scheme and/or the statutory Fuel Finder, FR prix-carburants, DE Tankerkoenig; the response's `fuel_attribution` names the ones actually matched), are priced through the routing engine with your costing (a `truck` profile makes detours respect dimensional/ADR restrictions) and ranked freshest-priced first and cheapest within that. Each result carries price {value, currency, updated_at, stale}, detour_minutes/detour_km, and saving_per_litre vs the cheapest on-route baseline (pass `fill_litres` to also get saving_total). `stale` = not verifiably fresher than 24 h: true unless BOTH the price's own updated_at and the snapshot's fetch time are inside that window, and true whenever either is missing. A stale price is ranked below every fresh one, is never the baseline, and carries NO saving_per_litre, quote it as "last seen at X on <date>", never as a saving. `say` is ALWAYS present and is the whole answer as one short spoken line, composed by the gateway with the number, the detour and the honest qualifier already in it. Prefer reading it verbatim to writing your own summary: a stale price's line states the figure and the day it was last seen and claims no saving, and an empty result's line names the cause rather than implying there is no fuel on that road. `coverage` says what the price snapshot holds (stations, countries, sources) and, when it holds UK stations, carries a `statement` naming the UK retailers covered, with `uk_retailers` and `uk_partial`. Show the statement with any UK answer: when `uk_partial` is true UK prices come only from those retailers' feeds, so an empty UK result means "none from these retailers", never "no fuel here". An empty result also carries `note`, the cause in prose, which on such a route ends with that statement. Requires the MapMap gateway; answers a clear error when the deployment has no fuel-price dataset. Display the returned fuel_attribution with the prices.
| Parameter | Type | Description |
|---|---|---|
| fuel | ["string","null"] | Which fuel to price: "diesel" (default), "petrol_95", "petrol_98", "premium_diesel", "e85" or "lpg" (aliases "petrol", "unleaded", "e10", "super_unleaded", "e5", "b7" and "sdv" are accepted). |
Check whether a vehicle may pass through a tunnel of a given ADR category ("A"–"E"). Provide `hazmat` and, when known, the load's ADR 8.6.4 tunnel restriction code (e.g. "B", "C5000D", "B/D", "none"). Applies the conservative worst-case reading: conditional clauses are assumed to apply, so a blocked answer may over-restrict but never under-restricts. No network access; answers instantly.
| Parameter | Type | Description |
|---|---|---|
| hazmat * | boolean | Whether the vehicle carries dangerous goods at all. When false the ADR tunnel matrix does not apply and every tunnel is permitted. |
| tunnel_code | ["string","null"] | ADR 8.6.4 tunnel restriction code of the load, e.g. "B", "C5000D", "B/D", or "(-)"/"none". Leave unset for a hazmat load of unknown code (conservatively treated as code B). |
| tunnel_category * | string | ADR category of the tunnel to check: "A", "B", "C", "D" or "E". |
{
"name": "check_adr_tunnel",
"description": "Check whether a vehicle may pass through a tunnel of a given ADR category (\"A\"–\"E\"). Provide `hazmat` and, when known, the load's ADR 8.6.4 tunnel restriction code (e.g. \"B\", \"C5000D\", \"B/D\", \"none\"). Applies the conservative worst-case reading: conditional clauses are assumed to apply, so a blocked answer may over-restrict but never under-restricts. No network access; answers instantly.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"hazmat",
"tunnel_category"
],
"properties": {
"hazmat": {
"type": "boolean",
"description": "Whether the vehicle carries dangerous goods at all. When false the\nADR tunnel matrix does not apply and every tunnel is permitted."
},
"tunnel_code": {
"type": [
"string",
"null"
],
"description": "ADR 8.6.4 tunnel restriction code of the load, e.g. \"B\", \"C5000D\",\n\"B/D\", or \"(-)\"/\"none\". Leave unset for a hazmat load of unknown\ncode (conservatively treated as code B)."
},
"tunnel_category": {
"type": "string",
"description": "ADR category of the tunnel to check: \"A\", \"B\", \"C\", \"D\" or \"E\"."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"DecisionStatus": {
"oneOf": [
{
"type": "string",
"const": "allowed",
"description": "Passage is permitted."
},
{
"type": "string",
"const": "blocked",
"description": "Passage is forbidden."
}
],
"description": "The tunnel-entry decision, mirroring `sn_adr::Decision`."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"decision",
"explanation",
"forbidden_tunnel_categories"
],
"properties": {
"reason": {
"type": [
"string",
"null"
],
"description": "Why passage is forbidden (present only when blocked); cites the\nADR 8.6.4 rule that applied."
},
"decision": {
"$ref": "#/$defs/DecisionStatus",
"description": "Whether passage is allowed or blocked."
},
"explanation": {
"type": "string",
"description": "Human-readable explanation of how the decision was reached,\nincluding the conservative worst-case reading."
},
"forbidden_tunnel_categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "ADR tunnel categories this load is forbidden from under the\nworst-case reading (conditional clauses assumed to apply). Empty\nwhen unrestricted."
}
}
}
}Measure a vehicle's overhead clearance along a route against surveyed point cloud geometry, wherever survey coverage exists. Routes with truck costing (so the search already avoids the height restrictions the map has tagged), then measures that corridor. Give `origin`, `destination` and `height_m`; optional `width_m` asks the corridor-width axis too, and optional `margin_m` adds your operating margin to the vehicle before the verdict. Returns `pass`, `fail`, `indeterminate` or `no_verdict` with the limiting point, the measured headroom, its uncertainty bound (`safe_headroom_m`, `sigma_m`, `sampling_gap_m`) and a link to that exact view in the survey viewer. An `indeterminate` carries `indeterminate_reasons` as codes to branch on and the same reasons as English inside `explanation`; read out the English. A `pass` may carry no limiting point at all, which means the survey found nothing above that corridor, and the width axis may answer `not_assessed` where the corridor edges are too sparsely surveyed while the height axis still answers. Honesty, and it matters here: this measures physical geometry from a dated survey. It is not a signed or posted height, `clearance_enforcement.route_certified` is always false, and the caveat is on every answer including the clear one. Ground the survey did not cover comes back as `not_surveyed_m` and is never judged, so a `pass` is possible over complete coverage and nowhere else; sparse or stale coverage comes back separately as `insufficient_data_m`. Reach for this when a truck route came back unchanged and you need to know whether that means anything: an unchanged route avoids what the map records, which is a different claim from measured headroom, because a structure nobody tagged is routed through like open road. Needs the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY), which holds the surveys; there is no fallback, and it will not answer from the routing step alone. The mapmap://guide/clearance resource sets out what each answer proves.
| Parameter | Type | Description |
|---|---|---|
| origin * | ref | Route origin. |
| width_m | ["number","null"] | Vehicle width in metres. Supplying it asks the width axis as well as the height axis; the width answer is reported separately and is never a headroom. |
| height_m |
Audit a map style's colour contrast against WCAG 2.1 (4.5:1 for label text, 3:1 for graphics like the route line), across both the light and dark palette variants. Pass a hosted `style_id` OR an inline `theme` document (as accepted by create_style). Advisory: failing pairs list the palette slots to adjust with set_palette; publishing is never blocked on contrast.
| Parameter | Type | Description |
|---|---|---|
| theme | any | …or an inline theme document (as accepted by `create_style`). Exactly one of `style_id`/`theme` must be given. |
| style_id | ["string","null"] | Hosted style id whose latest theme should be checked… |
{
"name": "check_style_contrast",
"description": "Audit a map style's colour contrast against WCAG 2.1 (4.5:1 for label text, 3:1 for graphics like the route line), across both the light and dark palette variants. Pass a hosted `style_id` OR an inline `theme` document (as accepted by create_style). Advisory: failing pairs list the palette slots to adjust with set_palette; publishing is never blocked on contrast.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"theme": {
"description": "…or an inline theme document (as accepted by `create_style`).\nExactly one of `style_id`/`theme` must be given."
},
"style_id": {
"type": [
"string",
"null"
],
"description": "Hosted style id whose latest theme should be checked…"
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"ContrastFindingInfo": {
"type": "object",
"required": [
"variant",
"kind",
"foreground",
"background",
"description",
"ratio",
"threshold",
"passes"
],
"properties": {
"kind": {
"type": "string",
"description": "Pair kind: \"text\" (threshold 4.5) or \"graphics\" (threshold 3.0)."
},
"ratio": {
"type": "number",
"format": "double",
"description": "Measured WCAG 2.1 contrast ratio."
},
"passes": {
"type": "boolean",
"description": "Whether the pair meets its threshold."
},
"variant": {
"type": "string",
"description": "Palette variant audited: \"light\" or \"dark\"."
},
"threshold": {
"type": "number",
"format": "double",
"description": "The WCAG threshold applied."
},
"background": {
"type": "string",
"description": "Effective backing palette slot."
},
"foreground": {
"type": "string",
"description": "Foreground palette slot."
},
"description": {
"type": "string",
"description": "Why this pair matters cartographically."
}
},
"description": "One audited colour pair of a contrast report."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"passes",
"findings"
],
"properties": {
"passes": {
"type": "boolean",
"description": "True when every audited pair meets its WCAG threshold."
},
"findings": {
"type": "array",
"items": {
"$ref": "#/$defs/ContrastFindingInfo"
},
"description": "Every audited pair, failing pairs first."
}
}
}
}Group stops into balanced geographic clusters, so a day too large for one optimisation can be optimised one cluster at a time. This is the front half of the recipe for a thousand-stop day: cluster here, then call `optimise_routes` per cluster, where the routing engine's own matrix decides the visiting order. IMPORTANT, this is STRAIGHT-LINE clustering. Distances are measured between coordinates, not along the road network: no road, river, motorway junction or one-way system is consulted, and two stops either side of an estuary look adjacent. That makes it the right tool for deciding which stops belong TOGETHER and the wrong one for deciding what ORDER to visit them in. The answer carries a `basis` sentence saying exactly this; show it, so a centroid is never read as a plan. Provide `locations` ([{id, lat, lon, load?}], ids unique, at most 5,000) and EXACTLY ONE of `clusters` (how many groups, balanced by stop count), `max_cluster_locations` or `max_cluster_load` (a per-cluster ceiling the count is derived from). Optional `territories` keep a cluster from straddling a round: each is clustered on its own, and so are the stops inside none of them. Optional `seed` (default 42) drives the seeding, the same request with the same seed always returns the same clusters, on every deployment, so a re-run is a re-run. Returns each cluster's member ids, count, summed load, centroid and territory, plus a `balance` block naming the constraint applied and whether it had to be relaxed to place every stop: a load ceiling with lumpy loads is a bin-packing problem and may have no solution at the derived count. Requires the MapMap gateway.
| Parameter | Type | Description |
|---|---|---|
| seed | ["integer","null"] | Seed for the k-means++ seeding (default 42). The same request with the same seed always returns the same clusters, on every deployment. |
| clusters | ["integer","null"] | How many clusters to produce, balanced by stop count. Give exactly one of `clusters`, `max_cluster_locations` or `max_cluster_load`. |
| locations * | array | The stops to group. Ids must be unique; at most 5,000. |
| territories |
Turn-by-turn guidance for one drive of a finished coverage plan (`submit_optimise_job` with `kind: "coverage"`, read with `get_job`), in one call. Give `job_id` (the coverage job, the caller's own and `succeeded`), `chunk_id` (the outing's `id` in `result.chunks`, from 1) and `drive`: "outing" (default, the outing itself), "transfer" (the drive into that outing from the previous one's end, or from where the car is; `chunk_loops` plans) or "transfer_to_start" (the plan's drive back to its start; no `chunk_id`). The gateway walks every piece of that drive's `trace_route_parts` on the engine's exact edge walk and answers one trip: `legs` has one entry per piece in driving order, each with its maneuvers, plus the whole drive's `distance_m`, `duration_s` and `geometry_polyline6`. Durations include the time the engine charges at each junction where one piece ends and the next begins (on the leg after it), so `duration_s` is the plan's `drive_time_s` for the drive (times the plan's own `time_factor`, which guidance by job id takes from the plan). Pieces join mid-street wherever the plan allowed: a leg's closing arrival and the next leg's opening departure at the same point mean carry straight on, not stop. Exact or nothing: it never falls back to map matching (which drops streets driven in and straight back out), so a piece the engine refuses is an error naming that piece and the engine's own words. Metered by the gateway as one call at the size of a /trace_route of the drive (one call per started block of shape points, never fewer than the pieces). A refused piece keeps those quota units (the engine did the work) but takes no prepaid credit or x402 payment; a request refused before walking (unknown or unfinished job, no such outing) is not billed. Premium for a truck plan. Requires the MapMap gateway.
| Parameter | Type | Description |
|---|---|---|
| drive | ref | `outing` (the default), `transfer` (the drive into that outing) or `transfer_to_start` (the plan's drive back to its start). |
| job_id * | string | The coverage job's id, as `submit_optimise_job` (`kind: "coverage"`) returned it. The job must be this key's own (or another key of the same account) and `succeeded`. |
| chunk_id | ["integer","null"] |
Create a hosted map style. Provide a name, optionally a named `base` to start from (light, dark, streets, midnight, navigator-day, navigator-night, fleet, outdoor, dataviz, backdrop, print - call list_style_layers for what each one is for), and optionally a theme document ({base: "light"|"dark", palette: {slot: colour}, layers: {layer_id: overrides}}). The named base is laid down first and the theme document is merged over it, so "streets with darker water" is one call; with neither, the style starts from the default theme. A theme may also set worldview (ISO 3166-1 alpha-2, accepted: AE, KR, SA, US) to display that jurisdiction's official names for a small curated registry of renamed features; omitted, labels keep the OSM on-the-ground names. Returns the generated style_id (pass it to set_palette / set_layer_paint) and the compiled style URL for MapLibre.
| Parameter | Type | Description |
|---|---|---|
| base | ["string","null"] | Optional named base to start from, e.g. "streets", "midnight", "navigator-night", "fleet". Call `list_style_layers` for the catalogue, including which bases expect an overlay of their own. The base's whole document is laid down first and `theme` is merged over it, so a base plus two palette entries … |
| name * | string | Human-readable style name; its kebab-case slug seeds the style id. |
| theme | any | Optional theme document (palette/layer overrides). Merged over `base` when one is given; on its own, it replaces the default theme outright. |
{
"name": "create_style",
"description": "Create a hosted map style. Provide a name, optionally a named `base` to start from (light, dark, streets, midnight, navigator-day, navigator-night, fleet, outdoor, dataviz, backdrop, print - call list_style_layers for what each one is for), and optionally a theme document ({base: \"light\"|\"dark\", palette: {slot: colour}, layers: {layer_id: overrides}}). The named base is laid down first and the theme document is merged over it, so \"streets with darker water\" is one call; with neither, the style starts from the default theme. A theme may also set worldview (ISO 3166-1 alpha-2, accepted: AE, KR, SA, US) to display that jurisdiction's official names for a small curated registry of renamed features; omitted, labels keep the OSM on-the-ground names. Returns the generated style_id (pass it to set_palette / set_layer_paint) and the compiled style URL for MapLibre.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"name"
],
"properties": {
"base": {
"type": [
"string",
"null"
],
"description": "Optional named base to start from, e.g. \"streets\", \"midnight\",\n\"navigator-night\", \"fleet\". Call `list_style_layers` for the\ncatalogue, including which bases expect an overlay of their own. The\nbase's whole document is laid down first and `theme` is merged over\nit, so a base plus two palette entries is a complete style. Omitted,\nthe style starts from the default light theme as it always did."
},
"name": {
"type": "string",
"description": "Human-readable style name; its kebab-case slug seeds the style id."
},
"theme": {
"description": "Optional theme document (palette/layer overrides). Merged over\n`base` when one is given; on its own, it replaces the default theme\noutright."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"style_id",
"version",
"style_url",
"theme"
],
"properties": {
"theme": {
"description": "The theme document that was stored."
},
"version": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "The published version (always 1 on create)."
},
"style_id": {
"type": "string",
"description": "The generated style id, pass it to `set_palette`,\n`set_layer_paint` and `get_style`."
},
"style_url": {
"type": "string",
"description": "Immutable URL of the compiled style at this version."
}
}
}
}Sample terrain elevation. Provide `points` (a bare list of coordinates) for point elevation, or `encoded_polyline` (optionally with `resample_distance_m`) for an along-route profile, not both. Returns one sample per point/resampled point in order; `elevation_m` is null wherever the engine's DEM tile set has no coverage at that point (never a guess). The `encoded_polyline` form also returns each sample's resampled lat/lon and cumulative `range_km` from the start.
| Parameter | Type | Description |
|---|---|---|
| points | ["array","null"] | Points to sample. Provide this or `encoded_polyline`, not both. |
| encoded_polyline | ["string","null"] | A route as a Google encoded polyline with six digits of precision. Provide this or `points`, not both. |
| resample_distance_m | ["number","null"] | Resamples `encoded_polyline` at this spacing in metres before sampling height (ignored for `points`). |
{
"name": "elevation",
"description": "Sample terrain elevation. Provide `points` (a bare list of coordinates) for point elevation, or `encoded_polyline` (optionally with `resample_distance_m`) for an along-route profile, not both. Returns one sample per point/resampled point in order; `elevation_m` is null wherever the engine's DEM tile set has no coverage at that point (never a guess). The `encoded_polyline` form also returns each sample's resampled lat/lon and cumulative `range_km` from the start.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"points": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/LatLon"
},
"description": "Points to sample. Provide this or `encoded_polyline`, not both."
},
"encoded_polyline": {
"type": [
"string",
"null"
],
"description": "A route as a Google encoded polyline with six digits of precision.\nProvide this or `points`, not both."
},
"resample_distance_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Resamples `encoded_polyline` at this spacing in metres before\nsampling height (ignored for `points`)."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"ElevationSample": {
"type": "object",
"required": [
"elevation_m"
],
"properties": {
"lat": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Latitude of the (possibly resampled) point, when known."
},
"lon": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Longitude of the (possibly resampled) point, when known."
},
"range_km": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Cumulative distance from the first point in kilometres, present\nonly for the `encoded_polyline` form."
},
"elevation_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Elevation in metres, or `null` when the engine has no DEM tile\ncoverage at this point, Valhalla's own honest value, never a\nguess."
}
},
"description": "One elevation sample: `elevation_m` and, when the request set\n`encoded_polyline`, the resampled point and its cumulative distance\nfrom the start."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"samples"
],
"properties": {
"samples": {
"type": "array",
"items": {
"$ref": "#/$defs/ElevationSample"
},
"description": "One sample per input point (or per resampled shape point, in the\n`encoded_polyline` form), in order."
}
}
}
}Earthquakes, volcano alerts and satellite fire detections in a bounding box, for display. Pass `bbox` [west, south, east, north] (WGS84), optional `types` (quake, volcano, fire; default all), `min_magnitude` (quakes, default 2.5) and `limit` (1 to 500, default 100). Earthquakes are USGS, magnitude 2.5 and above, past 24 hours, as reported (magnitudes and locations may be revised). Volcano alerts are USGS-monitored volcanoes ONLY: an absent alert says nothing about volcanoes elsewhere. Fire cells are NASA FIRMS VIIRS detections thinned to 0.5 degree cells: satellite-detected heat, NOT confirmed fires. Each feed carries `status` (ok, stale, unknown): pass a stale or unknown status on, never present old data as current. This is reported data for display, not a warning service and not safety-critical; keep that qualifier when you pass it on. Requires the MapMap gateway. Display the returned `attribution`, and for fire data the FIRMS `acknowledgment` and `disclaimer`.
| Parameter | Type | Description |
|---|---|---|
| bbox * | array | Bounding box `[west, south, east, north]`, WGS84 degrees. West must be less than east and south less than north; a box crossing the antimeridian is not supported (query two boxes). |
| limit | ["integer","null"] | Most events to return, 1 to 500 (default 100). Newest quakes first, then volcano alerts, then the busiest fire cells. |
| types | ["array","null"] | Which feeds to include: any of `quake`, `volcano`, `fire`. Default: all three. |
| min_magnitude | ["number","null"] | Smallest earthquake magnitude, 2.5 to 9.0 (default 2.5). Quakes only. |
{
"name": "events_in_area",
"description": "Earthquakes, volcano alerts and satellite fire detections in a bounding box, for display. Pass `bbox` [west, south, east, north] (WGS84), optional `types` (quake, volcano, fire; default all), `min_magnitude` (quakes, default 2.5) and `limit` (1 to 500, default 100). Earthquakes are USGS, magnitude 2.5 and above, past 24 hours, as reported (magnitudes and locations may be revised). Volcano alerts are USGS-monitored volcanoes ONLY: an absent alert says nothing about volcanoes elsewhere. Fire cells are NASA FIRMS VIIRS detections thinned to 0.5 degree cells: satellite-detected heat, NOT confirmed fires. Each feed carries `status` (ok, stale, unknown): pass a stale or unknown status on, never present old data as current. This is reported data for display, not a warning service and not safety-critical; keep that qualifier when you pass it on. Requires the MapMap gateway. Display the returned `attribution`, and for fire data the FIRMS `acknowledgment` and `disclaimer`.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"bbox"
],
"properties": {
"bbox": {
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 4,
"minItems": 4,
"description": "Bounding box `[west, south, east, north]`, WGS84 degrees. West must\nbe less than east and south less than north; a box crossing the\nantimeridian is not supported (query two boxes)."
},
"limit": {
"type": [
"integer",
"null"
],
"format": "uint16",
"maximum": 65535,
"minimum": 0,
"description": "Most events to return, 1 to 500 (default 100). Newest quakes\nfirst, then volcano alerts, then the busiest fire cells."
},
"types": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Which feeds to include: any of `quake`, `volcano`, `fire`. Default:\nall three."
},
"min_magnitude": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Smallest earthquake magnitude, 2.5 to 9.0 (default 2.5). Quakes\nonly."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"EventOut": {
"type": "object",
"required": [
"kind",
"id",
"lat",
"lon"
],
"properties": {
"id": {
"type": "string",
"description": "The event's id (a fire cell id is `fire:<south>,<west>`)."
},
"lat": {
"type": "number",
"format": "double",
"description": "Latitude, WGS84 degrees. A fire cell is its 0.5 degree cell centre."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude, WGS84 degrees."
},
"mag": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Quake: magnitude as reported (may be revised)."
},
"url": {
"type": [
"string",
"null"
],
"description": "Quake: USGS event page."
},
"kind": {
"type": "string",
"description": "`quake`, `volcano` or `fire`."
},
"name": {
"type": [
"string",
"null"
],
"description": "Volcano: name."
},
"time": {
"type": [
"string",
"null"
],
"description": "Quake: origin time, RFC 3339 UTC."
},
"count": {
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0,
"description": "Fire: satellite detections inside the cell."
},
"label": {
"type": [
"string",
"null"
],
"description": "Fire: \"Satellite-detected heat, not confirmed fires\". Keep it."
},
"place": {
"type": [
"string",
"null"
],
"description": "Quake: USGS place description, e.g. \"12 km SW of Ridgecrest, CA\"."
},
"derived": {
"type": [
"string",
"null"
],
"description": "Fire: says the cell is derived from detections, not a fire."
},
"max_frp": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Fire: the largest fire radiative power in the cell, megawatts."
},
"sent_at": {
"type": [
"string",
"null"
],
"description": "Volcano: when the notice was sent, RFC 3339 UTC."
},
"acq_date": {
"type": [
"string",
"null"
],
"description": "Fire: the acquisition date (YYYY-MM-DD)."
},
"cell_deg": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Fire: the cell size in degrees (0.5)."
},
"coverage": {
"type": [
"string",
"null"
],
"description": "Volcano: US-monitored volcanoes only; an absent alert says nothing\nabout volcanoes elsewhere."
},
"depth_km": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Quake: depth in kilometres."
},
"color_code": {
"type": [
"string",
"null"
],
"description": "Volcano: USGS aviation colour code as a word (GREEN, YELLOW,\nORANGE, RED)."
},
"notice_url": {
"type": [
"string",
"null"
],
"description": "Volcano: the USGS notice page."
},
"alert_level": {
"type": [
"string",
"null"
],
"description": "Volcano: USGS alert level (NORMAL, ADVISORY, WATCH, WARNING)."
},
"observatory": {
"type": [
"string",
"null"
],
"description": "Volcano: the monitoring observatory."
},
"high_confidence_share": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Fire: share of detections the satellite flags high confidence, 0\nto 1."
}
},
"description": "One earthquake, volcano alert or fire cell."
},
"EventsFeedOut": {
"type": "object",
"required": [
"status"
],
"properties": {
"age_s": {
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0,
"description": "Seconds since `fetched_at` when the gateway assembled the answer."
},
"source": {
"type": [
"string",
"null"
],
"description": "The feed's source, in words."
},
"status": {
"type": "string",
"description": "`ok` (fetched within the threshold), `stale` (older; features are\nstill returned, so say they are paused) or `unknown` (no data for\nthis feed). Never present stale or unknown data as current."
},
"detections": {
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0,
"description": "Fires only: raw satellite detections behind the thinned cells."
},
"fetched_at": {
"type": [
"string",
"null"
],
"description": "When the box last fetched the feed (RFC 3339), if known."
},
"threshold_s": {
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0,
"description": "The age in seconds after which the feed counts as stale."
},
"count_in_file": {
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0,
"description": "Events in the feed's file before the box and filters were applied."
}
},
"description": "One feed's freshness, as the gateway reports it."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"feeds",
"count",
"truncated",
"events",
"summary",
"label",
"coverage",
"attribution",
"acknowledgment",
"disclaimer",
"endorsement"
],
"properties": {
"count": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "Events returned."
},
"feeds": {
"type": "object",
"description": "Freshness of each requested feed, keyed `quake`, `volcano`, `fire`.",
"additionalProperties": {
"$ref": "#/$defs/EventsFeedOut"
}
},
"label": {
"type": "string",
"description": "Reported events for display; not a warning service. Pass it on."
},
"events": {
"type": "array",
"items": {
"$ref": "#/$defs/EventOut"
},
"description": "The events: newest quakes, then volcano alerts, then fire cells."
},
"summary": {
"type": "string",
"description": "One sentence built from the counts. Pass it on with its qualifier."
},
"coverage": {
"type": "string",
"description": "What each feed does and does not cover. Pass it on."
},
"truncated": {
"type": "boolean",
"description": "True when the limit cut the list short."
},
"disclaimer": {
"type": "string",
"description": "NASA FIRMS \"as is\" disclaimer. Display it with fire data."
},
"attribution": {
"type": "object",
"description": "Source credits, keyed by feed. Display them.",
"additionalProperties": {
"type": "string"
}
},
"endorsement": {
"type": "string",
"description": "No endorsement by or affiliation with USGS, NOAA or NASA is\nimplied."
},
"acknowledgment": {
"type": "string",
"description": "NASA FIRMS acknowledgment. Display it with fire data."
}
}
}
}Area in square metres enclosed by a ring of 3+ coordinates, computed geodesically. Always positive: the answer does not depend on whether the ring is wound clockwise or anticlockwise. Intended for zones and boundaries, not for polygons covering more than half the globe. Local computation: no network call, no quota.
| Parameter | Type | Description |
|---|---|---|
| points * | array | The coordinates to consider. |
{
"name": "geo_area",
"description": "Area in square metres enclosed by a ring of 3+ coordinates, computed geodesically. Always positive: the answer does not depend on whether the ring is wound clockwise or anticlockwise. Intended for zones and boundaries, not for polygons covering more than half the globe. Local computation: no network call, no quota.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"points"
],
"properties": {
"points": {
"type": "array",
"items": {
"$ref": "#/$defs/LatLon"
},
"description": "The coordinates to consider."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"area_sq_m"
],
"properties": {
"area_sq_m": {
"type": "number",
"format": "double",
"description": "Enclosed area in square metres, always positive regardless of\nwinding order."
}
}
}
}The axis-aligned bounding box enclosing 1+ coordinates, as {min_lat, min_lon, max_lat, max_lon}. Useful for fitting a map view to a set of stops. Local computation: no network call, no quota.
| Parameter | Type | Description |
|---|---|---|
| points * | array | The coordinates to consider. |
{
"name": "geo_bbox",
"description": "The axis-aligned bounding box enclosing 1+ coordinates, as {min_lat, min_lon, max_lat, max_lon}. Useful for fitting a map view to a set of stops. Local computation: no network call, no quota.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"points"
],
"properties": {
"points": {
"type": "array",
"items": {
"$ref": "#/$defs/LatLon"
},
"description": "The coordinates to consider."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"min_lat",
"min_lon",
"max_lat",
"max_lon"
],
"properties": {
"max_lat": {
"type": "number",
"format": "double",
"description": "Maximum latitude (north edge)."
},
"max_lon": {
"type": "number",
"format": "double",
"description": "Maximum longitude (east edge)."
},
"min_lat": {
"type": "number",
"format": "double",
"description": "Minimum latitude (south edge)."
},
"min_lon": {
"type": "number",
"format": "double",
"description": "Minimum longitude (west edge)."
}
}
}
}Initial bearing from one coordinate to another, in degrees clockwise from true north (0-360). This is the bearing at the START of the geodesic; over long distances the bearing changes en route. Local computation: no network call, no quota.
| Parameter | Type | Description |
|---|---|---|
| to * | ref | End coordinate. |
| from * | ref | Start coordinate. |
{
"name": "geo_bearing",
"description": "Initial bearing from one coordinate to another, in degrees clockwise from true north (0-360). This is the bearing at the START of the geodesic; over long distances the bearing changes en route. Local computation: no network call, no quota.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"from",
"to"
],
"properties": {
"to": {
"$ref": "#/$defs/LatLon",
"description": "End coordinate."
},
"from": {
"$ref": "#/$defs/LatLon",
"description": "Start coordinate."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"bearing_deg"
],
"properties": {
"bearing_deg": {
"type": "number",
"format": "double",
"description": "Initial bearing from `from` to `to`, degrees clockwise from true\nnorth, normalised to 0–360. Note this is the bearing at the start\nof the geodesic: over long distances the bearing changes en route."
}
}
}
}The centroid (geometric mean position) of 1+ coordinates, e.g. to pick a depot location or centre a map. Local computation: no network call, no quota.
| Parameter | Type | Description |
|---|---|---|
| points * | array | The coordinates to consider. |
{
"name": "geo_centroid",
"description": "The centroid (geometric mean position) of 1+ coordinates, e.g. to pick a depot location or centre a map. Local computation: no network call, no quota.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"points"
],
"properties": {
"points": {
"type": "array",
"items": {
"$ref": "#/$defs/LatLon"
},
"description": "The coordinates to consider."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"point"
],
"properties": {
"point": {
"$ref": "#/$defs/LatLon",
"description": "The computed coordinate."
}
}
}
}The coordinate reached by travelling `distance_m` metres from `from` on `bearing_deg` (degrees clockwise from true north). The inverse of `geo_distance` + `geo_bearing`. Local computation: no network call.
| Parameter | Type | Description |
|---|---|---|
| from * | ref | Starting coordinate. |
| distance_m * | number | Distance to travel in metres. |
| bearing_deg * | number | Bearing in degrees clockwise from true north. |
{
"name": "geo_destination",
"description": "The coordinate reached by travelling `distance_m` metres from `from` on `bearing_deg` (degrees clockwise from true north). The inverse of `geo_distance` + `geo_bearing`. Local computation: no network call.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"from",
"bearing_deg",
"distance_m"
],
"properties": {
"from": {
"$ref": "#/$defs/LatLon",
"description": "Starting coordinate."
},
"distance_m": {
"type": "number",
"format": "double",
"description": "Distance to travel in metres."
},
"bearing_deg": {
"type": "number",
"format": "double",
"description": "Bearing in degrees clockwise from true north."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"point"
],
"properties": {
"point": {
"$ref": "#/$defs/LatLon",
"description": "The computed coordinate."
}
}
}
}Distance in metres between two coordinates. Computed geodesically on the WGS84 ellipsoid, so it is the straight-line (as-the-crow-flies) distance, NOT a driving distance, use `route` or `matrix` for travel distance and time. Local computation: no network call, no quota.
| Parameter | Type | Description |
|---|---|---|
| to * | ref | End coordinate. |
| from * | ref | Start coordinate. |
{
"name": "geo_distance",
"description": "Distance in metres between two coordinates. Computed geodesically on the WGS84 ellipsoid, so it is the straight-line (as-the-crow-flies) distance, NOT a driving distance, use `route` or `matrix` for travel distance and time. Local computation: no network call, no quota.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"from",
"to"
],
"properties": {
"to": {
"$ref": "#/$defs/LatLon",
"description": "End coordinate."
},
"from": {
"$ref": "#/$defs/LatLon",
"description": "Start coordinate."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"distance_m"
],
"properties": {
"distance_m": {
"type": "number",
"format": "double",
"description": "Distance in metres along the WGS84 ellipsoid."
}
}
}
}Total length in metres of a polyline through 2+ coordinates, summed geodesically. This measures the line you supply, NOT a driven route , use `route` for that. Local computation: no network call, no quota.
| Parameter | Type | Description |
|---|---|---|
| points * | array | The coordinates to consider. |
{
"name": "geo_length",
"description": "Total length in metres of a polyline through 2+ coordinates, summed geodesically. This measures the line you supply, NOT a driven route , use `route` for that. Local computation: no network call, no quota.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"points"
],
"properties": {
"points": {
"type": "array",
"items": {
"$ref": "#/$defs/LatLon"
},
"description": "The coordinates to consider."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"length_m"
],
"properties": {
"length_m": {
"type": "number",
"format": "double",
"description": "Total geodesic length in metres."
}
}
}
}The closest position on a polyline to a given coordinate, plus the geodesic distance to it in metres. The answer may lie between vertices, not only on them. Useful for 'how far is this address from the route?'. Local computation: no network call, no quota.
| Parameter | Type | Description |
|---|---|---|
| line * | array | The polyline's coordinates, 2 or more. |
| point * | ref | The coordinate to measure from. |
{
"name": "geo_nearest_point_on_line",
"description": "The closest position on a polyline to a given coordinate, plus the geodesic distance to it in metres. The answer may lie between vertices, not only on them. Useful for 'how far is this address from the route?'. Local computation: no network call, no quota.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"point",
"line"
],
"properties": {
"line": {
"type": "array",
"items": {
"$ref": "#/$defs/LatLon"
},
"description": "The polyline's coordinates, 2 or more."
},
"point": {
"$ref": "#/$defs/LatLon",
"description": "The coordinate to measure from."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"point",
"distance_m"
],
"properties": {
"point": {
"$ref": "#/$defs/LatLon",
"description": "The closest position on the line, which may lie between vertices."
},
"distance_m": {
"type": "number",
"format": "double",
"description": "Geodesic distance from the input point to that position, metres."
}
}
}
}Whether a coordinate lies inside a polygon: delivery zones, catchments, congestion or clean-air zones, site boundaries. Provide `point` {lat, lon} and `polygon` as 3+ {lat, lon} coordinates of the outer ring (closed automatically if the last does not repeat the first). Points exactly on the boundary count as OUTSIDE. Local computation: no network call, no quota.
| Parameter | Type | Description |
|---|---|---|
| point * | ref | The coordinate to test. |
| polygon * | array | The polygon's outer ring, 3 or more coordinates. Closed automatically if the last point does not repeat the first. |
{
"name": "geo_point_in_polygon",
"description": "Whether a coordinate lies inside a polygon: delivery zones, catchments, congestion or clean-air zones, site boundaries. Provide `point` {lat, lon} and `polygon` as 3+ {lat, lon} coordinates of the outer ring (closed automatically if the last does not repeat the first). Points exactly on the boundary count as OUTSIDE. Local computation: no network call, no quota.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"point",
"polygon"
],
"properties": {
"point": {
"$ref": "#/$defs/LatLon",
"description": "The coordinate to test."
},
"polygon": {
"type": "array",
"items": {
"$ref": "#/$defs/LatLon"
},
"description": "The polygon's outer ring, 3 or more coordinates. Closed\nautomatically if the last point does not repeat the first."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"inside"
],
"properties": {
"inside": {
"type": "boolean",
"description": "True when the point is strictly inside the ring. Points exactly on\nthe boundary are **not** counted as inside."
}
}
}
}Reduce the number of coordinates in a polyline while keeping its shape (Douglas-Peucker). `tolerance_deg` is in DEGREES, not metres: about 0.0001 drops detail finer than roughly 10 m at the equator. Endpoints are always kept. Returns the retained points and how many were removed. Local computation: no network call, no quota.
| Parameter | Type | Description |
|---|---|---|
| points * | array | The polyline's coordinates, 2 or more. |
| tolerance_deg * | number | Douglas-Peucker tolerance in **degrees**, not metres. Around 0.0001 drops detail finer than roughly 10 m at the equator. |
{
"name": "geo_simplify",
"description": "Reduce the number of coordinates in a polyline while keeping its shape (Douglas-Peucker). `tolerance_deg` is in DEGREES, not metres: about 0.0001 drops detail finer than roughly 10 m at the equator. Endpoints are always kept. Returns the retained points and how many were removed. Local computation: no network call, no quota.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"points",
"tolerance_deg"
],
"properties": {
"points": {
"type": "array",
"items": {
"$ref": "#/$defs/LatLon"
},
"description": "The polyline's coordinates, 2 or more."
},
"tolerance_deg": {
"type": "number",
"format": "double",
"description": "Douglas-Peucker tolerance in **degrees**, not metres. Around\n0.0001 drops detail finer than roughly 10 m at the equator."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"points",
"removed"
],
"properties": {
"points": {
"type": "array",
"items": {
"$ref": "#/$defs/LatLon"
},
"description": "The retained coordinates, endpoints always preserved."
},
"removed": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "How many coordinates were removed."
}
}
}
}Turn a place (address, POI, town) into coordinates. Ask two ways, and they combine: `query` is free text, one run-together string, the way a person types into a search box, and `street`, `housenumber`, `city`, `postcode` and `country` name the parts of an address separately. At least one of the two is required. Pass the parts whenever you already hold the address in parts (a form, a CRM row, a manifest): components are REQUIREMENTS, not hints, so `city: "London"` means a result outside London cannot come back at all, where "London" inside `query` only reorders. `country` takes an ISO 3166-1 alpha-2 code or a country name ("GB", "United Kingdom"); a value naming no country is refused rather than silently matching nothing. Returns up to `limit` (default 10) candidates with name, one-line label, lat/lon, type and address parts. Pass `focus` {lat, lon} to rank results near a location higher. A bare city or town name (no comma) lists that city's airports and main railway stations directly behind it, ahead of namesakes elsewhere. Each hit also carries `match`: a per-component matched/inferred/unmatched verdict, the `score_gap` to the runner-up, and which backend answered. READ IT before acting on an address, an unmatched or inferred postcode on the top hit means the answer does not carry the address you asked for, and a small `score_gap` means the ranking barely chose, so show the alternatives instead of picking one. Use `verify_places` when the address came from a model or a user and needs checking rather than using. Results are matched in `lang` (default "en"), so English exonyms ("Munich", "Cologne", "Geneva") resolve to the place meant; pass `lang` when querying in another language, or "default" for each place's local name.
| Parameter | Type | Description |
|---|---|---|
| city | ["string","null"] | Structured component: town or city, e.g. "London". Matches the containing city as well as the immediate locality, so a suburb name works here too. |
| lang | ["string","null"] | Language of the place names to match and return, as a two-letter code. Defaults to "en", which is what makes English exonyms ("Munich", "Cologne", "Geneva") resolve to the place meant rather than a same-named town elsewhere. Set it to the language your query is written in; "default" asks for each pl… |
| focus | any |
Read an asynchronous job submitted with `submit_optimise_job`: its status, and once it has finished, its result inline, exactly the body the synchronous tool would have returned. Status is `queued`, `running`, `succeeded` or `failed`; the answer's `terminal` field says whether the job will ever leave the status it is in, so poll while that is false. POLLING IS FREE: the gateway meters the submission and not the reads, deliberately, because a poll that costs quota is a poll a caller rations, and a rationed poll is how a job that finished in ten seconds gets noticed four minutes later. Check every few seconds rather than guessing at a duration. `units_charged` is what the SUBMISSION drew, and `refunded` says whether a failure handed it back, a failed job shows both, because reporting zero would be a lie about what was charged. Webhooks are the alternative to polling and exist for humans wiring infrastructure, not for agents in a loop. A job belongs to the key that submitted it (or another key of the same identity); anyone else's id answers NOT FOUND rather than forbidden, because confirming an id exists is itself a disclosure. Requires the MapMap gateway.
| Parameter | Type | Description |
|---|---|---|
| id * | string | The job id returned by `submit_optimise_job`. |
{
"name": "get_job",
"description": "Read an asynchronous job submitted with `submit_optimise_job`: its status, and once it has finished, its result inline, exactly the body the synchronous tool would have returned. Status is `queued`, `running`, `succeeded` or `failed`; the answer's `terminal` field says whether the job will ever leave the status it is in, so poll while that is false. POLLING IS FREE: the gateway meters the submission and not the reads, deliberately, because a poll that costs quota is a poll a caller rations, and a rationed poll is how a job that finished in ten seconds gets noticed four minutes later. Check every few seconds rather than guessing at a duration. `units_charged` is what the SUBMISSION drew, and `refunded` says whether a failure handed it back, a failed job shows both, because reporting zero would be a lie about what was charged. Webhooks are the alternative to polling and exist for humans wiring infrastructure, not for agents in a loop. A job belongs to the key that submitted it (or another key of the same identity); anyone else's id answers NOT FOUND rather than forbidden, because confirming an id exists is itself a disclosure. Requires the MapMap gateway.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The job id returned by `submit_optimise_job`."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id",
"kind",
"status",
"terminal",
"created_at",
"units_charged",
"refunded"
],
"properties": {
"id": {
"type": "string",
"description": "The job id."
},
"kind": {
"type": "string",
"description": "`optimise`, `replan`, `matrix` or `coverage`."
},
"error": {
"type": [
"string",
"null"
],
"description": "Why it failed, once `status` is `failed`."
},
"result": {
"description": "The answer, inline, once `status` is `succeeded`, exactly the body\nthe synchronous tool would have returned (for `coverage`, which has\nnone, the gateway's plan unchanged). A matrix job answers\n`durations_s` and `distances_m`, as the `matrix` tool does; it also\nstill carries the same numbers as `durations` and `distances`, which\nare DEPRECATED and will be removed in a future release."
},
"status": {
"type": "string",
"description": "`queued`, `running`, `succeeded` or `failed`. Only `succeeded` and\n`failed` are terminal; keep polling on the other two."
},
"refunded": {
"type": "boolean",
"description": "Whether a failure refunded the submission's units."
},
"terminal": {
"type": "boolean",
"description": "Whether `status` is one this job will never leave."
},
"created_at": {
"type": "string",
"description": "RFC 3339 UTC submission time."
},
"started_at": {
"type": [
"string",
"null"
],
"description": "RFC 3339 UTC time a worker picked it up."
},
"finished_at": {
"type": [
"string",
"null"
],
"description": "RFC 3339 UTC time it finished, either way."
},
"units_charged": {
"type": "integer",
"format": "int64",
"description": "Metered units the SUBMISSION drew. This is what was charged;\n`refunded` says whether it came back."
},
"webhook_status": {
"type": [
"string",
"null"
],
"description": "`delivered` or `delivery_failed`, once a webhook was attempted."
}
}
}
}Fetch a hosted style's latest theme document (the editable source) and the URL of its latest compiled MapLibre style. Use the theme to inspect current palette and layer overrides before editing.
| Parameter | Type | Description |
|---|---|---|
| style_id * | string | Hosted style id, e.g. "midnight-fleet-a1b2c3". |
{
"name": "get_style",
"description": "Fetch a hosted style's latest theme document (the editable source) and the URL of its latest compiled MapLibre style. Use the theme to inspect current palette and layer overrides before editing.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"style_id"
],
"properties": {
"style_id": {
"type": "string",
"description": "Hosted style id, e.g. \"midnight-fleet-a1b2c3\"."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"style_id",
"style_url",
"theme"
],
"properties": {
"theme": {
"description": "The latest theme document, the editable source the next version\nis published from."
},
"style_id": {
"type": "string",
"description": "Hosted style id."
},
"style_url": {
"type": "string",
"description": "URL of the latest compiled MapLibre style (point MapLibre GL at\nit)."
}
}
}
}Check what your own API key has spent, so you can decide mid-task whether to keep going. Reading it is free: it costs no quota. Optional `from` and `to` (YYYY-MM-DD UTC, inclusive, at most 92 days apart) bound the report; omitted, it covers the current month to date. Returns `days` (per-day, per-endpoint), `totals` per endpoint over the range, `total_units`, plus `month_used_units` against `monthly_quota_units` and the prepaid `balance_millipence` (thousandths of a penny). Everything is counted in UNITS, weighted quota units, where a heavier endpoint costs more than one unit per request, so never report these figures as a number of calls. When `identity_pooled` is true the quota is shared with the other keys belonging to the same owner, so these figures are not yours alone. The key that authenticates the call is the key reported on: there is no way to read another caller's usage. On the hosted endpoint, connect with your own key (a bearer `snk_` key or OAuth sign-in): an anonymous connection is refused rather than shown the server operator's usage. Needs the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY).
| Parameter | Type | Description |
|---|---|---|
| to | ["string","null"] | Last day to report, `YYYY-MM-DD` (UTC) inclusive. Defaults to today. |
| from | ["string","null"] | First day to report, `YYYY-MM-DD` (UTC) inclusive. Defaults to the first day of the current month. At most 92 days may separate `from` and `to`. |
{
"name": "get_usage",
"description": "Check what your own API key has spent, so you can decide mid-task whether to keep going. Reading it is free: it costs no quota. Optional `from` and `to` (YYYY-MM-DD UTC, inclusive, at most 92 days apart) bound the report; omitted, it covers the current month to date. Returns `days` (per-day, per-endpoint), `totals` per endpoint over the range, `total_units`, plus `month_used_units` against `monthly_quota_units` and the prepaid `balance_millipence` (thousandths of a penny). Everything is counted in UNITS, weighted quota units, where a heavier endpoint costs more than one unit per request, so never report these figures as a number of calls. When `identity_pooled` is true the quota is shared with the other keys belonging to the same owner, so these figures are not yours alone. The key that authenticates the call is the key reported on: there is no way to read another caller's usage. On the hosted endpoint, connect with your own key (a bearer `snk_` key or OAuth sign-in): an anonymous connection is refused rather than shown the server operator's usage. Needs the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY).",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"to": {
"type": [
"string",
"null"
],
"description": "Last day to report, `YYYY-MM-DD` (UTC) inclusive. Defaults to\ntoday."
},
"from": {
"type": [
"string",
"null"
],
"description": "First day to report, `YYYY-MM-DD` (UTC) inclusive. Defaults to the\nfirst day of the current month. At most 92 days may separate\n`from` and `to`."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"UsageDay": {
"type": "object",
"required": [
"day",
"endpoints",
"total_units"
],
"properties": {
"day": {
"type": "string",
"description": "The day, `YYYY-MM-DD`."
},
"endpoints": {
"type": "array",
"items": {
"$ref": "#/$defs/UsageEndpointTotal"
},
"description": "Units per endpoint on this day, heaviest first."
},
"total_units": {
"type": "integer",
"format": "int64",
"description": "Total units on this day."
}
},
"description": "One day's usage, in units per endpoint."
},
"UsageEndpointTotal": {
"type": "object",
"required": [
"endpoint",
"units"
],
"properties": {
"units": {
"type": "integer",
"format": "int64",
"description": "Weighted quota units, never a count of calls."
},
"endpoint": {
"type": "string",
"description": "The endpoint label the meter records, e.g. `/route`, `/geocode`,\n`/tiles`. Labels are collapsed by the meter, so several request\nshapes can share one."
}
},
"description": "Units attributed to one endpoint."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"key_id",
"identity_pooled",
"from",
"to",
"days",
"totals",
"total_units",
"month_used_units",
"monthly_quota_units",
"balance_millipence"
],
"properties": {
"to": {
"type": "string",
"description": "Last day covered, `YYYY-MM-DD` inclusive."
},
"days": {
"type": "array",
"items": {
"$ref": "#/$defs/UsageDay"
},
"description": "Per-day breakdown over the range, oldest first. A day with no\nusage is absent rather than reported as zero."
},
"from": {
"type": "string",
"description": "First day covered, `YYYY-MM-DD` inclusive."
},
"key_id": {
"type": "string",
"description": "Identifier of the key this usage belongs to."
},
"totals": {
"type": "array",
"items": {
"$ref": "#/$defs/UsageEndpointTotal"
},
"description": "Units per endpoint over the whole range."
},
"total_units": {
"type": "integer",
"format": "int64",
"description": "Total units over the whole range."
},
"identity_pooled": {
"type": "boolean",
"description": "Whether quota is pooled across every key belonging to the same\nidentity. When true, these figures are the identity's shared\nconsumption, so another key of the same owner also spends them."
},
"month_used_units": {
"type": "integer",
"format": "int64",
"description": "Units counted against the monthly quota right now: the very number\nthe quota check enforces on, independent of `from`/`to`. Quota is\nmonthly, so this (not `total_units`) is what to compare with\n`monthly_quota_units`. It includes units recorded but not yet\nwritten to the daily counters, so over a whole-month range it can\nexceed `total_units`; that is not a discrepancy."
},
"balance_millipence": {
"type": "integer",
"format": "int64",
"description": "Prepaid balance in millipence (thousandths of a penny), for usage\nbeyond the monthly allowance."
},
"monthly_quota_units": {
"type": "integer",
"format": "int64",
"description": "The key's monthly allowance in units."
}
}
}
}Three to five short spoken lines an hour about the ground a route is on: one sentence, at the point the driver reaches the thing it is about, and then silence. Not a tour and not a chatbot. NOTHING IS GENERATED HERE: every line is a sentence a person wrote from a public-domain plaque inscription and a person reviewed, compiled into the gateway binary, so no model runs in this path and the lines are identical for every driver. Give `geometry_polyline6` from the `route` tool and, IMPORTANT, `duration_s` from the same answer: without it the silence budget falls back to a distance, and "four lines an hour" is a claim about time that a distance answers wrongly at both ends. Optional `min_gap_s`, `min_gap_m`, `max_offset_m` (default 60, hard ceiling 80), `max_lines` and `voice_format` ("opus" or "m4a", which adds each line's audio cache key and URL and NEVER synthesises). COVERAGE IS ONE CORRIDOR, deliberately: the Chelsea riverside, 18 reviewed lines over 5 km. EVERY OTHER ROUTE ANSWERS WITH NO LINES, and that is a correct answer rather than a failure. ALWAYS READ THE CENSUS, which is the record of WHAT WAS NOT SAID: no lines with every entry in `beyond_reach` means this feature does not cover the journey; no lines with entries in `silenced_by_budget` means the corridor is covered and the budget is holding them back. They are different answers and must never be relayed the same way. On the reference route the census reports 1 spoken and 17 silenced, which is the design working, not a thin corpus. Every line publishes `offset_m`, the measured distance from the plaque to the route, because it is the entire warrant for the word "here", and `plaque_ids` so any claim can be taken back to its source. TWO OMISSIONS ARE DELIBERATE: no line says anything is visible, still standing or unchanged (a plaque records that somebody was somewhere, and nothing more), and NO LINE SAYS WHICH SIDE OF THE ROAD anything is on, because nothing in the source records it and a look that finds nothing spends the driver's trust in everything else. Do not add either. COSTS 1 UNIT a call: it reads no tiles and opens no archive. Requires the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY).
| Parameter | Type | Description |
|---|---|---|
| max_lines | ["integer","null"] | Ceiling on how many lines come back, 1 to 50 (default 12). |
| min_gap_m | ["number","null"] | Least distance between two lines, metres (default 400). A floor under the time budget in every case. |
List the canonical place categories you can pass as `category` to `nearby_places` and `search_along_route` (and browse on with `geocode`). Each entry is a `category` token (the exact value to send, e.g. "fuel", "charging_station", "hgv_parking"), the `aliases` that colloquially name it ("petrol station", "EV charger", "lorry park"), and a one-line `description` of what it covers. Read this before guessing a category: a token that is not on this list matches nothing, and quietly returns an empty result rather than an error. Cuisines, brands and names are NOT categories, search those as free text. Sorted by category and identical on every call. Local lookup, no network, no quota.
No parameters.
{
"name": "list_place_categories",
"description": "List the canonical place categories you can pass as `category` to `nearby_places` and `search_along_route` (and browse on with `geocode`). Each entry is a `category` token (the exact value to send, e.g. \"fuel\", \"charging_station\", \"hgv_parking\"), the `aliases` that colloquially name it (\"petrol station\", \"EV charger\", \"lorry park\"), and a one-line `description` of what it covers. Read this before guessing a category: a token that is not on this list matches nothing, and quietly returns an empty result rather than an error. Cuisines, brands and names are NOT categories, search those as free text. Sorted by category and identical on every call. Local lookup, no network, no quota.",
"inputSchema": {
"type": "object",
"properties": {}
},
"outputSchema": {
"type": "object",
"$defs": {
"PlaceCategory": {
"type": "object",
"required": [
"category",
"aliases",
"description"
],
"properties": {
"aliases": {
"type": "array",
"items": {
"type": "string"
},
"description": "Colloquial phrases that resolve to this category, sorted. Passing\none of these as free text works too, but the canonical `category`\nis exact."
},
"category": {
"type": "string",
"description": "The canonical token to pass as a category filter, e.g. `fuel`."
},
"description": {
"type": "string",
"description": "What the category covers, in one line."
}
},
"description": "One canonical place category, the phrases that name it, and what it\ncovers."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"categories"
],
"properties": {
"categories": {
"type": "array",
"items": {
"$ref": "#/$defs/PlaceCategory"
},
"description": "Every category `nearby_places`, `search_along_route` and `geocode`\nrecognise, sorted alphabetically by `category`."
}
}
}
}List everything a MapMap style theme can style: the first-party named bases a style can start from (pass one as `create_style`'s `base`, or as the static-map API's `style=`), the named palette slots with their light/dark default colours, the skeleton layer ids (paint order) that `set_layer_paint` and `set_layer_layout` accept, what the less obvious layers draw (the footpath layers `road-path` and `road-path-*` for footways, cycleways, steps, bridleways, pedestrian streets and tracks, pedestrian squares `pedestrian-areas`) and the slot that colours each, the OpenMapTiles source-layers extra layers may reference, the insertion slots (`bottom`, `middle`, `top`) an extra layer may name, and the rules for a theme's own `sources` (your data by https URL). Attribution is enforced on every compiled style and cannot be themed away. Local lookup, no network; always works.
No parameters.
{
"name": "list_style_layers",
"description": "List everything a MapMap style theme can style: the first-party named bases a style can start from (pass one as `create_style`'s `base`, or as the static-map API's `style=`), the named palette slots with their light/dark default colours, the skeleton layer ids (paint order) that `set_layer_paint` and `set_layer_layout` accept, what the less obvious layers draw (the footpath layers `road-path` and `road-path-*` for footways, cycleways, steps, bridleways, pedestrian streets and tracks, pedestrian squares `pedestrian-areas`) and the slot that colours each, the OpenMapTiles source-layers extra layers may reference, the insertion slots (`bottom`, `middle`, `top`) an extra layer may name, and the rules for a theme's own `sources` (your data by https URL). Attribution is enforced on every compiled style and cannot be themed away. Local lookup, no network; always works.",
"inputSchema": {
"type": "object",
"properties": {}
},
"outputSchema": {
"type": "object",
"$defs": {
"StyleBaseInfo": {
"type": "object",
"required": [
"id",
"label",
"description",
"group",
"restrictions"
],
"properties": {
"id": {
"type": "string",
"description": "Base id: what `create_style`'s `base` and the static-map API's\n`style=` accept, e.g. \"navigator-night\"."
},
"group": {
"type": "string",
"description": "\"base\" for the two stock slates (`light`, `dark`), \"designed\" for a\ndrawn style."
},
"label": {
"type": "string",
"description": "Short display label, e.g. \"Navigator Night\"."
},
"description": {
"type": "string",
"description": "One line saying what the base is for. This is what to choose on."
},
"restrictions": {
"type": "boolean",
"description": "True when the base is drawn to sit under MapMap's\nvehicle-restriction overlay (only `fleet`). That overlay is a\nmapmap.ai runtime layer, not tile data and not part of any compiled\nstyle, so it draws in Studio and on /map and nowhere else. Asking\nfor this base anywhere else gets the palette alone; for a real\nrestriction answer use `check_clearance_on_route` or\n`check_adr_tunnel`, which answer for an actual vehicle."
}
},
"description": "One entry in the named-base catalogue (`sn_style::list_bases`)."
},
"StyleSlotInfo": {
"type": "object",
"required": [
"slot",
"before",
"description"
],
"properties": {
"slot": {
"type": "string",
"description": "`bottom`, `middle` or `top`."
},
"before": {
"type": "string",
"description": "The skeleton layer id the slot sits directly below."
},
"description": {
"type": "string",
"description": "Where it sits, in words."
}
},
"description": "One insertion slot for extra layers (Mapbox Standard names)."
},
"PaletteSlotInfo": {
"type": "object",
"required": [
"slot",
"light",
"dark"
],
"properties": {
"dark": {
"type": "string",
"description": "Default colour on the dark base theme."
},
"slot": {
"type": "string",
"description": "Slot name, e.g. \"water\" or \"roadMajor\"."
},
"light": {
"type": "string",
"description": "Default colour on the light base theme."
}
},
"description": "One themable palette slot with its built-in light/dark defaults."
},
"StyleSourcesInfo": {
"type": "object",
"required": [
"types",
"max_sources",
"max_geojson_sources",
"url_rules"
],
"properties": {
"types": {
"type": "array",
"items": {
"type": "string"
},
"description": "Accepted source types."
},
"url_rules": {
"type": "string",
"description": "The URL rules every source URL must pass."
},
"max_sources": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "At most this many sources per theme."
},
"max_geojson_sources": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "At most this many of them `geojson`."
}
},
"description": "What a theme's `sources` block accepts."
},
"StyleLayerDescription": {
"type": "object",
"required": [
"layer_id",
"palette_slot",
"draws"
],
"properties": {
"draws": {
"type": "string",
"description": "What it draws, in words."
},
"layer_id": {
"type": "string",
"description": "The skeleton layer id, e.g. \"road-path\"."
},
"palette_slot": {
"type": "string",
"description": "The palette slot that colours it, e.g. \"path\"."
}
},
"description": "What one skeleton layer draws."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"bases",
"palette_slots",
"layer_ids",
"layer_descriptions",
"source_layers",
"slots",
"sources",
"attribution"
],
"properties": {
"bases": {
"type": "array",
"items": {
"$ref": "#/$defs/StyleBaseInfo"
},
"description": "The first-party named bases a style can start from, in display\norder: pass one to `create_style`'s `base`, or to the static-map\nAPI's `style=`."
},
"slots": {
"type": "array",
"items": {
"$ref": "#/$defs/StyleSlotInfo"
},
"default": [],
"description": "The insertion slots an extra layer may name (`\"slot\"`), bottom of\nthe stack first, with the layer each sits directly below. A layer\nwithout a slot goes in `middle`."
},
"sources": {
"anyOf": [
{
"$ref": "#/$defs/StyleSourcesInfo"
},
{
"type": "null"
}
],
"default": null,
"description": "The rules for a theme's own `sources` (customer data by URL)."
},
"layer_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "The skeleton layer ids a theme's `layers` may override, in paint\norder (first = bottom)."
},
"attribution": {
"type": "string",
"description": "The attribution contract: enforced on every compiled style, not\nthemable."
},
"palette_slots": {
"type": "array",
"items": {
"$ref": "#/$defs/PaletteSlotInfo"
},
"description": "The named palette slots a theme's `palette` may override, with\ntheir light/dark defaults, in presentation order."
},
"source_layers": {
"type": "array",
"items": {
"type": "string"
},
"description": "The OpenMapTiles source-layers the tiles emit; an extra layer on\nthe `territory` source must reference one of these."
},
"layer_descriptions": {
"type": "array",
"items": {
"$ref": "#/$defs/StyleLayerDescription"
},
"default": [],
"description": "What a layer draws and the palette slot that colours it, for the\nlayers whose id alone does not say (footpaths and pedestrian\nsquares)."
}
}
}
}Snap a recorded GPS trace to the road network and say what it actually travelled over. Provide `shape` (2 to 2000 recorded points, oldest first) or `encoded_polyline` (the same trace as a polyline6 string) (not both) plus the `costing` it was travelled under: "auto" (default), "truck", "bicycle", "pedestrian" or "motor_scooter". Costing decides which roads the trace may match onto, so a walk matched as "auto" snaps to the carriageway rather than the footpath. Returns the matched path as `geometry_polyline6` (the snapped roads, not your raw points) with its `distance_m` and `duration_s`, then the roll-ups: `by_road_class` and `by_admin` (distance and time, longest first), `by_surface` (distance), and `toll`, `bridge` and `tunnel` totals. This is how you turn a dashcam or telematics log into a report, which country and region the driving happened in, how much of it was motorway, how much was tolled, how much was unpaved. Honesty: the roll-ups are summed per matched road segment, so they need not add up to `distance_m` exactly, and segments the map records no surface or admin area for are left out of that breakdown rather than filed under a guess, an entry in `by_admin` with null codes is exactly that, counted and not attributed. Needs the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY); there is no direct-backend fallback.
| Parameter | Type | Description |
|---|---|---|
| shape | ["array","null"] | The trace as an ordered list of recorded points, oldest first. Between 2 and 2000 points. Provide this or `encoded_polyline`. |
| costing | any | Costing model the trace was travelled under: `auto` (default), `truck`, `bicycle`, `pedestrian` or `motor_scooter`. It decides which roads the trace may be matched onto, so a walked trace matched as `auto` snaps to the carriageway rather than the path. |
| encoded_polyline | ["string","null"] | The trace as a Google encoded polyline with six digits of decimal precision (polyline6), the geometry `route` and `match_trace` themselves return. Provide this or `shape`. |
Compute a travel time/distance matrix between origins (rows) and destinations (columns). Costing "auto", "truck" (with optional `truck` profile as in `route`), "bicycle", "pedestrian" or "motor_scooter". Returns durations_s[i][j] in seconds and distances_m[i][j] in metres; null cells are unreachable pairs. Up to 10,000 cells per call (origins × destinations). Optional `exclude_polygons` for before/after scenarios ("close this bridge and recompute the matrix"): an array of polygons, each an array of [lon, lat] pairs forming one ring (longitude FIRST) whose intersecting roads are excluded from every cell's path finding. Applies to the Valhalla engine; unsupported on the GraphHopper engine, where it is ignored.
| Parameter | Type | Description |
|---|---|---|
| truck | any | Truck profile (dimensions + ADR declaration). Requires costing "truck". |
| costing | ref | Costing model: "auto" (default), "truck", "bicycle", "pedestrian" or "motor_scooter". |
| origins * | array | Origin locations (matrix rows). |
| destinations * | array | Destination locations (matrix columns). |
| exclude_polygons | ["array","null"] | Areas to avoid, scenario analysis ("close this bridge and recompute the matrix"): an array of polygons, each an array of `[lon, lat]` pairs forming one exterior ring (GeoJSON-style, longitude FIRST). Roads intersecting any ring are excluded from every cell's path finding; a pair no path joins withou… |
{
"name": "matrix",
"description": "Compute a travel time/distance matrix between origins (rows) and destinations (columns). Costing \"auto\", \"truck\" (with optional `truck` profile as in `route`), \"bicycle\", \"pedestrian\" or \"motor_scooter\". Returns durations_s[i][j] in seconds and distances_m[i][j] in metres; null cells are unreachable pairs. Up to 10,000 cells per call (origins × destinations). Optional `exclude_polygons` for before/after scenarios (\"close this bridge and recompute the matrix\"): an array of polygons, each an array of [lon, lat] pairs forming one ring (longitude FIRST) whose intersecting roads are excluded from every cell's path finding. Applies to the Valhalla engine; unsupported on the GraphHopper engine, where it is ignored.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"TruckSpec": {
"type": "object",
"properties": {
"hazmat": {
"type": "boolean",
"default": false,
"description": "Whether the vehicle carries dangerous goods (ADR). Defaults to\nfalse."
},
"width_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle width in metres."
},
"height_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle height in metres."
},
"length_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle length in metres."
},
"tunnel_code": {
"type": [
"string",
"null"
],
"description": "ADR 8.6.4 tunnel restriction code of the load, e.g. \"B\", \"C5000D\",\n\"B/D\", or \"(-)\"/\"none\" for explicitly unrestricted. Leave unset if\nunknown: a hazmat load without a code is conservatively treated as\ncode B (allowed only through category-A tunnels)."
},
"gross_weight_t": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Gross combination weight in metric tonnes."
}
},
"description": "Truck profile for routing: physical dimensions plus the ADR\ndangerous-goods declaration. Omitted dimensions default to the EU\nmaximum authorised dimensions of Council Directive 96/53/EC (4.0 m\nheight, 2.55 m width, 16.5 m length, 40 t gross weight)."
},
"CostingKind": {
"oneOf": [
{
"type": "string",
"const": "auto",
"description": "Standard car costing."
},
{
"type": "string",
"const": "truck",
"description": "Truck costing; honours dimensional limits and, when a `truck`\nprofile is supplied, ADR dangerous-goods restrictions."
},
{
"type": "string",
"const": "bicycle",
"description": "Bicycle costing; tune it with a `bicycle` options object."
},
{
"type": "string",
"const": "pedestrian",
"description": "Pedestrian (walking) costing; tune it with a `pedestrian` options\nobject (lit streets, wheelchair/blind, hiking difficulty)."
},
{
"type": "string",
"const": "motor_scooter",
"description": "Motor scooter (moped) costing: like auto but prefers lower-speed\nroads and may use ways closed to larger motor vehicles."
}
],
"description": "Costing models exposed by the MCP tools (a deliberate subset of the\nValhalla costing list), serialised in snake_case exactly as Valhalla\nnames them."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"origins",
"destinations"
],
"properties": {
"truck": {
"anyOf": [
{
"$ref": "#/$defs/TruckSpec"
},
{
"type": "null"
}
],
"description": "Truck profile (dimensions + ADR declaration). Requires costing\n\"truck\"."
},
"costing": {
"$ref": "#/$defs/CostingKind",
"default": "auto",
"description": "Costing model: \"auto\" (default), \"truck\", \"bicycle\", \"pedestrian\"\nor \"motor_scooter\"."
},
"origins": {
"type": "array",
"items": {
"$ref": "#/$defs/LatLon"
},
"description": "Origin locations (matrix rows)."
},
"destinations": {
"type": "array",
"items": {
"$ref": "#/$defs/LatLon"
},
"description": "Destination locations (matrix columns)."
},
"exclude_polygons": {
"type": [
"array",
"null"
],
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2
}
},
"description": "Areas to avoid, scenario analysis (\"close this bridge and\nrecompute the matrix\"): an array of polygons, each an array of\n`[lon, lat]` pairs forming one exterior ring (GeoJSON-style,\nlongitude FIRST). Roads intersecting any ring are excluded from\nevery cell's path finding; a pair no path joins without them stays\nnull (the search is never widened round them). Applies to the\nValhalla engine; unsupported on the GraphHopper engine, where it is\nignored."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"durations_s",
"distances_m"
],
"properties": {
"distances_m": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": [
"number",
"null"
],
"format": "double"
}
},
"description": "Travel distances in metres, same shape as `durations_s`. Null\ncells are unreachable pairs."
},
"durations_s": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": [
"number",
"null"
],
"format": "double"
}
},
"description": "Travel times in seconds; `durations_s[i][j]` is origin `i` →\ndestination `j`. Null cells are unreachable pairs."
}
}
}
}Find places near a point, nearest first with distance in metres, by category (cafes, fuel, EV charging, parking), by name or brand ("the nearest Lloyds bank", "nearest Sainsbury's"), or both. Use this instead of geocode whenever the question is about what is NEAR a location: geocode ranks a brand's branches everywhere and only biases by proximity, so it will happily return a Lloyds in another city over the one 100 m away. Provide `lat`, `lon` and at least one of `category` or `name`. `category` is matched against the map's lowercased OSM tag values (amenity/shop/tourism/…), e.g. "cafe", "fuel", "charging_station", "parking", "pharmacy", "supermarket", "hotel", "restaurant", "fast_food", "atm", "bakery", "hospital", "station"; common colloquial names are normalised ("coffee" -> cafe, "ev_charging" -> charging_station, "petrol" -> fuel, "chemist" -> pharmacy). `name` matches the place's name or alternative names word by word, case- and accent-insensitively, with the last word also matching as a prefix. Combine the two to disambiguate a brand, "Lloyds" plus "bank" excludes Lloyds Pharmacy. A category or name the map does not carry returns an empty list, never an error. Optional `radius_m` (default 2500, max 100000) bounds the straight-line search distance and `limit` (default 5, max 10) the result count. Each result has name, one-line label, lat/lon, address parts, distance_m, categories and a `details` object of display tags (opening_hours, website, phone, ...) when the map carries them. Every result also carries `bearing_deg` and a spoken `direction`. Pass `heading_deg` (degrees clockwise from true north, 0 = north, 90 = east) and results are described from where the user stands, "ahead and slightly to your right, about 80 metres", with a signed `relative_bearing_deg` (negative left, positive right); without a heading the phrasing falls back to cardinals ("to the north-east"), so this works with or without a compass. Add `fov_deg` to keep only what lies within that cone of the heading, it is the FULL width of the cone, so 90 keeps what lies within 45 degrees either side of dead ahead; anything dropped is counted in `out_of_view`, so a non-zero count means there ARE matching places nearby, just not in front of the user, say that rather than "nothing nearby". Prefer reading `direction` aloud over coordinates. Requires the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY).
| Parameter | Type | Description |
|---|---|---|
| lat * | number | Latitude of the search point in decimal degrees (−90 to 90). |
England bus and coach stops near a point, nearest first. Pass `lat` and `lon` (WGS84), optional `radius_m` (1 to 2,000, default 500) and `limit` (1 to 50, default 10). Each stop carries its NaPTAN ATCO code `id` (pass it to `next_departures`), `name`, `indicator` (e.g. "Stop S"), `locality`, position, `distance_m` and `bearing_deg` from the point, and `lines`, the line names the Bus Open Data timetables have calling there. Bus and coach only: rail, tram, metro and ferry stops are not included, and coverage is England (plus stops just across a border that an England service calls at). Display data, never a journey plan: pass on the returned `label` and `coverage`. Requires the MapMap gateway; a deployment without the stops index answers a clear error. Display the returned `attribution` (NaPTAN and BODS, Open Government Licence v3.0).
| Parameter | Type | Description |
|---|---|---|
| lat * | number | Latitude of the point, WGS84 degrees. |
| lon * | number | Longitude of the point, WGS84 degrees. |
| limit | ["integer","null"] | Most stops to return, 1 to 50 (default 10), nearest first. |
| radius_m | ["integer","null"] | Search radius in metres, 1 to 2,000 (default 500). |
{
"name": "nearby_stops",
"description": "England bus and coach stops near a point, nearest first. Pass `lat` and `lon` (WGS84), optional `radius_m` (1 to 2,000, default 500) and `limit` (1 to 50, default 10). Each stop carries its NaPTAN ATCO code `id` (pass it to `next_departures`), `name`, `indicator` (e.g. \"Stop S\"), `locality`, position, `distance_m` and `bearing_deg` from the point, and `lines`, the line names the Bus Open Data timetables have calling there. Bus and coach only: rail, tram, metro and ferry stops are not included, and coverage is England (plus stops just across a border that an England service calls at). Display data, never a journey plan: pass on the returned `label` and `coverage`. Requires the MapMap gateway; a deployment without the stops index answers a clear error. Display the returned `attribution` (NaPTAN and BODS, Open Government Licence v3.0).",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude of the point, WGS84 degrees."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude of the point, WGS84 degrees."
},
"limit": {
"type": [
"integer",
"null"
],
"format": "uint8",
"maximum": 255,
"minimum": 0,
"description": "Most stops to return, 1 to 50 (default 10), nearest first."
},
"radius_m": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Search radius in metres, 1 to 2,000 (default 500)."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"TransitStopOut": {
"type": "object",
"required": [
"id",
"name",
"lat",
"lon",
"lines"
],
"properties": {
"id": {
"type": "string",
"description": "The NaPTAN ATCO code, e.g. \"490008660N\": pass it to\n`next_departures`."
},
"lat": {
"type": "number",
"format": "double",
"description": "Stop latitude."
},
"lon": {
"type": "number",
"format": "double",
"description": "Stop longitude."
},
"name": {
"type": "string",
"description": "The stop's name."
},
"lines": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Line names the timetable has calling at the stop."
},
"locality": {
"type": [
"string",
"null"
],
"description": "The NaPTAN locality."
},
"indicator": {
"type": [
"string",
"null"
],
"description": "The on-street indicator, e.g. \"Stop S\"."
},
"distance_m": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Straight-line distance from the queried point, metres."
},
"bearing_deg": {
"type": [
"integer",
"null"
],
"format": "uint16",
"maximum": 65535,
"minimum": 0,
"description": "Bearing from the queried point to the stop, degrees clockwise from\ntrue north."
}
},
"description": "One bus or coach stop."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"stops",
"coverage",
"label",
"attribution"
],
"properties": {
"label": {
"type": "string",
"description": "What the answer is and is not: display data, never a journey plan\nor an arrival prediction. Pass it on with the stops."
},
"stops": {
"type": "array",
"items": {
"$ref": "#/$defs/TransitStopOut"
},
"description": "Stops inside the radius, nearest first."
},
"coverage": {
"type": "string",
"description": "What the data covers (England bus and coach stops; no rail, tram or\nferry). Pass it on with the stops."
},
"attribution": {
"type": "string",
"description": "NaPTAN and BODS attribution (Open Government Licence v3.0): display\nit with the stops."
}
}
}
}Timetabled bus departures at one stop, from the Bus Open Data (BODS) timetables. Pass `stop` (the NaPTAN ATCO code `nearby_stops` returns), optional `at` (RFC 3339, default now; the index holds three service days from today), `window_minutes` (1 to 180, default 60) and `limit` (1 to 30, default 8). Each departure carries `line`, `destination`, `operator`, `scheduled_at` (local time) and `trip`, plus `live` when a vehicle on that line was seen in the live positions within 3 km and heading towards the stop (`vehicle`, `distance_m`, `age_s`). These are TIMETABLE times: `basis` is always "timetable", and a live entry is an observation, never an arrival time or a delay. MapMap does not predict arrivals: never present `scheduled_at` or `live` as one, and pass on the returned `label` and `coverage` verbatim. Requires the MapMap gateway; a deployment without the departures index answers a clear error. Display the returned `attribution` (NaPTAN and BODS, Open Government Licence v3.0).
| Parameter | Type | Description |
|---|---|---|
| at | ["string","null"] | Start of the window, RFC 3339 (e.g. "2026-10-12T08:00:00+01:00"); default now. The index holds three service days from today. |
| stop * | string | The stop's NaPTAN ATCO code, as `nearby_stops` returns it. |
| limit | ["integer","null"] | Most departures to return, 1 to 30 (default 8). |
| window_minutes | ["integer","null"] | Window length, 1 to 180 minutes (default 60). |
{
"name": "next_departures",
"description": "Timetabled bus departures at one stop, from the Bus Open Data (BODS) timetables. Pass `stop` (the NaPTAN ATCO code `nearby_stops` returns), optional `at` (RFC 3339, default now; the index holds three service days from today), `window_minutes` (1 to 180, default 60) and `limit` (1 to 30, default 8). Each departure carries `line`, `destination`, `operator`, `scheduled_at` (local time) and `trip`, plus `live` when a vehicle on that line was seen in the live positions within 3 km and heading towards the stop (`vehicle`, `distance_m`, `age_s`). These are TIMETABLE times: `basis` is always \"timetable\", and a live entry is an observation, never an arrival time or a delay. MapMap does not predict arrivals: never present `scheduled_at` or `live` as one, and pass on the returned `label` and `coverage` verbatim. Requires the MapMap gateway; a deployment without the departures index answers a clear error. Display the returned `attribution` (NaPTAN and BODS, Open Government Licence v3.0).",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"stop"
],
"properties": {
"at": {
"type": [
"string",
"null"
],
"description": "Start of the window, RFC 3339 (e.g. \"2026-10-12T08:00:00+01:00\");\ndefault now. The index holds three service days from today."
},
"stop": {
"type": "string",
"description": "The stop's NaPTAN ATCO code, as `nearby_stops` returns it."
},
"limit": {
"type": [
"integer",
"null"
],
"format": "uint8",
"maximum": 255,
"minimum": 0,
"description": "Most departures to return, 1 to 30 (default 8)."
},
"window_minutes": {
"type": [
"integer",
"null"
],
"format": "uint16",
"maximum": 65535,
"minimum": 0,
"description": "Window length, 1 to 180 minutes (default 60)."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"TransitLiveOut": {
"type": "object",
"required": [
"vehicle",
"distance_m"
],
"properties": {
"age_s": {
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0,
"description": "Age of the vehicle's position fix, seconds."
},
"vehicle": {
"type": "string",
"description": "The operator's vehicle reference."
},
"distance_m": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "Straight-line distance from the vehicle to the stop, metres."
}
},
"description": "A vehicle seen on the departure's line heading towards the stop."
},
"TransitStopOut": {
"type": "object",
"required": [
"id",
"name",
"lat",
"lon",
"lines"
],
"properties": {
"id": {
"type": "string",
"description": "The NaPTAN ATCO code, e.g. \"490008660N\": pass it to\n`next_departures`."
},
"lat": {
"type": "number",
"format": "double",
"description": "Stop latitude."
},
"lon": {
"type": "number",
"format": "double",
"description": "Stop longitude."
},
"name": {
"type": "string",
"description": "The stop's name."
},
"lines": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Line names the timetable has calling at the stop."
},
"locality": {
"type": [
"string",
"null"
],
"description": "The NaPTAN locality."
},
"indicator": {
"type": [
"string",
"null"
],
"description": "The on-street indicator, e.g. \"Stop S\"."
},
"distance_m": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Straight-line distance from the queried point, metres."
},
"bearing_deg": {
"type": [
"integer",
"null"
],
"format": "uint16",
"maximum": 65535,
"minimum": 0,
"description": "Bearing from the queried point to the stop, degrees clockwise from\ntrue north."
}
},
"description": "One bus or coach stop."
},
"TransitDepartureOut": {
"type": "object",
"required": [
"line",
"scheduled_at",
"trip"
],
"properties": {
"line": {
"type": "string",
"description": "The line name, e.g. \"15\"."
},
"live": {
"anyOf": [
{
"$ref": "#/$defs/TransitLiveOut"
},
{
"type": "null"
}
],
"description": "A vehicle on this line seen heading towards the stop, or absent.\nAn observation, never an arrival time."
},
"trip": {
"type": "string",
"description": "The GTFS trip id."
},
"operator": {
"type": [
"string",
"null"
],
"description": "National Operator Code, e.g. \"TFLO\"."
},
"destination": {
"type": [
"string",
"null"
],
"description": "The headsign the timetable gives."
},
"scheduled_at": {
"type": "string",
"description": "The timetabled departure, RFC 3339 in local time. A timetable time,\nnever a prediction."
}
},
"description": "One timetabled departure."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"stop",
"basis",
"label",
"departures",
"coverage",
"attribution"
],
"properties": {
"stop": {
"$ref": "#/$defs/TransitStopOut",
"description": "The stop."
},
"basis": {
"type": "string",
"description": "Always \"timetable\"."
},
"label": {
"type": "string",
"description": "The honesty line, verbatim: timetable times, what a live entry is,\nand that MapMap does not predict arrival times. Pass it on with the\ndepartures."
},
"coverage": {
"type": "string",
"description": "What the data covers. Pass it on with the departures."
},
"departures": {
"type": "array",
"items": {
"$ref": "#/$defs/TransitDepartureOut"
},
"description": "Departures in timetable order."
},
"attribution": {
"type": "string",
"description": "NaPTAN and BODS attribution (Open Government Licence v3.0)."
},
"generated_at": {
"type": [
"string",
"null"
],
"description": "When the answer was assembled, RFC 3339."
},
"timetable_date": {
"type": [
"string",
"null"
],
"description": "The service date the requested time falls on, YYYY-MM-DD."
}
}
}
}Optimise multi-vehicle, multi-stop delivery plans (VRP). Provide `vehicles` (id, start/end, capacity, skills, time_window), `jobs` (id, location, service_s, delivery/pickup, skills, time_windows) and/or `shipments` (pickup+delivery pairs that ride the same vehicle). Costing "auto", "truck", "bicycle", "pedestrian" or "motor_scooter" (cargo-bike and courier fleets welcome): with a `truck` profile (dimensions + ADR declaration, as in `route`), the travel-time matrix respects dimensional and dangerous-goods restrictions, so every optimised route is truck-legal. Returns a summary, unassigned tasks and per-vehicle routes with ordered steps (arrival_s/duration_s in seconds, distance_m in metres). Fair use: at most 200 unique locations per problem, and no wider than the routing engine's matrix span (1,500 km on the hosted endpoint for motor costings, 400 km stock on a self-host). Past that, cluster the stops with `cluster` and optimise each group, or submit the whole problem to the asynchronous lane with `submit_optimise_job` (2,000 locations). Optional `territories` are named polygons ([{id, polygon}], GeoJSON [lon, lat] rings, LONGITUDE FIRST) that bound who serves what: a vehicle listing `territory_ids` may serve a task only if that task sits inside at least one of the territories it names, while a vehicle listing none is unrestricted and may serve anything, inside a round or outside every one. The response's `territories` block says which vehicle was eligible for what and names any task no vehicle could take. A vehicle may also declare `reloads` {max_trips 2-5, reload_time_s, depot?} to return to a depot, reload and go out again, the tipping round. It needs a `time_window`, because the shift is what gets split: it is cut into that many consecutive non-overlapping windows separated by the reload time, each trip carrying the vehicle's FULL capacity. That split is fixed BEFORE the solve, so the plan is conservative and never optimistic, it cannot put a lorry in two places at once, but it is an approximation: a trip that finishes early cannot lend its spare time to the next, so stops can come back unassigned that a truly sequential model would have served, and `max_trips` is a budget rather than a prediction (ask for five on a shift that supports three and every window shrinks to a fifth). Read the returned `reloads` block before quoting arrival times, and re-plan after each tip with `replan_routes` for the tighter answer. `relax_if_unassigned` {time_windows_by_s?, allow_overtime_s?} re-solves ONCE with those relaxations if the first plan left work unassigned, and the `relaxation` block says honestly which plan came back: at most one second solve, never beyond the caps stated, and the relaxed plan is returned ONLY if it assigns more work than the first. Capacities, skills and territories are never relaxed; only time windows move. It bills as two solves when the second one runs. Always check `relaxation.relaxed_plan_used` before telling anyone the day fits: a plan produced under relaxation has had promises moved. `emissions` {vehicle_category, fuel, euro_standard} annotates the plan with the clean-air zones its own stops sit in and what this vehicle pays in each; add `avoid_zones: true` to steer the travel-time matrix out of them, which changes the plan itself. Territories, reloads, relaxation and zones are computed by the MapMap gateway; without one configured the tool refuses rather than returning a plan that quietly ignored them. A field this input does not have is REFUSED by name rather than dropped: driver `breaks`, `max_tasks`, `max_travel_time`, `costs` and `eu_drivers_hours` are HTTP API fields this tool has not surfaced, so a plan is never returned as if it had honoured them. Returns `view_url`, a mapmap.ai link that draws the answer on a map (no key needed); the link carries the stop coordinates and names.
Put a single run's stops in the best visiting order ("order my errands"). Provide `start` {lat, lon} and `stops` (1-100 entries of {location, label?, service_s?}); optionally an `end` destination or `round_trip`: true to return to the start. Costing "auto" = car, "truck" = lorry (pass `truck` as in `route` for a truck-legal order). Returns the stops in visit order with arrival offsets in seconds, plus total duration and distance.
| Parameter | Type | Description |
|---|---|---|
| end | any | Optional fixed final destination. Mutually exclusive with `round_trip`; omitted (and not a round trip), the run ends at whichever stop the solver visits last. |
| start * | ref | Where the run starts. |
| stops * | array | The stops to put in the best visiting order (1–100). |
| truck | any | Truck profile (dimensions + ADR declaration); requires costing "truck". The travel-time matrix then respects dimensional and dangerous-goods restrictions. |
| costing | ref | Costing model: "auto" (default) or "truck". |
| round_trip | boolean | Return to `start` after the last stop (default false). |
{
"name": "order_stops",
"description": "Put a single run's stops in the best visiting order (\"order my errands\"). Provide `start` {lat, lon} and `stops` (1-100 entries of {location, label?, service_s?}); optionally an `end` destination or `round_trip`: true to return to the start. Costing \"auto\" = car, \"truck\" = lorry (pass `truck` as in `route` for a truck-legal order). Returns the stops in visit order with arrival offsets in seconds, plus total duration and distance.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"TruckSpec": {
"type": "object",
"properties": {
"hazmat": {
"type": "boolean",
"default": false,
"description": "Whether the vehicle carries dangerous goods (ADR). Defaults to\nfalse."
},
"width_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle width in metres."
},
"height_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle height in metres."
},
"length_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle length in metres."
},
"tunnel_code": {
"type": [
"string",
"null"
],
"description": "ADR 8.6.4 tunnel restriction code of the load, e.g. \"B\", \"C5000D\",\n\"B/D\", or \"(-)\"/\"none\" for explicitly unrestricted. Leave unset if\nunknown: a hazmat load without a code is conservatively treated as\ncode B (allowed only through category-A tunnels)."
},
"gross_weight_t": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Gross combination weight in metric tonnes."
}
},
"description": "Truck profile for routing: physical dimensions plus the ADR\ndangerous-goods declaration. Omitted dimensions default to the EU\nmaximum authorised dimensions of Council Directive 96/53/EC (4.0 m\nheight, 2.55 m width, 16.5 m length, 40 t gross weight)."
},
"CostingKind": {
"oneOf": [
{
"type": "string",
"const": "auto",
"description": "Standard car costing."
},
{
"type": "string",
"const": "truck",
"description": "Truck costing; honours dimensional limits and, when a `truck`\nprofile is supplied, ADR dangerous-goods restrictions."
},
{
"type": "string",
"const": "bicycle",
"description": "Bicycle costing; tune it with a `bicycle` options object."
},
{
"type": "string",
"const": "pedestrian",
"description": "Pedestrian (walking) costing; tune it with a `pedestrian` options\nobject (lit streets, wheelchair/blind, hiking difficulty)."
},
{
"type": "string",
"const": "motor_scooter",
"description": "Motor scooter (moped) costing: like auto but prefers lower-speed\nroads and may use ways closed to larger motor vehicles."
}
],
"description": "Costing models exposed by the MCP tools (a deliberate subset of the\nValhalla costing list), serialised in snake_case exactly as Valhalla\nnames them."
},
"OrderStopSpec": {
"type": "object",
"required": [
"location"
],
"properties": {
"label": {
"type": [
"string",
"null"
],
"description": "Human-readable label echoed back in the ordered plan\n(e.g. \"chemist\" or \"site B\")."
},
"location": {
"$ref": "#/$defs/LatLon",
"description": "The stop's location."
},
"service_s": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "On-site time in seconds (waiting, loading, shopping)."
}
},
"description": "One errand stop of an `order_stops` request."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"start",
"stops"
],
"properties": {
"end": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "Optional fixed final destination. Mutually exclusive with\n`round_trip`; omitted (and not a round trip), the run ends at\nwhichever stop the solver visits last."
},
"start": {
"$ref": "#/$defs/LatLon",
"description": "Where the run starts."
},
"stops": {
"type": "array",
"items": {
"$ref": "#/$defs/OrderStopSpec"
},
"description": "The stops to put in the best visiting order (1–100)."
},
"truck": {
"anyOf": [
{
"$ref": "#/$defs/TruckSpec"
},
{
"type": "null"
}
],
"description": "Truck profile (dimensions + ADR declaration); requires costing\n\"truck\". The travel-time matrix then respects dimensional and\ndangerous-goods restrictions."
},
"costing": {
"$ref": "#/$defs/CostingKind",
"default": "auto",
"description": "Costing model: \"auto\" (default) or \"truck\"."
},
"round_trip": {
"type": "boolean",
"default": false,
"description": "Return to `start` after the last stop (default false)."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"OrderedStop": {
"type": "object",
"required": [
"order",
"stop_index",
"location",
"arrival_s"
],
"properties": {
"label": {
"type": [
"string",
"null"
],
"description": "The request's label for this stop, when one was given."
},
"order": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "1-based visit order."
},
"location": {
"$ref": "#/$defs/LatLon",
"description": "The stop's location."
},
"arrival_s": {
"type": "integer",
"format": "int64",
"description": "Arrival time as an offset from departure, in seconds."
},
"stop_index": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "The stop's 0-based index in the request's `stops` array."
}
},
"description": "One stop of an ordered errand plan."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"profile",
"ordered",
"unassigned_stop_indexes",
"duration_s"
],
"properties": {
"ordered": {
"type": "array",
"items": {
"$ref": "#/$defs/OrderedStop"
},
"description": "The stops in optimal visiting order."
},
"profile": {
"type": "string",
"description": "The matrix costing profile (\"auto\" or \"truck\")."
},
"distance_m": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Total travel distance in metres, when reported."
},
"duration_s": {
"type": "integer",
"format": "int64",
"description": "Total travel time in seconds."
},
"unassigned_stop_indexes": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32",
"minimum": 0
},
"description": "0-based indexes of stops the solver could not fit (empty in the\nnormal, unconstrained case)."
}
}
}
}What is over THERE: given a position and the direction the user is facing, the places inside that cone, and whether the ground and the buildings in between let them actually be seen. Use this for "what is that over there", "is there a pub in that direction", "what am I looking at". Use `nearby_places` instead when the question is about what is NEAR a point rather than what is in a direction. Provide `lat`, `lon`, `bearing_deg` (degrees CLOCKWISE FROM TRUE NORTH: 0 north, 90 east, 180 south, 270 west) and at least one of `category` or `name`; `category=building` reaches named buildings. Optional `fov_deg` is the FULL width of the cone (default 60, so 30 degrees either side), `radius_m` the range (default 1000, max 5000), `eye_height_m` the observer's eye height (default 1.6). Each result carries `distance_m`, `bearing_deg`, a signed `angular_offset_deg` (negative left, positive right), a spoken `direction`, and a `visibility` block. READ THE VISIBILITY BLOCK BEFORE SAYING ANYTHING: `clear` means nothing in the data stands in the way, `occluded` names what does (a hill, or a building with its height), and `unknown` means NO check could run: with `unknown` say you cannot tell, never that it is visible. Read `basis` too: `terrain-only` in a town means hills were checked and buildings were not, which is weak. A non-zero `out_of_sector` means there ARE matching places nearby, just not in that direction, so say that rather than "nothing nearby". `coverage` names the datasets that answered and `caveat` is the standing limit: visibility is modelled from maps, not observed, and trees, walls, scaffolding and weather are not in it. Requires the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY).
| Parameter | Type | Description |
|---|---|---|
| lat * | number | Latitude of the observer in decimal degrees (−90 to 90). |
| lon * | number | Longitude of the observer in decimal degrees (−180 to 180). |
| name | ["string","null"] | A place name or brand to look for. At least one of `category` and `name` is required. |
| limit | ["integer","null"] |
Turn an itinerary into one navigable multi-stop route. Provide a `start` and `stops` (each a `location` {lat, lon} or a free-text `name` to geocode, plus optional `dwell_minutes` time at the stop), optional `depart_at` (RFC 3339) for absolute ETAs, `optimise: true` to reorder stops for the shortest day (VROOM solver), and `return_to_start`. Costing "auto", "truck" (with a `truck` profile the whole day respects dimensional/ADR restrictions), "bicycle", "pedestrian" or "motor_scooter". Returns the stops in visit order with per-leg duration/distance and arrival/departure times, totals, and the full route geometry (polyline6). Geocoded names carry a `resolution`, when `ambiguous` is true, check `alternatives` and re-run with an explicit location rather than trusting the guess. Returns `view_url`, a mapmap.ai link that draws the answer on a map (no key needed); the link carries the stop coordinates and names.
| Parameter | Type | Description |
|---|---|---|
| start * | ref | Where the day starts (name or location; `dwell_minutes` ignored). |
| stops * | array | The stops to visit (1–20). Visited in the given order unless `optimise` is true. |
| truck | any | Truck profile (dimensions + ADR declaration). Requires costing "truck". |
| costing | ref | Costing model: "auto" (default), "truck", "bicycle", "pedestrian" or "motor_scooter". |
| optimise | boolean | Reorder the stops for the shortest day (VROOM solver; requires the optimisation sidecar). Default false: visit in the given order. |
| depart_at | ["string","null"] | Departure time as RFC 3339 (e.g. "2026-07-18T09:00:00Z"); when given, every ETA is also returned as an absolute timestamp. |
Order a handful of errands against a hard arrival time, and say honestly whether they fit. This is the "pick up a prescription, get petrol, and be at the school by quarter past three" tool. Give `origin`, `destination` (+ `destination_name`), `arrive_by` (RFC 3339 with an offset: convert "quarter past three" yourself), optional `depart_at`, and 1 to 5 `errands`. Each errand is EITHER a `category` (a kind of place: "pharmacy", "fuel", "supermarket", or a colloquial phrase the server normalises; use `list_place_categories` for the vocabulary) OR a `place` {lat, lon} the driver already knows ("the school", "the nursery"). Resolve a named place with `geocode` first and pass the coordinate: never invent one. Optional `dwell_minutes` per errand (default 5). The server chooses the order and the actual shops, exhaustively, over engine-computed travel times -- do NOT attempt the ordering or the arithmetic yourself. IMPORTANT: `feasible: false` is an ANSWER, not an error to retry. It names the errand that costs the most (`blocking_errand`), says how late the whole chain would be (`over_by_s`), and returns the stops of the chain that DOES fit with `dropped` naming what had to go. Tell the driver what to drop. Every stop is a real indexed place carrying its id: never mention a shop the answer did not return. `hours` is "open_on_the_tag" (the map's tag covers your arrival, which is evidence and not a promise) or "unknown" (most places carry no hours at all); a place the tag proves shut is never proposed. ALWAYS show `usage_note`: this is planned before setting off or by a passenger, never at the wheel. Requires the MapMap gateway.
| Parameter | Type | Description |
|---|---|---|
| origin * | ref | Where the driver sets off from. |
| errands * | array | The errands, in any order: the answer decides the order. One to five. |
| arrive_by * | string | The hard arrival time, RFC 3339 with an offset ("2026-09-21T15:15:00+01:00"). Convert "quarter past three" to an absolute instant in the driver's own offset before calling. |
| depart_at |
Plan a whole electric-vehicle journey, charge stops included. Give `origin` and `destination` (plus optional `waypoints`) and a `vehicle`, a published profile ("small_hatch", "saloon", "suv", "van") and/or inline figures (battery_kwh, mass_kg, drag_area_m2, aux_kw, connectors), with `start_soc` (default 0.9), `min_arrival_soc` (default 0.1), `reserve_soc` (default 0.1, the floor the charge must never drop below mid-route), optional `connectors` and `min_kw` filters and `ambient_temperature_c`. Energy comes from a published road-load physics model over the route's own legs; charge times are integrated over the vehicle's charging curve capped by the charge point, NOT energy divided by peak power, which is the single biggest error in naive EV planners. Returns the stops with arrive/depart state of charge, charge time and detour, a per-leg state-of-charge trace, and the journey's driving and charging time. IMPORTANT: when no plan exists, a charger desert, a connector mismatch, a gap wider than the car's range, the answer comes back with `feasible: false`, a `reason` and the furthest point on the route the car can actually reach. That is an ANSWER, not an error to retry: report the reason and never describe it as a plan. `gradient_data` says whether elevation was available: "absent" means consumption was modelled on the flat and under-reads a hilly route. There is no national charge-point registry, so ALWAYS show the returned `coverage_note`, an infeasible plan means "none from these operators", never "there are no chargers here", and statuses are current only when `availability_live` is true. Requires the MapMap gateway; answers a clear error when the deployment has no charge-point dataset. Display the returned charging_attribution with the plan.
| Parameter | Type | Description |
|---|---|---|
| min_kw | ["number","null"] | Keep only charge points with a usable connector rated at least this many kW (e.g. 50 for rapid charging only). |
| origin * | ref | Where the journey starts. |
| vehicle | any | The vehicle. Omitted ⇒ the published "saloon" default, and the answer says which vehicle it used. |
| start_soc |
Compute the area reachable from an origin within one or more travel-time budgets, walkability/cyclability rings. Costing "pedestrian" answers "how far can I walk in 15 minutes?", "bicycle" the cycling equivalent; "auto", "truck" and "motor_scooter" work too (e.g. delivery coverage). `contours_minutes` lists the ring boundaries in minutes (1 to 4 values, each up to 120); set `polygons` true for filled polygons ready to render as a map fill layer instead of contour lines. Returns a GeoJSON FeatureCollection, one feature per contour. The origin is first moved onto the nearest road the travel mode can use (ferries excluded, at most 5 km away) and the rings are drawn from there: `snapped_origin` {lat, lon, distance_m} on the collection and on every feature's properties says where. An origin with no road within 5 km (open sea, desert, an unmapped area) is refused with "no roads near this point" rather than answered with a speck, and that refusal is not billed; move it onto land near a road. Optional `exclude_polygons` for before/after scenarios ("close this bridge and recompute reachability"): an array of polygons, each an array of [lon, lat] pairs forming one ring, longitude FIRST, whose intersecting roads are excluded from the reachability search. Applies to the Valhalla engine; unsupported on the GraphHopper engine, where it is ignored.
| Parameter | Type | Description |
|---|---|---|
| origin * | ref | Origin the reachable area is computed from. |
| costing | ref | Travel mode: "auto" (default), "truck", "bicycle", "pedestrian" or "motor_scooter". |
| polygons | ["boolean","null"] | Return filled polygons instead of contour linestrings (default false). Polygons draw directly as a MapLibre fill layer. |
| contours_minutes * | array | Contour boundaries in minutes of travel time, e.g. [5, 10, 15] for 5/10/15-minute rings. 1 to 4 values (the routing engine's limit), each between 0 and 120 minutes. |
Re-plan a fleet part-way through its shift. Send the day back; nothing is stored. MapMap holds NO dispatch state, no plan, no vehicle position, no completion log, so a re-plan is not a delta against something we remember: you pass the day's `optimise_routes` problem in full, plus `progress` (per vehicle: `completed_stop_ids` IN THE ORDER SERVED, an optional `current_position`, and `unavailable: true` for a breakdown or an end of hours) and/or `changes` (`cancel_job_ids`, `add_jobs`, `add_shipments`), and get a fresh plan for what is left. That costs bandwidth and buys the absence of a server-side plan that can go stale, leak, or fall out of step with the telematics platform that actually owns the truth, and it makes a re-plan reproducible: the same body always yields the same answer. Completed stops are LOCKED by construction: they are removed from the problem entirely and each vehicle starts from where it actually is, so the solver cannot move a stop that has already happened, a guarantee the solver cannot break, rather than a hint it is free to ignore. At least one progress entry or one change is required. A re-plan has NO CLOCK and no memory of the shift so far: time windows are solved from the start of each vehicle's `time_window`, not from now, and `max_tasks`, `max_travel_time`, breaks and `capacity` apply to the remaining route as written. Send what each vehicle has LEFT (a `time_window` that starts at the current time, limits and capacity reduced by what has been used); the `replan` notes name every such field the request carried. Returns the same plan shape as `optimise_routes` for the REMAINING work, plus a `replan` block: the prefix locked per vehicle, where each re-plans from and how that was decided, stops released from a vehicle that can no longer serve them, tasks forced unassigned, and a note for every id that did not resolve. Read that block, a stop that vanished from the plan is named there rather than left for a dispatcher to notice at four in the afternoon; a cancelled id that matched nothing is reported there too rather than refused. Multi-trip vehicles cannot be re-planned: a completion does not say which trip it belongs to, so a problem whose vehicles declare `reloads` is refused with what to send instead. Billed on the remaining problem, not the original. Requires the MapMap gateway.
| Parameter | Type | Description |
|---|---|---|
| jobs | array | Single-stop jobs (at least one job or shipment overall). |
| truck |
Report that the live world disagrees with the map, a closed road, a wrong or missing restriction, a bad speed limit, a missing road, a wrong one-way, or changed access. Use it when you observe the mismatch mid-task. Provide `location` {lat, lon}, a `category` (road_closed, wrong_restriction, wrong_speed_limit, missing_road, wrong_oneway, access_changed, other) and optionally a `description`, the OSM `way_id` and an `evidence_url`. This is a first-party observation: it is QUEUED for human/agent review and NEVER changes routing immediately or edits any map. Returns the queued report_id.
| Parameter | Type | Description |
|---|---|---|
| way_id | ["integer","null"] | The OSM way id the observation concerns, when the caller knows it. Optional, the report stands on its own as a first-party observation and is never tied to OSM data beyond this hint. |
| category * | ref | What kind of mismatch this is. |
| location * | ref | Where the mismatch was observed (WGS84 decimal degrees). |
| description | ["string","null"] | Free-text detail of what was observed on the ground, e.g. "barrier across the lane, diversion signed via the B4009". Bounded length. |
| evidence_url | ["string","null"] | A URL backing the observation (photo, notice, news item), when one exists. Bounded length. |
{
"name": "report_map_issue",
"description": "Report that the live world disagrees with the map, a closed road, a wrong or missing restriction, a bad speed limit, a missing road, a wrong one-way, or changed access. Use it when you observe the mismatch mid-task. Provide `location` {lat, lon}, a `category` (road_closed, wrong_restriction, wrong_speed_limit, missing_road, wrong_oneway, access_changed, other) and optionally a `description`, the OSM `way_id` and an `evidence_url`. This is a first-party observation: it is QUEUED for human/agent review and NEVER changes routing immediately or edits any map. Returns the queued report_id.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"MapIssueCategory": {
"oneOf": [
{
"type": "string",
"const": "road_closed",
"description": "A road the map shows as open is closed (roadworks, collapse, event)."
},
{
"type": "string",
"const": "wrong_restriction",
"description": "A turn/access/dimension/weight restriction is wrong or missing."
},
{
"type": "string",
"const": "wrong_speed_limit",
"description": "The posted speed limit differs from the map's value."
},
{
"type": "string",
"const": "missing_road",
"description": "A road exists on the ground but is absent from the map."
},
{
"type": "string",
"const": "wrong_oneway",
"description": "A one-way direction is wrong (or the road is not one-way at all)."
},
{
"type": "string",
"const": "access_changed",
"description": "Access has changed (e.g. now gated, private, or newly public)."
},
{
"type": "string",
"const": "other",
"description": "Anything else that does not fit the categories above."
}
],
"description": "The kind of map/live-world mismatch an agent is reporting.\n\nA first-party *observation* only: it records what the agent saw on the\nground, never an edit to any map or OSM-derived database."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"location",
"category"
],
"properties": {
"way_id": {
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0,
"description": "The OSM way id the observation concerns, when the caller knows it.\nOptional, the report stands on its own as a first-party\nobservation and is never tied to OSM data beyond this hint."
},
"category": {
"$ref": "#/$defs/MapIssueCategory",
"description": "What kind of mismatch this is."
},
"location": {
"$ref": "#/$defs/LatLon",
"description": "Where the mismatch was observed (WGS84 decimal degrees)."
},
"description": {
"type": [
"string",
"null"
],
"description": "Free-text detail of what was observed on the ground, e.g. \"barrier\nacross the lane, diversion signed via the B4009\". Bounded length."
},
"evidence_url": {
"type": [
"string",
"null"
],
"description": "A URL backing the observation (photo, notice, news item), when one\nexists. Bounded length."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"report_id",
"status",
"category"
],
"properties": {
"status": {
"type": "string",
"description": "Always \"queued\": the report awaits human/agent review and changes\nnothing about routing immediately."
},
"category": {
"type": "string",
"description": "The category, echoed back as its snake_case wire tag."
},
"report_id": {
"type": "string",
"description": "The generated id of the queued report (cite it in follow-ups)."
}
}
}
}Turn coordinates into the nearest places: addresses, POIs and localities with distance in metres. The inverse of geocode. Provide `lat` and `lon`; returns up to `limit` (default 5, max 10) results, nearest first, each with name, one-line label, lat/lon, type, address parts and distance_m, plus categories and a `details` object of display tags (opening_hours, website, phone, wikipedia, ...) on POI hits when the index carries them. Every result also carries `bearing_deg` and a spoken `direction`. Pass `heading_deg` (degrees clockwise from true north, 0 = north, 90 = east) and results are described from where the user stands, "ahead and slightly to your right, about 80 metres", with a signed `relative_bearing_deg` (negative left, positive right); without a heading the phrasing falls back to cardinals ("to the north-east"), so this works with or without a compass. Add `fov_deg` to keep only what lies within that cone of the heading, it is the FULL width, so 90 keeps what lies within 45 degrees either side of dead ahead; anything dropped is counted in `out_of_view`. Prefer reading `direction` aloud over coordinates.
| Parameter | Type | Description |
|---|---|---|
| lat * | number | Latitude in decimal degrees (−90 to 90). |
| lon * | number | Longitude in decimal degrees (−180 to 180). |
| limit | ["integer","null"] | Maximum number of results (1–10, default 5). |
| fov_deg | ["number","null"] | Field of view: the full width in degrees of a cone centred on `heading_deg`, outside which results are dropped, it is the FULL width, so 90 keeps only what lies within 45 degrees either side of dead ahead. Needs `heading_deg`, a cone has to point somewhere. The count of results removed is reported a… |
| heading_deg | ["number","null"] | Which way the user is facing, in degrees **clockwise from true north** (0 = north, 90 = east, 180 = south, 270 = west). Supply it and every result is also described from the user's point of view ("just ahead on your right"); omit it and results fall back to cardinal directions ("to the north-east"),… |
Compute a turn-by-turn route between origin and destination (optionally via waypoints). Costing "auto" = car, "truck" = lorry, "bicycle", "pedestrian" = walking, "motor_scooter" = moped. Pass `truck` {height_m, width_m, length_m, gross_weight_t, hazmat, tunnel_code} to apply dimensional limits and the ADR dangerous-goods tunnel matrix to the search; `pedestrian` {use_lit 0-1, type "wheelchair"|"blind", max_hiking_difficulty 1-6, use_hills 0-1, max_grade_pct 1-90, surface_quality "avoid"|"ignore"} for lit-street walking, wheelchair routing and trail limits. A wheelchair route through the MapMap gateway returns a `grade` block (maximum grade, ascent and descent sampled from a 30 m elevation model, the `use_hills` preference sent, and `cap.enforced` for a `max_grade_pct`, which the engine accepts but does not enforce yet: say so) and, where the deployment has a surface graph, a `surface_quality` block: `applied: true` means ways rated smoothness bad or worse in OpenStreetMap were avoided in the named region, a preference from ratings where they exist that says nothing about kerbs, widths, steps or inclines; `applied: false` gives the `reason`. Relay both caveats and never describe such a route as suitable for every user; `bicycle` {bicycle_type, use_roads 0-1, use_living_streets 0-1, avoid_bad_surfaces 0-1, use_hills 0-1} for quiet-ride and surface preferences. Returns distance (m), duration (s), maneuvers, polyline6 geometry and the ADR costing that was applied. Any of truck, auto, bicycle, pedestrian or motor_scooter routes may set `rationale: true` (opt-in, costs up to 1 + N extra routing calls) to learn which declared truck constraints or avoidance-side preferences (hills, surfaces, tolls, unlit streets, …) actually changed the route (`rationale.avoided[]`, basis route_divergence, it proves a field was binding, it does not identify the physical restriction or feature, and no live traffic or incident data is ever attributed). ADR honesty: `applied_adr.forbidden_tunnel_categories` describes the LOAD, not the returned route, and `applied_adr.tunnel_enforcement` states the boundary: roads are excluded only where the routing graph records an ADR tunnel category, so an unchanged route is not a clearance. Set `landmarks: true` for turn instructions anchored to recognisable places, each manoeuvre that passes one gains a `landmark_instruction` like "Turn right just after the Shell garage" beside the engine's own street-name `instruction`, which is never replaced. Prefer reading it aloud: it is how a passenger gives directions. Nothing is named unless it is recognisable from the road, within 40 m of the junction and not tagged as closed, so many routes return none and a `landmarks.annotated` of 0 with no `note` means this route genuinely passes nothing recognisable. Needs the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY), whose place index does the lookup. Through the gateway each manoeuvre also carries the road it starts on: `country`, `subdivision`, `ref` (route numbers only), `road_class`, `speed_limit_unit` (`mph` or `km/h`, from the road's country), `speed_limit_sign` (`vienna` or `mutcd`), `speed_limit_posted` (the limit as the sign shows it, in the road's unit) and `driving_side`; each is absent when the map does not know it, never guessed. Optional `exclude_polygons` for what-if scenarios ("close this bridge and re-route"): an array of polygons, each an array of [lon, lat] pairs forming one ring (longitude FIRST) whose intersecting roads are excluded from the search. Applies to the Valhalla engine; unsupported on the GraphHopper engine, where it is ignored. Optional `avoid` and `exclude` name road features to keep off, and the difference between them is not cosmetic. `avoid` ("tolls", "highways", "ferries") is a PREFERENCE: it sets the costing's willingness to zero, and the engine's own reference says that is not guaranteed to avoid the feature, measured, avoiding tolls across the Dartford Crossing returns the same tolled rout
What a journey PASSES, in sentences ready to be read aloud, each with its position along the route. The named rivers and canals it crosses, the road it runs on and for how far, the settlements it goes through, the protected landscapes it enters and how high the road climbs: the things a passenger who knew the area would say. NONE OF THIS IS IN A ROUTE: a route is a list of movements and a river crossing is not a movement, so do not try to read it out of `route`'s answer. Give `geometry_polyline6` straight from the `route` tool, plus optional `units` ("miles" default, or "kilometers"), `min_gap_m` and `max_observations`. Each observation carries `at_m` (WHERE it belongs (delivered anywhere else it is trivia, not an observation), a `kind`, a `say` sentence to relay verbatim, and a `basis` naming the map layer and tag the claim rests on. THE SILENCE BUDGET IS THE DESIGN: `min_gap_m` is a floor, not a target, and when a route yields more than `max_observations` the gap WIDENS on its own so the survivors stay spread over the whole journey rather than clustering where the map happened to be richest. Inside a window the rarer kind wins. So a short list on a long route is the budget working, not thin data. READ `coverage` BEFORE REPORTING AN EMPTY LIST: an empty `observations` with `tiles_read` of 0 means NO DATA WAS READ, which is not the same claim as quiet countryside, and `uncovered_m` says how much of the route could not be seen at all. Two things it will never say, deliberately: it never names a hill (a peak two kilometres away behind a ridge is named confidently and seen by nobody), and it never reads a junction number (an observation mistakable for an instruction is not safe to speak beside real guidance). A settlement is a labelled POINT, not a boundary, and `offset_m` publishes the distance behind the word "through". It is a query and it triggers nothing: no position is held and nothing is pushed. COSTS 10 UNITS a call, flat, whatever is asked for. Requires the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY), whose basemap archive and elevation model answer it; a deployment with no archive answers 501 and says so.
| Parameter | Type | Description |
|---|---|---|
| units | ["string","null"] | Units for the spoken distances: `miles` (default) or `kilometers`. `kilometres` and `km` are accepted too. |
| min_gap_m | ["number","null"] | Least distance along the route between two observations, metres (default 2000). A FLOOR, not a target: when the route holds more than `max_observations`, the gap widens past this on its own so the survivors stay spread over the whole journey. |
Find places (POIs) along a route with the REAL extra travel time of stopping at each, never a straight-line guess. Provide `origin` + `destination` (a route is computed) or an existing route's `geometry_polyline6`, plus a free-text `query` ("coffee", "EV charger", "truck stop") and `max_detour_minutes` (default 10). For a category intent ("fuel", "EV charger", "coffee") pass `category` instead of relying on words alone: it takes the same vocabulary as `nearby_places` (lowercased OSM tag values such as "fuel", "cafe", "charging_station", "parking", "pharmacy"), and common colloquial phrases are normalised server-side ("petrol station" and "gas station" to fuel, "coffee" to cafe, "EV charger" to charging_station). `query` alone also promotes a pure category phrase to the same browse, so "fuel" finds fuel stations rather than places whose NAME starts "Ful"; anything else stays free-text name matching. When a browse ran, the response echoes the tokens used in `matched_categories`. Candidates near the route corridor are priced through the routing engine with your costing: detour = (origin→place) + (place→destination) − (origin→destination). Costing "auto", "truck" (with a `truck` profile the detours respect dimensional/ADR restrictions), "bicycle", "pedestrian" or "motor_scooter". Returns results sorted by detour with detour_minutes, detour_km, along_route_position (0-1) and off_route_m; at most 25 candidates are priced per call (candidate_cap).
| Parameter | Type | Description |
|---|---|---|
| query * | string | Free-text POI query, e.g. "coffee", "EV charger", "truck stop". |
| truck | any | Truck profile (dimensions + ADR declaration). Requires costing "truck"; the detours then respect dimensional/ADR restrictions. |
| origin | any | Route origin (with `destination`, when no geometry is given). |
| costing | ref | Costing model for the route and detour matrix: "auto" (default), "truck", "bicycle", "pedestrian" or "motor_scooter". |
| category |
Set one MapLibre layout property on one skeleton layer of a hosted style (e.g. layer_id "road-path", property "line-cap", value "round"; null removes the property) and publish the result as a new immutable style version. Pair it with set_layer_paint for line patterns: dotted footpaths are road-path line-dasharray [0, 2] plus line-cap round. Layer ids come from list_style_layers. Returns the new version and style URL.
| Parameter | Type | Description |
|---|---|---|
| value * | any | The layout value (any MapLibre-valid JSON, e.g. "round"), or null to remove the property and fall back to the skeleton's. |
| layer_id * | string | Skeleton layer id, e.g. "road-path". Call `list_style_layers` for the accepted ids. |
| property * | string | MapLibre layout property name, e.g. "line-cap", "line-join" or "visibility". |
| style_id * | string | Hosted style id. |
{
"name": "set_layer_layout",
"description": "Set one MapLibre layout property on one skeleton layer of a hosted style (e.g. layer_id \"road-path\", property \"line-cap\", value \"round\"; null removes the property) and publish the result as a new immutable style version. Pair it with set_layer_paint for line patterns: dotted footpaths are road-path line-dasharray [0, 2] plus line-cap round. Layer ids come from list_style_layers. Returns the new version and style URL.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"style_id",
"layer_id",
"property",
"value"
],
"properties": {
"value": {
"description": "The layout value (any MapLibre-valid JSON, e.g. \"round\"), or null\nto remove the property and fall back to the skeleton's."
},
"layer_id": {
"type": "string",
"description": "Skeleton layer id, e.g. \"road-path\". Call `list_style_layers`\nfor the accepted ids."
},
"property": {
"type": "string",
"description": "MapLibre layout property name, e.g. \"line-cap\", \"line-join\" or\n\"visibility\"."
},
"style_id": {
"type": "string",
"description": "Hosted style id."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"style_id",
"version",
"style_url"
],
"properties": {
"version": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "The newly published version."
},
"style_id": {
"type": "string",
"description": "Hosted style id."
},
"style_url": {
"type": "string",
"description": "Immutable URL of the compiled style at this version."
}
}
}
}Set one MapLibre paint property on one skeleton layer of a hosted style (e.g. layer_id "road-major", property "line-width", value 4 or an expression array; null removes the property, e.g. line-dasharray null draws the dashed road-path solid) and publish the result as a new immutable style version. Layer ids come from list_style_layers. Returns the new version and style URL.
| Parameter | Type | Description |
|---|---|---|
| value * | any | The paint value (any MapLibre-valid JSON: number, colour string or expression array), or null to remove the property (for example `line-dasharray` null draws a dashed skeleton layer solid). |
| layer_id * | string | Skeleton layer id, e.g. "road-major". Call `list_style_layers` for the accepted ids. |
| property * | string | MapLibre paint property name, e.g. "line-width" or "fill-color". |
| style_id * | string | Hosted style id. |
{
"name": "set_layer_paint",
"description": "Set one MapLibre paint property on one skeleton layer of a hosted style (e.g. layer_id \"road-major\", property \"line-width\", value 4 or an expression array; null removes the property, e.g. line-dasharray null draws the dashed road-path solid) and publish the result as a new immutable style version. Layer ids come from list_style_layers. Returns the new version and style URL.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"style_id",
"layer_id",
"property",
"value"
],
"properties": {
"value": {
"description": "The paint value (any MapLibre-valid JSON: number, colour string or\nexpression array), or null to remove the property (for example\n`line-dasharray` null draws a dashed skeleton layer solid)."
},
"layer_id": {
"type": "string",
"description": "Skeleton layer id, e.g. \"road-major\". Call `list_style_layers`\nfor the accepted ids."
},
"property": {
"type": "string",
"description": "MapLibre paint property name, e.g. \"line-width\" or \"fill-color\"."
},
"style_id": {
"type": "string",
"description": "Hosted style id."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"style_id",
"version",
"style_url"
],
"properties": {
"version": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "The newly published version."
},
"style_id": {
"type": "string",
"description": "Hosted style id."
},
"style_url": {
"type": "string",
"description": "Immutable URL of the compiled style at this version."
}
}
}
}Recolour one or more palette slots of a hosted style (e.g. {"water": "#0b2038", "roadMajor": "#8a6d3b"}) and publish the result as a new immutable style version. Slot names come from list_style_layers; colours are CSS (#rgb/#rrggbb/#rrggbbaa/rgb()/hsl()). Returns the new version and style URL.
| Parameter | Type | Description |
|---|---|---|
| colours * | object | Palette overrides: slot name → CSS colour (e.g. {"water": "#0b2038"}). Call `list_style_layers` for the slot names. |
| style_id * | string | Hosted style id. |
{
"name": "set_palette",
"description": "Recolour one or more palette slots of a hosted style (e.g. {\"water\": \"#0b2038\", \"roadMajor\": \"#8a6d3b\"}) and publish the result as a new immutable style version. Slot names come from list_style_layers; colours are CSS (#rgb/#rrggbb/#rrggbbaa/rgb()/hsl()). Returns the new version and style URL.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"style_id",
"colours"
],
"properties": {
"colours": {
"type": "object",
"description": "Palette overrides: slot name → CSS colour (e.g.\n{\"water\": \"#0b2038\"}). Call `list_style_layers` for the slot names.",
"additionalProperties": {
"type": "string"
}
},
"style_id": {
"type": "string",
"description": "Hosted style id."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"style_id",
"version",
"style_url"
],
"properties": {
"version": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "The newly published version."
},
"style_id": {
"type": "string",
"description": "Hosted style id."
},
"style_url": {
"type": "string",
"description": "Immutable URL of the compiled style at this version."
}
}
}
}OPERATOR WRITE, ADMIN ONLY. Asserts a short-lived closure (`assert: {kind: closed}`) or speed (`{kind: speed_override, speed_kph}`, 1 to 120) on named OSM `way_ids` (1 to 20) and `direction` (forward, backward or both, default both), for `ttl_secs` (60 to 86400), with a `reason` and an optional `evidence_url`. The record expires on its own, ranks below official closures and is logged with the reason. NEVER CALL THIS WITHOUT A PERSON'S EXPLICIT APPROVAL OF THIS EXACT CLOSURE IN THIS CONVERSATION: draft it, show it, stop, and call it only after a yes. Available only where the operator runs sn-mcp locally with SN_CAMERA_INCIDENTS_ENABLED=true and SN_ADMIN_TOKEN set; everywhere else it refuses and says why. Whether a live traffic writer applies it is reported in `applied_by_live_writer`; false means the record is stored but no road changes.
| Parameter | Type | Description |
|---|---|---|
| assert * | ref | `closed` or a speed in km/h (1..=120). |
| reason * | string | Why, for the audit log and the incidents endpoint note. |
| way_ids * | array | OSM way ids to assert on; at most 20. |
| ttl_secs * | integer | Lifetime, seconds, 60..=86400. |
| direction | ref | Carriageway, default `both`. |
| evidence_url | ["string","null"] | Evidence link, if any. |
The planetary Kp index and the NOAA SWPC OVATION aurora forecast right now. No input. Returns `kp` (0 to 9) with its time, the forecast's valid time, the peak aurora probability and `aurora_png_url` (a 360 by 181 probability grid, percent per pixel, column 0 at 180 W, row 0 at 90 N) when the forecast is under an hour old; `status` is `unavailable` when it is older and nothing should be drawn. A FORECAST about 30 to 90 minutes ahead, not an observation; never present it as a sighting or a guarantee. Requires the MapMap gateway. Display the returned `attribution`; no endorsement by NOAA is implied.
No parameters.
{
"name": "space_weather_now",
"description": "The planetary Kp index and the NOAA SWPC OVATION aurora forecast right now. No input. Returns `kp` (0 to 9) with its time, the forecast's valid time, the peak aurora probability and `aurora_png_url` (a 360 by 181 probability grid, percent per pixel, column 0 at 180 W, row 0 at 90 N) when the forecast is under an hour old; `status` is `unavailable` when it is older and nothing should be drawn. A FORECAST about 30 to 90 minutes ahead, not an observation; never present it as a sighting or a guarantee. Requires the MapMap gateway. Display the returned `attribution`; no endorsement by NOAA is implied.",
"inputSchema": {
"type": "object",
"properties": {}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"status",
"threshold_s",
"summary",
"label",
"attribution",
"endorsement"
],
"properties": {
"kp": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Planetary Kp index, 0 to 9."
},
"age_s": {
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0,
"description": "Seconds since the forecast time when the answer was assembled."
},
"label": {
"type": "string",
"description": "\"Forecast, not an observation\". Pass it on."
},
"status": {
"type": "string",
"description": "`ok`, `unavailable` (the forecast is over an hour old: draw\nnothing) or `unknown` (no data)."
},
"kp_time": {
"type": [
"string",
"null"
],
"description": "When the Kp value applies (RFC 3339 UTC)."
},
"summary": {
"type": "string",
"description": "One sentence for the answer. Pass it on with its qualifier."
},
"attribution": {
"type": "string",
"description": "NOAA SWPC credit. Display it."
},
"endorsement": {
"type": "string",
"description": "No endorsement by or affiliation with NOAA is implied."
},
"threshold_s": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "The age in seconds after which the forecast is unavailable."
},
"forecast_time": {
"type": [
"string",
"null"
],
"description": "The time the aurora forecast is valid for (RFC 3339 UTC)."
},
"aurora_png_url": {
"type": [
"string",
"null"
],
"description": "URL of the 360 by 181 probability grid (percent per pixel, column\n0 at 180 W, row 0 at 90 N); present only while the forecast is\nfresh. Needs the caller's own MapMap key."
},
"max_probability": {
"type": [
"integer",
"null"
],
"format": "uint8",
"maximum": 255,
"minimum": 0,
"description": "Peak aurora probability anywhere on the grid, percent."
},
"observation_time": {
"type": [
"string",
"null"
],
"description": "The observation the forecast was made from (RFC 3339 UTC)."
}
}
}
}Send MapMap a structured integration retro (problems, gotchas, wins, docs gaps). Call at most once, after your MapMap integration works or you stop trying, and only if the developer has approved sending feedback to MapMap. Sends ONLY the structured fields in this schema to MapMap: there is no field for a transcript, a prompt, source code, file contents or coordinates. The free-text fields are short and capped, but they are still free text: do NOT paste code, credentials, customer names or personal data into them. Provide `what_built` (required), `problems` [{area: sdk|api|mcp|docs|billing|self-host|other, description, workaround_found}], `gotchas`, `wins`, `docs_gaps`, and optionally `agent_name` and `sdk_version`.
| Parameter | Type | Description |
|---|---|---|
| wins | array | What went well (at most 20 entries × 500 bytes). |
| gotchas | array | Surprises/traps worth documenting (at most 20 entries × 500 bytes). |
| problems | array | Problems hit during the integration (at most 20). |
| docs_gaps | array | Documentation gaps hit (at most 20 entries × 500 bytes). |
| agent_name | ["string","null"] | The submitting agent's name, e.g. "Claude Code" (at most 100 bytes). |
| what_built * | string | What was built with MapMap, in one or two sentences (required, at most 500 bytes). |
| sdk_version | ["string","null"] | MapMap SDK version integrated against, when known (at most 50 bytes). |
Submit a problem too large to solve inside one request to the asynchronous lane, and get a job id back. Set `kind` to "optimise", "replan", "matrix" or "coverage". For the first three, pass `problem` in EXACTLY the shape the matching synchronous tool takes, `optimise_routes` input, `replan_routes` input, or `matrix` input. Moving a working synchronous call onto this lane changes nothing but which tool you call it with. A field that tool's input does not have is REFUSED by name rather than dropped: the HTTP API accepts some the MCP tools have not surfaced yet, and a job queued without a constraint you asked for is worse than one that was never queued. "coverage" plans one drive that passes along EVERY street in an area at least once, in the legal direction, split into outings (the Chinese postman problem on the real road network): survey capture, street sweeping, gritting, refuse rounds. It has no synchronous tool; its `problem` is the POST /v1/jobs/coverage body: exactly one of `bbox` ([min_lon, min_lat, max_lon, max_lat]) or `polygon` (GeoJSON), and optionally `costing` ("auto" or "truck"), `optimise` ("distance", "time" or "balanced"), `road_classes` {include, exclude}, `include_private`, `turn_penalties` {avoid_left, avoid_right, avoid_u_turn} in metres per turn, `chunk_km` (outing length, default 15; outings land as close to it as the streets allow) or instead `chunk_time_s` (outing time, 900 to 21,600 s; both is refused: each outing's `trip_time_s`, with `chunk_loops` its transfers included), `chunk_tolerance` (default 0.25, 0.05 to 0.5: the band either way of the target an outing counts as on target), `time_factor` (0.5 to 3, default 1: multiplies every time, a pace correction for a vehicle slower than the graph's speeds), `start` {lat, lon, heading?, snap?}, `return_to_start`, `boundary`, `max_outside_m`, `chunk_loops`, `loop_radius_m`, `exclude`, `avoid` and `required`. `start` snaps to the nearest junction the plan passes; with `snap: "exact"` the drive starts where the car is (on the street within 50 m, facing `heading` if given, never turning round in the street) and the drive from there to the plan is planned too: outing 1's first steps, or with `chunk_loops` its `transfer_from_previous` (`summary.approach_km`). `return_to_start: false` ends the plan wherever leaves the least driving. `boundary` ("touching" default, "mostly_inside", "inside") decides which streets crossing the area's edge must be covered. `max_outside_m` (0 to 2,000 m) holds the drive within that distance of the area's edge: streets crossing the edge that reach further out are not covered, and divided roads turn round inside the limit where they can; `summary.outside_area` lists every stretch of the drive outside the area, how far it goes and, with the limit, which go past it because nothing within it joins up. `chunk_loops: true` makes every outing a closed loop that starts and ends at the same junction, with the drive between outings planned as a separate route (each chunk's `transfer_from_previous`, plus `transfer_to_start` with `return_to_start`); `walk_km` excludes those transfers (`summary.transfer_km` has them), and `summary.outings_outside_target` names any outing outside the target x (1 +/- `chunk_tolerance`) and why; `summary.outing_km` and `summary.outing_time_s` give the median, p10, p90, min and max outing km and trip time and how many are within 10 % and within the tolerance. Drive times include the engine's own junction time (turns, U-turns, signals). `loop_radius_m` (0 to 2,000 m, only with `chunk_loops`) lets an outing end within that distance of its start when that saves driving; `loop_end: "last_covered"` (only with `chunk_loops`) ends an outing where its last covered street does instead of driving back over covered streets, when the drive on is then shorter; `chunk_measure: "trip"` (only with `chunk_loops`, not with `chunk_time_s`) aims `chunk_km` at each outing's `trip_km` (the outing and its transfers) instead of its own km; `
Check whether a dataset's DECLARED coordinate reference system actually describes its own coordinates, before you draw it on a map. Catches the failures that are otherwise silent: swapped lat/lon axes, degrees labelled as metres, and Web Mercator or another projection mislabelled with a UTM or national-grid code. Pass the declared CRS (e.g. "EPSG:4326") and a sample of the raw coordinates as {x, y} in the dataset's OWN units, deliberately not named lon/lat, because whether they are degrees is the question. Returns a verdict (consistent / suspect / impossible), what is wrong in plain language, and where the numbers actually point when read another way. This is a sanity check, not a reprojection: it never transforms coordinates. Local computation: no network call, no quota.
| Parameter | Type | Description |
|---|---|---|
| coordinates * | array | A sample of the dataset's coordinates. A few dozen is plenty; the check is about ranges and spans, not volume. |
| declared_crs * | string | The CRS the dataset claims, e.g. `"EPSG:4326"`, `"EPSG:32610"`, `"EPSG:3857"`, `"EPSG:27700"`. |
{
"name": "validate_geodata",
"description": "Check whether a dataset's DECLARED coordinate reference system actually describes its own coordinates, before you draw it on a map. Catches the failures that are otherwise silent: swapped lat/lon axes, degrees labelled as metres, and Web Mercator or another projection mislabelled with a UTM or national-grid code. Pass the declared CRS (e.g. \"EPSG:4326\") and a sample of the raw coordinates as {x, y} in the dataset's OWN units, deliberately not named lon/lat, because whether they are degrees is the question. Returns a verdict (consistent / suspect / impossible), what is wrong in plain language, and where the numbers actually point when read another way. This is a sanity check, not a reprojection: it never transforms coordinates. Local computation: no network call, no quota.",
"inputSchema": {
"type": "object",
"$defs": {
"XY": {
"type": "object",
"required": [
"x",
"y"
],
"properties": {
"x": {
"type": "number",
"format": "double"
},
"y": {
"type": "number",
"format": "double"
}
},
"description": "One coordinate from the dataset, in the dataset's own units, NOT\nnecessarily degrees. Named `x`/`y` rather than `lon`/`lat` precisely\nbecause whether they are degrees is the thing in question."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"declared_crs",
"coordinates"
],
"properties": {
"coordinates": {
"type": "array",
"items": {
"$ref": "#/$defs/XY"
},
"description": "A sample of the dataset's coordinates. A few dozen is plenty; the\ncheck is about ranges and spans, not volume."
},
"declared_crs": {
"type": "string",
"description": "The CRS the dataset claims, e.g. `\"EPSG:4326\"`, `\"EPSG:32610\"`,\n`\"EPSG:3857\"`, `\"EPSG:27700\"`."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"Extent": {
"type": "object",
"required": [
"min_x",
"max_x",
"min_y",
"max_y"
],
"properties": {
"max_x": {
"type": "number",
"format": "double"
},
"max_y": {
"type": "number",
"format": "double"
},
"min_x": {
"type": "number",
"format": "double"
},
"min_y": {
"type": "number",
"format": "double"
}
}
},
"Verdict": {
"oneOf": [
{
"type": "string",
"const": "consistent",
"description": "Coordinates are consistent with the declared CRS."
},
{
"type": "string",
"const": "suspect",
"description": "Consistent only under an assumption worth stating (e.g. the values\nfit, but the axis order looks swapped)."
},
{
"type": "string",
"const": "impossible",
"description": "The declared CRS cannot describe these coordinates at all."
}
],
"description": "How much the declared CRS and the coordinates disagree."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"verdict",
"interpreted_as",
"problems",
"suggestions",
"extent"
],
"properties": {
"extent": {
"$ref": "#/$defs/Extent",
"description": "Observed extent of the sample, in the dataset's own units."
},
"verdict": {
"$ref": "#/$defs/Verdict"
},
"problems": {
"type": "array",
"items": {
"type": "string"
},
"description": "Plain-language findings, most important first. Empty when consistent."
},
"suggestions": {
"type": "array",
"items": {
"type": "string"
},
"description": "What the numbers look like, when they do not match the declaration."
},
"interpreted_as": {
"type": "string",
"description": "The CRS family the declaration was understood as."
}
}
}
}Check whether places (and itineraries) an AI mentioned are real, findable and physically possible. Pass structured `claims` (reliable, and the only path that supports itinerary feasibility) or free `text` (best-effort quoted-phrase extraction). Each claim resolves to exactly one of three verdicts, never a boolean: "verified" (matched a real place, with its stable id and the source/date of the evidence), "contradicted" (a specific, dated, sourced fact rules it out, currently only an itinerary leg the routing engine proves cannot be driven in the stated time, with the computed travel time as evidence), or "unverified" (no evidence either way). This tool NEVER asserts that a named real business does not exist or has closed, that would be a defamation risk with no upside; a missing match is always "unverified". Claims sharing increasing `sequence` values and both carrying `claimed_time` (ISO 8601) form itinerary legs checked for feasibility via `matrix`, catching e.g. "breakfast in Bath, 10am meeting in Edinburgh". Max 20 claims per request. A claim takes only `id`, `name`, `locality`, `sequence` and `claimed_time`; any other field (e.g. `near`) is refused naming the accepted ones, so put disambiguating context such as a town in `locality`. The response's `summary` field is a concise plain-text digest (also returned as this tool result's text content) so clients that drop structured/non-text content blocks still see the verdicts.
| Parameter | Type | Description |
|---|---|---|
| text | ["string","null"] | Free text to extract place claims from (best-effort heuristic: quoted phrases and Title Case runs after "at/in/near/to/from/ visiting", not NLP or an LLM call, and it does not attempt itinerary feasibility since there are no explicit times to anchor legs to). Mutually exclusive with `claims`. Max 8,… |
| claims | ["array","null"] | Structured claims, the reliable path, and the only path that supports itinerary feasibility. Mutually exclusive with `text`. Max 20 per request. |
| costing | ref | Costing for feasibility legs: "auto" (default), "truck", "bicycle", "pedestrian" or "motor_scooter". |
Forecast weather along a route, each sample read for the hour you actually reach it rather than the weather right now. Pass the route's `shape` (an encoded polyline6, the `route` tool's geometry_polyline6), optional `depart_at` (RFC 3339, default now), the route's `duration_s` (from `route`; omitted, an 80 km/h average is assumed and `duration_source` says so) and optional `sample_interval_m` (default 25,000, 5,000 to 100,000, at most 40 samples). Each sample carries its ETA, temperature, rain, snowfall, precipitation type and probability, wind and gust speed, visibility, the WMO weather code and `severe` (thunderstorm and heavy precipitation codes only). It is a FORECAST, not an observation: read on a 0.05 degree grid (about 5.5 km) at the nearest hour, up to 16 days ahead, and samples past that horizon or without data come back `available: false` with a reason, never painted dry. `summary` is one sentence (where rain or snow starts and for how far, the strongest gust, samples without data) and always ends by saying it is advisory, never a routing guarantee: keep that qualifier when you pass it on. Requires the MapMap gateway; a deployment without a weather source answers a clear error. Display the returned `attribution` with the forecast, linked to `attribution_url`, with `licence_url` (CC BY 4.0) linked; `derived_fields` names the sample fields MapMap derives rather than Open-Meteo supplies.
| Parameter | Type | Description |
|---|---|---|
| shape * | string | The route shape as an encoded polyline6 (the `route` tool's `geometry_polyline6`). |
| depart_at | ["string","null"] | Departure time, RFC 3339 (e.g. "2026-10-12T14:00:00Z"); defaults to now. Forecasts reach about 16 days ahead; samples past that answer unavailable. |
| duration_s | ["number","null"] | The route's duration in seconds, used to work out when you reach each sample. Pass the `route` tool's duration; omitted, a generic 80 km/h average is assumed and `duration_source` says so. |
| sample_interval_m | ["number","null"] |
The NOAA GFS forecast frames MapMap publishes for drawing weather on a map: 17 frames (0 to 48 hours every 3 hours) of the newest run, each with URLs for the global rain, temperature, cloud, gust and sea-level pressure PNG fields (1440 by 721, value-encoded; decode with `encodings`), the wind field (PNG plus JSON ranges) and XYZ tile templates for rain, temperature and isobars. Optional `run` (YYYYMMDDHH) and `fields`. The URLs need the caller's own MapMap key. A FORECAST, not an observation, processed by MapMap from NOAA GFS 0.25 degree data (regridded and quantised): never describe it as original NOAA data or imply NOAA endorsement. `status` says whether the newest run is fresh. Requires the MapMap gateway. Display the returned `attribution`.
| Parameter | Type | Description |
|---|---|---|
| run | ["string","null"] | A forecast run as YYYYMMDDHH (UTC), e.g. "2026101700". Default: the newest run. |
| fields | ["array","null"] | Which fields to return URLs for, any of `rain`, `temp`, `cloud`, `gust`, `mslp`, `wind`, `isobars`. Default: all. |
{
"name": "weather_frames",
"description": "The NOAA GFS forecast frames MapMap publishes for drawing weather on a map: 17 frames (0 to 48 hours every 3 hours) of the newest run, each with URLs for the global rain, temperature, cloud, gust and sea-level pressure PNG fields (1440 by 721, value-encoded; decode with `encodings`), the wind field (PNG plus JSON ranges) and XYZ tile templates for rain, temperature and isobars. Optional `run` (YYYYMMDDHH) and `fields`. The URLs need the caller's own MapMap key. A FORECAST, not an observation, processed by MapMap from NOAA GFS 0.25 degree data (regridded and quantised): never describe it as original NOAA data or imply NOAA endorsement. `status` says whether the newest run is fresh. Requires the MapMap gateway. Display the returned `attribution`.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"run": {
"type": [
"string",
"null"
],
"description": "A forecast run as YYYYMMDDHH (UTC), e.g. \"2026101700\". Default: the\nnewest run."
},
"fields": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Which fields to return URLs for, any of `rain`, `temp`, `cloud`,\n`gust`, `mslp`, `wind`, `isobars`. Default: all."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"WeatherFrameOut": {
"type": "object",
"required": [
"hour",
"valid_at",
"urls",
"tiles"
],
"properties": {
"half": {
"type": [
"object",
"null"
],
"description": "Half-resolution PNG URLs by field, when the run has them.",
"additionalProperties": {
"type": "string"
}
},
"hour": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "Hours after the run time."
},
"urls": {
"type": "object",
"description": "Absolute URLs by field (global value-encoded PNGs; wind also has a\nJSON ranges file under `wind_json`). Each needs the caller's own\nMapMap key.",
"additionalProperties": {
"type": "string"
}
},
"tiles": {
"type": "object",
"description": "XYZ tile templates by field (`rain`, `temp`: PNG; `isobars`: MVT).",
"additionalProperties": {
"type": "string"
}
},
"valid_at": {
"type": "string",
"description": "The time the frame is valid for (RFC 3339 UTC)."
}
},
"description": "One forecast frame."
},
"WeatherModelOut": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"description": "Model id (\"gfs\")."
},
"step_h": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Hours between frames."
},
"horizon_h": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Hours covered from the run time."
},
"frames_per_run": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Frames in a run."
},
"resolution_deg": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Grid resolution of the source data, degrees."
}
},
"description": "The forecast model behind the frames."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"status",
"run",
"run_id",
"generated_at",
"threshold_s",
"model",
"frames",
"encodings",
"summary",
"label",
"attribution",
"processed_by",
"note"
],
"properties": {
"run": {
"type": "string",
"description": "The run time (RFC 3339 UTC)."
},
"note": {
"type": "string",
"description": "Derived from NOAA GFS and modified by MapMap; no NOAA endorsement\nis implied. Pass it on."
},
"age_s": {
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0,
"description": "Seconds since `generated_at` when the answer was assembled."
},
"label": {
"type": "string",
"description": "\"Forecast, not an observation\". Pass it on."
},
"model": {
"$ref": "#/$defs/WeatherModelOut",
"description": "The forecast model."
},
"frames": {
"type": "array",
"items": {
"$ref": "#/$defs/WeatherFrameOut"
},
"description": "The frames, in hour order."
},
"run_id": {
"type": "string",
"description": "The run as YYYYMMDDHH."
},
"status": {
"type": "string",
"description": "`ok`, `stale` (the newest run is older than the threshold) or\n`unknown` (no frames). Pass a stale or unknown status on."
},
"summary": {
"type": "string",
"description": "One sentence for the answer. Pass it on with its qualifier."
},
"encodings": {
"description": "How to decode each PNG field (unit, scale, offset), verbatim from\nthe manifest."
},
"attribution": {
"type": "string",
"description": "NOAA GFS credit. Display it."
},
"threshold_s": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "The age in seconds after which the frames count as stale."
},
"generated_at": {
"type": "string",
"description": "When MapMap published the manifest (RFC 3339 UTC)."
},
"processed_by": {
"type": "string",
"description": "\"MapMap\": the data is processed by MapMap."
}
}
}
}MapMap: a self-hosted multi-modal routing platform, cars, trucks (with first-class ADR dangerous-goods support), bicycles, pedestrians and motor scooters. Tools: `route` computes turn-by-turn routes (costing "auto", "truck", "bicycle", "pedestrian" or "motor_scooter", pass a `truck` profile with dimensions and the ADR declaration to apply dimensional and hazmat restrictions to the search (see `applied_adr.tunnel_enforcement` for what a returned route does and does not prove), `pedestrian` options for lit-street preference, wheelchair/blind profiles, hills, surface quality and hiking difficulty, or `bicycle` options for bicycle type and road/surface/hill preferences; every one of these costings accepts `rationale: true` for an honest why-this-route explanation derived by route divergence); `search_along_route` finds POIs along a route with each one's real engine-computed detour cost ("coffee, adds 4 min"); `cheapest_fuel_along_route` ranks fuel stations along a route cheapest-first from live open-data price feeds (UK, FR, DE) with engine-computed detours, a 24-hour staleness flag (a stale price ranks below every fresh one and claims no saving), the saving vs the cheapest on-route baseline and a coverage statement naming the UK retailers covered, show it, because an empty UK result means "none from these retailers", never "no fuel here"; `cheapest_charging_along_route` ranks EV charge points along a route most-powerful-first from operator-published charge-point data, with engine-computed detours, connector and minimum-kW filters, and a coverage statement naming the operators covered, show it, because an empty result means "none from these operators", never "no chargers here"; `plan_ev_route` plans a whole EV journey, physics consumption over the route's legs, charge stops chosen so the state of charge never breaches the reserve floor, and charge times integrated over the vehicle's own charging curve rather than energy divided by peak power, and answers `feasible: false` with a named cause and the furthest reachable point rather than inventing a plan; `weather_along_route` reads the forecast for the hour each point of a route is reached (rain, snow, gusts, visibility, a severe flag) and answers with one summary sentence; it is a forecast, advisory and never a routing guarantee, so say so when you pass it on; `nearby_stops` finds England bus and coach stops near a point (NaPTAN ATCO codes, the lines calling there) and `next_departures` gives a stop's timetabled departures, each with any vehicle seen on that line heading towards the stop; they are timetable times and display data, never journey plans or arrival predictions, so pass on the `label` and `coverage` they return; `events_in_area` returns earthquakes, US-monitored volcano alerts and satellite-detected fire heat (not confirmed fires) in a box, `space_weather_now` the Kp index and the NOAA aurora forecast, and `weather_frames` the NOAA GFS forecast frames MapMap processes for drawing weather; all three are reported or forecast data for display, never a warning service, so pass on their status and `summary`; `nearby_places` finds places near a point by category (cafes, fuel, EV charging, parking, pharmacies) and/or by name or brand ("the nearest Lloyds bank"), nearest first with distance in metres; both `nearby_places` and `reverse_geocode` can answer egocentrically, pass `heading_deg` (and optionally `fov_deg`) and every result carries a `direction` phrased from where the user is standing ("ahead and slightly to your right, about 80 metres"), which is what a voice or wearable client should read out instead of coordinates; `route` also takes `landmarks: true` for turn instructions anchored to recognisable places ("Turn right just after the Shell garage") alongside the engine's own, which is what a driver or a voice client actually navigates by; `plan_day` turns an itinerary (names or coordinates, dwell times, optional optimisation) into one navigable multi-stop route with pe
Names, descriptions and schemas were written by the server and are shown as data.
Pattern matches on what the server declares. They show what it says it can do, not what it does.
None yet. Changes appear after a server's second daily check.
| costing | ref | Costing model for the route and detour matrix: "auto" (default), "truck", "bicycle", "pedestrian" or "motor_scooter". |
| connectors | ["array","null"] | Keep only charge points offering at least one of these connector standards: "type2", "type1", "ccs", "chademo", "tesla", "domestic" or "other". Omitted ⇒ every standard. |
| destination | any | Route destination. |
| max_results | ["integer","null"] | Maximum results (default 5, at most 25). |
| available_only | ["boolean","null"] | Keep only charge points with a bay reported free right now. Needs the deployment to have a live availability feed; without one the call is refused rather than silently returning nothing. |
| geometry_polyline6 | ["string","null"] | An existing route geometry as an encoded polyline6 (the `route` tool's `geometry_polyline6`). Provide either this or `origin` + `destination`, not both. |
| max_detour_minutes | ["number","null"] | Largest acceptable detour in minutes (default 10, at most 120). |
{
"name": "cheapest_charging_along_route",
"description": "Find the best EV charge points along a route, with the REAL extra travel time of stopping at each one, never a straight-line guess. Provide `origin` + `destination` (a route is computed) or an existing route's `geometry_polyline6`, plus optional `connectors` (\"ccs\", \"type2\", \"chademo\", \"type1\", \"tesla\", \"domestic\", \"other\"), `min_kw` (e.g. 50 for rapid only), `available_only` and `max_detour_minutes` (default 10). Charge points come from operator-published feeds, are costed through the routing engine with your costing (a `truck` profile makes detours respect dimensional/ADR restrictions) and ranked most powerful first, since minutes off the clock are bought with kilowatts. Each result carries max_power_kw, connector_standards, best_connector, evse_count, detour_minutes/detour_km and, where a live feed backs it, available_now. IMPORTANT: there is no national charge-point registry, every deployment covers only the operators it has onboarded, so ALWAYS show the returned `coverage_note` alongside the results. An empty `results` means \"none from these operators within the detour budget\", NEVER \"there are no chargers here\". Statuses are live only when availability_live is true; otherwise they are the values captured at the last ingest and must not be described as current. `say` is ALWAYS present and is the whole answer as one short spoken line, composed by the gateway with the coverage already inside the claim rather than appended to it: it scopes its superlative to the operators this deployment holds, and an empty result's line says the emptiness is about those operators. Prefer reading it verbatim to writing your own summary. Requires the MapMap gateway; answers a clear error when the deployment has no charge-point dataset. Display the returned charging_attribution with the results.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"TruckSpec": {
"type": "object",
"properties": {
"hazmat": {
"type": "boolean",
"default": false,
"description": "Whether the vehicle carries dangerous goods (ADR). Defaults to\nfalse."
},
"width_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle width in metres."
},
"height_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle height in metres."
},
"length_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle length in metres."
},
"tunnel_code": {
"type": [
"string",
"null"
],
"description": "ADR 8.6.4 tunnel restriction code of the load, e.g. \"B\", \"C5000D\",\n\"B/D\", or \"(-)\"/\"none\" for explicitly unrestricted. Leave unset if\nunknown: a hazmat load without a code is conservatively treated as\ncode B (allowed only through category-A tunnels)."
},
"gross_weight_t": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Gross combination weight in metric tonnes."
}
},
"description": "Truck profile for routing: physical dimensions plus the ADR\ndangerous-goods declaration. Omitted dimensions default to the EU\nmaximum authorised dimensions of Council Directive 96/53/EC (4.0 m\nheight, 2.55 m width, 16.5 m length, 40 t gross weight)."
},
"CostingKind": {
"oneOf": [
{
"type": "string",
"const": "auto",
"description": "Standard car costing."
},
{
"type": "string",
"const": "truck",
"description": "Truck costing; honours dimensional limits and, when a `truck`\nprofile is supplied, ADR dangerous-goods restrictions."
},
{
"type": "string",
"const": "bicycle",
"description": "Bicycle costing; tune it with a `bicycle` options object."
},
{
"type": "string",
"const": "pedestrian",
"description": "Pedestrian (walking) costing; tune it with a `pedestrian` options\nobject (lit streets, wheelchair/blind, hiking difficulty)."
},
{
"type": "string",
"const": "motor_scooter",
"description": "Motor scooter (moped) costing: like auto but prefers lower-speed\nroads and may use ways closed to larger motor vehicles."
}
],
"description": "Costing models exposed by the MCP tools (a deliberate subset of the\nValhalla costing list), serialised in snake_case exactly as Valhalla\nnames them."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"truck": {
"anyOf": [
{
"$ref": "#/$defs/TruckSpec"
},
{
"type": "null"
}
],
"description": "Truck profile (dimensions + ADR declaration). Requires costing\n\"truck\"; the detours then respect dimensional/ADR restrictions."
},
"min_kw": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Keep only charge points whose best connector is rated at least this\nmany kW (e.g. 50 for rapid charging only)."
},
"origin": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "Route origin (with `destination`, when no geometry is given)."
},
"costing": {
"$ref": "#/$defs/CostingKind",
"default": "auto",
"description": "Costing model for the route and detour matrix: \"auto\" (default),\n\"truck\", \"bicycle\", \"pedestrian\" or \"motor_scooter\"."
},
"connectors": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Keep only charge points offering at least one of these connector\nstandards: \"type2\", \"type1\", \"ccs\", \"chademo\", \"tesla\", \"domestic\"\nor \"other\". Omitted ⇒ every standard."
},
"destination": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "Route destination."
},
"max_results": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Maximum results (default 5, at most 25)."
},
"available_only": {
"type": [
"boolean",
"null"
],
"description": "Keep only charge points with a bay reported free right now. Needs\nthe deployment to have a live availability feed; without one the\ncall is refused rather than silently returning nothing."
},
"geometry_polyline6": {
"type": [
"string",
"null"
],
"description": "An existing route geometry as an encoded polyline6 (the `route`\ntool's `geometry_polyline6`). Provide either this or `origin` +\n`destination`, not both."
},
"max_detour_minutes": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Largest acceptable detour in minutes (default 10, at most 120)."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"ChargerHit": {
"type": "object",
"required": [
"charger_id",
"source",
"lat",
"lon",
"connector_standards",
"evse_count",
"status_live",
"detour_minutes",
"detour_s",
"along_route_position",
"off_route_m"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "WGS84 latitude in decimal degrees."
},
"lon": {
"type": "number",
"format": "double",
"description": "WGS84 longitude in decimal degrees."
},
"name": {
"type": [
"string",
"null"
],
"description": "Site name, where the operator publishes one."
},
"source": {
"type": "string",
"description": "Which operator feed this came from."
},
"detour_s": {
"type": "number",
"format": "double",
"description": "The same detour in seconds."
},
"operator": {
"type": [
"string",
"null"
],
"description": "Operator display name."
},
"detour_km": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Extra distance of the detour in kilometres, when the engine\nreported distances."
},
"charger_id": {
"type": "string",
"description": "Operator-scoped stable id."
},
"evse_count": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "Number of charging positions (EVSEs) at the site."
},
"updated_at": {
"type": [
"string",
"null"
],
"description": "When the operator last updated this record."
},
"off_route_m": {
"type": "number",
"format": "double",
"description": "Straight-line offset from the route geometry, metres."
},
"status_live": {
"type": "boolean",
"description": "Whether the status came from a live feed rather than the last\ningest."
},
"max_power_kw": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Highest rated power at the site, kW."
},
"available_now": {
"type": [
"boolean",
"null"
],
"description": "Whether a bay is free right now. Present only where a live\navailability feed backs the claim, absent means unknown, never\n\"occupied\"."
},
"best_connector": {
"anyOf": [
{
"$ref": "#/$defs/ChargerConnector"
},
{
"type": "null"
}
],
"description": "The highest-rated connector at the site."
},
"detour_minutes": {
"type": "number",
"format": "double",
"description": "Real extra travel time of stopping here, minutes."
},
"connector_standards": {
"type": "array",
"items": {
"type": "string"
},
"description": "Every distinct connector standard at the site."
},
"along_route_position": {
"type": "number",
"format": "double",
"description": "How far along the route the charge point sits, 0.0–1.0."
}
},
"description": "One charge point along the route, with its real engine-computed detour."
},
"ChargingSource": {
"type": "object",
"required": [
"source_id",
"operator",
"chargers"
],
"properties": {
"licence": {
"type": [
"string",
"null"
],
"description": "Licence or statutory basis of the feed."
},
"chargers": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "How many charge points this operator contributes."
},
"operator": {
"type": "string",
"description": "Operator display name."
},
"source_id": {
"type": "string",
"description": "Operator id."
},
"coverage_note": {
"type": [
"string",
"null"
],
"description": "Plain-language statement of what this operator's feed does and\ndoes not cover."
}
},
"description": "One operator's coverage and licence, as published by the deployment."
},
"ChargerConnector": {
"type": "object",
"required": [
"standard",
"dc"
],
"properties": {
"dc": {
"type": "boolean",
"description": "Whether this connector delivers DC (rapid) rather than AC."
},
"power_kw": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Rated power in kW, where the operator publishes enough to know it."
},
"standard": {
"type": "string",
"description": "Normalised standard: \"type2\", \"type1\", \"ccs\", \"chademo\", \"tesla\",\n\"domestic\" or \"other\"."
},
"power_kw_source": {
"type": [
"string",
"null"
],
"description": "\"declared\" when the operator published the rating, \"derived\" when\nit was computed from voltage × amperage × phases. Never present\nthe two as the same thing to a user."
}
},
"description": "The highest-rated connector at a charge point."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"costing",
"route_length_m",
"candidates_considered",
"candidates_costed",
"candidate_cap",
"max_detour_minutes",
"results",
"coverage_note",
"sources",
"availability_live",
"availability_note",
"say"
],
"properties": {
"say": {
"type": "string",
"description": "**Always present.** The whole answer as one short spoken line,\ncomposed by the gateway. Coverage is inside the claim rather than\nappended to it: the line scopes its superlative to the operators\nthis deployment holds, and an empty result's line says the\nemptiness is about those operators, never about the road. Safe to\nread to a driver verbatim."
},
"note": {
"type": [
"string",
"null"
],
"description": "Why `results` is empty, when it is, the cause, not a bare list."
},
"costing": {
"type": "string",
"description": "The costing the detours were computed with."
},
"results": {
"type": "array",
"items": {
"$ref": "#/$defs/ChargerHit"
},
"description": "Charge points within the detour budget, most powerful first\n(power, then detour)."
},
"sources": {
"type": "array",
"items": {
"$ref": "#/$defs/ChargingSource"
},
"description": "Every operator in the dataset, with its own coverage note and\nlicence. Present even when `results` is empty."
},
"candidate_cap": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "The matrix fan-out cap in force."
},
"coverage_note": {
"type": "string",
"description": "**Always present.** What this deployment's charge-point dataset\ndoes and does not cover. An empty `results` means \"none from these\noperators within the budget\", never \"there are no chargers here\".\nShow this to the user alongside the results."
},
"route_length_m": {
"type": "number",
"format": "double",
"description": "Length of the route geometry in metres."
},
"route_distance_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Direct origin→destination distance in metres."
},
"route_duration_s": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Direct origin→destination travel time in seconds (same estimator\nas the detour legs), when routable."
},
"availability_live": {
"type": "boolean",
"description": "Whether statuses are live (a bring-your-own availability feed) or\nthe values captured at the last ingest."
},
"availability_note": {
"type": "string",
"description": "Plain-language explanation of what the statuses mean here."
},
"candidates_costed": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "Candidates actually costed through the engine (fan-out capped at\n`candidate_cap`, most powerful kept)."
},
"max_detour_minutes": {
"type": "number",
"format": "double",
"description": "The detour budget applied, minutes."
},
"charging_attribution": {
"type": [
"string",
"null"
],
"description": "Attribution string for the charge-point operators actually\nreturned, display it with the results (a licence obligation)."
},
"candidates_considered": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "Charge points matching the filters that passed the corridor\npre-filter."
}
}
}
}| truck | any | Truck profile (dimensions + ADR declaration). Requires costing "truck"; the detours then respect dimensional/ADR restrictions. |
| origin | any | Route origin (with `destination`, when no geometry is given). |
| costing | ref | Costing model for the route and detour matrix: "auto" (default), "truck", "bicycle", "pedestrian" or "motor_scooter". |
| destination | any | Route destination. |
| fill_litres | ["number","null"] | Optional fill size in litres; each result then also carries `saving_total` = `saving_per_litre` × `fill_litres`. |
| max_results | ["integer","null"] | Maximum results (default 5, at most 25). |
| geometry_polyline6 | ["string","null"] | An existing route geometry as an encoded polyline6 (the `route` tool's `geometry_polyline6`). Provide either this or `origin` + `destination`, not both. |
| max_detour_minutes | ["number","null"] | Largest acceptable detour in minutes (default 10, at most 120). |
{
"name": "cheapest_fuel_along_route",
"description": "Find the cheapest fuel along a route, with the REAL extra travel time of stopping at each station, never a straight-line guess. Provide `origin` + `destination` (a route is computed) or an existing route's `geometry_polyline6`, plus a `fuel` code (\"diesel\" default, \"petrol_95\", \"petrol_98\", \"premium_diesel\", \"e85\", \"lpg\") and `max_detour_minutes` (default 10). Stations come from the live open-data price feeds (UK retailer feeds of the closed CMA interim scheme and/or the statutory Fuel Finder, FR prix-carburants, DE Tankerkoenig; the response's `fuel_attribution` names the ones actually matched), are priced through the routing engine with your costing (a `truck` profile makes detours respect dimensional/ADR restrictions) and ranked freshest-priced first and cheapest within that. Each result carries price {value, currency, updated_at, stale}, detour_minutes/detour_km, and saving_per_litre vs the cheapest on-route baseline (pass `fill_litres` to also get saving_total). `stale` = not verifiably fresher than 24 h: true unless BOTH the price's own updated_at and the snapshot's fetch time are inside that window, and true whenever either is missing. A stale price is ranked below every fresh one, is never the baseline, and carries NO saving_per_litre, quote it as \"last seen at X on <date>\", never as a saving. `say` is ALWAYS present and is the whole answer as one short spoken line, composed by the gateway with the number, the detour and the honest qualifier already in it. Prefer reading it verbatim to writing your own summary: a stale price's line states the figure and the day it was last seen and claims no saving, and an empty result's line names the cause rather than implying there is no fuel on that road. `coverage` says what the price snapshot holds (stations, countries, sources) and, when it holds UK stations, carries a `statement` naming the UK retailers covered, with `uk_retailers` and `uk_partial`. Show the statement with any UK answer: when `uk_partial` is true UK prices come only from those retailers' feeds, so an empty UK result means \"none from these retailers\", never \"no fuel here\". An empty result also carries `note`, the cause in prose, which on such a route ends with that statement. Requires the MapMap gateway; answers a clear error when the deployment has no fuel-price dataset. Display the returned fuel_attribution with the prices.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"TruckSpec": {
"type": "object",
"properties": {
"hazmat": {
"type": "boolean",
"default": false,
"description": "Whether the vehicle carries dangerous goods (ADR). Defaults to\nfalse."
},
"width_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle width in metres."
},
"height_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle height in metres."
},
"length_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle length in metres."
},
"tunnel_code": {
"type": [
"string",
"null"
],
"description": "ADR 8.6.4 tunnel restriction code of the load, e.g. \"B\", \"C5000D\",\n\"B/D\", or \"(-)\"/\"none\" for explicitly unrestricted. Leave unset if\nunknown: a hazmat load without a code is conservatively treated as\ncode B (allowed only through category-A tunnels)."
},
"gross_weight_t": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Gross combination weight in metric tonnes."
}
},
"description": "Truck profile for routing: physical dimensions plus the ADR\ndangerous-goods declaration. Omitted dimensions default to the EU\nmaximum authorised dimensions of Council Directive 96/53/EC (4.0 m\nheight, 2.55 m width, 16.5 m length, 40 t gross weight)."
},
"CostingKind": {
"oneOf": [
{
"type": "string",
"const": "auto",
"description": "Standard car costing."
},
{
"type": "string",
"const": "truck",
"description": "Truck costing; honours dimensional limits and, when a `truck`\nprofile is supplied, ADR dangerous-goods restrictions."
},
{
"type": "string",
"const": "bicycle",
"description": "Bicycle costing; tune it with a `bicycle` options object."
},
{
"type": "string",
"const": "pedestrian",
"description": "Pedestrian (walking) costing; tune it with a `pedestrian` options\nobject (lit streets, wheelchair/blind, hiking difficulty)."
},
{
"type": "string",
"const": "motor_scooter",
"description": "Motor scooter (moped) costing: like auto but prefers lower-speed\nroads and may use ways closed to larger motor vehicles."
}
],
"description": "Costing models exposed by the MCP tools (a deliberate subset of the\nValhalla costing list), serialised in snake_case exactly as Valhalla\nnames them."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"fuel": {
"type": [
"string",
"null"
],
"description": "Which fuel to price: \"diesel\" (default), \"petrol_95\", \"petrol_98\",\n\"premium_diesel\", \"e85\" or \"lpg\" (aliases \"petrol\", \"unleaded\",\n\"e10\", \"super_unleaded\", \"e5\", \"b7\" and \"sdv\" are accepted)."
},
"truck": {
"anyOf": [
{
"$ref": "#/$defs/TruckSpec"
},
{
"type": "null"
}
],
"description": "Truck profile (dimensions + ADR declaration). Requires costing\n\"truck\"; the detours then respect dimensional/ADR restrictions."
},
"origin": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "Route origin (with `destination`, when no geometry is given)."
},
"costing": {
"$ref": "#/$defs/CostingKind",
"default": "auto",
"description": "Costing model for the route and detour matrix: \"auto\" (default),\n\"truck\", \"bicycle\", \"pedestrian\" or \"motor_scooter\"."
},
"destination": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "Route destination."
},
"fill_litres": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Optional fill size in litres; each result then also carries\n`saving_total` = `saving_per_litre` × `fill_litres`."
},
"max_results": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Maximum results (default 5, at most 25)."
},
"geometry_polyline6": {
"type": [
"string",
"null"
],
"description": "An existing route geometry as an encoded polyline6 (the `route`\ntool's `geometry_polyline6`). Provide either this or `origin` +\n`destination`, not both."
},
"max_detour_minutes": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Largest acceptable detour in minutes (default 10, at most 120)."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"FuelBaseline": {
"type": "object",
"required": [
"currency",
"value",
"station_id",
"updated_at",
"stale"
],
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "The baseline station's human label, when known."
},
"brand": {
"type": [
"string",
"null"
],
"description": "The baseline station's brand, when known."
},
"stale": {
"type": "boolean",
"description": "True when the baseline price could not be verified fresher than\n24 hours."
},
"value": {
"type": "number",
"format": "double",
"description": "Baseline price per litre."
},
"currency": {
"type": "string",
"description": "ISO 4217 currency this baseline covers."
},
"station_id": {
"type": "string",
"description": "The baseline station's id."
},
"updated_at": {
"type": "string",
"description": "The baseline price's source timestamp, verbatim."
}
},
"description": "The cheapest effectively-on-route option in one currency, what the\ndriver pays by just pulling in without a detour; the reference the\nper-result savings are computed against. Only a fresh price is\neligible, so this is `stale: false` by construction."
},
"FuelCoverage": {
"type": "object",
"required": [
"stations",
"countries",
"sources"
],
"properties": {
"sources": {
"type": "object",
"description": "Feed code to station count (e.g. \"uk\", \"uk-fuelfinder\", \"fr\", \"de\").",
"additionalProperties": {
"type": "integer",
"format": "uint",
"minimum": 0
}
},
"stations": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "Stations in the whole snapshot."
},
"countries": {
"type": "array",
"items": {
"type": "string"
},
"description": "ISO 3166-1 alpha-2 countries the snapshot holds stations for. A\ncountry absent here cannot produce results."
},
"statement": {
"type": [
"string",
"null"
],
"description": "One sentence naming where UK prices come from and which retailers\nare in. Show it to the user with any UK answer: when `uk_partial`\nis true, an empty UK result means \"none from these retailers\",\nnever \"no fuel here\". Present only when the snapshot holds UK\nstations."
},
"uk_partial": {
"type": [
"boolean",
"null"
],
"description": "True when UK prices come only from the retailer feeds of the\nclosed CMA interim scheme, which cover some retailers and not\nothers, rather than from the statutory Fuel Finder. Present only\nwhen the snapshot holds UK stations."
},
"uk_retailers": {
"type": "array",
"items": {
"$ref": "#/$defs/FuelRetailer"
},
"description": "The UK retailers in the snapshot, largest first. Present only when\nthe snapshot holds UK stations."
}
},
"description": "What the deployment's fuel-price snapshot actually holds, as the\ngateway reports it."
},
"FuelRetailer": {
"type": "object",
"required": [
"name",
"stations"
],
"properties": {
"name": {
"type": "string",
"description": "Retailer or brand display name, as the gateway names it."
},
"stations": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "How many stations it contributes to the snapshot."
}
},
"description": "One UK retailer (or, with Fuel Finder loaded, forecourt brand) in the\ndeployment's fuel-price snapshot."
},
"FuelPriceQuote": {
"type": "object",
"required": [
"value",
"currency",
"updated_at",
"stale"
],
"properties": {
"stale": {
"type": "boolean",
"description": "True when the price could not be verified fresher than 24 hours:\nunless BOTH the source's own `updated_at` and the snapshot's fetch\ntime fall inside that window, and always when either is missing.\nTreat it as indicative, not bindable, say \"last seen at X on\n<date>\", never quote it as today's price or as a saving."
},
"value": {
"type": "number",
"format": "double",
"description": "Price per litre in `currency`."
},
"currency": {
"type": "string",
"description": "ISO 4217 code (GBP for the UK sources, EUR for FR/DE)."
},
"updated_at": {
"type": "string",
"description": "The source's own price timestamp, verbatim."
}
},
"description": "One live pump price: per-litre value in an ISO 4217 currency, with the\nsource's own update timestamp and a 24-hour staleness flag."
},
"FuelStationHit": {
"type": "object",
"required": [
"station_id",
"source",
"lat",
"lon",
"price",
"detour_minutes",
"detour_s",
"along_route_position",
"off_route_m"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "WGS84 latitude in decimal degrees."
},
"lon": {
"type": "number",
"format": "double",
"description": "WGS84 longitude."
},
"name": {
"type": [
"string",
"null"
],
"description": "Human label: trading name, town or address, where the feed\ncarries one."
},
"brand": {
"type": [
"string",
"null"
],
"description": "Brand where the feed carries one."
},
"price": {
"$ref": "#/$defs/FuelPriceQuote",
"description": "The requested fuel's live pump price at this station."
},
"source": {
"type": "string",
"description": "Which national feed the station came from (\"uk-fuelfinder\", \"uk\",\n\"fr\", \"de\")."
},
"detour_s": {
"type": "number",
"format": "double",
"description": "The same detour in raw seconds."
},
"detour_km": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Extra travel distance in kilometres, when the engine reported\ndistances."
},
"station_id": {
"type": "string",
"description": "Source-scoped stable station id."
},
"off_route_m": {
"type": "number",
"format": "double",
"description": "Straight-line distance from the station to the route, metres."
},
"saving_total": {
"type": [
"number",
"null"
],
"format": "double",
"description": "`saving_per_litre` × the request's `fill_litres`, when both exist."
},
"detour_minutes": {
"type": "number",
"format": "double",
"description": "Extra travel time of refuelling here, in minutes (rounded to 0.1):\n(origin→station) + (station→destination) − (origin→destination),\nall computed by the routing engine, never a straight-line guess."
},
"saving_per_litre": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Per-litre saving against the cheapest effectively-on-route station\nin the same currency (negative = dearer than staying on route).\nAbsent when no FRESH station sits on the route itself in this\ncurrency, and always absent on a stale result: an unverifiable\nprice may state a number but never claim a saving."
},
"along_route_position": {
"type": "number",
"format": "double",
"description": "Where along the route the station sits, 0.0 (origin) to 1.0\n(destination)."
}
},
"description": "One fuel station along the route, priced with its honest detour."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"fuel",
"costing",
"route_length_m",
"candidates_considered",
"candidates_costed",
"candidate_cap",
"max_detour_minutes",
"baseline",
"results",
"say"
],
"properties": {
"say": {
"type": "string",
"description": "**Always present.** The whole answer as one short spoken line,\ncomposed by the gateway: the number, the detour, and the honest\nqualifier where one applies. Safe to read to a driver verbatim,\nand safe on an empty result, where it names the cause rather than\nimplying there is no fuel on the road. A stale price's line states\nthe figure and the day it was last seen and claims no saving."
},
"fuel": {
"type": "string",
"description": "The normalised fuel code that was priced (e.g. \"diesel\")."
},
"note": {
"type": [
"string",
"null"
],
"description": "Why `results` is empty, when it is: the cause, not a bare list. On\na UK route where UK prices come only from some retailers' feeds it\nends with `coverage.statement`, so an empty answer is never read as\n\"no fuel here\". Absent when there are results."
},
"costing": {
"type": "string",
"description": "The costing the detours were priced with."
},
"results": {
"type": "array",
"items": {
"$ref": "#/$defs/FuelStationHit"
},
"description": "Stations within the detour budget, cheapest first (price, then\ndetour)."
},
"baseline": {
"type": "array",
"items": {
"$ref": "#/$defs/FuelBaseline"
},
"description": "The cheapest effectively-on-route option per currency (empty when\nno station sits on the route itself)."
},
"coverage": {
"anyOf": [
{
"$ref": "#/$defs/FuelCoverage"
},
{
"type": "null"
}
],
"description": "What the deployment's price snapshot covers. On a UK route, show\n`coverage.statement` to the user alongside the results: it names\nthe UK retailers covered, and an empty UK result means \"none from\nthese retailers\", never \"no fuel here\". Absent when the gateway is\ntoo old to report coverage."
},
"candidate_cap": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "The matrix fan-out cap in force."
},
"route_length_m": {
"type": "number",
"format": "double",
"description": "Length of the route geometry in metres."
},
"fuel_attribution": {
"type": [
"string",
"null"
],
"description": "Attribution string for the fuel-price data sources actually\nreturned, display it with the prices (a licence obligation)."
},
"route_distance_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Direct origin→destination distance in metres."
},
"route_duration_s": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Direct origin→destination travel time in seconds (same estimator\nas the detour legs), when routable."
},
"candidates_costed": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "Candidates actually priced through the engine (fan-out capped at\n`candidate_cap`, cheapest kept)."
},
"max_detour_minutes": {
"type": "number",
"format": "double",
"description": "The detour budget applied, minutes."
},
"candidates_considered": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "Stations selling the fuel that passed the corridor pre-filter."
}
}
}
}| number |
| Vehicle height in metres. Required: there is no default vehicle, because a default vehicle is how somebody gets an answer about a lorry that is not theirs. |
| margin_m | ["number","null"] | Operating margin in metres, added to the height before the verdict is decided (default 0). Your compliance policy, not ours: the measured figure and the safe bound are both reported whatever you set here, and the margin is echoed back. It is applied to the measurement, not to the routing step, where… |
| destination * | ref | Route destination. |
{
"name": "check_clearance_on_route",
"description": "Measure a vehicle's overhead clearance along a route against surveyed point cloud geometry, wherever survey coverage exists. Routes with truck costing (so the search already avoids the height restrictions the map has tagged), then measures that corridor. Give `origin`, `destination` and `height_m`; optional `width_m` asks the corridor-width axis too, and optional `margin_m` adds your operating margin to the vehicle before the verdict. Returns `pass`, `fail`, `indeterminate` or `no_verdict` with the limiting point, the measured headroom, its uncertainty bound (`safe_headroom_m`, `sigma_m`, `sampling_gap_m`) and a link to that exact view in the survey viewer. An `indeterminate` carries `indeterminate_reasons` as codes to branch on and the same reasons as English inside `explanation`; read out the English. A `pass` may carry no limiting point at all, which means the survey found nothing above that corridor, and the width axis may answer `not_assessed` where the corridor edges are too sparsely surveyed while the height axis still answers. Honesty, and it matters here: this measures physical geometry from a dated survey. It is not a signed or posted height, `clearance_enforcement.route_certified` is always false, and the caveat is on every answer including the clear one. Ground the survey did not cover comes back as `not_surveyed_m` and is never judged, so a `pass` is possible over complete coverage and nowhere else; sparse or stale coverage comes back separately as `insufficient_data_m`. Reach for this when a truck route came back unchanged and you need to know whether that means anything: an unchanged route avoids what the map records, which is a different claim from measured headroom, because a structure nobody tagged is routed through like open road. Needs the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY), which holds the surveys; there is no fallback, and it will not answer from the routing step alone. The mapmap://guide/clearance resource sets out what each answer proves.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"origin",
"destination",
"height_m"
],
"properties": {
"origin": {
"$ref": "#/$defs/LatLon",
"description": "Route origin."
},
"width_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle width in metres. Supplying it asks the width axis as well as\nthe height axis; the width answer is reported separately and is\nnever a headroom."
},
"height_m": {
"type": "number",
"format": "double",
"description": "Vehicle height in metres. Required: there is no default vehicle,\nbecause a default vehicle is how somebody gets an answer about a\nlorry that is not theirs."
},
"margin_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Operating margin in metres, added to the height before the verdict\nis decided (default 0). Your compliance policy, not ours: the\nmeasured figure and the safe bound are both reported whatever you\nset here, and the margin is echoed back. It is applied to the\nmeasurement, not to the routing step, where the map's own posted\nheights already carry a margin of their own."
},
"destination": {
"$ref": "#/$defs/LatLon",
"description": "Route destination."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"ClearanceEnforcement": {
"type": "object",
"required": [
"basis",
"route_certified",
"vertical_datum",
"caveat"
],
"properties": {
"basis": {
"type": "string",
"description": "How the figures were arrived at. Always\n`\"surveyed_pointcloud_within_survey_difference\"`: the difference\nbetween two heights measured in the same survey, on the same date,\nby the same processing. No map tag, no terrain model and no absolute\nvertical datum enters it."
},
"caveat": {
"type": "string",
"description": "What this answer does and does not prove, in one paragraph."
},
"vertical_datum": {
"type": "string",
"description": "The vertical frame the surveyed figures live in, spelled for a\nreader."
},
"route_certified": {
"type": "boolean",
"description": "Whether the route has been certified against a structure inventory.\nAlways `false`, and there is no future in which it is true: this is\na measurement with a bound, never a certificate about a route."
}
},
"description": "How a clearance answer was arrived at, and what it therefore does and\ndoes not prove.\n\nThe [`TunnelEnforcement`] pattern, applied to the other safety-adjacent\nanswer this server gives, and for the same reason: a headroom figure\nwith a bound on it reads like permission. It is not one. The block is\ncarried on every response including the clear one, because the clear one\nis the dangerous one.\n\nEvery field is taken verbatim from the gateway's report rather than\nrebuilt here. `vertical_datum` is a property of the survey the figures\ncame from, so this server cannot know it; and copying the caveat text\ninto a second crate is exactly the drift the single-source-of-truth rule\nexists to prevent. When the gateway omits any part of it, the tool\nrefuses the answer rather than emitting a report with a hollow caveat."
},
"LimitingPointSummary": {
"type": "object",
"required": [
"lat",
"lon",
"route_distance_m",
"headroom_m",
"sigma_m",
"sampling_gap_m",
"safe_headroom_m",
"overhead_class",
"surveyed_on",
"dataset"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude of the point, decimal degrees."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude of the point, decimal degrees."
},
"dataset": {
"type": "string",
"description": "The dataset the measurement came from."
},
"sigma_m": {
"type": "number",
"format": "double",
"description": "One-sigma measurement uncertainty on that figure, metres."
},
"headroom_m": {
"type": "number",
"format": "double",
"description": "Measured headroom: the surveyed gap between the road surface and\nthe lowest validated surface above it, metres."
},
"surveyed_on": {
"type": "string",
"description": "Last capture date of the survey behind this measurement, ISO."
},
"overhead_class": {
"type": "string",
"description": "What the overhead surface is made of: `structure`, `vegetation`,\n`wire` or `unknown`. Foliage is compressible and seasonal, so an old\nreading of it stops deciding."
},
"sampling_gap_m": {
"type": "number",
"format": "double",
"description": "One-sided sampling bias bound, metres: how far below the lowest\nsample the true low point could hang, given the sample spacing."
},
"safe_headroom_m": {
"type": "number",
"format": "double",
"description": "`headroom_m` less the uncertainty terms, metres. This is the number\nthe verdict is decided on, and the number to plan against."
},
"route_distance_m": {
"type": "number",
"format": "double",
"description": "How far along the route the point sits, metres."
}
},
"description": "One measured clearance on the route, with the bounds that qualify it.\n\nThere is no field here for a posted, signed or otherwise legally\nbinding height, and that absence is deliberate. A survey measures the\nphysical gap; a sign records a restriction a road authority posted, set\nbelow the physical gap on purpose. They are different quantities and\nthis server never reports one as the other."
},
"ClearanceWidthSummary": {
"type": "object",
"required": [
"verdict"
],
"properties": {
"reason": {
"type": [
"string",
"null"
],
"description": "Why the width axis declined to answer, present for\n`not_assessed`."
},
"verdict": {
"type": "string",
"description": "`pass`, `fail`, `indeterminate`, `no_verdict`, or `not_assessed`\nwhere the geometry or the request did not support an answer."
},
"clear_width_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Free width of the narrowest clear corridor found, metres. Present\nwhere a corridor edge was actually measured."
},
"safe_clear_width_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "That width less its uncertainty terms, metres: the number the width\nverdict is decided on."
}
},
"description": "The width axis: how wide the clear corridor is, never how tall.\n\nA separate type from [`LimitingPointSummary`] on purpose, with no\nheadroom field on it. These are different physical quantities, and a\nshared type is how the reader of a width answer ends up quoting a\nheadroom."
},
"ClearanceDatasetSummary": {
"type": "object",
"required": [
"dataset",
"survey_dates",
"stale"
],
"properties": {
"stale": {
"type": "boolean",
"description": "Whether the clearance field lags the survey it was baked from, or\nhas never been checked against it. Either way no route passes on it."
},
"dataset": {
"type": "string",
"description": "The dataset id."
},
"survey_dates": {
"type": "string",
"description": "Capture range, `from/to` in ISO dates."
}
},
"description": "One survey the report drew on."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"verdict",
"basis",
"clearance_enforcement",
"route_distance_m",
"route_duration_s",
"geometry_polyline6",
"assessed_m",
"not_surveyed_m",
"insufficient_data_m",
"width",
"datasets",
"advisories",
"indeterminate_reasons",
"explanation"
],
"properties": {
"basis": {
"type": "string",
"description": "Always `\"surveyed_geometry_not_signage\"`."
},
"width": {
"$ref": "#/$defs/ClearanceWidthSummary",
"description": "The width axis, answered separately when `width_m` was given."
},
"verdict": {
"type": "string",
"description": "`pass`, `fail`, `indeterminate` or `no_verdict` for the height axis.\nA `pass` is possible over completely surveyed ground and nowhere\nelse: unsurveyed ground yields `no_verdict`, never a pass."
},
"datasets": {
"type": "array",
"items": {
"$ref": "#/$defs/ClearanceDatasetSummary"
},
"description": "The surveys drawn on, with their capture dates and staleness."
},
"limiting": {
"anyOf": [
{
"$ref": "#/$defs/LimitingPointSummary"
},
{
"type": "null"
}
],
"description": "The limiting point on a `fail`, the tightest point on a `pass`, the\nworst contested point on an `indeterminate`. Absent on a\n`no_verdict`, and absent on a `pass` where the survey found nothing\nat all above the corridor."
},
"view_url": {
"type": [
"string",
"null"
],
"description": "Deep link to that exact view in the survey viewer, so the reading\ncan be looked at rather than taken on trust."
},
"advisories": {
"type": "array",
"items": {
"type": "string"
},
"description": "Notes on stretches of the route: vegetation age, a reading limited\nby a wire, a seam between surveys."
},
"assessed_m": {
"type": "number",
"format": "double",
"description": "Metres of route measured against survey data good enough to decide\non."
},
"explanation": {
"type": "string",
"description": "What was measured, when, with what bound, and what the tool declined\nto conclude. It may over-restrict; it never under-restricts."
},
"not_surveyed_m": {
"type": "number",
"format": "double",
"description": "Metres of route no survey covers. This is the absence of a\nmeasurement, and it is never the same statement as a measured open\nsky. No verdict is drawn over it."
},
"resolution_hint": {
"type": [
"string",
"null"
],
"description": "What would resolve an `indeterminate`, in one sentence, as the\nmeasuring service phrased it."
},
"route_distance_m": {
"type": "number",
"format": "double",
"description": "Length of the route the vehicle was routed over, metres."
},
"route_duration_s": {
"type": "number",
"format": "double",
"description": "Estimated driving time for that route, seconds."
},
"geometry_polyline6": {
"type": "string",
"description": "The route as a six-digit-precision encoded polyline, so the same\nshape can be drawn or re-measured without routing again."
},
"insufficient_data_m": {
"type": "number",
"format": "double",
"description": "Metres of route a survey covers but too sparsely, or too stale, to\ndecide on. Also an absence, and reported apart from\n`not_surveyed_m` because the two have different remedies."
},
"clearance_enforcement": {
"$ref": "#/$defs/ClearanceEnforcement",
"description": "What this answer does and does not prove. Read it."
},
"indeterminate_reasons": {
"type": "array",
"items": {
"type": "string"
},
"description": "Why an `indeterminate` could not be called, as machine-readable\ncodes (`inside_uncertainty_band`, `vegetation_age_exceeded`,\n`artefact_stale`, `artefact_freshness_unchecked`). Empty on every\nother verdict. These are for branching on, not for reading out: the\nsame reasons appear as English in `explanation`, and a person shown\n`artefact_freshness_unchecked` has been failed by whatever displayed\nit."
}
}
}
}| ["array","null"] |
| Optional territories. Given, no cluster straddles one: each territory is clustered on its own, and so are the stops inside none of them. |
| max_cluster_load | ["number","null"] | At most this much summed `load` per cluster; the cluster count is derived from it. A load ceiling with lumpy loads is a bin-packing problem and may have no solution at the derived count, the response says so rather than pretending. |
| max_cluster_locations | ["integer","null"] | At most this many stops per cluster; the cluster count is derived from it. |
{
"name": "cluster",
"description": "Group stops into balanced geographic clusters, so a day too large for one optimisation can be optimised one cluster at a time. This is the front half of the recipe for a thousand-stop day: cluster here, then call `optimise_routes` per cluster, where the routing engine's own matrix decides the visiting order. IMPORTANT, this is STRAIGHT-LINE clustering. Distances are measured between coordinates, not along the road network: no road, river, motorway junction or one-way system is consulted, and two stops either side of an estuary look adjacent. That makes it the right tool for deciding which stops belong TOGETHER and the wrong one for deciding what ORDER to visit them in. The answer carries a `basis` sentence saying exactly this; show it, so a centroid is never read as a plan. Provide `locations` ([{id, lat, lon, load?}], ids unique, at most 5,000) and EXACTLY ONE of `clusters` (how many groups, balanced by stop count), `max_cluster_locations` or `max_cluster_load` (a per-cluster ceiling the count is derived from). Optional `territories` keep a cluster from straddling a round: each is clustered on its own, and so are the stops inside none of them. Optional `seed` (default 42) drives the seeding, the same request with the same seed always returns the same clusters, on every deployment, so a re-run is a re-run. Returns each cluster's member ids, count, summed load, centroid and territory, plus a `balance` block naming the constraint applied and whether it had to be relaxed to place every stop: a load ceiling with lumpy loads is a bin-packing problem and may have no solution at the derived count. Requires the MapMap gateway.",
"inputSchema": {
"type": "object",
"$defs": {
"TerritorySpec": {
"type": "object",
"required": [
"id",
"polygon"
],
"properties": {
"id": {
"type": "string",
"description": "Caller-chosen id, echoed back and referenced by\n`vehicles[].territory_ids`. Must be unique within the request."
},
"polygon": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2
},
"description": "The outer ring as GeoJSON `[lon, lat]` positions, longitude\nFIRST. Closed or open; an unclosed ring is closed for you."
}
},
"description": "One named territory: a polygon that bounds which vehicle may serve\nwhich stop.",
"additionalProperties": false
},
"ClusterLocationSpec": {
"type": "object",
"required": [
"id",
"lat",
"lon"
],
"properties": {
"id": {
"type": "string",
"description": "Caller-chosen id, echoed back as the cluster's membership. Must be\nunique within the request."
},
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees."
},
"load": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Optional weight, parcels, kilograms, litres, minutes of service.\nSummed per cluster and reported; constrains the clustering only\nunder `max_cluster_load`."
}
},
"description": "One stop to be clustered."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"locations"
],
"properties": {
"seed": {
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0,
"description": "Seed for the k-means++ seeding (default 42). The same request with\nthe same seed always returns the same clusters, on every\ndeployment."
},
"clusters": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "How many clusters to produce, balanced by stop count. Give exactly\none of `clusters`, `max_cluster_locations` or `max_cluster_load`."
},
"locations": {
"type": "array",
"items": {
"$ref": "#/$defs/ClusterLocationSpec"
},
"description": "The stops to group. Ids must be unique; at most 5,000."
},
"territories": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/TerritorySpec"
},
"description": "Optional territories. Given, no cluster straddles one: each\nterritory is clustered on its own, and so are the stops inside none\nof them."
},
"max_cluster_load": {
"type": [
"number",
"null"
],
"format": "double",
"description": "At most this much summed `load` per cluster; the cluster count is\nderived from it. A load ceiling with lumpy loads is a bin-packing\nproblem and may have no solution at the derived count, the\nresponse says so rather than pretending."
},
"max_cluster_locations": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "At most this many stops per cluster; the cluster count is derived\nfrom it."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"clusters",
"parameters",
"balance",
"basis"
],
"properties": {
"basis": {
"type": "string",
"description": "The method statement: this is STRAIGHT-LINE clustering. Distances\nare between coordinates, not along roads, two stops either side of\nan estuary look adjacent. Show it. It is the sentence that stops a\ncentroid being read as a plan."
},
"balance": {
"description": "The constraint applied, the largest cluster produced, and whether\nthe ceiling had to be relaxed to place every stop."
},
"clusters": {
"description": "The clusters: each with its `id`, member `locations` (your ids),\n`count`, summed `load`, `centroid` and the `territory` it belongs\nto."
},
"parameters": {
"description": "The seed, the cluster count, the locations seen, how many\nterritories were used, the iterations run and whether it converged."
}
}
}
}| The outing's `id` in the job's `result.chunks` (from 1). Required unless `drive` is `transfer_to_start`. |
{
"name": "coverage_guidance",
"description": "Turn-by-turn guidance for one drive of a finished coverage plan (`submit_optimise_job` with `kind: \"coverage\"`, read with `get_job`), in one call. Give `job_id` (the coverage job, the caller's own and `succeeded`), `chunk_id` (the outing's `id` in `result.chunks`, from 1) and `drive`: \"outing\" (default, the outing itself), \"transfer\" (the drive into that outing from the previous one's end, or from where the car is; `chunk_loops` plans) or \"transfer_to_start\" (the plan's drive back to its start; no `chunk_id`). The gateway walks every piece of that drive's `trace_route_parts` on the engine's exact edge walk and answers one trip: `legs` has one entry per piece in driving order, each with its maneuvers, plus the whole drive's `distance_m`, `duration_s` and `geometry_polyline6`. Durations include the time the engine charges at each junction where one piece ends and the next begins (on the leg after it), so `duration_s` is the plan's `drive_time_s` for the drive (times the plan's own `time_factor`, which guidance by job id takes from the plan). Pieces join mid-street wherever the plan allowed: a leg's closing arrival and the next leg's opening departure at the same point mean carry straight on, not stop. Exact or nothing: it never falls back to map matching (which drops streets driven in and straight back out), so a piece the engine refuses is an error naming that piece and the engine's own words. Metered by the gateway as one call at the size of a /trace_route of the drive (one call per started block of shape points, never fewer than the pieces). A refused piece keeps those quota units (the engine did the work) but takes no prepaid credit or x402 payment; a request refused before walking (unknown or unfinished job, no such outing) is not billed. Premium for a truck plan. Requires the MapMap gateway.",
"inputSchema": {
"type": "object",
"$defs": {
"CoverageGuidanceDrive": {
"oneOf": [
{
"type": "string",
"const": "outing",
"description": "The outing itself (`chunks[].trace_route_parts`). The default."
},
{
"type": "string",
"const": "transfer",
"description": "The drive into the outing from the previous outing's end, or for\nthe first outing from where the car is (`start.snap: exact`):\n`chunks[].transfer_from_previous`, `chunk_loops` plans."
},
{
"type": "string",
"const": "transfer_to_start",
"description": "The plan's drive from the last outing back to `start`\n(`transfer_to_start`, `chunk_loops` with `return_to_start`). Takes\nno `chunk_id`."
}
],
"description": "Which drive of a coverage plan `coverage_guidance` guides."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"job_id"
],
"properties": {
"drive": {
"$ref": "#/$defs/CoverageGuidanceDrive",
"default": "outing",
"description": "`outing` (the default), `transfer` (the drive into that outing) or\n`transfer_to_start` (the plan's drive back to its start)."
},
"job_id": {
"type": "string",
"description": "The coverage job's id, as `submit_optimise_job` (`kind: \"coverage\"`)\nreturned it. The job must be this key's own (or another key of the\nsame account) and `succeeded`."
},
"chunk_id": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "The outing's `id` in the job's `result.chunks` (from 1). Required\nunless `drive` is `transfer_to_start`."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$defs": {
"ManeuverOut": {
"type": "object",
"required": [
"instruction",
"distance_m",
"duration_s"
],
"properties": {
"ref": {
"type": [
"string",
"null"
],
"description": "Route numbers of that road (`\"; \"` separated, e.g. `\"A27\"` or\n`\"I 5; US 101\"`); absent when it carries none, never read from a\nstreet name."
},
"country": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2 country of the road the manoeuvre starts on, e.g.\n`\"GB\"`. This and the road fields below come from the MapMap gateway's\nroad walk: present when the route was computed through the gateway\n(GATEWAY_URL + GATEWAY_API_KEY) and the map knows the road, absent\notherwise. Never inferred."
},
"distance_m": {
"type": "number",
"format": "double",
"description": "Length of the maneuver in metres."
},
"duration_s": {
"type": "number",
"format": "double",
"description": "Estimated duration of the maneuver in seconds."
},
"road_class": {
"type": [
"string",
"null"
],
"description": "Engine road class of that road (`motorway`, `trunk`, `primary`,\n`secondary`, `tertiary`, `unclassified`, `residential`,\n`service_other`)."
},
"instruction": {
"type": "string",
"description": "Written instruction, e.g. \"Turn right onto Main Street\"."
},
"subdivision": {
"type": [
"string",
"null"
],
"description": "ISO 3166-2 subdivision of that road where the map carries one, e.g.\n`\"GB-ENG\"` or `\"US-CA\"`."
},
"driving_side": {
"type": [
"string",
"null"
],
"description": "The side of the road traffic keeps to there, `\"left\"` or `\"right\"`;\npresent only when the road's country is known."
},
"speed_limit_sign": {
"type": [
"string",
"null"
],
"description": "The speed-limit sign family there: `\"vienna\"` (roundel) or\n`\"mutcd\"` (US and Canadian rectangle)."
},
"speed_limit_unit": {
"type": [
"string",
"null"
],
"description": "The unit speed limits are posted in on that road, `\"mph\"` or\n`\"km/h\"`, from its country (never from the request's units)."
},
"speed_limit_posted": {
"description": "The posted limit as the sign shows it, in the road's own unit:\n`{\"type\":\"known\",\"value\":30,\"unit\":\"mph\"}` (plus `\"national\":true`\nfor a national limit), `{\"type\":\"unlimited\"}` or `{\"type\":\"unknown\"}`.\nRead from the road the manoeuvre mostly travels along."
},
"landmark_instruction": {
"type": [
"string",
"null"
],
"description": "The same manoeuvre anchored to a recognisable place, e.g. \"Turn\nright just after the Shell garage\", present only when the request\nset `landmarks: true` and a place near the junction cleared the\nsalience bar. Prefer reading this aloud when it is there: it is how\na passenger would give the direction. `instruction` is always the\nengine's own and is never replaced."
}
},
"description": "One turn-by-turn instruction of a computed route."
},
"CoverageGuidanceLeg": {
"type": "object",
"required": [
"piece",
"distance_m",
"duration_s",
"maneuvers"
],
"properties": {
"piece": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "The piece's number, from 1, in driving order."
},
"maneuvers": {
"type": "array",
"items": {
"$ref": "#/$defs/ManeuverOut"
},
"description": "Its turn-by-turn maneuvers. A piece that ends mid-street closes\nwith an arrival and the next opens with a departure at the same\npoint: there the driver simply carries straight on."
},
"distance_m": {
"type": "number",
"format": "double",
"description": "The piece's length, metres."
},
"duration_s": {
"type": "number",
"format": "double",
"description": "The piece's estimated driving time, seconds: the engine's time for\nthe piece, plus the junction time at the join it starts from (none\nfor the first piece, or a join mid-street)."
}
},
"description": "One piece of a guided drive: the engine's own answer for it."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"drive",
"job_id",
"pieces",
"distance_m",
"duration_s",
"summary",
"legs",
"geometry_polyline6"
],
"properties": {
"legs": {
"type": "array",
"items": {
"$ref": "#/$defs/CoverageGuidanceLeg"
},
"description": "One leg per piece, in driving order, each with its maneuvers."
},
"drive": {
"type": "string",
"description": "The drive guided: `outing`, `transfer` or `transfer_to_start`."
},
"job_id": {
"type": "string",
"description": "The job it came from."
},
"pieces": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "Pieces walked, one leg each."
},
"summary": {
"type": "string",
"description": "One-line summary of the drive."
},
"chunk_id": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "The outing's `id`, when one was named."
},
"distance_m": {
"type": "number",
"format": "double",
"description": "The whole drive's length, metres."
},
"duration_s": {
"type": "number",
"format": "double",
"description": "The whole drive's estimated driving time, seconds: every piece's,\nand the junction time at each join between them, which is the\nplan's `drive_time_s` for the drive (times the plan's own\n`time_factor`, which guidance by job id takes from the plan)."
},
"geometry_polyline6": {
"type": "string",
"description": "The whole drive's geometry as the engine walked it, polyline6,\nlegs joined at their shared points."
}
}
}
}| Optional location bias: results near this point rank higher. |
| limit | ["integer","null"] | Maximum number of results (default 10): 1–10 on the hosted MapMap server, 1–50 on a self-hosted server that calls Photon directly. |
| query | ["string","null"] | Free-text place query, e.g. "Dover ferry terminal". Required unless at least one structured component is supplied. |
| street | ["string","null"] | Structured component: street name, e.g. "Downing Street". Matches the street of addresses and POIs (transliterated street names included) as well as the street itself. |
| country | ["string","null"] | Structured component: ISO 3166-1 alpha-2 code or country name, "GB", "gb", "United Kingdom" and "UK" all mean the same country. A value naming no country is refused rather than quietly applied as a filter that matches nothing. |
| postcode | ["string","null"] | Structured component: postcode in any spacing or case, "SW1A 2AA" and "sw1a2aa" are one query. A bare UK outward code ("SW1A") selects the whole district. |
| housenumber | ["string","null"] | Structured component: house number, e.g. "10" or "221B". Only meaningful alongside `street`, a house number on its own excludes nearly everything and identifies nothing. |
{
"name": "geocode",
"description": "Turn a place (address, POI, town) into coordinates. Ask two ways, and they combine: `query` is free text, one run-together string, the way a person types into a search box, and `street`, `housenumber`, `city`, `postcode` and `country` name the parts of an address separately. At least one of the two is required. Pass the parts whenever you already hold the address in parts (a form, a CRM row, a manifest): components are REQUIREMENTS, not hints, so `city: \"London\"` means a result outside London cannot come back at all, where \"London\" inside `query` only reorders. `country` takes an ISO 3166-1 alpha-2 code or a country name (\"GB\", \"United Kingdom\"); a value naming no country is refused rather than silently matching nothing. Returns up to `limit` (default 10) candidates with name, one-line label, lat/lon, type and address parts. Pass `focus` {lat, lon} to rank results near a location higher. A bare city or town name (no comma) lists that city's airports and main railway stations directly behind it, ahead of namesakes elsewhere. Each hit also carries `match`: a per-component matched/inferred/unmatched verdict, the `score_gap` to the runner-up, and which backend answered. READ IT before acting on an address, an unmatched or inferred postcode on the top hit means the answer does not carry the address you asked for, and a small `score_gap` means the ranking barely chose, so show the alternatives instead of picking one. Use `verify_places` when the address came from a model or a user and needs checking rather than using. Results are matched in `lang` (default \"en\"), so English exonyms (\"Munich\", \"Cologne\", \"Geneva\") resolve to the place meant; pass `lang` when querying in another language, or \"default\" for each place's local name.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"city": {
"type": [
"string",
"null"
],
"description": "Structured component: town or city, e.g. \"London\". Matches the\ncontaining city as well as the immediate locality, so a suburb name\nworks here too."
},
"lang": {
"type": [
"string",
"null"
],
"description": "Language of the place names to match and return, as a two-letter\ncode. Defaults to \"en\", which is what makes English exonyms\n(\"Munich\", \"Cologne\", \"Geneva\") resolve to the place meant rather\nthan a same-named town elsewhere. Set it to the language your\nquery is written in; \"default\" asks for each place's own local\nname. Deployments support a fixed set (this one: \"en\", \"de\",\n\"fr\"), and anything outside it is refused."
},
"focus": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "Optional location bias: results near this point rank higher."
},
"limit": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Maximum number of results (default 10): 1–10 on the hosted MapMap\nserver, 1–50 on a self-hosted server that calls Photon directly."
},
"query": {
"type": [
"string",
"null"
],
"description": "Free-text place query, e.g. \"Dover ferry terminal\". Required unless\nat least one structured component is supplied."
},
"street": {
"type": [
"string",
"null"
],
"description": "Structured component: street name, e.g. \"Downing Street\". Matches\nthe street of addresses and POIs (transliterated street names\nincluded) as well as the street itself."
},
"country": {
"type": [
"string",
"null"
],
"description": "Structured component: ISO 3166-1 alpha-2 code or country name,\n\"GB\", \"gb\", \"United Kingdom\" and \"UK\" all mean the same country.\nA value naming no country is refused rather than quietly applied as\na filter that matches nothing."
},
"postcode": {
"type": [
"string",
"null"
],
"description": "Structured component: postcode in any spacing or case, \"SW1A 2AA\"\nand \"sw1a2aa\" are one query. A bare UK outward code (\"SW1A\")\nselects the whole district."
},
"housenumber": {
"type": [
"string",
"null"
],
"description": "Structured component: house number, e.g. \"10\" or \"221B\". Only\nmeaningful alongside `street`, a house number on its own excludes\nnearly everything and identifies nothing."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"GeocodeHit": {
"type": "object",
"required": [
"label",
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees."
},
"city": {
"type": [
"string",
"null"
],
"description": "City or town, when known."
},
"name": {
"type": [
"string",
"null"
],
"description": "Place name, when the source feature has one."
},
"type": {
"type": [
"string",
"null"
],
"description": "Feature type, e.g. \"house\", \"street\", \"city\" (falls back to the\nOSM value when the endpoint does not classify)."
},
"label": {
"type": "string",
"description": "Human-readable one-line label assembled from the address parts."
},
"match": {
"anyOf": [
{
"$ref": "#/$defs/GeocodeMatch"
},
{
"type": "null"
}
],
"description": "How far this hit can be trusted to be the place that was asked\nfor, see [`GeocodeMatch`]. Present whenever the MapMap gateway\nanswered; absent on a deployment falling back to the direct Photon\ngeocoder, and absent on the gateway's own fast paths (a pasted\ncoordinate pair, a bare UK outward code, a category browse), which\nanswer without a ranking to report on."
},
"country": {
"type": [
"string",
"null"
],
"description": "Country, when known."
},
"postcode": {
"type": [
"string",
"null"
],
"description": "Postcode, when known."
}
},
"description": "One geocoding result."
},
"GeocodeMatch": {
"type": "object",
"required": [
"components",
"score_gap",
"source"
],
"properties": {
"source": {
"type": "string",
"description": "Which backend answered: \"mapmap-index\" (the first-party index) or\n\"photon\"."
},
"score_gap": {
"type": "number",
"format": "double",
"description": "The top result's score minus the runner-up's, rounded to 3 decimal\nplaces. `0` for a single result, and `0` from the `photon` source,\nwhich publishes no per-result score, so a `0` is \"no signal\", not\n\"a tie\"."
},
"components": {
"$ref": "#/$defs/GeocodeMatchComponents",
"description": "Per-component verdict on this hit: one entry for each structured\ncomponent supplied, and empty when the query was free text only."
}
},
"description": "How well one geocoding result answers what was actually asked.\n\nGeocoding's real failure mode is not \"no answer\" but a confident answer\nto a different question: a plausible row on the wrong street, with\nnothing in the response to say so. This object is that missing say-so,\nand an agent should read it before acting on an address.\n\nHow to read it:\n\n* Any component `unmatched` or `inferred` on the TOP hit means the\n answer does not carry the address that was asked for, an `unmatched`\n postcode means the result has no postcode at all, `inferred` means it\n has a different one. Neither is a match. Say so rather than presenting\n the hit as the address, and reach for `verify_places` when the address\n came from a model or a user and needs checking rather than using.\n* A small `score_gap` means the ranking barely chose between this hit\n and the runner-up, which is exactly when to show the alternatives\n instead of picking one for the user."
},
"GeocodeMatchComponents": {
"type": "object",
"properties": {
"city": {
"type": [
"string",
"null"
],
"description": "Verdict on the supplied `city`."
},
"street": {
"type": [
"string",
"null"
],
"description": "Verdict on the supplied `street`."
},
"country": {
"type": [
"string",
"null"
],
"description": "Verdict on the supplied `country`."
},
"postcode": {
"type": [
"string",
"null"
],
"description": "Verdict on the supplied `postcode`."
},
"housenumber": {
"type": [
"string",
"null"
],
"description": "Verdict on the supplied `housenumber`."
}
},
"description": "Per-component verdicts inside a [`GeocodeMatch`]. Each is one of\n\"matched\", \"inferred\" or \"unmatched\"; a component that was not supplied\nis absent entirely.\n\n* \"matched\", the result's own field carries the value asked for (case-\n and accent-insensitive, and by containment, so `city: \"London\"`\n matches \"City of London\").\n* \"inferred\", the result carries a value for that component, but not\n the one asked for. It reached the page through ranking, as when a\n street is found by its transliterated name and displayed under its\n canonical one.\n* \"unmatched\", the result carries no value for that component at all."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/$defs/GeocodeHit"
},
"description": "Matching places, best first."
}
}
}
}| min_gap_s | ["number","null"] | Least time between two lines, seconds (default 900, which is four an hour). Applied only with `duration_s`. |
| duration_s | ["number","null"] | That route's own duration, seconds: `duration_s` from the same answer. **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. |
| max_offset_m | ["number","null"] | How near a plaque must come to the route before its line may be spoken, metres (default 60, hard ceiling 80). |
| voice_format | ["string","null"] | Container to address each line's audio clip in: `opus` or `m4a`. Given, every line gains a `clip` with its synthesis cache key and URL. It NEVER synthesises: the key is a pure function of the sentence, so asking here buys nothing. |
| geometry_polyline6 * | string | The route shape, precision-6 encoded: `geometry_polyline6` straight out of the `route` tool's answer. |
{
"name": "heritage_narration",
"description": "Three to five short spoken lines an hour about the ground a route is on: one sentence, at the point the driver reaches the thing it is about, and then silence. Not a tour and not a chatbot. NOTHING IS GENERATED HERE: every line is a sentence a person wrote from a public-domain plaque inscription and a person reviewed, compiled into the gateway binary, so no model runs in this path and the lines are identical for every driver. Give `geometry_polyline6` from the `route` tool and, IMPORTANT, `duration_s` from the same answer: without it the silence budget falls back to a distance, and \"four lines an hour\" is a claim about time that a distance answers wrongly at both ends. Optional `min_gap_s`, `min_gap_m`, `max_offset_m` (default 60, hard ceiling 80), `max_lines` and `voice_format` (\"opus\" or \"m4a\", which adds each line's audio cache key and URL and NEVER synthesises). COVERAGE IS ONE CORRIDOR, deliberately: the Chelsea riverside, 18 reviewed lines over 5 km. EVERY OTHER ROUTE ANSWERS WITH NO LINES, and that is a correct answer rather than a failure. ALWAYS READ THE CENSUS, which is the record of WHAT WAS NOT SAID: no lines with every entry in `beyond_reach` means this feature does not cover the journey; no lines with entries in `silenced_by_budget` means the corridor is covered and the budget is holding them back. They are different answers and must never be relayed the same way. On the reference route the census reports 1 spoken and 17 silenced, which is the design working, not a thin corpus. Every line publishes `offset_m`, the measured distance from the plaque to the route, because it is the entire warrant for the word \"here\", and `plaque_ids` so any claim can be taken back to its source. TWO OMISSIONS ARE DELIBERATE: no line says anything is visible, still standing or unchanged (a plaque records that somebody was somewhere, and nothing more), and NO LINE SAYS WHICH SIDE OF THE ROAD anything is on, because nothing in the source records it and a look that finds nothing spends the driver's trust in everything else. Do not add either. COSTS 1 UNIT a call: it reads no tiles and opens no archive. Requires the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY).",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"geometry_polyline6"
],
"properties": {
"max_lines": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Ceiling on how many lines come back, 1 to 50 (default 12)."
},
"min_gap_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Least distance between two lines, metres (default 400). A floor\nunder the time budget in every case."
},
"min_gap_s": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Least time between two lines, seconds (default 900, which is four\nan hour). Applied only with `duration_s`."
},
"duration_s": {
"type": [
"number",
"null"
],
"format": "double",
"description": "That route's own duration, seconds: `duration_s` from the same\nanswer. **Supply it.** Without it the silence budget falls back to\na distance, and \"three to five lines an hour\" is a claim about\ntime that a distance answers wrongly at both ends."
},
"max_offset_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "How near a plaque must come to the route before its line may be\nspoken, metres (default 60, hard ceiling 80)."
},
"voice_format": {
"type": [
"string",
"null"
],
"description": "Container to address each line's audio clip in: `opus` or `m4a`.\nGiven, every line gains a `clip` with its synthesis cache key and\nURL. It NEVER synthesises: the key is a pure function of the\nsentence, so asking here buys nothing."
},
"geometry_polyline6": {
"type": "string",
"description": "The route shape, precision-6 encoded: `geometry_polyline6`\nstraight out of the `route` tool's answer."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"HeritageLine": {
"type": "object",
"required": [
"at_m",
"offset_m",
"say",
"subject",
"basis",
"id"
],
"properties": {
"id": {
"type": "string",
"description": "The corpus entry's own id, stable across responses, so a client\ncan remember which lines it has already played."
},
"say": {
"type": "string",
"description": "The sentence to say, verbatim. Written by a person from a\npublic-domain plaque inscription and reviewed by a person."
},
"at_m": {
"type": "number",
"format": "double",
"description": "Distance along the route where this belongs, metres."
},
"clip": {
"description": "The line's audio address (only when `voice_format` was given):\n`hash`, `url` and `format`. Nothing was synthesised to produce it."
},
"basis": {
"type": "string",
"description": "What the line rests on, in words."
},
"subject": {
"type": "string",
"description": "The subject's name as the source dataset records it."
},
"offset_m": {
"type": "number",
"format": "double",
"description": "Measured perpendicular distance from the plaque's own recorded\ncoordinate to the route, metres. Published on every line because\nit is the entire warrant for the word \"here\", and because the\ncoordinate behind it was recorded by a volunteer and has never\nbeen surveyed."
},
"plaque_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "uint32",
"minimum": 0
},
"description": "The source plaque records, by their OpenPlaques id, so any claim\ncan be taken back to its source."
}
},
"description": "One reviewed line about the ground the route is on."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"route_length_m",
"corridor",
"lines",
"census",
"attribution",
"caveat"
],
"properties": {
"lines": {
"type": "array",
"items": {
"$ref": "#/$defs/HeritageLine"
},
"description": "The lines, in route order. Empty is the ordinary answer nearly\neverywhere: read `census` before saying anything about it."
},
"caveat": {
"type": "string",
"description": "The standing limits, for relaying to users."
},
"census": {
"description": "The census of what was NOT said: `corpus_entries`, `within_reach`,\n`beyond_reach`, `spoken`, `silenced_by_budget`, the gap that was\napplied and what it was derived from. An empty `lines` with every\nentry in `beyond_reach` means this feature does not cover the\njourney; an empty `lines` with entries in `silenced_by_budget`\nmeans the budget is working. They are different answers and must\nnot be reported the same way."
},
"corridor": {
"description": "The corridor that was consulted: its id, name, the road it runs\non and the date its lines were reviewed."
},
"attribution": {
"type": "string",
"description": "The licence notice for this answer."
},
"route_length_m": {
"type": "number",
"format": "double",
"description": "The route's own length, metres."
}
}
}
}{
"name": "match_trace",
"description": "Snap a recorded GPS trace to the road network and say what it actually travelled over. Provide `shape` (2 to 2000 recorded points, oldest first) or `encoded_polyline` (the same trace as a polyline6 string) (not both) plus the `costing` it was travelled under: \"auto\" (default), \"truck\", \"bicycle\", \"pedestrian\" or \"motor_scooter\". Costing decides which roads the trace may match onto, so a walk matched as \"auto\" snaps to the carriageway rather than the footpath. Returns the matched path as `geometry_polyline6` (the snapped roads, not your raw points) with its `distance_m` and `duration_s`, then the roll-ups: `by_road_class` and `by_admin` (distance and time, longest first), `by_surface` (distance), and `toll`, `bridge` and `tunnel` totals. This is how you turn a dashcam or telematics log into a report, which country and region the driving happened in, how much of it was motorway, how much was tolled, how much was unpaved. Honesty: the roll-ups are summed per matched road segment, so they need not add up to `distance_m` exactly, and segments the map records no surface or admin area for are left out of that breakdown rather than filed under a guess, an entry in `by_admin` with null codes is exactly that, counted and not attributed. Needs the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY); there is no direct-backend fallback.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"CostingKind": {
"oneOf": [
{
"type": "string",
"const": "auto",
"description": "Standard car costing."
},
{
"type": "string",
"const": "truck",
"description": "Truck costing; honours dimensional limits and, when a `truck`\nprofile is supplied, ADR dangerous-goods restrictions."
},
{
"type": "string",
"const": "bicycle",
"description": "Bicycle costing; tune it with a `bicycle` options object."
},
{
"type": "string",
"const": "pedestrian",
"description": "Pedestrian (walking) costing; tune it with a `pedestrian` options\nobject (lit streets, wheelchair/blind, hiking difficulty)."
},
{
"type": "string",
"const": "motor_scooter",
"description": "Motor scooter (moped) costing: like auto but prefers lower-speed\nroads and may use ways closed to larger motor vehicles."
}
],
"description": "Costing models exposed by the MCP tools (a deliberate subset of the\nValhalla costing list), serialised in snake_case exactly as Valhalla\nnames them."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"shape": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/LatLon"
},
"description": "The trace as an ordered list of recorded points, oldest first.\nBetween 2 and 2000 points. Provide this or `encoded_polyline`."
},
"costing": {
"anyOf": [
{
"$ref": "#/$defs/CostingKind"
},
{
"type": "null"
}
],
"description": "Costing model the trace was travelled under: `auto` (default),\n`truck`, `bicycle`, `pedestrian` or `motor_scooter`. It decides\nwhich roads the trace may be matched onto, so a walked trace\nmatched as `auto` snaps to the carriageway rather than the path."
},
"encoded_polyline": {
"type": [
"string",
"null"
],
"description": "The trace as a Google encoded polyline with six digits of decimal\nprecision (polyline6), the geometry `route` and `match_trace`\nthemselves return. Provide this or `shape`."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"SegmentSummary": {
"type": "object",
"required": [
"distance_m",
"edge_count"
],
"properties": {
"distance_m": {
"type": "number",
"format": "double",
"description": "Distance carrying this flag in metres. Zero means none of the\nmatched path did."
},
"edge_count": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "How many matched segments carried this flag."
}
},
"description": "How much of the matched path carried one flag (toll, bridge, tunnel).\nThe engine reports no separate time for these, so distance and a count\nare all that can honestly be given."
},
"SurfaceSummary": {
"type": "object",
"required": [
"surface",
"distance_m",
"edge_count"
],
"properties": {
"surface": {
"type": "string",
"description": "The surface, as the routing graph records it: `paved_smooth`,\n`paved`, `paved_rough`, `compacted`, `dirt`, `gravel`, `path`,\n`impassable`."
},
"distance_m": {
"type": "number",
"format": "double",
"description": "Distance on this surface in metres."
},
"edge_count": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "How many matched segments carried this surface."
}
},
"description": "Distance the matched path spent on one road surface."
},
"AdminAreaSummary": {
"type": "object",
"required": [
"country_code",
"country",
"state_code",
"state",
"distance_m",
"duration_s",
"edge_count"
],
"properties": {
"state": {
"type": [
"string",
"null"
],
"default": null,
"description": "State/region name, or null when the graph records none."
},
"country": {
"type": [
"string",
"null"
],
"default": null,
"description": "Country name, or null as for `country_code`."
},
"distance_m": {
"type": "number",
"format": "double",
"description": "Distance in this area in metres."
},
"duration_s": {
"type": "number",
"format": "double",
"description": "Time in this area in seconds."
},
"edge_count": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "How many matched segments fell in this area."
},
"state_code": {
"type": [
"string",
"null"
],
"default": null,
"description": "State/region code, or null when the graph records none."
},
"country_code": {
"type": [
"string",
"null"
],
"default": null,
"description": "ISO 3166-1 alpha-2 country code, or null where the routing graph\nplaces the segment in no admin area at all."
}
},
"description": "Distance and time the matched path spent in one administrative area."
},
"RoadClassSummary": {
"type": "object",
"required": [
"road_class",
"distance_m",
"duration_s",
"edge_count"
],
"properties": {
"distance_m": {
"type": "number",
"format": "double",
"description": "Distance on this road class in metres."
},
"duration_s": {
"type": "number",
"format": "double",
"description": "Time on this road class in seconds."
},
"edge_count": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "How many matched segments carried this road class."
},
"road_class": {
"type": "string",
"description": "The road class, as the routing graph records it: `motorway`,\n`trunk`, `primary`, `secondary`, `tertiary`, `unclassified`,\n`residential`, `service_other`."
}
},
"description": "Distance and time the matched path spent on one road class."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"geometry_polyline6",
"distance_m",
"duration_s",
"summary",
"costing",
"edge_count",
"by_road_class",
"by_admin",
"by_surface",
"toll",
"bridge",
"tunnel"
],
"properties": {
"toll": {
"$ref": "#/$defs/SegmentSummary",
"description": "Tolled portion of the matched path."
},
"bridge": {
"$ref": "#/$defs/SegmentSummary",
"description": "Bridge portion of the matched path."
},
"tunnel": {
"$ref": "#/$defs/SegmentSummary",
"description": "Tunnel portion of the matched path."
},
"costing": {
"type": "string",
"description": "Costing the trace was matched under."
},
"summary": {
"type": "string",
"description": "One-line human summary of the match, for reading aloud."
},
"by_admin": {
"type": "array",
"items": {
"$ref": "#/$defs/AdminAreaSummary"
},
"description": "Distance and time by administrative area, longest first. An entry\nwhose codes are all null covers segments the graph could not place\nin any admin area, counted honestly rather than guessed at."
},
"by_surface": {
"type": "array",
"items": {
"$ref": "#/$defs/SurfaceSummary"
},
"description": "Distance by road surface (`paved`, `paved_smooth`, `gravel`, …),\nlongest first. Empty when the graph records no surface for any\nmatched segment."
},
"distance_m": {
"type": "number",
"format": "double",
"description": "Length of the matched path in metres."
},
"duration_s": {
"type": "number",
"format": "double",
"description": "Travel time along the matched path in seconds, from the engine's\nown time model."
},
"edge_count": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "How many road segments the trace matched onto."
},
"by_road_class": {
"type": "array",
"items": {
"$ref": "#/$defs/RoadClassSummary"
},
"description": "Distance and time by road class (`motorway`, `primary`,\n`residential`, …), longest first."
},
"geometry_polyline6": {
"type": "string",
"description": "The matched path as a Google encoded polyline with six digits of\ndecimal precision (polyline6). This is the trace snapped to real\nroads, not the raw input."
}
}
}
}| lon * | number | Longitude of the search point in decimal degrees (−180 to 180). |
| name | ["string","null"] | The name or brand of the place to find, "Lloyds", "Lloyds Bank", "Sainsbury's", for "where is the nearest X" questions. Every word must appear in the place's name or one of its alternative names, case- and accent-insensitively, with the last word also matching as a prefix ("Sains" finds Sainsbury's)… |
| limit | ["integer","null"] | Maximum number of results (1–10, default 5). |
| fov_deg | ["number","null"] | Field of view: the full width in degrees of a cone centred on `heading_deg`, outside which results are dropped, it is the FULL width, so 90 keeps only what lies within 45 degrees either side of dead ahead. Needs `heading_deg`, a cone has to point somewhere. The count of results removed is reported a… |
| category | ["string","null"] | The kind of place to find. The gateway matches it against the index's lowercased OSM tag values (the value of the POI's `amenity`/`shop`/`tourism`/`railway`/… tag), e.g. "cafe", "fuel", "charging_station", "parking", "pharmacy", "supermarket", "hotel", "restaurant", "fast_food", "atm", "bakery", "ho… |
| radius_m | ["integer","null"] | Maximum straight-line distance of any result from the point, in metres (1–100000, default 2500). |
| heading_deg | ["number","null"] | Which way the user is facing, in degrees **clockwise from true north** (0 = north, 90 = east, 180 = south, 270 = west). Supply it and every result is also described from the user's point of view ("just ahead on your right"); omit it and results fall back to cardinal directions ("to the north-east"),… |
{
"name": "nearby_places",
"description": "Find places near a point, nearest first with distance in metres, by category (cafes, fuel, EV charging, parking), by name or brand (\"the nearest Lloyds bank\", \"nearest Sainsbury's\"), or both. Use this instead of geocode whenever the question is about what is NEAR a location: geocode ranks a brand's branches everywhere and only biases by proximity, so it will happily return a Lloyds in another city over the one 100 m away. Provide `lat`, `lon` and at least one of `category` or `name`. `category` is matched against the map's lowercased OSM tag values (amenity/shop/tourism/…), e.g. \"cafe\", \"fuel\", \"charging_station\", \"parking\", \"pharmacy\", \"supermarket\", \"hotel\", \"restaurant\", \"fast_food\", \"atm\", \"bakery\", \"hospital\", \"station\"; common colloquial names are normalised (\"coffee\" -> cafe, \"ev_charging\" -> charging_station, \"petrol\" -> fuel, \"chemist\" -> pharmacy). `name` matches the place's name or alternative names word by word, case- and accent-insensitively, with the last word also matching as a prefix. Combine the two to disambiguate a brand, \"Lloyds\" plus \"bank\" excludes Lloyds Pharmacy. A category or name the map does not carry returns an empty list, never an error. Optional `radius_m` (default 2500, max 100000) bounds the straight-line search distance and `limit` (default 5, max 10) the result count. Each result has name, one-line label, lat/lon, address parts, distance_m, categories and a `details` object of display tags (opening_hours, website, phone, ...) when the map carries them. Every result also carries `bearing_deg` and a spoken `direction`. Pass `heading_deg` (degrees clockwise from true north, 0 = north, 90 = east) and results are described from where the user stands, \"ahead and slightly to your right, about 80 metres\", with a signed `relative_bearing_deg` (negative left, positive right); without a heading the phrasing falls back to cardinals (\"to the north-east\"), so this works with or without a compass. Add `fov_deg` to keep only what lies within that cone of the heading, it is the FULL width of the cone, so 90 keeps what lies within 45 degrees either side of dead ahead; anything dropped is counted in `out_of_view`, so a non-zero count means there ARE matching places nearby, just not in front of the user, say that rather than \"nothing nearby\". Prefer reading `direction` aloud over coordinates. Requires the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY).",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude of the search point in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude of the search point in decimal degrees (−180 to 180)."
},
"name": {
"type": [
"string",
"null"
],
"description": "The name or brand of the place to find, \"Lloyds\", \"Lloyds Bank\",\n\"Sainsbury's\", for \"where is the nearest X\" questions. Every word\nmust appear in the place's name or one of its alternative names,\ncase- and accent-insensitively, with the last word also matching as\na prefix (\"Sains\" finds Sainsbury's). Combine with `category` to\ndisambiguate a brand used by more than one kind of place (\"Lloyds\"\nplus \"bank\" excludes Lloyds Pharmacy). Optional when `category` is\ngiven; at least one of the two is required."
},
"limit": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Maximum number of results (1–10, default 5)."
},
"fov_deg": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Field of view: the full width in degrees of a cone centred on\n`heading_deg`, outside which results are dropped, it is the\nFULL width, so 90 keeps only what lies within 45 degrees either\nside of dead ahead. Needs\n`heading_deg`, a cone has to point somewhere. The count of\nresults removed is reported as `out_of_view`."
},
"category": {
"type": [
"string",
"null"
],
"description": "The kind of place to find. The gateway matches it against the\nindex's lowercased OSM tag values (the value of the POI's\n`amenity`/`shop`/`tourism`/`railway`/… tag), e.g. \"cafe\", \"fuel\",\n\"charging_station\", \"parking\", \"pharmacy\", \"supermarket\", \"hotel\",\n\"restaurant\", \"fast_food\", \"atm\", \"bakery\", \"hospital\", \"station\",\nand normalises common colloquial names first (\"coffee\" → cafe;\n\"ev_charging\", \"ev charging\" → charging_station; \"petrol\" → fuel;\n\"chemist\" → pharmacy). A category the index does not carry matches\nnothing: the result is an empty list, not an error. Optional when\n`name` is given; at least one of the two is required."
},
"radius_m": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Maximum straight-line distance of any result from the point, in\nmetres (1–100000, default 2500)."
},
"heading_deg": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Which way the user is facing, in degrees **clockwise from true\nnorth** (0 = north, 90 = east, 180 = south, 270 = west). Supply it\nand every result is also described from the user's point of view\n(\"just ahead on your right\"); omit it and results fall back to\ncardinal directions (\"to the north-east\"), so the tool works with\nor without a compass."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"NearbyPlace": {
"type": "object",
"required": [
"label",
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude of the place in decimal degrees."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude of the place in decimal degrees."
},
"city": {
"type": [
"string",
"null"
],
"description": "City or town, when known."
},
"name": {
"type": [
"string",
"null"
],
"description": "Place name, when the source feature has one."
},
"type": {
"type": [
"string",
"null"
],
"description": "Feature type, \"poi\" for category-browse hits."
},
"label": {
"type": "string",
"description": "Human-readable one-line label assembled from the address parts."
},
"country": {
"type": [
"string",
"null"
],
"description": "Country, when known: a country name, or the ISO 3166-1 alpha-2\ncode (e.g. \"GB\") on first-party hits, which carry only the code."
},
"details": {
"description": "Whitelisted OSM display tags on POI hits (opening_hours, website,\nphone, brand, cuisine, wheelchair, wikipedia, ...), passed through\nverbatim when present."
},
"postcode": {
"type": [
"string",
"null"
],
"description": "Postcode, when known."
},
"direction": {
"type": [
"string",
"null"
],
"description": "The direction phrased for speech, \"ahead and slightly to your\nright, about 80 metres\" with a heading, \"to the north-east, about\n80 metres\" without one. Deliver this verbatim rather than reading\nout coordinates."
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "POI categories (e.g. [\"cafe\"]), when the index carries them."
},
"distance_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Straight-line distance from the queried point in metres."
},
"bearing_deg": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Bearing from the queried point to this place, degrees clockwise\nfrom true north. Always present."
},
"relative_bearing_deg": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Where this place is relative to the way the user is facing:\nnegative to the left, positive to the right, −180 to 180. Present\nonly when the request supplied `heading_deg`."
}
},
"description": "One `nearby_places` result: a place matching the requested category\nand/or name near the queried point. The same shape family as [`GeocodeHit`], plus the\nbrowse-only extras (`distance_m`, `categories`, `details`) and the\negocentric extras (`bearing_deg`, `relative_bearing_deg`, `direction`)."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/$defs/NearbyPlace"
},
"description": "Matching places, nearest first. Empty when the index has no such\nplace within the radius."
},
"out_of_view": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "How many otherwise-matching places were dropped for falling\noutside `fov_deg`. Non-zero means there are matching places near\nthe user that are simply not in front of them, say so rather\nthan reporting nothing nearby. Always 0 when no field of view was\nset."
}
}
}
}| Parameter | Type | Description |
|---|---|---|
| jobs | array | Single-stop jobs (at least one job or shipment overall). |
| truck | any | Truck profile (dimensions + ADR declaration). Requires costing "truck"; the travel-time matrix then respects dimensional and dangerous-goods restrictions, so the whole plan is truck-legal. |
| costing | ref | Costing model for the travel-time matrix: "auto" (default), "truck", "bicycle", "pedestrian" or "motor_scooter". |
| vehicles * | array | The fleet (at least one vehicle, each with a start and/or end). |
| emissions | any | The fleet's emission declaration, for UK clean-air / low-emission zone assessment. On its own it annotates: the response's `zones` block names every zone containing one of the problem's own locations and what this vehicle would pay there. With `avoid_zones` it also steers the internal travel-time ma… |
| shipments | array | Pickup+delivery pairs. |
| avoid_zones | ["boolean","null"] | Keep the optimisation's travel-time matrix out of every zone the declared vehicle would be charged or banned in. Requires `emissions`. |
| territories | ["array","null"] | Fleet territories: named polygons that bound which vehicle may serve which stop, referenced by `vehicles[].territory_ids`. These are request data, caller-drawn rounds, validated per call and never stored. Nothing to do with clean-air zones or with the offline map packages of the same word. |
| relax_if_unassigned | any | Re-solve ONCE with these relaxations if the first solve leaves work unassigned, and say honestly which plan came back. At most one second solve, never beyond the caps you state, and the relaxed plan is returned only if it assigns MORE work than the first, giving away constraints for nothing is stric… |
{
"name": "optimise_routes",
"description": "Optimise multi-vehicle, multi-stop delivery plans (VRP). Provide `vehicles` (id, start/end, capacity, skills, time_window), `jobs` (id, location, service_s, delivery/pickup, skills, time_windows) and/or `shipments` (pickup+delivery pairs that ride the same vehicle). Costing \"auto\", \"truck\", \"bicycle\", \"pedestrian\" or \"motor_scooter\" (cargo-bike and courier fleets welcome): with a `truck` profile (dimensions + ADR declaration, as in `route`), the travel-time matrix respects dimensional and dangerous-goods restrictions, so every optimised route is truck-legal. Returns a summary, unassigned tasks and per-vehicle routes with ordered steps (arrival_s/duration_s in seconds, distance_m in metres). Fair use: at most 200 unique locations per problem, and no wider than the routing engine's matrix span (1,500 km on the hosted endpoint for motor costings, 400 km stock on a self-host). Past that, cluster the stops with `cluster` and optimise each group, or submit the whole problem to the asynchronous lane with `submit_optimise_job` (2,000 locations). Optional `territories` are named polygons ([{id, polygon}], GeoJSON [lon, lat] rings, LONGITUDE FIRST) that bound who serves what: a vehicle listing `territory_ids` may serve a task only if that task sits inside at least one of the territories it names, while a vehicle listing none is unrestricted and may serve anything, inside a round or outside every one. The response's `territories` block says which vehicle was eligible for what and names any task no vehicle could take. A vehicle may also declare `reloads` {max_trips 2-5, reload_time_s, depot?} to return to a depot, reload and go out again, the tipping round. It needs a `time_window`, because the shift is what gets split: it is cut into that many consecutive non-overlapping windows separated by the reload time, each trip carrying the vehicle's FULL capacity. That split is fixed BEFORE the solve, so the plan is conservative and never optimistic, it cannot put a lorry in two places at once, but it is an approximation: a trip that finishes early cannot lend its spare time to the next, so stops can come back unassigned that a truly sequential model would have served, and `max_trips` is a budget rather than a prediction (ask for five on a shift that supports three and every window shrinks to a fifth). Read the returned `reloads` block before quoting arrival times, and re-plan after each tip with `replan_routes` for the tighter answer. `relax_if_unassigned` {time_windows_by_s?, allow_overtime_s?} re-solves ONCE with those relaxations if the first plan left work unassigned, and the `relaxation` block says honestly which plan came back: at most one second solve, never beyond the caps stated, and the relaxed plan is returned ONLY if it assigns more work than the first. Capacities, skills and territories are never relaxed; only time windows move. It bills as two solves when the second one runs. Always check `relaxation.relaxed_plan_used` before telling anyone the day fits: a plan produced under relaxation has had promises moved. `emissions` {vehicle_category, fuel, euro_standard} annotates the plan with the clean-air zones its own stops sit in and what this vehicle pays in each; add `avoid_zones: true` to steer the travel-time matrix out of them, which changes the plan itself. Territories, reloads, relaxation and zones are computed by the MapMap gateway; without one configured the tool refuses rather than returning a plan that quietly ignored them. A field this input does not have is REFUSED by name rather than dropped: driver `breaks`, `max_tasks`, `max_travel_time`, `costs` and `eu_drivers_hours` are HTTP API fields this tool has not surfaced, so a plan is never returned as if it had honoured them. Returns `view_url`, a mapmap.ai link that draws the answer on a map (no key needed); the link carries the stop coordinates and names.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"RelaxSpec": {
"type": "object",
"properties": {
"allow_overtime_s": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Extend every vehicle's shift END by this many seconds. Shift starts\nare never moved earlier, a driver cannot begin before they begin."
},
"time_windows_by_s": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Widen every task time window by this many seconds at EACH end. A\n09:00–12:00 window with 1800 becomes 08:30–12:30."
}
},
"description": "What the caller is willing to give up if the first solve leaves work\nunassigned. At least one field is required.",
"additionalProperties": false
},
"TruckSpec": {
"type": "object",
"properties": {
"hazmat": {
"type": "boolean",
"default": false,
"description": "Whether the vehicle carries dangerous goods (ADR). Defaults to\nfalse."
},
"width_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle width in metres."
},
"height_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle height in metres."
},
"length_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle length in metres."
},
"tunnel_code": {
"type": [
"string",
"null"
],
"description": "ADR 8.6.4 tunnel restriction code of the load, e.g. \"B\", \"C5000D\",\n\"B/D\", or \"(-)\"/\"none\" for explicitly unrestricted. Leave unset if\nunknown: a hazmat load without a code is conservatively treated as\ncode B (allowed only through category-A tunnels)."
},
"gross_weight_t": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Gross combination weight in metric tonnes."
}
},
"description": "Truck profile for routing: physical dimensions plus the ADR\ndangerous-goods declaration. Omitted dimensions default to the EU\nmaximum authorised dimensions of Council Directive 96/53/EC (4.0 m\nheight, 2.55 m width, 16.5 m length, 40 t gross weight)."
},
"CostingKind": {
"oneOf": [
{
"type": "string",
"const": "auto",
"description": "Standard car costing."
},
{
"type": "string",
"const": "truck",
"description": "Truck costing; honours dimensional limits and, when a `truck`\nprofile is supplied, ADR dangerous-goods restrictions."
},
{
"type": "string",
"const": "bicycle",
"description": "Bicycle costing; tune it with a `bicycle` options object."
},
{
"type": "string",
"const": "pedestrian",
"description": "Pedestrian (walking) costing; tune it with a `pedestrian` options\nobject (lit streets, wheelchair/blind, hiking difficulty)."
},
{
"type": "string",
"const": "motor_scooter",
"description": "Motor scooter (moped) costing: like auto but prefers lower-speed\nroads and may use ways closed to larger motor vehicles."
}
],
"description": "Costing models exposed by the MCP tools (a deliberate subset of the\nValhalla costing list), serialised in snake_case exactly as Valhalla\nnames them."
},
"ReloadsSpec": {
"type": "object",
"required": [
"max_trips"
],
"properties": {
"depot": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "Where the vehicle reloads. Omitted, its own `start` is used (or its\n`end` if it declared only that)."
},
"max_trips": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "How many trips this vehicle may run in its shift, 2–5. A BUDGET,\nnot a prediction: the shift is cut into that many fixed windows\nbefore the solve, so asking for five trips on a shift that supports\nthree shrinks every window to a fifth and can make the whole day\nworse. Ask for the number of trips you actually expect to run."
},
"reload_time_s": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Seconds at the depot between trips, tipping, reloading, the\nweighbridge. Held out of the shift before it is partitioned, so it\nis never accidentally spent driving."
}
},
"description": "A vehicle's multi-trip reload plan.",
"additionalProperties": false
},
"EmissionsFuel": {
"oneOf": [
{
"type": "string",
"const": "petrol",
"description": "Petrol, including petrol hybrids (schemes rate a hybrid by its\ncombustion engine's approval)."
},
{
"type": "string",
"const": "diesel",
"description": "Diesel, including diesel hybrids."
},
{
"type": "string",
"const": "electric",
"description": "Battery-electric."
},
{
"type": "string",
"const": "hydrogen",
"description": "Hydrogen fuel cell."
},
{
"type": "string",
"const": "gas",
"description": "LPG or CNG; rated as petrol by every scheme in the dataset."
}
],
"description": "What a vehicle burns, in clean-air-zone scheme terms."
},
"EmissionsSpec": {
"type": "object",
"required": [
"vehicle_category",
"fuel"
],
"properties": {
"fuel": {
"$ref": "#/$defs/EmissionsFuel",
"description": "What it burns."
},
"euro_standard": {
"type": [
"integer",
"null"
],
"format": "uint8",
"maximum": 255,
"minimum": 0,
"description": "Its Euro emission standard, 1–6. Heavy-duty approvals are written\nin Roman numerals (Euro VI); declare Euro VI as `6`. Required for\nany combustion fuel, without it no zone can be resolved, and a\nhalf-declared vehicle is indistinguishable from an undeclared one.\nOptional only for `electric` or `hydrogen`."
},
"vehicle_category": {
"$ref": "#/$defs/EmissionsVehicleCategory",
"description": "What kind of vehicle this is, in scheme terms."
}
},
"description": "A vehicle's emission declaration, for clean-air / low-emission zone\nassessment."
},
"TerritorySpec": {
"type": "object",
"required": [
"id",
"polygon"
],
"properties": {
"id": {
"type": "string",
"description": "Caller-chosen id, echoed back and referenced by\n`vehicles[].territory_ids`. Must be unique within the request."
},
"polygon": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2
},
"description": "The outer ring as GeoJSON `[lon, lat]` positions, longitude\nFIRST. Closed or open; an unclosed ring is closed for you."
}
},
"description": "One named territory: a polygon that bounds which vehicle may serve\nwhich stop.",
"additionalProperties": false
},
"OptimiseJobSpec": {
"type": "object",
"required": [
"id",
"location"
],
"properties": {
"id": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "Caller-chosen job id, echoed back in steps and `unassigned`."
},
"pickup": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "int64"
},
"description": "Quantities picked up at the job (matches vehicle `capacity`)."
},
"skills": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "uint32",
"minimum": 0
},
"description": "Skills the job requires."
},
"delivery": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "int64"
},
"description": "Quantities delivered to the job (matches vehicle `capacity`)."
},
"location": {
"$ref": "#/$defs/LatLon",
"description": "Job location."
},
"service_s": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "On-site service time in seconds."
},
"time_windows": {
"type": [
"array",
"null"
],
"items": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"description": "Acceptable `[start, end]` windows in seconds."
}
},
"description": "One single-stop job of an optimisation problem.",
"additionalProperties": false
},
"OptimiseVehicleSpec": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "Caller-chosen vehicle id, echoed back on its route."
},
"end": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "End location; omitted, the route ends at its last stop."
},
"start": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "Start location; at least one of `start`/`end` is required."
},
"skills": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "uint32",
"minimum": 0
},
"description": "Skills this vehicle provides."
},
"reloads": {
"anyOf": [
{
"$ref": "#/$defs/ReloadsSpec"
},
{
"type": "null"
}
],
"description": "Let this vehicle return to a depot, reload and go out again, the\nwaste-collection tipping round, the van that comes back for a\nsecond wave of parcels."
},
"capacity": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "int64"
},
"description": "Multidimensional capacity (same length as job `delivery`/`pickup`)."
},
"time_window": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "int64"
},
"description": "Working window as `[start, end]` in seconds (any consistent epoch)."
},
"territory_ids": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Ids of the request's `territories` this vehicle may work in.\nOmitted or empty, the vehicle is UNRESTRICTED and may serve any\ntask, inside a territory or outside every one of them. Listed, the\nvehicle may serve a task only if that task sits inside at least one\nof the named territories."
}
},
"description": "One vehicle of an optimisation fleet.",
"additionalProperties": false
},
"OptimiseShipmentSpec": {
"type": "object",
"required": [
"pickup",
"delivery"
],
"properties": {
"amount": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "int64"
},
"description": "Quantities moved (matches vehicle `capacity`)."
},
"pickup": {
"$ref": "#/$defs/OptimiseShipmentStopSpec",
"description": "The pickup end."
},
"skills": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "uint32",
"minimum": 0
},
"description": "Skills the shipment requires."
},
"delivery": {
"$ref": "#/$defs/OptimiseShipmentStopSpec",
"description": "The delivery end."
}
},
"description": "A pickup+delivery pair that must ride the same vehicle, pickup first.",
"additionalProperties": false
},
"EmissionsVehicleCategory": {
"oneOf": [
{
"type": "string",
"const": "car",
"description": "A private car."
},
{
"type": "string",
"const": "van",
"description": "A van or light goods vehicle up to 3.5 tonnes."
},
{
"type": "string",
"const": "minibus",
"description": "A minibus (typically 8+ passenger seats, up to 5 tonnes)."
},
{
"type": "string",
"const": "hgv",
"description": "A heavy goods vehicle over 3.5 tonnes."
},
{
"type": "string",
"const": "bus",
"description": "A bus over 5 tonnes."
},
{
"type": "string",
"const": "coach",
"description": "A coach over 5 tonnes."
},
{
"type": "string",
"const": "taxi",
"description": "A licensed hackney carriage."
},
{
"type": "string",
"const": "phv",
"description": "A private hire vehicle."
},
{
"type": "string",
"const": "motorcycle",
"description": "A motorcycle, moped or tricycle."
},
{
"type": "string",
"const": "motorhome",
"description": "A motor caravan or campervan."
}
],
"description": "What a vehicle is, in clean-air-zone scheme terms.\n\nDeclaring this turns \"charge depends on vehicle emissions\" into an\nanswer. Without it a zone can only be named, never priced."
},
"OptimiseShipmentStopSpec": {
"type": "object",
"required": [
"id",
"location"
],
"properties": {
"id": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "Caller-chosen stop id, echoed back in steps and `unassigned`."
},
"location": {
"$ref": "#/$defs/LatLon",
"description": "Stop location."
},
"service_s": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "On-site service time in seconds."
}
},
"description": "One end (pickup or delivery) of a shipment.",
"additionalProperties": false
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"vehicles"
],
"properties": {
"jobs": {
"type": "array",
"items": {
"$ref": "#/$defs/OptimiseJobSpec"
},
"description": "Single-stop jobs (at least one job or shipment overall)."
},
"truck": {
"anyOf": [
{
"$ref": "#/$defs/TruckSpec"
},
{
"type": "null"
}
],
"description": "Truck profile (dimensions + ADR declaration). Requires costing\n\"truck\"; the travel-time matrix then respects dimensional and\ndangerous-goods restrictions, so the whole plan is truck-legal."
},
"costing": {
"$ref": "#/$defs/CostingKind",
"default": "auto",
"description": "Costing model for the travel-time matrix: \"auto\" (default),\n\"truck\", \"bicycle\", \"pedestrian\" or \"motor_scooter\"."
},
"vehicles": {
"type": "array",
"items": {
"$ref": "#/$defs/OptimiseVehicleSpec"
},
"description": "The fleet (at least one vehicle, each with a start and/or end)."
},
"emissions": {
"anyOf": [
{
"$ref": "#/$defs/EmissionsSpec"
},
{
"type": "null"
}
],
"description": "The fleet's emission declaration, for UK clean-air / low-emission\nzone assessment. On its own it annotates: the response's `zones`\nblock names every zone containing one of the problem's own\nlocations and what this vehicle would pay there. With\n`avoid_zones` it also steers the internal travel-time matrix away\nfrom those zones, so the plan itself changes."
},
"shipments": {
"type": "array",
"items": {
"$ref": "#/$defs/OptimiseShipmentSpec"
},
"description": "Pickup+delivery pairs."
},
"avoid_zones": {
"type": [
"boolean",
"null"
],
"description": "Keep the optimisation's travel-time matrix out of every zone the\ndeclared vehicle would be charged or banned in. Requires\n`emissions`."
},
"territories": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/TerritorySpec"
},
"description": "Fleet territories: named polygons that bound which vehicle may\nserve which stop, referenced by `vehicles[].territory_ids`. These\nare request data, caller-drawn rounds, validated per call and\nnever stored. Nothing to do with clean-air zones or with the\noffline map packages of the same word."
},
"relax_if_unassigned": {
"anyOf": [
{
"$ref": "#/$defs/RelaxSpec"
},
{
"type": "null"
}
],
"description": "Re-solve ONCE with these relaxations if the first solve leaves work\nunassigned, and say honestly which plan came back. At most one\nsecond solve, never beyond the caps you state, and the relaxed plan\nis returned only if it assigns MORE work than the first, giving\naway constraints for nothing is strictly worse than not giving them\naway. Capacities, skills and territories are never relaxed: only\ntime windows move, and only by the stated amounts. Bills as two\nsolves when the second one runs."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"OptimisedStep": {
"type": "object",
"required": [
"type",
"arrival_s",
"duration_s",
"service_s",
"waiting_time_s"
],
"properties": {
"id": {
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0,
"description": "The job/shipment-stop id, absent on start/end steps."
},
"load": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "int64"
},
"description": "Vehicle load after the step, when reported."
},
"type": {
"type": "string",
"description": "Step kind: \"start\", \"job\", \"pickup\", \"delivery\", \"break\" or \"end\"."
},
"location": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "The step's location resolved back to coordinates."
},
"arrival_s": {
"type": "integer",
"format": "int64",
"description": "Arrival time in seconds (same epoch as the request's windows)."
},
"service_s": {
"type": "integer",
"format": "int64",
"description": "On-site service time in seconds."
},
"duration_s": {
"type": "integer",
"format": "int64",
"description": "Cumulative travel time when the step begins, in seconds."
},
"waiting_time_s": {
"type": "integer",
"format": "int64",
"description": "Waiting time before the step in seconds."
}
},
"description": "One step of an optimised vehicle route."
},
"OptimisedRoute": {
"type": "object",
"required": [
"vehicle",
"duration_s",
"service_s",
"waiting_time_s",
"steps"
],
"properties": {
"steps": {
"type": "array",
"items": {
"$ref": "#/$defs/OptimisedStep"
},
"description": "Ordered steps: start, tasks in visit order, end."
},
"vehicle": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "The vehicle id from the request."
},
"service_s": {
"type": "integer",
"format": "int64",
"description": "Total on-site service time in seconds."
},
"distance_m": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Total travel distance in metres, when reported."
},
"duration_s": {
"type": "integer",
"format": "int64",
"description": "Total travel time in seconds."
},
"waiting_time_s": {
"type": "integer",
"format": "int64",
"description": "Total waiting time in seconds."
}
},
"description": "One vehicle's optimised route."
},
"UnassignedTask": {
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "The task id from the request."
},
"type": {
"type": "string",
"description": "Task kind: \"job\", \"pickup\" or \"delivery\"."
},
"location": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "The task's location, when known."
}
},
"description": "One unassigned task of an optimisation solution."
},
"OptimiseSummary": {
"type": "object",
"required": [
"cost",
"routes",
"unassigned",
"duration_s",
"service_s",
"waiting_time_s"
],
"properties": {
"cost": {
"type": "integer",
"format": "int64",
"description": "Solver cost of the plan (travel seconds under the default model)."
},
"routes": {
"type": "integer",
"format": "int64",
"description": "Number of vehicle routes in the plan."
},
"service_s": {
"type": "integer",
"format": "int64",
"description": "Total service time in seconds."
},
"distance_m": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Total travel distance in metres, when reported."
},
"duration_s": {
"type": "integer",
"format": "int64",
"description": "Total travel time in seconds."
},
"unassigned": {
"type": "integer",
"format": "int64",
"description": "Number of unassigned tasks."
},
"waiting_time_s": {
"type": "integer",
"format": "int64",
"description": "Total waiting time in seconds."
}
},
"description": "Solution summary of the `optimise_routes` tool."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"profile",
"summary",
"unassigned",
"routes"
],
"properties": {
"zones": {
"description": "Clean-air / low-emission zones touching the problem's own\nlocations, and what the declared vehicle pays in each. Present only\nwhen `emissions` was declared."
},
"routes": {
"type": "array",
"items": {
"$ref": "#/$defs/OptimisedRoute"
},
"description": "One optimised route per used vehicle."
},
"profile": {
"type": "string",
"description": "The matrix costing profile the plan was computed with (\"auto\",\n\"truck\", \"bicycle\", \"pedestrian\" or \"motor_scooter\")."
},
"reloads": {
"description": "The multi-trip split: each vehicle's trips, their windows, the\ndepot each returns to, and the stated approximation. Present only\nwhen a vehicle declared `reloads`.\n\nRead the `basis` inside it before quoting arrival times. The trip\nwindows are fixed BEFORE the solve, so a lorry that tips early\ncannot lend the spare time to its next trip: stops can come back\nunassigned that a truly sequential model would have served. The\nplan is feasible, never optimistic, it cannot put a vehicle in two\nplaces at once, but it is not optimal. Re-plan after each tip\nthrough `replan_routes` for the tighter answer."
},
"summary": {
"$ref": "#/$defs/OptimiseSummary",
"description": "Solution summary."
},
"view_url": {
"type": [
"string",
"null"
],
"description": "A mapmap.ai link that draws this fleet plan, one route per vehicle, on a map: open it or pass it\non as the last line of the answer. Nothing is stored server-side and\nopening it needs no key; the link itself carries the stop coordinates\nand stop names (plus any arrival clocks, dwell times and totals) and\nnothing else, so anyone holding it can read those stops. Absent when\nthe plan cannot be linked (see `view_url_note`) or the server runs\nwith links turned off (`SN_MCP_SITE_URL` empty)."
},
"relaxation": {
"description": "The relaxation report: the caps requested, whether a second solve\nran, whether ITS plan is the one returned, what was widened, and\nwhat is still unassigned. Present only when `relax_if_unassigned`\nwas declared.\n\nAlways read `second_solve` and `relaxed_plan_used` before telling\nanyone the day fits. A plan produced under relaxation has had\npromises moved, and the block is what says so."
},
"unassigned": {
"type": "array",
"items": {
"$ref": "#/$defs/UnassignedTask"
},
"description": "Tasks the solver could not assign to any vehicle."
},
"territories": {
"description": "How the territories bound the plan: which vehicle was eligible for\nwhat, and any task no eligible vehicle existed for. Present only\nwhen `territories` was declared."
},
"view_url_note": {
"type": [
"string",
"null"
],
"description": "Why there is no `view_url` (too many vehicles or stops for one link,\nor over the 6,000 character cap), or what the link left out to fit\nunder the cap (arrival times, dwell times, then stop names). Relay it\nwith the link."
}
}
}
}| Maximum number of results (1–25, default 5). |
| fov_deg | ["number","null"] | Full width in degrees of the cone centred on `bearing_deg` (1–360, default 60, so 30 degrees either side). The FULL width, not the half angle. |
| category | ["string","null"] | The kind of place to look for, from the same vocabulary `nearby_places` uses ("cafe", "pub", "fuel", "charging_station" …). Use "building" to ask what a named building over there is. At least one of `category` and `name` is required. |
| radius_m | ["integer","null"] | Maximum straight-line range in metres (1–5000, default 1000). |
| bearing_deg * | number | Which way the observer is facing, in degrees **clockwise from true north** (0 = north, 90 = east, 180 = south, 270 = west). Required: this tool answers "what is over there", and "there" has to point somewhere. |
| eye_height_m | ["number","null"] | Height of the observer's eye above the ground in metres (0–500, default 1.6, a standing adult). A driver's eye is nearer 1.2 m. |
| visible_only | ["boolean","null"] | When true, return only places whose visibility verdict is `clear`. Default false, which returns everything in the cone WITH its verdict, usually the better answer, because "it is there but you cannot see it from here" is worth saying. |
{
"name": "places_in_view",
"description": "What is over THERE: given a position and the direction the user is facing, the places inside that cone, and whether the ground and the buildings in between let them actually be seen. Use this for \"what is that over there\", \"is there a pub in that direction\", \"what am I looking at\". Use `nearby_places` instead when the question is about what is NEAR a point rather than what is in a direction. Provide `lat`, `lon`, `bearing_deg` (degrees CLOCKWISE FROM TRUE NORTH: 0 north, 90 east, 180 south, 270 west) and at least one of `category` or `name`; `category=building` reaches named buildings. Optional `fov_deg` is the FULL width of the cone (default 60, so 30 degrees either side), `radius_m` the range (default 1000, max 5000), `eye_height_m` the observer's eye height (default 1.6). Each result carries `distance_m`, `bearing_deg`, a signed `angular_offset_deg` (negative left, positive right), a spoken `direction`, and a `visibility` block. READ THE VISIBILITY BLOCK BEFORE SAYING ANYTHING: `clear` means nothing in the data stands in the way, `occluded` names what does (a hill, or a building with its height), and `unknown` means NO check could run: with `unknown` say you cannot tell, never that it is visible. Read `basis` too: `terrain-only` in a town means hills were checked and buildings were not, which is weak. A non-zero `out_of_sector` means there ARE matching places nearby, just not in that direction, so say that rather than \"nothing nearby\". `coverage` names the datasets that answered and `caveat` is the standing limit: visibility is modelled from maps, not observed, and trees, walls, scaffolding and weather are not in it. Requires the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY).",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"lat",
"lon",
"bearing_deg"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude of the observer in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude of the observer in decimal degrees (−180 to 180)."
},
"name": {
"type": [
"string",
"null"
],
"description": "A place name or brand to look for. At least one of `category` and\n`name` is required."
},
"limit": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Maximum number of results (1–25, default 5)."
},
"fov_deg": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Full width in degrees of the cone centred on `bearing_deg` (1–360,\ndefault 60, so 30 degrees either side). The FULL width, not the\nhalf angle."
},
"category": {
"type": [
"string",
"null"
],
"description": "The kind of place to look for, from the same vocabulary\n`nearby_places` uses (\"cafe\", \"pub\", \"fuel\", \"charging_station\" …).\nUse \"building\" to ask what a named building over there is. At\nleast one of `category` and `name` is required."
},
"radius_m": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Maximum straight-line range in metres (1–5000, default 1000)."
},
"bearing_deg": {
"type": "number",
"format": "double",
"description": "Which way the observer is facing, in degrees **clockwise from true\nnorth** (0 = north, 90 = east, 180 = south, 270 = west). Required:\nthis tool answers \"what is over there\", and \"there\" has to point\nsomewhere."
},
"eye_height_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Height of the observer's eye above the ground in metres (0–500,\ndefault 1.6, a standing adult). A driver's eye is nearer 1.2 m."
},
"visible_only": {
"type": [
"boolean",
"null"
],
"description": "When true, return only places whose visibility verdict is `clear`.\nDefault false, which returns everything in the cone WITH its\nverdict, usually the better answer, because \"it is there but you\ncannot see it from here\" is worth saying."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"PlaceInView": {
"type": "object",
"required": [
"name",
"label",
"lat",
"lon",
"categories",
"distance_m",
"bearing_deg",
"angular_offset_deg",
"direction",
"visibility"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees."
},
"name": {
"type": "string",
"description": "Place name."
},
"label": {
"type": "string",
"description": "One-line label: name, street, postcode, town, country."
},
"direction": {
"type": "string",
"description": "The direction phrased for speech, from where the observer stands\n(\"ahead and slightly to your right, about 80 metres\"). Prefer\nreading this aloud over coordinates."
},
"categories": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "The place's categories as the map tags them."
},
"distance_m": {
"type": "number",
"format": "double",
"description": "Straight-line distance from the observer, in metres."
},
"visibility": {
"$ref": "#/$defs/ViewVisibility",
"description": "Whether it can be seen, and what that rests on."
},
"bearing_deg": {
"type": "number",
"format": "double",
"description": "The place's own bearing from the observer, degrees clockwise from\ntrue north."
},
"angular_offset_deg": {
"type": "number",
"format": "double",
"description": "Signed angle from the observer's bearing to the place: negative to\nthe left, positive to the right."
}
},
"description": "One place in the observer's field of view."
},
"ViewVisibility": {
"type": "object",
"required": [
"verdict",
"basis",
"terrain",
"buildings"
],
"properties": {
"basis": {
"type": "string",
"description": "What the verdict rests on: `terrain-and-buildings`,\n`terrain-only`, `buildings-only` or `nothing`. `terrain-only` in a\ntown is weak: it means hills were checked and buildings were not."
},
"terrain": {
"type": "string",
"description": "What the terrain check concluded: `clear`, `occluded` or\n`no-elevation-data`."
},
"verdict": {
"type": "string",
"description": "`clear` (nothing in the data stands in the way), `occluded`\n(something does, and it is named), or `unknown` (no check could\nrun, so this result carries NO visibility claim: say so rather\nthan implying either)."
},
"buildings": {
"type": "string",
"description": "What the building check concluded: `clear`, `occluded`,\n`no-building-data` or `beyond-building-range`."
},
"obstruction": {
"anyOf": [
{
"$ref": "#/$defs/ViewObstruction"
},
{
"type": "null"
}
],
"description": "The obstruction, present exactly when the verdict is `occluded`."
}
},
"description": "Whether a place can be seen from the observer, and what that rests on."
},
"ViewObstruction": {
"type": "object",
"required": [
"kind",
"distance_m",
"height_above_sightline_m"
],
"properties": {
"kind": {
"type": "string",
"description": "`terrain` or `building`."
},
"distance_m": {
"type": "number",
"format": "double",
"description": "How far along the sight line it stands, in metres."
},
"building_name": {
"type": [
"string",
"null"
],
"description": "The blocking building's name, when the map carries one."
},
"building_height_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Height of the blocking building above its own ground, in metres.\nAbsent for terrain."
},
"building_height_basis": {
"type": [
"string",
"null"
],
"description": "`tagged` when somebody mapped the building's height, or\n`schema-default` when nobody did and the map's flat 5 m fallback\nwas used. A `schema-default` obstruction is a weaker finding and\nshould be described as one."
},
"height_above_sightline_m": {
"type": "number",
"format": "double",
"description": "How far its top rises above the sight line, in metres."
}
},
"description": "What stands in the way of seeing a place."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"results",
"coverage",
"caveat"
],
"properties": {
"caveat": {
"type": "string",
"description": "The standing caveat: visibility here is modelled, not observed."
},
"results": {
"type": "array",
"items": {
"$ref": "#/$defs/PlaceInView"
},
"description": "Places inside the cone, best first: everything visible before\neverything unchecked before everything occluded, and within each\nof those, nearest and most nearly dead-ahead first."
},
"coverage": {
"type": "string",
"description": "One sentence naming which datasets the visibility verdicts were\nactually checked against. Worth repeating when a verdict is being\nrelied on."
},
"out_of_sector": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "How many otherwise-matching places were dropped for lying outside\nthe cone. Non-zero means there ARE matching places near the\nobserver, just not in the direction they are facing, so say that\nrather than \"nothing nearby\"."
}
}
}
}| return_to_start | boolean | End the day back at the start (default false). |
{
"name": "plan_day",
"description": "Turn an itinerary into one navigable multi-stop route. Provide a `start` and `stops` (each a `location` {lat, lon} or a free-text `name` to geocode, plus optional `dwell_minutes` time at the stop), optional `depart_at` (RFC 3339) for absolute ETAs, `optimise: true` to reorder stops for the shortest day (VROOM solver), and `return_to_start`. Costing \"auto\", \"truck\" (with a `truck` profile the whole day respects dimensional/ADR restrictions), \"bicycle\", \"pedestrian\" or \"motor_scooter\". Returns the stops in visit order with per-leg duration/distance and arrival/departure times, totals, and the full route geometry (polyline6). Geocoded names carry a `resolution`, when `ambiguous` is true, check `alternatives` and re-run with an explicit location rather than trusting the guess. Returns `view_url`, a mapmap.ai link that draws the answer on a map (no key needed); the link carries the stop coordinates and names.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"TruckSpec": {
"type": "object",
"properties": {
"hazmat": {
"type": "boolean",
"default": false,
"description": "Whether the vehicle carries dangerous goods (ADR). Defaults to\nfalse."
},
"width_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle width in metres."
},
"height_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle height in metres."
},
"length_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle length in metres."
},
"tunnel_code": {
"type": [
"string",
"null"
],
"description": "ADR 8.6.4 tunnel restriction code of the load, e.g. \"B\", \"C5000D\",\n\"B/D\", or \"(-)\"/\"none\" for explicitly unrestricted. Leave unset if\nunknown: a hazmat load without a code is conservatively treated as\ncode B (allowed only through category-A tunnels)."
},
"gross_weight_t": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Gross combination weight in metric tonnes."
}
},
"description": "Truck profile for routing: physical dimensions plus the ADR\ndangerous-goods declaration. Omitted dimensions default to the EU\nmaximum authorised dimensions of Council Directive 96/53/EC (4.0 m\nheight, 2.55 m width, 16.5 m length, 40 t gross weight)."
},
"CostingKind": {
"oneOf": [
{
"type": "string",
"const": "auto",
"description": "Standard car costing."
},
{
"type": "string",
"const": "truck",
"description": "Truck costing; honours dimensional limits and, when a `truck`\nprofile is supplied, ADR dangerous-goods restrictions."
},
{
"type": "string",
"const": "bicycle",
"description": "Bicycle costing; tune it with a `bicycle` options object."
},
{
"type": "string",
"const": "pedestrian",
"description": "Pedestrian (walking) costing; tune it with a `pedestrian` options\nobject (lit streets, wheelchair/blind, hiking difficulty)."
},
{
"type": "string",
"const": "motor_scooter",
"description": "Motor scooter (moped) costing: like auto but prefers lower-speed\nroads and may use ways closed to larger motor vehicles."
}
],
"description": "Costing models exposed by the MCP tools (a deliberate subset of the\nValhalla costing list), serialised in snake_case exactly as Valhalla\nnames them."
},
"PlanDayStopInput": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "Free-text name or address, geocoded when no `location` is given."
},
"location": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "Exact coordinates; skips geocoding."
},
"dwell_minutes": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Time spent at the stop in minutes (default 0); shifts every later\nETA."
}
},
"description": "One stop of a `plan_day` itinerary: an exact location, or a free-text\nname to geocode (ambiguous matches are flagged in the response, never\nguessed silently)."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"start",
"stops"
],
"properties": {
"start": {
"$ref": "#/$defs/PlanDayStopInput",
"description": "Where the day starts (name or location; `dwell_minutes` ignored)."
},
"stops": {
"type": "array",
"items": {
"$ref": "#/$defs/PlanDayStopInput"
},
"description": "The stops to visit (1–20). Visited in the given order unless\n`optimise` is true."
},
"truck": {
"anyOf": [
{
"$ref": "#/$defs/TruckSpec"
},
{
"type": "null"
}
],
"description": "Truck profile (dimensions + ADR declaration). Requires costing\n\"truck\"."
},
"costing": {
"$ref": "#/$defs/CostingKind",
"default": "auto",
"description": "Costing model: \"auto\" (default), \"truck\", \"bicycle\", \"pedestrian\"\nor \"motor_scooter\"."
},
"optimise": {
"type": "boolean",
"default": false,
"description": "Reorder the stops for the shortest day (VROOM solver; requires the\noptimisation sidecar). Default false: visit in the given order."
},
"depart_at": {
"type": [
"string",
"null"
],
"description": "Departure time as RFC 3339 (e.g. \"2026-07-18T09:00:00Z\"); when\ngiven, every ETA is also returned as an absolute timestamp."
},
"return_to_start": {
"type": "boolean",
"default": false,
"description": "End the day back at the start (default false)."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"PlanStart": {
"type": "object",
"required": [
"location"
],
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "The start's name, when one was given."
},
"location": {
"$ref": "#/$defs/LatLon",
"description": "The start's resolved coordinates."
},
"resolution": {
"anyOf": [
{
"$ref": "#/$defs/StopResolution"
},
{
"type": "null"
}
],
"description": "Geocoding details when the start was given as a name."
}
},
"description": "The day's starting point as resolved."
},
"ReturnLeg": {
"type": "object",
"required": [
"travel_duration_s",
"travel_distance_m",
"arrival_offset_s"
],
"properties": {
"arrival_at": {
"type": [
"string",
"null"
],
"description": "Absolute arrival time (RFC 3339), when `depart_at` was given."
},
"arrival_offset_s": {
"type": "number",
"format": "double",
"description": "Arrival back at the start, seconds after departure."
},
"travel_distance_m": {
"type": "number",
"format": "double",
"description": "Distance back to the start, metres."
},
"travel_duration_s": {
"type": "number",
"format": "double",
"description": "Travel time back to the start, seconds."
}
},
"description": "The return leg of a `return_to_start` plan."
},
"GeocodeHit": {
"type": "object",
"required": [
"label",
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees."
},
"city": {
"type": [
"string",
"null"
],
"description": "City or town, when known."
},
"name": {
"type": [
"string",
"null"
],
"description": "Place name, when the source feature has one."
},
"type": {
"type": [
"string",
"null"
],
"description": "Feature type, e.g. \"house\", \"street\", \"city\" (falls back to the\nOSM value when the endpoint does not classify)."
},
"label": {
"type": "string",
"description": "Human-readable one-line label assembled from the address parts."
},
"match": {
"anyOf": [
{
"$ref": "#/$defs/GeocodeMatch"
},
{
"type": "null"
}
],
"description": "How far this hit can be trusted to be the place that was asked\nfor, see [`GeocodeMatch`]. Present whenever the MapMap gateway\nanswered; absent on a deployment falling back to the direct Photon\ngeocoder, and absent on the gateway's own fast paths (a pasted\ncoordinate pair, a bare UK outward code, a category browse), which\nanswer without a ranking to report on."
},
"country": {
"type": [
"string",
"null"
],
"description": "Country, when known."
},
"postcode": {
"type": [
"string",
"null"
],
"description": "Postcode, when known."
}
},
"description": "One geocoding result."
},
"PlannedStop": {
"type": "object",
"required": [
"input_index",
"location",
"dwell_minutes",
"travel_duration_s",
"travel_distance_m",
"arrival_offset_s",
"departure_offset_s"
],
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "The stop's name (from the request or the geocoder)."
},
"location": {
"$ref": "#/$defs/LatLon",
"description": "The stop's resolved coordinates."
},
"arrival_at": {
"type": [
"string",
"null"
],
"description": "Absolute arrival time (RFC 3339), when `depart_at` was given."
},
"resolution": {
"anyOf": [
{
"$ref": "#/$defs/StopResolution"
},
{
"type": "null"
}
],
"description": "Geocoding details when the stop was given as a name."
},
"input_index": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "Index of this stop in the request's `stops` array (visit order may\ndiffer when optimised)."
},
"departure_at": {
"type": [
"string",
"null"
],
"description": "Absolute departure time (RFC 3339), when `depart_at` was given."
},
"dwell_minutes": {
"type": "number",
"format": "double",
"description": "Dwell time applied at this stop, minutes."
},
"arrival_offset_s": {
"type": "number",
"format": "double",
"description": "Arrival, as seconds after departure from the start."
},
"travel_distance_m": {
"type": "number",
"format": "double",
"description": "Distance of the leg arriving at this stop, metres."
},
"travel_duration_s": {
"type": "number",
"format": "double",
"description": "Travel time of the leg arriving at this stop, seconds."
},
"departure_offset_s": {
"type": "number",
"format": "double",
"description": "Departure (arrival + dwell), as seconds after the day's start."
}
},
"description": "One planned stop with its leg and ETAs."
},
"GeocodeMatch": {
"type": "object",
"required": [
"components",
"score_gap",
"source"
],
"properties": {
"source": {
"type": "string",
"description": "Which backend answered: \"mapmap-index\" (the first-party index) or\n\"photon\"."
},
"score_gap": {
"type": "number",
"format": "double",
"description": "The top result's score minus the runner-up's, rounded to 3 decimal\nplaces. `0` for a single result, and `0` from the `photon` source,\nwhich publishes no per-result score, so a `0` is \"no signal\", not\n\"a tie\"."
},
"components": {
"$ref": "#/$defs/GeocodeMatchComponents",
"description": "Per-component verdict on this hit: one entry for each structured\ncomponent supplied, and empty when the query was free text only."
}
},
"description": "How well one geocoding result answers what was actually asked.\n\nGeocoding's real failure mode is not \"no answer\" but a confident answer\nto a different question: a plausible row on the wrong street, with\nnothing in the response to say so. This object is that missing say-so,\nand an agent should read it before acting on an address.\n\nHow to read it:\n\n* Any component `unmatched` or `inferred` on the TOP hit means the\n answer does not carry the address that was asked for, an `unmatched`\n postcode means the result has no postcode at all, `inferred` means it\n has a different one. Neither is a match. Say so rather than presenting\n the hit as the address, and reach for `verify_places` when the address\n came from a model or a user and needs checking rather than using.\n* A small `score_gap` means the ranking barely chose between this hit\n and the runner-up, which is exactly when to show the alternatives\n instead of picking one for the user."
},
"StopResolution": {
"type": "object",
"required": [
"query",
"chosen",
"ambiguous",
"alternatives"
],
"properties": {
"query": {
"type": "string",
"description": "The name that was geocoded."
},
"chosen": {
"$ref": "#/$defs/GeocodeHit",
"description": "The chosen match (best geocoder hit)."
},
"ambiguous": {
"type": "boolean",
"description": "True when other plausible matches exist somewhere else, check\n`alternatives` and re-run with an explicit `location` if the\nchosen one is wrong."
},
"alternatives": {
"type": "array",
"items": {
"$ref": "#/$defs/GeocodeHit"
},
"description": "Up to three alternative matches, best first."
}
},
"description": "How a free-text stop name was resolved to coordinates."
},
"GeocodeMatchComponents": {
"type": "object",
"properties": {
"city": {
"type": [
"string",
"null"
],
"description": "Verdict on the supplied `city`."
},
"street": {
"type": [
"string",
"null"
],
"description": "Verdict on the supplied `street`."
},
"country": {
"type": [
"string",
"null"
],
"description": "Verdict on the supplied `country`."
},
"postcode": {
"type": [
"string",
"null"
],
"description": "Verdict on the supplied `postcode`."
},
"housenumber": {
"type": [
"string",
"null"
],
"description": "Verdict on the supplied `housenumber`."
}
},
"description": "Per-component verdicts inside a [`GeocodeMatch`]. Each is one of\n\"matched\", \"inferred\" or \"unmatched\"; a component that was not supplied\nis absent entirely.\n\n* \"matched\", the result's own field carries the value asked for (case-\n and accent-insensitive, and by containment, so `city: \"London\"`\n matches \"City of London\").\n* \"inferred\", the result carries a value for that component, but not\n the one asked for. It reached the page through ranking, as when a\n street is found by its transliterated name and displayed under its\n canonical one.\n* \"unmatched\", the result carries no value for that component at all."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"costing",
"optimised",
"start",
"stops",
"total_travel_duration_s",
"total_dwell_s",
"total_distance_m",
"finish_offset_s",
"geometry_polyline6",
"summary"
],
"properties": {
"start": {
"$ref": "#/$defs/PlanStart",
"description": "The day's starting point."
},
"stops": {
"type": "array",
"items": {
"$ref": "#/$defs/PlannedStop"
},
"description": "The stops in visit order, each with leg, ETAs and any geocoding\nresolution to double-check."
},
"costing": {
"type": "string",
"description": "The costing the plan was routed with."
},
"summary": {
"type": "string",
"description": "One-line human-readable summary of the day."
},
"view_url": {
"type": [
"string",
"null"
],
"description": "A mapmap.ai link that draws this day plan on a map: open it or pass it\non as the last line of the answer. Nothing is stored server-side and\nopening it needs no key; the link itself carries the stop coordinates\nand stop names (plus any arrival clocks, dwell times and totals) and\nnothing else, so anyone holding it can read those stops. Absent when\nthe plan cannot be linked (see `view_url_note`) or the server runs\nwith links turned off (`SN_MCP_SITE_URL` empty)."
},
"depart_at": {
"type": [
"string",
"null"
],
"description": "The departure time echoed back, when one was given."
},
"finish_at": {
"type": [
"string",
"null"
],
"description": "Absolute end of the day (RFC 3339), when `depart_at` was given."
},
"optimised": {
"type": "boolean",
"description": "Whether the stop order was optimised (VROOM) or kept as given."
},
"return_leg": {
"anyOf": [
{
"$ref": "#/$defs/ReturnLeg"
},
{
"type": "null"
}
],
"description": "The leg back to the start, when `return_to_start` was set."
},
"total_dwell_s": {
"type": "number",
"format": "double",
"description": "Total time at stops, seconds."
},
"view_url_note": {
"type": [
"string",
"null"
],
"description": "Why there is no `view_url` (too many vehicles or stops for one link,\nor over the 6,000 character cap), or what the link left out to fit\nunder the cap (arrival times, dwell times, then stop names). Relay it\nwith the link."
},
"finish_offset_s": {
"type": "number",
"format": "double",
"description": "End of the day (last arrival + dwell), seconds after departure."
},
"total_distance_m": {
"type": "number",
"format": "double",
"description": "Total travel distance, metres."
},
"geometry_polyline6": {
"type": "string",
"description": "Full multi-stop route geometry (polyline6), hand it to the map SDK\nor the `route` tool consumers directly."
},
"total_travel_duration_s": {
"type": "number",
"format": "double",
"description": "Total driving/travel time, seconds."
}
}
}
}| ["string","null"] |
| When they set off, RFC 3339. Defaults to now. |
| destination * | ref | Where they have to be by `arrive_by`. |
| destination_name | ["string","null"] | What to call the destination in the answer ("the school"). |
| max_detour_minutes | ["number","null"] | How far off the direct route a candidate place may sit, as a detour in minutes (default 12, at most 45). |
{
"name": "plan_errands",
"description": "Order a handful of errands against a hard arrival time, and say honestly whether they fit. This is the \"pick up a prescription, get petrol, and be at the school by quarter past three\" tool. Give `origin`, `destination` (+ `destination_name`), `arrive_by` (RFC 3339 with an offset: convert \"quarter past three\" yourself), optional `depart_at`, and 1 to 5 `errands`. Each errand is EITHER a `category` (a kind of place: \"pharmacy\", \"fuel\", \"supermarket\", or a colloquial phrase the server normalises; use `list_place_categories` for the vocabulary) OR a `place` {lat, lon} the driver already knows (\"the school\", \"the nursery\"). Resolve a named place with `geocode` first and pass the coordinate: never invent one. Optional `dwell_minutes` per errand (default 5). The server chooses the order and the actual shops, exhaustively, over engine-computed travel times -- do NOT attempt the ordering or the arithmetic yourself. IMPORTANT: `feasible: false` is an ANSWER, not an error to retry. It names the errand that costs the most (`blocking_errand`), says how late the whole chain would be (`over_by_s`), and returns the stops of the chain that DOES fit with `dropped` naming what had to go. Tell the driver what to drop. Every stop is a real indexed place carrying its id: never mention a shop the answer did not return. `hours` is \"open_on_the_tag\" (the map's tag covers your arrival, which is evidence and not a promise) or \"unknown\" (most places carry no hours at all); a place the tag proves shut is never proposed. ALWAYS show `usage_note`: this is planned before setting off or by a passenger, never at the wheel. Requires the MapMap gateway.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"ErrandSpec": {
"type": "object",
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "What to call this errand in the answer (\"prescription\", \"petrol\").\nDefaults to the category, or to \"stop N\"."
},
"place": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "A specific place the driver already knows, as a coordinate. Use\nthis for \"the school\", \"the nursery\", \"Mum's\": places the map\ncannot be expected to resolve from the words alone. Resolve a NAMED\nplace with `geocode` first and pass the coordinate here; never\nguess one."
},
"category": {
"type": [
"string",
"null"
],
"description": "The KIND of place wanted: a category from `list_place_categories`\n(\"pharmacy\", \"fuel\", \"supermarket\"), or a colloquial phrase the\nserver normalises (\"petrol station\", \"chemist\"). Use this for\nanything the driver described by what it is rather than by name."
},
"dwell_minutes": {
"type": [
"number",
"null"
],
"format": "double",
"description": "How long the driver is out of the car here, minutes (default 5)."
}
},
"description": "One errand in a `plan_errands` chain: a kind of place to find, or a\nplace the caller already knows."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"origin",
"destination",
"arrive_by",
"errands"
],
"properties": {
"origin": {
"$ref": "#/$defs/LatLon",
"description": "Where the driver sets off from."
},
"errands": {
"type": "array",
"items": {
"$ref": "#/$defs/ErrandSpec"
},
"description": "The errands, in any order: the answer decides the order. One to\nfive."
},
"arrive_by": {
"type": "string",
"description": "The hard arrival time, RFC 3339 with an offset\n(\"2026-09-21T15:15:00+01:00\"). Convert \"quarter past three\" to an\nabsolute instant in the driver's own offset before calling."
},
"depart_at": {
"type": [
"string",
"null"
],
"description": "When they set off, RFC 3339. Defaults to now."
},
"destination": {
"$ref": "#/$defs/LatLon",
"description": "Where they have to be by `arrive_by`."
},
"destination_name": {
"type": [
"string",
"null"
],
"description": "What to call the destination in the answer (\"the school\")."
},
"max_detour_minutes": {
"type": [
"number",
"null"
],
"format": "double",
"description": "How far off the direct route a candidate place may sit, as a detour\nin minutes (default 12, at most 45)."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"ErrandStop": {
"type": "object",
"required": [
"errand",
"kind",
"lat",
"lon",
"arrive",
"depart",
"drive_s",
"hours"
],
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "The index id, for an indexed place. Its presence is what makes the\nstop checkable; a stop without one is a coordinate the caller gave."
},
"lat": {
"type": "number",
"format": "double",
"description": "Latitude."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude."
},
"kind": {
"type": "string",
"description": "\"category\" for a place the index found, \"place\" for one the caller\nsupplied."
},
"name": {
"type": [
"string",
"null"
],
"description": "The place's name."
},
"hours": {
"type": "string",
"description": "What the map's opening-hours tag says about the arrival time:\n\"open_on_the_tag\" (the tag covers it, which is evidence and NOT a\npromise) or \"unknown\" (no usable tag). A stop the tag proves shut\nis never proposed, so \"closed\" never appears here."
},
"label": {
"type": [
"string",
"null"
],
"description": "Its full label, for reading aloud."
},
"arrive": {
"type": "string",
"description": "When the driver arrives, RFC 3339."
},
"depart": {
"type": "string",
"description": "When they leave, RFC 3339."
},
"errand": {
"type": "string",
"description": "Which errand this stop discharges."
},
"drive_s": {
"type": "number",
"format": "double",
"description": "Driving time of the leg into this stop, seconds."
},
"hours_tag": {
"type": [
"string",
"null"
],
"description": "The tag itself, when the map carries one."
}
},
"description": "One planned stop in an errand chain."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"feasible",
"departure",
"arrive_by",
"stops",
"dropped",
"corridor_note",
"opening_hours_note",
"usage_note",
"verification_note"
],
"properties": {
"stops": {
"type": "array",
"items": {
"$ref": "#/$defs/ErrandStop"
},
"description": "The stops, in visit order. On an infeasible answer these are the\nstops of the reduced plan, the one that DOES fit."
},
"reason": {
"type": [
"string",
"null"
],
"description": "The same cause in plain language, for the driver."
},
"arrival": {
"type": [
"string",
"null"
],
"description": "When the plan arrives, RFC 3339. Present whenever there is a plan,\nincluding the reduced plan on an infeasible answer."
},
"dropped": {
"type": "array",
"items": {
"type": "string"
},
"description": "Errands that had to be dropped for the plan to fit. Empty when\nfeasible."
},
"slack_s": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Spare seconds before the deadline."
},
"feasible": {
"type": "boolean",
"description": "**Whether every errand fits before the deadline.** False is an\nANSWER, not an error: report `reason`, the errand named in\n`blocking_errand`, and what `dropped` says has to go."
},
"arrive_by": {
"type": "string",
"description": "The deadline, echoed."
},
"departure": {
"type": "string",
"description": "When the driver sets off, RFC 3339."
},
"over_by_s": {
"type": [
"number",
"null"
],
"format": "double",
"description": "How late the whole chain would be, seconds."
},
"usage_note": {
"type": "string",
"description": "**Always present.** Why this is planned stationary rather than at\nthe wheel. Show it."
},
"attribution": {
"type": [
"string",
"null"
],
"description": "Credit owed for the place data, when the answer used the index."
},
"reason_code": {
"type": [
"string",
"null"
],
"description": "Machine token for why the chain does not fit: \"deadline_missed\",\n\"destination_unreachable_in_time\", \"no_candidates_in_corridor\",\n\"all_candidates_closed\" or \"unroutable\"."
},
"corridor_note": {
"type": "string",
"description": "**Always present.** What the corridor search did and did not look\nat. An empty answer is a statement about this index and this\ncorridor, never about what exists on the ground."
},
"failed_errand": {
"type": [
"string",
"null"
],
"description": "The errand a \"no_candidates_in_corridor\" or \"all_candidates_closed\"\nanswer is about."
},
"total_drive_s": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Total driving time, seconds."
},
"total_dwell_s": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Total time out of the car, seconds."
},
"blocking_errand": {
"type": [
"string",
"null"
],
"description": "The errand that costs the most time, when the deadline is missed."
},
"verification_note": {
"type": "string",
"description": "**Always present.** That every stop is an indexed place or a\nsupplied coordinate, never a generated one."
},
"geometry_polyline6": {
"type": [
"string",
"null"
],
"description": "The planned journey as an encoded polyline6."
},
"opening_hours_note": {
"type": "string",
"description": "**Always present.** How opening hours were used, and how little of\nthe map carries them."
}
}
}
}| ["number","null"] |
| State of charge at the start, 0–1 (default 0.9). |
| waypoints | ["array","null"] | Intermediate points the route must pass through, in order (at most 8). Charge stops are inserted around them. |
| connectors | ["array","null"] | Keep only charge points offering at least one of these connector standards: "type2", "type1", "ccs", "chademo", "tesla", "domestic", "other". This narrows the vehicle's own set, never widens it. |
| destination * | ref | Where it ends. |
| reserve_soc | ["number","null"] | The floor the state of charge must never fall below mid-route (default 0.1). Distinct from the arrival figure. |
| min_arrival_soc | ["number","null"] | Lowest acceptable state of charge on arrival (default 0.1). |
| max_detour_minutes | ["number","null"] | How far off the route a charge point may sit, as a detour in minutes (default 15, at most 120). |
| ambient_temperature_c | ["number","null"] | Ambient temperature in °C. Derates traction energy from a published study; cabin heating belongs in the vehicle's `aux_kw`. |
{
"name": "plan_ev_route",
"description": "Plan a whole electric-vehicle journey, charge stops included. Give `origin` and `destination` (plus optional `waypoints`) and a `vehicle`, a published profile (\"small_hatch\", \"saloon\", \"suv\", \"van\") and/or inline figures (battery_kwh, mass_kg, drag_area_m2, aux_kw, connectors), with `start_soc` (default 0.9), `min_arrival_soc` (default 0.1), `reserve_soc` (default 0.1, the floor the charge must never drop below mid-route), optional `connectors` and `min_kw` filters and `ambient_temperature_c`. Energy comes from a published road-load physics model over the route's own legs; charge times are integrated over the vehicle's charging curve capped by the charge point, NOT energy divided by peak power, which is the single biggest error in naive EV planners. Returns the stops with arrive/depart state of charge, charge time and detour, a per-leg state-of-charge trace, and the journey's driving and charging time. IMPORTANT: when no plan exists, a charger desert, a connector mismatch, a gap wider than the car's range, the answer comes back with `feasible: false`, a `reason` and the furthest point on the route the car can actually reach. That is an ANSWER, not an error to retry: report the reason and never describe it as a plan. `gradient_data` says whether elevation was available: \"absent\" means consumption was modelled on the flat and under-reads a hilly route. There is no national charge-point registry, so ALWAYS show the returned `coverage_note`, an infeasible plan means \"none from these operators\", never \"there are no chargers here\", and statuses are current only when `availability_live` is true. Requires the MapMap gateway; answers a clear error when the deployment has no charge-point dataset. Display the returned charging_attribution with the plan.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"EvVehicleSpec": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "Display name for the vehicle in the answer."
},
"aux_kw": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Auxiliary load in kW, lights, electronics, cabin conditioning.\nWinter heating is several times the mild-weather default."
},
"mass_kg": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Kerb mass, kg."
},
"profile": {
"type": [
"string",
"null"
],
"description": "A published default profile: \"small_hatch\", \"saloon\", \"suv\" or\n\"van\". On its own it selects that vehicle; alongside any inline\nfigure below it is the base the figure overrides."
},
"connectors": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Connectors the vehicle accepts: \"type1\", \"type2\", \"ccs1\", \"ccs2\",\n\"chademo\", \"tesla\", \"gbt\"."
},
"battery_kwh": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Gross nominal battery capacity, kWh."
},
"drag_area_m2": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Drag area (drag coefficient × frontal area), m²."
},
"usable_fraction": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Fraction of the gross pack the vehicle will actually use, 0–1."
}
},
"description": "The vehicle for `plan_ev_route`: one of the published defaults by name,\ninline figures, or a named default with inline figures over it."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"origin",
"destination"
],
"properties": {
"min_kw": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Keep only charge points with a usable connector rated at least this\nmany kW (e.g. 50 for rapid charging only)."
},
"origin": {
"$ref": "#/$defs/LatLon",
"description": "Where the journey starts."
},
"vehicle": {
"anyOf": [
{
"$ref": "#/$defs/EvVehicleSpec"
},
{
"type": "null"
}
],
"description": "The vehicle. Omitted ⇒ the published \"saloon\" default, and the\nanswer says which vehicle it used."
},
"start_soc": {
"type": [
"number",
"null"
],
"format": "double",
"description": "State of charge at the start, 0–1 (default 0.9)."
},
"waypoints": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/LatLon"
},
"description": "Intermediate points the route must pass through, in order (at most\n8). Charge stops are inserted around them."
},
"connectors": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Keep only charge points offering at least one of these connector\nstandards: \"type2\", \"type1\", \"ccs\", \"chademo\", \"tesla\", \"domestic\",\n\"other\". This narrows the vehicle's own set, never widens it."
},
"destination": {
"$ref": "#/$defs/LatLon",
"description": "Where it ends."
},
"reserve_soc": {
"type": [
"number",
"null"
],
"format": "double",
"description": "The floor the state of charge must never fall below mid-route\n(default 0.1). Distinct from the arrival figure."
},
"min_arrival_soc": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Lowest acceptable state of charge on arrival (default 0.1)."
},
"max_detour_minutes": {
"type": [
"number",
"null"
],
"format": "double",
"description": "How far off the route a charge point may sit, as a detour in\nminutes (default 15, at most 120)."
},
"ambient_temperature_c": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Ambient temperature in °C. Derates traction energy from a published\nstudy; cabin heating belongs in the vehicle's `aux_kw`."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"EvPlanLeg": {
"type": "object",
"required": [
"from",
"to",
"duration_s",
"distance_m",
"start_soc",
"end_soc",
"consumed_wh",
"regen_wh"
],
"properties": {
"to": {
"type": "string",
"description": "Where it ends: a charge point's id or \"destination\"."
},
"from": {
"type": "string",
"description": "Where the leg starts: \"origin\" or a charge point's id."
},
"end_soc": {
"type": "number",
"format": "double",
"description": "State of charge at the end."
},
"min_soc": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Lowest state of charge anywhere within the leg."
},
"regen_wh": {
"type": "number",
"format": "double",
"description": "Battery energy regenerative braking gives back, Wh."
},
"start_soc": {
"type": "number",
"format": "double",
"description": "State of charge at the start of the leg."
},
"distance_m": {
"type": "number",
"format": "double",
"description": "Engine-computed distance, metres."
},
"duration_s": {
"type": "number",
"format": "double",
"description": "Engine-computed driving time, seconds."
},
"consumed_wh": {
"type": "number",
"format": "double",
"description": "Battery energy the leg spends, Wh."
}
},
"description": "One driving leg of the plan, with its state-of-charge bookkeeping."
},
"EvPlanStop": {
"type": "object",
"required": [
"charger_id",
"source",
"lat",
"lon",
"dc",
"arrive_soc",
"depart_soc",
"charge_s",
"along_route_position",
"off_route_m",
"status_live"
],
"properties": {
"dc": {
"type": "boolean",
"description": "Whether the connector delivers DC (rapid) rather than AC."
},
"lat": {
"type": "number",
"format": "double",
"description": "WGS84 latitude in decimal degrees."
},
"lon": {
"type": "number",
"format": "double",
"description": "WGS84 longitude in decimal degrees."
},
"name": {
"type": [
"string",
"null"
],
"description": "Site name, where the operator publishes one."
},
"source": {
"type": "string",
"description": "Which operator feed this came from."
},
"charge_s": {
"type": "number",
"format": "double",
"description": "Time plugged in, seconds, integrated over the vehicle's charging\ncurve capped by the charge point, not energy ÷ peak power."
},
"detour_s": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Extra driving time this stop costs against going straight past it,\nseconds."
},
"operator": {
"type": [
"string",
"null"
],
"description": "Operator display name."
},
"arrive_soc": {
"type": "number",
"format": "double",
"description": "State of charge on arrival. Never below the reserve floor."
},
"charger_id": {
"type": "string",
"description": "Operator-scoped stable id."
},
"charger_kw": {
"type": [
"number",
"null"
],
"format": "double",
"description": "That connector's rated power, kW, what the charge time was\ncomputed against."
},
"depart_soc": {
"type": "number",
"format": "double",
"description": "State of charge on departure."
},
"off_route_m": {
"type": "number",
"format": "double",
"description": "Straight-line offset from the route geometry, metres."
},
"status_live": {
"type": "boolean",
"description": "Whether the status came from a live feed rather than the last\ningest."
},
"available_now": {
"type": [
"boolean",
"null"
],
"description": "Whether a bay is free right now. Present only where a live\navailability feed backs the claim, absent means unknown, never\n\"occupied\"."
},
"power_kw_source": {
"type": [
"string",
"null"
],
"description": "\"declared\" when the operator published the rating, \"derived\" when it\nwas computed from voltage × amperage × phases. Never present the two\nas the same thing to a user."
},
"connector_standard": {
"type": [
"string",
"null"
],
"description": "The connector the plan charges on."
},
"along_route_position": {
"type": "number",
"format": "double",
"description": "How far along the route this stop sits, 0.0–1.0."
}
},
"description": "One charge stop in the plan."
},
"EvPlanSummary": {
"type": "object",
"required": [
"stops",
"total_drive_s",
"total_charge_s",
"total_duration_s",
"total_distance_m",
"start_soc",
"energy_kwh"
],
"properties": {
"stops": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "How many charge stops the plan contains. Zero on a journey the car\nmakes on its own, and zero on an infeasible one."
},
"start_soc": {
"type": "number",
"format": "double",
"description": "State of charge the journey starts at."
},
"energy_kwh": {
"type": "number",
"format": "double",
"description": "Net battery energy the journey costs, kWh."
},
"arrival_soc": {
"type": [
"number",
"null"
],
"format": "double",
"description": "State of charge on arrival, when the journey is feasible."
},
"total_drive_s": {
"type": "number",
"format": "double",
"description": "Time spent driving, seconds."
},
"total_charge_s": {
"type": "number",
"format": "double",
"description": "Time spent plugged in, seconds."
},
"total_distance_m": {
"type": "number",
"format": "double",
"description": "Distance of the planned journey, metres."
},
"total_duration_s": {
"type": "number",
"format": "double",
"description": "Driving plus charging, seconds, the number a user cares about."
}
},
"description": "The plan at a glance."
},
"EvPlanSocPoint": {
"type": "object",
"required": [
"at",
"soc",
"along_route_position"
],
"properties": {
"at": {
"type": "string",
"description": "\"origin\", a charge point's id, or \"destination\"."
},
"soc": {
"type": "number",
"format": "double",
"description": "State of charge on arrival at this point."
},
"departing_soc": {
"type": [
"number",
"null"
],
"format": "double",
"description": "State of charge on leaving, at a charge stop."
},
"along_route_position": {
"type": "number",
"format": "double",
"description": "How far along the route this point sits, 0.0–1.0."
}
},
"description": "One point on the state-of-charge trace."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"feasible",
"summary",
"stops",
"legs",
"soc_trace",
"gradient_data",
"coverage_note",
"availability_live"
],
"properties": {
"legs": {
"type": "array",
"items": {
"$ref": "#/$defs/EvPlanLeg"
},
"description": "The driving legs, in order."
},
"stops": {
"type": "array",
"items": {
"$ref": "#/$defs/EvPlanStop"
},
"description": "The charge stops, in visit order. Always empty when `feasible` is\nfalse: a journey that cannot be completed has no stop list."
},
"reason": {
"type": [
"string",
"null"
],
"description": "The same cause in plain language, for the user."
},
"summary": {
"$ref": "#/$defs/EvPlanSummary",
"description": "The plan at a glance."
},
"vehicle": {
"type": [
"string",
"null"
],
"description": "The vehicle the plan was computed for."
},
"feasible": {
"type": "boolean",
"description": "**Whether the journey is possible at all.** False means no plan\nexists, a charger desert, a connector mismatch, or a gap wider than\nthe car's range. Report the `reason` and the furthest reachable\npoint; never describe an infeasible answer as a plan."
},
"soc_trace": {
"type": "array",
"items": {
"$ref": "#/$defs/EvPlanSocPoint"
},
"description": "State of charge at every point of the journey."
},
"reason_code": {
"type": [
"string",
"null"
],
"description": "Machine token for why no plan exists, when none does:\n\"no_chargers_in_corridor\", \"connector_mismatch\", \"out_of_range\",\n\"dead_end\", \"below_min_kw\", \"chargers_unrated\", \"stop_limit\",\n\"dataset_empty\", \"no_charge_curve\" or \"unroutable\"."
},
"coverage_note": {
"type": "string",
"description": "**Always present.** What this deployment's charge-point dataset does\nand does not cover. An infeasible plan means \"none from these\noperators\", never \"there are no chargers here\". Show this alongside\nthe answer."
},
"gradient_data": {
"type": "string",
"description": "\"complete\", \"partial\" or \"absent\". **\"absent\" means the deployment\nhad no elevation data and consumption was modelled on the flat**,\nwhich under-reads a hilly route. Say so rather than presenting the\nfigure as measured."
},
"profile_source": {
"type": [
"string",
"null"
],
"description": "\"default\" when a published profile supplied the figures, \"inline\"\nwhen the caller did."
},
"route_distance_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Distance of the planned route, metres."
},
"route_duration_s": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Driving time of the planned route, seconds."
},
"availability_live": {
"type": "boolean",
"description": "Whether charge-point statuses came from a live availability feed. A\nstatic planner is the default: without a feed, nothing in this\nanswer is a claim about which bays are free right now."
},
"geometry_polyline6": {
"type": [
"string",
"null"
],
"description": "The planned journey's geometry as an encoded polyline6, through the\ncharge stops."
},
"charging_attribution": {
"type": [
"string",
"null"
],
"description": "Attribution string for the charge-point operators actually used,\ndisplay it with the plan (a licence obligation)."
},
"furthest_reachable_lat": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Latitude of that furthest reachable point."
},
"furthest_reachable_lon": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Longitude of that furthest reachable point."
},
"furthest_reachable_position": {
"type": [
"number",
"null"
],
"format": "double",
"description": "How far along the route the vehicle can get unaided, 0.0–1.0, when\nno plan exists."
}
}
}
}| exclude_polygons |
| ["array","null"] |
| Areas to avoid, scenario analysis ("close this bridge and recompute reachability"): an array of polygons, each an array of `[lon, lat]` pairs forming one exterior ring (GeoJSON-style, longitude FIRST). Roads intersecting any ring are excluded from the reachability search. Applies to the Valhalla eng… |
{
"name": "reachable_area",
"description": "Compute the area reachable from an origin within one or more travel-time budgets, walkability/cyclability rings. Costing \"pedestrian\" answers \"how far can I walk in 15 minutes?\", \"bicycle\" the cycling equivalent; \"auto\", \"truck\" and \"motor_scooter\" work too (e.g. delivery coverage). `contours_minutes` lists the ring boundaries in minutes (1 to 4 values, each up to 120); set `polygons` true for filled polygons ready to render as a map fill layer instead of contour lines. Returns a GeoJSON FeatureCollection, one feature per contour. The origin is first moved onto the nearest road the travel mode can use (ferries excluded, at most 5 km away) and the rings are drawn from there: `snapped_origin` {lat, lon, distance_m} on the collection and on every feature's properties says where. An origin with no road within 5 km (open sea, desert, an unmapped area) is refused with \"no roads near this point\" rather than answered with a speck, and that refusal is not billed; move it onto land near a road. Optional `exclude_polygons` for before/after scenarios (\"close this bridge and recompute reachability\"): an array of polygons, each an array of [lon, lat] pairs forming one ring, longitude FIRST, whose intersecting roads are excluded from the reachability search. Applies to the Valhalla engine; unsupported on the GraphHopper engine, where it is ignored.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"CostingKind": {
"oneOf": [
{
"type": "string",
"const": "auto",
"description": "Standard car costing."
},
{
"type": "string",
"const": "truck",
"description": "Truck costing; honours dimensional limits and, when a `truck`\nprofile is supplied, ADR dangerous-goods restrictions."
},
{
"type": "string",
"const": "bicycle",
"description": "Bicycle costing; tune it with a `bicycle` options object."
},
{
"type": "string",
"const": "pedestrian",
"description": "Pedestrian (walking) costing; tune it with a `pedestrian` options\nobject (lit streets, wheelchair/blind, hiking difficulty)."
},
{
"type": "string",
"const": "motor_scooter",
"description": "Motor scooter (moped) costing: like auto but prefers lower-speed\nroads and may use ways closed to larger motor vehicles."
}
],
"description": "Costing models exposed by the MCP tools (a deliberate subset of the\nValhalla costing list), serialised in snake_case exactly as Valhalla\nnames them."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"origin",
"contours_minutes"
],
"properties": {
"origin": {
"$ref": "#/$defs/LatLon",
"description": "Origin the reachable area is computed from."
},
"costing": {
"$ref": "#/$defs/CostingKind",
"default": "auto",
"description": "Travel mode: \"auto\" (default), \"truck\", \"bicycle\", \"pedestrian\"\nor \"motor_scooter\"."
},
"polygons": {
"type": [
"boolean",
"null"
],
"description": "Return filled polygons instead of contour linestrings (default\nfalse). Polygons draw directly as a MapLibre fill layer."
},
"contours_minutes": {
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"description": "Contour boundaries in minutes of travel time, e.g. [5, 10, 15]\nfor 5/10/15-minute rings. 1 to 4 values (the routing engine's\nlimit), each between 0 and 120 minutes."
},
"exclude_polygons": {
"type": [
"array",
"null"
],
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2
}
},
"description": "Areas to avoid, scenario analysis (\"close this bridge and\nrecompute reachability\"): an array of polygons, each an array of\n`[lon, lat]` pairs forming one exterior ring (GeoJSON-style,\nlongitude FIRST). Roads intersecting any ring are excluded from\nthe reachability search. Applies to the Valhalla engine;\nunsupported on the GraphHopper engine, where it is ignored."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"geojson"
],
"properties": {
"geojson": {
"description": "GeoJSON FeatureCollection of the reachability contours, one\nfeature per requested minute value (each feature's `contour`\nproperty is its minutes), as returned by the routing engine, drawn\nfrom the origin snapped onto the nearest usable road: the\ncollection's `snapped_origin` `{lat, lon, distance_m}` (repeated on\nevery feature's properties) says where that was."
}
}
}
}| any |
| Truck profile (dimensions + ADR declaration). Requires costing "truck"; the travel-time matrix then respects dimensional and dangerous-goods restrictions, so the whole plan is truck-legal. |
| changes | any | Changes to the work itself. Optional, on the same condition. |
| costing | ref | Costing model for the travel-time matrix: "auto" (default), "truck", "bicycle", "pedestrian" or "motor_scooter". |
| progress | array | Per-vehicle progress. Optional, but at least one progress entry or one change is required, a re-plan that reports nothing new is the original problem. |
| vehicles * | array | The fleet (at least one vehicle, each with a start and/or end). |
| emissions | any | The fleet's emission declaration, for UK clean-air / low-emission zone assessment. On its own it annotates: the response's `zones` block names every zone containing one of the problem's own locations and what this vehicle would pay there. With `avoid_zones` it also steers the internal travel-time ma… |
| shipments | array | Pickup+delivery pairs. |
| avoid_zones | ["boolean","null"] | Keep the optimisation's travel-time matrix out of every zone the declared vehicle would be charged or banned in. Requires `emissions`. |
| territories | ["array","null"] | Fleet territories: named polygons that bound which vehicle may serve which stop, referenced by `vehicles[].territory_ids`. These are request data, caller-drawn rounds, validated per call and never stored. Nothing to do with clean-air zones or with the offline map packages of the same word. |
| relax_if_unassigned | any | Re-solve ONCE with these relaxations if the first solve leaves work unassigned, and say honestly which plan came back. At most one second solve, never beyond the caps you state, and the relaxed plan is returned only if it assigns MORE work than the first, giving away constraints for nothing is stric… |
{
"name": "replan_routes",
"description": "Re-plan a fleet part-way through its shift. Send the day back; nothing is stored. MapMap holds NO dispatch state, no plan, no vehicle position, no completion log, so a re-plan is not a delta against something we remember: you pass the day's `optimise_routes` problem in full, plus `progress` (per vehicle: `completed_stop_ids` IN THE ORDER SERVED, an optional `current_position`, and `unavailable: true` for a breakdown or an end of hours) and/or `changes` (`cancel_job_ids`, `add_jobs`, `add_shipments`), and get a fresh plan for what is left. That costs bandwidth and buys the absence of a server-side plan that can go stale, leak, or fall out of step with the telematics platform that actually owns the truth, and it makes a re-plan reproducible: the same body always yields the same answer. Completed stops are LOCKED by construction: they are removed from the problem entirely and each vehicle starts from where it actually is, so the solver cannot move a stop that has already happened, a guarantee the solver cannot break, rather than a hint it is free to ignore. At least one progress entry or one change is required. A re-plan has NO CLOCK and no memory of the shift so far: time windows are solved from the start of each vehicle's `time_window`, not from now, and `max_tasks`, `max_travel_time`, breaks and `capacity` apply to the remaining route as written. Send what each vehicle has LEFT (a `time_window` that starts at the current time, limits and capacity reduced by what has been used); the `replan` notes name every such field the request carried. Returns the same plan shape as `optimise_routes` for the REMAINING work, plus a `replan` block: the prefix locked per vehicle, where each re-plans from and how that was decided, stops released from a vehicle that can no longer serve them, tasks forced unassigned, and a note for every id that did not resolve. Read that block, a stop that vanished from the plan is named there rather than left for a dispatcher to notice at four in the afternoon; a cancelled id that matched nothing is reported there too rather than refused. Multi-trip vehicles cannot be re-planned: a completion does not say which trip it belongs to, so a problem whose vehicles declare `reloads` is refused with what to send instead. Billed on the remaining problem, not the original. Requires the MapMap gateway.",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"RelaxSpec": {
"type": "object",
"properties": {
"allow_overtime_s": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Extend every vehicle's shift END by this many seconds. Shift starts\nare never moved earlier, a driver cannot begin before they begin."
},
"time_windows_by_s": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Widen every task time window by this many seconds at EACH end. A\n09:00–12:00 window with 1800 becomes 08:30–12:30."
}
},
"description": "What the caller is willing to give up if the first solve leaves work\nunassigned. At least one field is required.",
"additionalProperties": false
},
"TruckSpec": {
"type": "object",
"properties": {
"hazmat": {
"type": "boolean",
"default": false,
"description": "Whether the vehicle carries dangerous goods (ADR). Defaults to\nfalse."
},
"width_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle width in metres."
},
"height_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle height in metres."
},
"length_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle length in metres."
},
"tunnel_code": {
"type": [
"string",
"null"
],
"description": "ADR 8.6.4 tunnel restriction code of the load, e.g. \"B\", \"C5000D\",\n\"B/D\", or \"(-)\"/\"none\" for explicitly unrestricted. Leave unset if\nunknown: a hazmat load without a code is conservatively treated as\ncode B (allowed only through category-A tunnels)."
},
"gross_weight_t": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Gross combination weight in metric tonnes."
}
},
"description": "Truck profile for routing: physical dimensions plus the ADR\ndangerous-goods declaration. Omitted dimensions default to the EU\nmaximum authorised dimensions of Council Directive 96/53/EC (4.0 m\nheight, 2.55 m width, 16.5 m length, 40 t gross weight)."
},
"CostingKind": {
"oneOf": [
{
"type": "string",
"const": "auto",
"description": "Standard car costing."
},
{
"type": "string",
"const": "truck",
"description": "Truck costing; honours dimensional limits and, when a `truck`\nprofile is supplied, ADR dangerous-goods restrictions."
},
{
"type": "string",
"const": "bicycle",
"description": "Bicycle costing; tune it with a `bicycle` options object."
},
{
"type": "string",
"const": "pedestrian",
"description": "Pedestrian (walking) costing; tune it with a `pedestrian` options\nobject (lit streets, wheelchair/blind, hiking difficulty)."
},
{
"type": "string",
"const": "motor_scooter",
"description": "Motor scooter (moped) costing: like auto but prefers lower-speed\nroads and may use ways closed to larger motor vehicles."
}
],
"description": "Costing models exposed by the MCP tools (a deliberate subset of the\nValhalla costing list), serialised in snake_case exactly as Valhalla\nnames them."
},
"ReloadsSpec": {
"type": "object",
"required": [
"max_trips"
],
"properties": {
"depot": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "Where the vehicle reloads. Omitted, its own `start` is used (or its\n`end` if it declared only that)."
},
"max_trips": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "How many trips this vehicle may run in its shift, 2–5. A BUDGET,\nnot a prediction: the shift is cut into that many fixed windows\nbefore the solve, so asking for five trips on a shift that supports\nthree shrinks every window to a fifth and can make the whole day\nworse. Ask for the number of trips you actually expect to run."
},
"reload_time_s": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Seconds at the depot between trips, tipping, reloading, the\nweighbridge. Held out of the shift before it is partitioned, so it\nis never accidentally spent driving."
}
},
"description": "A vehicle's multi-trip reload plan.",
"additionalProperties": false
},
"EmissionsFuel": {
"oneOf": [
{
"type": "string",
"const": "petrol",
"description": "Petrol, including petrol hybrids (schemes rate a hybrid by its\ncombustion engine's approval)."
},
{
"type": "string",
"const": "diesel",
"description": "Diesel, including diesel hybrids."
},
{
"type": "string",
"const": "electric",
"description": "Battery-electric."
},
{
"type": "string",
"const": "hydrogen",
"description": "Hydrogen fuel cell."
},
{
"type": "string",
"const": "gas",
"description": "LPG or CNG; rated as petrol by every scheme in the dataset."
}
],
"description": "What a vehicle burns, in clean-air-zone scheme terms."
},
"EmissionsSpec": {
"type": "object",
"required": [
"vehicle_category",
"fuel"
],
"properties": {
"fuel": {
"$ref": "#/$defs/EmissionsFuel",
"description": "What it burns."
},
"euro_standard": {
"type": [
"integer",
"null"
],
"format": "uint8",
"maximum": 255,
"minimum": 0,
"description": "Its Euro emission standard, 1–6. Heavy-duty approvals are written\nin Roman numerals (Euro VI); declare Euro VI as `6`. Required for\nany combustion fuel, without it no zone can be resolved, and a\nhalf-declared vehicle is indistinguishable from an undeclared one.\nOptional only for `electric` or `hydrogen`."
},
"vehicle_category": {
"$ref": "#/$defs/EmissionsVehicleCategory",
"description": "What kind of vehicle this is, in scheme terms."
}
},
"description": "A vehicle's emission declaration, for clean-air / low-emission zone\nassessment."
},
"TerritorySpec": {
"type": "object",
"required": [
"id",
"polygon"
],
"properties": {
"id": {
"type": "string",
"description": "Caller-chosen id, echoed back and referenced by\n`vehicles[].territory_ids`. Must be unique within the request."
},
"polygon": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2
},
"description": "The outer ring as GeoJSON `[lon, lat]` positions, longitude\nFIRST. Closed or open; an unclosed ring is closed for you."
}
},
"description": "One named territory: a polygon that bounds which vehicle may serve\nwhich stop.",
"additionalProperties": false
},
"OptimiseJobSpec": {
"type": "object",
"required": [
"id",
"location"
],
"properties": {
"id": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "Caller-chosen job id, echoed back in steps and `unassigned`."
},
"pickup": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "int64"
},
"description": "Quantities picked up at the job (matches vehicle `capacity`)."
},
"skills": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "uint32",
"minimum": 0
},
"description": "Skills the job requires."
},
"delivery": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "int64"
},
"description": "Quantities delivered to the job (matches vehicle `capacity`)."
},
"location": {
"$ref": "#/$defs/LatLon",
"description": "Job location."
},
"service_s": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "On-site service time in seconds."
},
"time_windows": {
"type": [
"array",
"null"
],
"items": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"description": "Acceptable `[start, end]` windows in seconds."
}
},
"description": "One single-stop job of an optimisation problem.",
"additionalProperties": false
},
"ReplanChangesSpec": {
"type": "object",
"properties": {
"add_jobs": {
"type": "array",
"items": {
"$ref": "#/$defs/OptimiseJobSpec"
},
"description": "New single-stop jobs, in exactly the `optimise_routes` job shape."
},
"add_shipments": {
"type": "array",
"items": {
"$ref": "#/$defs/OptimiseShipmentSpec"
},
"description": "New pickup+delivery pairs, in exactly the `optimise_routes`\nshipment shape."
},
"cancel_job_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"description": "Ids of jobs that no longer need doing. A job already reported\ncompleted cannot be cancelled; the response says so rather than\nsilently dropping it."
}
},
"description": "What has changed about the work since the plan was made.",
"additionalProperties": false
},
"ReplanProgressSpec": {
"type": "object",
"required": [
"vehicle"
],
"properties": {
"vehicle": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "The vehicle this progress belongs to, an `id` from `vehicles`."
},
"unavailable": {
"type": [
"boolean",
"null"
],
"description": "The vehicle has dropped out of the shift, breakdown, illness, end\nof hours. It leaves the fleet for the re-plan; what it already\ncompleted stays completed."
},
"current_position": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "Where the vehicle is now; becomes its start for the re-plan.\nOmitted, its last completed stop is used; with neither, its\noriginal start."
},
"completed_stop_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"description": "Ids of the stops this vehicle has already served, IN THE ORDER IT\nSERVED THEM. Each is a job id or a shipment pickup/delivery id.\nThis is the locked prefix: it already happened, so no re-plan may\nmove it."
}
},
"description": "One vehicle's progress through its shift.",
"additionalProperties": false
},
"OptimiseVehicleSpec": {
"type": "object",
"required": [
"id"
],
"properties": {
"id": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "Caller-chosen vehicle id, echoed back on its route."
},
"end": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "End location; omitted, the route ends at its last stop."
},
"start": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "Start location; at least one of `start`/`end` is required."
},
"skills": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "uint32",
"minimum": 0
},
"description": "Skills this vehicle provides."
},
"reloads": {
"anyOf": [
{
"$ref": "#/$defs/ReloadsSpec"
},
{
"type": "null"
}
],
"description": "Let this vehicle return to a depot, reload and go out again, the\nwaste-collection tipping round, the van that comes back for a\nsecond wave of parcels."
},
"capacity": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "int64"
},
"description": "Multidimensional capacity (same length as job `delivery`/`pickup`)."
},
"time_window": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "int64"
},
"description": "Working window as `[start, end]` in seconds (any consistent epoch)."
},
"territory_ids": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "Ids of the request's `territories` this vehicle may work in.\nOmitted or empty, the vehicle is UNRESTRICTED and may serve any\ntask, inside a territory or outside every one of them. Listed, the\nvehicle may serve a task only if that task sits inside at least one\nof the named territories."
}
},
"description": "One vehicle of an optimisation fleet.",
"additionalProperties": false
},
"OptimiseShipmentSpec": {
"type": "object",
"required": [
"pickup",
"delivery"
],
"properties": {
"amount": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "int64"
},
"description": "Quantities moved (matches vehicle `capacity`)."
},
"pickup": {
"$ref": "#/$defs/OptimiseShipmentStopSpec",
"description": "The pickup end."
},
"skills": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "uint32",
"minimum": 0
},
"description": "Skills the shipment requires."
},
"delivery": {
"$ref": "#/$defs/OptimiseShipmentStopSpec",
"description": "The delivery end."
}
},
"description": "A pickup+delivery pair that must ride the same vehicle, pickup first.",
"additionalProperties": false
},
"EmissionsVehicleCategory": {
"oneOf": [
{
"type": "string",
"const": "car",
"description": "A private car."
},
{
"type": "string",
"const": "van",
"description": "A van or light goods vehicle up to 3.5 tonnes."
},
{
"type": "string",
"const": "minibus",
"description": "A minibus (typically 8+ passenger seats, up to 5 tonnes)."
},
{
"type": "string",
"const": "hgv",
"description": "A heavy goods vehicle over 3.5 tonnes."
},
{
"type": "string",
"const": "bus",
"description": "A bus over 5 tonnes."
},
{
"type": "string",
"const": "coach",
"description": "A coach over 5 tonnes."
},
{
"type": "string",
"const": "taxi",
"description": "A licensed hackney carriage."
},
{
"type": "string",
"const": "phv",
"description": "A private hire vehicle."
},
{
"type": "string",
"const": "motorcycle",
"description": "A motorcycle, moped or tricycle."
},
{
"type": "string",
"const": "motorhome",
"description": "A motor caravan or campervan."
}
],
"description": "What a vehicle is, in clean-air-zone scheme terms.\n\nDeclaring this turns \"charge depends on vehicle emissions\" into an\nanswer. Without it a zone can only be named, never priced."
},
"OptimiseShipmentStopSpec": {
"type": "object",
"required": [
"id",
"location"
],
"properties": {
"id": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "Caller-chosen stop id, echoed back in steps and `unassigned`."
},
"location": {
"$ref": "#/$defs/LatLon",
"description": "Stop location."
},
"service_s": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "On-site service time in seconds."
}
},
"description": "One end (pickup or delivery) of a shipment.",
"additionalProperties": false
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"vehicles"
],
"properties": {
"jobs": {
"type": "array",
"items": {
"$ref": "#/$defs/OptimiseJobSpec"
},
"description": "Single-stop jobs (at least one job or shipment overall)."
},
"truck": {
"anyOf": [
{
"$ref": "#/$defs/TruckSpec"
},
{
"type": "null"
}
],
"description": "Truck profile (dimensions + ADR declaration). Requires costing\n\"truck\"; the travel-time matrix then respects dimensional and\ndangerous-goods restrictions, so the whole plan is truck-legal."
},
"changes": {
"anyOf": [
{
"$ref": "#/$defs/ReplanChangesSpec"
},
{
"type": "null"
}
],
"description": "Changes to the work itself. Optional, on the same condition."
},
"costing": {
"$ref": "#/$defs/CostingKind",
"default": "auto",
"description": "Costing model for the travel-time matrix: \"auto\" (default),\n\"truck\", \"bicycle\", \"pedestrian\" or \"motor_scooter\"."
},
"progress": {
"type": "array",
"items": {
"$ref": "#/$defs/ReplanProgressSpec"
},
"description": "Per-vehicle progress. Optional, but at least one progress entry or\none change is required, a re-plan that reports nothing new is the\noriginal problem."
},
"vehicles": {
"type": "array",
"items": {
"$ref": "#/$defs/OptimiseVehicleSpec"
},
"description": "The fleet (at least one vehicle, each with a start and/or end)."
},
"emissions": {
"anyOf": [
{
"$ref": "#/$defs/EmissionsSpec"
},
{
"type": "null"
}
],
"description": "The fleet's emission declaration, for UK clean-air / low-emission\nzone assessment. On its own it annotates: the response's `zones`\nblock names every zone containing one of the problem's own\nlocations and what this vehicle would pay there. With\n`avoid_zones` it also steers the internal travel-time matrix away\nfrom those zones, so the plan itself changes."
},
"shipments": {
"type": "array",
"items": {
"$ref": "#/$defs/OptimiseShipmentSpec"
},
"description": "Pickup+delivery pairs."
},
"avoid_zones": {
"type": [
"boolean",
"null"
],
"description": "Keep the optimisation's travel-time matrix out of every zone the\ndeclared vehicle would be charged or banned in. Requires\n`emissions`."
},
"territories": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/TerritorySpec"
},
"description": "Fleet territories: named polygons that bound which vehicle may\nserve which stop, referenced by `vehicles[].territory_ids`. These\nare request data, caller-drawn rounds, validated per call and\nnever stored. Nothing to do with clean-air zones or with the\noffline map packages of the same word."
},
"relax_if_unassigned": {
"anyOf": [
{
"$ref": "#/$defs/RelaxSpec"
},
{
"type": "null"
}
],
"description": "Re-solve ONCE with these relaxations if the first solve leaves work\nunassigned, and say honestly which plan came back. At most one\nsecond solve, never beyond the caps you state, and the relaxed plan\nis returned only if it assigns MORE work than the first, giving\naway constraints for nothing is strictly worse than not giving them\naway. Capacities, skills and territories are never relaxed: only\ntime windows move, and only by the stated amounts. Bills as two\nsolves when the second one runs."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"OptimisedStep": {
"type": "object",
"required": [
"type",
"arrival_s",
"duration_s",
"service_s",
"waiting_time_s"
],
"properties": {
"id": {
"type": [
"integer",
"null"
],
"format": "uint64",
"minimum": 0,
"description": "The job/shipment-stop id, absent on start/end steps."
},
"load": {
"type": [
"array",
"null"
],
"items": {
"type": "integer",
"format": "int64"
},
"description": "Vehicle load after the step, when reported."
},
"type": {
"type": "string",
"description": "Step kind: \"start\", \"job\", \"pickup\", \"delivery\", \"break\" or \"end\"."
},
"location": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "The step's location resolved back to coordinates."
},
"arrival_s": {
"type": "integer",
"format": "int64",
"description": "Arrival time in seconds (same epoch as the request's windows)."
},
"service_s": {
"type": "integer",
"format": "int64",
"description": "On-site service time in seconds."
},
"duration_s": {
"type": "integer",
"format": "int64",
"description": "Cumulative travel time when the step begins, in seconds."
},
"waiting_time_s": {
"type": "integer",
"format": "int64",
"description": "Waiting time before the step in seconds."
}
},
"description": "One step of an optimised vehicle route."
},
"OptimisedRoute": {
"type": "object",
"required": [
"vehicle",
"duration_s",
"service_s",
"waiting_time_s",
"steps"
],
"properties": {
"steps": {
"type": "array",
"items": {
"$ref": "#/$defs/OptimisedStep"
},
"description": "Ordered steps: start, tasks in visit order, end."
},
"vehicle": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "The vehicle id from the request."
},
"service_s": {
"type": "integer",
"format": "int64",
"description": "Total on-site service time in seconds."
},
"distance_m": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Total travel distance in metres, when reported."
},
"duration_s": {
"type": "integer",
"format": "int64",
"description": "Total travel time in seconds."
},
"waiting_time_s": {
"type": "integer",
"format": "int64",
"description": "Total waiting time in seconds."
}
},
"description": "One vehicle's optimised route."
},
"UnassignedTask": {
"type": "object",
"required": [
"id",
"type"
],
"properties": {
"id": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "The task id from the request."
},
"type": {
"type": "string",
"description": "Task kind: \"job\", \"pickup\" or \"delivery\"."
},
"location": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "The task's location, when known."
}
},
"description": "One unassigned task of an optimisation solution."
},
"OptimiseSummary": {
"type": "object",
"required": [
"cost",
"routes",
"unassigned",
"duration_s",
"service_s",
"waiting_time_s"
],
"properties": {
"cost": {
"type": "integer",
"format": "int64",
"description": "Solver cost of the plan (travel seconds under the default model)."
},
"routes": {
"type": "integer",
"format": "int64",
"description": "Number of vehicle routes in the plan."
},
"service_s": {
"type": "integer",
"format": "int64",
"description": "Total service time in seconds."
},
"distance_m": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Total travel distance in metres, when reported."
},
"duration_s": {
"type": "integer",
"format": "int64",
"description": "Total travel time in seconds."
},
"unassigned": {
"type": "integer",
"format": "int64",
"description": "Number of unassigned tasks."
},
"waiting_time_s": {
"type": "integer",
"format": "int64",
"description": "Total waiting time in seconds."
}
},
"description": "Solution summary of the `optimise_routes` tool."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"profile",
"summary",
"unassigned",
"routes",
"replan"
],
"properties": {
"zones": {
"description": "Clean-air / low-emission zones touching the problem's own\nlocations, and what the declared vehicle pays in each. Present only\nwhen `emissions` was declared."
},
"replan": {
"description": "What the re-plan locked and why: the prefix held per vehicle, where\neach vehicle re-plans from and how that was decided, stops released\nfrom a vehicle that could no longer serve them, tasks forced\nunassigned, and a note for every id that did not resolve.\n\nRead it. A stop that vanished from the plan is named here rather\nthan left for the dispatcher to notice at four in the afternoon."
},
"routes": {
"type": "array",
"items": {
"$ref": "#/$defs/OptimisedRoute"
},
"description": "One optimised route per used vehicle."
},
"profile": {
"type": "string",
"description": "The matrix costing profile the plan was computed with (\"auto\",\n\"truck\", \"bicycle\", \"pedestrian\" or \"motor_scooter\")."
},
"reloads": {
"description": "The multi-trip split: each vehicle's trips, their windows, the\ndepot each returns to, and the stated approximation. Present only\nwhen a vehicle declared `reloads`.\n\nRead the `basis` inside it before quoting arrival times. The trip\nwindows are fixed BEFORE the solve, so a lorry that tips early\ncannot lend the spare time to its next trip: stops can come back\nunassigned that a truly sequential model would have served. The\nplan is feasible, never optimistic, it cannot put a vehicle in two\nplaces at once, but it is not optimal. Re-plan after each tip\nthrough `replan_routes` for the tighter answer."
},
"summary": {
"$ref": "#/$defs/OptimiseSummary",
"description": "Solution summary."
},
"view_url": {
"type": [
"string",
"null"
],
"description": "A mapmap.ai link that draws this fleet plan, one route per vehicle, on a map: open it or pass it\non as the last line of the answer. Nothing is stored server-side and\nopening it needs no key; the link itself carries the stop coordinates\nand stop names (plus any arrival clocks, dwell times and totals) and\nnothing else, so anyone holding it can read those stops. Absent when\nthe plan cannot be linked (see `view_url_note`) or the server runs\nwith links turned off (`SN_MCP_SITE_URL` empty)."
},
"relaxation": {
"description": "The relaxation report: the caps requested, whether a second solve\nran, whether ITS plan is the one returned, what was widened, and\nwhat is still unassigned. Present only when `relax_if_unassigned`\nwas declared.\n\nAlways read `second_solve` and `relaxed_plan_used` before telling\nanyone the day fits. A plan produced under relaxation has had\npromises moved, and the block is what says so."
},
"unassigned": {
"type": "array",
"items": {
"$ref": "#/$defs/UnassignedTask"
},
"description": "Tasks the solver could not assign to any vehicle."
},
"territories": {
"description": "How the territories bound the plan: which vehicle was eligible for\nwhat, and any task no eligible vehicle existed for. Present only\nwhen `territories` was declared."
},
"view_url_note": {
"type": [
"string",
"null"
],
"description": "Why there is no `view_url` (too many vehicles or stops for one link,\nor over the 6,000 character cap), or what the link left out to fit\nunder the cap (arrival times, dwell times, then stop names). Relay it\nwith the link."
}
}
}
}{
"name": "reverse_geocode",
"description": "Turn coordinates into the nearest places: addresses, POIs and localities with distance in metres. The inverse of geocode. Provide `lat` and `lon`; returns up to `limit` (default 5, max 10) results, nearest first, each with name, one-line label, lat/lon, type, address parts and distance_m, plus categories and a `details` object of display tags (opening_hours, website, phone, wikipedia, ...) on POI hits when the index carries them. Every result also carries `bearing_deg` and a spoken `direction`. Pass `heading_deg` (degrees clockwise from true north, 0 = north, 90 = east) and results are described from where the user stands, \"ahead and slightly to your right, about 80 metres\", with a signed `relative_bearing_deg` (negative left, positive right); without a heading the phrasing falls back to cardinals (\"to the north-east\"), so this works with or without a compass. Add `fov_deg` to keep only what lies within that cone of the heading, it is the FULL width, so 90 keeps what lies within 45 degrees either side of dead ahead; anything dropped is counted in `out_of_view`. Prefer reading `direction` aloud over coordinates.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
},
"limit": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Maximum number of results (1–10, default 5)."
},
"fov_deg": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Field of view: the full width in degrees of a cone centred on\n`heading_deg`, outside which results are dropped, it is the\nFULL width, so 90 keeps only what lies within 45 degrees either\nside of dead ahead. Needs\n`heading_deg`, a cone has to point somewhere. The count of\nresults removed is reported as `out_of_view`."
},
"heading_deg": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Which way the user is facing, in degrees **clockwise from true\nnorth** (0 = north, 90 = east, 180 = south, 270 = west). Supply it\nand every result is also described from the user's point of view\n(\"just ahead on your right\"); omit it and results fall back to\ncardinal directions (\"to the north-east\"), so the tool works with\nor without a compass."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"ReverseGeocodeHit": {
"type": "object",
"required": [
"label",
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude of the place in decimal degrees."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude of the place in decimal degrees."
},
"city": {
"type": [
"string",
"null"
],
"description": "City or town, when known."
},
"name": {
"type": [
"string",
"null"
],
"description": "Place name, when the source feature has one."
},
"type": {
"type": [
"string",
"null"
],
"description": "Feature type, e.g. \"address\", \"street\", \"poi\", \"locality\"."
},
"label": {
"type": "string",
"description": "Human-readable one-line label assembled from the address parts."
},
"country": {
"type": [
"string",
"null"
],
"description": "Country, when known: a country name, or the ISO 3166-1 alpha-2\ncode (e.g. \"GB\") on first-party hits, which carry only the code."
},
"details": {
"description": "Whitelisted OSM display tags on POI hits (opening_hours, website,\nphone, brand, cuisine, wheelchair, wikipedia, ...), passed through\nverbatim when present."
},
"postcode": {
"type": [
"string",
"null"
],
"description": "Postcode, when known."
},
"direction": {
"type": [
"string",
"null"
],
"description": "The direction phrased for speech, \"ahead and slightly to your\nright, about 80 metres\" with a heading, \"to the north-east, about\n80 metres\" without one. Deliver this verbatim rather than reading\nout coordinates."
},
"categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "POI categories (e.g. [\"cafe\"]), when the index carries them."
},
"distance_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Straight-line distance from the queried point in metres, when the\nbackend reports one (first-party gateway hits always do)."
},
"bearing_deg": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Bearing from the queried point to this place, degrees clockwise\nfrom true north. Always present."
},
"relative_bearing_deg": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Where this place is relative to the way the user is facing:\nnegative to the left, positive to the right, −180 to 180. Present\nonly when the request supplied `heading_deg`."
}
},
"description": "One reverse-geocoding result: a place near the queried point. The same\nshape family as [`GeocodeHit`], plus the reverse-only extras\n(`distance_m`, `categories`, `details`) and the egocentric extras\n(`bearing_deg`, `relative_bearing_deg`, `direction`)."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"results"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/$defs/ReverseGeocodeHit"
},
"description": "Nearby places, nearest first."
},
"out_of_view": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "How many otherwise-matching places were dropped for falling\noutside `fov_deg`. Non-zero means there are places near the user\nthat are simply not in front of them, say so rather than\nreporting nothing nearby. Always 0 when no field of view was set."
}
}
}
}| Parameter | Type | Description |
|---|---|---|
| avoid | ["array","null"] | Road features to avoid as a PREFERENCE. Rendered as the costing's willingness factor set to zero, a thumb on the scale, not a ban. The engine's own reference is explicit that a value of zero is not guaranteed to avoid the feature entirely, and it does not: asking to avoid tolls across the Dartford C… |
| truck | any | Truck profile (dimensions + ADR declaration). Requires costing "truck"; when present, ADR dangerous-goods costing options are merged into the request. |
| origin * | ref | Route origin. |
| scenic | ["boolean","null"] | Ask whether there is a prettier way (default false, `auto` costing only). The route in `geometry_polyline6` is NEVER swapped: what comes back is a peer offer beside it, in `scenic`, carrying the plain sentence that justifies it. No sentence, no offer: a route that scores well but cannot support one … |
| bicycle | any | Bicycle options (bicycle type, road/surface/hill preferences). Requires costing "bicycle". |
| costing | ref | Costing model: "auto" (default), "truck", "bicycle", "pedestrian" or "motor_scooter". |
| exclude | ["array","null"] | Road features to exclude outright, rendered as the costing's hard exclusion flag. Two things follow from that and both matter: a hard exclusion can return NO ROUTE rather than a detour (excluding tunnels on a Rotherhithe crossing has no answer), and the flags depend on the routing engine's `allow_ha… |
| emissions | any | The vehicle's emission declaration, for UK clean-air / low-emission zone assessment. Given, the response's `zones` block names every zone the route enters and what THIS vehicle pays there, with the publishing authority cited. Without it a zone can only be named, never priced. Needs the MapMap gatewa… |
| landmarks | ["boolean","null"] | Name landmarks in the turn instructions (default false): each manoeuvre that passes a recognisable place, a petrol station, a supermarket, a household-name chain, gains a `landmark_instruction` like "Turn right just after the Shell garage" beside the engine's own street-name instruction, which is ne… |
| rationale | ["boolean","null"] | Explain the route (default false): re-routes with each declared truck constraint (truck costing) or avoidance-side routing preference (auto, bicycle, pedestrian, motor_scooter) relaxed and reports the ones that actually changed the route as `rationale.avoided[]`. Opt-in, it costs up to 1 + N extra r… |
| waypoints | ["array","null"] | Optional intermediate stops, visited in order between origin and destination. |
| pedestrian | any | Pedestrian options (lit-street preference, wheelchair/blind type, hiking difficulty). Requires costing "pedestrian". |
| destination * | ref | Route destination. |
| exclude_polygons | ["array","null"] | Areas to avoid, scenario analysis ("close this bridge and re-route"): an array of polygons, each an array of `[lon, lat]` pairs forming one exterior ring (GeoJSON-style, longitude FIRST). Roads intersecting any ring are excluded from the search. When no route avoids them the answer is "no path": the… |
{
"name": "route",
"description": "Compute a turn-by-turn route between origin and destination (optionally via waypoints). Costing \"auto\" = car, \"truck\" = lorry, \"bicycle\", \"pedestrian\" = walking, \"motor_scooter\" = moped. Pass `truck` {height_m, width_m, length_m, gross_weight_t, hazmat, tunnel_code} to apply dimensional limits and the ADR dangerous-goods tunnel matrix to the search; `pedestrian` {use_lit 0-1, type \"wheelchair\"|\"blind\", max_hiking_difficulty 1-6, use_hills 0-1, max_grade_pct 1-90, surface_quality \"avoid\"|\"ignore\"} for lit-street walking, wheelchair routing and trail limits. A wheelchair route through the MapMap gateway returns a `grade` block (maximum grade, ascent and descent sampled from a 30 m elevation model, the `use_hills` preference sent, and `cap.enforced` for a `max_grade_pct`, which the engine accepts but does not enforce yet: say so) and, where the deployment has a surface graph, a `surface_quality` block: `applied: true` means ways rated smoothness bad or worse in OpenStreetMap were avoided in the named region, a preference from ratings where they exist that says nothing about kerbs, widths, steps or inclines; `applied: false` gives the `reason`. Relay both caveats and never describe such a route as suitable for every user; `bicycle` {bicycle_type, use_roads 0-1, use_living_streets 0-1, avoid_bad_surfaces 0-1, use_hills 0-1} for quiet-ride and surface preferences. Returns distance (m), duration (s), maneuvers, polyline6 geometry and the ADR costing that was applied. Any of truck, auto, bicycle, pedestrian or motor_scooter routes may set `rationale: true` (opt-in, costs up to 1 + N extra routing calls) to learn which declared truck constraints or avoidance-side preferences (hills, surfaces, tolls, unlit streets, …) actually changed the route (`rationale.avoided[]`, basis route_divergence, it proves a field was binding, it does not identify the physical restriction or feature, and no live traffic or incident data is ever attributed). ADR honesty: `applied_adr.forbidden_tunnel_categories` describes the LOAD, not the returned route, and `applied_adr.tunnel_enforcement` states the boundary: roads are excluded only where the routing graph records an ADR tunnel category, so an unchanged route is not a clearance. Set `landmarks: true` for turn instructions anchored to recognisable places, each manoeuvre that passes one gains a `landmark_instruction` like \"Turn right just after the Shell garage\" beside the engine's own street-name `instruction`, which is never replaced. Prefer reading it aloud: it is how a passenger gives directions. Nothing is named unless it is recognisable from the road, within 40 m of the junction and not tagged as closed, so many routes return none and a `landmarks.annotated` of 0 with no `note` means this route genuinely passes nothing recognisable. Needs the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY), whose place index does the lookup. Through the gateway each manoeuvre also carries the road it starts on: `country`, `subdivision`, `ref` (route numbers only), `road_class`, `speed_limit_unit` (`mph` or `km/h`, from the road's country), `speed_limit_sign` (`vienna` or `mutcd`), `speed_limit_posted` (the limit as the sign shows it, in the road's unit) and `driving_side`; each is absent when the map does not know it, never guessed. Optional `exclude_polygons` for what-if scenarios (\"close this bridge and re-route\"): an array of polygons, each an array of [lon, lat] pairs forming one ring (longitude FIRST) whose intersecting roads are excluded from the search. Applies to the Valhalla engine; unsupported on the GraphHopper engine, where it is ignored. Optional `avoid` and `exclude` name road features to keep off, and the difference between them is not cosmetic. `avoid` (\"tolls\", \"highways\", \"ferries\") is a PREFERENCE: it sets the costing's willingness to zero, and the engine's own reference says that is not guaranteed to avoid the feature, measured, avoiding tolls across the Dartford Crossing returns the same tolled rout",
"inputSchema": {
"type": "object",
"$defs": {
"TruckSpec": {
"type": "object",
"properties": {
"hazmat": {
"type": "boolean",
"default": false,
"description": "Whether the vehicle carries dangerous goods (ADR). Defaults to\nfalse."
},
"width_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle width in metres."
},
"height_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle height in metres."
},
"length_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle length in metres."
},
"tunnel_code": {
"type": [
"string",
"null"
],
"description": "ADR 8.6.4 tunnel restriction code of the load, e.g. \"B\", \"C5000D\",\n\"B/D\", or \"(-)\"/\"none\" for explicitly unrestricted. Leave unset if\nunknown: a hazmat load without a code is conservatively treated as\ncode B (allowed only through category-A tunnels)."
},
"gross_weight_t": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Gross combination weight in metric tonnes."
}
},
"description": "Truck profile for routing: physical dimensions plus the ADR\ndangerous-goods declaration. Omitted dimensions default to the EU\nmaximum authorised dimensions of Council Directive 96/53/EC (4.0 m\nheight, 2.55 m width, 16.5 m length, 40 t gross weight)."
},
"BicycleSpec": {
"type": "object",
"properties": {
"use_hills": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Willingness to take hills, 0.0–1.0 (0.0 = avoid climbs even at the\ncost of longer routes)."
},
"use_roads": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Willingness to ride roads alongside motor traffic, 0.0–1.0\n(0.0 = prefer cycleways and quiet streets, the quiet-ride slider)."
},
"bicycle_type": {
"type": [
"string",
"null"
],
"description": "Bicycle type: \"road\", \"hybrid\" (default), \"city\", \"cross\" or\n\"mountain\". Sets default speed and surface tolerance."
},
"avoid_bad_surfaces": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Avoidance of surfaces unsuited to the bicycle type, 0.0–1.0\n(1.0 = strictly avoid bad surfaces)."
},
"use_living_streets": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Preference for living/shared streets, 0.0–1.0."
}
},
"description": "Bicycle options for costing \"bicycle\": the bicycle type plus road,\nsurface and hill preference weights, mapped onto Valhalla\n`costing_options.bicycle`."
},
"CostingKind": {
"oneOf": [
{
"type": "string",
"const": "auto",
"description": "Standard car costing."
},
{
"type": "string",
"const": "truck",
"description": "Truck costing; honours dimensional limits and, when a `truck`\nprofile is supplied, ADR dangerous-goods restrictions."
},
{
"type": "string",
"const": "bicycle",
"description": "Bicycle costing; tune it with a `bicycle` options object."
},
{
"type": "string",
"const": "pedestrian",
"description": "Pedestrian (walking) costing; tune it with a `pedestrian` options\nobject (lit streets, wheelchair/blind, hiking difficulty)."
},
{
"type": "string",
"const": "motor_scooter",
"description": "Motor scooter (moped) costing: like auto but prefers lower-speed\nroads and may use ways closed to larger motor vehicles."
}
],
"description": "Costing models exposed by the MCP tools (a deliberate subset of the\nValhalla costing list), serialised in snake_case exactly as Valhalla\nnames them."
},
"AvoidFeature": {
"enum": [
"tolls",
"highways",
"ferries"
],
"type": "string",
"description": "A road feature to avoid as a PREFERENCE, not a ban. \"tolls\" and \"highways\" apply to motorised costings only (auto, truck, bus, motor_scooter, motorcycle); \"ferries\" applies to every costing. Asking for one on a costing whose engine table has no field for it is refused rather than silently ignored."
},
"EmissionsFuel": {
"oneOf": [
{
"type": "string",
"const": "petrol",
"description": "Petrol, including petrol hybrids (schemes rate a hybrid by its\ncombustion engine's approval)."
},
{
"type": "string",
"const": "diesel",
"description": "Diesel, including diesel hybrids."
},
{
"type": "string",
"const": "electric",
"description": "Battery-electric."
},
{
"type": "string",
"const": "hydrogen",
"description": "Hydrogen fuel cell."
},
{
"type": "string",
"const": "gas",
"description": "LPG or CNG; rated as petrol by every scheme in the dataset."
}
],
"description": "What a vehicle burns, in clean-air-zone scheme terms."
},
"EmissionsSpec": {
"type": "object",
"required": [
"vehicle_category",
"fuel"
],
"properties": {
"fuel": {
"$ref": "#/$defs/EmissionsFuel",
"description": "What it burns."
},
"euro_standard": {
"type": [
"integer",
"null"
],
"format": "uint8",
"maximum": 255,
"minimum": 0,
"description": "Its Euro emission standard, 1–6. Heavy-duty approvals are written\nin Roman numerals (Euro VI); declare Euro VI as `6`. Required for\nany combustion fuel, without it no zone can be resolved, and a\nhalf-declared vehicle is indistinguishable from an undeclared one.\nOptional only for `electric` or `hydrogen`."
},
"vehicle_category": {
"$ref": "#/$defs/EmissionsVehicleCategory",
"description": "What kind of vehicle this is, in scheme terms."
}
},
"description": "A vehicle's emission declaration, for clean-air / low-emission zone\nassessment."
},
"RouteLocation": {
"type": "object",
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"properties": {
"preferred_side": {
"anyOf": [
{
"$ref": "#/$defs/PreferredSideKind"
},
{
"type": "null"
}
],
"description": "Which side of the street to arrive on (or depart from). `same` (or\n`curb`) puts the vehicle on the door's side of the road, resolved\nagainst the locale's driving side. Two honest limits: this is a\n**snapping preference**, not a manoeuvre guarantee, the engine\nprefers an edge on that side, it does not promise the driver never\ncrosses, and it needs a coordinate genuinely offset from the road\ncentreline, because a point on the centreline has no side."
},
"street_side_tolerance_m": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Metres: nearer than this to the road centreline, the side of street\nis treated as `none` and `preferred_side` does nothing. Engine\ndefault 5 m."
},
"street_side_max_distance_m": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Metres: further than this from the road centreline, the side of\nstreet is treated as `none` and `preferred_side` does nothing.\nEngine default 1000 m. Together with `street_side_tolerance_m` this\nis a WINDOW: a pair that leaves no window (tolerance at or above\nmax distance) is refused here rather than answered with a route on\nwhich the kerbside preference was silently inert."
}
},
"description": "One location of a `route` request: a coordinate, plus the optional\nkerbside approach for arriving at it.\n\nA bare `{lat, lon}` is still a complete location, every kerbside field\nis optional and omitting all of them is exactly the request that was\nmade before they existed."
},
"ExcludeFeature": {
"enum": [
"tolls",
"highways",
"ferries",
"bridges",
"tunnels"
],
"type": "string",
"description": "A road feature to exclude outright. A hard exclusion can leave a request with no path at all (that is the honest answer, not a failure) and it depends on the routing engine's own hard-exclusion setting, which nothing here can read."
},
"PedestrianSpec": {
"type": "object",
"properties": {
"type": {
"type": [
"string",
"null"
],
"description": "Pedestrian type: \"wheelchair\" (avoids mapped steps and kerbs and\nthe rougher surface classes; hills per `use_hills`) or \"blind\"\n(richer guidance detail). Omit for the default on-foot profile."
},
"use_lit": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Preference for lit streets, 0.0–1.0 (1.0 = prefer lit paths as\nstrongly as possible, the \"walk me home on lit streets\" option).\nUnlit ways are still used when no lit alternative exists."
},
"use_hills": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Willingness to take hills, 0.0–1.0 (0.0 = avoid climbs as strongly\nas the engine can; the engine default is 0.5). A preference, not a\ncap. The MapMap gateway sends 0.0 on a wheelchair route that does\nnot set it, and reports that in `grade.preference`."
},
"max_grade_pct": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Maximum grade in whole percent, 1–90. Needs the MapMap gateway:\nthe routing engine accepts this cap but does not enforce it yet,\nand the gateway's `grade.cap` says so on every route that sets it."
},
"surface_quality": {
"type": [
"string",
"null"
],
"description": "Surface quality for wheelchair routes: \"avoid\" (the default where\nthe deployment has a surface graph covering the route) or \"ignore\"\n(use the ordinary graph). Wheelchair only, and needs the MapMap\ngateway; the `surface_quality` block in the output says whether it\nwas applied."
},
"max_hiking_difficulty": {
"type": [
"integer",
"null"
],
"format": "uint8",
"maximum": 255,
"minimum": 0,
"description": "Maximum hiking-trail difficulty the route may use, as OSM\n`sac_scale` 1–6 (1 = well-cleared, mostly flat trails; 6 =\ndemanding alpine terrain). Default 1."
}
},
"description": "Pedestrian options for costing \"pedestrian\": lit-street preference,\npedestrian type, hills, surface quality and hiking difficulty, mapped\nonto Valhalla `costing_options.pedestrian` (surface quality and the\ngrade cap are MapMap gateway fields). All preferences, never\nguarantees: the router prefers matching ways where the map data\nsupports it."
},
"PreferredSideKind": {
"oneOf": [
{
"type": "string",
"const": "same",
"description": "The side the location itself projects to, the kerb, resolved\nagainst the locale's driving side (the left kerb in the UK, the\nright in Germany)."
},
{
"type": "string",
"const": "opposite",
"description": "The far side of the road from the location."
},
{
"type": "string",
"const": "either",
"description": "No side preference."
},
{
"type": "string",
"const": "curb",
"description": "Alias for `same`, from the OSRM/Mapbox `approaches` vocabulary."
},
{
"type": "string",
"const": "unrestricted",
"description": "Alias for `either`, from the OSRM/Mapbox `approaches` vocabulary."
}
],
"description": "Side-of-street preference for arriving at or departing from a location.\n\nCarries both vocabularies: MapMap's own `same`/`opposite`/`either` and\nthe OSRM/Mapbox `approaches` words `curb`/`unrestricted`, which are\naliases for `same` and `either`. Both spell the same request, on this\nsurface and on the HTTP API."
},
"EmissionsVehicleCategory": {
"oneOf": [
{
"type": "string",
"const": "car",
"description": "A private car."
},
{
"type": "string",
"const": "van",
"description": "A van or light goods vehicle up to 3.5 tonnes."
},
{
"type": "string",
"const": "minibus",
"description": "A minibus (typically 8+ passenger seats, up to 5 tonnes)."
},
{
"type": "string",
"const": "hgv",
"description": "A heavy goods vehicle over 3.5 tonnes."
},
{
"type": "string",
"const": "bus",
"description": "A bus over 5 tonnes."
},
{
"type": "string",
"const": "coach",
"description": "A coach over 5 tonnes."
},
{
"type": "string",
"const": "taxi",
"description": "A licensed hackney carriage."
},
{
"type": "string",
"const": "phv",
"description": "A private hire vehicle."
},
{
"type": "string",
"const": "motorcycle",
"description": "A motorcycle, moped or tricycle."
},
{
"type": "string",
"const": "motorhome",
"description": "A motor caravan or campervan."
}
],
"description": "What a vehicle is, in clean-air-zone scheme terms.\n\nDeclaring this turns \"charge depends on vehicle emissions\" into an\nanswer. Without it a zone can only be named, never priced."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"origin",
"destination"
],
"properties": {
"avoid": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/AvoidFeature"
},
"description": "Road features to avoid as a PREFERENCE. Rendered as the costing's\nwillingness factor set to zero, a thumb on the scale, not a ban.\nThe engine's own reference is explicit that a value of zero is not\nguaranteed to avoid the feature entirely, and it does not: asking\nto avoid tolls across the Dartford Crossing returns the same tolled\nroute, because the untolled alternative is fifty kilometres\nfurther. Use `exclude` when you mean a ban."
},
"truck": {
"anyOf": [
{
"$ref": "#/$defs/TruckSpec"
},
{
"type": "null"
}
],
"description": "Truck profile (dimensions + ADR declaration). Requires costing\n\"truck\"; when present, ADR dangerous-goods costing options are\nmerged into the request."
},
"origin": {
"$ref": "#/$defs/RouteLocation",
"description": "Route origin."
},
"scenic": {
"type": [
"boolean",
"null"
],
"description": "Ask whether there is a prettier way (default false, `auto`\ncosting only). The route in `geometry_polyline6` is NEVER swapped:\nwhat comes back is a peer offer beside it, in `scenic`, carrying\nthe plain sentence that justifies it. No sentence, no offer: a\nroute that scores well but cannot support one is dropped rather\nthan dressed up, and `scenic.reason` is then null, which is an\nanswer. Every candidate that lost says why in\n`scenic.rejections[]` (`same_route`, `no_scenic_gain`,\n`not_scenic_enough`, `over_time_budget`, `nothing_to_say`), so\n\"no prettier way\" is always attributable. Opt-in because it\ncosts: at most two extra metered route computations, the same\nbilling shape as `rationale`. Needs the MapMap gateway, whose\nbasemap archive the scoring is measured against."
},
"bicycle": {
"anyOf": [
{
"$ref": "#/$defs/BicycleSpec"
},
{
"type": "null"
}
],
"description": "Bicycle options (bicycle type, road/surface/hill preferences).\nRequires costing \"bicycle\"."
},
"costing": {
"$ref": "#/$defs/CostingKind",
"default": "auto",
"description": "Costing model: \"auto\" (default), \"truck\", \"bicycle\", \"pedestrian\"\nor \"motor_scooter\"."
},
"exclude": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/ExcludeFeature"
},
"description": "Road features to exclude outright, rendered as the costing's hard\nexclusion flag. Two things follow from that and both matter: a hard\nexclusion can return NO ROUTE rather than a detour (excluding\ntunnels on a Rotherhithe crossing has no answer), and the flags\ndepend on the routing engine's `allow_hard_exclusions` setting,\nwhich the engine does not expose and nothing here can read, so\nthis is never promised, only requested."
},
"emissions": {
"anyOf": [
{
"$ref": "#/$defs/EmissionsSpec"
},
{
"type": "null"
}
],
"description": "The vehicle's emission declaration, for UK clean-air / low-emission\nzone assessment. Given, the response's `zones` block names every\nzone the route enters and what THIS vehicle pays there, with the\npublishing authority cited. Without it a zone can only be named,\nnever priced. Needs the MapMap gateway, which holds the curated\nzone dataset; the full dataset is readable at `GET /v1/zones`."
},
"landmarks": {
"type": [
"boolean",
"null"
],
"description": "Name landmarks in the turn instructions (default false): each\nmanoeuvre that passes a recognisable place, a petrol station, a\nsupermarket, a household-name chain, gains a\n`landmark_instruction` like \"Turn right just after the Shell\ngarage\" beside the engine's own street-name instruction, which is\nnever replaced. Nothing is named unless it is recognisable from the\nroad, within 40 m of the junction and not tagged as closed, so many\nroutes come back with none: a wrong landmark is worse than no\nlandmark. Needs the MapMap gateway, whose place index does the\nlookup."
},
"rationale": {
"type": [
"boolean",
"null"
],
"description": "Explain the route (default false): re-routes with each declared\ntruck constraint (truck costing) or avoidance-side routing\npreference (auto, bicycle, pedestrian, motor_scooter) relaxed and\nreports the ones that actually changed the route as\n`rationale.avoided[]`. Opt-in, it costs up to 1 + N extra routing\ncalls, one per declared field plus one combined probe, and it is\nbilled for the ones it actually makes: at most 8 in total,\ntypically fewer, and 1 when there is nothing to probe. Against the\nhosted gateway each probe is its own metered route call, which is\nexactly what `POST /route` with `rationale: true` charges for its\nown fan-out, so the two surfaces price the same explanation the\nsame way."
},
"waypoints": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/RouteLocation"
},
"description": "Optional intermediate stops, visited in order between origin and\ndestination."
},
"pedestrian": {
"anyOf": [
{
"$ref": "#/$defs/PedestrianSpec"
},
{
"type": "null"
}
],
"description": "Pedestrian options (lit-street preference, wheelchair/blind type,\nhiking difficulty). Requires costing \"pedestrian\"."
},
"destination": {
"$ref": "#/$defs/RouteLocation",
"description": "Route destination."
},
"exclude_polygons": {
"type": [
"array",
"null"
],
"items": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2
}
},
"description": "Areas to avoid, scenario analysis (\"close this bridge and\nre-route\"): an array of polygons, each an array of `[lon, lat]`\npairs forming one exterior ring (GeoJSON-style, longitude FIRST).\nRoads intersecting any ring are excluded from the search. When no\nroute avoids them the answer is \"no path\": the search is never\nwidened to snap a stop onto a road beyond the area. Applies to the\nValhalla engine; unsupported on the GraphHopper engine, where it is\nignored."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"AppliedAdr": {
"type": "object",
"required": [
"hazmat",
"forbidden_tunnel_categories",
"tunnel_enforcement",
"costing_options"
],
"properties": {
"hazmat": {
"type": "boolean",
"description": "Whether the profile declared dangerous goods."
},
"tunnel_code": {
"type": [
"string",
"null"
],
"description": "Canonical ADR tunnel restriction code applied (\"B/D\", \"(-)\", …),\nor null when no code was declared."
},
"costing_options": {
"description": "The exact Valhalla `costing_options` JSON merged into the request."
},
"tunnel_enforcement": {
"$ref": "#/$defs/TunnelEnforcement",
"description": "What the router did with `forbidden_tunnel_categories`, and the\nboundary of the resulting guarantee."
},
"forbidden_tunnel_categories": {
"type": "array",
"items": {
"type": "string"
},
"description": "ADR tunnel categories **the vehicle** is forbidden from under the\nworst-case reading of ADR 8.6.4 (conditional clauses assumed to\napply). Empty when unrestricted. This is not a claim that the\nreturned route contains no tunnel of these categories, read\n[`AppliedAdr::tunnel_enforcement`] for what was actually applied."
}
},
"description": "The ADR costing that was merged into a truck route request.\n\nEvery field here describes the **request**: the declared load and the\ncosting options built from it. Nothing here is an assertion about the\nreturned geometry, see [`TunnelEnforcement`]."
},
"ManeuverOut": {
"type": "object",
"required": [
"instruction",
"distance_m",
"duration_s"
],
"properties": {
"ref": {
"type": [
"string",
"null"
],
"description": "Route numbers of that road (`\"; \"` separated, e.g. `\"A27\"` or\n`\"I 5; US 101\"`); absent when it carries none, never read from a\nstreet name."
},
"country": {
"type": [
"string",
"null"
],
"description": "ISO 3166-1 alpha-2 country of the road the manoeuvre starts on, e.g.\n`\"GB\"`. This and the road fields below come from the MapMap gateway's\nroad walk: present when the route was computed through the gateway\n(GATEWAY_URL + GATEWAY_API_KEY) and the map knows the road, absent\notherwise. Never inferred."
},
"distance_m": {
"type": "number",
"format": "double",
"description": "Length of the maneuver in metres."
},
"duration_s": {
"type": "number",
"format": "double",
"description": "Estimated duration of the maneuver in seconds."
},
"road_class": {
"type": [
"string",
"null"
],
"description": "Engine road class of that road (`motorway`, `trunk`, `primary`,\n`secondary`, `tertiary`, `unclassified`, `residential`,\n`service_other`)."
},
"instruction": {
"type": "string",
"description": "Written instruction, e.g. \"Turn right onto Main Street\"."
},
"subdivision": {
"type": [
"string",
"null"
],
"description": "ISO 3166-2 subdivision of that road where the map carries one, e.g.\n`\"GB-ENG\"` or `\"US-CA\"`."
},
"driving_side": {
"type": [
"string",
"null"
],
"description": "The side of the road traffic keeps to there, `\"left\"` or `\"right\"`;\npresent only when the road's country is known."
},
"speed_limit_sign": {
"type": [
"string",
"null"
],
"description": "The speed-limit sign family there: `\"vienna\"` (roundel) or\n`\"mutcd\"` (US and Canadian rectangle)."
},
"speed_limit_unit": {
"type": [
"string",
"null"
],
"description": "The unit speed limits are posted in on that road, `\"mph\"` or\n`\"km/h\"`, from its country (never from the request's units)."
},
"speed_limit_posted": {
"description": "The posted limit as the sign shows it, in the road's own unit:\n`{\"type\":\"known\",\"value\":30,\"unit\":\"mph\"}` (plus `\"national\":true`\nfor a national limit), `{\"type\":\"unlimited\"}` or `{\"type\":\"unknown\"}`.\nRead from the road the manoeuvre mostly travels along."
},
"landmark_instruction": {
"type": [
"string",
"null"
],
"description": "The same manoeuvre anchored to a recognisable place, e.g. \"Turn\nright just after the Shell garage\", present only when the request\nset `landmarks: true` and a place near the junction cleared the\nsalience bar. Prefer reading this aloud when it is there: it is how\na passenger would give the direction. `instruction` is always the\nengine's own and is never replaced."
}
},
"description": "One turn-by-turn instruction of a computed route."
},
"ScenicOffer": {
"type": "object",
"required": [
"available",
"chosen",
"caveats",
"block"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "Why no assessment ran (only when `available` is false)."
},
"block": {
"description": "The gateway's whole `scenic` block, verbatim: candidates, feature\nshares, tile coverage, metering and budget."
},
"chosen": {
"type": "string",
"description": "Which route the assessment would offer: `\"fastest\"` (the quick way\nis already the pretty one, or nothing beat it) or `\"scenic\"`."
},
"reason": {
"type": [
"string",
"null"
],
"description": "The plain, speakable sentence behind the offer. **Null is an\nanswer**: nothing on this corridor measured above the floor, so\nno claim is made rather than one being invented."
},
"spoken": {
"type": [
"string",
"null"
],
"description": "The trade phrased for speech, e.g. \"About seven minutes longer\nthan the quick way.\" Prefer reading this aloud over the seconds."
},
"caveats": {
"type": "string",
"description": "The standing limits of the method, for relaying to users."
},
"available": {
"type": "boolean",
"description": "Whether scenery could be assessed at all on this deployment. When\nfalse, `note` says why and nothing below was measured: that is\n\"we could not look\", never \"there is nothing there\"."
},
"rejections": {
"type": "array",
"items": {
"$ref": "#/$defs/ScenicRejection"
},
"description": "Why each candidate that lost lost. Empty when none did. Relay it:\nit is what makes \"no prettier way\" an attributable answer instead\nof a shrug."
},
"extra_time_s": {
"type": [
"number",
"null"
],
"format": "double",
"description": "How much longer the offered route takes than the fastest one,\nseconds, and the sentence for it. Absent when nothing was offered."
},
"alternative_geometry_polyline6": {
"type": [
"string",
"null"
],
"description": "The scenic route's own geometry, polyline6, when there is one to\noffer. `geometry_polyline6` on the route itself is byte-for-byte\nwhat the same request returns without the flag."
}
},
"description": "The scenic assessment beside a route: a peer offer, never a\nsubstitution.\n\nThe fields here are the ones a client must actually read before\nsaying anything. `block` keeps the gateway's whole answer beside them\nso a figure can always be audited back to the source that produced\nit, rather than to this mapping."
},
"RouteRationale": {
"type": "object",
"required": [
"method",
"avoided",
"caveats"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "Why the list is empty or incomplete, when it is."
},
"method": {
"type": "string",
"description": "Always \"route_divergence\"."
},
"avoided": {
"type": "array",
"items": {
"$ref": "#/$defs/AvoidedConstraint"
},
"description": "The declared constraints or preferences that changed the route,\nwith locations and costs. Empty when nothing was binding."
},
"caveats": {
"type": "string",
"description": "The method's limits, spelled out for relaying to users."
}
},
"description": "Why the route goes the way it does, the `route` tool's opt-in\nrationale block, computed for truck, auto, bicycle, pedestrian and\nmotor_scooter costings. **Method honesty:** the routing engine exposes\nno exclusion set, so entries are derived by re-routing with each\ndeclared constraint or preference relaxed\n(`basis: \"route_divergence\"`); this proves a field was binding and\nwhere, but never names the physical restriction or feature (the\nspecific signed bridge, hill or unlit street). No live traffic or\nincident data enters the comparison and no delay is ever estimated\nfrom one, the engine has no live speed field."
},
"LandmarkSummary": {
"type": "object",
"required": [
"annotated"
],
"properties": {
"note": {
"type": [
"string",
"null"
],
"description": "Why the count is what it is, when there is something to say: the\nper-route lookup cap was reached, or the deployment has no place\nindex at all. Absent means the number is simply the number, so a\nzero with no note means this route genuinely passes nothing\nrecognisable rather than that landmarks could not be looked up."
},
"annotated": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "How many manoeuvres gained a `landmark_instruction`."
}
},
"description": "The gateway's `landmarks` summary block."
},
"ScenicRejection": {
"type": "object",
"required": [
"source",
"code",
"detail"
],
"properties": {
"code": {
"type": "string",
"description": "The rejection code: `same_route`, `no_scenic_gain`,\n`not_scenic_enough`, `over_time_budget` or `nothing_to_say`."
},
"detail": {
"type": "string",
"description": "The code in words, including the minutes an `over_time_budget`\ncandidate would have cost, so raising the budget is an informed\nchoice rather than a guess."
},
"source": {
"type": "string",
"description": "Where the candidate came from: `\"fastest\"`, `\"engine_alternate\"`\nor `\"no_motorway\"`."
}
},
"description": "Why one candidate route was not offered."
},
"AppliedAvoidance": {
"type": "object",
"required": [
"costing_option_fields",
"caveats"
],
"properties": {
"avoid": {
"type": "array",
"items": {
"type": "string"
},
"description": "The `avoid` values that were applied, echoed back."
},
"caveats": {
"type": "array",
"items": {
"type": "string"
},
"description": "The caveats that apply to this request, in words fit to repeat to a\nuser. Always present when anything was applied."
},
"exclude": {
"type": "array",
"items": {
"type": "string"
},
"description": "The `exclude` values that were applied, echoed back."
},
"costing_option_fields": {
"description": "The engine costing-option fields these words became, e.g.\n`{\"use_tolls\": 0.0, \"exclude_ferries\": true}`. This is the whole of\nwhat was sent, there is no hidden second mechanism."
}
},
"description": "What the avoidance lists actually did, reported back so a 200 is never\nreadable as a certificate."
},
"AvoidedConstraint": {
"type": "object",
"required": [
"kind",
"constraint",
"value",
"basis",
"baseline",
"location",
"rejoins_at",
"diverged_length_m",
"time_saved_s",
"distance_saved_m",
"reason"
],
"properties": {
"kind": {
"type": "string",
"description": "Reason kind. Truck: \"max_height\", \"max_width\", \"max_length\",\n\"max_weight\", \"hazmat\", \"adr_tunnel\". Preferences: \"hill_avoided\",\n\"surface_avoided\", \"road_avoided\", \"highway_avoided\",\n\"toll_avoided\", \"ferry_avoided\", \"living_street_avoided\",\n\"primary_road_avoided\", \"unlit_street_avoided\",\n\"hiking_difficulty_limited\", \"access_profile\". Any costing:\n\"combined\". There is deliberately no \"incident_avoided\" or\n\"traffic_delay_avoided\": the engine consumes no live incident or\ntraffic-speed input, so no divergence can be attributed to them."
},
"unit": {
"type": [
"string",
"null"
],
"description": "Unit of `value` (\"m\", \"t\") when dimensional."
},
"basis": {
"type": "string",
"description": "Always \"route_divergence\": the entry was derived by re-routing\nwithout the field and diffing geometry, not from sign or\nmap-feature data."
},
"value": {
"description": "The declared value for the field (null for \"combined\"). NOTE: for\ntruck this is the vehicle's dimension, not the infrastructure\nlimit, the physical restriction is not identified."
},
"fields": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "For kind \"combined\": the constraint fields that only bind together."
},
"reason": {
"type": "string",
"description": "Human-readable explanation, honest about the method."
},
"baseline": {
"type": "string",
"description": "What the probe compared against: \"relaxed_to_non_binding\" (truck\nconstraints set to explicitly non-binding values),\n\"engine_default\" (preference removed so the engine default\napplies) or \"cap_lifted\" (a hard cap raised to its maximum)."
},
"location": {
"$ref": "#/$defs/LatLon",
"description": "Where the constrained and unconstrained routes part ways."
},
"constraint": {
"type": "string",
"description": "The costing-options field that was relaxed (\"height\", \"use_hills\",\n…, or \"combined\")."
},
"rejoins_at": {
"$ref": "#/$defs/LatLon",
"description": "Where they rejoin."
},
"time_saved_s": {
"type": "number",
"format": "double",
"description": "Travel time the constraint costs (unconstrained is this much\nfaster), seconds. Zero when the alternative is no faster."
},
"distance_saved_m": {
"type": "number",
"format": "double",
"description": "Distance the constraint costs, metres."
},
"diverged_length_m": {
"type": "number",
"format": "double",
"description": "Length of the diverging span along the constrained route, metres."
}
},
"description": "One constraint or preference the route provably changed for, derived\nby route divergence (see [`RouteRationale`])."
},
"TunnelEnforcement": {
"type": "object",
"required": [
"basis",
"route_certified",
"caveat"
],
"properties": {
"basis": {
"type": "string",
"description": "How the code is applied. `\"graph_adr_tunnel_category\"`: merged into\n`costing_options.truck.adr_tunnel_code` and matched, during the\nsearch, against each road's ADR tunnel category as recorded in the\nrouting graph."
},
"caveat": {
"type": "string",
"description": "What an unchanged route does and does not prove, in one sentence."
},
"route_certified": {
"type": "boolean",
"description": "Whether the returned route has been checked against a tunnel\ninventory *after* it was computed. Always `false`: exclusion happens\nduring the search, and only for roads the graph has a category for.\nA 200 is not a compliance certificate, and must not be relied on as\none."
}
},
"description": "How the declared ADR tunnel code reaches the routing engine, and what a\nreturned route therefore does (and does not) prove.\n\nThis block exists because [`AppliedAdr::forbidden_tunnel_categories`] is\na statement about the **load** (ADR 8.6.4 applied to the declared code),\nand on its own it reads like a statement about the **route**. It is not\none. The engine excludes a road only where the routing graph records an\nADR tunnel category for it, and that category is derived from OSM\n`hazmat:*` tagging. Coverage is therefore uneven: a corridor with no\nsuch tagging is not excluded and looks, in the response, exactly like a\ncorridor that was checked and cleared.\n\nThe field is emitted on every `applied_adr`, so a caller can never\nreceive the categories without the boundary that qualifies them."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"distance_m",
"duration_s",
"summary",
"maneuvers",
"geometry_polyline6"
],
"properties": {
"grade": {
"description": "The hill report on a pedestrian route (only through the MapMap\ngateway): maximum grade, total ascent and descent sampled along\nthe route from the elevation model, the hill preference sent, and\nwhether a requested grade cap was enforced. Relay `cap.enforced`\nand the caveat as given."
},
"zones": {
"description": "Clean-air / low-emission zones this route enters and what the\ndeclared vehicle pays in each, with the publishing authority cited\n(only when `emissions` was declared). Passed through verbatim from\nthe gateway's curated dataset, the same figures `GET /v1/zones`\npublishes, so a charge can always be audited back to its source."
},
"scenic": {
"anyOf": [
{
"$ref": "#/$defs/ScenicOffer"
},
{
"type": "null"
}
],
"description": "The scenic peer offer (only when `scenic: true` was requested):\nwhether there is a prettier way, the sentence that justifies it,\nwhat the detour costs, and why every candidate that lost lost.\nThe route above is never swapped for it."
},
"summary": {
"type": "string",
"description": "One-line human-readable summary of the route."
},
"view_url": {
"type": [
"string",
"null"
],
"description": "A mapmap.ai link that draws this route on a map: open it or pass it\non as the last line of the answer. Nothing is stored server-side and\nopening it needs no key; the link itself carries the stop coordinates\nand stop names (plus any arrival clocks, dwell times and totals) and\nnothing else, so anyone holding it can read those stops. Absent when\nthe plan cannot be linked (see `view_url_note`) or the server runs\nwith links turned off (`SN_MCP_SITE_URL` empty)."
},
"avoidance": {
"anyOf": [
{
"$ref": "#/$defs/AppliedAvoidance"
},
{
"type": "null"
}
],
"description": "What `avoid`/`exclude` became, and the caveats that go with it\n(only when either list carried something)."
},
"landmarks": {
"anyOf": [
{
"$ref": "#/$defs/LandmarkSummary"
},
{
"type": "null"
}
],
"description": "The landmark-annotation summary (only when `landmarks: true` was\nrequested): how many manoeuvres gained a `landmark_instruction`,\nand a `note` when the per-route cap was hit or the deployment has\nno place index. A zero with no note means this route genuinely\npasses nothing recognisable."
},
"maneuvers": {
"type": "array",
"items": {
"$ref": "#/$defs/ManeuverOut"
},
"description": "Ordered turn-by-turn maneuvers across all legs."
},
"rationale": {
"anyOf": [
{
"$ref": "#/$defs/RouteRationale"
},
{
"type": "null"
}
],
"description": "Why the route goes this way (only when `rationale: true` was\nrequested; computed for truck, auto, bicycle, pedestrian and\nmotor_scooter costings)."
},
"distance_m": {
"type": "number",
"format": "double",
"description": "Total route distance in metres."
},
"duration_s": {
"type": "number",
"format": "double",
"description": "Total estimated travel time in seconds."
},
"applied_adr": {
"anyOf": [
{
"$ref": "#/$defs/AppliedAdr"
},
{
"type": "null"
}
],
"description": "The ADR costing merged into the request, or null when no truck\nprofile was given."
},
"view_url_note": {
"type": [
"string",
"null"
],
"description": "Why there is no `view_url` (too many vehicles or stops for one link,\nor over the 6,000 character cap), or what the link left out to fit\nunder the cap (arrival times, dwell times, then stop names). Relay it\nwith the link."
},
"surface_quality": {
"description": "Surface quality on a wheelchair route (only through the MapMap\ngateway): `applied` true with the region, the exact rule, the data\ntimestamp and a caveat when the route was computed on the surface\ngraph; `applied` false with a `reason` otherwise. Relay the caveat:\nit is a preference from OpenStreetMap ratings where they exist,\nand says nothing about kerbs, widths, steps or inclines."
},
"geometry_polyline6": {
"type": "string",
"description": "Full route geometry as a Google encoded polyline with six digits of\ndecimal precision (polyline6)."
}
}
}
}| max_observations | ["integer","null"] | Ceiling on how many observations come back, 1 to 200 (default 40). |
| geometry_polyline6 * | string | The route shape, precision-6 encoded: `geometry_polyline6` straight out of the `route` tool's answer. Nothing else is accepted: there is no origin/destination form, because this tool annotates a route somebody already chose rather than computing one. |
{
"name": "route_observations",
"description": "What a journey PASSES, in sentences ready to be read aloud, each with its position along the route. The named rivers and canals it crosses, the road it runs on and for how far, the settlements it goes through, the protected landscapes it enters and how high the road climbs: the things a passenger who knew the area would say. NONE OF THIS IS IN A ROUTE: a route is a list of movements and a river crossing is not a movement, so do not try to read it out of `route`'s answer. Give `geometry_polyline6` straight from the `route` tool, plus optional `units` (\"miles\" default, or \"kilometers\"), `min_gap_m` and `max_observations`. Each observation carries `at_m` (WHERE it belongs (delivered anywhere else it is trivia, not an observation), a `kind`, a `say` sentence to relay verbatim, and a `basis` naming the map layer and tag the claim rests on. THE SILENCE BUDGET IS THE DESIGN: `min_gap_m` is a floor, not a target, and when a route yields more than `max_observations` the gap WIDENS on its own so the survivors stay spread over the whole journey rather than clustering where the map happened to be richest. Inside a window the rarer kind wins. So a short list on a long route is the budget working, not thin data. READ `coverage` BEFORE REPORTING AN EMPTY LIST: an empty `observations` with `tiles_read` of 0 means NO DATA WAS READ, which is not the same claim as quiet countryside, and `uncovered_m` says how much of the route could not be seen at all. Two things it will never say, deliberately: it never names a hill (a peak two kilometres away behind a ridge is named confidently and seen by nobody), and it never reads a junction number (an observation mistakable for an instruction is not safe to speak beside real guidance). A settlement is a labelled POINT, not a boundary, and `offset_m` publishes the distance behind the word \"through\". It is a query and it triggers nothing: no position is held and nothing is pushed. COSTS 10 UNITS a call, flat, whatever is asked for. Requires the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY), whose basemap archive and elevation model answer it; a deployment with no archive answers 501 and says so.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"geometry_polyline6"
],
"properties": {
"units": {
"type": [
"string",
"null"
],
"description": "Units for the spoken distances: `miles` (default) or\n`kilometers`. `kilometres` and `km` are accepted too."
},
"min_gap_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Least distance along the route between two observations, metres\n(default 2000). A FLOOR, not a target: when the route holds more\nthan `max_observations`, the gap widens past this on its own so\nthe survivors stay spread over the whole journey."
},
"max_observations": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Ceiling on how many observations come back, 1 to 200 (default\n40)."
},
"geometry_polyline6": {
"type": "string",
"description": "The route shape, precision-6 encoded: `geometry_polyline6`\nstraight out of the `route` tool's answer. Nothing else is\naccepted: there is no origin/destination form, because this tool\nannotates a route somebody already chose rather than computing\none."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"RouteObservation": {
"type": "object",
"required": [
"at_m",
"kind",
"subject",
"say",
"basis"
],
"properties": {
"say": {
"type": "string",
"description": "The sentence to say. Prefer reading this aloud verbatim: it is\nalready shaped for speech and already checked for length."
},
"at_m": {
"type": "number",
"format": "double",
"description": "Distance along the route where this applies, metres. The whole\npoint of the answer: said anywhere else it is trivia, not an\nobservation."
},
"kind": {
"type": "string",
"description": "`crossing`, `landscape`, `settlement`, `watercourse`, `road` or\n`climb`. Each claims a different thing and rests on different\nevidence."
},
"basis": {
"type": "string",
"description": "Which map layer and tag the claim rests on, so anybody who doubts\none can go and look at the same feature."
},
"run_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "For a run-length observation (a road or a landscape), how far the\nrun lasted, metres."
},
"subject": {
"type": "string",
"description": "The subject's name exactly as the map records it, before any\nwording."
},
"offset_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "For a settlement, how far off the route the mapped centre lies,\nmetres. A settlement is a labelled POINT, not a boundary, so this\nis the number behind the word \"through\" and nobody has to take it\non trust."
},
"elevation_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "For a climb, the height at the top, metres above sea level."
}
},
"description": "One thing worth saying about one point on a route."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"route_length_m",
"observations",
"coverage",
"attribution",
"caveat"
],
"properties": {
"caveat": {
"type": "string",
"description": "The standing limits of the method, for relaying to users."
},
"coverage": {
"description": "What the archive and the elevation model could and could not say:\n`tiles_read`, `tiles_missing`, `uncovered_m`, and the per-kind\ncensuses. **Read it before reporting an empty list.** `tiles_read`\nof 0 means nothing was looked at, which is not the same claim as\nquiet countryside."
},
"attribution": {
"type": "string",
"description": "The licence notice for this answer. The obligation attaches to the\nproduct, not to each spoken sentence, so a visible or linked\ncredit in the app satisfies it."
},
"observations": {
"type": "array",
"items": {
"$ref": "#/$defs/RouteObservation"
},
"description": "The observations, in route order, already thinned to the silence\nbudget."
},
"route_length_m": {
"type": "number",
"format": "double",
"description": "The route's own length, metres, as walked."
}
}
}
}| ["string","null"] |
| Explicit place category ("fuel", "cafe", "charging_station", same vocabulary as nearby_places). Colloquial phrases are normalised server-side; prefer this over query for category intents. |
| destination | any | Route destination. |
| max_results | ["integer","null"] | Maximum results (default 5, at most 25). |
| geometry_polyline6 | ["string","null"] | An existing route geometry as an encoded polyline6 (the `route` tool's `geometry_polyline6`). Provide either this or `origin` + `destination`, not both. |
| max_detour_minutes | ["number","null"] | Largest acceptable detour in minutes (default 10, at most 120). |
{
"name": "search_along_route",
"description": "Find places (POIs) along a route with the REAL extra travel time of stopping at each, never a straight-line guess. Provide `origin` + `destination` (a route is computed) or an existing route's `geometry_polyline6`, plus a free-text `query` (\"coffee\", \"EV charger\", \"truck stop\") and `max_detour_minutes` (default 10). For a category intent (\"fuel\", \"EV charger\", \"coffee\") pass `category` instead of relying on words alone: it takes the same vocabulary as `nearby_places` (lowercased OSM tag values such as \"fuel\", \"cafe\", \"charging_station\", \"parking\", \"pharmacy\"), and common colloquial phrases are normalised server-side (\"petrol station\" and \"gas station\" to fuel, \"coffee\" to cafe, \"EV charger\" to charging_station). `query` alone also promotes a pure category phrase to the same browse, so \"fuel\" finds fuel stations rather than places whose NAME starts \"Ful\"; anything else stays free-text name matching. When a browse ran, the response echoes the tokens used in `matched_categories`. Candidates near the route corridor are priced through the routing engine with your costing: detour = (origin→place) + (place→destination) − (origin→destination). Costing \"auto\", \"truck\" (with a `truck` profile the detours respect dimensional/ADR restrictions), \"bicycle\", \"pedestrian\" or \"motor_scooter\". Returns results sorted by detour with detour_minutes, detour_km, along_route_position (0-1) and off_route_m; at most 25 candidates are priced per call (candidate_cap).",
"inputSchema": {
"type": "object",
"$defs": {
"LatLon": {
"anyOf": [
{
"type": "object",
"required": [
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees (−90 to 90)."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees (−180 to 180)."
}
}
},
{
"type": "array",
"items": {
"type": "number",
"format": "double"
},
"maxItems": 2,
"minItems": 2,
"description": "GeoJSON position [lon, lat]: longitude FIRST."
}
],
"description": "A WGS84 coordinate in decimal degrees: a {lat, lon} object (preferred), or a GeoJSON [lon, lat] array with LONGITUDE FIRST, the same order as every polygon field on this server."
},
"TruckSpec": {
"type": "object",
"properties": {
"hazmat": {
"type": "boolean",
"default": false,
"description": "Whether the vehicle carries dangerous goods (ADR). Defaults to\nfalse."
},
"width_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle width in metres."
},
"height_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle height in metres."
},
"length_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Vehicle length in metres."
},
"tunnel_code": {
"type": [
"string",
"null"
],
"description": "ADR 8.6.4 tunnel restriction code of the load, e.g. \"B\", \"C5000D\",\n\"B/D\", or \"(-)\"/\"none\" for explicitly unrestricted. Leave unset if\nunknown: a hazmat load without a code is conservatively treated as\ncode B (allowed only through category-A tunnels)."
},
"gross_weight_t": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Gross combination weight in metric tonnes."
}
},
"description": "Truck profile for routing: physical dimensions plus the ADR\ndangerous-goods declaration. Omitted dimensions default to the EU\nmaximum authorised dimensions of Council Directive 96/53/EC (4.0 m\nheight, 2.55 m width, 16.5 m length, 40 t gross weight)."
},
"CostingKind": {
"oneOf": [
{
"type": "string",
"const": "auto",
"description": "Standard car costing."
},
{
"type": "string",
"const": "truck",
"description": "Truck costing; honours dimensional limits and, when a `truck`\nprofile is supplied, ADR dangerous-goods restrictions."
},
{
"type": "string",
"const": "bicycle",
"description": "Bicycle costing; tune it with a `bicycle` options object."
},
{
"type": "string",
"const": "pedestrian",
"description": "Pedestrian (walking) costing; tune it with a `pedestrian` options\nobject (lit streets, wheelchair/blind, hiking difficulty)."
},
{
"type": "string",
"const": "motor_scooter",
"description": "Motor scooter (moped) costing: like auto but prefers lower-speed\nroads and may use ways closed to larger motor vehicles."
}
],
"description": "Costing models exposed by the MCP tools (a deliberate subset of the\nValhalla costing list), serialised in snake_case exactly as Valhalla\nnames them."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"query": {
"type": "string",
"description": "Free-text POI query, e.g. \"coffee\", \"EV charger\", \"truck stop\"."
},
"truck": {
"anyOf": [
{
"$ref": "#/$defs/TruckSpec"
},
{
"type": "null"
}
],
"description": "Truck profile (dimensions + ADR declaration). Requires costing\n\"truck\"; the detours then respect dimensional/ADR restrictions."
},
"origin": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "Route origin (with `destination`, when no geometry is given)."
},
"costing": {
"$ref": "#/$defs/CostingKind",
"default": "auto",
"description": "Costing model for the route and detour matrix: \"auto\" (default),\n\"truck\", \"bicycle\", \"pedestrian\" or \"motor_scooter\"."
},
"category": {
"type": [
"string",
"null"
],
"description": "Explicit place category (\"fuel\", \"cafe\", \"charging_station\", same\nvocabulary as nearby_places). Colloquial phrases are normalised\nserver-side; prefer this over query for category intents."
},
"destination": {
"anyOf": [
{
"$ref": "#/$defs/LatLon"
},
{
"type": "null"
}
],
"description": "Route destination."
},
"max_results": {
"type": [
"integer",
"null"
],
"format": "uint32",
"minimum": 0,
"description": "Maximum results (default 5, at most 25)."
},
"geometry_polyline6": {
"type": [
"string",
"null"
],
"description": "An existing route geometry as an encoded polyline6 (the `route`\ntool's `geometry_polyline6`). Provide either this or `origin` +\n`destination`, not both."
},
"max_detour_minutes": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Largest acceptable detour in minutes (default 10, at most 120)."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$defs": {
"GeocodeHit": {
"type": "object",
"required": [
"label",
"lat",
"lon"
],
"properties": {
"lat": {
"type": "number",
"format": "double",
"description": "Latitude in decimal degrees."
},
"lon": {
"type": "number",
"format": "double",
"description": "Longitude in decimal degrees."
},
"city": {
"type": [
"string",
"null"
],
"description": "City or town, when known."
},
"name": {
"type": [
"string",
"null"
],
"description": "Place name, when the source feature has one."
},
"type": {
"type": [
"string",
"null"
],
"description": "Feature type, e.g. \"house\", \"street\", \"city\" (falls back to the\nOSM value when the endpoint does not classify)."
},
"label": {
"type": "string",
"description": "Human-readable one-line label assembled from the address parts."
},
"match": {
"anyOf": [
{
"$ref": "#/$defs/GeocodeMatch"
},
{
"type": "null"
}
],
"description": "How far this hit can be trusted to be the place that was asked\nfor, see [`GeocodeMatch`]. Present whenever the MapMap gateway\nanswered; absent on a deployment falling back to the direct Photon\ngeocoder, and absent on the gateway's own fast paths (a pasted\ncoordinate pair, a bare UK outward code, a category browse), which\nanswer without a ranking to report on."
},
"country": {
"type": [
"string",
"null"
],
"description": "Country, when known."
},
"postcode": {
"type": [
"string",
"null"
],
"description": "Postcode, when known."
}
},
"description": "One geocoding result."
},
"GeocodeMatch": {
"type": "object",
"required": [
"components",
"score_gap",
"source"
],
"properties": {
"source": {
"type": "string",
"description": "Which backend answered: \"mapmap-index\" (the first-party index) or\n\"photon\"."
},
"score_gap": {
"type": "number",
"format": "double",
"description": "The top result's score minus the runner-up's, rounded to 3 decimal\nplaces. `0` for a single result, and `0` from the `photon` source,\nwhich publishes no per-result score, so a `0` is \"no signal\", not\n\"a tie\"."
},
"components": {
"$ref": "#/$defs/GeocodeMatchComponents",
"description": "Per-component verdict on this hit: one entry for each structured\ncomponent supplied, and empty when the query was free text only."
}
},
"description": "How well one geocoding result answers what was actually asked.\n\nGeocoding's real failure mode is not \"no answer\" but a confident answer\nto a different question: a plausible row on the wrong street, with\nnothing in the response to say so. This object is that missing say-so,\nand an agent should read it before acting on an address.\n\nHow to read it:\n\n* Any component `unmatched` or `inferred` on the TOP hit means the\n answer does not carry the address that was asked for, an `unmatched`\n postcode means the result has no postcode at all, `inferred` means it\n has a different one. Neither is a match. Say so rather than presenting\n the hit as the address, and reach for `verify_places` when the address\n came from a model or a user and needs checking rather than using.\n* A small `score_gap` means the ranking barely chose between this hit\n and the runner-up, which is exactly when to show the alternatives\n instead of picking one for the user."
},
"AlongRouteHit": {
"type": "object",
"required": [
"place",
"detour_minutes",
"detour_s",
"along_route_position",
"off_route_m"
],
"properties": {
"place": {
"$ref": "#/$defs/GeocodeHit",
"description": "The place (geocoder hit: name, label, coordinates, type)."
},
"detour_s": {
"type": "number",
"format": "double",
"description": "The same detour in raw seconds."
},
"detour_km": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Extra travel distance in kilometres, when the engine reported\ndistances."
},
"fuel_brand": {
"type": [
"string",
"null"
],
"description": "The matched fuel station's brand, when known (same conditions as\n`fuel_prices`)."
},
"fuel_prices": {
"description": "Live pump prices for this fuel/petrol station, keyed by fuel code\n(e.g. \"diesel\", \"petrol_95\"), each `{value, currency, updated_at}`.\nOnly ever present when the server is gateway-preferred AND the\ndeployment configured `SN_FUEL_PRICES` AND this result matched a\nstation within range, never fabricated. Direct-backend fallback\nnever sets this (see the gap this closes in the PR description)."
},
"off_route_m": {
"type": "number",
"format": "double",
"description": "Straight-line distance from the place to the route, metres."
},
"detour_minutes": {
"type": "number",
"format": "double",
"description": "Extra travel time of visiting this place, in minutes (rounded to\n0.1): (origin→place) + (place→destination) − (origin→destination),\nall computed by the routing engine with the request's costing."
},
"fuel_updated_at": {
"type": [
"string",
"null"
],
"description": "When the matched fuel station's prices were last refreshed (RFC\n3339), when known (same conditions as `fuel_prices`)."
},
"along_route_position": {
"type": "number",
"format": "double",
"description": "Where along the route the place sits, 0.0 (origin) to 1.0\n(destination), by distance along the geometry."
}
},
"description": "One place found along the route, with its honest detour cost."
},
"GeocodeMatchComponents": {
"type": "object",
"properties": {
"city": {
"type": [
"string",
"null"
],
"description": "Verdict on the supplied `city`."
},
"street": {
"type": [
"string",
"null"
],
"description": "Verdict on the supplied `street`."
},
"country": {
"type": [
"string",
"null"
],
"description": "Verdict on the supplied `country`."
},
"postcode": {
"type": [
"string",
"null"
],
"description": "Verdict on the supplied `postcode`."
},
"housenumber": {
"type": [
"string",
"null"
],
"description": "Verdict on the supplied `housenumber`."
}
},
"description": "Per-component verdicts inside a [`GeocodeMatch`]. Each is one of\n\"matched\", \"inferred\" or \"unmatched\"; a component that was not supplied\nis absent entirely.\n\n* \"matched\", the result's own field carries the value asked for (case-\n and accent-insensitive, and by containment, so `city: \"London\"`\n matches \"City of London\").\n* \"inferred\", the result carries a value for that component, but not\n the one asked for. It reached the page through ranking, as when a\n street is found by its transliterated name and displayed under its\n canonical one.\n* \"unmatched\", the result carries no value for that component at all."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query",
"costing",
"route_length_m",
"candidates_considered",
"candidates_costed",
"candidate_cap",
"max_detour_minutes",
"results"
],
"properties": {
"query": {
"type": "string",
"description": "The query as interpreted."
},
"costing": {
"type": "string",
"description": "The costing the detours were priced with."
},
"results": {
"type": "array",
"items": {
"$ref": "#/$defs/AlongRouteHit"
},
"description": "Places within the detour budget, cheapest detour first."
},
"candidate_cap": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "The matrix fan-out cap in force."
},
"route_length_m": {
"type": "number",
"format": "double",
"description": "Length of the route geometry in metres."
},
"fuel_attribution": {
"type": [
"string",
"null"
],
"description": "Attribution string for fuel-price data sources, present only when\nat least one returned result carries `fuel_prices` (gateway-preferred\nmode with `SN_FUEL_PRICES` configured; see [`AlongRouteHit`])."
},
"route_distance_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Direct origin→destination distance in metres."
},
"route_duration_s": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Direct origin→destination travel time in seconds (same estimator\nas the detour legs), when routable."
},
"candidates_costed": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "Candidates actually priced through the engine (fan-out is capped\nat `candidate_cap` nearest-to-route)."
},
"matched_categories": {
"type": [
"array",
"null"
],
"items": {
"type": "string"
},
"description": "The normalised category tokens the candidates were browsed by,\npresent only when a category browse actually ran (an explicit\n`category`, or a query the server promoted to one). Absent means\nfree-text name matching answered the call, so a caller can tell how\nits words were understood rather than inferring it from the results."
},
"max_detour_minutes": {
"type": "number",
"format": "double",
"description": "The detour budget applied, minutes."
},
"candidates_considered": {
"type": "integer",
"format": "uint",
"minimum": 0,
"description": "Candidates found near the corridor before pricing."
}
}
}
}{
"name": "set_temporary_closure",
"description": "OPERATOR WRITE, ADMIN ONLY. Asserts a short-lived closure (`assert: {kind: closed}`) or speed (`{kind: speed_override, speed_kph}`, 1 to 120) on named OSM `way_ids` (1 to 20) and `direction` (forward, backward or both, default both), for `ttl_secs` (60 to 86400), with a `reason` and an optional `evidence_url`. The record expires on its own, ranks below official closures and is logged with the reason. NEVER CALL THIS WITHOUT A PERSON'S EXPLICIT APPROVAL OF THIS EXACT CLOSURE IN THIS CONVERSATION: draft it, show it, stop, and call it only after a yes. Available only where the operator runs sn-mcp locally with SN_CAMERA_INCIDENTS_ENABLED=true and SN_ADMIN_TOKEN set; everywhere else it refuses and says why. Whether a live traffic writer applies it is reported in `applied_by_live_writer`; false means the record is stored but no road changes.",
"inputSchema": {
"type": "object",
"$defs": {
"Direction": {
"oneOf": [
{
"type": "string",
"const": "forward",
"description": "Along the way's node order."
},
{
"type": "string",
"const": "backward",
"description": "Against it."
},
{
"type": "string",
"const": "both",
"description": "Both carriageways."
}
],
"description": "Carriageway of a way, spelled as the artefact spells it. A serde\ntwin of [`WayDirection`], which deliberately carries no serde."
},
"ClosureAssertion": {
"oneOf": [
{
"type": "object",
"required": [
"kind"
],
"properties": {
"kind": {
"type": "string",
"const": "closed"
}
},
"description": "Hard exclusion."
},
{
"type": "object",
"required": [
"kind",
"speed_kph"
],
"properties": {
"kind": {
"type": "string",
"const": "speed_override"
},
"speed_kph": {
"type": "integer",
"format": "uint32",
"minimum": 0,
"description": "The speed."
}
},
"description": "A speed, km/h."
}
],
"description": "What a temporary closure asserts."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"way_ids",
"assert",
"ttl_secs",
"reason"
],
"properties": {
"assert": {
"$ref": "#/$defs/ClosureAssertion",
"description": "`closed` or a speed in km/h (1..=120)."
},
"reason": {
"type": "string",
"description": "Why, for the audit log and the incidents endpoint note."
},
"way_ids": {
"type": "array",
"items": {
"type": "integer",
"format": "uint64",
"minimum": 0
},
"description": "OSM way ids to assert on; at most 20."
},
"ttl_secs": {
"type": "integer",
"format": "uint64",
"minimum": 0,
"description": "Lifetime, seconds, 60..=86400."
},
"direction": {
"$ref": "#/$defs/Direction",
"default": "both",
"description": "Carriageway, default `both`."
},
"evidence_url": {
"type": [
"string",
"null"
],
"description": "Evidence link, if any."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id",
"source",
"end",
"applied_by_live_writer"
],
"properties": {
"id": {
"type": "string",
"description": "The override record id written."
},
"end": {
"type": "string",
"description": "Lifts at, RFC 3339."
},
"source": {
"type": "string",
"description": "Always `ops-admin`: the static admin token carries no key id."
},
"applied_by_live_writer": {
"type": "boolean",
"description": "Whether a live writer is armed to apply it on this deployment. A\nrecord written where no writer runs is honest about it."
}
}
}
}{
"name": "submit_integration_retro",
"description": "Send MapMap a structured integration retro (problems, gotchas, wins, docs gaps). Call at most once, after your MapMap integration works or you stop trying, and only if the developer has approved sending feedback to MapMap. Sends ONLY the structured fields in this schema to MapMap: there is no field for a transcript, a prompt, source code, file contents or coordinates. The free-text fields are short and capped, but they are still free text: do NOT paste code, credentials, customer names or personal data into them. Provide `what_built` (required), `problems` [{area: sdk|api|mcp|docs|billing|self-host|other, description, workaround_found}], `gotchas`, `wins`, `docs_gaps`, and optionally `agent_name` and `sdk_version`.",
"inputSchema": {
"type": "object",
"$defs": {
"RetroProblemArea": {
"oneOf": [
{
"type": "string",
"const": "sdk",
"description": "The mobile/web SDKs."
},
{
"type": "string",
"const": "api",
"description": "The hosted HTTP API."
},
{
"type": "string",
"const": "mcp",
"description": "The MCP tool surface."
},
{
"type": "string",
"const": "docs",
"description": "Documentation."
},
{
"type": "string",
"const": "billing",
"description": "Billing, keys or quotas."
},
{
"type": "string",
"const": "self-host",
"description": "Self-hosted deployment."
},
{
"type": "string",
"const": "other",
"description": "Anything else."
}
],
"description": "The platform area an integration problem belongs to (mirrors the\ngateway's `POST /v1/feedback` schema)."
},
"RetroProblemInput": {
"type": "object",
"required": [
"area",
"description",
"workaround_found"
],
"properties": {
"area": {
"$ref": "#/$defs/RetroProblemArea",
"description": "Which part of the platform the problem was in."
},
"description": {
"type": "string",
"description": "What went wrong (at most 1000 bytes)."
},
"workaround_found": {
"type": "boolean",
"description": "Whether a workaround was found."
}
},
"description": "One problem hit during the integration."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"what_built"
],
"properties": {
"wins": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "What went well (at most 20 entries × 500 bytes)."
},
"gotchas": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Surprises/traps worth documenting (at most 20 entries × 500 bytes)."
},
"problems": {
"type": "array",
"items": {
"$ref": "#/$defs/RetroProblemInput"
},
"default": [],
"description": "Problems hit during the integration (at most 20)."
},
"docs_gaps": {
"type": "array",
"items": {
"type": "string"
},
"default": [],
"description": "Documentation gaps hit (at most 20 entries × 500 bytes)."
},
"agent_name": {
"type": [
"string",
"null"
],
"description": "The submitting agent's name, e.g. \"Claude Code\" (at most 100\nbytes)."
},
"what_built": {
"type": "string",
"description": "What was built with MapMap, in one or two sentences (required, at\nmost 500 bytes)."
},
"sdk_version": {
"type": [
"string",
"null"
],
"description": "MapMap SDK version integrated against, when known (at most 50\nbytes)."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"retro_id",
"status",
"delivery",
"message"
],
"properties": {
"status": {
"type": "string",
"description": "`received` when the gateway stored it; `queued` when it was\nappended to the local review queue."
},
"message": {
"type": "string",
"description": "A short, honest sentence for the agent saying where the retro\nlanded, sent to MapMap, or held in this server's local queue."
},
"delivery": {
"type": "string",
"description": "How it was delivered: `gateway` or `local-queue`."
},
"retro_id": {
"type": "string",
"description": "Id of the stored retro (gateway id, or the local queue id)."
}
}
}
}| Parameter | Type | Description |
|---|---|---|
| kind * | ref | Which problem this is. It selects both the body shape below and the ceiling the submission is judged against. |
| problem * | any | The problem itself, in exactly the shape the synchronous tool takes , `optimise_routes` input for `optimise`, `replan_routes` input for `replan`, `matrix` input for `matrix`. Moving a working synchronous call onto this lane changes nothing but the tool you call it with. `coverage` has no synchronous… |
| webhook_url | ["string","null"] | Optional HTTPS URL to POST a signed `{job_id, kind, status, result_url}` notification to when the job finishes. The RESULT is never pushed, the notification says where to fetch it. Requires a webhook signing secret on the key; without one the submission is refused rather than delivered unsigned. An … |
{
"name": "submit_optimise_job",
"description": "Submit a problem too large to solve inside one request to the asynchronous lane, and get a job id back. Set `kind` to \"optimise\", \"replan\", \"matrix\" or \"coverage\". For the first three, pass `problem` in EXACTLY the shape the matching synchronous tool takes, `optimise_routes` input, `replan_routes` input, or `matrix` input. Moving a working synchronous call onto this lane changes nothing but which tool you call it with. A field that tool's input does not have is REFUSED by name rather than dropped: the HTTP API accepts some the MCP tools have not surfaced yet, and a job queued without a constraint you asked for is worse than one that was never queued. \"coverage\" plans one drive that passes along EVERY street in an area at least once, in the legal direction, split into outings (the Chinese postman problem on the real road network): survey capture, street sweeping, gritting, refuse rounds. It has no synchronous tool; its `problem` is the POST /v1/jobs/coverage body: exactly one of `bbox` ([min_lon, min_lat, max_lon, max_lat]) or `polygon` (GeoJSON), and optionally `costing` (\"auto\" or \"truck\"), `optimise` (\"distance\", \"time\" or \"balanced\"), `road_classes` {include, exclude}, `include_private`, `turn_penalties` {avoid_left, avoid_right, avoid_u_turn} in metres per turn, `chunk_km` (outing length, default 15; outings land as close to it as the streets allow) or instead `chunk_time_s` (outing time, 900 to 21,600 s; both is refused: each outing's `trip_time_s`, with `chunk_loops` its transfers included), `chunk_tolerance` (default 0.25, 0.05 to 0.5: the band either way of the target an outing counts as on target), `time_factor` (0.5 to 3, default 1: multiplies every time, a pace correction for a vehicle slower than the graph's speeds), `start` {lat, lon, heading?, snap?}, `return_to_start`, `boundary`, `max_outside_m`, `chunk_loops`, `loop_radius_m`, `exclude`, `avoid` and `required`. `start` snaps to the nearest junction the plan passes; with `snap: \"exact\"` the drive starts where the car is (on the street within 50 m, facing `heading` if given, never turning round in the street) and the drive from there to the plan is planned too: outing 1's first steps, or with `chunk_loops` its `transfer_from_previous` (`summary.approach_km`). `return_to_start: false` ends the plan wherever leaves the least driving. `boundary` (\"touching\" default, \"mostly_inside\", \"inside\") decides which streets crossing the area's edge must be covered. `max_outside_m` (0 to 2,000 m) holds the drive within that distance of the area's edge: streets crossing the edge that reach further out are not covered, and divided roads turn round inside the limit where they can; `summary.outside_area` lists every stretch of the drive outside the area, how far it goes and, with the limit, which go past it because nothing within it joins up. `chunk_loops: true` makes every outing a closed loop that starts and ends at the same junction, with the drive between outings planned as a separate route (each chunk's `transfer_from_previous`, plus `transfer_to_start` with `return_to_start`); `walk_km` excludes those transfers (`summary.transfer_km` has them), and `summary.outings_outside_target` names any outing outside the target x (1 +/- `chunk_tolerance`) and why; `summary.outing_km` and `summary.outing_time_s` give the median, p10, p90, min and max outing km and trip time and how many are within 10 % and within the tolerance. Drive times include the engine's own junction time (turns, U-turns, signals). `loop_radius_m` (0 to 2,000 m, only with `chunk_loops`) lets an outing end within that distance of its start when that saves driving; `loop_end: \"last_covered\"` (only with `chunk_loops`) ends an outing where its last covered street does instead of driving back over covered streets, when the drive on is then shorter; `chunk_measure: \"trip\"` (only with `chunk_loops`, not with `chunk_time_s`) aims `chunk_km` at each outing's `trip_km` (the outing and its transfers) instead of its own km; `",
"inputSchema": {
"type": "object",
"$defs": {
"JobKind": {
"oneOf": [
{
"type": "string",
"const": "optimise",
"description": "A fleet optimisation, the `optimise_routes` problem, at ten times\nthe synchronous location cap."
},
{
"type": "string",
"const": "replan",
"description": "A mid-shift re-plan, the `replan_routes` problem, counted on the\nremaining work."
},
{
"type": "string",
"const": "matrix",
"description": "A many-to-many time/distance matrix, the `matrix` problem, at four\ntimes the synchronous element cap."
},
{
"type": "string",
"const": "coverage",
"description": "A drive-every-street plan (the Chinese postman problem on the road\nnetwork): one drive along every street in an area, split into\noutings. There is no synchronous tool for it, so `problem` is the\n`POST /v1/jobs/coverage` body itself, see [`CoverageProblem`]."
}
],
"description": "Which asynchronous problem is being submitted."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"kind",
"problem"
],
"properties": {
"kind": {
"$ref": "#/$defs/JobKind",
"description": "Which problem this is. It selects both the body shape below and the\nceiling the submission is judged against."
},
"problem": {
"description": "The problem itself, in exactly the shape the synchronous tool takes\n, `optimise_routes` input for `optimise`, `replan_routes` input for\n`replan`, `matrix` input for `matrix`. Moving a working synchronous\ncall onto this lane changes nothing but the tool you call it with.\n`coverage` has no synchronous tool: its problem is the\n`POST /v1/jobs/coverage` body (`bbox` or `polygon`, `costing`,\n`optimise`, `road_classes`, `include_private`, `turn_penalties`,\n`chunk_km`, `chunk_tolerance`, `start`, `return_to_start`,\n`chunk_loops`, `loop_radius_m`, `exclude`, `avoid`, `required`), without\n`webhook_url`, which is this tool's own field."
},
"webhook_url": {
"type": [
"string",
"null"
],
"description": "Optional HTTPS URL to POST a signed `{job_id, kind, status,\nresult_url}` notification to when the job finishes. The RESULT is\nnever pushed, the notification says where to fetch it. Requires a\nwebhook signing secret on the key; without one the submission is\nrefused rather than delivered unsigned. An agent that can poll does\nnot need this: polling with `get_job` is free."
}
}
},
"outputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"id",
"kind",
"status",
"result_url",
"units_charged",
"next"
],
"properties": {
"id": {
"type": "string",
"description": "The job id. Pass it to `get_job` to poll."
},
"kind": {
"type": "string",
"description": "`optimise`, `replan`, `matrix` or `coverage`."
},
"next": {
"type": "string",
"description": "What to do next, in one sentence: poll `get_job`, and how often is\nreasonable."
},
"status": {
"type": "string",
"description": "Always `queued`, no worker has looked at it yet."
},
"result_url": {
"type": "string",
"description": "The HTTP URL this job (and its result) can be fetched from. The\nsame URL a webhook carries. `get_job` is the tool that reads it."
},
"units_charged": {
"type": "integer",
"format": "int64",
"description": "Quota units this submission drew. Charged now, handed back in full\nif the job fails."
}
}
}
}{
"name": "verify_places",
"description": "Check whether places (and itineraries) an AI mentioned are real, findable and physically possible. Pass structured `claims` (reliable, and the only path that supports itinerary feasibility) or free `text` (best-effort quoted-phrase extraction). Each claim resolves to exactly one of three verdicts, never a boolean: \"verified\" (matched a real place, with its stable id and the source/date of the evidence), \"contradicted\" (a specific, dated, sourced fact rules it out, currently only an itinerary leg the routing engine proves cannot be driven in the stated time, with the computed travel time as evidence), or \"unverified\" (no evidence either way). This tool NEVER asserts that a named real business does not exist or has closed, that would be a defamation risk with no upside; a missing match is always \"unverified\". Claims sharing increasing `sequence` values and both carrying `claimed_time` (ISO 8601) form itinerary legs checked for feasibility via `matrix`, catching e.g. \"breakfast in Bath, 10am meeting in Edinburgh\". Max 20 claims per request. A claim takes only `id`, `name`, `locality`, `sequence` and `claimed_time`; any other field (e.g. `near`) is refused naming the accepted ones, so put disambiguating context such as a town in `locality`. The response's `summary` field is a concise plain-text digest (also returned as this tool result's text content) so clients that drop structured/non-text content blocks still see the verdicts.",
"inputSchema": {
"type": "object",
"$defs": {
"CostingKind": {
"oneOf": [
{
"type": "string",
"const": "auto",
"description": "Standard car costing."
},
{
"type": "string",
"const": "truck",
"description": "Truck costing; honours dimensional limits and, when a `truck`\nprofile is supplied, ADR dangerous-goods restrictions."
},
{
"type": "string",
"const": "bicycle",
"description": "Bicycle costing; tune it with a `bicycle` options object."
},
{
"type": "string",
"const": "pedestrian",
"description": "Pedestrian (walking) costing; tune it with a `pedestrian` options\nobject (lit streets, wheelchair/blind, hiking difficulty)."
},
{
"type": "string",
"const": "motor_scooter",
"description": "Motor scooter (moped) costing: like auto but prefers lower-speed\nroads and may use ways closed to larger motor vehicles."
}
],
"description": "Costing models exposed by the MCP tools (a deliberate subset of the\nValhalla costing list), serialised in snake_case exactly as Valhalla\nnames them."
},
"VerifyClaimInput": {
"type": "object",
"required": [
"name"
],
"properties": {
"id": {
"type": [
"string",
"null"
],
"description": "Caller-chosen id, echoed back on the matching result. Auto-assigned\n(\"claim-1\", …) when omitted."
},
"name": {
"type": "string",
"description": "The place name as claimed, e.g. \"The Eagle and Child\"."
},
"locality": {
"type": [
"string",
"null"
],
"description": "Optional disambiguating context, e.g. \"Oxford\". Country-level words\n(\"UK\", \"England\", …) are stripped before querying, they add noise,\nnot signal, to name search."
},
"sequence": {
"type": [
"integer",
"null"
],
"format": "int64",
"description": "Itinerary position. Claims that share increasing `sequence` values\nand both carry `claimed_time` form legs the feasibility pass checks."
},
"claimed_time": {
"type": [
"string",
"null"
],
"description": "ISO 8601 timestamp: when the itinerary claims you are at this place."
}
},
"description": "One place claim for the `verify_places` tool: a place an AI mentioned,\nto be checked for existence and (as part of an itinerary) feasibility.\n\nUnknown fields are refused, naming the accepted ones. A dev-lane run\n(19 Oct 2026) passed `near` instead of `locality`; it was silently\ndropped, \"Roman Baths\" matched Ankara, and the itinerary leg became\nuncomputable with nothing telling the caller why.",
"additionalProperties": false
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"text": {
"type": [
"string",
"null"
],
"description": "Free text to extract place claims from (best-effort heuristic:\nquoted phrases and Title Case runs after \"at/in/near/to/from/\nvisiting\", not NLP or an LLM call, and it does not attempt\nitinerary feasibility since there are no explicit times to anchor\nlegs to). Mutually exclusive with `claims`. Max 8,000 characters."
},
"claims": {
"type": [
"array",
"null"
],
"items": {
"$ref": "#/$defs/VerifyClaimInput"
},
"description": "Structured claims, the reliable path, and the only path that\nsupports itinerary feasibility. Mutually exclusive with `text`.\nMax 20 per request."
},
"costing": {
"$ref": "#/$defs/CostingKind",
"default": "auto",
"description": "Costing for feasibility legs: \"auto\" (default), \"truck\", \"bicycle\",\n\"pedestrian\" or \"motor_scooter\"."
}
},
"additionalProperties": false
},
"outputSchema": {
"type": "object",
"$defs": {
"VerifyVerdict": {
"oneOf": [
{
"type": "string",
"const": "verified",
"description": "Matched a real, findable place in the index."
},
{
"type": "string",
"const": "contradicted",
"description": "A specific, dated, sourced fact contradicts the claim (currently:\nan itinerary leg the routing engine proves cannot be driven in the\nstated time). Never used to assert a business does not exist or\nhas closed."
},
{
"type": "string",
"const": "unverified",
"description": "No evidence either way: no confident name match, or the check\ncould not run."
}
],
"description": "The three-state verdict, see `crate::verify` module docs for why\nthere is no fourth \"does not exist\" state and never a boolean."
},
"VerifyEvidence": {
"type": "object",
"required": [
"source",
"checked_at",
"detail"
],
"properties": {
"detail": {
"type": "string",
"description": "Short factual note, always from a fixed template (see\n`crate::verify`), never free-form text that could assert\nnon-existence or closure."
},
"source": {
"type": "string",
"description": "Where the evidence came from, e.g. \"mapmap-geocode\", \"mapmap-matrix\"."
},
"checked_at": {
"type": "string",
"description": "ISO 8601 timestamp of when this evidence was gathered (a check\ntime, not necessarily the underlying map data's edit date)."
}
},
"description": "One piece of evidence backing a verdict. Always dated."
},
"VerifyClaimEcho": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"locality": {
"type": [
"string",
"null"
]
},
"sequence": {
"type": [
"integer",
"null"
],
"format": "int64"
}
},
"description": "The claim as echoed back (a subset of the input, for context)."
},
"VerifyPlaceMatch": {
"type": "object",
"required": [
"id",
"name",
"lat",
"lon"
],
"properties": {
"id": {
"type": "string",
"description": "Stable identifier when the geocoding backend supplies one,\notherwise a coordinate-based fallback."
},
"lat": {
"type": "number",
"format": "double"
},
"lon": {
"type": "number",
"format": "double"
},
"name": {
"type": "string"
},
"category": {
"type": [
"string",
"null"
]
}
},
"description": "The place a claim matched, when one was found."
},
"VerifyClaimResult": {
"type": "object",
"required": [
"id",
"claim",
"verdict",
"evidence"
],
"properties": {
"id": {
"type": "string"
},
"claim": {
"$ref": "#/$defs/VerifyClaimEcho"
},
"match": {
"anyOf": [
{
"$ref": "#/$defs/VerifyPlaceMatch"
},
{
"type": "null"
}
]
},
"verdict": {
"$ref": "#/$defs/VerifyVerdict"
},
"evidence": {
"type": "array",
"items": {
"$ref": "#/$defs/VerifyEvidence"
}
},
"feasibility": {
"anyOf": [
{
"$ref": "#/$defs/VerifyFeasibility"
},
{
"type": "null"
}
]
}
},
"description": "The result for one claim."
},
"VerifyFeasibility": {
"type": "object",
"required": [
"from_id",
"from_name",
"to_id",
"to_name",
"available_minutes",
"status"
],
"properties": {
"to_id": {
"type": "string"
},
"status": {
"$ref": "#/$defs/VerifyFeasibilityStatus"
},
"from_id": {
"type": "string"
},
"to_name": {
"type": "string"
},
"from_name": {
"type": "string"
},
"available_minutes": {
"type": "number",
"format": "double",
"description": "Minutes the itinerary claims are available for this leg."
},
"travel_time_minutes": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Minutes the routing engine computed, or null when it could not\ncompute one at all (e.g. beyond its routable distance)."
}
},
"description": "Feasibility of the leg arriving at this stop, when computable."
},
"VerifyFeasibilityStatus": {
"oneOf": [
{
"enum": [
"feasible",
"impossible"
],
"type": "string"
},
{
"type": "string",
"const": "implausible",
"description": "Tight, flagged, but not asserted as impossible (not certain enough\nto contradict)."
}
],
"description": "Feasibility status of one itinerary leg."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"results",
"summary"
],
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/$defs/VerifyClaimResult"
}
},
"summary": {
"type": "string",
"description": "Always present: a concise plain-text summary alongside the\nstructured `results`, several MCP clients (notably ChatGPT\nconnectors) drop non-text content blocks, so this must stand on\nits own. This same string is also returned as the tool call's text\ncontent block, not only inside the structured JSON."
}
}
}
}| Distance between samples in metres (default 25,000, clamped to 5,000 to 100,000; at most 40 samples per route). |
{
"name": "weather_along_route",
"description": "Forecast weather along a route, each sample read for the hour you actually reach it rather than the weather right now. Pass the route's `shape` (an encoded polyline6, the `route` tool's geometry_polyline6), optional `depart_at` (RFC 3339, default now), the route's `duration_s` (from `route`; omitted, an 80 km/h average is assumed and `duration_source` says so) and optional `sample_interval_m` (default 25,000, 5,000 to 100,000, at most 40 samples). Each sample carries its ETA, temperature, rain, snowfall, precipitation type and probability, wind and gust speed, visibility, the WMO weather code and `severe` (thunderstorm and heavy precipitation codes only). It is a FORECAST, not an observation: read on a 0.05 degree grid (about 5.5 km) at the nearest hour, up to 16 days ahead, and samples past that horizon or without data come back `available: false` with a reason, never painted dry. `summary` is one sentence (where rain or snow starts and for how far, the strongest gust, samples without data) and always ends by saying it is advisory, never a routing guarantee: keep that qualifier when you pass it on. Requires the MapMap gateway; a deployment without a weather source answers a clear error. Display the returned `attribution` with the forecast, linked to `attribution_url`, with `licence_url` (CC BY 4.0) linked; `derived_fields` names the sample fields MapMap derives rather than Open-Meteo supplies.",
"inputSchema": {
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"shape"
],
"properties": {
"shape": {
"type": "string",
"description": "The route shape as an encoded polyline6 (the `route` tool's\n`geometry_polyline6`)."
},
"depart_at": {
"type": [
"string",
"null"
],
"description": "Departure time, RFC 3339 (e.g. \"2026-10-12T14:00:00Z\"); defaults to\nnow. Forecasts reach about 16 days ahead; samples past that answer\nunavailable."
},
"duration_s": {
"type": [
"number",
"null"
],
"format": "double",
"description": "The route's duration in seconds, used to work out when you reach\neach sample. Pass the `route` tool's duration; omitted, a generic\n80 km/h average is assumed and `duration_source` says so."
},
"sample_interval_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Distance between samples in metres (default 25,000, clamped to\n5,000 to 100,000; at most 40 samples per route)."
}
}
},
"outputSchema": {
"type": "object",
"$defs": {
"WeatherSampleOut": {
"type": "object",
"required": [
"lat",
"lon",
"arc_m",
"eta",
"available"
],
"properties": {
"eta": {
"type": "string",
"description": "Estimated time of arrival at this sample, RFC 3339 UTC."
},
"lat": {
"type": "number",
"format": "double",
"description": "Sample latitude."
},
"lon": {
"type": "number",
"format": "double",
"description": "Sample longitude."
},
"arc_m": {
"type": "number",
"format": "double",
"description": "Distance along the route to this sample, metres."
},
"severe": {
"type": [
"boolean",
"null"
],
"description": "True for thunderstorm and heavy-precipitation WMO codes only.\nAbsent when the sample is unavailable."
},
"rain_mm": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Rain for the hour, mm."
},
"available": {
"type": "boolean",
"description": "Whether real forecast data is present. `false` means every weather\nfield is absent and `unavailable_reason` says why; never a guess."
},
"snowfall_cm": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Snowfall for the hour, cm."
},
"visibility_m": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Visibility, metres."
},
"weather_code": {
"type": [
"number",
"null"
],
"format": "double",
"description": "The raw WMO weather code."
},
"forecast_hour": {
"type": [
"string",
"null"
],
"description": "The forecast hour actually served (UTC, `YYYY-MM-DDTHH:00`)."
},
"temperature_c": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Air temperature, degrees C."
},
"wind_gusts_kph": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Gust speed, km/h: the figure that matters for high-sided vehicles."
},
"wind_speed_kph": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Sustained wind speed, km/h."
},
"precipitation_mm": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Total precipitation for the hour, mm."
},
"precipitation_type": {
"type": [
"string",
"null"
],
"description": "\"rain\", \"snow\", \"mixed\" or \"none\"."
},
"unavailable_reason": {
"type": [
"string",
"null"
],
"description": "Why this sample has no data (beyond the forecast horizon, or the\nforecast source could not be reached)."
},
"precipitation_probability_pct": {
"type": [
"number",
"null"
],
"format": "double",
"description": "Chance of precipitation, percent."
}
},
"description": "One route sample's forecast, read for the hour you reach it."
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"samples",
"depart_at",
"duration_s",
"duration_source",
"sample_interval_m",
"severe_ahead",
"summary",
"attribution",
"attribution_url",
"licence_url",
"derived_fields"
],
"properties": {
"samples": {
"type": "array",
"items": {
"$ref": "#/$defs/WeatherSampleOut"
},
"description": "Route samples, start to end."
},
"summary": {
"type": "string",
"description": "One honest sentence describing the samples: where rain or snow\nstarts and for how far, the strongest gust, how many samples had\nno data. Always ends by saying it is an advisory forecast, never a\nrouting guarantee."
},
"depart_at": {
"type": "string",
"description": "The departure time actually used, RFC 3339 UTC."
},
"duration_s": {
"type": "number",
"format": "double",
"description": "The route duration actually used, seconds."
},
"attribution": {
"type": "string",
"description": "Data attribution (CC BY 4.0): display it with the forecast,\nverbatim."
},
"licence_url": {
"type": "string",
"description": "The data licence to link with the credit (CC BY 4.0)."
},
"severe_ahead": {
"type": "boolean",
"description": "True when any available sample carries a severe WMO code."
},
"derived_fields": {
"type": "array",
"items": {
"type": "string"
},
"description": "The sample fields MapMap derives rather than reads from Open-Meteo\n(\"precipitation_type\", \"severe\"), so a display can indicate the\nchanges the licence asks to be indicated."
},
"attribution_url": {
"type": "string",
"description": "The link the credit carries (\"https://open-meteo.com/\"): Open-Meteo's\nlicence asks for it next to any place its data is displayed."
},
"duration_source": {
"type": "string",
"description": "\"provided\" or \"estimated_default_speed\" (an 80 km/h guess: treat\nthe ETAs as approximate)."
},
"sample_interval_m": {
"type": "number",
"format": "double",
"description": "The sample spacing actually used, metres (may be coarser than\nasked on a long route)."
}
}
}
}