{"openapi":"3.1.0","info":{"title":"Carucate Derived Market Data API","version":"1.0.0-beta","description":"Professional, aggregate-only published property-market data for England and Wales. No individual sales, addresses or EPC certificates are exposed."},"paths":{"/api/v1/areas/search":{"get":{"summary":"Search published Carucate areas","description":"Returns at most ten published postcode districts or market areas matching a name or postcode-district prefix. Individual addresses and postcode sectors are excluded.","security":[{"CarucateApiKey":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":100,"example":"London"}}],"responses":{"200":{"description":"Published area matches"},"400":{"description":"Invalid query"},"401":{"description":"Missing, invalid or revoked API key"},"403":{"description":"Professional access required"},"429":{"description":"Rate or monthly allowance exceeded"}}}},"/api/v1/account/usage":{"get":{"summary":"Current API-key allowance","description":"Returns only the calling key's current rate and monthly allowance. This request itself counts toward both limits.","security":[{"CarucateApiKey":[]}],"responses":{"200":{"description":"Current key-scoped allowance"},"401":{"description":"Missing, invalid or revoked API key"},"403":{"description":"Professional access required"},"429":{"description":"Rate or monthly allowance exceeded; rate exhaustion includes Retry-After."}}}},"/api/v1/areas/{areaType}/{areaCode}":{"get":{"summary":"Published area summary","security":[{"CarucateApiKey":[]}],"parameters":[{"name":"areaType","in":"path","required":true,"schema":{"type":"string","enum":["district","built_up_area","local_authority","region","country"]}},{"name":"areaCode","in":"path","required":true,"schema":{"type":"string","example":"E12000007"}}],"responses":{"200":{"description":"Published aggregate area summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AreaSummary"},"example":{"area":{"type":"region","code":"E12000007","name":"London"},"market":{"median_price_pence":52800000,"median_price_per_sqm_pence":652600,"total_sales":3703795,"epc_floor_area_coverage":0.5,"data_current_to":"2026-06-30"},"limitations":["Aggregate published market data only."]}}}},"401":{"description":"Missing, invalid or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Professional access required"},"404":{"description":"Area is unavailable or not published"},"429":{"description":"Rate or monthly allowance exceeded"}}}},"/api/v1/areas/{areaType}/{areaCode}/history":{"get":{"summary":"Published aggregate market history","description":"Returns exact monthly, rolling-quarter or rolling-12-month aggregate history for all market, one property type, or one floor-area band. Postcode sectors and property-type-plus-size combinations are excluded.","security":[{"CarucateApiKey":[]}],"parameters":[{"name":"areaType","in":"path","required":true,"schema":{"type":"string","enum":["district","built_up_area","local_authority","region","country"]}},{"name":"areaCode","in":"path","required":true,"schema":{"type":"string","example":"E12000007"}},{"name":"years","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":31,"default":5}},{"name":"cadence","in":"query","required":false,"schema":{"type":"string","enum":["monthly","rolling_3m","rolling_12m"],"default":"monthly"},"description":"Rolling history has ten years available."},{"name":"property_type","in":"query","required":false,"schema":{"type":"string","enum":["*","D","S","T","F"],"default":"*"}},{"name":"size_band","in":"query","required":false,"schema":{"type":"string","enum":["all","s","m","l","xl"],"default":"all"},"description":"Choose either this or property_type; not both."}],"responses":{"200":{"description":"Published aggregate history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AreaHistory"},"example":{"area":{"type":"region","code":"E12000007","name":"London"},"period_years":5,"cadence":"rolling_12m","selection":{"property_type":"D","size_band":"all"},"data_current_to":"2026-06-30","series":[{"period":"2026-06-01","sale_count":16342,"median_price_pence":52800000,"median_price_per_sqm_pence":652600}],"limitations":["Published aggregate series only."]}}}},"401":{"description":"Missing, invalid or revoked API key"},"403":{"description":"Professional access required"},"404":{"description":"Area is unavailable or not published"},"429":{"description":"Rate or monthly allowance exceeded"}}}},"/api/v1/rankings":{"get":{"summary":"Published Top or Bottom market rankings","description":"Returns up to ten published regions, local authorities, cities/towns or postcode districts. Postcode-sector rankings are excluded.","security":[{"CarucateApiKey":[]}],"parameters":[{"name":"scope","in":"query","required":false,"schema":{"type":"string","enum":["region","built_up_area","local_authority","district"],"default":"region"}},{"name":"metric","in":"query","required":false,"schema":{"type":"string","enum":["price","psm","coverage"],"default":"price"}},{"name":"direction","in":"query","required":false,"schema":{"type":"string","enum":["top","bottom"],"default":"top"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10,"default":10}}],"responses":{"200":{"description":"Published rankings"},"400":{"description":"Invalid filter"},"401":{"description":"Missing, invalid or revoked API key"},"403":{"description":"Professional access required"},"429":{"description":"Rate or monthly allowance exceeded"}}}},"/api/v1/areas/{areaType}/{areaCode}/evidence":{"get":{"summary":"Published contextual market evidence","description":"Returns aggregate energy-transition evidence and, where available for the geography, Census tenure, official private-rent and flood-screening context. Null is not zero.","security":[{"CarucateApiKey":[]}],"parameters":[{"name":"areaType","in":"path","required":true,"schema":{"type":"string","enum":["district","built_up_area","local_authority","region","country"]}},{"name":"areaCode","in":"path","required":true,"schema":{"type":"string","example":"E12000007"}}],"responses":{"200":{"description":"Published aggregate evidence"},"401":{"description":"Missing, invalid or revoked API key"},"403":{"description":"Professional access required"},"404":{"description":"Area is unavailable or not published"},"429":{"description":"Rate or monthly allowance exceeded"}}}},"/api/v1/areas/{areaType}/{areaCode}/evidence-brief":{"get":{"summary":"Professional Evidence Brief representation","description":"Returns the allow-listed aggregate fields in the printable Professional Evidence Brief. It contains no individual properties, addresses, full postcodes, raw source records or postcode-sector values.","security":[{"CarucateApiKey":[]}],"parameters":[{"name":"areaType","in":"path","required":true,"schema":{"type":"string","enum":["district","built_up_area","local_authority","region","country"]}},{"name":"areaCode","in":"path","required":true,"schema":{"type":"string","example":"E12000007"}},{"name":"modules","in":"query","required":false,"schema":{"type":"string","example":"market,market_calculations,history,market_structure,energy"},"description":"Comma-separated approved modules: market, market_calculations, history, market_structure, property_types, floor_area, energy, tenure, rents, housing_supply, flood. Omit for the full Brief. Limitations are always included."},{"name":"history_years","in":"query","required":false,"schema":{"type":"integer","enum":[1,3,5,10],"default":5},"description":"Selected rolling-12-month market-history window. Used only when history is selected; current-market figures remain trailing 24 months."}],"responses":{"200":{"description":"Aggregate Professional Evidence Brief representation"},"400":{"description":"No approved module selected"},"401":{"description":"Missing, invalid or revoked API key"},"403":{"description":"Professional access required"},"404":{"description":"Area is unavailable or not published"},"429":{"description":"Rate or monthly allowance exceeded"}}}}},"components":{"securitySchemes":{"CarucateApiKey":{"type":"apiKey","in":"header","name":"X-Carucate-API-Key"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"A valid API key is required."}}},"Area":{"type":"object","required":["type","code","name"],"properties":{"type":{"type":"string","enum":["district","built_up_area","local_authority","region","country"]},"code":{"type":"string"},"name":{"type":"string"}}},"AreaSummary":{"type":"object","required":["area","market","limitations"],"properties":{"area":{"$ref":"#/components/schemas/Area"},"market":{"type":"object","properties":{"median_price_pence":{"type":["integer","null"]},"median_price_per_sqm_pence":{"type":["integer","null"]},"total_sales":{"type":"integer"},"epc_floor_area_coverage":{"type":["number","null"]},"data_current_to":{"type":["string","null"],"format":"date"}}},"limitations":{"type":"array","items":{"type":"string"}}}},"MonthPoint":{"type":"object","required":["period","sale_count"],"properties":{"period":{"type":"string","format":"date"},"sale_count":{"type":"integer"},"median_price_pence":{"type":["integer","null"]},"median_price_per_sqm_pence":{"type":["integer","null"]}}},"AreaHistory":{"type":"object","required":["area","period_years","cadence","selection","series","limitations"],"properties":{"area":{"$ref":"#/components/schemas/Area"},"period_years":{"type":"integer"},"cadence":{"type":"string","enum":["monthly","rolling_3m","rolling_12m"]},"selection":{"type":"object","properties":{"property_type":{"type":"string"},"size_band":{"type":"string"}}},"data_current_to":{"type":["string","null"],"format":"date"},"series":{"type":"array","items":{"$ref":"#/components/schemas/MonthPoint"}},"limitations":{"type":"array","items":{"type":"string"}}}}}}}