API Documentation

PlanNexus provides a RESTful API for accessing planning application data from councils across the UK.

The API is versioned at /v1 and treated as a stable contract — changes are additive, and any breaking change is announced ahead of time. See the changelog & change policy.

Authentication

All API requests require an API key passed via the X-API-Key header.

Example requestcurl

curl https://api.plannexus.io/v1/applications \
 -H"X-API-Key: pn_live_your_key_here" \
 -G -d"q=extension" -d"postcode=SW1"

Rate Limiting

Rate limits are communicated via response headers:

Tier	Rate	Monthly	Price
Free	10/min	1,000	£0
Starter	60/min	50,000	£99/mo
Pro	300/min	150,000	£299/mo
Enterprise	Custom	Unlimited	Custom

Endpoints

GET/v1/applications

Search and filter planning applications with full-text search, postcode filtering, and faceted results.

Parameters

qstringFull-text search query

postcodestringPostcode prefix filter (e.g. SW1, E8)

statusstringFilter by status (comma-separated)

application_typestringFilter by type

authority_iduuidFilter by authority

date_received_fromdateReceived on or after (YYYY-MM-DD)

date_received_todateReceived on or before

sortstringSort field (default: date_received)

orderstringasc or desc (default: desc)

pageintPage number (default: 1)

per_pageintResults per page (default: 25, max: 100)

GET/v1/applications/nearby

Find planning applications near a geographic point.

Parameters

latfloatLatitude (-90 to 90)

lngfloatLongitude (-180 to 180)

radiusintRadius in metres (default: 1000, max: 50000)

GET/v1/applications/{id}

Get full details for a single planning application.

GET/v1/applications/{id}/documents

List documents associated with an application.

GET/v1/applications/{id}/history

Get the status change history for an application.

GET/v1/applications/export.csv

Paid. Stream a filtered result set as a CSV download — up to 25,000 rows per call, metered per-row against your monthly export allowance. Takes the same filters as /v1/applications, plus:

Parameters

date_validated_fromdateValidated on or after (YYYY-MM-DD)

date_validated_todateValidated on or before

validated_or_receivedboolFall back to date_received where a council publishes no validated date — keeps a validated-date feed complete

latfloatLatitude for radius filter (use with lng + radius)

lngfloatLongitude for radius filter

radiusintMetres around (lat, lng) — default 1000, max 50000

window_daysintDays back from today when date_received_from is unset (default 90)

limitintRows to return (max 25,000)

GET/v1/applications/top-agents.csv

Paid. The most-active planning agents within a filtered result set, as CSV — same filters as /v1/applications.

GET/v1/authorities

List all local authorities in the database.

GET/v1/analytics/councils

Public — no auth. League table — approval rate, decision speed and volume for every authority (rolling 12 months, official MHCLG PS2). Rendered at plannexus.io/leagues/planning.

Parameters

sortstringapproval_rate | speed | decisions

regionstringFilter to one region

GET/v1/analytics/councils/{gss}

Paid. One council's scorecard vs national + regional averages, with rank and the major/minor/other split.

GET/v1/analytics/councils/{gss}/trends

Paid. Full quarterly approval/timeliness series, 1979 to present.

GET/v1/analytics/councils/{gss}/teaser

Public — no auth. Headline approval rate, national average and rank for one council.

GET/v1/analytics/activity

Paid. Busiest authorities by applications received (live; 12-month and last-90-day volumes).

Parameters

sortstringvolume | recent

regionstringFilter to one region

GET/v1/analytics/activity/{gss}

Paid. One authority's volume, application-type mix and 24-month trend.

GET/v1/analytics/agents

Paid. Most-active planning agents by application volume (national, or scoped to one authority).

Parameters

gss_codestringScope to one authority (else national)

limitintRows to return (default 50, max 100)

GET/v1/analytics/market/{gss}

Paid. Property-market summary for one council from HM Land Registry Price Paid — median price, sales volume and year-on-year change (England & Wales; YoY suppressed on thin samples).

GET/v1/analytics/market/{gss}/teaser

Public — no auth. Headline median price and sales volume for one council.

GET/v1/analytics/energy

Public — no auth. Energy-efficiency league built from 22M+ domestic EPC certificates — share rated C or better and mean SAP score per council (suppressed under 100 certificates). Rendered at plannexus.io/leagues/energy.

GET/v1/analytics/energy/{gss}

Paid. One council's EPC profile: rating distribution, mean SAP score and retrofit signals.

GET/v1/analytics/energy/{gss}/teaser

Public — no auth. Headline share rated C+ and rank for one council.

GET/v1/analytics/appeals

Public — no auth. Appeals league from Planning Inspectorate casework — overturn rate per council (appeals allowed / decided; suppressed under 20 decided). Rendered at plannexus.io/leagues/appeals.

GET/v1/analytics/appeals/agents

Paid. Agent win rates at appeal — who actually gets refusals overturned.

GET/v1/analytics/appeals/{gss}

Paid. One council's appeal record: overturn rate vs the national average, volume and 10-year trend.

GET/v1/analytics/appeals/{gss}/teaser

Public — no auth. Headline overturn rate and rank for one council.

POST/v1/subscriptions

Create a webhook subscription to receive notifications for new applications or status changes.

Parameters

webhook_urlstringHTTPS URL to receive payloads

filter_postcodesstring[]Postcode prefix filters

eventsstring[]Event types: new_application, status_change, decision_made

GET/v1/subscriptions

List your webhook subscriptions.

Official SDKs

Thin, typed clients around the REST API. Both honour Retry-After on 429 automatically and ship TypeScript/Python types for every response shape.

Python — pip install plannexuspython

from plannexus import PlanNexus

with PlanNexus(api_key="pn_live_...") as client:
 result = client.applications.search(
 q="extension", postcode="SW1", per_page=10
 )
 for app in result["data"]:
 print(app["reference"], app["address"])

Node / TS — npm install plannexustypescript

import { PlanNexus } from "plannexus";

const client = new PlanNexus({ apiKey: "pn_live_..." });

const result = await client.applications.search({
 q: "extension",
 postcode: "SW1",
 per_page: 10,
});
for (const app of result.data) {
 console.log(app.reference, app.address);
}

Raw HTTP examples

Pythonpython

import httpx

client = httpx.Client(
 base_url="https://api.plannexus.io/v1",
 headers={"X-API-Key": "pn_live_your_key"}
)

# Search for extensions in SW1
resp = client.get("/applications", params={
"q": "extension",
"postcode": "SW1",
"per_page": 10
})
data = resp.json()

for app in data["data"]:
 print(f"{app['reference']} - {app['address']}")
 print(f" Status: {app['status']}")
 print(f" Received: {app['date_received']}")

JavaScriptjavascript

const response = await fetch(
"https://api.plannexus.io/v1/applications? " +
 new URLSearchParams({ q: "extension", postcode: "SW1" }),
 {
 headers: {"X-API-Key": "pn_live_your_key" },
 }
);

const { data, meta } = await response.json();
console.log(`Found ${meta.total} applications`);

data.forEach((app) => {
 console.log(`${app.reference} - ${app.address}`);
});

Response envelope & pagination

List endpoints (applications, authorities, subscriptions) return a wrapped envelope:

List response shapejson

{
"data": [ /* array of records */ ],
"meta": {
"total": 4218,
"page": 1,
"per_page": 25,
"pages": 169
 }
}

Single-record endpoints return the bare object. Pagination is page-based with page and per_page query params — `per_page` caps at 100.

Error codes

Status	Meaning	What to do
400	Malformed request / bad query	Read the `detail` field; fix the input
401	Missing / invalid API key	Add `X-API-Key` header; rotate if lost
403	Feature requires a higher tier (e.g. webhooks)	Upgrade at `/dashboard/billing`
404	Resource not found	Check the id / reference
429	Rate limit / quota exhausted	Honour the `Retry-After` header; retry after
5xx	Server error	Retry with exponential backoff; persistent 5xx → email support

Webhooks

Create a subscription via POST /v1/subscriptions (or the Webhooks page in your dashboard). PlanNexus POSTs a JSON payload to your endpoint whenever a matching application triggers a subscribed event.

Event types

new_application — a council published a new application
status_change — an existing application's status moved (e.g. validated → under-consultation)
decision_made — an application was decided (approved/refused/withdrawn)

Payload format

POST to your webhook URLjson

{
"event": "new_application",
"timestamp": "2026-04-23T09:15:42.108Z",
"data": {
"application_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
"reference": "23/04521/FUL",
"authority_id": "018e1c50-...",
"address": "14 Bishopsgate, London EC2N 4AW",
"postcode": "EC2N 4AW",
"description": "Erection of a single-storey rear extension.",
"status": "validated",
"decision": null,
"application_type": "householder",
"date_received": "2026-04-23" }
}

Headers

Content-Type : application/json
X-PlanNexus-Signature : sha256=<hex-digest> — HMAC-SHA256 over the raw body, keyed by your webhook secret
X-PlanNexus-Event — same as payload.event; handy for routing before parsing the body

Verifying signatures

Pythonpython

import hmac, hashlib

def verify(body: bytes, header: str, secret: str) -> bool:
 expected ="sha256=" + hmac.new(
 secret.encode(), body, hashlib.sha256
 ).hexdigest()
 return hmac.compare_digest(expected, header)

Node.jsjavascript

import { createHmac, timingSafeEqual } from "crypto";

export function verify(body, header, secret) {
 const expected =
"sha256=" +
 createHmac("sha256", secret).update(body).digest("hex");
 const a = Buffer.from(expected);
 const b = Buffer.from(header);
 return a.length === b.length && timingSafeEqual(a, b);
}

Delivery & retries

A 2xx response is treated as delivered. Anything else counts toward a consecutive-failure tally; a subscription is auto-paused after 10 consecutive failures. Paused subscriptions stop receiving events — resume them from the dashboard once your endpoint is healthy. Click Send test on a subscription to fire a synthetic event: "test" payload — test deliveries don't count against the failure tally.

Interactive API Explorer

Try the API directly in your browser with our Swagger UI.

Open Swagger UI

API Documentation

PlanNexus provides a RESTful API for accessing planning application data from councils across the UK.

The API is versioned at /v1 and treated as a stable contract — changes are additive, and any breaking change is announced ahead of time. See the changelog & change policy.

Authentication

All API requests require an API key passed via the X-API-Key header.

Example requestcurl

curl https://api.plannexus.io/v1/applications \
 -H"X-API-Key: pn_live_your_key_here" \
 -G -d"q=extension" -d"postcode=SW1"

Rate Limiting

Rate limits are communicated via response headers:

Tier	Rate	Monthly	Price
Free	10/min	1,000	£0
Starter	60/min	50,000	£99/mo
Pro	300/min	150,000	£299/mo
Enterprise	Custom	Unlimited	Custom

Endpoints

GET/v1/applications

Search and filter planning applications with full-text search, postcode filtering, and faceted results.

Parameters

qstringFull-text search query

postcodestringPostcode prefix filter (e.g. SW1, E8)

statusstringFilter by status (comma-separated)

application_typestringFilter by type

authority_iduuidFilter by authority

date_received_fromdateReceived on or after (YYYY-MM-DD)

date_received_todateReceived on or before

sortstringSort field (default: date_received)

orderstringasc or desc (default: desc)

pageintPage number (default: 1)

per_pageintResults per page (default: 25, max: 100)

GET/v1/applications/nearby

Find planning applications near a geographic point.

Parameters

latfloatLatitude (-90 to 90)

lngfloatLongitude (-180 to 180)

radiusintRadius in metres (default: 1000, max: 50000)

GET/v1/applications/{id}

Get full details for a single planning application.

GET/v1/applications/{id}/documents

List documents associated with an application.

GET/v1/applications/{id}/history

Get the status change history for an application.

GET/v1/applications/export.csv

Paid. Stream a filtered result set as a CSV download — up to 25,000 rows per call, metered per-row against your monthly export allowance. Takes the same filters as /v1/applications, plus:

Parameters

date_validated_fromdateValidated on or after (YYYY-MM-DD)

date_validated_todateValidated on or before

validated_or_receivedboolFall back to date_received where a council publishes no validated date — keeps a validated-date feed complete

latfloatLatitude for radius filter (use with lng + radius)

lngfloatLongitude for radius filter

radiusintMetres around (lat, lng) — default 1000, max 50000

window_daysintDays back from today when date_received_from is unset (default 90)

limitintRows to return (max 25,000)

GET/v1/applications/top-agents.csv

Paid. The most-active planning agents within a filtered result set, as CSV — same filters as /v1/applications.

GET/v1/authorities

List all local authorities in the database.

GET/v1/analytics/councils

Public — no auth. League table — approval rate, decision speed and volume for every authority (rolling 12 months, official MHCLG PS2). Rendered at plannexus.io/leagues/planning.

Parameters

sortstringapproval_rate | speed | decisions

regionstringFilter to one region

GET/v1/analytics/councils/{gss}

Paid. One council's scorecard vs national + regional averages, with rank and the major/minor/other split.

GET/v1/analytics/councils/{gss}/trends

Paid. Full quarterly approval/timeliness series, 1979 to present.

GET/v1/analytics/councils/{gss}/teaser

Public — no auth. Headline approval rate, national average and rank for one council.

GET/v1/analytics/activity

Paid. Busiest authorities by applications received (live; 12-month and last-90-day volumes).

Parameters

sortstringvolume | recent

regionstringFilter to one region

GET/v1/analytics/activity/{gss}

Paid. One authority's volume, application-type mix and 24-month trend.

GET/v1/analytics/agents

Paid. Most-active planning agents by application volume (national, or scoped to one authority).

Parameters

gss_codestringScope to one authority (else national)

limitintRows to return (default 50, max 100)

GET/v1/analytics/market/{gss}

Paid. Property-market summary for one council from HM Land Registry Price Paid — median price, sales volume and year-on-year change (England & Wales; YoY suppressed on thin samples).

GET/v1/analytics/market/{gss}/teaser

Public — no auth. Headline median price and sales volume for one council.

GET/v1/analytics/energy

GET/v1/analytics/energy/{gss}

Paid. One council's EPC profile: rating distribution, mean SAP score and retrofit signals.

GET/v1/analytics/energy/{gss}/teaser

Public — no auth. Headline share rated C+ and rank for one council.

GET/v1/analytics/appeals

GET/v1/analytics/appeals/agents

Paid. Agent win rates at appeal — who actually gets refusals overturned.

GET/v1/analytics/appeals/{gss}

Paid. One council's appeal record: overturn rate vs the national average, volume and 10-year trend.

GET/v1/analytics/appeals/{gss}/teaser

Public — no auth. Headline overturn rate and rank for one council.

POST/v1/subscriptions

Create a webhook subscription to receive notifications for new applications or status changes.

Parameters

webhook_urlstringHTTPS URL to receive payloads

filter_postcodesstring[]Postcode prefix filters

eventsstring[]Event types: new_application, status_change, decision_made

GET/v1/subscriptions

List your webhook subscriptions.

Official SDKs

Thin, typed clients around the REST API. Both honour Retry-After on 429 automatically and ship TypeScript/Python types for every response shape.

Python — pip install plannexuspython

from plannexus import PlanNexus

with PlanNexus(api_key="pn_live_...") as client:
 result = client.applications.search(
 q="extension", postcode="SW1", per_page=10
 )
 for app in result["data"]:
 print(app["reference"], app["address"])

Node / TS — npm install plannexustypescript

import { PlanNexus } from "plannexus";

const client = new PlanNexus({ apiKey: "pn_live_..." });

const result = await client.applications.search({
 q: "extension",
 postcode: "SW1",
 per_page: 10,
});
for (const app of result.data) {
 console.log(app.reference, app.address);
}

Raw HTTP examples

Pythonpython

import httpx

client = httpx.Client(
 base_url="https://api.plannexus.io/v1",
 headers={"X-API-Key": "pn_live_your_key"}
)

# Search for extensions in SW1
resp = client.get("/applications", params={
"q": "extension",
"postcode": "SW1",
"per_page": 10
})
data = resp.json()

for app in data["data"]:
 print(f"{app['reference']} - {app['address']}")
 print(f" Status: {app['status']}")
 print(f" Received: {app['date_received']}")

JavaScriptjavascript

const response = await fetch(
"https://api.plannexus.io/v1/applications? " +
 new URLSearchParams({ q: "extension", postcode: "SW1" }),
 {
 headers: {"X-API-Key": "pn_live_your_key" },
 }
);

const { data, meta } = await response.json();
console.log(`Found ${meta.total} applications`);

data.forEach((app) => {
 console.log(`${app.reference} - ${app.address}`);
});

Response envelope & pagination

List endpoints (applications, authorities, subscriptions) return a wrapped envelope:

List response shapejson

{
"data": [ /* array of records */ ],
"meta": {
"total": 4218,
"page": 1,
"per_page": 25,
"pages": 169
 }
}

Single-record endpoints return the bare object. Pagination is page-based with page and per_page query params — `per_page` caps at 100.

Error codes

Status	Meaning	What to do
400	Malformed request / bad query	Read the `detail` field; fix the input
401	Missing / invalid API key	Add `X-API-Key` header; rotate if lost
403	Feature requires a higher tier (e.g. webhooks)	Upgrade at `/dashboard/billing`
404	Resource not found	Check the id / reference
429	Rate limit / quota exhausted	Honour the `Retry-After` header; retry after
5xx	Server error	Retry with exponential backoff; persistent 5xx → email support

Webhooks

Event types

new_application — a council published a new application
status_change — an existing application's status moved (e.g. validated → under-consultation)
decision_made — an application was decided (approved/refused/withdrawn)

Payload format

POST to your webhook URLjson

{
"event": "new_application",
"timestamp": "2026-04-23T09:15:42.108Z",
"data": {
"application_id": "3f2504e0-4f89-11d3-9a0c-0305e82c3301",
"reference": "23/04521/FUL",
"authority_id": "018e1c50-...",
"address": "14 Bishopsgate, London EC2N 4AW",
"postcode": "EC2N 4AW",
"description": "Erection of a single-storey rear extension.",
"status": "validated",
"decision": null,
"application_type": "householder",
"date_received": "2026-04-23" }
}

Headers

Content-Type : application/json
X-PlanNexus-Signature : sha256=<hex-digest> — HMAC-SHA256 over the raw body, keyed by your webhook secret
X-PlanNexus-Event — same as payload.event; handy for routing before parsing the body

Verifying signatures

Pythonpython

import hmac, hashlib

def verify(body: bytes, header: str, secret: str) -> bool:
 expected ="sha256=" + hmac.new(
 secret.encode(), body, hashlib.sha256
 ).hexdigest()
 return hmac.compare_digest(expected, header)

Node.jsjavascript

import { createHmac, timingSafeEqual } from "crypto";

export function verify(body, header, secret) {
 const expected =
"sha256=" +
 createHmac("sha256", secret).update(body).digest("hex");
 const a = Buffer.from(expected);
 const b = Buffer.from(header);
 return a.length === b.length && timingSafeEqual(a, b);
}

Delivery & retries

Interactive API Explorer

Try the API directly in your browser with our Swagger UI.

Open Swagger UI