# UKDataAPI — Full Documentation

> Complete reference for all 22 UK government data intelligence endpoints. Each endpoint aggregates 3-12 upstream UK government APIs into a single enriched response with proprietary scoring algorithms.

For the short version: https://www.ukdatapi.com/llms.txt

## Authentication

All v1 endpoints require an API key passed via the Authorization header:

    Authorization: Bearer ukd_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

API keys are available at https://www.ukdatapi.com after registration.

x402 endpoints accept payment via the x402 protocol (USDC on Base Mainnet) instead of API keys. Include the X-PAYMENT header with a valid x402 payment proof.

Base URL: https://www.ukdatapi.com/api/v1
x402 Base URL: https://www.ukdatapi.com/api/x402

## Response Format

All endpoints return JSON with a consistent envelope:

    {
      "_meta": {
        "sources": ["companies_house", "fca", ...],
        "data_freshness": { "companies_house": "2025-04-22T10:00:00Z", ... },
        "credits_used": 15
      },
      "data": { ... }
    }

Error responses use standard HTTP codes with:

    {
      "error": "not_found",
      "suggestion": "Did you mean SW1A 1AA?"
    }

## Depth Parameter

Most endpoints support a `depth` query parameter controlling response detail and credit cost:

- `summary` — Key fields only, lowest credit cost
- `standard` — Default, balanced detail (used when depth is omitted)
- `full` — All available fields, highest credit cost

## Endpoints

### 1. Entity Intelligence

    GET /api/v1/entity/{identifier}
    GET /api/x402/entity/{identifier}

Retrieve comprehensive company information including officers, financials, regulatory status, and risk signals.

**Parameters:**
- `identifier` (path, required) — Companies House number (e.g., "00445790"), charity number, or company name
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"

**Credit Cost:**
- summary: 2 credits ($0.002 x402)
- standard: 8 credits ($0.015 x402)
- full: 16 credits ($0.030 x402)

**Response Fields:**
- `company` — Name, number, status, type, incorporation date, registered address, SIC codes
- `officers` — Current and resigned directors/secretaries with appointment dates
- `financials` — Latest accounts: total assets, net assets, turnover, profit/loss, cash, employees
- `filing_history` — Recent Companies House filings
- `charges` — Outstanding and satisfied charges/mortgages
- `regulatory` — FCA register status, permissions, regulated activities
- `gazette` — London/Edinburgh/Belfast Gazette notices (insolvency, winding up, striking off)
- `charity` — Charity Commission data if applicable: objectives, income, spending, trustees
- `contracts` — Government contracts won via Contracts Finder
- `distress_score` — Corporate Distress Score (0-100, proprietary)

**Corporate Distress Score (0-100):**
Proprietary composite score indicating financial health risk. Factors weighted:
- Overdue accounts (25%) — Days past due for annual accounts filing
- Net assets trend (20%) — Year-on-year change in net assets
- Cash position (15%) — Cash relative to total assets
- Officer churn (15%) — Director appointment/resignation frequency
- Charges (10%) — Outstanding charge count and recency
- Gazette notices (10%) — Insolvency-related gazette entries
- Filing gaps (5%) — Irregular filing patterns

Score ranges: 0-25 = Low risk, 26-50 = Moderate, 51-75 = Elevated, 76-100 = High risk

**Upstream Sources:** Companies House API, FCA Financial Services Register, Charity Commission API, The Gazette, Contracts Finder

---

### 2. Location Intelligence

    GET /api/v1/location/{postcode}
    GET /api/x402/location/{postcode}

Area profiling combining demographics, crime, flood risk, food hygiene, labour market, health indicators, broadband, and air quality for any UK postcode.

**Parameters:**
- `postcode` (path, required) — UK postcode (e.g., "SW1A 1AA" or "SW1A1AA")
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"
- `radius_m` (query, optional) — Search radius in metres. Default: 1000

**Credit Cost:**
- summary: 2 credits ($0.002 x402)
- standard: 10 credits ($0.020 x402)
- full: 20 credits ($0.035 x402)

**Response Fields:**
- `postcode` — Validated postcode details, coordinates, ward, constituency, LSOA
- `demographics` — Census 2021 data: population, age distribution, ethnicity, households, tenure
- `crime` — Police.uk crime data: recent crimes by category, street-level breakdown
- `flood_risk` — EA flood risk zones, flood warnings, historical flooding
- `food_hygiene` — FSA ratings for nearby food establishments
- `labour_market` — ONS/Nomis: employment rate, earnings, claimant count, economic activity
- `health` — OHID Fingertips: life expectancy, obesity, smoking, deprivation index
- `broadband` — Ofcom: average download/upload speed, coverage by technology
- `air_quality` — Defra: NO2, PM2.5, PM10 levels, AQMA status

**Upstream Sources:** ONS Postcode Directory, Census 2021, Police.uk, Environment Agency, FSA, ONS Nomis, OHID Fingertips, Ofcom, Defra

---

### 3. Property Intelligence

    GET /api/v1/property/{postcode}
    GET /api/x402/property/{postcode}

Property due diligence combining price history, energy performance, planning constraints, environmental risk, and crime data.

**Parameters:**
- `postcode` (path, required) — UK postcode
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"

**Credit Cost:**
- summary: 5 credits ($0.010 x402)
- standard: 15 credits ($0.025 x402)
- full: 30 credits ($0.050 x402)

**Response Fields:**
- `price_history` — Land Registry: recent transactions, price paid, property type, tenure
- `price_statistics` — Median, mean, min, max prices by property type for the postcode
- `epc` — Energy Performance Certificates: current rating, potential, wall/roof/heating details
- `planning` — Local planning constraints and nearby planning applications
- `environmental_risk_score` — Composite Environmental Risk Score (0-100)
- `flood_risk` — EA flood zone classification, flood warnings
- `crime` — Nearby crime statistics from Police.uk
- `listed_buildings` — Historic England listed buildings nearby

**Environmental Risk Score (0-100):**
Composite score for property due diligence:
- Flood risk (35%) — EA flood zone, surface water risk, historical flooding
- Ground stability (25%) — BGS shrink-swell clay, landslide, ground dissolution
- Radon (20%) — BGS/PHE radon affected area classification
- Water quality (10%) — EA water body status (good/moderate/poor)
- Air quality (10%) — Defra AQMA proximity and pollutant levels

Score ranges: 0-25 = Low risk, 26-50 = Moderate, 51-75 = Elevated, 76-100 = High risk

**Upstream Sources:** HM Land Registry Price Paid, EPC Register, Planning Data (DLUHC), Environment Agency, BGS Geohazards, Police.uk, Historic England

---

### 4. Due Diligence Report

    GET /api/v1/report/entity/{identifier}
    GET /api/x402/report/entity/{identifier}

Synthesized company assessment producing an actionable verdict with structured red/green flags. Designed to replace traditional credit reports.

**Parameters:**
- `identifier` (path, required) — Companies House number, charity number, or company name

**Credit Cost:** 25 credits ($0.050 x402)

**Response Fields:**
- `verdict` — "PROCEED" | "CAUTION" | "DO_NOT_ENGAGE"
- `confidence` — Confidence level (0-100) in the verdict
- `distress_score` — Corporate Distress Score (0-100)
- `red_flags` — Array of risk indicators with severity and source
- `green_flags` — Array of positive indicators with source
- `governance` — Director assessment, board stability, experience diversity
- `financial_health` — Asset trend, profitability, cash adequacy
- `regulatory_status` — FCA, Charity Commission, gazette notices summary
- `recommendation` — Actionable text recommendation
- `data_completeness` — Percentage of data sources successfully queried

**Verdict Logic:**
- PROCEED: Distress score < 30, no critical red flags, adequate data completeness
- CAUTION: Distress score 30-65, or minor red flags present, or data gaps
- DO_NOT_ENGAGE: Distress score > 65, critical red flags (active gazette notices, dissolved, overdue accounts > 12 months)

**Upstream Sources:** All Entity Intelligence sources plus additional gazette cross-referencing

---

### 5. Environmental Risk Intelligence

    GET /api/v1/environment/{postcode}
    GET /api/x402/environment/{postcode}

Multi-factor environmental risk assessment combining flood, geology, radon, water quality, and carbon intensity data.

**Parameters:**
- `postcode` (path, required) — UK postcode
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"

**Credit Cost:**
- summary: 4 credits ($0.008 x402)
- standard: 12 credits ($0.020 x402)
- full: 24 credits ($0.040 x402)

**Response Fields:**
- `environmental_risk_score` — Composite score (0-100) with breakdown
- `flood` — EA flood risk assessment: river, surface water, coastal, groundwater
- `geology` — BGS: bedrock, superficial deposits, shrink-swell clay, landslide susceptibility
- `radon` — Radon affected area band and estimated percentage of homes above action level
- `water_quality` — EA Water Framework Directive: waterbody status, chemical/ecological classification
- `carbon_intensity` — National Grid ESO: current grid carbon intensity, generation mix
- `air_quality` — Defra: pollutant levels, AQMA status

**Upstream Sources:** Environment Agency Flood Risk, BGS GeoIndex, BGS Radon, EA Water Quality, National Grid ESO Carbon Intensity, Defra AQMA

---

### 6. Planning Intelligence

    GET /api/v1/planning/{postcode}
    GET /api/x402/planning/{postcode}

Planning data aggregation combining planning applications, site constraints, council performance, environmental designations, flood risk, and mining risk for any UK postcode. Includes proprietary Planning Development Score.

**Parameters:**
- `postcode` (path, required) — UK postcode (e.g., "SW1A 1AA" or "SW1A1AA")
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"

**Credit Cost:**
- summary: 4 credits ($0.008 x402)
- standard: 12 credits ($0.020 x402)
- full: 24 credits ($0.040 x402)

**Response Fields:**
- `development_score` — Planning Development Score (0-100) with rating, confidence, and 7 weighted factors
- `constraints` — Conservation area (boolean + name), listed buildings (count + names with grade), Green Belt, Article 4 directions (count + names), Tree Preservation Orders, brownfield sites (full depth), constraint level classification
- `applications` — Recent planning applications with reference, description, type, status, decision date. Includes total_found, approval_rate, refusal_rate, pending_count, withdrawn_count
- `designations` — SSSI, AONB, National Park (boolean + name for each), designation count
- `flood_risk` — Risk level (low/warning/severe), active warnings count
- `council_performance` — Local authority approval rate %, major/minor on-time %, determination period
- `council_portal_url` — Direct URL to the council's planning portal
- `mining_risk` — Coalfield membership, risk level, mine entries nearby (full depth only)

**Planning Development Score (0-100):**
Proprietary composite score rating development viability. Factors weighted:
- Constraint density (25%) — Conservation area, Green Belt, listed buildings, Article 4, TPOs
- Development momentum (20%) — Recent application approval ratio
- Environmental designations (15%) — SSSI, AONB, National Park impact
- Council efficiency (15%) — Approval rate and major application on-time percentage
- Brownfield opportunity (10%) — Nearby brownfield site availability
- Flood risk (10%) — EA flood risk level
- Mining risk (5%) — Coal Authority risk assessment

Score ranges: 0-24 = HIGHLY_CONSTRAINED, 25-39 = CONSTRAINED, 40-59 = MODERATE, 60-74 = FAVOURABLE, 75-100 = HIGHLY_FAVOURABLE

**Upstream Sources:** Planning Data Platform (DLUHC), Natural England (ArcGIS), MHCLG Open Data Communities (SPARQL), Environment Agency Flood Monitoring, Coal Authority/BGS

---

### 7. Market Sizing Intelligence

    GET /api/v1/market/{postcode}
    GET /api/x402/market/{postcode}

Market opportunity analysis for any UK area, combining labour market data, property market context, competitor density, and demographic purchasing power.

**Parameters:**
- `postcode` (path, required) — UK postcode
- `sector` (query, optional) — SIC code or sector keyword to filter competitor analysis
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"

**Credit Cost:**
- summary: 5 credits ($0.010 x402)
- standard: 15 credits ($0.025 x402)
- full: 30 credits ($0.050 x402)

**Response Fields:**
- `market_opportunity_score` — Composite opportunity score (0-100)
- `labour_market` — ONS Nomis: employment rate, median earnings, claimant count, economic activity rate
- `property_market` — Land Registry: price trends, transaction volumes, property type mix
- `demographics` — Census 2021: population, age profile, household composition
- `competitor_density` — Companies House: active companies in sector within radius
- `tam_estimate` — Total Addressable Market estimate based on demographics and sector
- `deprivation` — IMD rank and decile for the area

**Upstream Sources:** ONS Census 2021, ONS Nomis, HM Land Registry, Companies House, IMD

---

### 8. Trade & Customs Intelligence

    GET /api/v1/trade/{commodity}
    GET /api/x402/trade/{commodity}

UK import duty rates, preferential rates, quotas, and trade measures for any commodity.

**Parameters:**
- `commodity` (path, required) — HS commodity code (e.g., "0901" for coffee) or keyword description

**Credit Cost:** 10 credits ($0.020 x402)

**Response Fields:**
- `commodity` — Resolved commodity code, description, hierarchy
- `duty_rates` — MFN (Most Favoured Nation) duty rate, measure type
- `preferential_rates` — Reduced rates by country/trade agreement
- `quotas` — Applicable tariff-rate quotas, balances, fill rates
- `trade_remedies` — Anti-dumping duties, countervailing measures
- `rules_of_origin` — Applicable rules for preferential treatment
- `supplementary_units` — Required supplementary unit of measure

**Upstream Sources:** HMRC Trade Tariff API

---

### 9. Education Intelligence

    GET /api/v1/education/{postcode}
    GET /api/x402/education/{postcode}

Schools near any UK postcode with Ofsted ratings, type, phase, pupil numbers, and catchment analysis.

**Parameters:**
- `postcode` (path, required) — UK postcode
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"
- `phase` (query, optional) — Filter by phase: "primary", "secondary", "16 plus", "all phases"

**Credit Cost:** 8 credits ($0.020 x402)

**Response Fields:**
- `schools` — Array of nearby schools with:
  - Name, URN, type (academy, maintained, free school, independent)
  - Phase (primary, secondary, 16+, all-through)
  - Ofsted rating (Outstanding, Good, Requires Improvement, Inadequate)
  - Last inspection date
  - Pupil numbers, capacity
  - Distance from postcode
  - Religious character, gender
- `statistics` — Aggregated: count by Ofsted rating, count by phase, average distance
- `nearest_outstanding` — Closest Outstanding-rated school by phase

**Upstream Sources:** DfE Get Information About Schools (GIAS), Ofsted Data

---

### 10. Transport & Connectivity Intelligence

    GET /api/v1/transport/{postcode}
    GET /api/x402/transport/{postcode}

Transport connectivity assessment including nearest stations, bus stops, traffic flow, and a composite connectivity score.

**Parameters:**
- `postcode` (path, required) — UK postcode
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"

**Credit Cost:** 8 credits ($0.020 x402)

**Response Fields:**
- `connectivity_score` — Composite transport connectivity score (0-100)
- `rail_stations` — Nearest railway stations with distance, lines served, frequency
- `bus_stops` — Nearest bus stops with routes served
- `traffic` — DfT traffic counts: annual average daily flow (AADF) on nearby roads
- `accessibility` — Journey time statistics to key services (employment, education, health)

**Upstream Sources:** DfT NaPTAN (National Public Transport Access Nodes), DfT Traffic Counts, DfT Journey Time Statistics

---

### 11. Vehicle Intelligence

    GET /api/v1/vehicle/{registration}
    GET /api/x402/vehicle/{registration}

Full MOT history for any UK vehicle with mileage tracking, advisory trends, and a Vehicle Health Score.

**Parameters:**
- `registration` (path, required) — UK vehicle registration number (e.g., "AB12CDE")

**Credit Cost:** 6 credits ($0.015 x402)

**Response Fields:**
- `vehicle` — Make, model, colour, fuel type, registration date, engine size
- `mot_history` — Array of MOT tests with:
  - Test date, result (pass/fail), mileage, expiry date
  - Defects: type (dangerous, major, minor, advisory), text, category
- `mileage_trend` — Calculated annual mileage, trend direction, anomaly detection
- `vehicle_health_score` — Vehicle Health Score (0-100)
- `advisory_trends` — Recurring advisories grouped by category (brakes, tyres, suspension, etc.)

**Vehicle Health Score (0-100):**
- MOT pass rate (30%) — Historical pass/fail ratio
- Advisory frequency (25%) — Number of advisories per test
- Mileage consistency (20%) — Regularity of mileage increments (flags clocking)
- Defect severity (15%) — Weighted count of dangerous/major/minor defects
- Vehicle age factor (10%) — Age-adjusted expectations

Score ranges: 0-25 = Poor, 26-50 = Fair, 51-75 = Good, 76-100 = Excellent

**Upstream Sources:** DVSA MOT History API

---

### 12. Healthcare Intelligence

    GET /api/v1/health/{postcode}
    GET /api/x402/health/{postcode}

Healthcare landscape assessment combining public health indicators, CQC-rated care providers, and GP prescribing patterns.

**Parameters:**
- `postcode` (path, required) — UK postcode
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"

**Credit Cost:** 12 credits ($0.030 x402)

**Response Fields:**
- `health_indicators` — OHID Fingertips: life expectancy, infant mortality, obesity prevalence, smoking prevalence, deprivation score, physical activity levels
- `care_providers` — CQC-rated providers nearby:
  - Name, type (GP, hospital, care home, dentist)
  - Overall CQC rating (Outstanding, Good, Requires Improvement, Inadequate)
  - Domain ratings: safe, effective, caring, responsive, well-led
  - Last inspection date
  - Distance from postcode
- `prescribing` — OpenPrescribing: top prescribed items by BNF category, spending patterns, practice-level data
- `nhs_services` — Nearby NHS services: GPs, pharmacies, hospitals, urgent care

**Upstream Sources:** OHID Fingertips API, CQC API, OpenPrescribing API, NHS Choices/ODS

---

### 13. Energy & ESG Intelligence

    GET /api/v1/energy/{postcode}
    GET /api/x402/energy/{postcode}

Grid carbon intensity, generation mix, local energy efficiency data, and a composite ESG Score for any UK postcode.

**Parameters:**
- `postcode` (path, required) — UK postcode
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"

**Credit Cost:** 12 credits ($0.025 x402)

**Response Fields:**
- `esg_score` — Composite ESG Score (0-100)
- `carbon_intensity` — National Grid ESO: current and forecast carbon intensity (gCO2/kWh)
- `generation_mix` — Current electricity generation mix by fuel type (gas, wind, solar, nuclear, etc.)
- `wholesale_prices` — Elexon: current wholesale electricity price
- `local_epc` — Aggregated EPC data for the postcode area: average rating, efficiency distribution
- `renewable_capacity` — Nearby renewable energy installations (REPD)

**ESG Score (0-100):**
- Grid carbon intensity (30%) — Regional carbon intensity vs national average
- Local EPC efficiency (25%) — Average energy rating in the area
- Renewable capacity (20%) — Nearby renewable generation capacity
- Air quality (15%) — Defra pollutant levels
- Green space (10%) — OS/Census green space accessibility

Score ranges: 0-25 = Poor, 26-50 = Below Average, 51-75 = Good, 76-100 = Excellent

**Upstream Sources:** National Grid ESO Carbon Intensity API, Elexon BMRS, EPC Register, REPD, Defra

---

### 14. Legal & Policy Intelligence

    GET /api/v1/legal/{query}
    GET /api/x402/legal/{query}

Search UK legislation and pending Parliamentary bills relevant to any topic, sector, or keyword.

**Parameters:**
- `query` (path, required) — Search term (e.g., "data protection", "employment", "building safety")

**Credit Cost:** 10 credits ($0.025 x402)

**Response Fields:**
- `legislation` — Matching UK Acts and Statutory Instruments:
  - Title, year, type (primary/secondary)
  - Status (in force, repealed, amended)
  - URL to legislation.gov.uk
  - Relevant sections/provisions
- `bills` — Current Parliamentary bills:
  - Title, summary, stage (first reading, committee, royal assent)
  - Sponsors, last update date
  - URL to Parliament.uk
- `relevance_scores` — How closely each result matches the query

**Upstream Sources:** legislation.gov.uk API, UK Parliament Bills API

---

### 15. Government Tenders & Procurement

    GET /api/v1/tenders
    GET /api/x402/tenders

Open government procurement opportunities and recently awarded contracts.

**Parameters:**
- `sector` (query, optional) — Filter by sector keyword (e.g., "technology", "construction")
- `region` (query, optional) — Filter by region (e.g., "London", "North West")

**Credit Cost:** 10 credits ($0.020 x402)

**Response Fields:**
- `open_tenders` — Currently open opportunities:
  - Title, description, buyer organisation
  - Value range (min/max), currency
  - Deadline, publication date
  - CPV codes, procedure type
  - URL to original notice
- `awarded_contracts` — Recently awarded contracts:
  - Title, awarded supplier, value
  - Award date, buyer organisation
- `buyer_profiles` — Active buying organisations with tender counts
- `statistics` — Average contract value, total open opportunities, sector breakdown

**Upstream Sources:** Contracts Finder API, Find a Tender Service

---

### 16. Water Quality Intelligence

    GET /api/v1/water/{postcode}
    GET /api/x402/water/{postcode}

Water quality assessment combining EA Water Framework Directive data, drinking water quality, and water company performance for any UK postcode.

**Parameters:**
- `postcode` (path, required) — UK postcode
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"

**Credit Cost:**
- summary: 4 credits ($0.008 x402)
- standard: 12 credits ($0.020 x402)
- full: 24 credits ($0.040 x402)

**Response Fields:**
- `water_quality_score` — Water Quality Score (0-100) with factor breakdown
- `waterbody_status` — EA Water Framework Directive classification: ecological and chemical status
- `drinking_water` — DWI compliance data: mean zonal compliance, failures, risk assessments
- `water_company` — Responsible water company, performance metrics, pollution incidents
- `bathing_water` — Nearby bathing water quality classifications (if applicable)
- `pollution_incidents` — Recent EA-recorded pollution incidents in the area

**Water Quality Score (0-100):**
Higher scores = better water quality. Factors: waterbody ecological status (30%), drinking water compliance (25%), pollution incidents (20%), water company performance (15%), bathing water quality (10%).

**Upstream Sources:** EA Water Framework Directive, Drinking Water Inspectorate, EA Pollution Incidents, Water Company Performance Data

---

### 17. Digital Connectivity Intelligence

    GET /api/v1/connectivity/{postcode}
    GET /api/x402/connectivity/{postcode}

Broadband and mobile coverage assessment with a Digital Readiness Score for any UK postcode.

**Parameters:**
- `postcode` (path, required) — UK postcode
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"

**Credit Cost:**
- summary: 4 credits ($0.008 x402)
- standard: 10 credits ($0.020 x402)
- full: 20 credits ($0.035 x402)

**Response Fields:**
- `digital_readiness_score` — Digital Readiness Score (0-100) with factor breakdown
- `broadband` — Ofcom Connected Nations: average download/upload speeds, superfast/ultrafast availability, ISP coverage
- `mobile` — 4G and 5G coverage by operator (EE, Three, O2, Vodafone), indoor/outdoor
- `full_fibre` — FTTP availability and planned rollout
- `digital_exclusion_risk` — Factors indicating digital exclusion: age demographics, deprivation, infrastructure gaps

**Digital Readiness Score (0-100):**
Higher scores = better connectivity. Factors: broadband speed (30%), full fibre availability (25%), mobile 4G/5G coverage (20%), ISP competition (15%), digital exclusion risk (10%).

**Upstream Sources:** Ofcom Connected Nations, Think Broadband, Census 2021 Digital Data

---

### 18. Political Intelligence

    GET /api/v1/political/{postcode}
    GET /api/x402/political/{postcode}

Political representation and engagement data for any UK postcode, including MP details, party information, petitions, and voting patterns.

**Parameters:**
- `postcode` (path, required) — UK postcode
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"

**Credit Cost:**
- summary: 2 credits ($0.020 x402)
- standard: 8 credits ($0.020 x402)
- full: 16 credits ($0.020 x402)

**Response Fields:**
- `political_engagement_index` — Political Engagement Index with factor breakdown
- `constituency` — Parliamentary constituency name, ONS code
- `mp` — Current MP: name, party, contact details, voting record summary
- `petitions` — Active petitions relevant to the constituency with signature counts
- `election_results` — Last general election results: candidates, votes, turnout
- `council` — Local authority, political control, councillor details

**Political Engagement Index:**
Composite measure of political activity and engagement in the area. Based on voter turnout, petition activity, MP engagement, and local election participation.

**Upstream Sources:** UK Parliament API, Electoral Commission, petitions.parliament.uk, Democracy Club

---

### 19. Director Network Intelligence

    GET /api/v1/director/{name_or_id}
    GET /api/x402/director/{name_or_id}

Director network analysis revealing appointment history, co-directorships, disqualifications, and a Director Risk Score.

**Parameters:**
- `name_or_id` (path, required) — Director name or Companies House person ID
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"

**Credit Cost:**
- summary: 5 credits ($0.010 x402)
- standard: 15 credits ($0.030 x402)
- full: 30 credits ($0.060 x402)

**Response Fields:**
- `director_risk_score` — Director Risk Score (0-100) with factor breakdown
- `person` — Name, date of birth (month/year), nationality, country of residence
- `appointments` — All current and past directorships with company names, dates, roles
- `co_directors` — Network of individuals who share directorships (co-director graph)
- `disqualifications` — Any disqualification orders from the Insolvency Service
- `dissolved_companies` — Count and details of dissolved companies previously directed
- `psc_declarations` — Persons of Significant Control declarations

**Director Risk Score (0-100):**
Higher scores = higher risk. Factors: dissolved company count (25%), disqualification history (25%), appointment churn rate (20%), company distress correlation (15%), co-director risk network (15%).

**Upstream Sources:** Companies House Officers API, Companies House Disqualified Directors Register, Insolvency Service

---

### 20. Funding & Grants Intelligence

    GET /api/v1/funding/{query}
    GET /api/x402/funding/{query}

Grants, research funding opportunities, and public contracts matching a query, with a Funding Opportunity Score.

**Parameters:**
- `query` (path, required) — Search term describing the funding area (e.g., "clean energy", "AI research", "social housing")
- `type` (query, optional) — Filter: "grant", "contract", "research", "all". Default: "all"

**Credit Cost:**
- summary: 4 credits ($0.025 x402)
- standard: 10 credits ($0.025 x402)
- full: 20 credits ($0.025 x402)

**Response Fields:**
- `funding_opportunity_score` — Funding Opportunity Score (0-100) indicating match quality
- `grants` — Matching grant opportunities: funder, value, deadline, eligibility
- `research_funding` — UKRI and Innovate UK open calls matching the query
- `contracts` — Relevant public sector contracts from Contracts Finder
- `awarded_recently` — Recently awarded funding in the same area (benchmark data)
- `statistics` — Total available funding, average award size, success rates

**Funding Opportunity Score (0-100):**
Higher scores = stronger opportunity match. Factors: query relevance (30%), funding value (25%), deadline proximity (20%), funder track record (15%), competition level (10%).

**Upstream Sources:** UKRI Gateway to Research, Contracts Finder, Find a Tender, EU Horizon (UK-eligible)

---

### 21. Innovation & IP Intelligence

    GET /api/v1/innovation/{identifier}
    GET /api/x402/innovation/{identifier}

Patent portfolio, research grants, and innovation activity for a company or topic, with an Innovation Score.

**Parameters:**
- `identifier` (path, required) — Company name, Companies House number, or topic keyword
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"

**Credit Cost:**
- summary: 4 credits ($0.008 x402)
- standard: 12 credits ($0.025 x402)
- full: 24 credits ($0.050 x402)

**Response Fields:**
- `innovation_score` — Innovation Score (0-100) with factor breakdown
- `patents` — UK IPO patent applications and grants: titles, filing dates, status, classifications
- `trademarks` — Registered and pending UK trademarks
- `research_grants` — UKRI-funded research projects linked to the entity
- `ktp_partnerships` — Knowledge Transfer Partnerships involving the entity
- `r_and_d_tax_credits` — Sector benchmarks for R&D tax credit claims

**Innovation Score (0-100):**
Higher scores = stronger innovation activity. Factors: patent portfolio (30%), research grant activity (25%), trademark registrations (15%), KTP partnerships (15%), R&D intensity vs sector (15%).

**Upstream Sources:** UK Intellectual Property Office, UKRI Gateway to Research, Innovate UK

---

### 22. Demographics & Deprivation Intelligence

    GET /api/v1/demographics/{postcode}
    GET /api/x402/demographics/{postcode}

Detailed census data, deprivation indices, and consumer profiling with a Spending Power Index for any UK postcode.

**Parameters:**
- `postcode` (path, required) — UK postcode
- `depth` (query, optional) — "summary" | "standard" | "full". Default: "standard"

**Credit Cost:**
- summary: 4 credits ($0.008 x402)
- standard: 12 credits ($0.025 x402)
- full: 24 credits ($0.050 x402)

**Response Fields:**
- `spending_power_index` — Spending Power Index (0-100) with factor breakdown
- `census` — ONS Census 2021: population, age distribution, ethnicity, household composition, tenure, qualifications
- `deprivation` — IMD: overall rank, decile, domain scores (income, employment, education, health, crime, barriers, living environment)
- `consumer_profile` — Household income estimates, economic activity, car ownership, internet access
- `housing` — Tenure mix, property types, overcrowding, second homes
- `migration` — Internal and international migration flows for the area

**Spending Power Index (0-100):**
Higher scores = greater consumer spending power. Factors: household income (30%), deprivation rank (25%), economic activity rate (20%), housing tenure (15%), qualification levels (10%).

**Upstream Sources:** ONS Census 2021, Index of Multiple Deprivation, ONS Annual Survey of Hours and Earnings, CACI

---

## Scoring Algorithms

UKDataAPI provides twelve proprietary scoring algorithms:

### Corporate Distress Score (0-100)
Used in: Entity Intelligence, Due Diligence Report
Higher scores = higher risk. Combines overdue accounts (25%), net assets trend (20%), cash position (15%), officer churn (15%), charges (10%), gazette notices (10%), filing gaps (5%). Calibrated against known UK insolvencies 2018-2024.

### Planning Development Score (0-100)
Used in: Planning Intelligence
Higher scores = greater development viability. Combines constraint density (25%), development momentum (20%), environmental designations (15%), council efficiency (15%), brownfield opportunity (10%), flood risk (10%), mining risk (5%). Based on Planning Data Platform, Natural England, MHCLG, Environment Agency, and Coal Authority data.

Score ranges: 0-24 = HIGHLY_CONSTRAINED, 25-39 = CONSTRAINED, 40-59 = MODERATE, 60-74 = FAVOURABLE, 75-100 = HIGHLY_FAVOURABLE

### Environmental Risk Score (0-100)
Used in: Property Intelligence, Environmental Risk Intelligence
Higher scores = higher risk. Combines flood risk (35%), ground stability (25%), radon (20%), water quality (10%), air quality (10%). Based on Environment Agency, BGS, and Defra datasets.

### Vehicle Health Score (0-100)
Used in: Vehicle Intelligence
Higher scores = better health. Combines MOT pass rate (30%), advisory frequency (25%), mileage consistency (20%), defect severity (15%), age factor (10%). Based on full DVSA MOT history.

### ESG Score (0-100)
Used in: Energy & ESG Intelligence
Higher scores = better environmental performance. Combines grid carbon intensity (30%), local EPC efficiency (25%), renewable capacity (20%), air quality (15%), green space (10%).

### Water Quality Score (0-100)
Used in: Water Quality Intelligence
Higher scores = better water quality. Combines waterbody ecological status (30%), drinking water compliance (25%), pollution incidents (20%), water company performance (15%), bathing water quality (10%).

### Digital Readiness Score (0-100)
Used in: Digital Connectivity Intelligence
Higher scores = better connectivity. Combines broadband speed (30%), full fibre availability (25%), mobile 4G/5G coverage (20%), ISP competition (15%), digital exclusion risk (10%).

### Political Engagement Index
Used in: Political Intelligence
Composite measure of political activity and engagement based on voter turnout, petition activity, MP engagement, and local election participation.

### Director Risk Score (0-100)
Used in: Director Network Intelligence
Higher scores = higher risk. Combines dissolved company count (25%), disqualification history (25%), appointment churn rate (20%), company distress correlation (15%), co-director risk network (15%).

### Funding Opportunity Score (0-100)
Used in: Funding & Grants Intelligence
Higher scores = stronger opportunity match. Combines query relevance (30%), funding value (25%), deadline proximity (20%), funder track record (15%), competition level (10%).

### Innovation Score (0-100)
Used in: Innovation & IP Intelligence
Higher scores = stronger innovation activity. Combines patent portfolio (30%), research grant activity (25%), trademark registrations (15%), KTP partnerships (15%), R&D intensity vs sector (15%).

### Spending Power Index (0-100)
Used in: Demographics & Deprivation Intelligence
Higher scores = greater consumer spending power. Combines household income (30%), deprivation rank (25%), economic activity rate (20%), housing tenure (15%), qualification levels (10%).

## Pricing Tiers

### API Key Access (v1 endpoints)

| Plan | Price | Credits/month | Rate limit |
|------|-------|---------------|------------|
| Free | EUR 0 | 200 | 10 req/min |
| Starter | EUR 39/month | 8,000 | 60 req/min |
| Growth | EUR 129/month | 30,000 | 200 req/min |
| Scale | EUR 349/month | 150,000 | 500 req/min |

### x402 Pay-Per-Request (x402 endpoints)

No subscription required. Pay per request in USDC on Base Mainnet:

| Endpoint | Price |
|----------|-------|
| Entity Intelligence | $0.015 |
| Location Intelligence | $0.020 |
| Property Intelligence | $0.025 |
| Due Diligence Report | $0.050 |
| Environmental Risk | $0.020 |
| Planning Intelligence | $0.020 |
| Market Sizing | $0.025 |
| Trade & Customs | $0.020 |
| Education | $0.020 |
| Transport | $0.020 |
| Vehicle | $0.015 |
| Healthcare | $0.030 |
| Energy & ESG | $0.025 |
| Legal & Policy | $0.025 |
| Tenders | $0.020 |
| Water Quality | $0.020 |
| Digital Connectivity | $0.020 |
| Political | $0.020 |
| Director Network | $0.030 |
| Funding & Grants | $0.025 |
| Innovation & IP | $0.025 |
| Demographics | $0.025 |

Tiered depth pricing applies to endpoints supporting the depth parameter. Summary costs ~10-40% of standard, full costs ~175-200% of standard.

## AI Agent Access

### MCP Server
URL: https://www.ukdatapi.com/api/mcp
22 tools available, one per endpoint. Compatible with Claude Desktop, Cursor, Windsurf, and any MCP-compatible client.
Registry: io.github.jackmmaher/ukdatapi

### x402 Protocol
USDC payments on Base Mainnet (Chain ID 8453).
Asset: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 (USDC)
Price list: https://www.ukdatapi.com/.well-known/x402

### OpenAI Plugin
Manifest: https://www.ukdatapi.com/.well-known/ai-plugin.json
OpenAPI spec: https://www.ukdatapi.com/api/openapi.json

## Rate Limits & Error Codes

| HTTP Code | Meaning |
|-----------|---------|
| 200 | Success |
| 400 | Bad request — invalid parameter format |
| 401 | Unauthorized — missing or invalid API key |
| 402 | Payment required — x402 payment needed |
| 404 | Not found — entity/postcode not found (check suggestion field) |
| 429 | Rate limited — reduce request frequency |
| 500 | Server error — retry with exponential backoff |
| 502 | Upstream API unavailable — partial data may be returned |

## Links

- Website: https://www.ukdatapi.com
- Documentation: https://www.ukdatapi.com/docs
- API Health: https://www.ukdatapi.com/api/v1/health
- OpenAPI Spec: https://www.ukdatapi.com/api/openapi.json
- MCP Registry: https://github.com/modelcontextprotocol/servers
- Pricing: https://www.ukdatapi.com/#pricing
- Status: https://www.ukdatapi.com/api/v1/health