Skip to content
Documentation menu
docs / api / post-v1-fuel-along
Fuel

POST/v1/fuel/along

Access and price

AuthAn API key, as Authorization: Bearer snk_… or ?api_key=snk_…. Metered. Needs a full key; a browser (maps) key is refused.
PriceA 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.
PremiumWhen 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

bash
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

json
{
  "destination": {
    "lat": 53.48,
    "lon": -2.24
  },
  "fill_litres": 55,
  "fuel": "diesel",
  "max_detour_minutes": 8,
  "origin": {
    "lat": 51.75,
    "lon": -1.26
  }
}

Responses

200Stations selling the requested fuel within the detour budget, freshest-priced first and cheapest within that: {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
FieldTypeRequiredDescription
baselineobjectnoThe cheapest station on the route itself, per currency, that a saving is measured against.
candidatesobjectnoHow many stations were near the route, costed and the cap.
costingstringnoThe costing used for the route and detours.
coverageobjectnoPrice feed coverage: countries, stations per source and a statement of what is and is not covered.
eta_calibrationobjectnoThe typical-delay calibration applied to the route times.
fuelstringnoThe fuel asked for.
fuel_attributionstringnoPrice data attribution.
max_detour_minutesnumbernoThe detour ceiling applied, in minutes.
resultsobject[]noStations 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.
routeobjectnoThe base route: distance, duration and the detour baseline.
saystringnoOne 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

json
{
  "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."
}
400Invalid request

application/problem+json · Problem

401Missing or invalid API key. Also: No key, or a missing, malformed, unknown, revoked or expired one (unauthorized); the body carries signup, docs and a one-call hint for a free key

application/problem+json · Problem

402Beyond the included volume with no way to pay this call: an x402 body naming how to pay (provisional key past its allowance, prepaid balance below the price, or a rejected X-PAYMENT). Not problem+json

application/json · X402PaymentRequired

403The key may not call this: a browser key outside its scope (scope-insufficient), a request from an origin the key does not allow (origin-not-allowed), or an account restriction (forbidden)

application/problem+json · Problem

413The request declares a body larger than 1048576 bytes (plain text, not problem+json)

text/plain

429Quota or rate limit exceeded. Also: Per-key rate limit (rate-limited, with Retry-After), or monthly quota exhausted with no payment path (quota-exceeded)

application/problem+json · Problem

501The fuel-price dataset is not enabled (SN_FUEL_PRICES unset)

application/problem+json · Problem

502Upstream routing engine failed

application/problem+json · Problem

504The request did not finish within the gateway's request deadline (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