Skip to content
Documentation menu
docs / api / post-v1-charging-along
EV charging

POST/v1/charging/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

Best EV chargers 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/charging/along" \
  -H "Authorization: Bearer $MAPMAP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"connectors":["ccs"],"destination":{"lat":53.48,"lon":-2.24},"max_detour_minutes":8,"min_kw":50,"origin":{"lat":51.75,"lon":-1.26}}'

Request body

application/json

EV charge-point search: a route (geometry_polyline6, or origin + destination + costing), an optional connectors filter (type2, ccs, chademo, tesla, type1, domestic, other), min_kw, available_only (needs an availability overlay), max_detour_minutes (default 10, max 120), max_results (default 5, max 25), Valhalla costing_options and an optional top-level adr profile

Example: From website/public/docs/analysis.md:1557

json
{
  "connectors": [
    "ccs"
  ],
  "destination": {
    "lat": 53.48,
    "lon": -2.24
  },
  "max_detour_minutes": 8,
  "min_kw": 50,
  "origin": {
    "lat": 51.75,
    "lon": -1.26
  }
}

Responses

200Charge points matching the filters within the detour budget, most powerful first: {costing, route, max_detour_minutes, filters: {connectors, min_kw, available_only}, candidates: {considered, costed, cap}, coverage: {chargers, evses, countries, sources}, coverage_note (ALWAYS present; an empty results array means none from these operators, never no chargers here), sources[]: {source_id, operator, chargers, coverage_note, licence}, availability: {live, note}, note (only when results is empty, naming which cause applies), results[]: {charger_id, source, operator, name, lat, lon, max_power_kw, connector_standards, evse_count, best_connector (the best of the standards the request filtered on, the site's best when it filtered on none), status, status_live, available_now, detour_minutes, detour_km, along_route_position, off_route_m, updated_at}, say, charging_attribution}. say is the whole answer as one short spoken line, present on every response including an empty one, and it scopes its claim to the operators this deployment covers. Detours are engine-computed, never crow-flies
FieldTypeRequiredDescription
availabilityobjectnoWhether statuses are live, and what they are when not.
candidatesobjectnoHow many charge points were near the route, costed and the cap.
costingstringnoThe costing used for the route and detours.
coverageobjectnoCharge points and positions covered, by country and source.
coverage_notestringnoWhich operators are covered. An empty result means none from these operators, never no chargers.
eta_calibrationobjectnoThe typical-delay calibration applied to the route times.
filtersobjectnoThe connector and power filters applied.
max_detour_minutesnumbernoThe detour ceiling applied, in minutes.
notestringnoWhat the result means, when it needs saying (for example an empty result).
resultsobject[]noCharge points within the ceiling, most powerful first: operator, name, max_power_kw, connector_standards, best_connector, status_live, updated_at and the detour fields.
routeobjectnoThe base route: distance, duration and the detour baseline.
saystringnoOne sentence to read aloud.
sourcesobject[]noEach data source with its count and coverage note.

Example: Recorded from the hosted gateway on 2026-11-05 with a test key: POST /v1/charging/along, Brixton to Brighton, CCS at 50 kW or more; lists trimmed to their first items

json
{
  "availability": {
    "live": false,
    "note": "No live availability feed is configured, so every status is the value captured when the dataset was last ingested, not what the bay is doing now. Supply your operator's OCPI feed to make these live."
  },
  "candidates": {
    "cap": 25,
    "considered": 0,
    "costed": 0
  },
  "costing": "auto",
  "coverage": {
    "chargers": 6052,
    "countries": [
      "GB"
    ],
    "evses": 6054,
    "sources": {
      "chargy": 6052
    }
  },
  "coverage_note": "Covers 6052 charge point(s) (6054 charging position(s)) from char.gy (on-street lamppost charging). Charge points from any operator not listed are absent from this dataset entirely, so an empty result means \"none from these operators\", never \"no chargers here\".",
  "eta_calibration": {
    "added_s": 935.9,
    "alternates_added_s": [],
    "applied": true,
    "bands": {
      "built_up": {
        "added_s": 892.8,
        "distance_m": 17010.6
      },
      "intermediate": {
        "added_s": 18.5,
        "distance_m": 1376.1
      },
      "open_road": {
        "added_s": 24.6,
        "distance_m": 1678.6
      }
    },
    "engine_time_s": 4433.776,
    "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. 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, and the route itself is unchanged.",
    "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"
    ],
    "traffic_network_m": 7752.2
  },
  "filters": {
    "available_only": false,
    "connectors": [
      "ccs"
    ],
    "min_kw": 50
  },
  "max_detour_minutes": 5,
  "note": "No charge point matching connectors ccs and at least 50 kW lies near this route, out of the 6052 this deployment carries from char.gy (on-street lamppost charging). See `coverage_note` for what that does and does not include.",
  "results": [],
  "route": {
    "detour_baseline_m": null,
    "detour_baseline_s": null,
    "distance_m": 79640,
    "duration_s": 5369.673,
    "length_m": 79549
  },
  "say": "No charge point we cover with a CCS connector at 50 kilowatts or more is near this route. We cover char.gy only, so this says nothing about others.",
  "sources": [
    {
      "chargers": 6052,
      "coverage_note": "On-street lamppost charging in char.gy's partner boroughs only: no rapid hubs, no forecourts and no other operator's network.",
      "licence": "Public Charge Point Regulations 2023",
      "operator": "char.gy (on-street lamppost charging)",
      "source_id": "chargy"
    }
  ]
}
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 charge-point dataset is not enabled (SN_CHARGE_DIR 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.

Also under EV charging

Generated from https://api.mapmap.ai/openapi.json on 2026-11-12 · operationId post_charging_along