# Plota - UK Planning Applications API

Plota is a REST API for UK planning application data. It collects applications from hundreds of local planning authority portals and serves them in one consistent, structured format (JSON, or CSV), classified by type and linked to the official council record.

Use it to search, retrieve, and monitor UK planning applications by area, postcode, council, category, or date - live or historical.

## What Plota provides
- Coverage across hundreds of UK councils in England, Scotland, Wales and Northern Ireland, checked daily.
- A historical archive of 10M+ applications back to 2016 (available on paid plans).
- Automatic type classification on live applications (2026 onward), into categories such as extensions, new homes, change of use, solar, trees and HMOs. Call GET /v1/categories for the full list.
- The official council source URL on each record.
- One consistent JSON shape across all councils; JSON or CSV output; keyset pagination.
- Signed webhooks for new matches.
- The same dataset is browsable on the public site at https://plota.co.uk.

## Base URL & auth
Base URL: https://api.plota.co.uk/v1
Header: `Authorization: Bearer YOUR_API_KEY`  (or `X-API-Key: YOUR_API_KEY`)
Free demo key (500 requests/month, for building & testing): https://plota.co.uk/api-access
Full machine-readable schema: https://plota.co.uk/openapi.json

## Conventions
- Responses are JSON unless `format=csv`.
- Errors: `{ "error": { "type", "message", "request_id" } }`.
- Pagination: keyset - follow `meta.next_cursor` via `?cursor=...`.
- Rate limit + monthly quota depend on plan; HTTP 429 when exceeded.
- Dates are ISO 8601 (`YYYY-MM-DD`).

## Core endpoints
- `GET /v1/applications` - search. Params: `postcode`, `council` (slug), `nation`, `category` (slug, comma-separated), `q` (keyword), `stage` (normalised: pending|approved|refused|withdrawn|decided|other), `status` (raw council text substring), `date_from`, `date_to`, `limit`, `cursor`, `format=json|csv`.
- `GET /v1/applications/{id}` - a single application.
- `GET /v1/applications/nearby?lat=&lng=&radius=` (or `?postcode=`) - nearby search, radius in metres.
- `GET /v1/applications/{id}/history` - status & decision timeline.
- `GET /v1/councils` - covered councils + coverage metadata (last checked, portal type, nation).
- `GET /v1/categories` - the authoritative list of Plota category slugs + labels.
- `GET /v1/alerts` and `GET /v1/alerts/{id}/matches` - your saved alert feeds.
- `POST /v1/webhooks` - register a signed webhook for new matches (Starter plan and above).

## Live vs historical data
Live data (2026 onward) is deep-classified and carries a `category`. The Plota archive (2016-2025, 10M+ applications) is a paid feature: include it by passing a date range reaching before 2026 together with a scope (`council`, `nation`, coordinates, or `q`). Every record carries `"source": "live" | "historical"`. Historical records have `category: null` and a broad, council-derived `planning_route`.

## The application object
```json
{
  "id": "a1b2c3d4",
  "reference": "2026/2284/FUL",
  "authority": { "slug": "wandsworth", "name": "Wandsworth" },
  "address": "81 Example Road, London SW11 6HB",
  "postcode": "SW11 6HB",
  "description": "Single storey rear extension.",
  "category": { "slug": "extensions", "label": "Extensions & alterations" },
  "categories": [ { "slug": "extensions", "label": "Extensions & alterations" } ],
  "planning_route": "Full planning permission",
  "status": "Pending",
  "stage": "pending",
  "date_received": "2026-06-18",
  "date_validated": "2026-06-20",
  "date_decided": null,
  "location": { "lat": 51.4601, "lng": -0.1702 },
  "links": { "plota": "https://plota.co.uk/application/a1b2c3d4", "council": "https://planning.council.gov.uk/..." },
  "source": "live"
}
```

## Recipes
Recent extensions near a postcode:
```
curl "https://api.plota.co.uk/v1/applications?postcode=SW11&category=extensions&limit=10" -H "Authorization: Bearer YOUR_API_KEY"
```
Everything in one council since a date, as CSV:
```
curl "https://api.plota.co.uk/v1/applications?council=wandsworth&date_from=2026-01-01&format=csv" -H "Authorization: Bearer YOUR_API_KEY"
```
New homes within 800m of a coordinate:
```
curl "https://api.plota.co.uk/v1/applications/nearby?lat=51.4601&lng=-0.1702&radius=800&category=new-homes" -H "Authorization: Bearer YOUR_API_KEY"
```
Historical approvals in an area (paid; date reaches pre-2026 + a scope):
```
curl "https://api.plota.co.uk/v1/applications?council=leeds&date_from=2018-01-01&date_to=2020-12-31" -H "Authorization: Bearer YOUR_API_KEY"
```
Push new matches to Slack/CRM: save an alert in Plota, then `POST /v1/webhooks` with its `alert_id`; Plota delivers signed events as matches appear.

Always call `GET /v1/categories` for the exact category slugs rather than guessing.

## Status fields: `status` vs `stage`
Each application has two fields:
- `status` - on LIVE records, the council's own wording VERBATIM (e.g. "Pending Consideration", "Application Permitted"). Verifiable against the council record.
- `stage` - the NORMALISED value, one of `pending`, `approved`, `refused`, `withdrawn`, `decided`, `other`. Filter and aggregate on this. Filter with `?stage=approved`. A blank/awaiting council status maps to `pending`.

On Plota archive (historical) records, `status` equals `stage` - the archive has no separate council wording, so both carry the same normalised value.

## Licensing & terms
- Plota's data is derived from publicly available UK local-authority planning records. Each record includes the official council source URL; keep it with the data so results stay verifiable.
- Access is governed by the Plota API terms - see https://plota.co.uk/api-access and https://plota.co.uk/privacy.
- The demo tier is for evaluation and testing. Commercial and production use requires a paid plan. Bulk redistribution or reselling the raw dataset is an Enterprise arrangement - contact us.
- Do not scrape the public website; use this API for programmatic access, and stay within your plan's rate limit and monthly quota.
- Provided as-is for data access, not legal or planning advice; classification and normalisation are best-effort.

## For AI agents (live tool-use)
Plota publishes an MCP server so assistants (Claude, Cursor, ChatGPT, etc.) can query planning data live inside a conversation - e.g. "find recent HMO approvals in Croydon". See https://plota.co.uk/api-docs.

## Good to know
- Plota provides data access, not legal or planning advice. Classification is best-effort; each record also exposes the council's own application type (`planning_route`) so results are checkable.
- Use this API for programmatic access; automated scraping of the public website is not permitted.