# Developer API

Web page: https://ampmap.co.uk/developers

Read-only JSON for chargers, live status, search and vehicles

The Amp Map site and its embeds read their data from a small JSON API. The read-only endpoints below are open to anyone: no key and no sign-up. Every response is JSON over HTTPS.

## Machine-readable descriptions

The same endpoints, described for tools and agents:

- [/openapi.json](https://ampmap.co.uk/openapi.json) - OpenAPI 3.1 description
- [/.well-known/api-catalog](https://ampmap.co.uk/.well-known/api-catalog) - API catalogue (RFC 9727)
- [/llms.txt](https://ampmap.co.uk/llms.txt) - Site summary for language models
- [/.well-known/mcp/server-card.json](https://ampmap.co.uk/.well-known/mcp/server-card.json) - MCP server card
- [/.well-known/agent-card.json](https://ampmap.co.uk/.well-known/agent-card.json) - A2A agent card
- [/.well-known/agent-skills/index.json](https://ampmap.co.uk/.well-known/agent-skills/index.json) - Agent skills index
- [/.well-known/oauth-authorization-server](https://ampmap.co.uk/.well-known/oauth-authorization-server) - OAuth authorisation server metadata (RFC 8414)
- [/.well-known/oauth-protected-resource/mcp](https://ampmap.co.uk/.well-known/oauth-protected-resource/mcp) - OAuth protected resource metadata for /mcp (RFC 9728)

## Endpoints

### GET /api/chargers

**Chargers in a map viewport** Charging locations inside a bounding box, nearest the centre first unless sorted otherwise, in the compact form the map uses. When more sites match than are returned, or the box is too wide to scan in one request, truncated is true and total gives the full count. Unknown or malformed filter values are ignored. Pass ids instead of a box to fetch saved chargers in full.

- **minLat:** South edge, decimal degrees (WGS 84). Use with the other three edges for a viewport query; an omitted edge reads as 0.
- **minLng:** West edge, decimal degrees. Use with the other three edges.
- **maxLat:** North edge, decimal degrees. Use with the other three edges.
- **maxLng:** East edge, decimal degrees. Use with the other three edges.
- **conn:** Connectors, any of: ccs, chademo, type2, j1772 (Type 1), 3pin. Comma-separated.
- **kw:** Minimum power in kW: 7, 22, 50 or 150.
- **open:** 1 = only sites with a socket free now (live status).
- **hideoff:** 1 = hide sites that are out of service.
- **network:** Network slugs, comma-separated, as in /networks/{slug}. At most 20.
- **h24:** 1 = only sites that publish 24-hour opening.
- **free:** 1 = free to use.
- **hub:** 1 = four or more chargers.
- **price:** Maximum price, pence per kWh.
- **public:** 1 = public access only.
- **rel:** 1 = in service 95% or more of the last 30 days (measured from live status).
- **sort:** Which sites fill the results when more match: near (default), price, speed, open or reliable.
- **view:** count = return only the number of matching sites. With ids, status = return only the live status fields.
- **ids:** Up to 100 charger ids, comma-separated. Returns those chargers in full instead of a viewport.

```sh
curl 'https://ampmap.co.uk/api/chargers?minLat=53.46&minLng=-2.26&maxLat=53.49&maxLng=-2.22&conn=ccs&kw=50'
```

### GET /api/chargers/{id}

**One charging location** One location in full - sockets with live status, plugs, prices, opening hours and its data sources - with measured busy times by hour, 30-day reliability and recent driver activity.

- **id required:** Charger id, as in /charger/{id}.

```sh
curl 'https://ampmap.co.uk/api/chargers/be-ev-golden-hill-uk'
```

### GET /api/search

**Search places, postcodes, chargers, networks and vehicles** What the site search box shows: matching places (with a bounding box to show on a map), a UK postcode, charging locations, networks and vehicle guides.

- **q:** Search text. Under 2 characters (or none) returns empty results; longer queries are cut to 80.

```sh
curl 'https://ampmap.co.uk/api/search?q=manchester'
```

### GET /api/embed/chargers

**Slim charger rows for widgets** Charger rows in the slim form the embeddable widgets use. Either nearest to a point (at, n, dist) or inside a bounding box (minLat, minLng, maxLat, maxLng). Network slugs that match no network return an empty list.

- **at:** Point to search from, as lng,lat in decimal degrees: latitude within ±85, at most 8 decimal places. Nearest mode.
- **n:** Nearest mode: how many chargers, 3 to 25 (default 10).
- **dist:** Nearest mode: search radius in miles, 1 to 100.
- **minLat:** Viewport mode: south edge, decimal degrees.
- **minLng:** Viewport mode: west edge, decimal degrees.
- **maxLat:** Viewport mode: north edge, decimal degrees.
- **maxLng:** Viewport mode: east edge, decimal degrees.
- **network:** Network slugs, comma-separated. At most 10.
- **speed:** Speed bands, any of: slow, fast, rapid, ultra. Comma-separated.
- **conn:** Connectors, any of: type2, ccs, chademo, j1772 (Type 1), 3pin. Comma-separated.
- **open:** 1 = only chargers with a socket free now.
- **sort:** near (default), speed, price, value or open.

```sh
curl 'https://ampmap.co.uk/api/embed/chargers?at=-2.24,53.48&n=5'
```

### GET /api/cars

**Vehicle catalogue** Every electric and plug-in hybrid car in the UK catalogue, with battery size and peak AC and DC charging rates.

```sh
curl 'https://ampmap.co.uk/api/cars'
```

### GET /api/cars/{id}

**One vehicle** One vehicle's full specification: battery, charging rates and connectors, range, and the source of the figures.

- **id required:** Vehicle id, from the catalogue.

```sh
curl 'https://ampmap.co.uk/api/cars/audi-a6-e-tron-95kwh-2025'
```

### GET /api/health

**Service health** Whether the service and its database are up. Answers 503 while the database cannot be reached.

```sh
curl 'https://ampmap.co.uk/api/health'
```

## AI agents and assistants

The same read-only data is open to AI agents: four tools - search places, find chargers near a point, check one charger's live status and find the cheapest published prices nearby - over the Model Context Protocol, the Agent2Agent protocol and, in supporting browsers, WebMCP. No key and no sign-up.

### MCP server (POST https://ampmap.co.uk/mcp)

A stateless Streamable HTTP endpoint for MCP clients. Send JSON-RPC 2.0 requests by POST: initialize, tools/list, then tools/call. Responses are plain JSON, never a stream.

[/.well-known/mcp/server-card.json](https://ampmap.co.uk/.well-known/mcp/server-card.json)

### A2A agent (POST https://ampmap.co.uk/a2a)

A minimal Agent2Agent JSON-RPC endpoint. SendMessage (or message/send) takes a short request in plain English, such as "chargers near Leeds", "cheapest near York" or "status of a charger id", or a data part naming a skill and its input. Answers are deterministic: no language model is involved.

[/.well-known/agent-card.json](https://ampmap.co.uk/.well-known/agent-card.json)

### Agent skills

Instructions for agents that work with plain HTTP, listed in an Agent Skills discovery index with a SHA-256 digest of each file.

[/.well-known/agent-skills/index.json](https://ampmap.co.uk/.well-known/agent-skills/index.json)

### WebMCP

In browsers that support WebMCP, every page registers the same tools with the browser's agent, plus two that move the page: open a charger and show the map at a point.

## Acting for a user

With a driver's permission, an assistant can also check in, report a problem, rate a charger or add a photo for them, and set, list or cancel an alert that a busy charger is free, over MCP or A2A. Those tools need an OAuth 2.1 access token the driver grants; the read-only tools never do.

### Signing in

1. Call a write tool without a token. The answer is HTTP 401 with a WWW-Authenticate header naming the protected resource metadata for the endpoint you called.
2. Read the authorisation server metadata it points to, and register a public client at /oauth/register (dynamic client registration). Redirect URIs must be https, or http on localhost or 127.0.0.1; there is no client secret.
3. Send the driver to /oauth/authorize with response\_type=code, a PKCE challenge (S256 only), state, the scopes you need and resource set to the endpoint you will call (/mcp or /a2a). The driver sees your name, marked as the one you gave yourself, and what you are asking for, and chooses Allow or Deny.
4. Exchange the code at /oauth/token with your code\_verifier. A code works once. Access tokens last an hour; refresh tokens change on every use, and presenting an old one ends the connection.
5. Call the tool with Authorization: Bearer and the access token. A token without the tool's scope is refused with 403 insufficient\_scope.

### OAuth endpoints

- `/oauth/register`
- `/oauth/authorize`
- `/oauth/token`
- `/oauth/revoke`

### Scopes and tools

- **charger:checkin:** checkin\_charger - charging worked (a check-in) or did not (a fault report)
- **charger:report:** report\_charger\_problem - a fault, a blocked bay, wrong details or something else
- **charger:review:** rate\_charger - 1 to 5 stars and an optional review
- **charger:photo:** upload\_charger\_photo - a JPEG, PNG or WebP photo as base64
- **charger:watch:** watch\_charger, list\_charger\_watches and cancel\_charger\_watch - one alert to the driver's browser when a busy charger has a socket free. The driver turns alerts from assistants on once, on their Amp Map account page, in the browser they want them in; until then watch\_charger says so and sets nothing up.

### What a write means

Whatever an assistant sends counts as the driver's own contribution from their device, under the same rules as the site's own forms: one voice per driver, one rating per charger, and reports that show to other drivers just as the site's do. Ratings, reviews and photos from assistants appear once Amp Map has checked them. The driver can disconnect an assistant from their account page at any time; revoke tokens you no longer need at /oauth/revoke.

## Errors

A request that cannot be answered gets a 4xx status with a JSON body such as {"error": "invalid bbox"}. An id that does not exist answers 404.

## Fair use and caching

There are no API keys. Successful responses carry a Cache-Control header: keep responses for as long as it allows rather than asking again. Requests pass through Cloudflare, and automated traffic that slows the service for drivers may be throttled or blocked without notice. The endpoints and their fields can change while Amp Map is in beta; fields are added more often than removed.

Planning heavy or bulk use? [Tell us first](https://ampmap.co.uk/feedback).

## Data and attribution

Charger locations, prices and live status come from the data feeds charge point operators publish about their own networks, and from Open Charge Map and its contributors. Vehicle specifications come from OpenEV Data. Each charger lists its sources, with their licence terms where the source publishes them, and those terms apply to that record. If you show this data, credit the operators and Open Charge Map, and link to Amp Map.

Every source is listed on the [credits page](https://ampmap.co.uk/credits).
