{"openapi":"3.1.0","info":{"title":"Postcode Context API - UK Socio-Economic, Property & Demographic Intelligence","version":"1.0.0","description":"High-performance, 100% stateless UK postcode context API and Remote MCP Server running on Cloudflare Workers and Cloudflare D1. Monitored and monetised natively via x402 v2 (USDC on Base) and RapidAPI Gateway. Combines ONS Census 2021, HM Land Registry, Open EPC Register, Indices of Multiple Deprivation (IMD), and Ofcom Connected Nations broadband under OGL v3.0.","contact":{"name":"Postcode Context Support","url":"https://postcodecontext.uk"},"license":{"name":"Open Government Licence v3.0","url":"https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/"}},"servers":[{"url":"https://api.postcodecontext.uk","description":"Production Edge Anycast Network"},{"url":"http://localhost:8787","description":"Local Wrangler Dev Server"}],"components":{"schemas":{"SummaryForAI":{"type":"object","required":["ai_context_briefing","primary_persona_tag","affluence_tier","b2c_spending_propensity","affluence_score_100","family_suitability_score_100","commuter_connectivity_score_100","property_value_index"],"properties":{"ai_context_briefing":{"type":"string","description":"Pre-synthesised dense natural language summary designed for LLM context window injection"},"primary_persona_tag":{"type":"string","description":"Target marketing and socio-economic persona"},"affluence_tier":{"type":"string","enum":["Ultra-Prime","Affluent","Mid-Market","Working-Striving","High-Deprivation"]},"b2c_spending_propensity":{"type":"string"},"affluence_score_100":{"type":"integer","minimum":1,"maximum":100},"family_suitability_score_100":{"type":"integer","minimum":1,"maximum":100},"commuter_connectivity_score_100":{"type":"integer","minimum":1,"maximum":100},"property_value_index":{"type":"integer","minimum":1,"maximum":100}}},"Location":{"type":"object","required":["postcode","clean_postcode","outcode","incode","lsoa_code","lsoa_name","local_authority","constituency","region_or_nation","rural_urban_classification","latitude","longitude"],"properties":{"postcode":{"type":"string","example":"SW1A 1AA"},"clean_postcode":{"type":"string","example":"SW1A1AA"},"outcode":{"type":"string","example":"SW1A"},"incode":{"type":"string","example":"1AA"},"lsoa_code":{"type":"string","example":"E01004736"},"msoa_code":{"type":"string","example":"E02000977"},"lsoa_name":{"type":"string","example":"Westminster 018C"},"local_authority":{"type":"string","example":"Westminster"},"constituency":{"type":"string","example":"Ipswich"},"region_or_nation":{"type":"string","example":"East of England"},"rural_urban_classification":{"type":"string","example":"Urban city and town"},"latitude":{"type":"number","example":52.056736},"longitude":{"type":"number","example":1.148217}}},"PropertyAndEnergy":{"type":"object","required":["median_house_price_gbp","price_per_sqm_gbp","sales_volume_3yr","dominant_property_type","avg_floor_area_sqm","epc_rating_current","epc_rating_potential","retrofit_upside_potential","pre_1930_housing_pct"],"properties":{"median_house_price_gbp":{"type":"integer","example":165000},"price_per_sqm_gbp":{"type":"integer","example":2450},"sales_volume_3yr":{"type":"integer","example":118},"dominant_property_type":{"type":"string","example":"Flat/Maisonette"},"avg_floor_area_sqm":{"type":"number","example":62.5},"epc_rating_current":{"type":"string","example":"C"},"epc_rating_potential":{"type":"string","example":"B"},"retrofit_upside_potential":{"type":"string"},"pre_1930_housing_pct":{"type":"number","example":34}}},"DeprivationDeciles":{"type":"object","required":["_scale_explanation","imd_overall_decile","imd_overall_rank","income_deprivation_decile","employment_deprivation_decile","education_skills_decile","health_deprivation_decile","crime_safety_decile","housing_barriers_decile","living_environment_decile"],"properties":{"_scale_explanation":{"type":"string"},"imd_overall_decile":{"type":"integer","minimum":1,"maximum":10},"imd_overall_rank":{"type":"integer"},"income_deprivation_decile":{"type":"integer","minimum":1,"maximum":10},"employment_deprivation_decile":{"type":"integer","minimum":1,"maximum":10},"education_skills_decile":{"type":"integer","minimum":1,"maximum":10},"health_deprivation_decile":{"type":"integer","minimum":1,"maximum":10},"crime_safety_decile":{"type":"integer","minimum":1,"maximum":10},"housing_barriers_decile":{"type":"integer","minimum":1,"maximum":10},"living_environment_decile":{"type":"integer","minimum":1,"maximum":10}}},"CensusDemographics":{"type":"object","required":["population_density_per_sqkm","est_median_household_income_gbp","tenure_breakdown_pct","qualifications_pct","ns_sec_managerial_professional_pct","economically_active_employed_pct","retired_pct","student_pct","work_from_home_pct","car_ownership_pct","age_distribution_pct"],"properties":{"population_density_per_sqkm":{"type":"integer","example":6800},"est_median_household_income_gbp":{"type":"integer","example":29500},"tenure_breakdown_pct":{"type":"object","properties":{"owned_outright":{"type":"number"},"mortgaged":{"type":"number"},"private_rented":{"type":"number"},"social_rented":{"type":"number"}}},"qualifications_pct":{"type":"object","properties":{"degree_or_higher_level4_plus":{"type":"number"},"no_qualifications":{"type":"number"}}},"ns_sec_managerial_professional_pct":{"type":"number"},"economically_active_employed_pct":{"type":"number"},"retired_pct":{"type":"number"},"student_pct":{"type":"number"},"work_from_home_pct":{"type":"number"},"car_ownership_pct":{"type":"object","properties":{"zero_cars":{"type":"number"},"two_or_more_cars":{"type":"number"}}},"age_distribution_pct":{"type":"object","properties":{"age_0_to_15":{"type":"number"},"age_16_to_29":{"type":"number"},"age_30_to_44":{"type":"number"},"age_45_to_64":{"type":"number"},"age_65_plus":{"type":"number"}}}}},"DigitalInfrastructure":{"type":"object","required":["median_download_mbps","gigabit_availability_pct"],"properties":{"median_download_mbps":{"type":"number","example":74.2},"gigabit_availability_pct":{"type":"number","example":89.4}}},"LandmarkContext":{"type":"object","required":["is_national_landmark","landmark_name","landmark_category","demographic_distortion_note"],"properties":{"is_national_landmark":{"type":"boolean","example":true},"landmark_name":{"type":"string","example":"Buckingham Palace"},"landmark_category":{"type":"string","enum":["Royal Residence","Government & Executive","Parliamentary & Civic","National Defence & Security","Central Banking & Financial","National Heritage & Cathedral","Diplomatic & Embassy","Academic & Historic Seat","Healthcare & Medical Research","Correctional & Institutional","National Sports & Culture","Major Transport Hub","Special Non-Geographic","Military Overseas & BFPO"],"example":"Royal Residence"},"demographic_distortion_note":{"type":"string","example":"Census demographics reflect residential blocks in Westminster 018C (Wellington Barracks and rental flats towards Victoria), not the Royal Household."}}},"PostcodeIntelligenceResponse":{"type":"object","required":["summary_for_ai","location","property_and_energy","deprivation_deciles","census_demographics","digital_infrastructure","_attribution"],"properties":{"summary_for_ai":{"$ref":"#/components/schemas/SummaryForAI"},"location":{"$ref":"#/components/schemas/Location"},"property_and_energy":{"$ref":"#/components/schemas/PropertyAndEnergy"},"deprivation_deciles":{"$ref":"#/components/schemas/DeprivationDeciles"},"census_demographics":{"$ref":"#/components/schemas/CensusDemographics"},"digital_infrastructure":{"$ref":"#/components/schemas/DigitalInfrastructure"},"landmark_context":{"$ref":"#/components/schemas/LandmarkContext"},"_attribution":{"type":"string"},"_billing":{"type":"object","properties":{"mode":{"type":"string"},"remaining_today":{"type":"integer"}}}}}}},"paths":{"/api/v1/postcode/{postcode}":{"get":{"summary":"Get UK Postcode Intelligence Profile","description":"Returns full demographic, housing market, EPC energy efficiency, broadband, and deprivation indices for a single UK postcode. Normalises input automatically.","operationId":"get_postcode_intelligence","parameters":[{"name":"postcode","in":"path","required":true,"description":"UK postcode (e.g. SW1A 1AA, IP1 1AA, M1 1AE)","schema":{"type":"string","example":"SW1A 1AA"}},{"name":"view","in":"query","required":false,"description":"Slice target view: full (complete dataset, default), summary/ai (~80 tokens brief), property (valuations & EPC), or demographics (Census & IMD deciles)","schema":{"type":"string","enum":["full","summary","property","demographics"],"default":"full"}},{"name":"format","in":"query","required":false,"description":"Export format: json (default), flat (flattened 1-level key/value object), or csv (RFC 4180 text/csv)","schema":{"type":"string","enum":["json","flat","csv"],"default":"json"}}],"responses":{"200":{"description":"Successful postcode intelligence profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostcodeIntelligenceResponse"}},"text/csv":{"schema":{"type":"string","description":"CSV data export"}}}},"402":{"description":"Payment required (Free IP quota exceeded; requires x402 USDC micropayment or RapidAPI proxy header)"},"404":{"description":"Postcode not found in database"}}}},"/api/v1/compare":{"post":{"summary":"Compare UK Postcodes","description":"Compares 2 to 5 UK postcodes side-by-side with an automated AI comparison ranking by affluence, crime safety, value per sqm, broadband speed, and family suitability.","operationId":"compare_uk_postcodes","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["postcodes"],"properties":{"postcodes":{"type":"array","description":"List of 2 to 5 UK postcodes to compare","minItems":2,"maxItems":5,"items":{"type":"string","example":"SW1A 1AA"}}},"example":{"postcodes":["SW1A 1AA","EC1A 1BB"]}},"example":{"postcodes":["SW1A 1AA","EC1A 1BB"]}}}},"responses":{"200":{"description":"Comparison analysis successfully generated","content":{"application/json":{"schema":{"type":"object","properties":{"postcodes":{"type":"array","items":{"$ref":"#/components/schemas/PostcodeIntelligenceResponse"}},"comparison_synthesis":{"type":"object"},"_attribution":{"type":"string"}}}}}},"402":{"description":"Payment required"}}}},"/api/v1/batch":{"post":{"summary":"Batch Enrich UK Postcodes","description":"High-throughput bulk enrichment of up to 50 UK postcodes with cohort aggregation metrics (average affluence, dominant persona, and top property values). Supports ?view= and ?format=csv.","operationId":"enrich_postcodes_batch","parameters":[{"name":"view","in":"query","required":false,"description":"Slice target view across batch results: full (default), summary, property, or demographics","schema":{"type":"string","enum":["full","summary","property","demographics"],"default":"full"}},{"name":"format","in":"query","required":false,"description":"Export format: json (default), flat, or csv","schema":{"type":"string","enum":["json","flat","csv"],"default":"json"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["postcodes"],"properties":{"postcodes":{"type":"array","description":"List of 1 to 50 UK postcodes to enrich","minItems":1,"maxItems":50,"items":{"type":"string","example":"SW1A 1AA"}}},"example":{"postcodes":["SW1A 1AA","IP1 1AA","EH1 1YZ"]}},"example":{"postcodes":["SW1A 1AA","IP1 1AA","EH1 1YZ"]}}}},"responses":{"200":{"description":"Batch enrichment and cohort summary completed","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/PostcodeIntelligenceResponse"}},"cohort_summary":{"type":"object"},"_attribution":{"type":"string"}}}}}},"402":{"description":"Payment required (No free tier on batch requests)"}}}},"/api/v1/outcode/{outcode}":{"get":{"summary":"Get Outward Code District Summary","description":"Aggregates all postcodes within a postal outward district (e.g. IP1, SW1A, M1) to return district-wide median house prices, deprivation ranges, and top personas.","operationId":"get_outcode_district_summary","parameters":[{"name":"outcode","in":"path","required":true,"description":"UK outward postal district code","schema":{"type":"string","example":"SW1A"}}],"responses":{"200":{"description":"District summary generated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"outcode":{"type":"string"},"total_postcodes":{"type":"integer"},"district_median_house_price_gbp":{"type":"integer"},"district_avg_price_per_sqm_gbp":{"type":"integer"},"average_affluence_score_100":{"type":"integer"},"dominant_affluence_tier":{"type":"string"},"imd_overall_decile_range":{"type":"object"},"top_personas":{"type":"array","items":{"type":"string"}},"district_context_briefing":{"type":"string"},"_attribution":{"type":"string"}}}}}},"402":{"description":"Payment required"}}}},"/api/v1/dictionary":{"get":{"summary":"Get Machine-Readable Data Dictionary","description":"Returns the complete field specification catalog, mathematical calculation formulas, statistical scales, and OGL v3.0 sovereign data provenance for all 48 variables served by the API. Always free with zero token consumption.","operationId":"get_data_dictionary","parameters":[{"name":"domain","in":"query","required":false,"description":"Filter fields by domain category","schema":{"type":"string","enum":["summary_for_ai","property_and_energy","deprivation_deciles","census_demographics","digital_infrastructure","location","query_and_fallbacks"]}},{"name":"field","in":"query","required":false,"description":"Filter by specific field name","schema":{"type":"string","example":"affluence_score_100"}}],"responses":{"200":{"description":"Data dictionary metadata returned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"version":{"type":"string"},"total_fields":{"type":"integer"},"domains":{"type":"array","items":{"type":"string"}},"entries":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"domain":{"type":"string"},"type":{"type":"string"},"unit":{"type":"string"},"scale":{"type":"string"},"description":{"type":"string"},"formula":{"type":"string"},"source":{"type":"string"},"example":{}}}}}}}}}}}}}}