PostcodeProp

Developer platform

API changelog

The versioning promise: additive changes — new fields, new endpoints, new MCP tools — ship within v1 without notice, so parse tolerantly and ignore fields you do not use. Breaking changes get a new versioned path and at least 90 days' notice on this page before anything changes underneath you.

← Back to the developer docs

/api/v1/rankings enabled

  • • The open-data licensing review that kept /api/v1/rankings behind a 503 is resolved: the OSM-derived nightlife input to the young-professional persona is treated as an ODbL produced work — analysis in docs/legal/d6-odbl-rankings-analysis.md (decision D6). The endpoint is live.
  • • What it serves: persona outcode rankings (persona=investor | family | young_professional, default investor), rank-ordered nationally, with an optional region outcode-prefix filter and limit up to 250 rows (default 50). 1 credit per call. Scores are recomputed twice monthly.
  • • Rankings responses carry meta.attribution with the licence statements for that persona's score inputs — reproduce the OSM/ODbL statement if you republish young-professional rankings.
  • • MCP surface unchanged: still 8 tools. Rankings is REST-only for now; a get_rankings tool would be announced here first.
  • • Also from this week: rate-limit enforcement now matches the published contract — Growth and Scale keys actually get their 120/300 req/min (per-key overrides apply only where explicitly set) — metered MCP tool calls carry the same X-Credits-* and X-RateLimit-Limit headers as REST with compare_areas metered per postcode, and the MCP server is published to the official MCP registry.

Provenance on every metered response

  • • Machine-readable provenance ({source, licence, asOf, methodology?, note?}) now ships on every metered response, not just area and property. /api/v1/comparables and /api/v1/epc carry a top-level provenance block naming HM Land Registry Price Paid and the MHCLG EPC register respectively; /api/v1/metrics/green-premium carries one naming its inputs and linking the published methodology page; POST /api/v1/summary carries a provenance map covering the sections the summary draws on. Additive — no existing field moved or changed shape.
  • • Attribution statements (the licence text re-users must reproduce when republishing) now ride in meta on those responses too, matching area and property.
  • • The mirroring MCP tools — get_comparables, get_epc, get_metric — return the same blocks.

v1 launch

  • • Nine REST endpoints live: area, investment-score, property, comparables, epc, coverage, compare, summary, and metrics/{metric}. A tenth, /api/v1/rankings, is built but returns 503 behind a feature flag pending a licensing review — if it is enabled, that will be announced here.
  • • Remote MCP server at /mcp (Streamable HTTP): eight read-only tools mirroring the REST endpoints on the same credit meter. Bearer API-key auth on every call, including the handshake; only tool calls are metered.
  • • Weighted credit metering, with X-Credits-Limit, X-Credits-Used and X-Credits-Remaining reported on every metered response.
  • • Per-section provenance — source, licence, vintage — on area and property responses; the other endpoints state their row caps and data notes in meta.
  • • Free plan (250 credits/month, no card, self-serve) and ppa_test_ sandbox keys, returning canned fixtures on area and investment-score without touching quota. The other REST endpoints answer a test key with 400 test_fixture_unavailable; the MCP server rejects test keys with 401.