API Reference

Authentication

Pass your API key in the X-API-Key header. You can also use Authorization: Bearer YOUR_KEY.

X-API-Key: pw_live_a1b2c3d4e5f6...

Errors

All errors return JSON with an error field and an appropriate HTTP status code.

Pagination

All list endpoints return a meta object. Use ?page=2&limit=50 to paginate. Max limit is 100.

"meta": {
  "total":  4821,  // total matching records
  "page":   1,     // current page (1-indexed)
  "limit":  20,    // records per page
  "pages":  242    // total pages
}

Rate limits

Limits reset at midnight UTC. Exceeding the limit returns 429.

List planning applications. All parameters are optional and can be combined.

Query Parameters

curl "https://api.planwire.io/v1/applications?council=adu&q=extension&status=Approved&limit=5" \
  -H "X-API-Key: YOUR_KEY"

Find applications within a radius using PostGIS spatial indexing. Extremely fast even over millions of records.

curl "https://api.planwire.io/v1/applications/nearby?lat=51.4975&lng=-0.1278&radius_km=1" \
  -H "X-API-Key: YOUR_KEY"

Fetch a single planning application by its UUID. Includes property enrichment — EA flood zone and Land Registry sold prices for the postcode.

curl "https://api.planwire.io/v1/applications/8f6fac3a-d93a-453e-b5db-6c5ecc631bf0" \
  -H "X-API-Key: YOUR_KEY"

Fetch an application using the council's own reference number (e.g. 24/01234/FUL). Also includes flood risk and nearby sold prices.

curl "https://api.planwire.io/v1/applications/ref/adu/AWDM%2F0158%2F25" \
  -H "X-API-Key: YOUR_KEY"

List all 379 supported Local Planning Authorities, with application counts.

{
  "data": [{
    "id":               "adu",
    "name":             "Adur District Council",
    "portalType":       "official",
    "applicationCount": 874
  }]
}

Get a single council's details including the date of the most recent application.

curl "https://api.planwire.io/v1/councils/adu" \
  -H "X-API-Key: YOUR_KEY"

List all webhooks registered to your API key.

Subscribe to planning application events. You'll receive an HTTP POST to your URL whenever a matching application is new or updated.

Request Body

curl -X POST "https://api.planwire.io/v1/webhooks" \
  -H "X-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/hooks/planning",
    "filters": {
      "postcodePrefix": "SW1",
      "status": "Approved"
    }
  }'

Webhook Payload

Requests are signed with HMAC-SHA256 — verify using the X-PlanWire-Signature header.

{
  "event":       "application.new",   // or "application.updated"
  "timestamp":   "2025-03-19T14:23:01Z",
  "application": { /* full application object */ }
}

Verifying signatures

Compute HMAC-SHA256(secret, rawBody) and compare to the X-PlanWire-Signature header value (after stripping the sha256= prefix).

import { createHmac } from 'crypto';

function verify(secret, rawBody, sigHeader) {
  const expected = 'sha256=' + createHmac('sha256', secret)
    .update(rawBody).digest('hex');
  return sigHeader === expected;
}

import hmac, hashlib

def verify(secret, raw_body, sig_header):
    expected = 'sha256=' + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(sig_header, expected)

Remove a webhook by its UUID.

Send a test event to verify your endpoint is reachable and your signature verification works.

curl -X POST "https://api.planwire.io/v1/webhooks/YOUR_WEBHOOK_ID/test" \
  -H "X-API-Key: YOUR_KEY"

View the last 50 delivery attempts for a webhook — useful for debugging failed deliveries.

{
  "data": [{
    "id":          "a3f2...",
    "event":       "application.new",
    "statusCode":  200,
    "success":     true,
    "createdAt":   "2025-03-19T14:23:01Z"
  }]
}