API reference
Version 1, read-only, JSON. No key is required in this phase. Lengths are in millimetres and power in watts. Records describe parameters only; your robot decides whether a charger fits.
- Errors return
{ "error": { "code", "message", "details"? } }with status 400, 404, 429, 500, 502 or 503. - Unknown query parameters are rejected with 400 so typos do not silently widen a search.
- Private chargers return a rounded area centre with
approximate: trueandprecision_m >= 500. Exact positions are never returned.
Search chargers by radius
GET/api/v1/chargers?lat=&lng=&radius_m=&interface=&step_free=
Returns at most 100 chargers ordered by distance from the query point. Each result has a distance_m field.
| Parameter | Type | Description |
|---|---|---|
| lat | number | Required. Latitude of the search centre, -90 to 90. |
| lng | number | Required. Longitude of the search centre, -180 to 180. |
| radius_m | integer | Optional, default 5000. Search radius in metres, 1 to 50000. |
| interface | slug | Optional. Only chargers with a connector of this interface. |
| step_free | boolean | Optional. true = steps_count is 0 and threshold_height_mm <= 20. |
| max_step_height_mm | integer | Optional robot profile. Excludes chargers whose known threshold is higher. |
| min_passage_width_mm | integer | Optional robot profile. Excludes chargers whose known approach width is narrower. |
| worst_surface | surface | Optional robot profile, e.g. sett. Worst acceptable surface; excludes chargers with a known rougher surface. |
| can_use_elevator | boolean | Optional robot profile. false excludes chargers that are known to need an elevator. |
curl "https://<host>/api/v1/chargers?lat=51.1079&lng=17.0385&radius_m=1000"{
"data": [
{
"id": "10000000-0000-4000-8000-000000000006",
"name": "Demo: Shopping Arcade Service Bay",
"visibility": "public",
"is_demo": true,
"location": {
"lat": 51.1075,
"lng": 17.0405,
"precision_m": 5,
"approximate": false,
"indoor": true
},
"connectors": [
{
"id": "2b839306-5072-4590-b569-f6fd3e4d535b",
"interface": {
"kind": "contact",
"name": "Demo Contact Dock A",
"slug": "demo-contact-dock-a"
},
"max_power_w": 450,
"mounting_height_mm": 0,
"pad": null
}
],
"access": {
"surface": "vinyl",
"door_type": "automatic",
"steps_count": 0,
"elevator_required": true,
"threshold_height_mm": 5,
"min_passage_width_mm": 1100,
"step_free": true
},
"availability": {
"opening_hours": "Mo-Sa 09:00-21:00"
},
"trust": {
"last_verified_at": "2026-08-19T00:56:43.845795+00:00",
"verified_by": "robot:demo-unit-02",
"status": "verified",
"max_age_days": 180
},
"created_at": "2026-11-17T00:56:43.845795+00:00",
"updated_at": "2026-11-17T00:56:43.845795+00:00",
"distance_m": 147
}
],
"meta": {
"count": 1,
"max_results": 100,
"verification_max_age_days": 180,
"query": {
"lat": 51.1079,
"lng": 17.0385,
"radius_m": 1000,
"interface": null,
"step_free": false
}
}
}{
"error": {
"code": "invalid_request",
"message": "radius_m: radius_m must be between 1 and 50000",
"details": [
{
"param": "radius_m",
"message": "radius_m must be between 1 and 50000"
}
]
}
}Get one charger
GET/api/v1/chargers/{id}
id must be a UUID (400 otherwise). Unknown ids return 404. The record has no distance_m.
curl "https://<host>/api/v1/chargers/10000000-0000-4000-8000-000000000006"{
"data": {
"id": "10000000-0000-4000-8000-000000000006",
"name": "Demo: Shopping Arcade Service Bay",
"visibility": "public",
"is_demo": true,
"location": {
"lat": 51.1075,
"lng": 17.0405,
"precision_m": 5,
"approximate": false,
"indoor": true
},
"connectors": [
{
"id": "2b839306-5072-4590-b569-f6fd3e4d535b",
"interface": {
"kind": "contact",
"name": "Demo Contact Dock A",
"slug": "demo-contact-dock-a"
},
"max_power_w": 450,
"mounting_height_mm": 0,
"pad": null
}
],
"access": {
"surface": "vinyl",
"door_type": "automatic",
"steps_count": 0,
"elevator_required": true,
"threshold_height_mm": 5,
"min_passage_width_mm": 1100,
"step_free": true
},
"availability": {
"opening_hours": "Mo-Sa 09:00-21:00"
},
"trust": {
"last_verified_at": "2026-08-19T00:56:43.845795+00:00",
"verified_by": "robot:demo-unit-02",
"status": "verified",
"max_age_days": 180
},
"created_at": "2026-11-17T00:56:43.845795+00:00",
"updated_at": "2026-11-17T00:56:43.845795+00:00"
}
}Plan a route to a charger
POST/api/v1/route
Routes over public footways with openrouteservice's wheelchair profile, constrained by an optional robot profile. Every field in profile is optional; unknown fields are rejected. Only public chargers can be routed to (private ones return 404). Results are cached and requests are rate limited per client (429 with Retry-After). If routing is not configured the endpoint returns 503.
geometryis a GeoJSON LineString;warnings[].rangeandsteps[].rangeindex into its coordinates.duration_sourceisprofile_speedwhen you sendspeed_mps, otherwise a provider wheelchair-speed estimate.charger_access.statusisok,failorunknownwhen the record lacks the data. A route is guidance, not a guarantee of passability.fromis snapped to the nearest routable way within 100 m;start_snapped_togives the snapped point and distance, and astart_snappedwarning is added when it moved by 1 m or more.- Send exactly one of
charger_idorto: { lat, lng }(400 otherwise). Withtothe response hasdestination_ad_hoc: true,charger_id: nullandcharger_access.status: unknown. The same distance limit, cache and rate limit apply. Nothing is stored. profile.worst_surfaceis a threshold: that surface and every smoother one are allowed. Accepted values, smoothest first: paved, asphalt, concrete, paving_stones, concrete:plates, sett, cobblestone:flattened, unhewn_cobblestone, concrete:lanes, cobblestone, unpaved, fine_gravel, compacted, metal, ice, grass_paver, sand, dirt, earth, grass, gravel, ground, mud, pebblestone, salt, snow, wood, woodchips. Any other value returns 400. For charger access checks, indoor tile, vinyl and polished stone count as smooth; carpet and unrecorded surfaces giveunknown.
| Warning code | Meaning |
|---|---|
| start_snapped | from was moved by 1 m or more to reach the footway network. |
| kerb_stricter_than_provider | max_step_height_mm is below 30 mm. The provider is asked for its strictest sloped-kerb filter (0.03 m), so kerbs between your value and 30 mm are not excluded. details: { requested_mm, provider_min_mm: 30 }. |
| incline_approximated | max_incline_pct is not one of the provider values; the next stricter value was used. |
| charger_access_* | The charger record fails or lacks data for part of the profile. |
| Status | code | Meaning |
|---|---|---|
| 422 | start_not_routable | No routable way within 100 m of from, or the nearest way is not connected to the network that reaches the charger. |
| 422 | destination_not_routable | The charger or to point has no routable way within 350 m. |
| 422 | no_route_for_profile | The start is routable without restrictions, but no route satisfies the profile. |
| 422 | route_too_long | The route is longer than the footway routing limit. |
| 502 | provider_error | Any other routing provider failure. |
| 504 | routing_timeout | The routing provider did not respond in time. |
| 503 | routing_quota_exceeded | The provider quota is exhausted; see Retry-After. |
curl -X POST "https://<host>/api/v1/route" \
-H "Content-Type: application/json" \
-d '{"from":{"lat":51.1079,"lng":17.0385},"charger_id":"<uuid>","profile":{"max_step_height_mm":30,"min_passage_width_mm":700,"max_incline_pct":6,"worst_surface":"sett","can_use_elevator":false,"speed_mps":1.2}}'curl -X POST "https://<host>/api/v1/route" \
-H "Content-Type: application/json" \
-d '{"from":{"lat":51.1079,"lng":17.0385},"to":{"lat":51.1099,"lng":17.040499999999998},"profile":{"max_step_height_mm":80,"worst_surface":"cobblestone"}}'List interfaces
GET/api/v1/interfaces
curl "https://<host>/api/v1/interfaces"{
"data": [
{
"id": "00000000-0000-4000-8000-000000000001",
"slug": "demo-contact-dock-a",
"name": "Demo Contact Dock A",
"vendor": null,
"kind": "contact",
"notes": "Placeholder floor dock with two spring contacts. Fictional, for demonstration only.",
"source_url": null,
"is_demo": true,
"created_at": "2026-11-17T00:56:43.845795+00:00",
"updated_at": "2026-11-17T00:56:43.845795+00:00"
}
],
"meta": {
"count": 1
}
}Charger record JSON Schema
JSON Schema (draft 2020-12) for each item in data.
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "/api/v1/schemas/charger-record.json",
"title": "ChargerRecord",
"description": "One charger as returned by the v1 API. All lengths are in millimetres, power in watts. The registry states parameters; it does not certify compatibility.",
"type": "object",
"required": [
"id",
"name",
"visibility",
"is_demo",
"location",
"connectors",
"access",
"availability",
"trust",
"created_at",
"updated_at"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"visibility": {
"enum": [
"public",
"private"
]
},
"is_demo": {
"type": "boolean",
"description": "True for fictional demonstration records."
},
"location": {
"type": "object",
"required": [
"lat",
"lng",
"precision_m",
"approximate",
"indoor"
],
"additionalProperties": false,
"properties": {
"lat": {
"type": "number",
"minimum": -90,
"maximum": 90
},
"lng": {
"type": "number",
"minimum": -180,
"maximum": 180
},
"precision_m": {
"type": "integer",
"minimum": 0,
"description": "Radius in metres within which the charger lies. At least 500 for private chargers."
},
"approximate": {
"type": "boolean",
"description": "True for private chargers: lat/lng is a rounded area centre, never the exact position."
},
"indoor": {
"type": "boolean"
}
}
},
"distance_m": {
"type": "integer",
"minimum": 0,
"description": "Only in radius search results. Distance from the query point to location.lat/lng."
},
"connectors": {
"type": "array",
"items": {
"type": "object",
"required": [
"id",
"interface",
"max_power_w",
"mounting_height_mm",
"pad"
],
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"interface": {
"type": "object",
"required": [
"slug",
"name",
"kind"
],
"properties": {
"slug": {
"type": "string"
},
"name": {
"type": "string"
},
"kind": {
"enum": [
"contact",
"plug",
"inductive",
"battery_swap"
]
}
}
},
"max_power_w": {
"type": [
"integer",
"null"
],
"minimum": 1
},
"mounting_height_mm": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Height of the connector above the floor."
},
"pad": {
"type": [
"object",
"null"
],
"description": "Only present for inductive interfaces.",
"properties": {
"width_mm": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Pad width."
},
"length_mm": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Pad length."
}
}
}
}
}
},
"access": {
"type": [
"object",
"null"
],
"description": "Physical access from the nearest public way to the charger. Null when not recorded.",
"required": [
"steps_count",
"threshold_height_mm",
"door_type",
"min_passage_width_mm",
"surface",
"elevator_required",
"step_free"
],
"properties": {
"steps_count": {
"type": "integer",
"minimum": 0
},
"threshold_height_mm": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Highest threshold on the route."
},
"door_type": {
"enum": [
"none",
"manual",
"automatic",
"revolving"
]
},
"min_passage_width_mm": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Narrowest passage on the route."
},
"surface": {
"type": [
"string",
"null"
]
},
"elevator_required": {
"type": "boolean"
},
"step_free": {
"type": "boolean",
"description": "Derived: steps_count = 0 and threshold_height_mm <= 20."
}
}
},
"availability": {
"type": "object",
"required": [
"opening_hours"
],
"properties": {
"opening_hours": {
"type": [
"string",
"null"
],
"description": "OpenStreetMap opening_hours syntax, e.g. \"Mo-Fr 08:00-18:00\"."
}
}
},
"trust": {
"type": "object",
"required": [
"last_verified_at",
"verified_by",
"status",
"max_age_days"
],
"properties": {
"last_verified_at": {
"type": [
"string",
"null"
],
"format": "date-time"
},
"verified_by": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"verified",
"unverified"
],
"description": "Derived: \"unverified\" when last_verified_at is null or older than 180 days."
},
"max_age_days": {
"type": "integer",
"const": 180
}
}
},
"created_at": {
"type": "string",
"format": "date-time"
},
"updated_at": {
"type": "string",
"format": "date-time"
}
}
}Changelog
- Breaking:
allowed_surfacesis replaced byworst_surfacein the route profile and the chargers search. It is a single threshold in the provider's surface order; unknown values and the old field return 400. POST /api/v1/routeacceptsto: { lat, lng }instead ofcharger_id. Addsdestination_ad_hocand the 422 errordestination_not_routable.- New route warning
kerb_stricter_than_providerwhenmax_step_height_mmis below 30 mm.