{"openapi":"3.1.0","info":{"title":"Postcode Context - Great Britain Demographics & Property Intelligence API","version":"1.0.0","description":"Give AI agents real-world Great Britain location intelligence. High-performance, 100% stateless Great Britain postcode context API and Remote MCP Server running on Cloudflare Workers edge nodes. Turn any postcode into structured property, demographic, energy, school, healthcare, and connectivity context in one call. Covers England, Scotland, and Wales (Northern Ireland BT postcodes strictly excluded for 100% royalty-free OGL v3.0 compliance without proprietary PAF or LPS fees). Unifies 14 statutory open datasets: ONS Census 2021, ONSPD, Ordnance Survey OS OpenData, Royal Mail Gridlink allocation, HM Land Registry 3-year rolling transactions, Open EPC domestic register, English Indices of Deprivation (IMD 2019), Welsh WIMD 2025, Scottish SIMD 2020, Ofcom Connected Nations broadband, DfE Get Information About Schools (GIAS), Ofsted Inspection Outcomes, Care Quality Commission (CQC) healthcare registries, and Scottish/Welsh schools directories. Features pre-synthesised AI affluence scores, multi-criteria comparisons, and dense 2-sentence context briefings. Natively monetised via x402 v2 (USDC on Base Mainnet eip155:8453) with high-throughput batch screening ($0.05 per 50 postcodes).","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 archetype"},"affluence_tier":{"type":"string","enum":["Ultra-Prime","Affluent","Mid-Market","Working-Striving","High-Deprivation"],"description":"Categorical socio-economic bracket segmenting Great Britain residential neighbourhoods into 5 macro cohorts"},"b2c_spending_propensity":{"type":"string","description":"Inferred neighbourhood consumer expenditure profile derived from local affluence tier and tenure. Represents a macro area characteristic, not an observed financial record of an individual household."},"affluence_score_100":{"type":"integer","minimum":1,"maximum":100,"description":"Composite socio-economic score from 1 to 100 (weighted: 35% modelled income, 25% human capital qualifications/NS-SeC, 25% IMD deprivation freedom, 15% homeownership equity; ~10 points represents ~1 national decile shift)"},"family_suitability_score_100":{"type":"integer","minimum":1,"maximum":100,"description":"Composite family suitability score from 1 to 100 (weighted: 40% statutory crime safety, 30% school/education opportunity, 30% child and parenting-age demographic density)"},"commuter_connectivity_score_100":{"type":"integer","minimum":1,"maximum":100,"description":"Broadband & transport transit access score from 1 to 100 (evaluating zero-car transit reliance and professional commuter corridor affluence)"},"property_value_index":{"type":"integer","minimum":1,"maximum":100,"description":"Relative property valuation index benchmarked against prime central London baseline (£16,200/sqm ceiling = 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,"description":"HM Land Registry 3-year rolling median transaction price in GBP"},"price_per_sqm_gbp":{"type":"integer","example":14200,"description":"Synthetic property valuation benchmark joining HM Land Registry 3-year rolling median transaction prices with Open EPC domestic modal internal floor areas for the dominant housing typology at postcode level"},"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,"description":"Statutory Crime Deprivation Decile (1-10) from the English IoD 2025, Welsh WIMD 2025, and Scottish SIMD 2020 (1 = highest recorded crime deprivation nationally, 10 = lowest recorded crime deprivation / safest 10%). Sourced from multi-year police records per capita at LSOA level. Represents neighbourhood historical baseline, not individual personal victimisation risk."},"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,"description":"Modelled neighbourhood estimate of annual median gross disposable household income in GBP (LSOA level). Derived from DWP/HMRC income deprivation administrative data calibrated with Census 2021 NS-SeC higher managerial occupations and Level 4 qualifications. Not an observed Census return."},"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"],"properties":{"is_national_landmark":{"type":"boolean","example":true,"description":"True if this postcode represents a major national landmark, royal palace, civic seat, or special non-geographic entity"},"landmark_name":{"type":["string","null"],"example":"Buckingham Palace"},"landmark_category":{"type":["string","null"],"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",null],"example":"Royal Residence"},"demographic_distortion_note":{"type":["string","null"],"example":"Census demographics reflect residential blocks in Westminster 018C (Wellington Barracks and rental flats towards Victoria), not the Royal Household."}}},"SchoolSummary":{"type":"object","properties":{"id":{"type":"string","example":"ENG-101138"},"name":{"type":"string","example":"St Matthew's School, Westminster"},"phase":{"type":"string","example":"Primary"},"gender":{"type":"string","example":"Mixed"},"religious_character":{"type":["string","null"],"example":"Church of England"},"admissions_policy":{"type":["string","null"],"example":"Non-selective"},"distance_km":{"type":"number","example":0.54}}},"EducationAndSchools":{"type":"object","properties":{"nearest_primary_school":{"anyOf":[{"$ref":"#/components/schemas/SchoolSummary"},{"type":"null"}]},"nearest_secondary_school":{"anyOf":[{"$ref":"#/components/schemas/SchoolSummary"},{"type":"null"}]}}},"HealthcareSummary":{"type":"object","properties":{"id":{"type":"string","example":"CQC-1-12687408410"},"name":{"type":"string","example":"Medloop"},"care_type":{"type":"string","example":"GP Practice"},"distance_km":{"type":"number","example":0.48},"regulator":{"type":"string","example":"CQC"},"rating":{"type":["string","null"],"example":"Good"},"inspection_date":{"type":["string","null"],"example":"22/Jan/2024"}}},"HealthcareAndServices":{"type":"object","properties":{"nearest_gp_surgery":{"anyOf":[{"$ref":"#/components/schemas/HealthcareSummary"},{"type":"null"}]},"nearest_hospital":{"anyOf":[{"$ref":"#/components/schemas/HealthcareSummary"},{"type":"null"}]}}},"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"},"schools_and_education":{"$ref":"#/components/schemas/EducationAndSchools"},"healthcare_and_services":{"$ref":"#/components/schemas/HealthcareAndServices"},"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","Great Britain Property","Geospatial","Census"],"summary":"Get Great Britain Postcode Intelligence Profile","description":"Returns full demographic, housing market, EPC energy efficiency, broadband, and deprivation indices for a single Great Britain postcode (England, Scotland, Wales). Normalises input automatically (accepts space, compact SW1A1AA, or URL-encoded + / %20). Also accessible via query parameter at GET /api/v1/postcode?postcode=SW1A1AA.","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":"Great Britain postcode (e.g. SW1A 1AA, BB7 3BB, EH1 1YZ, CF10 1EP). Accepts spaces, no spaces (SW1A1AA), or URL-encoded (+ / %20). Northern Ireland (BT) postcodes excluded.","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), demographics (Census & IMD deciles), education (nearest schools & proximity), healthcare (GP & hospital), or services (education, healthcare & digital connectivity)","schema":{"type":"string","enum":["full","summary","property","demographics","education","schools","healthcare","health","services","infrastructure"],"default":"full"}},{"name":"exclude","in":"query","required":false,"description":"Comma-separated domains to exclude from payload: schools, healthcare (e.g. exclude=schools,healthcare)","schema":{"type":"string","example":"schools,healthcare"}},{"name":"format","in":"query","required":false,"description":"Export format: json (default), flat, csv, or markdown/md (GitHub Flavored Markdown)","schema":{"type":"string","enum":["json","flat","csv","markdown","md"],"default":"json"}}],"responses":{"200":{"description":"Successful postcode intelligence profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostcodeIntelligenceResponse"}},"text/markdown":{"schema":{"type":"string","description":"GitHub Flavored Markdown export"}},"text/csv":{"schema":{"type":"string","description":"CSV data export"}}}},"402":{"description":"Payment Required: Settle via x402 protocol (USDC on Base Mainnet, eip155:8453)."},"404":{"description":"Postcode not found in database or outside territorial coverage"}}}},"/api/v1/postcode":{"get":{"tags":["Demographics","Great Britain Property","Geospatial","Census"],"summary":"Get Great Britain Postcode Intelligence Profile (Query Parameter)","description":"Query-parameter alternative to /api/v1/postcode/{postcode}. Returns full demographic, housing market, EPC energy efficiency, broadband, and deprivation indices for a single Great Britain postcode.","operationId":"get_postcode_intelligence_query","x-x402-price":"$0.005","x-x402-network":"eip155:8453","x-x402-asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","x-x402-payTo":"0x8ab7568ac097523e81a94644235fcf19a2b85670","parameters":[{"name":"postcode","in":"query","required":true,"description":"Great Britain postcode (e.g. SW1A 1AA, BB7 3BB, EH1 1YZ, CF10 1EP). Accepts spaces, no spaces (SW1A1AA), or URL-encoded (+ / %20). Northern Ireland (BT) postcodes excluded.","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), demographics (Census & IMD deciles), education (nearest schools & proximity), healthcare (GP & hospital), or services (education, healthcare & digital connectivity)","schema":{"type":"string","enum":["full","summary","property","demographics","education","schools","healthcare","health","services","infrastructure"],"default":"full"}},{"name":"exclude","in":"query","required":false,"description":"Comma-separated domains to exclude from payload: schools, healthcare (e.g. exclude=schools,healthcare)","schema":{"type":"string","example":"schools,healthcare"}},{"name":"format","in":"query","required":false,"description":"Export format: json (default), flat, csv, or markdown/md (GitHub Flavored Markdown)","schema":{"type":"string","enum":["json","flat","csv","markdown","md"],"default":"json"}}],"responses":{"200":{"description":"Successful postcode intelligence profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostcodeIntelligenceResponse"}},"text/markdown":{"schema":{"type":"string","description":"GitHub Flavored Markdown export"}},"text/csv":{"schema":{"type":"string","description":"CSV data export"}}}},"402":{"description":"Payment Required: Settle via x402 protocol (USDC on Base Mainnet, eip155:8453)."},"404":{"description":"Postcode not found in database"}}}},"/api/v1/compare":{"post":{"tags":["Demographics","Great Britain Property","Geospatial","Census"],"summary":"Compare Great Britain Postcodes","description":"Compares 2 to 5 Great Britain postcodes side-by-side (England, Scotland, Wales) with an automated AI comparison ranking by affluence, crime safety, value per sqm, broadband speed, and family suitability.","operationId":"compare_gb_postcodes","x-x402-price":"$0.01","x-x402-network":"eip155:8453","x-x402-asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","x-x402-payTo":"0x8ab7568ac097523e81a94644235fcf19a2b85670","parameters":[{"name":"format","in":"query","required":false,"description":"Export format: json (default), csv, or markdown/md (GitHub Flavored Markdown)","schema":{"type":"string","enum":["json","csv","markdown","md"],"default":"json"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["postcodes"],"properties":{"postcodes":{"type":"array","description":"List of 2 to 5 Great Britain postcodes to compare (England, Scotland, Wales)","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}}},"metrics_summary":{"type":"array","description":"Raw underlying comparison metrics returned side-by-side for objective multi-criteria agent evaluation","items":{"type":"object","properties":{"postcode":{"type":"string","example":"SW1A 1AA"},"affluence_score_100":{"type":"number","example":98},"crime_safety_decile":{"type":["integer","null"],"example":6},"median_price_paid_gbp":{"type":["number","null"],"example":1450000},"price_per_sqm_gbp":{"type":["number","null"],"example":14500},"median_down_mbps":{"type":["number","null"],"example":120},"family_suitability_score_100":{"type":"number","example":45},"primary_persona_tag":{"type":"string","example":"Metro High-Flyer"}}}},"scale_directions":{"type":"object","description":"Explicit documentation of score polarities and caveats for calling agents","properties":{"affluence_score_100":{"type":"string","example":"Higher is more affluent (0-100 scale, calibrated against national deciles)"},"crime_safety_decile":{"type":"string","example":"Higher is safer (Decile 10 = lowest recorded crime per capita; Decile 1 = highest recorded crime)"},"price_per_sqm_gbp":{"type":"string","example":"Lower represents lower nominal cost per unit area (entry barrier), though not inherently superior quality"},"median_down_mbps":{"type":"string","example":"Higher indicates faster fixed-line broadband download throughput"},"family_suitability_score_100":{"type":"string","example":"Higher indicates greater family orientation (house composition, greenspace, school density)"}}},"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"}}}},"text/markdown":{"schema":{"type":"string","description":"GitHub Flavored Markdown export"}},"text/csv":{"schema":{"type":"string","description":"CSV data export"}}}},"402":{"description":"Payment Required: Settle via x402 protocol (USDC on Base Mainnet, eip155:8453)."}}},"get":{"tags":["Demographics","Great Britain Property","Geospatial","Census"],"summary":"Compare Great Britain Postcodes (Query Parameter)","description":"Compares 2 to 5 comma-separated Great Britain postcodes side-by-side via GET query parameter.","operationId":"compare_gb_postcodes_get","x-x402-price":"$0.01","x-x402-network":"eip155:8453","x-x402-asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","x-x402-payTo":"0x8ab7568ac097523e81a94644235fcf19a2b85670","parameters":[{"name":"postcodes","in":"query","required":true,"description":"Comma-separated list of 2 to 5 Great Britain postcodes to compare (e.g. SW1A 1AA,BB7 3BB)","schema":{"type":"string","example":"SW1A 1AA,BB7 3BB"}},{"name":"format","in":"query","required":false,"description":"Export format: json (default), csv, or markdown/md (GitHub Flavored Markdown)","schema":{"type":"string","enum":["json","csv","markdown","md"],"default":"json"}}],"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","properties":{"highest_affluence":{"type":"object"},"lowest_crime":{"type":"object"},"best_value_per_sqm":{"type":"object"},"fastest_broadband":{"type":"object"},"highest_family_score":{"type":"object"},"metrics_summary":{"type":"array","description":"Raw underlying comparison metrics returned side-by-side for objective multi-criteria agent evaluation"},"scale_directions":{"type":"object","description":"Explicit documentation of score polarities and caveats for calling agents"},"synthesis_notes":{"type":"string"}}},"_attribution":{"type":"string"}}}},"text/markdown":{"schema":{"type":"string","description":"GitHub Flavored Markdown export"}},"text/csv":{"schema":{"type":"string","description":"CSV data export"}}}},"402":{"description":"Payment Required: Settle via x402 protocol (USDC on Base Mainnet, eip155:8453)."}}}},"/api/v1/batch":{"post":{"tags":["Demographics","Great Britain Property","Geospatial","Census"],"summary":"Batch Enrich Great Britain Postcodes","description":"High-throughput bulk enrichment of up to 50 Great Britain postcodes with cohort aggregation metrics (average affluence, dominant persona, and top property values across England, Scotland, Wales). Supports ?view= and ?format=markdown/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/brief (~80 tokens), property (valuations & EPC), demographics (Census & IMD deciles), education, healthcare, or infrastructure","schema":{"type":"string","enum":["full","summary","property","demographics","education","schools","healthcare","health","services","infrastructure"],"default":"full"}},{"name":"format","in":"query","required":false,"description":"Export format: json (default), flat, csv, or markdown/md (GitHub Flavored Markdown)","schema":{"type":"string","enum":["json","flat","csv","markdown","md"],"default":"json"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["postcodes"],"properties":{"postcodes":{"type":"array","description":"List of 1 to 50 Great Britain 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},"average_affluence_score":{"type":["integer","null"],"example":78},"average_house_price_gbp":{"type":["integer","null"],"example":545000},"dominant_persona":{"type":["string","null"],"example":"Affluent Suburban"},"top_3_highest_value_postcodes":{"type":"array","items":{"type":"object","properties":{"postcode":{"type":"string","example":"SW1A 1AA"},"median_house_price_gbp":{"type":["integer","null"],"example":1250000},"affluence_score_100":{"type":["integer","null"],"example":94}}}}}},"_attribution":{"type":"string"}}}},"text/markdown":{"schema":{"type":"string","description":"GitHub Flavored Markdown export"}},"text/csv":{"schema":{"type":"string","description":"CSV data export"}}}},"402":{"description":"Payment Required: Settle via x402 protocol (USDC on Base Mainnet, eip155:8453)."}}},"get":{"tags":["Demographics","Great Britain Property","Geospatial","Census"],"summary":"Batch Enrich Great Britain Postcodes (Query Parameter)","description":"Bulk enrichment of 1 to 50 comma-separated Great Britain postcodes via GET query parameter.","operationId":"enrich_postcodes_batch_get","x-x402-price":"$0.05","x-x402-network":"eip155:8453","x-x402-asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","x-x402-payTo":"0x8ab7568ac097523e81a94644235fcf19a2b85670","parameters":[{"name":"postcodes","in":"query","required":true,"description":"Comma-separated list of 1 to 50 Great Britain postcodes to enrich (e.g. SW1A 1AA,BB7 3BB,EH1 1YZ)","schema":{"type":"string","example":"SW1A 1AA,BB7 3BB,EH1 1YZ"}},{"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, csv, or markdown/md (GitHub Flavored Markdown)","schema":{"type":"string","enum":["json","flat","csv","markdown","md"],"default":"json"}}],"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"}}}},"text/markdown":{"schema":{"type":"string","description":"GitHub Flavored Markdown export"}},"text/csv":{"schema":{"type":"string","description":"CSV data export"}}}},"402":{"description":"Payment Required: Settle via x402 protocol (USDC on Base Mainnet, eip155:8453)."}}}},"/api/v1/outcode/{outcode}":{"get":{"tags":["Demographics","Great Britain Property","Geospatial","Census"],"summary":"Get Great Britain Outward Code District Summary","description":"Aggregates all postcodes within a Great Britain outward district (e.g. BB7, SW1A, EH1, CF10) to return district-wide median house prices, deprivation ranges, and top personas. Also accessible via query parameter at GET /api/v1/outcode?outcode=BB7.","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":"Great Britain outward postal district code (e.g. BB7, SW1A, EH1, CF10)","schema":{"type":"string","example":"BB7"}},{"name":"view","in":"query","required":false,"description":"Slice target view: full (complete dataset, default), summary, property, demographics, education, healthcare, or services","schema":{"type":"string","enum":["full","summary","property","demographics","education","schools","healthcare","health","services","infrastructure"],"default":"full"}},{"name":"exclude","in":"query","required":false,"description":"Comma-separated domains to exclude from payload: schools, healthcare (e.g. exclude=schools,healthcare)","schema":{"type":"string","example":"schools,healthcare"}},{"name":"format","in":"query","required":false,"description":"Export format: json (default), flat, csv, or markdown/md (GitHub Flavored Markdown)","schema":{"type":"string","enum":["json","flat","csv","markdown","md"],"default":"json"}}],"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"}}}},"text/markdown":{"schema":{"type":"string","description":"GitHub Flavored Markdown export"}},"text/csv":{"schema":{"type":"string","description":"CSV data export"}}}},"402":{"description":"Payment Required: Settle via x402 protocol (USDC on Base Mainnet, eip155:8453)."}}}},"/api/v1/outcode":{"get":{"tags":["Demographics","Great Britain Property","Geospatial","Census"],"summary":"Get Great Britain Outward Code District Summary (Query Parameter)","description":"Query-parameter alternative to /api/v1/outcode/{outcode}. Aggregates all postcodes within a postal outward district (e.g. BB7, SW1A, EH1, CF10).","operationId":"get_outcode_district_summary_query","x-x402-price":"$0.005","x-x402-network":"eip155:8453","x-x402-asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","x-x402-payTo":"0x8ab7568ac097523e81a94644235fcf19a2b85670","parameters":[{"name":"outcode","in":"query","required":true,"description":"Great Britain outward postal district code (e.g. BB7, SW1A, EH1, CF10)","schema":{"type":"string","example":"BB7"}},{"name":"view","in":"query","required":false,"description":"Slice target view: full (complete dataset, default), summary, property, demographics, education, healthcare, or services","schema":{"type":"string","enum":["full","summary","property","demographics","education","schools","healthcare","health","services","infrastructure"],"default":"full"}},{"name":"exclude","in":"query","required":false,"description":"Comma-separated domains to exclude from payload: schools, healthcare (e.g. exclude=schools,healthcare)","schema":{"type":"string","example":"schools,healthcare"}},{"name":"format","in":"query","required":false,"description":"Export format: json (default), flat, csv, or markdown/md (GitHub Flavored Markdown)","schema":{"type":"string","enum":["json","flat","csv","markdown","md"],"default":"json"}}],"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"}}}},"text/markdown":{"schema":{"type":"string","description":"GitHub Flavored Markdown export"}},"text/csv":{"schema":{"type":"string","description":"CSV data export"}}}},"402":{"description":"Payment Required: Settle via x402 protocol (USDC on Base Mainnet, eip155:8453)."}}}},"/api/v1/attribution":{"get":{"tags":["Attribution","Legal","Licensing","Open Data"],"summary":"Get Statutory Data Provenance & Attribution Register","description":"Returns the full machine-readable provenance, Crown copyright notices, Royal Mail database right statements, and Open Government Licence v3.0 links for all 8 underlying public sector datasets. Always free with zero charge.","operationId":"get_data_attribution","responses":{"200":{"description":"Statutory attribution register returned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"licence":{"type":"string"},"licence_url":{"type":"string"},"territorial_scope":{"type":"string"},"attribution_summary":{"type":"string"},"sources":{"type":"array","items":{"type":"object","properties":{"dataset":{"type":"string"},"provider":{"type":"string"},"coverage":{"type":"string"},"licence":{"type":"string"},"licence_url":{"type":"string"},"mandatory_statement":{"type":"string"}}}}}}}}}}}},"/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":{}}}}}}}}}}}},"/.well-known/x402.json":{"get":{"tags":["Discovery & Agent Protocols"],"summary":"x402 Protocol Machine Discovery Manifest","description":"Machine-readable JSON manifest exposing x402 payment requirements, Base Mainnet network configuration, USDC asset address, and endpoint rates.","operationId":"get_x402_discovery_manifest","responses":{"200":{"description":"x402 v2 protocol discovery manifest","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/agent-card.json":{"get":{"tags":["Discovery & Agent Protocols"],"summary":"A2A Agent Card Standard Discovery Manifest","description":"Canonical Agent-to-Agent (A2A v1.0) digital card describing agent identity, provider, supported interfaces (REST & MCP), x402 payment requirements, and skill catalogue.","operationId":"get_a2a_agent_card","responses":{"200":{"description":"A2A v1.0 Agent Card JSON specification","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/agent.json":{"get":{"tags":["Discovery & Agent Protocols"],"summary":"A2A Agent Card Legacy Alias","description":"Legacy draft alias for /.well-known/agent-card.json.","operationId":"get_a2a_agent_card_legacy","responses":{"200":{"description":"A2A v1.0 Agent Card JSON specification","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/.well-known/mcp.json":{"get":{"tags":["Discovery & Agent Protocols"],"summary":"Model Context Protocol (MCP) Server Discovery Manifest","description":"Standardized discovery manifest detailing remote MCP server endpoint, Streamable HTTP transport, x402 payment requirements, and registered tools catalogue.","operationId":"get_mcp_discovery_manifest","responses":{"200":{"description":"Model Context Protocol discovery manifest","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}