{"openapi":"3.1.0","info":{"title":"Postcode Context UK - Demographic, Property & Deprivation Intelligence API","version":"1.0.0","description":"High-performance, 100% stateless UK postcode context API and Remote MCP Server running on Cloudflare Workers edge nodes. Combines ONS Census 2021 demographics, Index of Multiple Deprivation (IMD 2019) deciles, HM Land Registry transaction records, Open EPC Register ratings, and Ofcom broadband connectivity under OGL v3.0. Features pre-synthesised AI affluence scores and dense context window briefings. Fully monetised natively via x402 v2 (USDC on Base Mainnet) and RapidAPI Gateway.","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":"Cities of London and Westminster"},"region_or_nation":{"type":"string","example":"London"},"rural_urban_classification":{"type":"string","example":"Urban major conurbation"},"latitude":{"type":"number","example":51.501009},"longitude":{"type":"number","example":-0.141588}}},"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":1250000},"price_per_sqm_gbp":{"type":"integer","example":14200},"sales_volume_3yr":{"type":"integer","example":118},"dominant_property_type":{"type":"string","example":"Flat/Maisonette"},"avg_floor_area_sqm":{"type":"number","example":88},"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":{"tags":["Demographics","UK Property","Geospatial","Census"],"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","x-x402-price":"$0.005","x-x402-network":"eip155:8453","x-x402-asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","x-x402-payTo":"0x8ab7568ac097523e81a94644235fcf19a2b85670","parameters":[{"name":"postcode","in":"path","required":true,"description":"UK postcode (e.g. SW1A 1AA, BB7 3BB, 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: Settle via x402 (USDC on Base Mainnet) or access our free tier on RapidAPI: https://rapidapi.com/postcode-context-uk-postcode-context-uk-default/api/postcode-context-uk"},"404":{"description":"Postcode not found in database"}}}},"/api/v1/compare":{"post":{"tags":["Demographics","UK Property","Geospatial","Census"],"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","x-x402-price":"$0.01","x-x402-network":"eip155:8453","x-x402-asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","x-x402-payTo":"0x8ab7568ac097523e81a94644235fcf19a2b85670","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","BB7 3BB"]}},"example":{"postcodes":["SW1A 1AA","BB7 3BB"]}}}},"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","description":"Automated synthesis highlighting extremes, value outliers, and comparative trade-offs","properties":{"highest_affluence":{"type":"object","properties":{"postcode":{"type":"string","example":"SW1A 1AA"},"score":{"type":"integer","example":98},"tier":{"type":"string","example":"Ultra-Prime"}}},"lowest_crime":{"type":"object","properties":{"postcode":{"type":"string","example":"BB7 3BB"},"decile":{"type":"integer","example":10}}},"best_value_per_sqm":{"type":"object","properties":{"postcode":{"type":"string","example":"BB7 3BB"},"price_per_sqm_gbp":{"type":"integer","example":6462}}},"fastest_broadband":{"type":"object","properties":{"postcode":{"type":"string","example":"BB7 3BB"},"median_down_mbps":{"type":"number","example":350}}},"highest_family_score":{"type":"object","properties":{"postcode":{"type":"string","example":"BB7 3BB"},"score":{"type":"integer","example":82}}},"synthesis_notes":{"type":"string","example":"SW1A 1AA commands higher property prices per sqm and high affluence (98), while BB7 3BB (Dunsop Bridge, centre of GB) offers superior family suitability and lowest crime."}}},"_attribution":{"type":"string"}}}}}},"402":{"description":"Payment Required: Settle via x402 (USDC on Base Mainnet) or access our free tier on RapidAPI: https://rapidapi.com/postcode-context-uk-postcode-context-uk-default/api/postcode-context-uk"}}}},"/api/v1/batch":{"post":{"tags":["Demographics","UK Property","Geospatial","Census"],"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","x-x402-price":"$0.05","x-x402-network":"eip155:8453","x-x402-asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","x-x402-payTo":"0x8ab7568ac097523e81a94644235fcf19a2b85670","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","BB7 3BB","EH1 1YZ"]}},"example":{"postcodes":["SW1A 1AA","BB7 3BB","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","description":"Macro cohort statistics across all enriched postcodes in the batch","properties":{"total_requested":{"type":"integer","example":3},"total_matched":{"type":"integer","example":3},"cohort_mean_affluence_score_100":{"type":"number","example":78.5},"cohort_median_house_price_gbp":{"type":"integer","example":545000},"dominant_affluence_tier":{"type":"string","example":"Affluent"},"top_3_highest_value_postcodes":{"type":"array","items":{"type":"object","properties":{"postcode":{"type":"string","example":"SW1A 1AA"},"median_house_price_gbp":{"type":"integer","example":1250000}}}}}},"_attribution":{"type":"string"}}}}}},"402":{"description":"Payment Required: Settle via x402 (USDC on Base Mainnet) or access our free tier on RapidAPI: https://rapidapi.com/postcode-context-uk-postcode-context-uk-default/api/postcode-context-uk"}}}},"/api/v1/outcode/{outcode}":{"get":{"tags":["Demographics","UK Property","Geospatial","Census"],"summary":"Get Outward Code District Summary","description":"Aggregates all postcodes within a postal outward district (e.g. BB7, SW1A, M1) to return district-wide median house prices, deprivation ranges, and top personas.","operationId":"get_outcode_district_summary","x-x402-price":"$0.005","x-x402-network":"eip155:8453","x-x402-asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","x-x402-payTo":"0x8ab7568ac097523e81a94644235fcf19a2b85670","parameters":[{"name":"outcode","in":"path","required":true,"description":"UK outward postal district code","schema":{"type":"string","example":"BB7"}}],"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: Settle via x402 (USDC on Base Mainnet) or access our free tier on RapidAPI: https://rapidapi.com/postcode-context-uk-postcode-context-uk-default/api/postcode-context-uk"}}}},"/api/v1/dictionary":{"get":{"tags":["Demographics","UK Property","Geospatial","Census"],"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":{}}}}}}}}}}}}}}