{"openapi":"3.1.0","info":{"title":"PostcodeProperty.ai API","version":"1.0","description":"UK area & property intelligence from official and open data, with machine-readable provenance on every metered response.\n\n**Credits**: calls are metered in weighted credits (area/score/EPC/metric/rankings = 1, comparables = 2, property = 5 (+2 with address resolution), compare = 1/postcode, AI summary = 10, coverage = 0). `X-Credits-*` headers report your allowance on every response.\n\n**Address-light by default**: responses carry facts + identifiers (UPRN, postcode). Address strings appear only with `display=true`, contractually restricted to displaying residential property price information.\n\n**Sandbox**: any key beginning `ppa_test_` returns canned fixtures on supported endpoints — no quota, no live data.\n\nThe same key drives the MCP server at `https://postcodeproperty.ai/mcp` (Streamable HTTP; tools mirror these endpoints on the same meter).","contact":{"email":"hello@postcodeproperty.ai","url":"https://postcodeproperty.ai/developers"},"termsOfService":"https://postcodeproperty.ai/terms"},"servers":[{"url":"https://postcodeproperty.ai"}],"security":[{"apiKey":[]}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"API key from the dashboard, e.g. Authorization: Bearer ppa_live_…"}},"schemas":{"Provenance":{"type":"object","description":"Machine-readable provenance — on every metered data response. Area/property responses carry one block per data section; single-source responses (comparables, epc, metrics/*) carry one top-level `provenance` block; the AI summary carries a map keyed by the sections it draws on. The product guarantee: every number tells you where it came from.","properties":{"source":{"type":"string"},"licence":{"type":"string"},"asOf":{"type":"string","description":"Vintage (YYYY-MM or YYYY)"},"methodology":{"type":"string","format":"uri","description":"Present only when a methodology page exists"},"note":{"type":"string"}}},"Meta":{"type":"object","properties":{"generatedAt":{"type":"string","format":"date-time"},"sourceCompleteness":{"type":"integer","description":"% of attempted sources that answered"},"unavailableSources":{"type":"array","items":{"type":"string"}},"noDataSources":{"type":"array","items":{"type":"string"}},"vintages":{"type":"object","additionalProperties":{"type":"string"}},"attribution":{"type":"array","description":"Licence statements re-users must reproduce when republishing.","items":{"type":"object","properties":{"source":{"type":"string"},"licence":{"type":"string"},"statement":{"type":"string"}}}},"cache":{"type":"object","description":"Disclosed on cached serves — a cached response never pretends to be live.","properties":{"hit":{"type":"boolean"},"age_seconds":{"type":"integer"},"stale":{"type":"boolean"},"tier":{"type":"string"}}}}}}},"paths":{"/api/v1/area":{"get":{"summary":"Area report","description":"Concise area-level report for a postcode or outcode: investment score with breakdown, crime, schools, transport, broadband, flood, prices, trends, rental, healthcare, amenities, demographics, air quality, planning. 1 credit.","parameters":[{"name":"postcode","in":"query","required":true,"schema":{"type":"string"},"example":"SW1A 1AA","description":"Full UK postcode or outcode."}],"responses":{"200":{"description":"Area report with per-section provenance and meta.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}}}}},"/api/v1/investment-score":{"get":{"summary":"Investment score","description":"Focused projection of the area report: 1–10 score, weighted breakdown, completeness. 1 credit.","parameters":[{"name":"postcode","in":"query","required":true,"schema":{"type":"string"},"example":"N1"}],"responses":{"200":{"description":"Score payload"},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}}}}},"/api/v1/property":{"get":{"summary":"Property report (flagship)","description":"Property-grade report by UPRN (preferred), postcode, or — on paid plans — address string (resolved via licensed OS Places, +2 credits). EPC attributes, sale history facts, council-tax estimate, flood, planning, crime, schools, transport, broadband, demographics, deprivation, heritage. 5 credits. Requires the read:property scope.","parameters":[{"name":"uprn","in":"query","schema":{"type":"string"},"description":"Unique Property Reference Number (preferred key)."},{"name":"postcode","in":"query","schema":{"type":"string"},"description":"Full postcode for postcode-level data."},{"name":"address","in":"query","schema":{"type":"string"},"description":"Address string (paid plans; OS Places resolution; +2 credits)."},{"name":"display","in":"query","schema":{"type":"boolean"},"description":"Include address strings — restricted to residential property price information display (see terms)."}],"responses":{"200":{"description":"Property report"},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}}}}},"/api/v1/comparables":{"get":{"summary":"Sold-price comparables","description":"Recent HM Land Registry sales around a postcode (exact-outcode matching) with stats. Max 100 rows/call. Top-level provenance block (HMLR Price Paid) + attribution in meta. 2 credits. read:property scope.","parameters":[{"name":"postcode","in":"query","required":true,"schema":{"type":"string"}},{"name":"radius","in":"query","schema":{"type":"integer","minimum":100,"maximum":5000,"default":1000}},{"name":"months","in":"query","schema":{"type":"integer","minimum":1,"maximum":60,"default":24}},{"name":"display","in":"query","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Comparables"},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}}}}},"/api/v1/epc":{"get":{"summary":"EPC certificates","description":"Certificate attributes by UPRN or postcode (newest first). Attributes only — no address strings. Top-level provenance block (MHCLG EPC register) + attribution in meta. 1 credit. read:property scope.","parameters":[{"name":"uprn","in":"query","schema":{"type":"string"}},{"name":"postcode","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Certificates"},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}}}}},"/api/v1/coverage":{"get":{"summary":"Coverage pre-flight (free)","description":"Which datasets hold data for a postcode — check before spending credits. 0 credits.","parameters":[{"name":"postcode","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Coverage flags"},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}}}}},"/api/v1/compare":{"post":{"summary":"Compare areas","description":"Compare 2–5 postcodes/outcodes with honest, data-backed verdicts. 1 credit per postcode.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"postcodes":{"type":"array","items":{"type":"string"},"minItems":2,"maxItems":5}},"required":["postcodes"]},"example":{"postcodes":["N1","E8","SE15"]}}}},"responses":{"200":{"description":"Comparison"},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}}}}},"/api/v1/summary":{"post":{"summary":"AI area summary","description":"LLM-written summary of OUR cached area data (no client-supplied prompt content). `provenance` maps every section the summary draws on to its source, licence and vintage. 10 credits. 30-day cache.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"postcode":{"type":"string"}},"required":["postcode"]},"example":{"postcode":"E8"}}}},"responses":{"200":{"description":"Summary"},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}}}}},"/api/v1/metrics/{metric}":{"get":{"summary":"Published indices","description":"Derived metrics with published methodology. Live: green-premium. Top-level provenance block naming the inputs and linking the methodology page. Named coming-soon (explicit 501): ppsqm, liquidity, new-build-premium, leasehold, retrofit-potential, affordability, road-danger. 1 credit.","parameters":[{"name":"metric","in":"path","required":true,"schema":{"type":"string"},"example":"green-premium"},{"name":"outcode","in":"query","required":true,"schema":{"type":"string"},"example":"LS6"}],"responses":{"200":{"description":"Metric payload with methodology link"},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"501":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}}}}},"/api/v1/rankings":{"get":{"summary":"Persona outcode rankings","description":"Persona-weighted outcode rankings, rank-ordered nationally and recomputed twice monthly. 1 credit. meta.attribution carries the licence statements for the requested persona's score inputs — the young_professional nightlife input is OSM-derived (ODbL), so reproduce that statement if you republish. Enabled 2026-08-03 (see the changelog).","parameters":[{"name":"persona","in":"query","schema":{"type":"string","enum":["investor","family","young_professional"],"default":"investor"}},{"name":"region","in":"query","schema":{"type":"string"},"description":"Outcode prefix filter."},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":250,"default":50}}],"responses":{"200":{"description":"Rankings"},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}},"503":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Machine-readable code"},"message":{"type":"string","description":"Human-readable explanation"}},"required":["error","message"]}}}}}}}}}