{"openapi":"3.0.3","info":{"title":"Plota API","version":"1.0.0","description":"Structured, classified, source-linked UK planning application data. Search applications, retrieve details, query nearby, list councils and categories, and read saved alert feeds.","contact":{"name":"Plota","email":"hello@plota.co.uk","url":"https://plota.co.uk/api-access"}},"servers":[{"url":"https://api.plota.co.uk/v1","description":"Production"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"description":"Bearer token authentication","type":"http","scheme":"bearer"},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"Application":{"type":"object","properties":{"id":{"type":"string","example":"a1b2c3d4"},"reference":{"type":"string","nullable":true},"authority":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"}}},"address":{"type":"string","nullable":true},"postcode":{"type":"string","nullable":true},"description":{"type":"string","nullable":true},"category":{"type":"object","nullable":true,"properties":{"slug":{"type":"string"},"label":{"type":"string"}}},"categories":{"type":"array","items":{"type":"object"}},"planning_route":{"type":"string","nullable":true},"status":{"type":"string","nullable":true,"description":"LIVE records: the council's own status text, VERBATIM (e.g. \"Pending Consideration\", \"Application Permitted\"). ARCHIVE (historical) records have no council wording of their own, so `status` equals `stage` there."},"stage":{"type":"string","nullable":true,"enum":["pending","approved","refused","withdrawn","decided","other"],"description":"The NORMALISED status - the raw `status` collapsed to a stable, filterable set. Use this to filter/aggregate. A blank/awaiting council status maps to `pending`. Identical on live and archive records."},"date_received":{"type":"string","format":"date","nullable":true},"date_validated":{"type":"string","format":"date","nullable":true},"date_decided":{"type":"string","format":"date","nullable":true},"location":{"type":"object","nullable":true,"properties":{"lat":{"type":"number"},"lng":{"type":"number"}}},"links":{"type":"object","properties":{"plota":{"type":"string","nullable":true},"council":{"type":"string","nullable":true}}},"source":{"type":"string","enum":["live","historical"],"description":"'live' = current Plota-collected data with deep classification. 'historical' = Plota archive (pre-2026); category is null and planning_route is a broad council-based type. Historical is a paid feature."}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"request_id":{"type":"string"}}}}}}},"paths":{"/applications":{"get":{"summary":"Search planning applications","operationId":"listApplications","parameters":[{"name":"postcode","in":"query","schema":{"type":"string"},"description":"Full or partial postcode (e.g. SW11)"},{"name":"council","in":"query","schema":{"type":"string"},"description":"Council slug (see /councils)"},{"name":"nation","in":"query","schema":{"type":"string","enum":["england","scotland","wales","northern-ireland"]},"description":"Filter to a UK nation."},{"name":"category","in":"query","schema":{"type":"string"},"description":"Category slug(s), comma-separated (see /categories)"},{"name":"q","in":"query","schema":{"type":"string"},"description":"Keyword search over description and address (full-text); a reference-style value also matches the reference field."},{"name":"status","in":"query","schema":{"type":"string"},"description":"Substring match on the council's raw status text (verbatim). For stable filtering use `stage` instead."},{"name":"stage","in":"query","schema":{"type":"string","enum":["pending","approved","refused","withdrawn","decided","other"]},"description":"Filter by NORMALISED status. One of pending, approved, refused, withdrawn, decided, other. Recommended over `status` for filtering/aggregating."},{"name":"date_from","in":"query","schema":{"type":"string","format":"date"},"description":"Inclusive lower bound (YYYY-MM-DD). A range reaching before 2026, with a scope (council/nation/coords/keyword), includes Plota archive results on paid plans (source:\"historical\")."},{"name":"date_to","in":"query","schema":{"type":"string","format":"date"},"description":"Inclusive upper bound (YYYY-MM-DD)."},{"name":"limit","in":"query","schema":{"type":"integer"},"description":"Page size (capped per plan)"},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Pagination cursor from meta.next_cursor"},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"]},"description":"Response format (default json)."}],"responses":{"200":{"description":"A page of applications","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Application"}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"count":{"type":"integer"},"next_cursor":{"type":"string","nullable":true},"historical_included":{"type":"boolean"},"historical_available":{"type":"boolean"},"historical_more":{"type":"boolean"},"historical_note":{"type":"string"}}}}}}}},"401":{"description":"Authentication error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited"}}}},"/applications/{id}":{"get":{"summary":"Retrieve one application","operationId":"getApplication","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"public_id or numeric id"}],"responses":{"200":{"description":"Application","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Application"}}}}}},"404":{"description":"Not found"}}}},"/applications/nearby":{"get":{"summary":"Find applications near a location","operationId":"nearbyApplications","parameters":[{"name":"lat","in":"query","schema":{"type":"number"}},{"name":"lng","in":"query","schema":{"type":"number"}},{"name":"radius","in":"query","schema":{"type":"integer"},"description":"Metres (max 5000)"},{"name":"postcode","in":"query","schema":{"type":"string"},"description":"Alternative to lat/lng - any valid full or partial UK postcode (geocoded server-side)."},{"name":"category","in":"query","schema":{"type":"string"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"A page of applications","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Application"}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"count":{"type":"integer"},"next_cursor":{"type":"string","nullable":true},"historical_included":{"type":"boolean"},"historical_available":{"type":"boolean"},"historical_more":{"type":"boolean"},"historical_note":{"type":"string"}}}}}}}},"400":{"description":"Invalid request"}}}},"/councils":{"get":{"summary":"List covered councils","operationId":"listCouncils","responses":{"200":{"description":"Councils"}}}},"/categories":{"get":{"summary":"List planning categories","operationId":"listCategories","responses":{"200":{"description":"Categories"}}}},"/alerts":{"get":{"summary":"List your saved alerts","operationId":"listAlerts","responses":{"200":{"description":"Alerts"}}}},"/alerts/{id}":{"get":{"summary":"Retrieve a saved alert","operationId":"getAlert","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Alert"}}}},"/alerts/{id}/matches":{"get":{"summary":"Applications matching a saved alert","operationId":"alertMatches","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}},{"name":"days","in":"query","schema":{"type":"integer"}},{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"]}}],"responses":{"200":{"description":"A page of applications","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Application"}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"count":{"type":"integer"},"next_cursor":{"type":"string","nullable":true},"historical_included":{"type":"boolean"},"historical_available":{"type":"boolean"},"historical_more":{"type":"boolean"},"historical_note":{"type":"string"}}}}}}}}}}},"/applications/{id}/history":{"get":{"summary":"Application status & decision timeline","operationId":"applicationHistory","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"History"}}}},"/exports":{"post":{"summary":"Bulk export (plan-gated)","operationId":"createExport","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"postcode":{"type":"string"},"council":{"type":"string"},"category":{"type":"string"},"date_from":{"type":"string"},"date_to":{"type":"string"},"limit":{"type":"integer"},"format":{"type":"string","enum":["json","csv"]}}}}}},"responses":{"200":{"description":"Export"},"403":{"description":"Not on this plan"}}}},"/webhooks":{"get":{"summary":"List your webhooks","operationId":"listWebhooks","responses":{"200":{"description":"Webhooks"}}},"post":{"summary":"Register a webhook","operationId":"createWebhook","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","format":"uri"},"alert_id":{"type":"integer"}}}}}},"responses":{"201":{"description":"Created (secret shown once)"}}}},"/webhooks/{id}":{"delete":{"summary":"Delete a webhook","operationId":"deleteWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Deleted"}}}},"/webhooks/{id}/test":{"post":{"summary":"Send a test webhook event","operationId":"testWebhook","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Delivery result"}}}}}}