Developer API Documentation — Scottish Planning Database

Developer API Overview & Scope

The Scottish Planning Database API is an open web service providing unified spatial searching, real-time lifecycle event feeds, and detail resolution across all 32 Scottish local council planning authorities and 2 national park authorities.

📍 Geographic & Temporal Data Scope
The dataset and search index currently covers Scottish local authority planning applications for the year 2026. Historical planning records prior to 2026 are not currently indexed by this public service.

⚠️ Disclaimer & SLA Policy
This service is provided strictly on a best-effort basis with no Service Level Objective (SLO) or uptime SLA guarantee. Endpoints, schemas, response formats, and access rules may be modified, restricted, or placed behind API keys/authentication at any time with no prior notice.

Gateway Architecture & Published vs Hidden Endpoints

All incoming web traffic passes through a Caddy Ingress Gateway reverse proxy. Public APIs are exposed under the /api/v1/ URI namespace.

To maintain security and prevent unauthenticated telemetry exposure, internal application monitoring endpoints are explicitly hidden and blocked at the gateway level.

Published API Endpoints

GET /api/v1/proposals

Performs spatial, location, or council-scoped attribute searches against the indexed planning database. Public queries are strictly read-only and return cached database records.

Query Parameters

Parameter	Type	Required	Description
`location`	string	Optional	Location name, Google Maps URL, or `lat,lng` coordinate pair (e.g. `56.3952,-3.4312`).
`lat`, `lng`	float	Optional	Explicit WGS84 Latitude and Longitude coordinates.
`radius` / `radius_m`	string / float	Optional	Search radius (e.g. `250m`, `500m`, `1km`, `2km`, `5km`). Default: `500m`.
`bbox`	string	Optional	Bounding box formatted as `minLat,minLng,maxLat,maxLng` or OSGB36 Easting/Northing coordinates.
`council`	string	Optional	Filter by specific council name (e.g., `Perth & Kinross` or `City of Edinburgh`).
`major_only`	boolean	Optional	Set to `true` or `1` to return only Major Planning Applications.
`sort_by`	string	Optional	Sort order: `distance` (closest first, default) or `date` (newest first).
`limit`	integer	Optional	Maximum results returned (default: `50`).

cURL Example

cURL Request

curl -X GET "https://away.mhutchinson.uk/api/v1/proposals?location=56.3952,-3.4312&radius=1km&major_only=true&limit=10"

JSON Response Structure

Response (200 OK)

{
  "search_params": {
    "council": "",
    "center": { "lat": 56.3952, "lng": -3.4312 },
    "radius_m": 1000,
    "major_only": true,
    "sort_by": 0
  },
  "total_found": 1,
  "displayed": 1,
  "proposals": [
    {
      "id": "db_24/00123/FUL",
      "easting": 311750,
      "northing": 723400,
      "lat": 56.3954,
      "lng": -3.4310,
      "distance_m": 25.4,
      "app_type": "FUL",
      "app_type_desc": "Full Planning Permission",
      "year": 2024,
      "properties": {
        "local_auth": "Perth & Kinross",
        "reference": "24/00123/FUL"
      },
      "portal_url": "https://planningapps.pkc.gov.uk/...",
      "proposal": "Erection of residential dwellinghouses",
      "address": "Inchture, PH14 9RN",
      "status": "Application Permitted",
      "decision": "Approved",
      "decision_summary": "APPROVED"
    }
  ]
}

GET /api/v1/feed

Provides a real-time event feed of proposal lifecycle events (e.g. PROPOSAL_DISCOVERED, PROPOSAL_RESOLVED, DECISION_DETERMINED). Supports cursor pagination.

Query Parameters

Parameter	Type	Required	Description
`event_type` / `type`	string	Optional	Filter feed events: `discovered` (new WFS records), `resolution` (portal scrapers updates/decisions), `resolved`, or `determined`.
`council`	string	Optional	Filter feed events by authority name.
`major_only`	boolean	Optional	Filter for major development events only.
`since` / `date`	string	Optional	ISO 8601 / RFC3339 timestamp (e.g. `2026-08-01T00:00:00Z`) or date (`YYYY-MM-DD`).
`limit`	integer	Optional	Page size limit (default `50`).

cURL Examples

Fetch Newest 50 Discovered Applications

curl -X GET "https://away.mhutchinson.uk/api/v1/feed?event_type=discovered&limit=50"

Fetch Latest 50 Resolution Changes

curl -X GET "https://away.mhutchinson.uk/api/v1/feed?event_type=resolution&limit=50"

GET /api/v1/stats

Returns nationwide statistics including total cached proposals, portal resolution progress rates, unresolvable proposal totals, and council breakdown metrics.

cURL Example

cURL Request

curl -X GET "https://away.mhutchinson.uk/api/v1/stats"

GET /api/v1/councils

Lists all 34 Scottish planning authorities (32 local councils + 2 national parks) with their base portal URLs and system identifiers.

cURL Example

cURL Request

curl -X GET "https://away.mhutchinson.uk/api/v1/councils"

GET /api/v1/councils/{council}/unresolvable

Inspects the top unresolvable planning proposals for a specific authority (records where detail resolution failed $\ge N$ times).

cURL Example

cURL Request

curl -X GET "https://away.mhutchinson.uk/api/v1/councils/Perth%20%26%20Kinross/unresolvable?min_failed=5"

GET /api/v1/councils/{council}/activity

Provides live telemetry, current status, backoff duration, and event logs for a specific council's background ingestion worker.

cURL Example

cURL Request

curl -X GET "https://away.mhutchinson.uk/api/v1/councils/City%20of%20Edinburgh/activity"

GET /api/v1/workers/activity

Returns live worker snapshots and rate-limiting backoff status across all 32 Scottish local authorities.

cURL Example

cURL Request

curl -X GET "https://away.mhutchinson.uk/api/v1/workers/activity"

Hidden / Restricted Internal Endpoints

The following backend endpoints are maintained exclusively for container orchestration, internal monitoring, and scraper diagnostics. They are hidden and blocked at the Caddy Ingress Gateway and will respond with HTTP 403 Forbidden to external requests:

Endpoint Path	Status	Reason for Gateway Block
`/metrics`	403 Forbidden	Prometheus metric scraping endpoint (restricted to internal Prometheus monitoring).
`/healthz`	403 Forbidden	Container liveness check route.
`/api/v1/health`	403 Forbidden	Detailed ingestion health diagnostic & host backoff cap snapshot (restricted to internal system operations).