Documentation menu
POST/v1/fuel/along
Access and price
| Auth | An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Needs a full key; a browser (maps) key is refused. |
|---|---|
| Price | A flat 10 calls, whatever max_results asks for. Class: standard, or premium for truck and ADR work. Published as unit_rules.along_route in /pricing.json. |
| Premium | When the body asks for truck routing: "costing": "truck", a top-level adr object or "hazmat": true |
What it does
Cheapest fuel along a route.
An API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Price: A flat 10 calls, whatever max_results asks for.
Call it
curl -fsS -X POST "https://api.mapmap.ai/v1/fuel/along" \
-H "Authorization: Bearer $MAPMAP_KEY" \
-H "Content-Type: application/json" \
-d '{"destination":{"lat":53.48,"lon":-2.24},"fill_litres":55,"fuel":"diesel","max_detour_minutes":8,"origin":{"lat":51.75,"lon":-1.26}}'Request body
application/json
Cheapest-fuel search: a route (geometry_polyline6, or origin + destination + costing), a fuel code (default diesel), optional max_detour_minutes (default 10, max 120), max_results (default 5, max 25), fill_litres (adds saving_total per result), Valhalla costing_options and an optional top-level adr profile
Example: From website/public/docs/analysis.md:1388
{
"destination": {
"lat": 53.48,
"lon": -2.24
},
"fill_litres": 55,
"fuel": "diesel",
"max_detour_minutes": 8,
"origin": {
"lat": 51.75,
"lon": -1.26
}
}Responses
{fuel, costing, route: {duration_s, distance_m, length_m, detour_baseline_s, detour_baseline_m}, max_detour_minutes, candidates: {considered, costed, cap, selection}, coverage: {stations, countries, sources}, note (only when results is empty, naming which of the several causes applies), baseline: {<currency>: {value, station_id, brand, name, updated_at}}, results[]: {station_id, source, brand, name, lat, lon, price: {value, currency, updated_at, fetched_at}, stale, detour_minutes, detour_km, along_route_position, off_route_m, saving_per_litre, saving_total}, say, fuel_attribution}. route.duration_s/distance_m are the path search's own figures, the same journey POST /route answers; detour_baseline_* is the matrix leg every detour is computed against. The 25 costed candidates are those nearest the route by the straight-line detour bound (candidates.selection), and the baseline is a station that passed the detour filter, so a saving is never quoted against one the results could not contain. say is the whole answer as one short spoken line, present on every response including an empty one. Detours are engine-computed, never crow-flies. stale is true unless BOTH the price's own updated_at and the snapshot's fetch time are within 24 hours; a stale price is ranked after every fresh one, is never the baseline, and carries no saving_per_litre| Field | Type | Required | Description |
|---|---|---|---|
| baseline | object | no | The cheapest station on the route itself, per currency, that a saving is measured against. |
| candidates | object | no | How many stations were near the route, costed and the cap. |
| costing | string | no | The costing used for the route and detours. |
| coverage | object | no | Price feed coverage: countries, stations per source and a
statement of what is and is not covered. |
| eta_calibration | object | no | The typical-delay calibration applied to the route times. |
| fuel | string | no | The fuel asked for. |
| fuel_attribution | string | no | Price data attribution. |
| max_detour_minutes | number | no | The detour ceiling applied, in minutes. |
| results | object[] | no | Stations within the ceiling, cheapest first: brand, name,
price, stale, detour_s, detour_minutes,
along_route_position, and saving_per_litre and
saving_total against the baseline. |
| route | object | no | The base route: distance, duration and the detour baseline. |
| say | string | no | One sentence to read aloud. |
Example: Recorded from the hosted gateway on 2026-11-05 with a test key: POST /v1/fuel/along, diesel from Brixton to Brighton; lists trimmed to their first items
{
"baseline": {
"GBP": {
"brand": "ESSO",
"name": "DYKE ROAD, HOVE",
"stale": false,
"station_id": "esso:gcpchqyfthzc",
"updated_at": "05/11/2026 00:05:14",
"value": 1.969
}
},
"candidates": {
"cap": 25,
"considered": 58,
"costed": 25,
"selection": "nearest-by-lower-bound"
},
"costing": "auto",
"coverage": {
"countries": [
"DE",
"FR",
"GB"
],
"sources": {
"de": 1907,
"fr": 9825,
"uk": 1919
},
"statement": "UK prices come only from the feeds of 8 retailers: Asda (790), Shell (546), Rontec (265), Esso (194), Applegreen (65), Moto (47), Jet (11), Morrisons (1), 1919 stations in all. Forecourts run by any other retailer are not in this dataset, so a UK route with no result may still have fuel.",
"stations": 13651,
"uk_partial": true,
"uk_retailers": [
{
"name": "Asda",
"stations": 790
},
{
"name": "Shell",
"stations": 546
}
]
},
"eta_calibration": {
"applied": true,
"cells_calibrated": 51,
"cells_not_walked": 0,
"cells_unchanged": 0,
"method": "gb_typical_delay_v1",
"note": "Local roads in Great Britain carry no live traffic data, so the time on them includes the junction and congestion delay a typical car meets at this time of day, from Department for Transport statistics, on top of the routing engine's free-flowing time: the same delay POST /route adds, applied to the path each cell was costed on. It is a typical figure, not live traffic. Motorways, roads covered by National Highways traffic data and roads outside Great Britain keep the engine's own time.",
"period": "all_day",
"sources": [
"Department for Transport, tables CGN0503 and CGN0504: average speed and delay on local 'A' roads in England, urban and rural, by time of day, rolling year to June 2026"
]
},
"fuel": "diesel",
"fuel_attribution": "Fuel prices: UK retailer scheme (CMA)",
"max_detour_minutes": 5,
"results": [
{
"along_route_position": 0.978,
"brand": "ESSO",
"detour_km": 0,
"detour_minutes": 0,
"detour_s": 0,
"lat": 50.838315,
"lon": -0.1553,
"name": "DYKE ROAD, HOVE",
"off_route_m": 24,
"price": {
"currency": "GBP",
"fetched_at": "2026-11-05T20:20:20.493400034Z",
"updated_at": "05/11/2026 00:05:14",
"value": 1.969
},
"saving_per_litre": 0,
"saving_total": 0,
"source": "uk",
"stale": false,
"station_id": "esso:gcpchqyfthzc"
},
{
"along_route_position": 0.095,
"brand": "ESSO",
"detour_km": 0.11,
"detour_minutes": 1.2,
"detour_s": 70,
"lat": 51.396933,
"lon": -0.115952,
"name": "845-853 London Road, THORNTON HEATH",
"off_route_m": 24,
"price": {
"currency": "GBP",
"fetched_at": "2026-11-05T20:20:20.493400034Z",
"updated_at": "05/11/2026 00:05:14",
"value": 1.989
},
"saving_per_litre": -0.02,
"saving_total": -1.1,
"source": "uk",
"stale": false,
"station_id": "esso:gcpumke8f4ez"
}
],
"route": {
"detour_baseline_m": 80256,
"detour_baseline_s": 5363.795,
"distance_m": 79640,
"duration_s": 5369.673,
"length_m": 79549
},
"say": "Cheapest diesel is Esso at 196.9p a litre, and it is on your way. Nothing on your route is cheaper, so there is no saving to quote."
}application/problem+json · Problem
unauthorized); the body carries signup, docs and a one-call hint for a free keyapplication/problem+json · Problem
X-PAYMENT). Not problem+jsonapplication/json · X402PaymentRequired
scope-insufficient), a request from an origin the key does not allow (origin-not-allowed), or an account restriction (forbidden)application/problem+json · Problem
text/plain
rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)application/problem+json · Problem
application/problem+json · Problem
application/problem+json · Problem
request-timeout)application/problem+json · Problem
Error bodies follow the shared problem model documented on API conventions.
Generated from https://api.mapmap.ai/openapi.json on 2026-11-12 · operationId post_fuel_along