MCP tool reference

Every tool the hosted MapMap MCP server serves, with its inputs, its output and one real call. This page is generated from the server's own tools/list (input and output JSON Schemas built from the server's types), captured from https://mcp.mapmap.ai/mcp on 2026-11-06 (sn-mcp 0.3.0, 56 tools). Do not edit it by hand: run node --experimental-strip-types scripts/generate-mcp-tools-md.mjs in website/.

How to connect, keys and billing, resources, prompts and self-hosting are on MCP server. Recipes per assistant are on Use MapMap from any AI assistant.

Reading this page

• Access says how the tool can be called on the hosted endpoint. Keyless tools answer without a key under fair use; present your own snk_ key as Authorization: Bearer snk_… and their metered calls bill to you instead. Keyless, local tools are pure computation: no network call, never metered. Your own key tools refuse keyless calls on the hosted endpoint. Operator tool means it refuses on the hosted endpoint.
• Inputs lists every argument the server accepts. Default is the schema's own default or the default the server's description states; empty means none is stated. Limits are the bounds the schema enforces; limits stated only in prose are in the description.
• A coordinate (LatLon) is a {lat, lon} object (preferred) or a GeoJSON [lon, lat] array, longitude first. Distances are metres and durations seconds unless a field name says otherwise.
• Caveats are the server's own sentences about what an answer does and does not mean, quoted from its description. Pass them on when you relay the answer.
• Example calls were made keyless on the hosted endpoint on the date shown. Results are trimmed for length: long strings end in … and arrays show their first two entries.
• Tool failures come back as MCP tool errors (isError: true) with a message naming the fix, so an agent can correct itself.

Tools by group

• Routing: route, route_observations, heritage_narration, matrix, reachable_area, elevation, match_trace
• Fleet and optimisation: optimise_routes, order_stops, cluster, replan_routes, plan_day, plan_errands, plan_ev_route
• Along-route search: search_along_route, cheapest_fuel_along_route, cheapest_charging_along_route
• Places and geocoding: geocode, reverse_geocode, nearby_places, places_in_view, list_place_categories
• Transit: nearby_stops, next_departures
• Weather and events: weather_along_route, weather_frames, events_in_area, space_weather_now, camera_incidents
• Clearance and ADR: check_adr_tunnel, check_clearance_on_route
• Verify: verify_places, validate_geodata
• Map styling: list_style_layers, get_style, create_style, set_palette, set_layer_paint, set_layer_layout, check_style_contrast
• Geo helpers: geo_distance, geo_bearing, geo_destination, geo_point_in_polygon, geo_bbox, geo_centroid, geo_length, geo_area, geo_simplify, geo_nearest_point_on_line
• Jobs: submit_optimise_job, get_job
• Account and usage: get_usage
• Feedback and operator tools: report_map_issue, submit_integration_retro, set_temporary_closure

Routing

Routes in every costing, what a route passes, reachability, travel matrices, elevation and trace matching.

route

Compute a turn-by-turn route between origin and destination (optionally via waypoints). Costing "auto" = car, "truck" = lorry, "bicycle", "pedestrian" = walking, "motor_scooter" = moped.

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Caveats the server states:

• 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.
• 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.
• 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.
• 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 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 route, because the untolled alternative is fifty kilometres further.
• exclude ("tolls", "highways", "ferries", "bridges", "tunnels") is a hard exclusion: it can answer NO ROUTE rather than a detour, and it depends on the routing engine's own hard-exclusion setting, which the engine does not report and this server cannot read, so it is requested, never promised.
• "tolls" and "highways" under avoid exist only on motorised costings; asking for one on a bicycle is refused rather than silently ignored.
• Whatever is applied comes back in avoidance, with the caveats, relay them, because "avoid tolls" read as a guarantee is the failure mode here.
• It is a snapping preference, not a manoeuvre guarantee, and it needs a coordinate genuinely offset from the road centreline; street_side_tolerance_m and street_side_max_distance_m bound the window in which it applies, and a pair leaving no window is refused rather than answered with the preference silently inert.
• Without it a zone can only be named, never priced.
• Set scenic: true (auto costing only) to ask whether there is a prettier way.
• It is a PEER OFFER, never a substitution: the route in geometry_polyline6 is byte-for-byte what the same request returns without the flag, and the prettier way, when there is one, arrives beside it in scenic, with its own geometry in scenic.alternative_geometry_polyline6 and what it costs in scenic.spoken ("About seven minutes longer than the quick way").
• That is an ANSWER, not a failure, and it is the one to relay.
• It is a re-ranking of routes the engine already proposed, not a scenic search: a beautiful road the engine never offered was never considered, and scenic.caveats says so.
• Like rationale, IT COSTS EXTRA METERED COMPUTATIONS, at most two, which is why it is opt-in and never on by default.
• available: false with a note means this deployment could not look, which is not the same claim as nothing being there.

Inputs

AvoidFeature: 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.

One of "tolls", "highways", "ferries".

BicycleSpec: Bicycle options for costing "bicycle": the bicycle type plus road, surface and hill preference weights, mapped onto Valhalla costing_options.bicycle.

RouteLocation: One location of a route request: a coordinate, plus the optional kerbside approach for arriving at it. A bare {lat, lon} is still a complete location, every kerbside field is optional and omitting all of them is exactly the request that was made before they existed.

PreferredSideKind: Side-of-street preference for arriving at or departing from a location. Carries both vocabularies: MapMap's own same/opposite/either and the OSRM/Mapbox approaches words curb/unrestricted, which are aliases for same and either. Both spell the same request, on this surface and on the HTTP API.

ExcludeFeature: 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.

One of "tolls", "highways", "ferries", "bridges", "tunnels".

PedestrianSpec: Pedestrian options for costing "pedestrian": lit-street preference, pedestrian type, hills, surface quality and hiking difficulty, mapped onto Valhalla costing_options.pedestrian (surface quality and the grade cap are MapMap gateway fields). All preferences, never guarantees: the router prefers matching ways where the map data supports it.

Output

AppliedAdr: The ADR costing that was merged into a truck route request. Every field here describes the request: the declared load and the costing options built from it. Nothing here is an assertion about the returned geometry, see TunnelEnforcement.

TunnelEnforcement: How the declared ADR tunnel code reaches the routing engine, and what a returned route therefore does (and does not) prove. This block exists because forbidden_tunnel_categories is a statement about the load (ADR 8.6.4 applied to the declared code), and on its own it reads like a statement about the route. It is not one. The engine excludes a road only where the routing graph records an ADR tunnel category for it, and that category is derived from OSM hazmat:* tagging. Coverage is therefore uneven: a corridor with no such tagging is not excluded and looks, in the response, exactly like a corridor that was checked and cleared. The field is emitted on every applied_adr, so a caller can never receive the categories without the boundary that qualifies them.

AppliedAvoidance: What the avoidance lists actually did, reported back so a 200 is never readable as a certificate.

LandmarkSummary: The gateway's landmarks summary block.

ManeuverOut: One turn-by-turn instruction of a computed route.

RouteRationale: Why the route goes the way it does, the route tool's opt-in rationale block, computed for truck, auto, bicycle, pedestrian and motor_scooter costings. Method honesty: the routing engine exposes no exclusion set, so entries are derived by re-routing with each declared constraint or preference relaxed (basis: "route_divergence"); this proves a field was binding and where, but never names the physical restriction or feature (the specific signed bridge, hill or unlit street). No live traffic or incident data enters the comparison and no delay is ever estimated from one, the engine has no live speed field.

AvoidedConstraint: One constraint or preference the route provably changed for, derived by route divergence (see RouteRationale).

ScenicOffer: The scenic assessment beside a route: a peer offer, never a substitution. The fields here are the ones a client must actually read before saying anything. block keeps the gateway's whole answer beside them so a figure can always be audited back to the source that produced it, rather than to this mapping.

ScenicRejection: Why one candidate route was not offered.

Example (called 2026-11-05)

{
  "origin": {
    "lat": 51.5007,
    "lon": -0.1246
  },
  "destination": {
    "lat": 51.5308,
    "lon": -0.1238
  },
  "costing": "auto"
}

Result (trimmed):

{
  "distance_m": 5106,
  "duration_s": 917.918,
  "geometry_polyline6": "gejfaB~zrFDCRGXC^?rCXvD`@|@H`@J`@\\\\b@P^Pf@Nd@Px@Jp@HfA@fAC`Aq@fKeA|OK`ASlAY|@_@r…",
  "maneuvers": [
    {
      "country": "GB",
      "distance_m": 39,
      "driving_side": "left",
      "duration_s": 7.271,
      "instruction": "Drive south.",
      "road_class": "service_other",
      "speed_limit_posted": {
        "type": "unknown"
      },
      "speed_limit_sign": "vienna",
      "speed_limit_unit": "mph",
      "subdivision": "GB-ENG"
    },
    {
      "country": "GB",
      "distance_m": 23,
      "driving_side": "left",
      "duration_s": 5.026,
      "instruction": "Turn right.",
      "road_class": "service_other",
      "speed_limit_posted": {
        "type": "unknown"
      },
      "speed_limit_sign": "vienna",
      "speed_limit_unit": "mph",
      "subdivision": "GB-ENG"
    },
    "… 16 more"
  ],
  "summary": "5.1 km, 15 min (18 maneuvers), Found route between points",
  "view_url": "https://mapmap.ai/view?p=eyJ2IjoxLCJraW5kIjoicm91dGUiLCJjb3N0aW5nIjoiYXV0byIsInJ…"
}

More from the server's description:

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. Returns distance (m), duration (s), maneuvers, polyline6 geometry and the ADR costing that was applied. Prefer reading it aloud: it is how a passenger gives directions. Needs the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY), whose place index does the lookup. 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. Each location also takes a kerbside approach: preferred_side "same" (alias "curb") stops on the door's side of the road, resolved against the locale's driving side, the left kerb in the UK, the right in Germany, with "opposite" and "either" (alias "unrestricted") for the rest. Pass emissions {vehicle_category, fuel, euro_standard} for UK clean-air-zone assessment: the response's zones block then names every zone the route enters and what THIS vehicle pays there, with the publishing authority cited. Needs the gateway, which holds the curated zone dataset; the whole dataset, every scheme, charge, boundary and provenance record, is readable at GET /v1/zones on the HTTP API when an agent needs to audit a figure or list zones without routing. EVERY OFFER STATES ITS REASON OR THERE IS NO OFFER: a route that scores well but cannot support a plain sentence is dropped rather than dressed up, so a scenic.reason of null means nothing here measured above the floor. A REJECTION IS ALSO AN ANSWER: every candidate that lost says why in scenic.rejections[] (same_route, no_scenic_gain, not_scenic_enough, over_time_budget with the minutes it would have cost, nothing_to_say), so "no prettier way" is always attributable and raising the budget is an informed choice. Needs the gateway, whose basemap archive the scoring is measured against. 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.

route_observations

What a journey PASSES, in sentences ready to be read aloud, each with its position along the route.

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Caveats the server states:

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

Inputs

Output

RouteObservation: One thing worth saying about one point on a route.

Example (called 2026-11-05)

{
  "geometry_polyline6": "gejfaB~zrFDCRGXC^?rCXvD`…"
}

Result (trimmed):

{
  "attribution": "Map data © OpenStreetMap contributors, ODbL. Basemap schema © OpenMapTiles, CC-BY 4.0.",
  "caveat": "Observations are computed by intersecting the route's geometry with OpenStreetMa…",
  "coverage": {
    "elevation": {
      "found": 21,
      "named": 21
    },
    "elevation_source": "model",
    "road": {
      "ambiguous_m": 0,
      "named_m": 100,
      "unnamed_m": 5000
    },
    "settlements": {
      "found": 16,
      "named": 8
    },
    "tiles_missing": 0,
    "tiles_read": 2,
    "tiles_unreadable": 0,
    "uncovered_m": 0,
    "watercourse_crossings": {
      "found": 0,
      "named": 0
    }
  },
  "observations": [
    {
      "at_m": 1700,
      "basis": "place.name",
      "kind": "settlement",
      "offset_m": 397.87514065536885,
      "say": "Passing through Covent Garden.",
      "subject": "Covent Garden"
    },
    {
      "at_m": 4900,
      "basis": "place.name",
      "kind": "settlement",
      "offset_m": 584.8831887682724,
      "say": "Passing through St Pancras.",
      "subject": "St Pancras"
    }
  ],
  "route_length_m": 5098.2
}

More from the server's description:

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. Give geometry_polyline6 straight from the route tool, plus optional units ("miles" default, or "kilometers"), min_gap_m and max_observations. Inside a window the rarer kind wins. 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.

heritage_narration

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.

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Caveats the server states:

• Not a tour and not a chatbot.
• 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.
• 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.
• Do not add either.

Inputs

Output

HeritageLine: One reviewed line about the ground the route is on.

Example (called 2026-11-05)

{
  "geometry_polyline6": "wekeaBxksIsQzPtFdN~HxR`@…",
  "duration_s": 492.248
}

Result (trimmed):

{
  "attribution": "Plaque inscriptions from the OpenPlaques United Kingdom dataset (snapshot of 14 …",
  "caveat": "Every line is a sentence written and reviewed by a person from the inscription o…",
  "census": {
    "beyond_reach": 8,
    "corpus_entries": 18,
    "corridor": "chelsea-riverside",
    "gap_basis": "time",
    "gap_m": 5368.4,
    "mean_speed_kph": 21.5,
    "silenced_by_budget": 9,
    "spoken": 1,
    "within_reach": 10
  },
  "corridor": {
    "id": "chelsea-riverside",
    "name": "Chelsea riverside",
    "reviewed_on": "2026-09-21",
    "road": "A3220 and A3212, Lots Road to Millbank"
  },
  "lines": [
    {
      "at_m": 446.6,
      "basis": "inscription, and the dataset's own role for her",
      "id": "gaskell",
      "offset_m": 34.9,
      "plaque_ids": [
        380
      ],
      "say": "Elizabeth Gaskell was born along here. She wrote Cranford.",
      "subject": "Elizabeth Gaskell"
    }
  ],
  "route_length_m": 2936.2
}

More from the server's description:

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. EVERY OTHER ROUTE ANSWERS WITH NO LINES, and that is a correct answer rather than a failure. 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. COSTS 1 UNIT a call: it reads no tiles and opens no archive. Requires the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY).

matrix

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

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Inputs

Output

Example (called 2026-11-05)

{
  "origins": [
    {
      "lat": 51.5007,
      "lon": -0.1246
    }
  ],
  "destinations": [
    {
      "lat": 51.5308,
      "lon": -0.1238
    },
    {
      "lat": 51.5194,
      "lon": -0.127
    }
  ],
  "costing": "auto"
}

Result (trimmed):

{
  "distances_m": [
    [
      5106,
      2846
    ]
  ],
  "durations_s": [
    [
      917.823,
      519.729
    ]
  ]
}

More from the server's description:

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.

reachable_area

Compute the area reachable from an origin within one or more travel-time budgets, walkability/cyclability rings.

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Caveats the server states:

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

Inputs

Output

Example (called 2026-11-05)

{
  "origin": {
    "lat": 51.5007,
    "lon": -0.1246
  },
  "contours_minutes": [
    5
  ],
  "costing": "auto"
}

Result (trimmed):

{
  "geojson": {
    "engine": "valhalla",
    "eta_calibration": {
      "applied": false,
      "method": "gb_typical_delay_v1",
      "note": "Isochrone contours are drawn on the routing engine's free-flowing times, which d…",
      "travel_times": "free_flow"
    },
    "features": [
      {
        "geometry": "{…}",
        "properties": "{…}",
        "type": "Feature"
      }
    ],
    "snapped_origin": {
      "distance_m": 19.2,
      "lat": 51.500644,
      "lon": -0.124863
    },
    "type": "FeatureCollection"
  }
}

More from the server's description:

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

elevation

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.

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Caveats the server states:

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

Inputs

Output

ElevationSample: One elevation sample: elevation_m and, when the request set encoded_polyline, the resampled point and its cumulative distance from the start.

Example (called 2026-11-05)

{
  "points": [
    {
      "lat": 51.5007,
      "lon": -0.1246
    },
    {
      "lat": 51.4769,
      "lon": -0.0005
    }
  ]
}

Result (trimmed):

{
  "samples": [
    {
      "elevation_m": 16.37
    },
    {
      "elevation_m": 48.28
    }
  ]
}

More from the server's description:

The encoded_polyline form also returns each sample's resampled lat/lon and cumulative range_km from the start.

match_trace

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

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Caveats the server states:

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

Inputs

Output

SegmentSummary: How much of the matched path carried one flag (toll, bridge, tunnel). The engine reports no separate time for these, so distance and a count are all that can honestly be given.

AdminAreaSummary: Distance and time the matched path spent in one administrative area.

RoadClassSummary: Distance and time the matched path spent on one road class.

SurfaceSummary: Distance the matched path spent on one road surface.

Example (called 2026-11-05)

{
  "shape": [
    {
      "lat": 51.5007,
      "lon": -0.1246
    },
    {
      "lat": 51.5033,
      "lon": -0.1276
    },
    {
      "lat": 51.5068,
      "lon": -0.128
    }
  ],
  "costing": "auto"
}

Result (trimmed):

{
  "bridge": {
    "distance_m": 0,
    "edge_count": 0
  },
  "by_admin": [
    {
      "country": "United Kingdom",
      "country_code": "GB",
      "distance_m": 1123,
      "duration_s": 314.7,
      "edge_count": 60,
      "state": "England",
      "state_code": "ENG"
    }
  ],
  "by_road_class": [
    {
      "distance_m": 657,
      "duration_s": 81.7,
      "edge_count": 29,
      "road_class": "primary"
    },
    {
      "distance_m": 229,
      "duration_s": 139.1,
      "edge_count": 11,
      "road_class": "service_other"
    },
    "… 2 more"
  ],
  "by_surface": [
    {
      "distance_m": 1086,
      "edge_count": 57,
      "surface": "paved_smooth"
    },
    {
      "distance_m": 37,
      "edge_count": 3,
      "surface": "paved"
    }
  ],
  "costing": "auto",
  "distance_m": 1065,
  "duration_s": 293.945,
  "edge_count": 60,
  "geometry_polyline6": "myjfaBphrFGdEI`\\EvEInN{DIkFK{Wc@cNUqHa@e@r[E~BC`CSpJiDA{CQmBGgD?ySLwOHuADaLPAbB?…",
  "summary": "matched 1.1 km, 4 min over 60 road segment(s) as auto",
  "toll": {
    "distance_m": 0,
    "edge_count": 0
  },
  "tunnel": {
    "distance_m": 0,
    "edge_count": 0
  }
}

More from the server's description:

Costing decides which roads the trace may match onto, so a walk matched as "auto" snaps to the carriageway rather than the footpath. 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. Needs the MapMap gateway (GATEWAY_URL + GATEWAY_API_KEY); there is no direct-backend fallback.

Fleet and optimisation

Multi-stop and multi-vehicle planning, re-planning mid-shift, EV journeys and errands against a deadline.

optimise_routes

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

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Caveats the server states:

• 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.
• 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).
• 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.
• Breaks are never widened, a driver's rest is not a preference to trade for a fuller van , and neither are capacities, skills, territories or task caps; only time windows move.
• 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.

Inputs

Output

Example (called 2026-11-05)

{
  "vehicles": [
    {
      "id": 1,
      "start": {
        "lat": 51.5007,
        "lon": -0.1246
      },
      "end": {
        "lat": 51.5007,
        "lon": -0.1246
      }
    }
  ],
  "jobs": [
    {
      "id": 1,
      "location": {
        "lat": 51.5308,
        "lon": -0.1238
      }
    },
    {
      "id": 2,
      "location": {
        "lat": 51.5194,
        "lon": -0.127
      }
    }
  ],
  "costing": "auto"
}

Result (trimmed):

{
  "profile": "auto",
  "routes": [
    {
      "distance_m": 9166,
      "duration_s": 1638,
      "service_s": 0,
      "steps": [
        "{…}",
        "{…}",
        "… 2 more"
      ],
      "vehicle": 1,
      "waiting_time_s": 0
    }
  ],
  "summary": {
    "cost": 1638,
    "distance_m": 9166,
    "duration_s": 1638,
    "routes": 1,
    "service_s": 0,
    "unassigned": 0,
    "waiting_time_s": 0
  },
  "unassigned": [],
  "view_url": "https://mapmap.ai/view?p=eyJ2IjoxLCJraW5kIjoiZmxlZXQiLCJjb3N0aW5nIjoiYXV0byIsInJ…",
  "zones": {
    "at_locations": [
      {
        "assessment": "unknown",
        "currency": "GBP",
        "daily_charge": null,
        "enforcement": "charge",
        "id": "gb-london-lez",
        "locations_inside": 3,
        "name": "London Low Emission Zone",
        "operator": "Transport for London",
        "source": "{…}",
        "type": "lez"
      },
      {
        "assessment": "unknown",
        "currency": "GBP",
        "daily_charge": null,
        "enforcement": "charge",
        "id": "gb-london-ulez",
        "locations_inside": 3,
        "name": "London Ultra Low Emission Zone",
        "operator": "Transport for London",
        "source": "{…}",
        "type": "ulez"
      }
    ],
    "basis": "the optimiser is fed a travel-time matrix, not road geometry, so this block repo…",
    "caveats": "Zone boundaries are simplified from the published geometry to the tolerance stat…",
    "note": "charge depends on vehicle emissions, supply `emissions` (vehicle_category, fuel,…"
  }
}

More from the server's description:

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). 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 and task caps. Read the returned reloads block before quoting arrival times, and re-plan after each tip with replan_routes for the tighter answer. 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. 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.

order_stops

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.

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Inputs

OrderStopSpec: One errand stop of an order_stops request.

Output

OrderedStop: One stop of an ordered errand plan.

Example (called 2026-11-05)

{
  "start": {
    "lat": 51.5007,
    "lon": -0.1246
  },
  "stops": [
    {
      "location": {
        "lat": 51.5308,
        "lon": -0.1238
      },
      "label": "B"
    },
    {
      "location": {
        "lat": 51.5194,
        "lon": -0.127
      },
      "label": "C"
    }
  ]
}

Result (trimmed):

{
  "distance_m": 4791,
  "duration_s": 868,
  "ordered": [
    {
      "arrival_s": 520,
      "label": "C",
      "location": {
        "lat": 51.5194,
        "lon": -0.127
      },
      "order": 1,
      "stop_index": 1
    },
    {
      "arrival_s": 868,
      "label": "B",
      "location": {
        "lat": 51.5308,
        "lon": -0.1238
      },
      "order": 2,
      "stop_index": 0
    }
  ],
  "profile": "auto",
  "unassigned_stop_indexes": []
}

More from the server's description:

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.

cluster

Group stops into balanced geographic clusters, so a day too large for one optimisation can be optimised one cluster at a time.

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Caveats the server states:

• 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.
• The answer carries a basis sentence saying exactly this; show it, so a centroid is never read as a plan.

Inputs

ClusterLocationSpec: One stop to be clustered.

Output

Example (called 2026-11-05)

{
  "locations": [
    {
      "id": "a",
      "lat": 51.5,
      "lon": -0.12
    },
    {
      "id": "b",
      "lat": 51.51,
      "lon": -0.13
    },
    {
      "id": "c",
      "lat": 51.6,
      "lon": -0.2
    },
    {
      "id": "d",
      "lat": 51.61,
      "lon": -0.21
    }
  ],
  "clusters": 2
}

Result (trimmed):

{
  "balance": {
    "basis": "locations",
    "largest_cluster_load": 0,
    "largest_cluster_locations": 2,
    "max_load_per_cluster": null,
    "max_locations_per_cluster": null,
    "note": "every cluster is inside the ceiling.",
    "relaxed": false
  },
  "basis": "Straight-line clustering. Distances are measured between coordinates on a local …",
  "clusters": [
    {
      "centroid": {
        "lat": 51.504999999999995,
        "lon": -0.125
      },
      "count": 2,
      "id": 0,
      "load": 0,
      "locations": [
        "a",
        "b"
      ],
      "territory": null
    },
    {
      "centroid": {
        "lat": 51.605,
        "lon": -0.205
      },
      "count": 2,
      "id": 1,
      "load": 0,
      "locations": [
        "c",
        "d"
      ],
      "territory": null
    }
  ],
  "parameters": {
    "clusters": 2,
    "converged": true,
    "iterations": 2,
    "locations": 4,
    "locations_outside_all_territories": 0,
    "seed": 42,
    "territories": 0
  }
}

More from the server's description:

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. That makes it the right tool for deciding which stops belong TOGETHER and the wrong one for deciding what ORDER to visit them in. 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.

replan_routes

Re-plan a fleet part-way through its shift. Send the day back; nothing is stored.

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Caveats the server states:

• 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 ORIGINAL 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.
• 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.

Inputs

ReplanChangesSpec: What has changed about the work since the plan was made.

ReplanProgressSpec: One vehicle's progress through its shift.

Output

Example (called 2026-11-05)

{
  "vehicles": [
    {
      "id": 1,
      "start": {
        "lat": 51.5007,
        "lon": -0.1246
      },
      "end": {
        "lat": 51.5007,
        "lon": -0.1246
      }
    }
  ],
  "jobs": [
    {
      "id": 1,
      "location": {
        "lat": 51.5308,
        "lon": -0.1238
      }
    },
    {
      "id": 2,
      "location": {
        "lat": 51.5194,
        "lon": -0.127
      }
    }
  ],
  "costing": "auto",
  "progress": [
    {
      "vehicle": 1,
      "completed_stop_ids": [
        1
      ]
    }
  ]
}

Result (trimmed):

{
  "profile": "auto",
  "replan": {
    "basis": "MapMap stores no dispatch state. Completed stops are locked by removing them fro…",
    "changes_applied": {
      "added_jobs": [],
      "added_shipments": [],
      "cancelled_jobs": [],
      "completed_stops": 1,
      "vehicles_unavailable": []
    },
    "locked_stops_per_vehicle": [
      {
        "start_basis": "last_completed_stop",
        "start_from": "{…}",
        "stops": [
          1
        ],
        "unavailable": false,
        "vehicle": 1
      }
    ],
    "mechanism": "locked-prefix elision",
    "notes": [],
    "released_stops": []
  },
  "routes": [
    {
      "distance_m": 4288,
      "duration_s": 770,
      "service_s": 0,
      "steps": [
        "{…}",
        "{…}",
        "… 1 more"
      ],
      "vehicle": 1,
      "waiting_time_s": 0
    }
  ],
  "summary": {
    "cost": 770,
    "distance_m": 4288,
    "duration_s": 770,
    "routes": 1,
    "service_s": 0,
    "unassigned": 0,
    "waiting_time_s": 0
  },
  "unassigned": [],
  "zones": {
    "at_locations": [
      {
        "assessment": "unknown",
        "currency": "GBP",
        "daily_charge": null,
        "enforcement": "charge",
        "id": "gb-london-lez",
        "locations_inside": 3,
        "name": "London Low Emission Zone",
        "operator": "Transport for London",
        "source": "{…}",
        "type": "lez"
      },
      {
        "assessment": "unknown",
        "currency": "GBP",
        "daily_charge": null,
        "enforcement": "charge",
        "id": "gb-london-ulez",
        "locations_inside": 3,
        "name": "London Ultra Low Emission Zone",
        "operator": "Transport for London",
        "source": "{…}",
        "type": "ulez"
      }
    ],
    "basis": "the optimiser is fed a travel-time matrix, not road geometry, so this block repo…",
    "caveats": "Zone boundaries are simplified from the published geometry to the tolerance stat…",
    "note": "charge depends on vehicle emissions, supply `emissions` (vehicle_category, fuel,…"
  }
}

More from the server's description:

At least one progress entry or one change is required. Requires the MapMap gateway.

plan_day

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.

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Inputs

PlanDayStopInput: One stop of a plan_day itinerary: an exact location, or a free-text name to geocode (ambiguous matches are flagged in the response, never guessed silently).

Output

ReturnLeg: The return leg of a return_to_start plan.

PlanStart: The day's starting point as resolved.

StopResolution: How a free-text stop name was resolved to coordinates.

PlannedStop: One planned stop with its leg and ETAs.

Example (called 2026-11-05)

{
  "start": {
    "location": {
      "lat": 51.5007,
      "lon": -0.1246
    }
  },
  "stops": [
    {
      "location": {
        "lat": 51.5308,
        "lon": -0.1238
      },
      "dwell_minutes": 15
    },
    {
      "location": {
        "lat": 51.5194,
        "lon": -0.127
      }
    }
  ],
  "costing": "auto"
}

Result (trimmed):

{
  "costing": "auto",
  "finish_offset_s": 2120.168,
  "geometry_polyline6": "gejfaB~zrFDCRGXC^?rCXvD`@|@H`@J`@\\\\b@P^Pf@Nd@Px@Jp@HfA@fAC`Aq@fKeA|OK`ASlAY|@_@r…",
  "optimised": false,
  "start": {
    "location": {
      "lat": 51.5007,
      "lon": -0.1246
    }
  },
  "stops": [
    {
      "arrival_offset_s": 917.918,
      "departure_offset_s": 1817.9180000000001,
      "dwell_minutes": 15,
      "input_index": 0,
      "location": {
        "lat": 51.5308,
        "lon": -0.1238
      },
      "travel_distance_m": 5106,
      "travel_duration_s": 917.918
    },
    {
      "arrival_offset_s": 2120.168,
      "departure_offset_s": 2120.168,
      "dwell_minutes": 0,
      "input_index": 1,
      "location": {
        "lat": 51.5194,
        "lon": -0.127
      },
      "travel_distance_m": 1724,
      "travel_duration_s": 302.25
    }
  ],
  "summary": "2 stops, 6.8 km, 20 min travelling + 15 min at stops",
  "total_distance_m": 6830,
  "total_dwell_s": 900,
  "total_travel_duration_s": 1220.168,
  "view_url": "https://mapmap.ai/view?p=eyJ2IjoxLCJraW5kIjoicGxhbiIsImNvc3RpbmciOiJhdXRvIiwicm9…"
}

More from the server's description:

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.

plan_errands

Order a handful of errands against a hard arrival time, and say honestly whether they fit.

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Caveats the server states:

• Resolve a named place with geocode first and pass the coordinate: never invent one.
• 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.
• 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.

Inputs

ErrandSpec: One errand in a plan_errands chain: a kind of place to find, or a place the caller already knows.

Output

ErrandStop: One planned stop in an errand chain.

Example (called 2026-11-05)

{
  "origin": {
    "lat": 51.5007,
    "lon": -0.1246
  },
  "destination": {
    "lat": 51.5308,
    "lon": -0.1238
  },
  "arrive_by": "2026-11-05T11:57:15Z",
  "errands": [
    {
      "category": "pharmacy"
    }
  ]
}

Result (trimmed):

{
  "arrival": "2026-11-05T09:17:32Z",
  "arrive_by": "2026-11-05T11:57:15Z",
  "attribution": "Place data © OpenStreetMap contributors, ODbL.",
  "corridor_note": "Candidates come from the corridor of the direct route. A place further off it th…",
  "departure": "2026-11-05T08:57:15Z",
  "dropped": [],
  "feasible": true,
  "geometry_polyline6": "gejfaB~zrFDCRGXC^?rCXvD`@|@H`@J`@\\\\b@P^Pf@Nd@Px@Jp@HfA@fAC`Aq@fKeA|OK`ASlAY|@_@r…",
  "opening_hours_note": "Opening hours come from OpenStreetMap's `opening_hours` tag, which most places d…",
  "slack_s": 9582.5,
  "stops": [
    {
      "arrive": "2026-11-05T09:05:16Z",
      "depart": "2026-11-05T09:10:16Z",
      "drive_s": 480.8,
      "errand": "pharmacy",
      "hours": "unknown",
      "id": "osm:n13260552152:poi",
      "kind": "category",
      "label": "Kerrs, BLOOMSBURY WAY 41, London, Knepp Wildland, United Kingdom",
      "lat": 51.5173794,
      "lon": -0.1250005,
      "name": "Kerrs"
    }
  ],
  "total_drive_s": 916.8,
  "total_dwell_s": 300,
  "usage_note": "Plan before setting off, or let a passenger do it. Stating a request like this i…",
  "…": "1 more fields"
}

More from the server's description:

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"). Optional dwell_minutes per errand (default 5). 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. Requires the MapMap gateway.

plan_ev_route

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.

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Caveats the server states:

• 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.
• 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.
• Display the returned charging_attribution with the plan.

Inputs

EvVehicleSpec: The vehicle for plan_ev_route: one of the published defaults by name, inline figures, or a named default with inline figures over it.

Output

EvPlanLeg: One driving leg of the plan, with its state-of-charge bookkeeping.

EvPlanSocPoint: One point on the state-of-charge trace.

EvPlanStop: One charge stop in the plan.

EvPlanSummary: The plan at a glance.

Example (called 2026-11-05)

{
  "origin": {
    "lat": 51.5074,
    "lon": -0.1278
  },
  "destination": {
    "lat": 52.4862,
    "lon": -1.8904
  },
  "vehicle": {
    "profile": "saloon"
  }
}

Result (trimmed):

{
  "availability_live": false,
  "coverage_note": "Covers 6050 charge point(s) (6052 charging position(s)) from char.gy (on-street …",
  "feasible": true,
  "geometry_polyline6": "kpwfaBx|xFQU]i@]o@_@iA]yAWuBSsBM_D@sCLuBXyA^}Ap@cBb@aAb@m@^]PGb@CfANnA\\x@\\x@r@~A…",
  "gradient_data": "complete",
  "legs": [
    {
      "consumed_wh": 21581.3,
      "distance_m": 189635,
      "duration_s": 8291.3,
      "end_soc": 0.523,
      "from": "origin",
      "min_soc": 0.523,
      "regen_wh": 68.7,
      "start_soc": 0.9,
      "to": "destination"
    }
  ],
  "profile_source": "default",
  "route_distance_m": 189635,
  "route_duration_s": 8291.3,
  "soc_trace": [
    {
      "along_route_position": 0,
      "at": "origin",
      "soc": 0.9
    },
    {
      "along_route_position": 1,
      "at": "destination",
      "soc": 0.523
    }
  ],
  "stops": [],
  "summary": {
    "arrival_soc": 0.523,
    "energy_kwh": 21.51,
    "start_soc": 0.9,
    "stops": 0,
    "total_charge_s": 0,
    "total_distance_m": 189635,
    "total_drive_s": 8291.3,
    "total_duration_s": 8291.3
  },
  "vehicle": "saloon (Tesla Model 3 RWD, Highland)"
}

More from the server's description:

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. Requires the MapMap gateway; answers a clear error when the deployment has no charge-point dataset.

Along-route search

Places, fuel and charge points along a route, each priced by its real detour.

search_along_route

Find places (POIs) along a route with the REAL extra travel time of stopping at each, never a straight-line guess.

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Inputs

Output

AlongRouteHit: One place found along the route, with its honest detour cost.

Example (called 2026-11-05)

{
  "origin": {
    "lat": 51.5007,
    "lon": -0.1246
  },
  "destination": {
    "lat": 51.5308,
    "lon": -0.1238
  },
  "query": "cafe",
  "category": "cafe"
}

Result (trimmed):

{
  "candidate_cap": 25,
  "candidates_considered": 42,
  "candidates_costed": 25,
  "costing": "auto",
  "matched_categories": [
    "cafe"
  ],
  "max_detour_minutes": 10,
  "query": "cafe",
  "results": [
    {
      "along_route_position": 0.776,
      "detour_km": 0,
      "detour_minutes": 0,
      "detour_s": 0,
      "off_route_m": 13,
      "place": {
        "label": "Cafe Angel, London, City of London, Knepp Wildland, United Kingdom",
        "lat": 51.524764100000006,
        "lon": -0.1161125,
        "name": "Cafe Angel",
        "type": "cafe"
      }
    },
    {
      "along_route_position": 0.567,
      "detour_km": 0,
      "detour_minutes": 0,
      "detour_s": 0,
      "off_route_m": 73,
      "place": {
        "label": "Espresso House, London, Knepp Wildland, United Kingdom",
        "lat": 51.51825,
        "lon": -0.120913,
        "name": "Espresso House",
        "type": "cafe"
      }
    },
    "… 3 more"
  ],
  "route_distance_m": 5105,
  "route_duration_s": 917.823,
  "route_length_m": 5098
}

More from the server's description:

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

cheapest_fuel_along_route

Find the cheapest fuel along a route, with the REAL extra travel time of stopping at each station, never a straight-line guess.

Access: Keyless. Answers without a key on the hosted endpoint under fair use; present your own key to meter it to you.

Caveats the server states:

• 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".
• Display the returned fuel_attribution with the prices.

Inputs

Output

FuelBaseline: The cheapest effectively-on-route option in one currency, what the driver pays by just pulling in without a detour; the reference the per-result savings are computed against. Only a fresh price is eligible, so this is stale: false by construction.