{"openapi":"3.1.0","info":{"version":"6.36.0","title":"Vepler Public API","description":"UK property data in one API: addresses and UPRNs, property records, market listings, sold transactions, planning applications, land titles, schools, energy performance, environmental designations and neighbourhood metrics. Every request is authenticated with an API key sent in the x-api-key header. This specification covers the public API only; webhook and administrative endpoints are not included.","x-logo":{"url":"https://vepler.com/favicon.svg","altText":"Vepler","href":"https://vepler.com"},"contact":{"name":"Vepler Support","email":"support@vepler.com","url":"https://vepler.com"},"license":{"name":"MIT","url":"https://opensource.org/licenses/MIT"}},"servers":[{"url":"https://api.vepler.com","description":"Production API"}],"security":[{"apiKeyAuth":[]}],"tags":[{"name":"Property","description":"Property records keyed by UPRN: physical characteristics, tenure, market status, pricing and ownership. Query one property, a batch, or a whole area."},{"name":"Search","description":"One search endpoint across properties, addresses, streets and places. It infers what the query is from its shape and returns ranked results with the matched entity type on each row."},{"name":"AVM","description":"Automated valuations produced by an ensemble of machine learning models. Each estimate carries a confidence interval, so you can decide when the spread is too wide to act on."},{"name":"Listings","description":"Properties currently advertised for sale or to rent, with asking price, marketing status, descriptions, features and media."},{"name":"EPC","description":"Energy Performance Certificates: current and potential energy ratings, the underlying fabric and heating assessment, improvement recommendations and estimated running costs."},{"name":"Address","description":"UK addressing built on UPRNs. Postcode lookup, type-ahead autocomplete, free-text resolution, reverse geocoding from coordinates, bulk cleansing and verification."},{"name":"Planning","description":"Planning applications from local planning authorities across the UK, with normalised status and development type, decision dates, documents and extracted application detail."},{"name":"Companies","description":"UK company data from Companies House: registrations, officers, and people with significant control. Person records are deduplicated across filings by entity resolution."},{"name":"Councils","description":"Local authorities across Great Britain and Ireland, with contact details, service URLs and administrative identifiers."},{"name":"Schools","description":"Schools with inspection outcomes, performance metrics, intake and capacity, and the trust or authority responsible for them."},{"name":"Schools Catchment","description":"Catchment geometry and admission areas per school, plus the nationwide view of which local authorities have been ingested and to what depth."},{"name":"Schools Reference","description":"Reference data behind the Schools API: the metric framework catalogue and its definitions, the coverage matrix, and the changelog of schema and data changes."},{"name":"Areas","description":"Administrative and statistical geographies across the UK, with boundaries, parent and child hierarchies, and lookups from a point or postcode to the areas containing it."},{"name":"Connectivity","description":"Broadband and mobile coverage at a location: available technologies, achievable speeds and per-operator signal, summarised into comparable scores."},{"name":"POI","description":"Points of interest near a location: amenities, facilities, transport and local services."},{"name":"Streets","description":"Street-level records: the properties on a street and aggregate statistics for it."},{"name":"Metrics","description":"Demographic, economic and housing statistics for UK geographies, comparable across areas of the same type."},{"name":"Safety","description":"Recorded crime and antisocial behaviour by neighbourhood, with counts by category and period, and scores that weight offence severity and recency."},{"name":"Sites","description":"Registered land titles and their boundaries from HM Land Registry. Query by area, find the titles linked to a property, and read enrichment covering planning history, property statistics and area metrics."},{"name":"Buildings","description":"Building footprints and attributes from Ordnance Survey. Look up by building ID or UPRN, search and aggregate by area, or find the buildings at a point."},{"name":"Transactions","description":"Sold property transactions from HM Land Registry price paid data. Search by area, price and date, or read the sale history of a single UPRN."},{"name":"Title Deeds","description":"Purchase official copies of registered title documents. Purchases are charged, and the asynchronous route returns AI-extracted structured detail alongside the source documents."},{"name":"Energy","description":"Electricity network infrastructure across multiple countries and network operators. Substations with capacity and headroom over time, supply area polygons, Embedded Capacity Register entries and scenario forecasts."},{"name":"Air Quality","description":"Modelled pollutant concentrations and air quality bands at a location, including a coordinate-exact route that applies distance decay from the nearest sources."},{"name":"Flood Risk","description":"Flood risk at an exact coordinate, covering the sources assessed, the risk band for each, and the provenance of the underlying datasets."},{"name":"Census","description":"UK census demographics: datasets, variables, classifications and categories, area profiles, rollups for custom areas, and precomputed choropleth tiles (XYZ CSV) with ckmeans breaks."},{"name":"Prosperity","description":"The Prosperity Index for small areas, combining indicators of economic and social outcome into comparable scores."},{"name":"Heritage","description":"Nationally designated heritage assets: scheduled monuments, world heritage sites, registered battlefields and protected wreck sites. Snapshot-versioned and point-queryable, with stable ids, Open Government Licence provenance and an opt-in MultiPolygon boundary."},{"name":"Conservation","description":"Nationally designated conservation areas: Special Areas of Conservation, Special Protection Areas, Ramsar wetlands, ancient and native woodland, and landscape designations. Snapshot-versioned and point-queryable, with stable ids, Open Government Licence provenance and an opt-in MultiPolygon boundary."},{"name":"Land Constraint","description":"Designations that constrain what can be built: Green Belt, Tree Preservation Zones, Article 4 Direction Areas, Agricultural Land Classification, Flood Zones 2 and 3, and Coal Mining Development High Risk Areas. Separately licensed from Heritage and Conservation."},{"name":"Models","description":"Vepler's models, run on your own images in the OpenAI API format. Point any OpenAI SDK at `https://api.vepler.com/v1/ai`; the API key can be sent as `Authorization: Bearer` or in `x-api-key`. Each model reads one image and returns one JSON object."},{"name":"System","description":"Health checks and service status for the API and its upstream dependencies."}],"components":{"securitySchemes":{"apiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"Send your API key in the x-api-key header on every request. Keys are issued from the Vepler dashboard.","x-speakeasy-example":"vpr_live_YOUR_KEY_HERE"}},"schemas":{"PropertyAttributeCatalogue":{"type":"object","properties":{"generatedAt":{"type":"string"},"attributes":{"type":"array","items":{"$ref":"#/components/schemas/PropertyAttributeEntry"}},"groups":{"type":"array","items":{"$ref":"#/components/schemas/PropertyAttributeGroup"}},"tiers":{"type":"array","items":{"$ref":"#/components/schemas/PropertyTierInfo"}},"filterFields":{"type":"array","items":{"$ref":"#/components/schemas/PropertyFilterField"}},"comparators":{"type":"array","items":{"type":"string"}},"sortFields":{"type":"array","items":{"type":"string"},"description":"Every attribute `sort[].field` accepts."},"defaultAttributes":{"type":"array","items":{"type":"string"},"description":"The attributes returned when a request omits `attributes`."},"pencePerCredit":{"type":["number","null"],"description":"What one credit costs in pence on pay-as-you-go, so a charge in pounds is credits multiplied by this and divided by 100. Null when the rate could not be read."},"grantedPermissions":{"type":"array","items":{"type":"string"},"description":"Extended permissions this API key holds. Attributes needing a permission outside this set are left out of responses rather than raising an error."}},"required":["generatedAt","attributes","groups","tiers","filterFields","comparators","sortFields","defaultAttributes","pencePerCredit","grantedPermissions"]},"PropertyAttributeEntry":{"type":"object","properties":{"path":{"type":"string","description":"The attribute's dotted path, written exactly as the `attributes` parameter takes it."},"group":{"type":"string","description":"Group the attribute belongs to, which is the first segment of its path."},"type":{"type":"string","description":"JSON type of the value this attribute returns."},"description":{"type":"string","description":"What the attribute means, as published in the API reference."},"enumValues":{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]},"description":"The full set of values this attribute can take, where it is limited to a fixed set."},"tier":{"type":"string","description":"Billing tier requesting this attribute puts the response into."},"requiresPermission":{"type":["string","null"],"description":"Extended permission needed to receive this attribute, or null when every account may have it."},"filterable":{"type":"boolean","description":"True when this attribute can be used as a `query[].groups[].conditions[].field`."}},"required":["path","group","type","tier","requiresPermission","filterable"]},"PropertyAttributeGroup":{"type":"object","properties":{"key":{"type":"string"},"label":{"type":"string"},"attributeCount":{"type":"integer"},"tier":{"type":"string","description":"The highest billing tier any attribute in this group reaches."}},"required":["key","label","attributeCount","tier"]},"PropertyTierInfo":{"type":"object","properties":{"code":{"type":"string"},"label":{"type":"string"},"credits":{"type":["number","null"],"description":"Credits this tier costs per property record. Tiers add up, and `tier_core` is charged on every request. Null when the price could not be read."}},"required":["code","label","credits"]},"PropertyFilterField":{"type":"object","properties":{"field":{"type":"string","description":"Name accepted by `query[].groups[].conditions[].field`."},"target":{"type":"string","description":"The attribute this name filters on. It matches `field` for a dotted path and differs for an alias."},"kind":{"type":"string","enum":["term","range"],"description":"Which comparators the field takes: a `term` field matches exact values with `eq`, `ne`, `in` and `nin`, and a `range` field takes those plus `gt`, `gte`, `lt` and `lte`."}},"required":["field","target","kind"]},"PropertyListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/PropertyDataApi"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250},"monitoring":{"$ref":"#/components/schemas/PropertyMonitoringReceipt"}},"required":["object","url","has_more","data"]},"PropertyDataApi":{"type":"object","properties":{"propertyId":{"type":"string","description":"Identifier of this property record.","example":"123abc"},"locationId":{"type":"string","description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). It is returned on every property, whichever attributes are requested.","example":"456def"},"countryCode":{"type":"string","enum":["GB","IE"],"description":"Sovereign state the property sits in, as an ISO 3166-1 alpha-2 code. Distinct from `address.country`, which names the UK nation.","example":"GB"},"idScheme":{"type":"string","enum":["uprn","eircode"],"description":"Which identifier scheme `locationId` holds: `uprn` for Great Britain, `eircode` for Ireland.","example":"uprn"},"uprn":{"type":["string","null"],"description":"The Unique Property Reference Number (UPRN). The same value as `locationId` for properties in Great Britain, and null elsewhere.","example":"456def"},"slug":{"type":"string","description":"The address as a URL-safe slug, for building readable property links.","example":"123-main-street-london"},"sources":{"type":"array","items":{"type":"string"},"default":[],"description":"Identifiers of the listing records behind this property, each as `provider::key`. Returned only to callers holding the source-data permission."},"parentLocationId":{"type":["string","null"],"description":"Location ID of the parent this property sits within, such as the block a flat belongs to."},"streetIds":{"type":"array","items":{"type":"number"},"description":"Unique Street Reference Numbers (USRNs) of the streets this property is addressed on."},"classificationCode":{"type":["string","null"],"description":"How Ordnance Survey classifies the use of this address, for example `RD` for a residential dwelling, `RH` for a house in multiple occupation and `C` codes for commercial premises. Read `propertyCategory` for the residential or commercial split rather than reading the code's first letter.","example":"RD06"},"propertyCategory":{"type":["string","null"],"enum":["residential","commercial",null],"description":"Whether the property is residential or commercial, derived from its classification code."},"occupancyStatus":{"type":["string","null"],"enum":["planned","under_construction","occupied","vacant","demolished",null],"description":"Where the property sits in its physical life, from planned through occupied to demolished.","example":"occupied"},"unitCount":{"type":["integer","null"],"minimum":1,"description":"Number of addressable sub-units the property contains, such as the flats in a block.","example":12},"coordinateConfidence":{"type":["string","null"],"enum":["high","medium","low",null],"description":"How precisely the coordinates place the property: `high` is within the building footprint, `low` is no better than a postcode centroid.","example":"high"},"build":{"$ref":"#/components/schemas/BuildData"},"building":{"type":["object","null"],"properties":{"osid":{"type":"string","format":"uuid","description":"Ordnance Survey identifier for the building. It is the source identifier of the matching record on the Buildings API."},"structure":{"type":["object","null"],"properties":{"footprintAreaSqm":{"type":["number","null"],"description":"Area covered by the building footprint, in square metres."},"heightMax":{"type":["number","null"],"description":"Height from ground level to the highest point of the building, in metres."},"floors":{"type":["integer","null"],"description":"Number of floors above ground."},"physicalState":{"type":["string","null"],"description":"Physical state of the building, in the source's own wording.","example":"Extant"},"connectivity":{"type":["string","null"],"description":"Whether the building stands alone or is joined to neighbouring buildings, in the source's own wording.","example":"Detached"}},"description":"Physical dimensions and form of the building."},"construction":{"type":["object","null"],"properties":{"material":{"type":["string","null"],"description":"Primary wall construction material, in the source's own wording.","example":"Brick Or Block Or Stone"},"period":{"type":["string","null"],"description":"Period the building was constructed in, as an age band in the source's own wording.","example":"1900-1918"},"year":{"type":["integer","null"],"description":"Year the building was constructed, where one is recorded."}},"description":"Construction age and materials, drawn from the building survey data and from EPC assessments."},"roof":{"type":["object","null"],"properties":{"shape":{"type":["string","null"],"description":"Shape of the roof.","example":"Pitched"},"material":{"type":["string","null"],"description":"Primary roof covering material. Not included in property responses.","example":"Slate"},"area":{"type":["object","null"],"properties":{"total":{"type":["number","null"],"description":"Total roof surface area, in square metres."},"flat":{"type":["number","null"],"description":"Roof surface area that is flat, in square metres."},"pitched":{"type":["number","null"],"description":"Roof surface area that is pitched, in square metres."},"indeterminable":{"type":["number","null"],"description":"Roof surface area whose form could not be determined, in square metres."},"north":{"type":["number","null"],"description":"North-facing roof surface area, in square metres."},"northeast":{"type":["number","null"],"description":"North-east-facing roof surface area, in square metres."},"east":{"type":["number","null"],"description":"East-facing roof surface area, in square metres."},"southeast":{"type":["number","null"],"description":"South-east-facing roof surface area, in square metres."},"south":{"type":["number","null"],"description":"South-facing roof surface area, in square metres."},"southwest":{"type":["number","null"],"description":"South-west-facing roof surface area, in square metres."},"west":{"type":["number","null"],"description":"West-facing roof surface area, in square metres."},"northwest":{"type":["number","null"],"description":"North-west-facing roof surface area, in square metres."}},"description":"Roof surface area broken down by form and orientation. Not included in property responses."},"solar":{"type":["string","null"],"enum":["present","absent",null],"description":"Whether solar panels are present on the roof."},"greenRoof":{"type":["string","null"],"enum":["present","absent",null],"description":"Whether the roof is a green or living roof. Not included in property responses."}},"description":"Roof characteristics. On this surface the values come from EPC assessments."},"basement":{"type":["object","null"],"properties":{"present":{"type":["string","null"],"enum":["present","absent",null],"description":"Whether the building has a basement."},"selfContained":{"type":["string","null"],"enum":["present","absent",null],"description":"Whether the basement is self-contained, with its own entrance."}},"description":"Whether the building has a basement, and whether that basement is self-contained."},"type":{"type":["string","null"],"description":"Descriptive classification of the structure, in the source's own wording.","example":"Building"},"use":{"type":["string","null"],"description":"Primary use of the building, in the source's own wording.","example":"Residential"},"addressCount":{"type":["object","null"],"properties":{"total":{"type":["integer","null"],"description":"Number of addressable locations in this building."},"residential":{"type":["integer","null"],"description":"How many of those locations are classified residential."},"commercial":{"type":["integer","null"],"description":"How many of those locations are classified commercial."},"other":{"type":["integer","null"],"description":"How many of those locations fall outside the residential and commercial classes."}},"description":"Counts of the addressable locations in this building, split by classification."},"dataSources":{"type":"array","items":{"type":"string"},"default":[],"description":"Data sources that contributed at least one field to this building."},"_provenance":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{}},"description":"Where each field's value came from, keyed by the field's dotted path. Takes the same shape as the provenance map on the building at the linked `osid`. Returned only when `_provenance` is among the requested attributes."}},"description":"Physical description of the building the property is part of."},"address":{"$ref":"#/components/schemas/PropertyAddress"},"spatial":{"type":"object","properties":{"type":{"type":"string","enum":["Point"],"description":"Geometry type discriminator. Always `Point`.","example":"Point"},"coordinates":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180,"description":"Longitude."},{"type":"number","minimum":-90,"maximum":90,"description":"Latitude."}],"description":"The property's position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]},"boundary":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180,"description":"Longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order)."},{"type":"number","minimum":-90,"maximum":90,"description":"Latitude."}]},"minItems":4},"minItems":1}},"required":["type","coordinates"]},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180,"description":"Longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order)."},{"type":"number","minimum":-90,"maximum":90,"description":"Latitude."}]},"minItems":4}},"minItems":1}},"required":["type","coordinates"]}],"description":"The property's boundary, as a GeoJSON Polygon or MultiPolygon.","example":{"type":"Polygon","coordinates":[[[-0.128,51.5075],[-0.1276,51.5075],[-0.1276,51.5073],[-0.128,51.5073],[-0.128,51.5075]]]}}}},"roomDetails":{"$ref":"#/components/schemas/RoomDetails"},"pricing":{"$ref":"#/components/schemas/PricingData"},"marketStatus":{"$ref":"#/components/schemas/MarketStatus"},"epc":{"$ref":"#/components/schemas/EPCData"},"saleHistory":{"type":"array","items":{"$ref":"#/components/schemas/SaleRecord"},"description":"Sales of the property recorded in the price register, most recent first."},"tenure":{"$ref":"#/components/schemas/TenureData"},"councilTax":{"$ref":"#/components/schemas/CouncilTaxData"},"tags":{"$ref":"#/components/schemas/PropertyTags"},"listings":{"type":"array","items":{"$ref":"#/components/schemas/Listing"},"default":[],"description":"Sale and rental listings for the property, live and historic."},"priceChangeSale":{"type":"array","items":{"$ref":"#/components/schemas/PriceChange"},"description":"Every sale asking price recorded for the property, starting with the first."},"priceChangeRent":{"type":"array","items":{"$ref":"#/components/schemas/PriceChange"},"description":"Every rental asking price recorded for the property, starting with the first."},"leases":{"type":"array","items":{"$ref":"#/components/schemas/Lease"},"description":"Leases registered against the property, those carrying an alienation clause first."},"tenancy":{"$ref":"#/components/schemas/TenancyData"},"charges":{"type":"object","properties":{"serviceCharge":{"$ref":"#/components/schemas/ChargeHistory"},"groundRent":{"$ref":"#/components/schemas/ChargeHistory"}},"description":"Recurring charges on the property: the service charge and the ground rent."},"floodRisk":{"type":"object","properties":{"riskLevel":{"type":"string","description":"Level of flood risk recorded at this location."},"suitability":{"type":["string","null"],"description":"Suitability assessment recorded for the location."}},"description":"Flood risk recorded at the property's location."},"refurbishment":{"$ref":"#/components/schemas/RefurbishmentData"},"overlays":{"type":"array","items":{"type":"string"},"default":[],"description":"Environmental and spatial characteristics recorded at this location, such as designations, flood risk bands, noise bands and radon bands, each as an upper-case tag."},"relationships":{"type":"array","items":{"type":"string"},"description":"Areas and cross-references this property belongs to, each written as `TYPE::id`, such as `LSOA::E01000001` for its Lower Layer Super Output Area or `WARD::E05000123` for its ward."},"assessments":{"$ref":"#/components/schemas/PropertyAssessments"},"_provenance":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{}},"description":"Where each claim-resolved value came from, keyed by the field it applies to. Request it through `attributes`; it is returned only to callers holding the source-data permission."}}},"BuildData":{"type":"object","properties":{"propertyType":{"type":["string","null"],"enum":["unknown","other","flat","detached","semiDetached","terraced","bungalow","maisonette","cottage","chalet","lodge","mobileHome","houseboat","retirement","characterProperty","blockOfFlats","houseShare","farmhouse","mill","barn","coachHouse","statelyHome","farm","parking","equestrian","restaurant","industrial","warehouse","leisure","retail","land","office","riad","hotel","studentAccommodation","commercial","pub","bar","hotelRoom","shop","retailHighStreet","retailOutOfTown","industrialDevelopment","distributionWarehouse","industrialPark","storage","servicedOffice","residentialDevelopment","commercialDevelopment","mixedUse",null],"description":"Type of property, taken from a fixed set of types.","example":"terraced"},"subPropertyType":{"type":["string","null"],"description":"A more detailed property type, not restricted to the fixed set `propertyType` uses.","example":"Victorian terrace"},"floorHeight":{"type":["number","null"],"description":"Floor height recorded for the property."},"totalFloorArea":{"type":["number","null"],"description":"Total internal floor area, in square metres, as measured for the energy certificate.","example":85},"mainsGasFlag":{"type":["string","null"],"description":"Mains gas availability recorded for the property."},"mainFuel":{"type":["string","null"],"description":"Main fuel the property is heated with."},"windowType":{"type":["string","null"],"description":"How the windows are glazed."},"roofType":{"type":["string","null"],"description":"How the roof is built."},"wallType":{"type":["string","null"],"description":"How the walls are built."},"constructionAge":{"type":["object","null"],"properties":{"startYear":{"type":"number","description":"First year of the period the property was built in."},"endYear":{"type":"number","description":"Last year of the period the property was built in."},"midYear":{"type":"number","description":"Mid-point of the period, useful when a single year is needed."},"isExact":{"type":"boolean","description":"True when the year of construction is known exactly rather than as a period."}},"description":"When the property was built, as a period rather than a single year.","example":{"startYear":1880,"endYear":1900,"midYear":1890,"isExact":false}}}},"PropertyAddress":{"type":"object","properties":{"displayAddress":{"type":"string","description":"The whole address on one line, ready to show to an end user.","example":"123 Example Street, London SW1A 1AA"},"line_1":{"type":"string","description":"First line of the address: organisation, sub-building, building name or number, and street.","example":"Flat 10, 7-12 Tuckers Close"},"line_2":{"type":"string","description":"Second line of the address, the locality. Empty when the address has no locality.","example":"Horsell"},"line_3":{"type":"string","description":"Third line of the address. Always empty: no address component is composed into it.","example":""},"post_town":{"type":"string","description":"Post town the address is delivered through.","example":"Woking"},"county":{"type":"string","description":"Ceremonial county the postcode falls in, such as `Surrey`, `Greater London` or `Powys`. It is not part of `displayAddress`, cannot be filtered on, and is not served on map tiles. It is absent where there is none (Northern Ireland has no ceremonial county) and on properties whose stored address predates the field, so absence does not mean the postcode has no county. `GET /v1/address/postcodes/{postcode}` resolves the same value on demand for any GB postcode.","example":"Surrey"},"postcode":{"type":"string","pattern":"^[A-Z]{1,2}[0-9][0-9A-Z]?\\s?[0-9][A-Z]{2}$","description":"A full UK postcode. The space is optional and case is not significant; the value is returned upper-cased.","example":"SW1A 1AA"},"postcodeNoSpace":{"type":"string","description":"The postcode with the space removed. This is the form a postcode area filter matches against.","example":"SW1A1AA"},"outcode":{"type":"string","description":"The outward code, the first part of the postcode, such as `SW1A`.","example":"SW1A"},"incode":{"type":"string","description":"The inward code, the second part of the postcode.","example":"1AA"},"country":{"type":["string","null"],"description":"The UK nation the address sits in, as a slug: `england`, `scotland`, `wales` or `northern-ireland`. Null when the nation could not be resolved.","example":"scotland"},"countryCode":{"type":"string","enum":["GB","IE"],"description":"Sovereign state the address sits in, as an ISO 3166-1 alpha-2 code. Distinct from `country`, which names the UK nation.","example":"GB"},"eircode":{"type":["string","null"],"description":"Irish postal code. Null for addresses in Great Britain, which carry `postcode` instead.","example":"D02 AF30"}}},"RoomDetails":{"type":"object","properties":{"beds":{"type":["number","null"],"description":"Number of bedrooms.","example":3},"baths":{"type":["number","null"],"description":"Number of bathrooms.","example":2}}},"PricingData":{"type":"object","properties":{"currentSale":{"type":["number","null"],"description":"Asking price on the live sale listing, in whole pounds. Null when the property is not for sale.","example":450000},"currentRent":{"type":["number","null"],"description":"Asking rent on the live rental listing, per month in whole pounds. Null when it is not to let.","example":1500},"estimatedSale":{"type":["number","null"],"description":"Sale asking price taken from the property's listings, including ones no longer live, in whole pounds.","example":190000},"estimatedRent":{"type":["number","null"],"description":"Rental asking price taken from the property's listings, including ones no longer live, per month in whole pounds.","example":625},"currency":{"type":["string","null"],"description":"Currency the prices are quoted in, as an ISO 4217 code.","example":"GBP"}}},"MarketStatus":{"type":"object","properties":{"timeline":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["sale","rent"]},"start":{"type":"string","format":"date-time"},"end":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["live","sstc","under_offer","reserved","removed"]},"statusTimeline":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","enum":["live","sstc","under_offer","reserved","removed"]},"start":{"type":"string","format":"date-time","description":"When the property entered this status, as an ISO 8601 timestamp."},"end":{"type":["string","null"],"format":"date-time","description":"When the property left this status, as an ISO 8601 timestamp. Null while the status still holds."}}}}}},"description":"Every marketing period the property has been through, for sale and to let."},"forSale":{"type":"string","enum":["live","sstc","under_offer","unavailable"],"description":"Where the property currently stands in the sale market.","example":"live"},"forRent":{"type":"string","enum":["live","reserved","unavailable"],"description":"Where the property currently stands in the rental market.","example":"unavailable"},"pricePerSqft":{"type":["number","null"],"description":"Sale price per square foot of floor area.","example":850},"pricePerSqm":{"type":["number","null"],"description":"Price per square metre of floor area.","example":9150},"backOTMRent":{"type":["boolean","null"],"description":"True when the property returned to the rental market within 180 days of an earlier period ending.","example":false},"lastOTMRent":{"type":["string","null"],"format":"date-time","description":"When the property was last on the rental market, as an ISO 8601 timestamp: the start of the current period, or the end of the most recent one when it is no longer listed.","example":"2024-01-15T00:00:00Z"},"backOTM":{"type":["boolean","null"],"description":"True when the property returned to the sale market within 180 days of an earlier period ending.","example":false},"hasPriceReductionSale":{"type":["boolean","null"],"description":"True when a live sale listing has reduced its price at least once.","example":false},"hasPriceReductionRent":{"type":["boolean","null"],"description":"True when a live rental listing has reduced its price at least once.","example":false},"lastOTM":{"type":["string","null"],"format":"date-time","description":"When the property was last on the sale market, as an ISO 8601 timestamp: the start of the current period, or the end of the most recent one when it is no longer listed.","example":"2024-01-15T00:00:00Z"},"sstcDate":{"type":["string","null"],"format":"date-time","description":"When the property became sold subject to contract, as an ISO 8601 timestamp.","example":"2024-03-01T00:00:00Z"},"reservedDate":{"type":["string","null"],"format":"date-time","description":"When the property was reserved, as an ISO 8601 timestamp.","example":"2024-02-15T00:00:00Z"},"underOfferDate":{"type":["string","null"],"format":"date-time","description":"When the property went under offer, as an ISO 8601 timestamp.","example":"2024-02-20T00:00:00Z"}}},"EPCData":{"type":"object","properties":{"currentRatingBand":{"type":["string","null"],"enum":["A+","A","B+","B","C+","C","D+","D","E+","E","F+","F","G",null],"description":"Energy efficiency band on the current certificate, where A+ and A are the most efficient and G the least.","example":"C"},"currentRatingScore":{"type":["number","null"],"description":"Numeric energy score on the current certificate. Read it with `rating.current.scoreType`: a domestic SAP score runs 1 to 100 and higher is better.","example":69},"rating":{"type":["object","null"],"properties":{"current":{"type":"object","properties":{"band":{"type":"string","enum":["A+","A","B+","B","C+","C","D+","D","E+","E","F+","F","G"],"description":"Energy efficiency band, where A+ and A are the most efficient and G the least. Domestic certificates use A to G, non-domestic certificates add A+, and Scotland non-domestic certificates also use half-bands such as B+ and C+."},"score":{"type":"number","description":"Numeric score behind the band, read alongside `scoreType`. A `sap` score runs from 1 to 100 and higher is better. An `asset` score is in kg CO2 per m² and an `operational` score is measured against a benchmark; both are unbounded and lower is better. An `epi` score is in kg CO2 per m² calculated with Scottish weather data."},"scoreType":{"type":"string","enum":["sap","asset","operational","epi"],"description":"Which scale `score` is on. Read it before comparing scores across certificates."}},"description":"The rating the building holds as assessed."},"potential":{"type":["object","null"],"properties":{"band":{"type":"string","enum":["A+","A","B+","B","C+","C","D+","D","E+","E","F+","F","G"],"description":"Energy efficiency band, where A+ and A are the most efficient and G the least. Domestic certificates use A to G, non-domestic certificates add A+, and Scotland non-domestic certificates also use half-bands such as B+ and C+."},"score":{"type":"number","description":"Numeric score behind the band, read alongside `scoreType`. A `sap` score runs from 1 to 100 and higher is better. An `asset` score is in kg CO2 per m² and an `operational` score is measured against a benchmark; both are unbounded and lower is better. An `epi` score is in kg CO2 per m² calculated with Scottish weather data."},"scoreType":{"type":"string","enum":["sap","asset","operational","epi"],"description":"Which scale `score` is on. Read it before comparing scores across certificates."}},"description":"The rating the building would reach if the recommended improvements were carried out. Null on Display Energy Certificates, which rate measured use rather than potential, and on England and Wales non-domestic certificates, which do not publish one. Scotland non-domestic does."},"carbonNeutral":{"type":"boolean","description":"True when the building is rated carbon neutral. Scotland non-domestic certificates record this as a 'Carbon Neu' band, which is published here as band `A+` with this flag set."}},"description":"Energy rating as assessed, and as it could be with the recommended improvements made."},"emissions":{"type":["object","null"],"properties":{"co2Current":{"type":["number","null"],"description":"Annual carbon dioxide emissions at the assessed efficiency. Domestic certificates report tonnes per year and non-domestic certificates report kg CO2 per m² per year; read `co2Unit` for the unit that applies to this record."},"co2Potential":{"type":["number","null"],"description":"Annual carbon dioxide emissions once the recommended improvements are carried out. Domestic only; null on non-domestic certificates and Display Energy Certificates."},"co2PerFloorArea":{"type":["number","null"],"description":"Annual carbon dioxide emissions per square metre of floor area, in kg CO2 per m² per year. On non-domestic certificates this is the building emission rate."},"co2Unit":{"type":"string","enum":["tonnes_per_year","kg_co2_per_m2_per_year"],"description":"The unit `co2Current` is expressed in. Domestic certificates use `tonnes_per_year`; non-domestic certificates and Display Energy Certificates use `kg_co2_per_m2_per_year`."},"environmentalScoreCurrent":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Environmental impact score from 1 to 100, where higher is better. Domestic only."},"environmentalScorePotential":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"The environmental impact score the property would reach once the recommended improvements are carried out, on the same 1 to 100 scale. Domestic only."},"energyConsumptionCurrent":{"type":["number","null"],"description":"Annual energy consumption at the assessed efficiency. Domestic certificates report kWh per year and non-domestic certificates report kWh per m² per year; read `energyConsumptionUnit` for the unit that applies to this record."},"energyConsumptionPotential":{"type":["number","null"],"description":"Annual energy consumption once the recommended improvements are carried out. Domestic only."},"energyConsumptionUnit":{"type":["string","null"],"enum":["kwh_per_year","kwh_per_m2_per_year",null],"description":"The unit `energyConsumptionCurrent` is expressed in."}},"description":"Environmental impact, carbon dioxide emissions and energy consumption from the certificate."},"runningCosts":{"type":["object","null"],"properties":{"heating":{"type":"object","properties":{"current":{"type":"integer","description":"Estimated annual heating cost at the assessed efficiency, in GBP."},"potential":{"type":"integer","description":"Estimated annual heating cost once the recommended improvements are carried out, in GBP."}},"description":"Estimated annual heating cost, as assessed and after improvement."},"hotWater":{"type":"object","properties":{"current":{"type":"integer","description":"Estimated annual hot water cost at the assessed efficiency, in GBP."},"potential":{"type":"integer","description":"Estimated annual hot water cost once the recommended improvements are carried out, in GBP."}},"description":"Estimated annual hot water cost, as assessed and after improvement."},"lighting":{"type":"object","properties":{"current":{"type":"integer","description":"Estimated annual lighting cost at the assessed efficiency, in GBP."},"potential":{"type":"integer","description":"Estimated annual lighting cost once the recommended improvements are carried out, in GBP."}},"description":"Estimated annual lighting cost, as assessed and after improvement."}},"description":"Estimated annual running costs for heating, hot water and lighting. Domestic certificates only; null for the other types."},"fabric":{"type":["object","null"],"properties":{"walls":{"type":"object","properties":{"construction":{"type":["string","null"],"enum":["cavity","solid_brick","timber_frame","sandstone_or_limestone","sandstone","granite_or_whinstone","granite","system_built","solid_stone","cob","park_home","basement","curtain_wall",null],"description":"How the external walls are built."},"material":{"type":["string","null"],"description":"The wall material, for example 'brick', where the assessor's description identifies one."},"insulationType":{"type":["string","null"],"enum":["none","as_built","filled_cavity","external","internal","filled_cavity_and_external","filled_cavity_and_internal","partial","retro_fitted","loft","rafter",null],"description":"How the walls are insulated, if at all."},"insulationPresent":{"type":["boolean","null"],"description":"True when the walls are insulated."},"insulationAssumed":{"type":"boolean","description":"True when the assessor assumed the insulation rather than confirming it."},"thermalTransmittance":{"type":["number","null"],"description":"Thermal transmittance (U-value) of the walls, in W/m²K, where the assessment reports one."},"description":{"type":["string","null"],"description":"The assessor's own description of the walls, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient the walls are, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How the walls score for environmental impact, on the certificate's five-point scale."},"dataQuality":{"type":["string","null"],"enum":["truncated_thermal_transmittance","quality_label_only","welsh_language","corrupted_encoding","source_error",null],"description":"Set when the source value could not be read as recorded, giving the reason. Null when the value came through intact."}},"description":"The external walls and their insulation."},"roof":{"type":"object","properties":{"roofType":{"type":["string","null"],"enum":["pitched","flat","thatched","another_dwelling_above","other_premises_above","roof_room",null],"description":"How the roof is built, including the cases where another dwelling or premises sits above."},"insulationType":{"type":["string","null"],"enum":["none","as_built","filled_cavity","external","internal","filled_cavity_and_external","filled_cavity_and_internal","partial","retro_fitted","loft","rafter",null],"description":"How the roof is insulated, if at all."},"insulationDepthMm":{"type":["integer","null"],"description":"Depth of the loft insulation, in millimetres."},"insulationPresent":{"type":["boolean","null"],"description":"True when the roof is insulated."},"insulationAssumed":{"type":"boolean","description":"True when the assessor assumed the insulation rather than confirming it."},"thermalTransmittance":{"type":["number","null"],"description":"Thermal transmittance (U-value) of the roof, in W/m²K, where the assessment reports one."},"description":{"type":["string","null"],"description":"The assessor's own description of the roof, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient the roof is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How the roof scores for environmental impact, on the certificate's five-point scale."},"dataQuality":{"type":["string","null"],"enum":["truncated_thermal_transmittance","quality_label_only","welsh_language","corrupted_encoding","source_error",null],"description":"Set when the source value could not be read as recorded, giving the reason. Null when the value came through intact."}},"description":"The roof and its insulation."},"floor":{"type":"object","properties":{"floorType":{"type":["string","null"],"enum":["solid","suspended_timber","suspended_sealed","another_dwelling_below","other_premises_below",null],"description":"How the ground floor is built, including the cases where another dwelling or premises sits below."},"insulationPresent":{"type":["boolean","null"],"description":"True when the floor is insulated."},"insulationAssumed":{"type":"boolean","description":"True when the assessor assumed the insulation rather than confirming it."},"insulationType":{"type":["string","null"],"enum":["none","as_built","filled_cavity","external","internal","filled_cavity_and_external","filled_cavity_and_internal","partial","retro_fitted","loft","rafter",null],"description":"How the floor is insulated, where insulation is present."},"thermalTransmittance":{"type":["number","null"],"description":"Thermal transmittance (U-value) of the floor, in W/m²K, where the assessment reports one."},"description":{"type":["string","null"],"description":"The assessor's own description of the floor, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient the floor is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How the floor scores for environmental impact, on the certificate's five-point scale."},"dataQuality":{"type":["string","null"],"enum":["truncated_thermal_transmittance","quality_label_only","welsh_language","corrupted_encoding","source_error",null],"description":"Set when the source value could not be read as recorded, giving the reason. Null when the value came through intact."}},"description":"The ground floor and its insulation."},"mainHeating":{"type":"object","properties":{"systemType":{"type":["string","null"],"enum":["boiler_radiators","boiler_underfloor","storage_heaters","room_heaters","warm_air","heat_pump_radiators","heat_pump_underfloor","underfloor_electric","community_scheme","micro_chp","none_assumed",null],"description":"What kind of main heating system is installed."},"fuel":{"type":["string","null"],"enum":["mains_gas","lpg","oil","electricity","biomass","coal","anthracite","smokeless_fuel","biogas","district_heating","heat_pump","dual_fuel","waste_heat","other",null],"description":"The fuel this heating system runs on."},"heatPumpType":{"type":["string","null"],"enum":["air_source","ground_source","water_source",null],"description":"Where the heat pump draws its heat from, where the system is a heat pump."},"isMultiSystem":{"type":"boolean","description":"True when the certificate records more than one heating system."},"description":{"type":["string","null"],"description":"The assessor's own description of the heating system, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient the heating system is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How the heating system scores for environmental impact, on the certificate's five-point scale."},"dataQuality":{"type":["string","null"],"enum":["truncated_thermal_transmittance","quality_label_only","welsh_language","corrupted_encoding","source_error",null],"description":"Set when the source value could not be read as recorded, giving the reason. Null when the value came through intact."}},"description":"The main heating system."},"windows":{"type":"object","properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"description":"The windows and their glazing."},"heatingControls":{"type":"object","properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"description":"How the heating is controlled."},"hotWater":{"type":"object","properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"description":"The hot water system."},"lighting":{"type":"object","properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"description":"The lighting installed."},"secondaryHeating":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"description":"Any secondary heating system. Null when the property has none."},"airTightness":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"description":"The air tightness assessment. Scotland only; null on England and Wales certificates."}},"description":"Component-by-component assessment of the building, covering walls, roof, floor, windows and more. Domestic certificates only."},"systems":{"type":["object","null"],"properties":{"mainFuel":{"type":["string","null"],"enum":["mains_gas","lpg","oil","electricity","biomass","coal","anthracite","smokeless_fuel","biogas","district_heating","heat_pump","dual_fuel","waste_heat","other",null],"description":"The main fuel the building uses, mapped to a standard set of categories. `mainFuelExternal` carries the wording used on the certificate."},"mainFuelExternal":{"type":["string","null"],"description":"The fuel exactly as the certificate words it, for example 'mains gas (not community)' or 'electricity (7-hour tariff)'."},"mainsGas":{"type":["boolean","null"],"description":"True when the property has a mains gas connection. Domestic only; null when the certificate does not say."},"energyTariff":{"type":["string","null"],"enum":["single","dual","off_peak_7hr","off_peak_10hr","off_peak_18hr","off_peak_24hr","unknown",null],"description":"The electricity tariff the property is on, including the off-peak arrangements. Domestic only."},"mainHeatingControls":{"type":["string","null"],"description":"The heating controls recorded on the certificate, as a source code. Domestic only."},"renewables":{"type":"object","properties":{"solarThermal":{"type":["boolean","null"],"description":"True when the building has solar thermal panels heating its hot water."},"photovoltaic":{"type":["object","null"],"properties":{"present":{"type":"boolean","description":"True when solar photovoltaic panels are installed."},"supplyPercentage":{"type":["number","null"],"description":"The photovoltaic supply figure recorded on the certificate, as a percentage. Domestic only."}},"description":"The solar photovoltaic installation."},"windTurbines":{"type":["integer","null"],"description":"Number of wind turbines installed. Domestic only."},"description":{"type":["string","null"],"description":"The renewable sources in the assessor's own words. Non-domestic only."}},"description":"Renewable energy generated on site."},"ventilation":{"type":["string","null"],"enum":["natural","mechanical_extract","mechanical_supply_and_extract",null],"description":"How the property is ventilated. Domestic only."},"heatLossCorridor":{"type":["string","null"],"enum":["no_corridor","heated_corridor","unheated_corridor",null],"description":"Whether the dwelling is reached by a corridor and whether that corridor is heated. Recorded for flats and maisonettes only."},"unheatedCorridorLength":{"type":["number","null"],"description":"Length of the unheated corridor, in metres. Recorded for flats and maisonettes only."},"airConditioning":{"type":["object","null"],"properties":{"present":{"type":"boolean","description":"True when the building has air conditioning."},"kwRating":{"type":["number","null"],"description":"Rated capacity of the air conditioning system, in kW."},"estimatedKwRating":{"type":["number","null"],"description":"Estimated capacity of the air conditioning system, in kW, used when the rated capacity is unknown."},"inspectionStatus":{"type":["string","null"],"enum":["completed","commissioned","not_commissioned","not_relevant","unknown",null],"description":"Whether an air conditioning inspection has been carried out, commissioned, or is not relevant."}},"description":"The building's air conditioning. Recorded on non-domestic certificates and Display Energy Certificates; null for domestic."}},"description":"The property's energy systems: fuel, heating controls, ventilation and on-site renewables."},"recommendations":{"type":"array","items":{"type":"object","properties":{"sequence":{"type":"integer","description":"Position in the recommended order. Carrying the measures out in this order gives the most cost-effective path."},"measure":{"type":["string","null"],"enum":["wall_insulation","wall_insulation_combined","cavity_wall_insulation","loft_insulation","floor_insulation_solid","floor_insulation_suspended","flat_roof_insulation","room_in_roof_insulation","party_wall_insulation","draught_proofing","external_doors","double_glazing","replacement_glazing","secondary_glazing","condensing_boiler","gas_condensing_boiler","oil_condensing_boiler","room_to_condensing_boiler","condensing_unit","gas_condensing_unit","warm_air_unit","storage_heaters","storage_heaters_dual_immersion","heating_controls","zone_control","flue_gas_recovery","shower_heat_recovery","cylinder_jacket","cylinder_insulation","cylinder_thermostat","water_heating_controls","heat_pump","heat_pump_underfloor","biomass_boiler","solar_thermal","solar_pv","wind_turbine","pv_battery","pv_diverter","low_energy_lighting",null],"description":"Which improvement is recommended, mapped to a standard set of measures."},"category":{"type":["string","null"],"enum":["insulation","glazing","heating","hot_water","renewables","lighting",null],"description":"What kind of improvement the measure is."},"summary":{"type":["string","null"],"description":"The measure in a short line, as worded on the certificate."},"description":{"type":["string","null"],"description":"The fuller explanation of the measure, as worded on the certificate."},"cost":{"type":["object","null"],"properties":{"min":{"type":["integer","null"],"description":"Low end of the estimated cost, in GBP."},"max":{"type":["integer","null"],"description":"High end of the estimated cost, in GBP."},"currency":{"type":"string","enum":["GBP"],"description":"The currency of the cost figures. Always `GBP`."},"year":{"type":["integer","null"],"description":"The year the cost was estimated in. Treat it as the base year when adjusting for inflation."},"indicative":{"type":["string","null"],"description":"The cost range exactly as the certificate words it, for example '£100 - £350'."}},"description":"What the measure is estimated to cost, as numeric bounds in GBP. Use `cost.year` as the base year when adjusting for inflation."},"saving":{"type":["object","null"],"properties":{"annual":{"type":["integer","null"],"description":"Estimated saving each year, in GBP."},"currency":{"type":"string","enum":["GBP"],"description":"The currency of the saving. Always `GBP`."}},"description":"What the measure is estimated to save each year, in GBP."},"projectedRating":{"type":["object","null"],"properties":{"band":{"type":["string","null"],"description":"The energy band the dwelling reaches once this measure is in place, for example 'C'."},"energyScore":{"type":["integer","null"],"description":"The SAP score the dwelling reaches with this measure and every measure before it in the sequence."},"environmentalScore":{"type":["integer","null"],"description":"The environmental impact score the dwelling reaches with this measure and every measure before it."}},"description":"The rating reached once this measure is carried out. Domestic only."},"greenDealEligible":{"type":["boolean","null"],"description":"True when the measure qualifies for Green Deal financing."},"paybackType":{"type":["string","null"],"enum":["short","medium","long","other",null],"description":"How long the measure takes to pay for itself. Non-domestic only."},"co2Impact":{"type":["string","null"],"enum":["low","medium","high",null],"description":"How much the measure cuts carbon dioxide emissions. Scotland non-domestic only."},"measureCode":{"type":["string","null"],"description":"The code this measure carries on the source certificate. Scottish certificates prefix theirs with 'EPC-', such as 'EPC-R4'."}},"description":"One recommended improvement, with its cost and saving estimates, its standard measure classification, and the rating it would achieve."},"description":"Improvements the assessor recommended, with their expected effect on the rating."},"meesCompliance":{"type":["string","null"],"enum":["compliant","at_risk","non_compliant","not_applicable","exempt","unknown",null],"description":"Whether the property meets the Minimum Energy Efficiency Standard that governs letting."},"certificateType":{"type":["string","null"],"enum":["domestic","non_domestic","dec",null],"description":"Which kind of certificate this is: domestic, non-domestic, or a display energy certificate."},"inspectionDate":{"type":["string","null"],"description":"When the property was inspected for this certificate, as an ISO 8601 date."},"sourceReference":{"type":["string","null"],"description":"The certificate's own identifier in the register it came from."}}},"SaleRecord":{"type":"object","properties":{"sourceId":{"type":"string","description":"Identifier of this sale in the register it came from.","example":"hmlr-123456"},"date":{"type":"string","format":"date-time","description":"When the sale completed, as an ISO 8601 timestamp.","example":"2023-06-15T00:00:00Z"},"amount":{"type":"number","description":"Price the property sold for, in whole pounds.","example":450000},"ppdCategory":{"type":"string","enum":["A","B"],"description":"Which kind of transfer the price register recorded. `A` is a standard market sale. `B` is an additional transfer, such as a repossession, a portfolio sale, a right-to-buy purchase or a compulsory purchase, and typically sells below market value.","example":"A"},"newBuild":{"type":"boolean","description":"True when the price register recorded the sale as a new build.","example":false},"tenure":{"type":"string","description":"Tenure recorded against the sale.","example":"freehold"},"nation":{"type":"string","enum":["ENG","WAL","SCO","NIR"],"description":"UK nation the sold property is in.","example":"ENG"}}},"TenureData":{"type":"object","properties":{"type":{"type":["string","null"],"enum":["freehold","leasehold","unknown",null],"description":"How the property is held.","example":"freehold"}}},"CouncilTaxData":{"type":"object","properties":{"taxBand":{"type":["string","null"],"enum":["A","B","C","D","E","F","G","H","I",null],"description":"Valuation band the property is assessed in for council tax.","example":"D"},"currentAnnualAmount":{"type":["number","null"],"description":"Charge for the current tax year, in pence.","example":180000},"councilId":{"type":["string","null"],"description":"Identifier of the council that bills this property.","example":"E09000033"},"status":{"type":["string","null"],"description":"Status the council holds against this council tax record.","example":"active"},"currentTaxYear":{"type":["string","null"],"description":"Tax year the current charge applies to.","example":"2024-25"},"isEstimated":{"type":"boolean","description":"True when the amount is an estimate rather than a charge taken from the council.","example":false},"taxBandDetails":{"type":"array","items":{"$ref":"#/components/schemas/CouncilTaxBandDetails"},"description":"The band and charge recorded for each period, including periods that have ended."}}},"CouncilTaxBandDetails":{"type":"object","properties":{"id":{"type":["number","null"],"description":"Identifier of this council tax record.","example":1},"annualAmount":{"type":["number","null"],"description":"Charge for the whole tax year, in pence.","example":180000},"effectiveFrom":{"type":["string","null"],"description":"When this band and amount took effect, as an ISO 8601 date.","example":"2023-04-01"},"effectiveTo":{"type":["string","null"],"description":"When this band and amount stopped applying, as an ISO 8601 date. Null while it still applies.","example":null},"taxYear":{"type":["string","null"],"description":"Tax year the charge applies to.","example":"2023-24"}}},"PropertyTags":{"type":"object","properties":{"newBuildScheme":{"type":"boolean","description":"True when the property is part of a new-build scheme.","example":false},"chainFree":{"type":"boolean","description":"True when a live sale listing states there is no onward chain.","example":true},"auction":{"type":"boolean","description":"True when a live sale listing uses auction language, such as a guide price or bidding.","example":false},"sharedOwnership":{"type":"boolean","description":"True when the property is offered on a shared-ownership basis.","example":false},"retirement":{"type":"boolean","description":"True when a live sale listing describes the property as retirement or age-restricted housing.","example":false},"cashBuyers":{"type":"boolean","description":"True when a live sale listing accepts cash buyers only.","example":false},"negativeEquity":{"type":"boolean","description":"Signals that the property may be in negative equity, derived from its recorded prices. Treat it as an indicator, not a statement of the owner's financial position.","example":false},"hmo":{"type":"boolean","description":"True when the property is classified as a house in multiple occupation.","example":false},"unmodernised":{"type":"boolean","description":"True when the property is flagged as unmodernised.","example":false},"slowToSell":{"type":"boolean","description":"True when a live sale listing has run for more than 180 days or has cut its price at least twice.","example":false},"quickSale":{"type":"boolean","description":"True when a live sale listing is marketed as a quick sale.","example":false},"agriculturalTie":{"type":"boolean","description":"True when occupation of the property is tied to agricultural work.","example":false},"studentAccommodation":{"type":"boolean","description":"True when the property is student halls or similar student housing.","example":false},"holidayLet":{"type":"boolean","description":"True when the property is classified as a holiday let or short-term let.","example":false}},"default":{"newBuildScheme":false,"chainFree":false,"auction":false,"sharedOwnership":false,"retirement":false,"cashBuyers":false,"negativeEquity":false,"hmo":false,"unmodernised":false,"slowToSell":false,"quickSale":false,"agriculturalTie":false,"studentAccommodation":false,"holidayLet":false}},"Listing":{"type":"object","properties":{"listingId":{"type":"string","description":"Identifier of this listing.","example":"lst-123abc"},"status":{"type":"string","enum":["live","unavailable","removed","sstc","under_offer","sold","reserved"],"description":"Where the listing currently stands.","example":"live"},"type":{"type":"string","enum":["sale","rent"],"description":"Whether the listing is a sale or a letting.","example":"sale"},"source":{"type":"object","properties":{"provider":{"type":"string","description":"Identifier of the provider that supplied the listing.","example":"provider-a"},"key":{"type":"string","description":"Identifier the provider uses for this listing.","example":"123456789"}},"description":"Where the listing came from. Returned only to callers holding the source-data permission, and left out of the response otherwise."},"removedDate":{"type":["string","null"],"format":"date-time","description":"When the listing was taken down, as an ISO 8601 timestamp. Null while it is still live.","example":null},"publishedDate":{"type":["string","null"],"format":"date-time","description":"When the listing was first published, as an ISO 8601 timestamp. Null when the source does not publish one.","example":"2024-01-01T00:00:00Z"},"features":{"type":"object","properties":{"parking":{"type":"boolean"},"garden":{"type":"boolean"},"garage":{"type":"boolean"},"balcony":{"type":"boolean"},"terrace":{"type":"boolean"},"patio":{"type":"boolean"},"conservatory":{"type":"boolean"},"ensuite":{"type":"boolean"},"fireplace":{"type":"boolean"},"furnished":{"type":"boolean"},"unfurnished":{"type":"boolean"},"partFurnished":{"type":"boolean"},"newBuild":{"type":"boolean"},"chainFree":{"type":"boolean"},"groundFloor":{"type":"boolean"},"topFloor":{"type":"boolean"},"lift":{"type":"boolean"},"alarm":{"type":"boolean"},"cctv":{"type":"boolean"},"doubleGlazing":{"type":"boolean"},"centralHeating":{"type":"boolean"}},"additionalProperties":{},"description":"Features the listing advertises.","example":{"parking":true,"garden":true}},"observedFeatures":{"type":["object","null"],"properties":{"spaces":{"type":"object","properties":{"interior":{"$ref":"#/components/schemas/ObservedFeature"},"exterior":{"$ref":"#/components/schemas/ObservedFeature"},"outdoor_space":{"$ref":"#/components/schemas/ObservedFeature"},"communal":{"$ref":"#/components/schemas/ObservedFeature"},"non_property":{"$ref":"#/components/schemas/ObservedFeature"},"interior.kitchen":{"$ref":"#/components/schemas/ObservedFeature"},"interior.bathroom":{"$ref":"#/components/schemas/ObservedFeature"},"interior.bathroom.ensuite":{"$ref":"#/components/schemas/ObservedFeature"},"interior.bathroom.shower_room":{"$ref":"#/components/schemas/ObservedFeature"},"interior.bathroom.cloakroom":{"$ref":"#/components/schemas/ObservedFeature"},"interior.bedroom":{"$ref":"#/components/schemas/ObservedFeature"},"interior.living_room":{"$ref":"#/components/schemas/ObservedFeature"},"interior.dining_room":{"$ref":"#/components/schemas/ObservedFeature"},"interior.kitchen_diner":{"$ref":"#/components/schemas/ObservedFeature"},"interior.kitchen_living":{"$ref":"#/components/schemas/ObservedFeature"},"interior.hallway":{"$ref":"#/components/schemas/ObservedFeature"},"interior.landing":{"$ref":"#/components/schemas/ObservedFeature"},"interior.stairs":{"$ref":"#/components/schemas/ObservedFeature"},"interior.utility_room":{"$ref":"#/components/schemas/ObservedFeature"},"interior.study":{"$ref":"#/components/schemas/ObservedFeature"},"interior.conservatory":{"$ref":"#/components/schemas/ObservedFeature"},"interior.porch":{"$ref":"#/components/schemas/ObservedFeature"},"interior.basement":{"$ref":"#/components/schemas/ObservedFeature"},"interior.attic":{"$ref":"#/components/schemas/ObservedFeature"},"interior.dressing_room":{"$ref":"#/components/schemas/ObservedFeature"},"interior.storage":{"$ref":"#/components/schemas/ObservedFeature"},"interior.garage_interior":{"$ref":"#/components/schemas/ObservedFeature"},"interior.gym":{"$ref":"#/components/schemas/ObservedFeature"},"interior.games_room":{"$ref":"#/components/schemas/ObservedFeature"},"interior.library":{"$ref":"#/components/schemas/ObservedFeature"},"interior.wine_cellar":{"$ref":"#/components/schemas/ObservedFeature"},"interior.workshop":{"$ref":"#/components/schemas/ObservedFeature"},"interior.sauna":{"$ref":"#/components/schemas/ObservedFeature"},"interior.pool_room":{"$ref":"#/components/schemas/ObservedFeature"},"exterior.front_elevation":{"$ref":"#/components/schemas/ObservedFeature"},"exterior.rear_elevation":{"$ref":"#/components/schemas/ObservedFeature"},"exterior.aerial":{"$ref":"#/components/schemas/ObservedFeature"},"exterior.street":{"$ref":"#/components/schemas/ObservedFeature"},"outdoor_space.garden":{"$ref":"#/components/schemas/ObservedFeature"},"outdoor_space.patio":{"$ref":"#/components/schemas/ObservedFeature"},"outdoor_space.terrace":{"$ref":"#/components/schemas/ObservedFeature"},"outdoor_space.balcony":{"$ref":"#/components/schemas/ObservedFeature"},"outdoor_space.driveway":{"$ref":"#/components/schemas/ObservedFeature"},"outdoor_space.pool":{"$ref":"#/components/schemas/ObservedFeature"},"outdoor_space.outbuilding":{"$ref":"#/components/schemas/ObservedFeature"},"communal.lobby":{"$ref":"#/components/schemas/ObservedFeature"},"communal.corridor":{"$ref":"#/components/schemas/ObservedFeature"},"communal.garden":{"$ref":"#/components/schemas/ObservedFeature"}},"description":"Spaces the photographs show, keyed by scene key, each with the evidence behind it. A key is absent when no photograph supports it, which is not the same as the property lacking that space.","example":{"outdoor_space.garden":{"present":true,"confidence":0.94,"imageCount":3}}},"condition":{"type":["object","null"],"properties":{"value":{"$ref":"#/components/schemas/ImageCondition"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence in that assessment, from 0 to 1."}},"description":"The state of repair across the photographs as a whole. Null when too few photographs carry an assessment to summarise one."},"presentation":{"type":"object","properties":{"watermark_present":{"$ref":"#/components/schemas/ObservedFeature"},"virtually_staged":{"$ref":"#/components/schemas/ObservedFeature"},"empty_room":{"$ref":"#/components/schemas/ObservedFeature"},"furnished":{"$ref":"#/components/schemas/ObservedFeature"}},"description":"How the photographs present the property, keyed by quality key. `virtually_staged` is worth reading before treating condition as evidence, because digitally added furniture changes how a room reads."},"imagesAnalysed":{"type":"integer","minimum":0,"description":"How many of the listing's images these values were drawn from.","example":24},"taxonomyVersion":{"type":"string","description":"Release of the label vocabulary these values were produced against.","example":"1.0.0-draft"}},"description":"What the listing's photographs show, as distinct from what its text advertises. Null until the gallery has been analysed."},"priceChange":{"type":"array","items":{"$ref":"#/components/schemas/ListingPriceChange"},"description":"Every price this listing has been advertised at, starting with the first."},"description":{"type":["string","null"],"description":"The listing's own description of the property.","example":"Beautiful 3 bedroom house..."},"floorPlanImages":{"type":"array","items":{"$ref":"#/components/schemas/ListingImage"},"description":"Floor plans published with the listing."},"images":{"type":"array","items":{"$ref":"#/components/schemas/ListingImage"},"description":"Photographs published with the listing."},"seller":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Name of the agent or seller marketing the property.","example":"Example Estate Agents"},"PAID":{"type":["string","null"],"description":"The agent's Property Agent Identifier (PAID).","example":"12345"}},"description":"Who is marketing the property."},"pricing":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"Currency the prices are quoted in, as an ISO 4217 code.","example":"GBP"},"estimated":{"type":["number","null"],"description":"Estimated value of the property, in whole pounds.","example":500000},"price":{"type":["number","null"],"description":"Price the listing advertises, in whole pounds.","example":190000}},"description":"What the listing asks for the property."}}},"ObservedFeature":{"type":"object","properties":{"present":{"type":"boolean","description":"Whether the photographs support this feature at the published confidence.","example":true},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"Confidence of the strongest supporting image, from 0 to 1.","example":0.94},"imageCount":{"type":"integer","minimum":0,"description":"How many photographs support the feature. This counts images, not rooms: three photographs of a bathroom do not mean three bathrooms.","example":3}}},"ImageCondition":{"type":"string","enum":["move_in_ready","cosmetically_dated","renovation_needed","derelict"],"description":"The state of repair the photographs suggest."},"ListingPriceChange":{"type":"object","properties":{"direction":{"type":"string","enum":["up","down","initial"],"description":"Whether the price rose or fell. `initial` marks the first price recorded, which has no change.","example":"down"},"date":{"type":["string","null"],"format":"date-time","description":"When the price changed, as an ISO 8601 timestamp.","example":"2024-01-15T00:00:00Z"},"percent":{"type":["number","null"],"description":"Change from the previous price as a percentage, negative for a reduction.","example":-5.2},"amount":{"type":["number","null"],"description":"Change from the previous price in whole pounds, negative for a reduction.","example":-10000},"price":{"type":["number","null"],"description":"The price after this change, in whole pounds.","example":190000}}},"ListingImage":{"type":"object","properties":{"url":{"type":["string","null"],"format":"uri","description":"URL of the full-size image.","example":"https://example.com/image.jpg"},"thumbnailUrl":{"type":["string","null"],"format":"uri","description":"URL of a ready-made 640×480 WebP thumbnail of the same image.","example":"https://hot-cdn.vepler.com/listings/abc123/def456/640w.webp"},"labels":{"type":["object","null"],"properties":{"documentClass":{"$ref":"#/components/schemas/ImageDocumentClass"},"documentClassConfidence":{"type":"number","minimum":0,"maximum":1,"description":"How strongly the image supports its document class, from 0 to 1.","example":0.99},"scene":{"type":"array","items":{"$ref":"#/components/schemas/ImageSceneLabel"},"description":"The spaces the photograph shows, most specific first, each with its own confidence. Keys are hierarchical, so `interior.bathroom.ensuite` also implies `interior.bathroom` and `interior`. Empty for anything that is not a photograph."},"condition":{"allOf":[{"$ref":"#/components/schemas/ImageCondition"},{"type":["string","null"],"description":"The state of repair the photograph suggests. Null when no assessment is published for this image.","example":"move_in_ready"}]},"presentation":{"type":"array","items":{"$ref":"#/components/schemas/ImageQuality"},"description":"How the photograph presents the property rather than what it shows. `virtually_staged` marks furniture added digitally, and `empty_room` marks an unfurnished space.","example":["furnished"]},"taxonomyVersion":{"type":"string","description":"Release of the label vocabulary these values were produced against.","example":"1.0.0-draft"}},"description":"What this image is and what it shows. Null until the image has been analysed."}}},"ImageDocumentClass":{"type":"string","enum":["photo","floor_plan","epc_chart","brochure_page","site_plan","map","agent_branding","other"],"description":"What the image is, rather than what it shows. A `photo` is a photograph of the property or its surroundings; the other values are documents published alongside the photographs.","example":"photo"},"ImageSceneLabel":{"type":"object","properties":{"key":{"$ref":"#/components/schemas/ImageScene"},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"How strongly the image supports this key, from 0 to 1.","example":0.97}}},"ImageScene":{"type":"string","enum":["interior","exterior","outdoor_space","communal","non_property","interior.kitchen","interior.bathroom","interior.bathroom.ensuite","interior.bathroom.shower_room","interior.bathroom.cloakroom","interior.bedroom","interior.living_room","interior.dining_room","interior.kitchen_diner","interior.kitchen_living","interior.hallway","interior.landing","interior.stairs","interior.utility_room","interior.study","interior.conservatory","interior.porch","interior.basement","interior.attic","interior.dressing_room","interior.storage","interior.garage_interior","interior.gym","interior.games_room","interior.library","interior.wine_cellar","interior.workshop","interior.sauna","interior.pool_room","exterior.front_elevation","exterior.rear_elevation","exterior.aerial","exterior.street","outdoor_space.garden","outdoor_space.patio","outdoor_space.terrace","outdoor_space.balcony","outdoor_space.driveway","outdoor_space.pool","outdoor_space.outbuilding","communal.lobby","communal.corridor","communal.garden"],"description":"The space shown, as a hierarchical key such as `interior.bathroom.ensuite`.","example":"interior.kitchen"},"ImageQuality":{"type":"string","enum":["watermark_present","virtually_staged","empty_room","furnished"]},"PriceChange":{"type":"object","properties":{"direction":{"type":"string","enum":["up","down","initial"],"description":"Whether the price rose or fell. `initial` marks the first price recorded, which has no change.","example":"down"},"date":{"type":["string","null"],"format":"date-time","description":"When the price changed, as an ISO 8601 timestamp.","example":"2024-01-15T00:00:00Z"},"percent":{"type":["number","null"],"description":"Change from the previous price as a percentage, negative for a reduction.","example":-5.2},"amount":{"type":["number","null"],"description":"Change from the previous price in whole pounds, negative for a reduction.","example":-10000},"price":{"type":["number","null"],"description":"The price after this change, in whole pounds.","example":190000}}},"Lease":{"type":"object","properties":{"leaseType":{"type":["string","null"],"description":"Kind of lease recorded.","example":"Leasehold"},"dateOfLease":{"type":["string","null"],"description":"When the lease was granted, as an ISO 8601 date. Null when the register does not give a date.","example":"1985-06-15"},"expiryDate":{"type":["string","null"],"description":"When the lease expires, as an ISO 8601 date. Null when the register does not give a date.","example":"2085-06-14"},"alienationClause":{"type":"boolean","description":"True when the lease carries an alienation clause restricting assignment or subletting.","example":false}}},"TenancyData":{"type":"object","properties":{"isTenanted":{"type":["boolean","null"],"description":"True when the property appears to be let to a tenant.","example":true},"confidenceScore":{"type":"number","minimum":0,"maximum":100,"description":"How much weight to put on `isTenanted`, from 0 to 100.","example":75}}},"ChargeHistory":{"type":["object","null"],"properties":{"current":{"type":["number","null"],"description":"Best current estimate of the annual charge, in whole pounds.","example":3418},"currency":{"type":["string","null"],"description":"Currency the charges are quoted in, as an ISO 4217 code.","example":"GBP"},"entries":{"type":"array","items":{"$ref":"#/components/schemas/ChargeEntry"},"description":"Every charge recorded for the property, newest last."},"lastUpdated":{"type":"string","format":"date-time","description":"When this charge history was last refreshed, as an ISO 8601 timestamp.","example":"2024-01-15T10:30:00Z"},"confidence":{"type":"number","minimum":0,"maximum":100,"description":"How much weight to put on `current`, from 0 to 100.","example":90}}},"ChargeEntry":{"type":"object","properties":{"value":{"type":"number","description":"Charge recorded on this entry, in whole pounds.","example":3418},"currency":{"type":["string","null"],"description":"Currency the charge is quoted in, as an ISO 4217 code.","example":"GBP"},"recordedDate":{"type":"string","format":"date-time","description":"When this charge was recorded, as an ISO 8601 timestamp.","example":"2024-01-01T00:00:00Z"},"sourceId":{"type":"string","description":"Identifier of the record this charge was read from.","example":"listing-123"},"sourceProvider":{"type":"string","description":"Provider that supplied this charge.","example":"provider-a"},"confidence":{"type":"number","minimum":0,"maximum":100,"description":"How much weight to put on this entry, from 0 to 100. It rises when other sources and recent entries agree with the figure, and falls as the entry ages.","example":85},"isOutlier":{"type":"boolean","description":"True when this figure sits well outside the rest of the property's recorded charges.","example":false}}},"RefurbishmentData":{"type":"object","properties":{"refurbSize":{"type":["string","null"],"enum":["small","medium","large",null],"description":"How much refurbishment the property appears to need.","example":"medium"}},"default":{"refurbSize":null}},"PropertyAssessments":{"type":"object","properties":{"heritage":{"$ref":"#/components/schemas/HeritageAssessments"},"conservation":{"$ref":"#/components/schemas/ConservationAssessments"}},"description":"Heritage and conservation designations assessed at this property's location. A product that is absent was not assessed."},"HeritageAssessments":{"type":"object","properties":{"designations":{"type":"object","additionalProperties":{"oneOf":[{"type":"object","properties":{"inside":{"type":"boolean","enum":[true],"description":"Always `true` on this branch: the location falls inside a zone."},"zone":{"$ref":"#/components/schemas/HeritageZone"}},"required":["inside","zone"],"description":"The location is inside a zone of this kind, which is given in full."},{"type":"object","properties":{"inside":{"type":"boolean","enum":[false],"description":"Always `false` on this branch: the location falls outside every zone of this kind."},"nearest":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Name the custodian gives the designation, such as 'City of Bath'."},"reference":{"type":"string","description":"The custodian's own register reference for the designation."},"designatedDate":{"type":["string","null"],"description":"When the designation took effect, as an ISO 8601 date. Read it together with `datePrecision`."},"areaHectares":{"type":["number","null"],"description":"Area the designation covers, in hectares."},"datePrecision":{"type":"string","enum":["day","month","year","none"],"description":"How much of `designatedDate` the source actually specified, so a year-only date is not read as exact."},"monumentClass":{"type":"string","description":"What kind of monument this mainly is, for example 'defensive' or 'roman'. Carried by scheduled monuments; English monuments resolve to 'unassigned' because the source carries no typology."},"monumentClasses":{"type":"array","items":{"type":"string"},"description":"Every kind of monument this one counts as, where the source records more than one."},"unescoInscriptionType":{"type":"string","description":"What the site was inscribed for, either 'cultural', 'natural' or 'mixed'. Carried by world heritage sites only."},"unescoInscriptionCriteria":{"type":"array","items":{"type":"string"},"description":"The UNESCO criteria, numbered i to x, that the site was inscribed under."},"zoneSubtype":{"type":"string","description":"Which part of a world heritage site this is, either 'core_area' or the surrounding 'buffer_zone'."},"battleType":{"type":"string","description":"What kind of engagement the battlefield commemorates, for example 'land_battle', 'siege' or 'naval'. Carried by registered battlefields only."},"wreckProtectionType":{"type":"string","description":"Which regime protects the wreck, for example 'protected_wreck_site', 'historic_marine_protected_area' or 'protected_historic_wreck'."},"listedGrade":{"type":"string","description":"Grade the building or park is listed at, for example 'grade_i', 'grade_ii_star' or 'category_a'. Grades are specific to each UK nation and do not map onto one another: Scotland's categories A, B and C are not the equivalents of grades I, II* and II. Absent where nothing is graded."},"distanceM":{"type":"number","minimum":0,"description":"Distance to the feature, in metres.","example":42.3},"bearingDeg":{"type":"number","minimum":0,"maximum":360,"description":"Direction to the feature, in degrees clockwise from true north. Between 0 and 360.","example":137.5}},"required":["distanceM"],"description":"The closest zone of this kind and how far away it is. Not present in every response."}},"required":["inside"],"description":"The location is outside every zone of this kind, optionally with the closest one."}],"description":"Whether the location falls inside a zone of this kind. Branch on `inside`: when it is `false`, the closest zone may be given instead."},"description":"Heritage designations found at this location, keyed by designation type such as `listed_building` or `scheduled_monument`. A type appears only when the property is inside one or has one within 500 metres; a type that is absent was checked and found clear."},"provenance":{"$ref":"#/components/schemas/Provenance"}}},"HeritageZone":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Name the custodian gives the designation, such as 'City of Bath'."},"reference":{"type":"string","description":"The custodian's own register reference for the designation."},"designatedDate":{"type":["string","null"],"description":"When the designation took effect, as an ISO 8601 date. Read it together with `datePrecision`."},"areaHectares":{"type":["number","null"],"description":"Area the designation covers, in hectares."},"datePrecision":{"type":"string","enum":["day","month","year","none"],"description":"How much of `designatedDate` the source actually specified, so a year-only date is not read as exact."},"monumentClass":{"type":"string","description":"What kind of monument this mainly is, for example 'defensive' or 'roman'. Carried by scheduled monuments; English monuments resolve to 'unassigned' because the source carries no typology."},"monumentClasses":{"type":"array","items":{"type":"string"},"description":"Every kind of monument this one counts as, where the source records more than one."},"unescoInscriptionType":{"type":"string","description":"What the site was inscribed for, either 'cultural', 'natural' or 'mixed'. Carried by world heritage sites only."},"unescoInscriptionCriteria":{"type":"array","items":{"type":"string"},"description":"The UNESCO criteria, numbered i to x, that the site was inscribed under."},"zoneSubtype":{"type":"string","description":"Which part of a world heritage site this is, either 'core_area' or the surrounding 'buffer_zone'."},"battleType":{"type":"string","description":"What kind of engagement the battlefield commemorates, for example 'land_battle', 'siege' or 'naval'. Carried by registered battlefields only."},"wreckProtectionType":{"type":"string","description":"Which regime protects the wreck, for example 'protected_wreck_site', 'historic_marine_protected_area' or 'protected_historic_wreck'."},"listedGrade":{"type":"string","description":"Grade the building or park is listed at, for example 'grade_i', 'grade_ii_star' or 'category_a'. Grades are specific to each UK nation and do not map onto one another: Scotland's categories A, B and C are not the equivalents of grades I, II* and II. Absent where nothing is graded."}}},"Provenance":{"type":"object","properties":{"snapshotId":{"type":"string","minLength":1,"description":"Identifier of the published snapshot this response was served from.","example":"aq-20260517-04"},"productVersion":{"type":"string","minLength":1,"description":"Semantic version of the product that computed this response.","example":"1.1.0"},"scoringContractVersion":{"type":"string","description":"Version of the shared scoring contract behind this response's score and band. Compare it across two responses to confirm both scores came from the same scoring table.","example":"score-1.0.0"},"publishedAt":{"type":"string","description":"When this snapshot was published, as an ISO 8601 timestamp.","example":"2026-05-17T12:00:00Z"},"asOf":{"type":"string","description":"The moment the data is current as of, as an ISO 8601 timestamp. It usually falls between a source's `releaseDate` and `publishedAt`.","example":"2026-05-01T00:00:00Z"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/DataSourceRef"},"minItems":1,"description":"Every upstream source that contributed to this response. At least one is always present."}},"description":"Where this response's data came from, when it was published, and what it is current as of."},"DataSourceRef":{"type":"object","properties":{"id":{"type":"string","minLength":1,"description":"Stable machine code identifying the source, safe to match on.","example":"ea_aqma_register"},"name":{"type":"string","minLength":1,"description":"Full name of the source dataset.","example":"Environment Agency Air Quality Management Areas register"},"custodian":{"type":"string","description":"Organisation that publishes and maintains the source.","example":"Environment Agency"},"jurisdiction":{"type":"array","items":{"type":"string"},"description":"Territories the source covers, as ISO 3166-1 alpha-2 codes, each optionally carrying a subdivision such as `GB-ENG`.","example":["GB-ENG"]},"url":{"type":"string","format":"uri","description":"Canonical address at which the custodian publishes the source.","example":"https://environment.data.gov.uk/dataset/aqma"},"releaseDate":{"type":"string","description":"When the custodian published this version of the source, as an ISO 8601 date.","example":"2026-04-30"},"fetchedAt":{"type":"string","description":"When this version of the source was ingested, as an ISO 8601 timestamp.","example":"2026-05-01T08:14:22Z"},"sha256":{"type":"string","description":"SHA-256 hash of the raw file as fetched, so the exact input can be verified.","example":"9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"},"licence":{"type":"string","description":"Identifier of the licence this source is published under, for example 'OGL_v3.0', 'INSPIRE', 'CC_BY_4.0' or 'proprietary'.","example":"OGL_v3.0"},"version":{"type":"string","description":"Version the custodian assigns to this release, where they publish one.","example":"2025-Q4"}},"description":"One upstream source that contributed to this response."},"ConservationAssessments":{"type":"object","properties":{"designations":{"type":"object","additionalProperties":{"oneOf":[{"type":"object","properties":{"inside":{"type":"boolean","enum":[true],"description":"Always `true` on this branch: the location falls inside a zone."},"zone":{"$ref":"#/components/schemas/ConservationZone"}},"required":["inside","zone"],"description":"The location is inside a zone of this kind, which is given in full."},{"type":"object","properties":{"inside":{"type":"boolean","enum":[false],"description":"Always `false` on this branch: the location falls outside every zone of this kind."},"nearest":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Name the custodian gives the designation, such as 'City of Bath'."},"reference":{"type":"string","description":"The custodian's own register reference for the designation."},"designatedDate":{"type":["string","null"],"description":"When the designation took effect, as an ISO 8601 date. Read it together with `datePrecision`."},"areaHectares":{"type":["number","null"],"description":"Area the designation covers, in hectares."},"datePrecision":{"type":"string","enum":["day","month","year","none"],"description":"How much of `designatedDate` the source actually specified, so a year-only date is not read as exact."},"lifecycle":{"type":"string","description":"Where the designation stands in its lifecycle, for example 'designated', 'candidate' or 'withdrawn'. Branch on this before treating a designation as in force."},"woodlandClass":{"type":"string","description":"How old and how natural the woodland is, for example 'ancient_semi_natural', 'plantation_on_ancient' or 'long_established'. Carried by the woodland designation types only."},"landscapeClass":{"type":"string","description":"Which landscape designation this is, either 'aonb' or 'national_scenic_area'. Carried by the landscape designation type only."},"habitatCode":{"type":"string","description":"The habitat's classification code, as the custodian publishes it against the UK Biodiversity Action Plan or EUNIS scheme. Carried by the priority habitat type only."},"distanceM":{"type":"number","minimum":0,"description":"Distance to the feature, in metres.","example":42.3},"bearingDeg":{"type":"number","minimum":0,"maximum":360,"description":"Direction to the feature, in degrees clockwise from true north. Between 0 and 360.","example":137.5}},"required":["distanceM"],"description":"The closest zone of this kind and how far away it is. Not present in every response."}},"required":["inside"],"description":"The location is outside every zone of this kind, optionally with the closest one."}],"description":"Whether the location falls inside a zone of this kind. Branch on `inside`: when it is `false`, the closest zone may be given instead."},"description":"Nature conservation designations found at this location, keyed by designation type such as `ancient_woodland` or `site_of_special_scientific_interest`. A type appears only when the property is inside one or has one within 500 metres; a type that is absent was checked and found clear."},"provenance":{"$ref":"#/components/schemas/Provenance"}}},"ConservationZone":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Name the custodian gives the designation, such as 'City of Bath'."},"reference":{"type":"string","description":"The custodian's own register reference for the designation."},"designatedDate":{"type":["string","null"],"description":"When the designation took effect, as an ISO 8601 date. Read it together with `datePrecision`."},"areaHectares":{"type":["number","null"],"description":"Area the designation covers, in hectares."},"datePrecision":{"type":"string","enum":["day","month","year","none"],"description":"How much of `designatedDate` the source actually specified, so a year-only date is not read as exact."},"lifecycle":{"type":"string","description":"Where the designation stands in its lifecycle, for example 'designated', 'candidate' or 'withdrawn'. Branch on this before treating a designation as in force."},"woodlandClass":{"type":"string","description":"How old and how natural the woodland is, for example 'ancient_semi_natural', 'plantation_on_ancient' or 'long_established'. Carried by the woodland designation types only."},"landscapeClass":{"type":"string","description":"Which landscape designation this is, either 'aonb' or 'national_scenic_area'. Carried by the landscape designation type only."},"habitatCode":{"type":"string","description":"The habitat's classification code, as the custodian publishes it against the UK Biodiversity Action Plan or EUNIS scheme. Carried by the priority habitat type only."}}},"PropertyMonitoringReceipt":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["monitoring"]},"registered":{"type":"integer","description":"Properties this request started monitoring, out of those it returned."},"monitored":{"type":"integer","description":"Properties from this request now monitored, including those already monitored before it. Their term is extended to the requested length rather than being registered twice."}},"required":["status","registered","monitored"],"description":"Monitoring is in place for the returned properties. Registration happens with the request."},{"type":"object","properties":{"status":{"type":"string","enum":["queued"]},"jobId":{"type":["string","null"],"description":"Identifier of the background registration task. Quote it in support enquiries."},"matchedCount":{"type":"integer","description":"Number of properties the query matched, which is the set submitted for registration."}},"required":["status","jobId","matchedCount"],"description":"The registration was accepted: every property the query matched is being registered in the background. Properties your account already monitors have their term extended."},{"type":"object","properties":{"status":{"type":"string","enum":["refused"]},"reason":{"type":"string","enum":["no_tenant"]},"message":{"type":"string","description":"Why the registration was refused and what to do instead."}},"required":["status","reason","message"],"description":"Refused because the request carried no account identity, so there is nothing to register the monitoring against. System callers should use the admin registration procedure instead."},{"type":"object","properties":{"status":{"type":"string","enum":["refused"]},"reason":{"type":"string","enum":["no_active_grant"]},"message":{"type":"string","description":"Why the registration was refused and what to do instead."}},"required":["status","reason","message"],"description":"Refused because the account holds no active property_monitoring licence grant. Record the agreement and create the grant first, then re-send the request."},{"type":"object","properties":{"status":{"type":"string","enum":["refused"]},"reason":{"type":"string","enum":["match_too_large"]},"matchedCount":{"type":"integer","description":"Number of properties the query matched."},"maxProperties":{"type":"integer","description":"The `monitor.maxProperties` guard the match exceeded."},"message":{"type":"string","description":"Why the registration was refused and what to do instead."}},"required":["status","reason","matchedCount","maxProperties","message"],"description":"Refused because the query matched more properties than `monitor.maxProperties` allows. Nothing was registered. Narrow the query, or raise the guard as far as 10,000, and re-send."},{"type":"object","properties":{"status":{"type":"string","enum":["failed"]},"error":{"type":"string","description":"What went wrong."}},"required":["status","error"],"description":"The background registration task could not be scheduled. Nothing was registered and nothing will be billed, so re-send the same request to try again."}],"description":"What happened to the monitoring registration. Present only when the request included `monitor`, and the property results are the same whatever its outcome."},"PropertyQueryRequest":{"type":"object","properties":{"area":{"type":"array","items":{"$ref":"#/components/schemas/PropertyAreaFilter"},"description":"Where to search. A property inside any one of these areas is returned.","example":[{"type":"postcode","value":"SW1A1AA"}]},"query":{"type":"array","items":{"$ref":"#/components/schemas/PropertyQueryOperator"},"description":"Filters to apply within the area. A property matching any one entry is returned."},"sort":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["marketStatus.lastOTM","marketStatus.lastOTMRent","marketStatus.backOTM","marketStatus.backOTMRent","marketStatus.sstcDate","marketStatus.underOfferDate","marketStatus.reservedDate","pricing.currentSale","pricing.currentRent","pricing.predictedPrice","marketStatus.pricePerSqft","marketStatus.pricePerSqm","roomDetails.beds","roomDetails.baths","build.totalFloorArea","build.plotSize","build.constructionAge.midYear","_score","_doc"],"description":"Attribute to sort by."},"order":{"type":"string","enum":["asc","desc"],"description":"Whether to sort ascending or descending."},"missing":{"type":"string","enum":["_first","_last"],"description":"Where properties with no value for this attribute go: first or last."},"mode":{"type":"string","enum":["min","max","sum","avg","median"],"description":"Which value to sort on where the attribute holds several, such as the lowest or the mean."}},"required":["field","order"]},"maxItems":3,"description":"How to order the results. Up to three attributes, applied in the order given.","example":[{"field":"pricing.currentSale","order":"desc"},{"field":"roomDetails.beds","order":"desc"}]},"limit":{"type":"integer","minimum":1,"maximum":10000,"default":25,"description":"Maximum number of properties to return in one page. Defaults to 25. Minimum 1, maximum 10,000.","example":25},"offset":{"type":"integer","minimum":0,"maximum":9999,"default":0,"description":"Number of results to skip before the first one returned. Defaults to 0. `limit` plus `offset` may not exceed 10,000: a request for a deeper page is rejected with a 400 rather than quietly served a different page.","example":0},"attributes":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Attributes to return, as dotted paths in an array or a single comma-separated string. Only these are returned, plus `locationId`, which is always included, so requesting narrowly keeps responses small. Omit it to receive the default set. `GET /v1/property/attributes` lists every path and what it costs.","example":"address,pricing,roomDetails,epc"},"track":{"type":"boolean","default":false,"description":"Has no effect on the response or on how the request is billed."},"monitor":{"type":"object","properties":{"months":{"type":"integer","exclusiveMinimum":0,"description":"How many calendar months to monitor for, counted from when the registration is processed."},"maxProperties":{"type":"integer","minimum":1,"maximum":10000,"default":10000,"description":"Refuse the registration when the query matches more properties than this. Defaults to 10,000, which is also the maximum. It stops a wider filter than intended from registering, and billing for, far more properties than expected. When it refuses, the receipt reports the matched count and the query results are still returned."}},"required":["months"],"description":"Register every property this query matches for monitoring, which is the whole match set rather than the page returned, billed monthly per property. Registration runs in the background and the response carries a `monitoring` receipt describing what happened. It needs an active property_monitoring licence grant. Properties your account already monitors are skipped, so re-sending the same query is safe."},"countryCode":{"type":"string","description":"Sovereign state the request is aimed at, as an ISO 3166-1 alpha-2 code such as `GB`. Taken as a hint only: it does not filter the results, and the data covers Great Britain."}},"required":["area","query"]},"PropertyAreaFilter":{"anyOf":[{"$ref":"#/components/schemas/PropertyLocationIdAreaFilter"},{"$ref":"#/components/schemas/PropertyPostcodeAreaFilter"},{"$ref":"#/components/schemas/PropertyOutcodeAreaFilter"},{"$ref":"#/components/schemas/PropertyPointAreaFilter"},{"$ref":"#/components/schemas/PropertyPolygonAreaFilter"},{"$ref":"#/components/schemas/PropertyMultiPolygonAreaFilter"}]},"PropertyLocationIdAreaFilter":{"type":"object","properties":{"locationId":{"type":"string","minLength":2,"maxLength":20,"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN).","example":"10002291456"}},"required":["locationId"]},"PropertyPostcodeAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["postcode"]},"value":{"type":"string","pattern":"^[A-Z]{1,2}[0-9][0-9A-Z]?(\\s?[0-9][A-Z]{2})?$","description":"A full UK postcode, or just its outward code (the first part, such as `SW1A`). The space is optional and case is not significant; the value is returned upper-cased.","example":"SW1"},"radius":{"type":"number","description":"Search radius in metres.","example":1000}},"required":["type","value"]},"PropertyOutcodeAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["outcode"]},"value":{"type":"string","minLength":2,"maxLength":4,"description":"The outward code to search, such as `SW1A`."}},"required":["type","value"]},"PropertyPointAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["point"]},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"Centre of the search: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]},"radius":{"type":"number","description":"Search radius around the point, in metres.","example":1000}},"required":["type","coordinates","radius"]},"PropertyPolygonAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"description":"Rings of the search polygon, each point longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order). The first ring is the boundary and any further rings are holes in it. Each ring needs at least three distinct points, and its first and last point must be identical so the ring closes.","example":[[[-0.1278,51.5074],[-0.128,51.508],[-0.1275,51.507],[-0.1278,51.5074]]]}},"required":["type","coordinates"]},"PropertyMultiPolygonAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["multipolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}},"description":"Several search polygons, each given as its own set of rings. Points are longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[[[[-0.1278,51.5074],[-0.128,51.508],[-0.1275,51.507],[-0.1278,51.5074]]]]}},"required":["type","coordinates"]},"PropertyQueryOperator":{"type":"object","properties":{"operator":{"type":"string","enum":["AND","OR"],"description":"How the conditions inside this entry combine: `AND` needs every condition to match, `OR` needs at least one."},"groups":{"type":"array","items":{"$ref":"#/components/schemas/PropertyQueryGroup"},"description":"Groups of conditions the operator applies to."}},"required":["operator","groups"]},"PropertyQueryGroup":{"type":"object","properties":{"conditions":{"type":"array","items":{"$ref":"#/components/schemas/PropertyQueryCondition"},"description":"Conditions to combine, using the `operator` on the entry that holds this group."}},"required":["conditions"]},"PropertyQueryCondition":{"type":"object","properties":{"field":{"type":"string","description":"Attribute to filter on, given as its dotted path, such as `roomDetails.beds`, `pricing.currentSale` or `tags.hmo`. Shorter aliases such as `beds`, `propertyType` and `saleListingStatus` resolve to the same attributes. `GET /v1/property/attributes` lists every accepted name in `filterFields`."},"comparator":{"type":"string","enum":["eq","ne","gt","gte","lt","lte","in","nin","contains","startswith","endswith"],"description":"How to compare the attribute with `value`. What a given attribute accepts depends on its `kind` in `GET /v1/property/attributes`: a `term` attribute takes `eq`, `ne`, `in` and `nin`, and a `range` attribute takes those plus `gt`, `gte`, `lt` and `lte`. A comparator the attribute does not accept is rejected with a 400."},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}],"description":"Value to compare the attribute against. `in` and `nin` take an array of values."}},"required":["field","comparator","value"]},"PropertyAggregateResponse":{"type":"object","properties":{"total":{"type":"number","description":"Number of properties the area and query matched.","example":1234},"areaKm2":{"type":"number","description":"Combined size of the requested areas, in square kilometres.","example":45.6},"aggregations":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/AggregationResult"},"description":"The results, keyed by the name given to each aggregation in the request.","example":{"price_stats":{"count":1234,"min":125000,"max":2500000,"avg":485000,"sum":598290000},"by_type":{"buckets":[{"key":"FLAT","doc_count":456},{"key":"TERRACED","doc_count":234}]}}}},"required":["total","areaKm2","aggregations"]},"AggregationResult":{"anyOf":[{"$ref":"#/components/schemas/ExtendedStatsAggregationResult"},{"$ref":"#/components/schemas/StatsAggregationResult"},{"$ref":"#/components/schemas/TermsAggregationResult"},{"$ref":"#/components/schemas/HistogramAggregationResult"},{"$ref":"#/components/schemas/PercentilesAggregationResult"},{"$ref":"#/components/schemas/SingleValueAggregationResult"},{"$ref":"#/components/schemas/NestedAggregationResult"}]},"ExtendedStatsAggregationResult":{"type":"object","properties":{"count":{"type":"number","description":"Number of matching records that have a value for this field."},"min":{"type":["number","null"],"description":"Smallest value found. Null when `count` is 0."},"max":{"type":["number","null"],"description":"Largest value found. Null when `count` is 0."},"avg":{"type":["number","null"],"description":"Mean of the values found. Null when `count` is 0."},"sum":{"type":["number","null"],"description":"Total of the values found. Null when `count` is 0."},"sum_of_squares":{"type":["number","null"],"description":"Total of the squared values. Null when `count` is 0."},"variance":{"type":["number","null"],"description":"Population variance. Null when `count` is 0."},"variance_population":{"type":["number","null"],"description":"Population variance. Null when `count` is 0."},"variance_sampling":{"type":["number","null"],"description":"Sample variance, using Bessel's correction. Null when `count` is below 2."},"std_deviation":{"type":["number","null"],"description":"Population standard deviation. Null when `count` is 0."},"std_deviation_population":{"type":["number","null"],"description":"Population standard deviation. Null when `count` is 0."},"std_deviation_sampling":{"type":["number","null"],"description":"Sample standard deviation. Null when `count` is below 2."},"std_deviation_bounds":{"type":["object","null"],"properties":{"upper":{"type":["number","null"]},"lower":{"type":["number","null"]},"upper_population":{"type":["number","null"]},"lower_population":{"type":["number","null"]},"upper_sampling":{"type":["number","null"]},"lower_sampling":{"type":["number","null"]}},"required":["upper","lower","upper_population","lower_population","upper_sampling","lower_sampling"],"description":"The mean plus and minus two standard deviations. Null when `count` is 0."}},"required":["count","min","max","avg","sum","sum_of_squares","variance","variance_population","variance_sampling","std_deviation","std_deviation_population","std_deviation_sampling","std_deviation_bounds"]},"StatsAggregationResult":{"type":"object","properties":{"count":{"type":"number","description":"Number of matching records that have a value for this field."},"min":{"type":["number","null"],"description":"Smallest value found. Null when `count` is 0."},"max":{"type":["number","null"],"description":"Largest value found. Null when `count` is 0."},"avg":{"type":["number","null"],"description":"Mean of the values found. Null when `count` is 0."},"sum":{"type":["number","null"],"description":"Total of the values found. Null when `count` is 0."}},"required":["count","min","max","avg","sum"],"example":{"count":28500000,"min":0.5,"max":2450000,"avg":312.8,"sum":8914800000}},"TermsAggregationResult":{"type":"object","properties":{"doc_count_error_upper_bound":{"type":"number","description":"Largest amount by which any single bucket count in this result could be understated. Present when the counts are approximate rather than exact."},"sum_other_doc_count":{"type":"number","description":"Combined count of the records that fell into buckets left out because `size` capped how many came back."},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/TermsBucket"},"description":"One bucket per distinct value, each with its count."}},"required":["buckets"]},"TermsBucket":{"type":"object","properties":{"key":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}],"description":"The distinct field value this bucket covers."},"doc_count":{"type":"number","description":"Number of matching records that carry this value."}},"required":["key","doc_count"],"additionalProperties":{},"example":{"key":"freehold","doc_count":21300000}},"HistogramAggregationResult":{"type":"object","properties":{"buckets":{"type":"array","items":{"$ref":"#/components/schemas/HistogramBucket"},"description":"The buckets, in ascending key order."}},"required":["buckets"]},"HistogramBucket":{"type":"object","properties":{"key":{"type":"number","description":"Lower bound of this bucket, inclusive. The bucket runs from `key` up to but not including the next."},"key_as_string":{"type":"string","description":"The bucket key rendered with the requested `format`, for example '2024-06'. Present on date buckets only."},"doc_count":{"type":"number","description":"Number of matching records that fall into this bucket."}},"required":["key","doc_count"],"additionalProperties":{},"example":{"key":0,"doc_count":5200000}},"PercentilesAggregationResult":{"type":"object","properties":{"values":{"type":"object","additionalProperties":{"type":["number","null"]},"description":"One entry per requested percentile, keyed by the percentile itself, so '25.0' holds the value at the 25th percentile. Each value is null when nothing matched."}},"required":["values"],"example":{"values":{"25.0":120.5,"50.0":312.8,"75.0":680.2,"90.0":1450,"99.0":8500}}},"SingleValueAggregationResult":{"type":"object","properties":{"value":{"type":["number","null"],"description":"The computed value. Null when nothing matched."}},"required":["value"],"example":{"value":312.8}},"NestedAggregationResult":{"type":"object","properties":{"doc_count":{"type":"number","description":"Number of nested entries the aggregation ran over, rather than the number of parent records."}},"additionalProperties":{}},"PropertyAggregateRequest":{"type":"object","properties":{"area":{"type":"array","items":{"$ref":"#/components/schemas/PropertyAreaFilter"},"minItems":1,"description":"Where to aggregate. At least one area is required, and they may cover 500 km² in total at most.","example":[{"type":"postcode","value":"SW1A1AA"}]},"query":{"type":"array","items":{"$ref":"#/components/schemas/PropertyQueryOperator"},"description":"Filters narrowing which properties are counted, in the same shape as `POST /v1/property/query`."},"aggregations":{"type":"array","items":{"$ref":"#/components/schemas/AggregationInput"},"minItems":1,"maxItems":10,"description":"What to calculate over the matching properties. Between 1 and 10 of them.","example":[{"name":"price_stats","type":"stats","field":"currentSaleListingPrice"},{"name":"by_type","type":"terms","field":"propertyType","size":10}]}},"required":["area","aggregations"]},"AggregationInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":50,"description":"Name for this aggregation. It is the key its result appears under in the response `aggregations` object, so it must be unique within the request. Between 1 and 50 characters.","example":"tenure_breakdown"},"type":{"type":"string","enum":["terms","range","histogram","date_histogram","stats","extended_stats","min","max","avg","sum","count","cardinality","percentiles"],"description":"How the matching records are aggregated. Each type takes its own parameters and returns its own result shape."},"field":{"type":"string","minLength":1,"description":"Field to aggregate over. Each dataset allows a fixed set of fields, and each of those supports only certain aggregation types; a field or type outside that set is rejected.","example":"areaSqm"},"size":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of buckets a grouping aggregation returns, between 1 and 100. The single-value metric types ignore it. For the map-tile grouping type it sets the tile precision rather than a bucket count. When omitted, the default depends on the dataset and the field.","example":10},"interval":{"type":"number","exclusiveMinimum":0,"description":"Width of each bucket for a `histogram` aggregation, in the units of the field. Must be greater than zero. Some datasets reject a `histogram` aggregation that omits it rather than applying a default.","example":100000},"calendarInterval":{"type":"string","description":"Calendar-aware bucket width for a date aggregation: 1m (minute), 1h (hour), 1d (day), 1w (week), 1M (month), 1q (quarter) or 1y (year). Mutually exclusive with `fixedInterval`, so supply one or the other, never both.","example":"1M"},"fixedInterval":{"type":"string","description":"Fixed-duration bucket width for a date aggregation, written as a number and a unit (ms, s, m, h, d), for example \"30m\", \"1h\" or \"7d\". Unlike `calendarInterval` it takes no account of daylight saving or of months having different lengths. Mutually exclusive with `calendarInterval`, so supply one or the other, never both.","example":"1h"},"ranges":{"type":"array","items":{"$ref":"#/components/schemas/RangeDefinition"},"description":"The ranges a `range` aggregation groups into. At least one is needed, and each covers `from` inclusive up to `to` exclusive.","example":[{"key":"small","to":100},{"key":"medium","from":100,"to":1000},{"key":"large","from":1000}]},"percents":{"type":"array","items":{"type":"number","minimum":0,"maximum":100},"description":"The percentiles to compute, each between 0 and 100. Used by the `percentiles` type.","example":[25,50,75,90,99]},"minDocCount":{"type":"integer","minimum":0,"description":"Smallest number of matching records a bucket must hold to appear in the result. Set it to 0 to keep buckets that matched nothing. Only the bucketing types honour it; single-value metric types ignore it.","example":0},"order":{"type":"object","additionalProperties":{"type":"string","enum":["asc","desc"]},"description":"Order the buckets of a `terms` aggregation. The key is what to sort on, either `_count`, `_key`, or the name of one of this aggregation's sub-aggregations; the value is the direction.","example":{"_count":"desc"}},"format":{"type":"string","description":"Pattern used to render `key_as_string` on each date bucket, for example \"yyyy-MM-dd\".","example":"yyyy-MM"},"timeZone":{"type":"string","description":"IANA time zone that date bucket boundaries are aligned to, for example \"Europe/London\".","example":"Europe/London"},"aggs":{"type":"array","items":{"$ref":"#/components/schemas/NestedAggregation"},"maxItems":10,"description":"Sub-aggregations run inside each bucket of this one. Up to 10, and they may nest one level further, giving two levels below the top."}},"required":["name","type","field"]},"RangeDefinition":{"type":"object","properties":{"from":{"type":"number","description":"Lower bound of the range, inclusive. Omit to leave the range open below."},"to":{"type":"number","description":"Upper bound of the range, exclusive. Omit to leave the range open above."},"key":{"type":"string","description":"Label for this range. It is returned as the bucket key in the result."}}},"NestedAggregation":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":50,"description":"Name for this aggregation. It is the key its result appears under in the response `aggregations` object, so it must be unique within the request. Between 1 and 50 characters.","example":"tenure_breakdown"},"type":{"type":"string","enum":["terms","range","histogram","date_histogram","stats","extended_stats","min","max","avg","sum","count","cardinality","percentiles"],"description":"How the matching records are aggregated. Each type takes its own parameters and returns its own result shape."},"field":{"type":"string","minLength":1,"description":"Field to aggregate over. Each dataset allows a fixed set of fields, and each of those supports only certain aggregation types; a field or type outside that set is rejected.","example":"areaSqm"},"size":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of buckets a grouping aggregation returns, between 1 and 100. The single-value metric types ignore it. For the map-tile grouping type it sets the tile precision rather than a bucket count. When omitted, the default depends on the dataset and the field.","example":10},"interval":{"type":"number","exclusiveMinimum":0,"description":"Width of each bucket for a `histogram` aggregation, in the units of the field. Must be greater than zero. Some datasets reject a `histogram` aggregation that omits it rather than applying a default.","example":100000},"calendarInterval":{"type":"string","description":"Calendar-aware bucket width for a date aggregation: 1m (minute), 1h (hour), 1d (day), 1w (week), 1M (month), 1q (quarter) or 1y (year). Mutually exclusive with `fixedInterval`, so supply one or the other, never both.","example":"1M"},"fixedInterval":{"type":"string","description":"Fixed-duration bucket width for a date aggregation, written as a number and a unit (ms, s, m, h, d), for example \"30m\", \"1h\" or \"7d\". Unlike `calendarInterval` it takes no account of daylight saving or of months having different lengths. Mutually exclusive with `calendarInterval`, so supply one or the other, never both.","example":"1h"},"ranges":{"type":"array","items":{"$ref":"#/components/schemas/RangeDefinition"},"description":"The ranges a `range` aggregation groups into. At least one is needed, and each covers `from` inclusive up to `to` exclusive.","example":[{"key":"small","to":100},{"key":"medium","from":100,"to":1000},{"key":"large","from":1000}]},"percents":{"type":"array","items":{"type":"number","minimum":0,"maximum":100},"description":"The percentiles to compute, each between 0 and 100. Used by the `percentiles` type.","example":[25,50,75,90,99]},"minDocCount":{"type":"integer","minimum":0,"description":"Smallest number of matching records a bucket must hold to appear in the result. Set it to 0 to keep buckets that matched nothing. Only the bucketing types honour it; single-value metric types ignore it.","example":0},"order":{"type":"object","additionalProperties":{"type":"string","enum":["asc","desc"]},"description":"Order the buckets of a `terms` aggregation. The key is what to sort on, either `_count`, `_key`, or the name of one of this aggregation's sub-aggregations; the value is the direction.","example":{"_count":"desc"}},"format":{"type":"string","description":"Pattern used to render `key_as_string` on each date bucket, for example \"yyyy-MM-dd\".","example":"yyyy-MM"},"timeZone":{"type":"string","description":"IANA time zone that date bucket boundaries are aligned to, for example \"Europe/London\".","example":"Europe/London"},"aggs":{"type":"array","items":{"$ref":"#/components/schemas/LeafAggregation"},"maxItems":10,"description":"Sub-aggregations run inside each bucket of this one. Up to 10, and they cannot nest any further."}},"required":["name","type","field"]},"LeafAggregation":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":50,"description":"Name for this aggregation. It is the key its result appears under in the response `aggregations` object, so it must be unique within the request. Between 1 and 50 characters.","example":"tenure_breakdown"},"type":{"type":"string","enum":["terms","range","histogram","date_histogram","stats","extended_stats","min","max","avg","sum","count","cardinality","percentiles"],"description":"How the matching records are aggregated. Each type takes its own parameters and returns its own result shape."},"field":{"type":"string","minLength":1,"description":"Field to aggregate over. Each dataset allows a fixed set of fields, and each of those supports only certain aggregation types; a field or type outside that set is rejected.","example":"areaSqm"},"size":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of buckets a grouping aggregation returns, between 1 and 100. The single-value metric types ignore it. For the map-tile grouping type it sets the tile precision rather than a bucket count. When omitted, the default depends on the dataset and the field.","example":10},"interval":{"type":"number","exclusiveMinimum":0,"description":"Width of each bucket for a `histogram` aggregation, in the units of the field. Must be greater than zero. Some datasets reject a `histogram` aggregation that omits it rather than applying a default.","example":100000},"calendarInterval":{"type":"string","description":"Calendar-aware bucket width for a date aggregation: 1m (minute), 1h (hour), 1d (day), 1w (week), 1M (month), 1q (quarter) or 1y (year). Mutually exclusive with `fixedInterval`, so supply one or the other, never both.","example":"1M"},"fixedInterval":{"type":"string","description":"Fixed-duration bucket width for a date aggregation, written as a number and a unit (ms, s, m, h, d), for example \"30m\", \"1h\" or \"7d\". Unlike `calendarInterval` it takes no account of daylight saving or of months having different lengths. Mutually exclusive with `calendarInterval`, so supply one or the other, never both.","example":"1h"},"ranges":{"type":"array","items":{"$ref":"#/components/schemas/RangeDefinition"},"description":"The ranges a `range` aggregation groups into. At least one is needed, and each covers `from` inclusive up to `to` exclusive.","example":[{"key":"small","to":100},{"key":"medium","from":100,"to":1000},{"key":"large","from":1000}]},"percents":{"type":"array","items":{"type":"number","minimum":0,"maximum":100},"description":"The percentiles to compute, each between 0 and 100. Used by the `percentiles` type.","example":[25,50,75,90,99]},"minDocCount":{"type":"integer","minimum":0,"description":"Smallest number of matching records a bucket must hold to appear in the result. Set it to 0 to keep buckets that matched nothing. Only the bucketing types honour it; single-value metric types ignore it.","example":0},"order":{"type":"object","additionalProperties":{"type":"string","enum":["asc","desc"]},"description":"Order the buckets of a `terms` aggregation. The key is what to sort on, either `_count`, `_key`, or the name of one of this aggregation's sub-aggregations; the value is the direction.","example":{"_count":"desc"}},"format":{"type":"string","description":"Pattern used to render `key_as_string` on each date bucket, for example \"yyyy-MM-dd\".","example":"yyyy-MM"},"timeZone":{"type":"string","description":"IANA time zone that date bucket boundaries are aligned to, for example \"Europe/London\".","example":"Europe/London"}},"required":["name","type","field"]},"PropertyBySlugsRequest":{"type":"object","properties":{"slugs":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":1000,"description":"Property slugs to look up. Between 1 and 1,000 of them."},"attributes":{"type":"array","items":{"type":"string"},"description":"Attributes to return, given as dotted paths. Only these are returned, plus `locationId`, which is always included. Omit it to receive the default set. `GET /v1/property/attributes` lists every path."},"limit":{"type":"number","minimum":1,"maximum":1000,"default":25,"description":"Maximum number of properties to return. Defaults to 25. Minimum 1, maximum 1,000."},"track":{"type":"boolean","default":false,"description":"Has no effect on the response or on how the request is billed."},"countryCode":{"type":"string","description":"Sovereign state the request is aimed at, as an ISO 3166-1 alpha-2 code such as `GB`. Taken as a hint only: it does not filter the results, and the data covers Great Britain."}},"required":["slugs"]},"HealthResponse":{"type":"object","properties":{"status":{"type":"string","description":"Status of the service. `ok` when it is operating normally.","example":"ok"},"service":{"type":"string","description":"Name of the service that answered.","example":"safety"},"timestamp":{"type":"string","description":"When the check ran, as an ISO 8601 timestamp.","example":"2026-09-03T08:30:00.000Z"}},"required":["status","service","timestamp"]},"CrimeIncidentsListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`.","example":"list"},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/safety/crime"},"has_more":{"type":"boolean","description":"True when more results exist than were returned. The safety endpoints are not paged, so it is false.","example":false},"total_count":{"type":"number","description":"Number of results in `data`.","example":47},"data":{"type":"array","items":{"$ref":"#/components/schemas/CrimeIncident"},"description":"The crime incidents inside the requested radius and date window, most recent month first."},"summary":{"$ref":"#/components/schemas/CrimeIncidentsSummary"}},"required":["object","url","has_more","data","summary"]},"CrimeIncident":{"type":"object","properties":{"crimeId":{"type":["string","null"],"description":"Identifier issued for the incident by the police data source. Null for anti-social behaviour, which is published without one.","example":"8935d073778b476df95681c6d84e5d5342f69f43f8fe9948826735849b12afdd"},"category":{"type":"string","description":"Crime category, underscore-separated. One of: anti_social_behaviour, bicycle_theft, burglary, criminal_damage_and_arson, drugs, other_crime, other_theft, possession_of_weapons, public_order, robbery, shoplifting, theft_from_the_person, vehicle_crime, violence_and_sexual_offences.","example":"burglary"},"label":{"type":["string","null"],"description":"Human-readable name for the crime category.","example":"Burglary"},"reportedBy":{"type":["string","null"],"description":"Identifier of the police force that recorded the incident, in lower-case hyphenated form.","example":"metropolitan"},"crimeLocation":{"type":["string","null"],"description":"Location label for the incident. The current data source publishes no location text, so this is null; use `coordinates` to place the incident.","example":null},"crimeDate":{"type":"string","description":"Month the incident was recorded in, as an ISO 8601 timestamp on the first day of that month. The source publishes incidents by month, not by day.","example":"2026-06-01T00:00:00.000Z"},"outcome":{"type":["string","null"],"description":"Last recorded outcome for the incident, as published by the police data source. Null for anti-social behaviour and for incidents with no outcome yet.","example":"Under investigation"},"coordinates":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}],"description":"Position of the anonymised reporting point: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order). The source snaps each incident to a nearby map point, so the position is accurate to roughly 150m. Null for records published without a position.","example":[-0.1278,51.5074]}},"required":["crimeId","category","label","reportedBy","crimeLocation","crimeDate","outcome","coordinates"]},"CrimeIncidentsSummary":{"type":"object","properties":{"byCategory":{"type":"object","additionalProperties":{"type":"number"},"description":"Number of incidents in each crime category across the returned set.","example":{"burglary":12,"anti_social_behaviour":18,"vehicle_crime":17}},"radius":{"type":"number","description":"Search radius that was applied, in metres.","example":1000},"period":{"type":"string","description":"Anchor month for the window, in `YYYY-MM` form. When the request supplies `date` this is that month, or the most recent month with significant reporting in the area if that is earlier; otherwise it is the most recent month with significant reporting in the area.","example":"2026-06"},"truncated":{"type":"boolean","description":"True when the search hit the cap of 5,000 incidents and the returned set is incomplete. Narrow the radius or the date window to see the rest.","example":false}},"required":["byCategory","radius","period","truncated"]},"MonthlyCategoryStatsListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`.","example":"list"},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/safety/crime"},"has_more":{"type":"boolean","description":"True when more results exist than were returned. The safety endpoints are not paged, so it is false.","example":false},"total_count":{"type":"number","description":"Number of results in `data`.","example":47},"data":{"type":"array","items":{"$ref":"#/components/schemas/MonthlyCategoryStats"},"description":"Monthly counts for the 12 months ending at the most recent month with significant reporting in the area, oldest first. Months with no recorded incidents are left out."}},"required":["object","url","has_more","data"]},"MonthlyCategoryStats":{"type":"object","properties":{"date":{"type":"string","description":"Month the counts cover, in `YYYY-MM` form.","example":"2026-06"},"categories":{"type":"object","additionalProperties":{"type":"number"},"description":"Number of incidents in each crime category for the month.","example":{"burglary":4,"anti_social_behaviour":9}}},"required":["date","categories"]},"PointCategoryStatsListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`.","example":"list"},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/safety/crime"},"has_more":{"type":"boolean","description":"True when more results exist than were returned. The safety endpoints are not paged, so it is false.","example":false},"total_count":{"type":"number","description":"Number of results in `data`.","example":47},"data":{"type":"array","items":{"$ref":"#/components/schemas/PointCategoryStats"},"description":"One entry per reporting point and month, over the same 12-month window as the area statistics. Several points inside the radius produce several entries for the same month, which is what heat-map style overlays need."}},"required":["object","url","has_more","data"]},"PointCategoryStats":{"type":"object","properties":{"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"Position of the anonymised reporting point: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]},"date":{"type":"string","description":"Month the counts cover, in `YYYY-MM` form.","example":"2026-06"},"categories":{"type":"object","additionalProperties":{"type":"number"},"description":"Number of incidents in each crime category at this point for the month.","example":{"vehicle_crime":2,"theft_from_the_person":1}}},"required":["coordinates","date","categories"]},"CrimeCatalogCountriesResponse":{"type":"object","properties":{"countries":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/CrimeCatalogPeriodsByCountry"},"description":"Periods held for each country, keyed by country identifier and split into yearly and monthly.","example":{"england":{"yearly":[],"monthly":["2026-06","2026-05"]},"wales":{"yearly":[],"monthly":["2026-06","2026-05"]}}}},"required":["countries"]},"CrimeCatalogPeriodsByCountry":{"type":"object","properties":{"yearly":{"type":"array","items":{"type":"string"},"description":"Yearly periods (`YYYY`) held for the country, most recent first. Empty today.","example":[]},"monthly":{"type":"array","items":{"type":"string"},"description":"Monthly periods (`YYYY-MM`) held for the country, most recent first.","example":["2026-06","2026-05","2026-04"]}},"required":["yearly","monthly"]},"CrimeCatalogByCountryResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`.","example":"list"},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/safety/crime"},"has_more":{"type":"boolean","description":"True when more results exist than were returned. The safety endpoints are not paged, so it is false.","example":false},"total_count":{"type":"number","description":"Number of results in `data`.","example":47},"data":{"type":"array","items":{"$ref":"#/components/schemas/CrimeCatalogEntry"},"description":"One entry per period held for the requested country, newest period first."}},"required":["object","url","has_more","data"]},"CrimeCatalogEntry":{"type":"object","properties":{"country":{"type":"string","description":"Country the entry covers: `england` or `wales`.","example":"england"},"period":{"type":"string","description":"Period the entry covers. Yearly entries use `YYYY`, monthly entries use `YYYY-MM`.","example":"2026-06"},"periodType":{"type":"string","enum":["monthly","yearly"],"description":"Granularity of `period`. Only monthly periods are published today.","example":"monthly"},"isAvailable":{"type":"boolean","description":"True when this period has been published and can be queried.","example":true}},"required":["country","period","periodType","isAvailable"]},"GeographyMetricsListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`.","example":"list"},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/safety/crime"},"has_more":{"type":"boolean","description":"True when more results exist than were returned. The safety endpoints are not paged, so it is false.","example":false},"total_count":{"type":"number","description":"Number of results in `data`.","example":47},"data":{"type":"array","items":{"$ref":"#/components/schemas/GeographyMetricsRow"},"description":"One row per area and period, or one row per period when areas are merged."}},"required":["object","url","has_more","data"]},"GeographyMetricsRow":{"type":"object","properties":{"geographicCode":{"type":"string","description":"Area code this row covers. When areas are merged it is the comma-joined list of every requested code that contributed to the row.","example":"E01000001"},"entityType":{"type":["string","null"],"description":"Type of area the code identifies: `lsoa21`, `msoa21`, `district_borough_unitary_ward`, `built_up_area_250`, `local_authority_district`, `county_unitary_authority`, `english_region` or `country_region`. A unitary authority is served as `local_authority_district`, and every ward, in England and in Wales, is served as `district_borough_unitary_ward`. Null when areas are merged.","example":"lsoa21"},"name":{"type":["string","null"],"description":"Name of the area. Null when areas are merged.","example":"City of London 001A"},"country":{"type":["string","null"],"description":"`england` or `wales`. Null when merged areas span both.","example":"england"},"geographyFit":{"type":["number","null"],"description":"How much of this area's own footprint is covered by the Lower Layer Super Output Areas its figures are aggregated from, as a fraction from 0 to 1. A value means the figures are an approximation of that quality, so 0.88 says the areas summed together cover 88% of this one. Null means the area is made up of whole Lower Layer Super Output Areas and no approximation arises, which is the case at every administrative level from LSOA to country; it is not an unknown value. Wards and built-up areas average about 0.88, and roughly one in eight is below 0.7.","example":0.88},"period":{"type":"string","description":"Month this row covers, in `YYYY-MM` form.","example":"2026-06"},"population":{"type":"number","description":"Resident population the rates are calculated against, from the latest mid-year estimate. When areas are merged it is the sum across them. 0 when the area's data is missing.","example":1850},"totalCrimeCount":{"type":"number","description":"Number of incidents across all categories over the 24-month window ending at the period.","example":124},"totalCrimeRate":{"type":"number","description":"Incidents across all categories per 1,000 residents per year over the window.","example":67},"totalCrimeScore":{"type":["number","null"],"description":"The area's overall safety score, from 0 to 100, where higher is safer. The same value as the `all` category's `crimeScore`. Null when areas are merged and when the police force did not report.","example":52.4},"dataAvailability":{"type":"string","description":"How complete the data behind this row is. `available` means the police force reported throughout the window. `partial` means part of the window or part of the area was not reported. `missing` means the force did not report, so counts and rates come from stray incidents recorded by a neighbouring force and must not be read as evidence of safety. `unknown` means coverage could not be determined. Read this beside every number in the row.","example":"available"},"modelVersion":{"type":["string","null"],"description":"Version of the scoring model that produced the row.","example":"3.0.0"},"categories":{"type":"array","items":{"$ref":"#/components/schemas/GeographyCategoryMetric"},"description":"Breakdown of the period by crime category, `all` first."},"timeSeriesData":{"type":"array","items":{"$ref":"#/components/schemas/GeographyTimeSeriesPoint"},"description":"Monthly history leading up to this row's period. Empty when `includeTimeSeries` is false; the window length comes from the `months` parameter, which defaults to 12."}},"required":["geographicCode","period","population","totalCrimeCount","totalCrimeRate","categories","timeSeriesData"]},"GeographyCategoryMetric":{"type":"object","properties":{"category":{"type":"string","description":"Crime category this breakdown covers. `all` is the composite across every category.","example":"burglary"},"crimeCount":{"type":"number","description":"Number of incidents in this category over the trailing 24-month window ending at the row's period. Not decayed.","example":47},"crimeRate":{"type":"number","description":"Incidents in this category per 1,000 residents per year over the window. 0 when the row's `dataAvailability` is `missing`.","example":12.3},"crimeScore":{"type":["number","null"],"description":"Safety score for this category, from 0 to 100, where higher is safer. Each category has its own scale, so scores are not comparable across categories. Null when areas are merged, because scores cannot be combined across geographies, and when the police force did not report. Never treat a null as 0.","example":71},"percentile":{"type":["number","null"],"description":"Where this category's score ranks among areas of the same type in England and Wales for the month, from 0 to 100, where 100 is safest. Null when areas are merged and when fewer than 10 areas could be ranked. Not comparable across area types.","example":65},"percentileLocal":{"type":["number","null"],"description":"The same rank taken within the area's parent local authority. Null for local authorities and above, when areas are merged, and when fewer than 10 areas could be ranked.","example":40},"trendFactor":{"type":["number","null"],"description":"Direction and size of the change in this category, comparing the most recent year with the year before. Positive values mean crime is falling. Null when areas are merged and when not computed.","example":0.12},"trendRatio":{"type":["number","null"],"description":"Incidents in the most recent year divided by the year before. Above 1 means crime is rising.","example":0.89},"trendZ":{"type":["number","null"],"description":"Statistical significance of the year-on-year change, as a z-score.","example":-0.89},"trendLabel":{"type":["string","null"],"description":"The trend in words: `improving`, `worsening`, `stable` or `unknown`. Null when areas are merged.","example":"stable"},"trendSignificant":{"type":"boolean","description":"True only when `trendLabel` is `improving` or `worsening`.","example":false},"harmRate":{"type":["number","null"],"description":"Expected harm per 1,000 residents per year, weighting each offence by its severity, with recent months weighted more heavily. Null when areas are merged and when the police force did not report.","example":9571.6},"harmLower":{"type":["number","null"],"description":"Lower bound of the 80% prediction interval on harm over the next 12 months.","example":6582.2},"harmUpper":{"type":["number","null"],"description":"Upper bound of the 80% prediction interval on harm over the next 12 months.","example":13918.6},"dataAvailability":{"type":"string","description":"How complete the data behind this row is. `available` means the police force reported throughout the window. `partial` means part of the window or part of the area was not reported. `missing` means the force did not report, so counts and rates come from stray incidents recorded by a neighbouring force and must not be read as evidence of safety. `unknown` means coverage could not be determined. Read this beside every number in the row. Merged rows report `available` only when every merged area is, otherwise `partial`.","example":"available"},"coveredPeriods":{"type":["number","null"],"description":"How many months of the 24-month window had usable data. Null when areas are merged.","example":24},"confidenceInterval":{"$ref":"#/components/schemas/CrimeConfidenceInterval"},"explanatoryTags":{"type":["array","null"],"items":{"type":"string"},"description":"Machine-readable codes describing what drives the area's score. They use the same vocabulary as `CrimeMetrics.explanatoryTags`. Only the `all` category carries tags; other categories carry an empty list. Null when areas are merged.","example":["primarily_property_crime","high_data_confidence"]},"periodDetails":{"$ref":"#/components/schemas/CrimePeriodDetails"}},"required":["category","crimeCount","crimeRate","crimeScore","percentile","trendFactor","dataAvailability","confidenceInterval","explanatoryTags","periodDetails"]},"CrimeConfidenceInterval":{"type":["object","null"],"properties":{"lower":{"type":"number","description":"Lower bound of the interval around the score.","example":64.5},"upper":{"type":"number","description":"Upper bound of the interval around the score.","example":78.2},"confidence":{"type":"number","description":"Confidence level the interval was computed at, from 0 to 1.","example":0.95}},"required":["lower","upper","confidence"],"description":"95% confidence interval around `crimeScore`, reflecting sampling only. Null when areas are merged and when no interval was computed."},"CrimePeriodDetails":{"type":["object","null"],"properties":{"start":{"type":"string","description":"First month of the window, in `YYYY-MM` form.","example":"2024-07"},"end":{"type":"string","description":"Last month of the window, in `YYYY-MM` form.","example":"2026-06"},"windowMonths":{"type":"number","description":"Length of the analysis window, in months.","example":24},"sampleSize":{"type":"number","description":"Number of incidents in the analysis window.","example":487},"coveredPeriods":{"type":["number","null"],"description":"How many months of the window had usable data. Null when not known.","example":24}},"required":["start","end","windowMonths","sampleSize","coveredPeriods"],"additionalProperties":{},"description":"The trailing window behind this category's numbers. Null when areas are merged."},"GeographyTimeSeriesPoint":{"type":"object","properties":{"period":{"type":"string","description":"Month this point covers, in `YYYY-MM` form.","example":"2026-05"},"category":{"type":"string","description":"Crime category this point covers. `all` is the composite across every category.","example":"all"},"crimeCount":{"type":"number","description":"Number of incidents in this category over the 24-month window ending at this month.","example":38},"crimeRate":{"type":"number","description":"Incidents in this category per 1,000 residents per year over that window.","example":9.8},"crimeScore":{"type":["number","null"],"description":"Safety score for this month and category, from 0 to 100, where higher is safer. Null when areas are merged and when the police force did not report.","example":73},"percentile":{"type":["number","null"],"description":"Where this month's score ranks among areas of the same type, from 0 to 100, where 100 is safest. Null when it has not been ranked.","example":62},"trendFactor":{"type":["number","null"],"description":"Direction and size of the year-on-year change for this month and category. Positive means crime is falling. Null when areas are merged.","example":0.08},"dataAvailability":{"type":"string","description":"How complete the data behind this row is. `available` means the police force reported throughout the window. `partial` means part of the window or part of the area was not reported. `missing` means the force did not report, so counts and rates come from stray incidents recorded by a neighbouring force and must not be read as evidence of safety. `unknown` means coverage could not be determined. Read this beside every number in the row.","example":"available"}},"required":["period","category","crimeCount","crimeRate","crimeScore","percentile","trendFactor"]},"EPCQueryResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Type of this response. Always `list`."},"url":{"type":"string","enum":["/v1/epc/query"],"description":"The path that produced this list. Always `/v1/epc/query`."},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Identifier for this certificate within the API."},"certificateType":{"type":"string","enum":["domestic","non_domestic","dec"],"description":"What kind of certificate this is. `domestic` and `non_domestic` are Energy Performance Certificates for dwellings and for other buildings; `dec` is a Display Energy Certificate, which rates a public building's measured energy use."},"assessmentMethodology":{"type":"string","enum":["rdsap","sap","sbem","dsm","operational"],"description":"Which procedure the assessment followed. `rdsap` is the reduced-data procedure for existing dwellings and `sap` the full procedure for new ones; `sbem` covers non-domestic buildings and `dsm` the dynamic simulation modelling used for the most complex of them; `operational` is the metered assessment behind a Display Energy Certificate."},"source":{"type":"string","enum":["mhclg","scottish_government"],"description":"Which national register the certificate came from: `mhclg` for England and Wales, `scottish_government` for Scotland."},"sourceReference":{"type":"string","description":"The certificate's own reference number in the register it came from."},"buildingReferenceNumber":{"type":["string","null"],"description":"Reference that ties successive assessments of the same building together. It is issued by the source register and is not a location ID."},"locationId":{"type":["integer","null"],"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). Null when the certificate has not been matched to a location."},"address":{"type":"object","properties":{"displayAddress":{"type":"string","description":"The address formatted as a single line, ready to show to an end user."},"line1":{"type":["string","null"],"description":"First line of the address."},"line2":{"type":["string","null"],"description":"Second line of the address, where there is one."},"line3":{"type":["string","null"],"description":"Third line of the address. Scottish certificates carry the post town here."},"postTown":{"type":["string","null"],"description":"The post town."},"postcode":{"type":"string","description":"The full UK postcode."},"postcodeNoSpace":{"type":"string","description":"The same postcode with the space removed, for matching."}},"required":["displayAddress","line1","line2","line3","postTown","postcode","postcodeNoSpace"],"description":"The certificate's address, in the same form as the rest of the API."},"coordinates":{"type":["object","null"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees."},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees."}},"required":["latitude","longitude"],"description":"Where the building is. Taken from the matched location where there is one, otherwise the centre of the postcode."},"localAuthority":{"type":["string","null"],"description":"ONS code for the local authority the building sits in."},"localAuthorityLabel":{"type":["string","null"],"description":"Name of that local authority."},"constituency":{"type":["string","null"],"description":"Code for the parliamentary constituency, or on Scottish certificates the electoral ward."},"constituencyLabel":{"type":["string","null"],"description":"Name of that constituency or ward."},"county":{"type":["string","null"],"description":"The county. England and Wales only."},"dataZone":{"type":["string","null"],"description":"Code for the Scottish data zone the building sits in. Scotland only."},"inspectionDate":{"type":"string","description":"When the assessor inspected the building, as an ISO 8601 date."},"lodgementDate":{"type":"string","description":"When the certificate was lodged on the national register, as an ISO 8601 date."},"validUntil":{"type":["string","null"],"description":"When the certificate expires, as an ISO 8601 date. Energy Performance Certificates run for ten years from lodgement; Display Energy Certificates run for one."},"propertyType":{"type":["string","null"],"description":"What kind of building this is, mapped to a standard set of categories. Domestic certificates use `house`, `flat`, `bungalow`, `maisonette` or `park_home`; non-domestic certificates use categories such as `office_workshop`, `retail_financial` and `storage_distribution`. `propertyTypeExternal` carries the wording used on the certificate."},"propertyTypeExternal":{"type":["string","null"],"description":"The property type exactly as the certificate words it, for example 'House' or 'Offices and Workshop businesses'."},"totalFloorArea":{"type":["number","null"],"description":"Floor area of the building, in square metres. Domestic certificates give the total internal floor area; non-domestic certificates give the conditioned floor area."},"transactionType":{"type":["string","null"],"enum":["marketed_sale","non_marketed_sale","rental","new_dwelling","voluntary","voluntary_reissue","stock_condition_survey","grant_scheme","display_public_building","construction","other",null],"description":"What prompted the assessment, mapped to a standard set of categories."},"transactionTypeExternal":{"type":["string","null"],"description":"What prompted the assessment, exactly as the certificate words it."},"rating":{"type":"object","properties":{"current":{"type":"object","properties":{"band":{"type":"string","enum":["A+","A","B+","B","C+","C","D+","D","E+","E","F+","F","G"],"description":"Energy efficiency band, where A+ and A are the most efficient and G the least. Domestic certificates use A to G, non-domestic certificates add A+, and Scotland non-domestic certificates also use half-bands such as B+ and C+."},"score":{"type":"number","description":"Numeric score behind the band, read alongside `scoreType`. A `sap` score runs from 1 to 100 and higher is better. An `asset` score is in kg CO2 per m² and an `operational` score is measured against a benchmark; both are unbounded and lower is better. An `epi` score is in kg CO2 per m² calculated with Scottish weather data."},"scoreType":{"type":"string","enum":["sap","asset","operational","epi"],"description":"Which scale `score` is on. Read it before comparing scores across certificates."}},"required":["band","score","scoreType"],"description":"The rating the building holds as assessed."},"potential":{"type":["object","null"],"properties":{"band":{"type":"string","enum":["A+","A","B+","B","C+","C","D+","D","E+","E","F+","F","G"],"description":"Energy efficiency band, where A+ and A are the most efficient and G the least. Domestic certificates use A to G, non-domestic certificates add A+, and Scotland non-domestic certificates also use half-bands such as B+ and C+."},"score":{"type":"number","description":"Numeric score behind the band, read alongside `scoreType`. A `sap` score runs from 1 to 100 and higher is better. An `asset` score is in kg CO2 per m² and an `operational` score is measured against a benchmark; both are unbounded and lower is better. An `epi` score is in kg CO2 per m² calculated with Scottish weather data."},"scoreType":{"type":"string","enum":["sap","asset","operational","epi"],"description":"Which scale `score` is on. Read it before comparing scores across certificates."}},"required":["band","score","scoreType"],"description":"The rating the building would reach if the recommended improvements were carried out. Null on Display Energy Certificates, which rate measured use rather than potential, and on England and Wales non-domestic certificates, which do not publish one. Scotland non-domestic does."},"carbonNeutral":{"type":"boolean","description":"True when the building is rated carbon neutral. Scotland non-domestic certificates record this as a 'Carbon Neu' band, which is published here as band `A+` with this flag set."}},"required":["current","potential","carbonNeutral"],"description":"The building's energy rating. Every certificate type carries one, so filter on `rating.current.band` to compare efficiency across types."},"emissions":{"type":"object","properties":{"co2Current":{"type":["number","null"],"description":"Annual carbon dioxide emissions at the assessed efficiency. Domestic certificates report tonnes per year and non-domestic certificates report kg CO2 per m² per year; read `co2Unit` for the unit that applies to this record."},"co2Potential":{"type":["number","null"],"description":"Annual carbon dioxide emissions once the recommended improvements are carried out. Domestic only; null on non-domestic certificates and Display Energy Certificates."},"co2PerFloorArea":{"type":["number","null"],"description":"Annual carbon dioxide emissions per square metre of floor area, in kg CO2 per m² per year. On non-domestic certificates this is the building emission rate."},"co2Unit":{"type":"string","enum":["tonnes_per_year","kg_co2_per_m2_per_year"],"description":"The unit `co2Current` is expressed in. Domestic certificates use `tonnes_per_year`; non-domestic certificates and Display Energy Certificates use `kg_co2_per_m2_per_year`."},"environmentalScoreCurrent":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Environmental impact score from 1 to 100, where higher is better. Domestic only."},"environmentalScorePotential":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"The environmental impact score the property would reach once the recommended improvements are carried out, on the same 1 to 100 scale. Domestic only."},"energyConsumptionCurrent":{"type":["number","null"],"description":"Annual energy consumption at the assessed efficiency. Domestic certificates report kWh per year and non-domestic certificates report kWh per m² per year; read `energyConsumptionUnit` for the unit that applies to this record."},"energyConsumptionPotential":{"type":["number","null"],"description":"Annual energy consumption once the recommended improvements are carried out. Domestic only."},"energyConsumptionUnit":{"type":["string","null"],"enum":["kwh_per_year","kwh_per_m2_per_year",null],"description":"The unit `energyConsumptionCurrent` is expressed in."}},"required":["co2Current","co2Potential","co2PerFloorArea","co2Unit","environmentalScoreCurrent","environmentalScorePotential","energyConsumptionCurrent","energyConsumptionPotential","energyConsumptionUnit"],"description":"Carbon dioxide emissions, environmental impact scores and energy consumption."},"runningCosts":{"type":["object","null"],"properties":{"heating":{"type":"object","properties":{"current":{"type":"integer","description":"Estimated annual heating cost at the assessed efficiency, in GBP."},"potential":{"type":"integer","description":"Estimated annual heating cost once the recommended improvements are carried out, in GBP."}},"required":["current","potential"],"description":"Estimated annual heating cost, as assessed and after improvement."},"hotWater":{"type":"object","properties":{"current":{"type":"integer","description":"Estimated annual hot water cost at the assessed efficiency, in GBP."},"potential":{"type":"integer","description":"Estimated annual hot water cost once the recommended improvements are carried out, in GBP."}},"required":["current","potential"],"description":"Estimated annual hot water cost, as assessed and after improvement."},"lighting":{"type":"object","properties":{"current":{"type":"integer","description":"Estimated annual lighting cost at the assessed efficiency, in GBP."},"potential":{"type":"integer","description":"Estimated annual lighting cost once the recommended improvements are carried out, in GBP."}},"required":["current","potential"],"description":"Estimated annual lighting cost, as assessed and after improvement."}},"required":["heating","hotWater","lighting"],"description":"Estimated annual running costs in GBP. Domestic only; null on non-domestic certificates and Display Energy Certificates."},"fabric":{"type":["object","null"],"properties":{"walls":{"type":"object","properties":{"construction":{"type":["string","null"],"enum":["cavity","solid_brick","timber_frame","sandstone_or_limestone","sandstone","granite_or_whinstone","granite","system_built","solid_stone","cob","park_home","basement","curtain_wall",null],"description":"How the external walls are built."},"material":{"type":["string","null"],"description":"The wall material, for example 'brick', where the assessor's description identifies one."},"insulationType":{"type":["string","null"],"enum":["none","as_built","filled_cavity","external","internal","filled_cavity_and_external","filled_cavity_and_internal","partial","retro_fitted","loft","rafter",null],"description":"How the walls are insulated, if at all."},"insulationPresent":{"type":["boolean","null"],"description":"True when the walls are insulated."},"insulationAssumed":{"type":"boolean","description":"True when the assessor assumed the insulation rather than confirming it."},"thermalTransmittance":{"type":["number","null"],"description":"Thermal transmittance (U-value) of the walls, in W/m²K, where the assessment reports one."},"description":{"type":["string","null"],"description":"The assessor's own description of the walls, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient the walls are, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How the walls score for environmental impact, on the certificate's five-point scale."},"dataQuality":{"type":["string","null"],"enum":["truncated_thermal_transmittance","quality_label_only","welsh_language","corrupted_encoding","source_error",null],"description":"Set when the source value could not be read as recorded, giving the reason. Null when the value came through intact."}},"required":["construction","material","insulationType","insulationPresent","insulationAssumed","thermalTransmittance","description","energyEfficiency","environmentalEfficiency","dataQuality"],"description":"The external walls and their insulation."},"roof":{"type":"object","properties":{"roofType":{"type":["string","null"],"enum":["pitched","flat","thatched","another_dwelling_above","other_premises_above","roof_room",null],"description":"How the roof is built, including the cases where another dwelling or premises sits above."},"insulationType":{"type":["string","null"],"enum":["none","as_built","filled_cavity","external","internal","filled_cavity_and_external","filled_cavity_and_internal","partial","retro_fitted","loft","rafter",null],"description":"How the roof is insulated, if at all."},"insulationDepthMm":{"type":["integer","null"],"description":"Depth of the loft insulation, in millimetres."},"insulationPresent":{"type":["boolean","null"],"description":"True when the roof is insulated."},"insulationAssumed":{"type":"boolean","description":"True when the assessor assumed the insulation rather than confirming it."},"thermalTransmittance":{"type":["number","null"],"description":"Thermal transmittance (U-value) of the roof, in W/m²K, where the assessment reports one."},"description":{"type":["string","null"],"description":"The assessor's own description of the roof, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient the roof is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How the roof scores for environmental impact, on the certificate's five-point scale."},"dataQuality":{"type":["string","null"],"enum":["truncated_thermal_transmittance","quality_label_only","welsh_language","corrupted_encoding","source_error",null],"description":"Set when the source value could not be read as recorded, giving the reason. Null when the value came through intact."}},"required":["roofType","insulationType","insulationDepthMm","insulationPresent","insulationAssumed","thermalTransmittance","description","energyEfficiency","environmentalEfficiency","dataQuality"],"description":"The roof and its insulation."},"floor":{"type":"object","properties":{"floorType":{"type":["string","null"],"enum":["solid","suspended_timber","suspended_sealed","another_dwelling_below","other_premises_below",null],"description":"How the ground floor is built, including the cases where another dwelling or premises sits below."},"insulationPresent":{"type":["boolean","null"],"description":"True when the floor is insulated."},"insulationAssumed":{"type":"boolean","description":"True when the assessor assumed the insulation rather than confirming it."},"insulationType":{"type":["string","null"],"enum":["none","as_built","filled_cavity","external","internal","filled_cavity_and_external","filled_cavity_and_internal","partial","retro_fitted","loft","rafter",null],"description":"How the floor is insulated, where insulation is present."},"thermalTransmittance":{"type":["number","null"],"description":"Thermal transmittance (U-value) of the floor, in W/m²K, where the assessment reports one."},"description":{"type":["string","null"],"description":"The assessor's own description of the floor, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient the floor is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How the floor scores for environmental impact, on the certificate's five-point scale."},"dataQuality":{"type":["string","null"],"enum":["truncated_thermal_transmittance","quality_label_only","welsh_language","corrupted_encoding","source_error",null],"description":"Set when the source value could not be read as recorded, giving the reason. Null when the value came through intact."}},"required":["floorType","insulationPresent","insulationAssumed","insulationType","thermalTransmittance","description","energyEfficiency","environmentalEfficiency","dataQuality"],"description":"The ground floor and its insulation."},"mainHeating":{"type":"object","properties":{"systemType":{"type":["string","null"],"enum":["boiler_radiators","boiler_underfloor","storage_heaters","room_heaters","warm_air","heat_pump_radiators","heat_pump_underfloor","underfloor_electric","community_scheme","micro_chp","none_assumed",null],"description":"What kind of main heating system is installed."},"fuel":{"type":["string","null"],"enum":["mains_gas","lpg","oil","electricity","biomass","coal","anthracite","smokeless_fuel","biogas","district_heating","heat_pump","dual_fuel","waste_heat","other",null],"description":"The fuel this heating system runs on."},"heatPumpType":{"type":["string","null"],"enum":["air_source","ground_source","water_source",null],"description":"Where the heat pump draws its heat from, where the system is a heat pump."},"isMultiSystem":{"type":"boolean","description":"True when the certificate records more than one heating system."},"description":{"type":["string","null"],"description":"The assessor's own description of the heating system, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient the heating system is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How the heating system scores for environmental impact, on the certificate's five-point scale."},"dataQuality":{"type":["string","null"],"enum":["truncated_thermal_transmittance","quality_label_only","welsh_language","corrupted_encoding","source_error",null],"description":"Set when the source value could not be read as recorded, giving the reason. Null when the value came through intact."}},"required":["systemType","fuel","heatPumpType","isMultiSystem","description","energyEfficiency","environmentalEfficiency","dataQuality"],"description":"The main heating system."},"windows":{"type":"object","properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"required":["description","energyEfficiency","environmentalEfficiency"],"description":"The windows and their glazing."},"heatingControls":{"type":"object","properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"required":["description","energyEfficiency","environmentalEfficiency"],"description":"How the heating is controlled."},"hotWater":{"type":"object","properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"required":["description","energyEfficiency","environmentalEfficiency"],"description":"The hot water system."},"lighting":{"type":"object","properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"required":["description","energyEfficiency","environmentalEfficiency"],"description":"The lighting installed."},"secondaryHeating":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"required":["description","energyEfficiency","environmentalEfficiency"],"description":"Any secondary heating system. Null when the property has none."},"airTightness":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"required":["description","energyEfficiency","environmentalEfficiency"],"description":"The air tightness assessment. Scotland only; null on England and Wales certificates."}},"required":["walls","roof","floor","mainHeating","windows","heatingControls","hotWater","lighting","secondaryHeating","airTightness"],"description":"Component-by-component assessment of the building fabric. Domestic only; null on non-domestic certificates and Display Energy Certificates."},"systems":{"type":"object","properties":{"mainFuel":{"type":["string","null"],"enum":["mains_gas","lpg","oil","electricity","biomass","coal","anthracite","smokeless_fuel","biogas","district_heating","heat_pump","dual_fuel","waste_heat","other",null],"description":"The main fuel the building uses, mapped to a standard set of categories. `mainFuelExternal` carries the wording used on the certificate."},"mainFuelExternal":{"type":["string","null"],"description":"The fuel exactly as the certificate words it, for example 'mains gas (not community)' or 'electricity (7-hour tariff)'."},"mainsGas":{"type":["boolean","null"],"description":"True when the property has a mains gas connection. Domestic only; null when the certificate does not say."},"energyTariff":{"type":["string","null"],"enum":["single","dual","off_peak_7hr","off_peak_10hr","off_peak_18hr","off_peak_24hr","unknown",null],"description":"The electricity tariff the property is on, including the off-peak arrangements. Domestic only."},"mainHeatingControls":{"type":["string","null"],"description":"The heating controls recorded on the certificate, as a source code. Domestic only."},"renewables":{"type":"object","properties":{"solarThermal":{"type":["boolean","null"],"description":"True when the building has solar thermal panels heating its hot water."},"photovoltaic":{"type":["object","null"],"properties":{"present":{"type":"boolean","description":"True when solar photovoltaic panels are installed."},"supplyPercentage":{"type":["number","null"],"description":"The photovoltaic supply figure recorded on the certificate, as a percentage. Domestic only."}},"required":["present","supplyPercentage"],"description":"The solar photovoltaic installation."},"windTurbines":{"type":["integer","null"],"description":"Number of wind turbines installed. Domestic only."},"description":{"type":["string","null"],"description":"The renewable sources in the assessor's own words. Non-domestic only."}},"required":["solarThermal","photovoltaic","windTurbines","description"],"description":"Renewable energy generated on site."},"ventilation":{"type":["string","null"],"enum":["natural","mechanical_extract","mechanical_supply_and_extract",null],"description":"How the property is ventilated. Domestic only."},"heatLossCorridor":{"type":["string","null"],"enum":["no_corridor","heated_corridor","unheated_corridor",null],"description":"Whether the dwelling is reached by a corridor and whether that corridor is heated. Recorded for flats and maisonettes only."},"unheatedCorridorLength":{"type":["number","null"],"description":"Length of the unheated corridor, in metres. Recorded for flats and maisonettes only."},"airConditioning":{"type":["object","null"],"properties":{"present":{"type":"boolean","description":"True when the building has air conditioning."},"kwRating":{"type":["number","null"],"description":"Rated capacity of the air conditioning system, in kW."},"estimatedKwRating":{"type":["number","null"],"description":"Estimated capacity of the air conditioning system, in kW, used when the rated capacity is unknown."},"inspectionStatus":{"type":["string","null"],"enum":["completed","commissioned","not_commissioned","not_relevant","unknown",null],"description":"Whether an air conditioning inspection has been carried out, commissioned, or is not relevant."}},"required":["present","kwRating","estimatedKwRating","inspectionStatus"],"description":"The building's air conditioning. Recorded on non-domestic certificates and Display Energy Certificates; null for domestic."}},"required":["mainFuel","mainFuelExternal","mainsGas","energyTariff","mainHeatingControls","renewables","ventilation","heatLossCorridor","unheatedCorridorLength","airConditioning"],"description":"The building's energy systems: fuel, heating, renewables and ventilation."},"domesticDetails":{"type":["object","null"],"properties":{"builtForm":{"type":["string","null"],"enum":["detached","semi_detached","mid_terrace","end_terrace","enclosed_mid_terrace","enclosed_end_terrace",null],"description":"How the dwelling sits in relation to its neighbours."},"tenure":{"type":["string","null"],"enum":["owner_occupied","rented_social","rented_private","unknown",null],"description":"Whether the dwelling is owner occupied or rented, and if rented, socially or privately."},"constructionAge":{"type":["object","null"],"properties":{"startYear":{"type":["integer","null"],"description":"First year of the construction period. Null when the band is open-ended, such as 'before 1900'."},"endYear":{"type":["integer","null"],"description":"Last year of the construction period. Null when the band is open-ended, such as '2007 onwards'."},"midYear":{"type":["integer","null"],"description":"Midpoint of the construction period, for when a single year is needed."},"isExact":{"type":"boolean","description":"True when the certificate gives an exact year of construction rather than a band."}},"required":["startYear","endYear","midYear","isExact"],"description":"The period the dwelling was built in, as a year range."},"constructionAgeBandExternal":{"type":["string","null"],"description":"The construction age band exactly as the certificate words it, for example 'England and Wales: 1930-1949' or 'before 1919'."},"habitableRooms":{"type":["integer","null"],"description":"Number of habitable rooms."},"heatedRooms":{"type":["integer","null"],"description":"Number of heated rooms."},"floorLevel":{"type":["string","null"],"description":"Which floor the dwelling is on, as recorded on the certificate. Recorded for flats."},"flatTopStorey":{"type":["boolean","null"],"description":"True when the flat is on the top storey of its building."},"flatStoreyCount":{"type":["integer","null"],"description":"Number of storeys in the building the flat is in."},"extensionCount":{"type":["integer","null"],"description":"Number of extensions the dwelling has."},"openFireplaces":{"type":["integer","null"],"description":"Number of open fireplaces."},"floorHeight":{"type":["number","null"],"description":"Average floor-to-ceiling height, in metres."},"glazing":{"type":"object","properties":{"type":{"type":["string","null"],"enum":["single","double_pre_2002","double_post_2002","double_unknown","triple","secondary","secondary_low_emissivity","not_defined",null],"description":"What kind of glazing is fitted, with double glazing split by whether it was installed before 2002."},"proportion":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Percentage of the windows that are double or triple glazed, from 0 to 100."},"area":{"type":["string","null"],"enum":["much_less_than_typical","less_than_typical","normal","more_than_typical","much_more_than_typical",null],"description":"How much glazing the dwelling has compared with a typical property of its type. Only older assessments carry it, as the current assessment procedure no longer records it."}},"required":["type","proportion","area"],"description":"The dwelling's glazing."},"lowEnergyLighting":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Percentage of the light fittings that are low energy, from 0 to 100."},"spaceHeatingDemand":{"type":["number","null"],"description":"Annual space heating demand, in kWh per year. Scotland only."},"waterHeatingDemand":{"type":["number","null"],"description":"Annual water heating demand, in kWh per year. Scotland only."},"threeYearEnergyCostCurrent":{"type":["number","null"],"description":"Estimated energy cost over three years at the assessed efficiency, in GBP. Scotland only."},"threeYearEnergySavingPotential":{"type":["number","null"],"description":"Estimated energy saving over three years if the recommended improvements are carried out, in GBP. Scotland only."},"impactLoftInsulation":{"type":["number","null"],"description":"Estimated change in SAP score from installing loft insulation. Scotland only."},"impactCavityWallInsulation":{"type":["number","null"],"description":"Estimated change in SAP score from installing cavity wall insulation. Scotland only."},"impactSolidWallInsulation":{"type":["number","null"],"description":"Estimated change in SAP score from installing solid wall insulation. Scotland only."},"lzcEnergySources":{"type":["string","null"],"description":"The low and zero carbon energy sources present, as described on the certificate. Scotland only."}},"required":["builtForm","tenure","constructionAge","constructionAgeBandExternal","habitableRooms","heatedRooms","floorLevel","flatTopStorey","flatStoreyCount","extensionCount","openFireplaces","floorHeight","glazing","lowEnergyLighting","spaceHeatingDemand","waterHeatingDemand","threeYearEnergyCostCurrent","threeYearEnergySavingPotential","impactLoftInsulation","impactCavityWallInsulation","impactSolidWallInsulation","lzcEnergySources"],"description":"Details that apply to dwellings only: construction, rooms, glazing and the Scotland-specific measures. Null on non-domestic certificates and Display Energy Certificates."},"benchmarks":{"type":["object","null"],"properties":{"newBuild":{"type":["number","null"],"description":"The benchmark rating an equivalent new building would achieve. On Scottish certificates this is in kg CO2 per m² per year."},"newBuildBand":{"type":["string","null"],"enum":["A+","A","B+","B","C+","C","D+","D","E+","E","F+","F","G",null],"description":"Band for the new build benchmark. Scotland only."},"existingStock":{"type":["string","null"],"description":"The benchmark for typical existing stock. England and Wales only."},"standardEmissions":{"type":["number","null"],"description":"Standard Emission Rate: the improvement-adjusted baseline the building is measured against, in kg CO2 per m² per year. England and Wales only."},"targetEmissions":{"type":["number","null"],"description":"Target Emission Rate: the emissions the Building Regulations require of this building, in kg CO2 per m² per year."},"typicalEmissions":{"type":["number","null"],"description":"Typical Emission Rate: the industry comparison baseline, in kg CO2 per m² per year. England and Wales only."},"buildingEmissions":{"type":["number","null"],"description":"Building Emission Rate: the building's own annual emissions, in kg CO2 per m² per year."},"buildingLevel":{"type":["integer","null"],"minimum":3,"maximum":5,"description":"How complex the building is to assess, from 3 to 5. Level 3 covers small, naturally ventilated buildings, level 4 those with more sophisticated heating and cooling, and level 5 the most complex, such as airports and large shopping centres, which need dynamic simulation modelling. England and Wales only."},"buildingEnvironment":{"type":["string","null"],"enum":["heating_and_natural_ventilation","heating_and_mechanical_ventilation","air_conditioning","mixed_mode_natural","mixed_mode_mechanical","unconditioned",null],"description":"How the building is serviced for heating, ventilation and cooling, which sets the basis for its emissions calculation."},"meets2002Standard":{"type":["boolean","null"],"description":"True when the building meets the 2002 Scottish building standards. Scotland only."},"electricitySource":{"type":["string","null"],"description":"Where the building's electricity comes from. Scotland only."},"approximateEnergyUse":{"type":["number","null"],"description":"Total energy use less on-site generation, in kWh per m² per year. Scotland only."}},"required":["newBuild","newBuildBand","existingStock","standardEmissions","targetEmissions","typicalEmissions","buildingEmissions","buildingLevel","buildingEnvironment","meets2002Standard","electricitySource","approximateEnergyUse"],"description":"Benchmarks and complexity classification for non-domestic buildings. Null on domestic certificates."},"scotlandNativeRating":{"type":["object","null"],"properties":{"currentRating":{"type":"number","description":"The building's energy performance rating calculated with Scottish weather data, in kg CO2 per m² per year."},"currentBand":{"type":"string","enum":["A+","A","B+","B","C+","C","D+","D","E+","E","F+","F","G"],"description":"Band for that rating. Scotland uses half-bands such as B+ and C+, and a carbon neutral building is published here as `A+`."},"potentialRating":{"type":["number","null"],"description":"The rating the building would reach if the recommended improvements were carried out. Scotland publishes this; England and Wales does not."},"potentialBand":{"type":["string","null"],"enum":["A+","A","B+","B","C+","C","D+","D","E+","E","F+","F","G",null],"description":"Band for the achievable rating."}},"required":["currentRating","currentBand","potentialRating","potentialBand"],"description":"Scotland's own non-domestic rating, calculated with Scottish weather data. Null on domestic certificates and on England and Wales certificates."},"operationalPerformance":{"type":["object","null"],"properties":{"currentRating":{"type":"number","description":"Operational rating for the current year, comparing the building's carbon dioxide emissions with the benchmark for its type. 100 is typical for the type and lower is better. A value of 9999 means the assessment is incomplete."},"ratingBand":{"type":"string","enum":["A+","A","B+","B","C+","C","D+","D","E+","E","F+","F","G"],"description":"Band for the operational rating. Display Energy Certificates run A to G, with no A+."},"yr1Rating":{"type":["number","null"],"description":"Operational rating for the previous year."},"yr2Rating":{"type":["number","null"],"description":"Operational rating for the year before that."},"thermalUsage":{"type":["object","null"],"properties":{"actual":{"type":"number","description":"Measured annual thermal fuel use, in kWh per m² per year."},"typical":{"type":"number","description":"Benchmark thermal fuel use for a building of this type, in kWh per m² per year."}},"required":["actual","typical"],"description":"Thermal fuel use measured against its benchmark."},"electricalUsage":{"type":["object","null"],"properties":{"actual":{"type":"number","description":"Measured annual electricity use, in kWh per m² per year."},"typical":{"type":"number","description":"Benchmark electricity use for a building of this type, in kWh per m² per year."}},"required":["actual","typical"],"description":"Electricity use measured against its benchmark."},"renewablesThermalPercentage":{"type":["number","null"],"description":"Percentage of the building's heat supplied from renewable sources."},"renewablesElectricalPercentage":{"type":["number","null"],"description":"Percentage of the building's electricity supplied from renewable sources."},"buildingCategory":{"type":"array","items":{"type":"string","enum":["C1","C2","C3","C4","C5","C6","H1","H2","H3","H4","H5","H6","H7","H8","S1","S2","S3","S4","S5","S6","S7","S8","S9","S10","W1","W2","W3","W4","W5"]},"description":"The CIBSE TM46 benchmark categories the building is measured against. A mixed-use building carries more than one."},"mainBenchmark":{"type":["string","null"],"description":"The main benchmark category in words, for example 'General Office'."},"occupancyLevel":{"type":["string","null"],"description":"How heavily the building is occupied during its operating hours."},"nominatedDate":{"type":["string","null"],"description":"The reference date the assessor chose for this assessment, as an ISO 8601 date."},"assessmentEndDate":{"type":["string","null"],"description":"The last day of the 12-month period the assessment covers, as an ISO 8601 date."}},"required":["currentRating","ratingBand","yr1Rating","yr2Rating","thermalUsage","electricalUsage","renewablesThermalPercentage","renewablesElectricalPercentage","buildingCategory","mainBenchmark","occupancyLevel","nominatedDate","assessmentEndDate"],"description":"Operational performance taken from the building's metered energy use. Null on domestic and non-domestic certificates."},"recommendations":{"type":"array","items":{"type":"object","properties":{"sequence":{"type":"integer","description":"Position in the recommended order. Carrying the measures out in this order gives the most cost-effective path."},"measure":{"type":["string","null"],"enum":["wall_insulation","wall_insulation_combined","cavity_wall_insulation","loft_insulation","floor_insulation_solid","floor_insulation_suspended","flat_roof_insulation","room_in_roof_insulation","party_wall_insulation","draught_proofing","external_doors","double_glazing","replacement_glazing","secondary_glazing","condensing_boiler","gas_condensing_boiler","oil_condensing_boiler","room_to_condensing_boiler","condensing_unit","gas_condensing_unit","warm_air_unit","storage_heaters","storage_heaters_dual_immersion","heating_controls","zone_control","flue_gas_recovery","shower_heat_recovery","cylinder_jacket","cylinder_insulation","cylinder_thermostat","water_heating_controls","heat_pump","heat_pump_underfloor","biomass_boiler","solar_thermal","solar_pv","wind_turbine","pv_battery","pv_diverter","low_energy_lighting",null],"description":"Which improvement is recommended, mapped to a standard set of measures."},"category":{"type":["string","null"],"enum":["insulation","glazing","heating","hot_water","renewables","lighting",null],"description":"What kind of improvement the measure is."},"summary":{"type":["string","null"],"description":"The measure in a short line, as worded on the certificate."},"description":{"type":["string","null"],"description":"The fuller explanation of the measure, as worded on the certificate."},"cost":{"type":["object","null"],"properties":{"min":{"type":["integer","null"],"description":"Low end of the estimated cost, in GBP."},"max":{"type":["integer","null"],"description":"High end of the estimated cost, in GBP."},"currency":{"type":"string","enum":["GBP"],"description":"The currency of the cost figures. Always `GBP`."},"year":{"type":["integer","null"],"description":"The year the cost was estimated in. Treat it as the base year when adjusting for inflation."},"indicative":{"type":["string","null"],"description":"The cost range exactly as the certificate words it, for example '£100 - £350'."}},"required":["min","max","currency","year","indicative"],"description":"What the measure is estimated to cost, as numeric bounds in GBP. Use `cost.year` as the base year when adjusting for inflation."},"saving":{"type":["object","null"],"properties":{"annual":{"type":["integer","null"],"description":"Estimated saving each year, in GBP."},"currency":{"type":"string","enum":["GBP"],"description":"The currency of the saving. Always `GBP`."}},"required":["annual","currency"],"description":"What the measure is estimated to save each year, in GBP."},"projectedRating":{"type":["object","null"],"properties":{"band":{"type":["string","null"],"description":"The energy band the dwelling reaches once this measure is in place, for example 'C'."},"energyScore":{"type":["integer","null"],"description":"The SAP score the dwelling reaches with this measure and every measure before it in the sequence."},"environmentalScore":{"type":["integer","null"],"description":"The environmental impact score the dwelling reaches with this measure and every measure before it."}},"required":["band","energyScore","environmentalScore"],"description":"The rating reached once this measure is carried out. Domestic only."},"greenDealEligible":{"type":["boolean","null"],"description":"True when the measure qualifies for Green Deal financing."},"paybackType":{"type":["string","null"],"enum":["short","medium","long","other",null],"description":"How long the measure takes to pay for itself. Non-domestic only."},"co2Impact":{"type":["string","null"],"enum":["low","medium","high",null],"description":"How much the measure cuts carbon dioxide emissions. Scotland non-domestic only."},"measureCode":{"type":["string","null"],"description":"The code this measure carries on the source certificate. Scottish certificates prefix theirs with 'EPC-', such as 'EPC-R4'."}},"required":["sequence","measure","category","summary","description","cost","saving","projectedRating","greenDealEligible","paybackType","co2Impact","measureCode"],"description":"One recommended improvement, with its cost and saving estimates, its standard measure classification, and the rating it would achieve."},"description":"The improvements recommended on the certificate, in the order they should be carried out. Empty when no recommendations are held for this certificate."},"meesCompliance":{"type":"string","enum":["compliant","at_risk","non_compliant","not_applicable","exempt","unknown"],"description":"Whether the building meets the Minimum Energy Efficiency Standard, worked out from the current rating band, the certificate type and the nation. `compliant` covers bands A to D, `non_compliant` bands F and G, and `at_risk` marks band E as lettable today with no headroom under the expected tightening to C. The standard is SI 2015/962, which covers both domestic and non-domestic private rented property in England and Wales but does not extend to Scotland, and which is assessed on an asset rating rather than the operational rating a Display Energy Certificate carries. Scottish certificates and DECs are therefore `not_applicable`. `exempt` means a registered PRS exemption and appears only on legacy rows; it is never derived from certificate data. `unknown` means there is not enough data to decide."},"createdAt":{"type":"string","description":"When this certificate first appeared in the API, as an ISO 8601 timestamp."},"updatedAt":{"type":"string","description":"When this record was last updated, as an ISO 8601 timestamp."}},"required":["id","certificateType","assessmentMethodology","source","sourceReference","buildingReferenceNumber","locationId","address","coordinates","localAuthority","localAuthorityLabel","constituency","constituencyLabel","county","dataZone","inspectionDate","lodgementDate","validUntil","propertyType","propertyTypeExternal","totalFloorArea","transactionType","transactionTypeExternal","rating","emissions","runningCosts","fabric","systems","domesticDetails","benchmarks","scotlandNativeRating","operationalPerformance","recommendations","meesCompliance","createdAt","updatedAt"],"description":"A single Energy Performance Certificate, covering domestic and non-domestic EPCs and Display Energy Certificates across England, Wales and Scotland. Filter on `certificateType` to narrow to one kind, and on `rating.current.band` to compare efficiency across all three."},"description":"The certificates on this page, in the requested order."},"pagination":{"type":"object","properties":{"total_count":{"type":"integer","description":"Total number of results matching the request across all pages."},"has_more":{"type":"boolean","description":"True when further results exist beyond this page."}},"required":["total_count","has_more"],"description":"Where this page sits in the full result set."}},"required":["object","url","data","pagination"],"description":"A page of EPC certificates matching the search."},"EPCQueryRequest":{"type":"object","properties":{"area":{"type":"array","items":{"$ref":"#/components/schemas/EPCAreaFilter"},"description":"Geographic filters. A certificate matches when it falls in any one of them."},"query":{"type":"array","items":{"$ref":"#/components/schemas/EPCQueryOperator"},"description":"Field filters. Every entry must hold, and they apply on top of the geographic filters."},"sort":{"type":"array","items":{"$ref":"#/components/schemas/EPCSort"},"maxItems":3,"description":"How to order the results, applied in the order given. Up to 3 keys. Defaults to the most recently lodged certificate first.","example":[{"field":"lodgementDate","order":"desc"}]},"limit":{"type":"integer","minimum":1,"maximum":10000,"default":25,"description":"Maximum number of items to return. Defaults to 25. Minimum 1, maximum 10000.","example":25},"offset":{"type":"integer","minimum":0,"maximum":100000,"default":0,"description":"Number of results to skip before the first one returned. Defaults to 0. Maximum 100000.","example":0},"attributes":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Names of the fields to return, as an array or as one comma-separated string. Every response carries the complete certificate, so naming fields does not narrow the payload."}},"description":"A search over EPC certificates: where to look, what to match, how to order it and how much to return."},"EPCAreaFilter":{"anyOf":[{"$ref":"#/components/schemas/EPCPostcodeAreaFilter"},{"$ref":"#/components/schemas/EPCPointAreaFilter"},{"$ref":"#/components/schemas/EPCPolygonAreaFilter"},{"$ref":"#/components/schemas/EPCLocalAuthorityAreaFilter"}],"description":"One geographic filter. The `type` field picks which of the four forms the rest of the object takes."},"EPCPostcodeAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["postcode"],"description":"Selects the postcode branch. Always `postcode`."},"value":{"type":"string","pattern":"^[A-Z]{1,2}[0-9][0-9A-Z]?(\\s?[0-9][A-Z]{2})?$","description":"A full UK postcode, or just its outward code (the first part, such as `SW1A`). The space is optional and case is not significant; the value is returned upper-cased.","example":"SW1"}},"required":["type","value"],"description":"Match certificates whose postcode starts with the value given, so an outward code covers the whole area."},"EPCPointAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["point"],"description":"Selects the point branch. Always `point`."},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"The centre of the search: latitude first, then longitude, in WGS84 decimal degrees. This is the reverse of the order GeoJSON uses.","example":[51.5074,-0.1278]},"radius":{"type":"number","minimum":1,"maximum":50000,"description":"How far around that point to search, in metres. Minimum 1, maximum 50000.","example":1000}},"required":["type","coordinates","radius"],"description":"Match certificates within a radius of a point."},"EPCPolygonAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["polygon"],"description":"Selects the polygon branch. Always `polygon`."},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"description":"The rings of the polygon. Each position is latitude first, then longitude, in WGS84 decimal degrees, which is the reverse of the order GeoJSON uses. Every ring must close by repeating its first position as the last."}},"required":["type","coordinates"],"description":"Match certificates that fall inside a polygon you supply."},"EPCLocalAuthorityAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["local_authority"],"description":"Selects the local authority branch. Always `local_authority`."},"value":{"type":"string","minLength":2,"maxLength":20,"description":"ONS code for the local authority to search within, for example 'E09000033'."}},"required":["type","value"],"description":"Match certificates in one local authority."},"EPCQueryOperator":{"type":"object","properties":{"operator":{"type":"string","enum":["AND","OR"],"description":"How the groups combine: `AND` needs every group to hold, `OR` needs at least one."},"groups":{"type":"array","items":{"$ref":"#/components/schemas/EPCQueryGroup"},"minItems":1,"description":"The groups to combine. At least one is required."}},"required":["operator","groups"],"description":"Several condition groups combined with one logical operator."},"EPCQueryGroup":{"type":"object","properties":{"conditions":{"type":"array","items":{"$ref":"#/components/schemas/EPCQueryCondition"},"minItems":1,"description":"The conditions in this group. All of them must hold. At least one is required."}},"required":["conditions"],"description":"A set of conditions that must all hold together."},"EPCQueryCondition":{"type":"object","properties":{"field":{"type":"string","enum":["certificateType","currentRatingBand","currentRatingScore","meesCompliance","source","inspectionDate","lodgementDate","localAuthority","propertyType","transactionType","totalFloorArea","postcodeNoSpace","fabric.walls.construction","fabric.walls.insulationType","fabric.walls.insulationPresent","fabric.walls.thermalTransmittance","fabric.roof.roofType","fabric.roof.insulationDepthMm","fabric.roof.insulationPresent","fabric.floor.floorType","fabric.floor.insulationPresent","fabric.mainHeating.systemType","fabric.mainHeating.fuel","fabric.mainHeating.heatPumpType","domesticDetails.builtForm","domesticDetails.tenure","domesticDetails.constructionAge.startYear","domesticDetails.constructionAge.endYear","emissions.co2Current","emissions.co2PerFloorArea","emissions.energyConsumptionCurrent","runningCosts.heating.current","runningCosts.hotWater.current","runningCosts.lighting.current"],"description":"Which field the condition applies to."},"comparator":{"type":"string","enum":["eq","ne","gt","gte","lt","lte","in","nin"],"description":"How `value` is compared with the field. `in` and `nin` test membership of a list; the rest compare against a single value."},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"}]}}],"description":"The value to compare against. Pass an array when the comparator is `in` or `nin`."}},"required":["field","comparator","value"],"description":"A single filter: the field, how to compare it, and what to compare it against."},"EPCSort":{"type":"object","properties":{"field":{"type":"string","enum":["lodgementDate","inspectionDate","currentRatingScore","totalFloorArea","emissions.co2Current","emissions.co2PerFloorArea"],"description":"Which field to sort on."},"order":{"type":"string","enum":["asc","desc"],"description":"The direction to sort in."}},"required":["field","order"],"description":"One sort key and the direction to apply it in."},"AdvancedListing":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier for this listing."},"propertyId":{"type":["string","null"],"description":"Identifier of the physical property this listing is matched to. Null when it has not been matched."},"locationId":{"type":["string","null"],"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). Null when the listing has not been matched to a location."},"status":{"type":"string","enum":["live","removed","sstc","under_offer","sold","reserved"],"description":"Where the listing stands in the sale or letting process. 'live': actively marketed. 'sstc': sold subject to contract. 'under_offer': an offer has been accepted but contracts have not been exchanged. 'reserved': reserved, most often on a new build. 'sold': the sale has completed. 'removed': withdrawn, or no longer present in the source feed.","example":"live"},"type":{"type":"string","enum":["sale","rent"],"description":"Whether the property is advertised for sale or to rent. This governs how to read the price: an asking price for 'sale', the rent quoted by the source for 'rent'.","example":"sale"},"publishedDate":{"type":["string","null"],"format":"date-time","description":"When the listing was first published by the source, as an ISO 8601 timestamp. Null when the source does not publish one.","example":"2024-01-15T10:30:00Z"},"removedDate":{"type":["string","null"],"format":"date-time","description":"When the listing was removed from the source, as an ISO 8601 timestamp. Null while the listing is still there.","example":"2024-01-15T10:30:00Z"},"provider":{"type":"string","description":"Identifier for the data provider that supplied this listing. Returned only to API keys entitled to source data."},"key":{"type":"string","description":"The listing's own reference within the provider's system. Returned only to API keys entitled to source data."},"sources":{"type":"array","items":{"type":"string"},"description":"The data sources this document draws on. Returned only to API keys entitled to source data."},"tenure":{"$ref":"#/components/schemas/AdvancedListingTenure"},"description":{"type":["string","null"],"description":"The main marketing description written for the property."},"bullets":{"type":"array","items":{"type":"string"},"description":"Key selling points, one per entry."},"isRetirement":{"type":"boolean","description":"True when the property is age-restricted retirement housing."},"isAuction":{"type":"boolean","description":"True when the property is being sold at auction."},"isSharedOwnership":{"type":"boolean","description":"True when the property is offered under shared ownership."},"isNewBuild":{"type":"boolean","description":"True when the property is newly built and has not been lived in."},"seller":{"$ref":"#/components/schemas/AdvancedListingSeller"},"address":{"$ref":"#/components/schemas/AdvancedListingAddress"},"spatial":{"type":["object","null"],"properties":{"lat":{"type":["number","null"],"description":"Latitude of the property in WGS84 decimal degrees."},"lon":{"type":["number","null"],"description":"Longitude of the property in WGS84 decimal degrees."}},"description":"Where the property sits."},"roomDetails":{"$ref":"#/components/schemas/AdvancedListingRoomDetails"},"build":{"$ref":"#/components/schemas/AdvancedListingBuild"},"features":{"type":"array","items":{"type":"object","properties":{"featureId":{"type":"string","description":"Key naming the feature, for example 'TENURE', 'FLOORS' or 'FLOOR_AREA'. Feature keys are an open set that varies by data provider, so treat this as free-form rather than a fixed list.","example":"parking"},"value":{"type":"string","description":"The value stated for the feature, as supplied with the listing. It may be a yes or no answer, a measurement, or a category such as 'Freehold'.","example":"Driveway parking"}},"description":"One property feature stated in the listing, as a key and the value given for it."},"description":"Features stated in the listing, as key and value pairs."},"tags":{"type":"object","additionalProperties":{"type":"boolean"},"description":"Classification flags for the listing. A flag is present and set to true only when it applies."},"pricing":{"$ref":"#/components/schemas/AdvancedListingPricing"},"energyRating":{"$ref":"#/components/schemas/AdvancedListingEnergyRating"},"saleHistory":{"type":"array","items":{"$ref":"#/components/schemas/AdvancedListingSaleHistory"},"description":"Previous sales recorded for the property."},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"description":"One image belonging to a property listing."},"description":"Photographs of the property. Returned only to API keys entitled to listing media."},"floorPlanImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"description":"One image belonging to a property listing."},"description":"Floor plan images. Returned only to API keys entitled to listing media."},"statusHistory":{"type":"array","items":{"$ref":"#/components/schemas/AdvancedListingStatusHistory"},"description":"The statuses this listing has moved through, with the date of each."},"descriptors":{"type":"object","additionalProperties":{},"description":"Attributes read out of the listing's own material, keyed by the extractor that produced them, for example 'residential-council-tax-band'. Each value is the extraction result, or null when the extractor produced nothing usable."}},"description":"A property listing assembled from everything held for it: pricing, rooms, build, tenure, energy rating, media and extracted attributes. Monetary values are in pounds."},"AdvancedListingTenure":{"type":"object","properties":{"type":{"type":["string","null"],"enum":["freehold","leasehold","share_of_freehold","commonhold","feudal",null],"description":"How the property is held, standardised so that one value matches every wording the sources use. Null when the source states no tenure or answers non-committally, such as 'ask agent'."},"typeRaw":{"type":["string","null"],"description":"Tenure exactly as the source stated it, which may carry extra detail such as the number of years left on a lease."}}},"AdvancedListingSeller":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Name of the agent or seller marketing the property."}}},"AdvancedListingAddress":{"type":"object","properties":{"displayAddress":{"type":["string","null"],"description":"The address as supplied with the listing, ready to display."},"postcode":{"type":["string","null"],"description":"Full postcode for the property."},"outcode":{"type":["string","null"],"description":"The postcode's outward code (the first part, such as `SW1A`)."},"incode":{"type":["string","null"],"description":"The part of the postcode after the space, such as `1AA`."}}},"AdvancedListingRoomDetails":{"type":"object","properties":{"beds":{"type":["number","null"],"description":"Number of bedrooms."},"baths":{"type":["number","null"],"description":"Number of bathrooms."},"recepts":{"type":["number","null"],"description":"Number of reception rooms, meaning the living, dining and sitting rooms."}}},"AdvancedListingBuild":{"type":"object","properties":{"propertyType":{"type":["string","null"],"description":"What kind of property this is, standardised across providers, for example 'detached', 'flat' or 'bungalow'."},"floorHeight":{"type":["number","null"],"description":"Floor height stated for the property, where the source gives one."},"floors":{"type":["number","null"],"description":"Number of floors, where the source gives one."},"totalFloorArea":{"type":["number","null"],"description":"Total internal floor area in square metres."}}},"AdvancedListingPricing":{"type":"object","properties":{"currency":{"type":["string","null"],"description":"ISO 4217 currency code for the prices in this object. Always `GBP`."},"price":{"type":["number","null"],"description":"Current price in pounds: the asking price for a sale listing, or the rent for a rental. A value of 625000 means £625,000.","example":625000},"pricePerSqft":{"type":["number","null"],"description":"Price per square foot in pounds. Present only when a total floor area is known."},"pricePerSqm":{"type":["number","null"],"description":"Price per square metre in pounds. Present only when a total floor area is known."},"priceHistory":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"When the price change was recorded, as an ISO 8601 timestamp.","example":"2024-01-15T10:30:00Z"},"price":{"type":"number","exclusiveMinimum":0,"description":"The price after the change, in pounds: the revised asking price for a sale listing, or the revised rent for a rental.","example":50000000},"oldPrice":{"type":"number","exclusiveMinimum":0,"description":"The price before the change, in pounds. Not present for the first price recorded for a listing.","example":52000000},"amount":{"type":"number","description":"The new price minus the old one, in pounds, rounded to two decimal places. Negative when the price was cut.","example":-2000000},"percent":{"type":"number","description":"The change as a percentage of the previous price, rounded to two decimal places. Negative when the price was cut, so -3.85 is a cut of 3.85 per cent.","example":-3.85},"direction":{"type":"string","enum":["increase","decrease","nochange"],"description":"Whether the price went up, went down, or stayed the same at this revision.","example":"decrease"}},"description":"One price revision recorded against the listing, with the size of the change in pounds."},"description":"Price revisions for this listing, most recent first."}}},"AdvancedListingEnergyRating":{"type":"object","properties":{"currentEnergyRating":{"type":["string","null"],"description":"Energy Performance Certificate rating for the property as it stands. Usually the band letter from A to G, and in some records the letter followed by the score in brackets."},"potentialEnergyRating":{"type":["string","null"],"description":"Energy Performance Certificate rating recorded as achievable for the property, in the same form as `currentEnergyRating`."},"currentEnergyEfficiency":{"type":["number","null"],"description":"Energy efficiency score behind `currentEnergyRating`, on the 1 to 100 scale."},"potentialEnergyEfficiency":{"type":["number","null"],"description":"Energy efficiency score behind `potentialEnergyRating`, on the same 1 to 100 scale."}}},"AdvancedListingSaleHistory":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"When the sale took place, as an ISO 8601 timestamp.","example":"2024-01-15T10:30:00Z"},"amount":{"type":"number","description":"What the property sold for, in pounds."}}},"AdvancedListingStatusHistory":{"type":"object","properties":{"status":{"type":"string","enum":["live","removed","sstc","under_offer","sold","reserved"],"description":"Where the listing stands in the sale or letting process. 'live': actively marketed. 'sstc': sold subject to contract. 'under_offer': an offer has been accepted but contracts have not been exchanged. 'reserved': reserved, most often on a new build. 'sold': the sale has completed. 'removed': withdrawn, or no longer present in the source feed.","example":"live"},"date":{"type":"string","format":"date-time","description":"When the listing took this status, as an ISO 8601 timestamp.","example":"2024-01-15T10:30:00Z"}}},"ListingAdvancedQueryRequest":{"type":"object","properties":{"area":{"type":"array","items":{"$ref":"#/components/schemas/ListingAreaFilter"},"description":"Areas to search. A listing in any one of them is returned."},"query":{"type":"array","items":{"$ref":"#/components/schemas/ListingQueryOperator"},"description":"Filter on the listing fields. Conditions inside a group are combined by that entry's operator, and separate entries are combined so that a listing matching any of them is returned."},"sort":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["publishedDate","removedDate","pricing.price","pricing.pricePerSqft","pricing.pricePerSqm","roomDetails.beds","roomDetails.baths","build.totalFloorArea","_score","_doc"],"description":"Field to sort by. Only the fields listed here can be sorted on."},"order":{"type":"string","enum":["asc","desc"],"description":"Whether to sort ascending or descending."},"missing":{"type":"string","enum":["_first","_last"],"description":"Where to place listings that have no value for the field. Defaults to `_last`, after the listings that do have one."}},"required":["field","order"]},"maxItems":3,"description":"How to sort the results. Up to 3 fields, applied in the order given.","example":[{"field":"publishedDate","order":"desc"}]},"limit":{"type":"number","minimum":1,"maximum":100,"default":25,"description":"Maximum number of listings to return. Defaults to 25. Minimum 1, maximum 100.","example":25},"offset":{"type":"number","minimum":0,"maximum":10000,"default":0,"description":"Number of results to skip before the first one returned. Defaults to 0. Maximum 10000.","example":0},"attributes":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Fields to include in each listing returned, as an array or as one comma-separated string. Defaults to the full set; naming fewer makes the response smaller.","example":"id,address,pricing,roomDetails,tenure"}},"description":"A search over the aggregated listings: areas to cover, a filter on the listing fields, how to sort, and which fields to return."},"ListingAreaFilter":{"anyOf":[{"$ref":"#/components/schemas/ListingPostcodeAreaFilter"},{"$ref":"#/components/schemas/ListingOutcodeAreaFilter"},{"$ref":"#/components/schemas/ListingPointAreaFilter"},{"$ref":"#/components/schemas/ListingPolygonAreaFilter"},{"$ref":"#/components/schemas/ListingMultiPolygonAreaFilter"}],"description":"One area to search, given as a postcode, an outward code, a circle, a polygon or a set of polygons. Where a request carries several areas, a listing in any of them is returned."},"ListingPostcodeAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["postcode"]},"value":{"type":"string","minLength":2,"maxLength":10,"description":"A full UK postcode. Only listings carrying exactly this postcode are returned; to cover a wider area, use an outward code filter instead.","example":"SW1A 1AA"}},"required":["type","value"]},"ListingOutcodeAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["outcode"]},"value":{"type":"string","minLength":2,"maxLength":4,"description":"An outward code, such as `SW1A`. Returns every listing whose postcode has that outward code.","example":"SW1A"}},"required":["type","value"]},"ListingPointAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["point"]},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"Centre of the search circle: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]},"radius":{"type":"number","exclusiveMinimum":0,"description":"Radius of the search circle around the centre, in metres.","example":1000}},"required":["type","coordinates","radius"]},"ListingPolygonAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"description":"The rings that make up the search area, each position longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order). The first and last position of a ring must match so that it closes. Listings inside the area are returned."}},"required":["type","coordinates"]},"ListingMultiPolygonAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["multipolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}},"description":"Several polygons, each given as its rings of positions, longitude first then latitude, in WGS84 decimal degrees (the GeoJSON order). Listings inside any of the polygons are returned."}},"required":["type","coordinates"]},"ListingQueryOperator":{"type":"object","properties":{"operator":{"type":"string","enum":["AND","OR"],"description":"How the conditions inside each group are combined: `AND` needs every condition to match, `OR` needs any one of them."},"groups":{"type":"array","items":{"$ref":"#/components/schemas/ListingQueryGroup"},"description":"Groups of conditions, each combined by `operator`."}},"required":["operator","groups"]},"ListingQueryGroup":{"type":"object","properties":{"conditions":{"type":"array","items":{"$ref":"#/components/schemas/ListingQueryCondition"},"description":"The conditions in this group."}},"required":["conditions"]},"ListingQueryCondition":{"type":"object","properties":{"field":{"type":"string","description":"Field to filter on, named exactly as it appears in the response, for example `status`, `type`, `roomDetails.beds`, `pricing.price`, `build.propertyType`, `tenure.type`, `address.outcode` or `publishedDate`. A field that cannot be filtered on is rejected with a 400 rather than ignored.","example":"roomDetails.beds"},"comparator":{"type":"string","enum":["eq","ne","gt","gte","lt","lte","in","nin"],"description":"How to compare the field with `value`: equal or not equal, one of or none of a list, or a range. The range comparators (`gt`, `gte`, `lt`, `lte`) apply to numeric and date fields only."},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}],"description":"Value to compare the field against. `in` and `nin` take an array; the other comparators take one value."}},"required":["field","comparator","value"]},"PlanningListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/PlanningApplication"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."},"PlanningApplication":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier for this planning application. Pass it to GET /{applicationIds} to fetch it again.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"provider":{"type":"string","description":"Identifier for the local planning authority that received the application, as a slug of the council name such as 'lambeth' or 'st-albans'. Use the same value in the councils filter on POST /query.","example":"lambeth"},"key":{"type":"string","description":"Reference number the local planning authority assigned to the application. The format varies by council, for example '24/00123/FUL' or 'APP/2024/0001'. This is the reference to quote when contacting the council about the application.","example":"24/00123/FUL"},"sourceId":{"type":"string","description":"Council slug and council reference joined as `provider::key`, for example 'lambeth::24/00123/FUL'. It identifies the application across every council, and is what GET /sources/{sourceIds} accepts.","example":"lambeth::24/00123/FUL"},"status":{"type":"string","enum":["received","pending_validation","invalid","valid","under_consideration","consultation","pending_decision","approved","rejected","withdrawn","appeal","on_hold","expired","unknown"],"description":"How far the application has progressed, normalised so the same value means the same thing at every council. An application is 'received' once the council holds it, 'pending_validation' while the administrative checks are outstanding, then either 'invalid' when those checks fail or 'valid' once it is registered. Assessment runs through 'under_consideration', 'consultation' while neighbours and consultees may comment, and 'pending_decision' once the officer's assessment is finished. It ends at 'approved' (permission granted, possibly with conditions), 'rejected' (permission refused), 'withdrawn' (pulled by the applicant), 'appeal' (taken to the Planning Inspectorate), 'expired' (lapsed with no decision issued) or 'on_hold' (paused by the council). 'unknown' means no status could be established; read statusExternal for the council's own wording where there is any.","example":"approved"},"statusExternal":{"type":["string","null"],"description":"The council's own status wording, exactly as published and before normalisation, for example 'Application Permitted'. Terminology differs from council to council. Read it when status is 'unknown', or when the exact wording matters. Null when the council published no status text.","example":"Application Permitted"},"statusConfidence":{"type":["number","null"],"description":"How certain the mapping from statusExternal to status is, from 0 to 1, with higher values meaning more certain. Null when no mapping was performed.","example":0.95},"type":{"type":["string","null"],"description":"Normalised type of consent the application seeks, such as a householder application, a listed building consent or a prior approval. Null when the type could not be determined. See typeExternal for the council's own wording.","example":"Full Planning"},"typeExternal":{"type":["string","null"],"description":"The council's own wording for the application type, exactly as published and before normalisation. Councils name the same type differently, so this is the value to read when type is null or when the exact wording matters. Null when the council published no type text.","example":"Full Planning Permission"},"developmentCategory":{"type":["string","null"],"description":"Broad sector the proposed development falls into, worked out automatically from the description and the application type. Useful for grouping applications by the kind of development rather than the kind of consent. Null when the development could not be categorised.","example":"Residential"},"typeConfidence":{"type":["number","null"],"description":"How certain the mapping from typeExternal to type is, from 0 to 1, with higher values meaning more certain. Null when no mapping was performed.","example":0.92},"description":{"type":["string","null"],"description":"The proposed works in the applicant's or the council's own words, for example 'Erection of a two-storey rear extension and loft conversion with rear dormer'. How much detail this carries varies by council. Null when the source published no description.","example":"Erection of a two-storey rear extension and loft conversion with rear dormer"},"address":{"type":["object","null"],"properties":{"line1":{"type":["string","null"],"description":"First line of the site address."},"line2":{"type":["string","null"],"description":"Second line of the site address."},"line3":{"type":["string","null"],"description":"Third line of the site address."},"line4":{"type":["string","null"],"description":"Fourth line of the site address."},"town":{"type":["string","null"],"description":"Town or city the site sits in."},"county":{"type":["string","null"],"description":"County the site sits in."},"postcode":{"type":["string","null"],"description":"Postcode of the site.","example":"SW1A 1AA"},"ward":{"type":["string","null"],"description":"Electoral ward the site falls in."},"formattedAddress":{"type":["string","null"],"description":"The whole site address on one line, where the planning authority publishes it that way."}},"description":"Address of the application site as the planning authority publishes it. Which lines are filled in varies by council: some publish a fully structured address, others only a single line in formattedAddress. Null when the council published no address."},"people":{"type":["object","null"],"properties":{"applicants":{"type":"array","items":{"$ref":"#/components/schemas/PlanningApplicant"},"description":"The people or organisations that submitted the application."},"agents":{"type":"array","items":{"$ref":"#/components/schemas/PlanningAgent"},"description":"The planning agents or consultants acting for the applicant."}},"description":"The applicants and planning agents named on the application. Only names and organisations are returned; contact details such as telephone numbers and email addresses are removed. Null when the council named nobody."},"caseOfficer":{"type":["string","null"],"description":"Name of the planning officer handling the assessment. Null when the council did not publish one.","example":"J. Smith"},"constraints":{"type":["array","null"],"items":{"$ref":"#/components/schemas/PlanningConstraint"},"description":"Designations recorded against the site, such as a conservation area, a listed building, a tree preservation order or green belt. Null when the council published none."},"relatedCases":{"type":["array","null"],"items":{"$ref":"#/components/schemas/PlanningRelatedCase"},"description":"Other planning cases tied to this one, such as an appeal, an amendment, or another application at the same site. Null when none were recorded."},"receivedDate":{"type":["string","null"],"description":"When the planning authority received the application, as an ISO 8601 timestamp. This is the submission date and usually the earliest date on the application. Filter on it with receivedDateFrom and receivedDateTo. Null when the council did not publish the date.","example":"2024-03-15T00:00:00.000Z"},"validatedDate":{"type":["string","null"],"description":"When the planning authority confirmed the application was complete and registered it for assessment, as an ISO 8601 timestamp. Null when the council did not publish the date.","example":"2024-03-20T00:00:00.000Z"},"decidedDate":{"type":["string","null"],"description":"When the planning authority issued its decision, as an ISO 8601 timestamp. Null while the application is undecided, or when the council did not publish the date.","example":"2024-06-15T00:00:00.000Z"},"consultationStartDate":{"type":["string","null"],"description":"When the public consultation period opened, as an ISO 8601 timestamp. Null when the council did not publish the date.","example":"2024-04-01T00:00:00.000Z"},"consultationEndDate":{"type":["string","null"],"description":"When the public consultation period closed, as an ISO 8601 timestamp. Null when the council did not publish the date.","example":"2024-04-22T00:00:00.000Z"},"expiryDate":{"type":["string","null"],"description":"When the permission lapses if the development has not begun, as an ISO 8601 timestamp. Null when no expiry applies or the council did not publish one.","example":"2027-06-15T00:00:00.000Z"},"appealedDate":{"type":["string","null"],"description":"When an appeal was lodged with the Planning Inspectorate, as an ISO 8601 timestamp. Null when no appeal has been lodged.","example":"2024-09-01T00:00:00.000Z"},"appealedStatus":{"type":["string","null"],"description":"Where the appeal has got to, in the wording used by the Planning Inspectorate or the council, for example 'Appeal Lodged' or 'Appeal Dismissed'. These values are not normalised. Null when no appeal has been lodged or no status was published.","example":"Appeal Lodged"},"spatial":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["Point"],"description":"Geometry type discriminator. Always `Point`."},"coordinates":{"type":"array","items":{"type":"number"},"description":"A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order)."}},"required":["type","coordinates"],"description":"Centre point of the application site, as a GeoJSON Point (RFC 7946). Not present when no point is held for the application. For the site boundary rather than its centre, see spatialFeatures.","example":{"type":"Point","coordinates":[-0.1278,51.5074]}},"spatialFeatures":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["FeatureCollection"],"description":"Object type discriminator. Always `FeatureCollection`."},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"],"description":"Object type discriminator. Always `Feature`."},"geometry":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Point"],"description":"Geometry type discriminator. Always `Point`."},"coordinates":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"description":"A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]}},"required":["type","coordinates"],"additionalProperties":false,"description":"A single location expressed as a GeoJSON Point geometry.","title":"GeoJSON Point","example":{"type":"Point","coordinates":[-0.1278,51.5074]}},{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"],"description":"Geometry type discriminator. Always `Polygon`."},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"description":"A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]},"minItems":4},"minItems":1,"description":"The rings that make up the polygon. The first ring is the outer boundary and any further rings are holes inside it. Each ring needs at least four positions and closes by repeating its first position as the last."}},"required":["type","coordinates"],"additionalProperties":false,"description":"An area expressed as a GeoJSON Polygon geometry.","title":"GeoJSON Polygon","example":{"type":"Polygon","coordinates":[[[-0.128,51.507],[-0.127,51.507],[-0.127,51.508],[-0.128,51.508],[-0.128,51.507]]]}},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"],"description":"Geometry type discriminator. Always `MultiPolygon`."},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"description":"A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]},"minItems":4},"minItems":1},"minItems":1,"description":"One entry per polygon, each holding that polygon's rings in the same form as a Polygon geometry."}},"required":["type","coordinates"],"additionalProperties":false,"description":"Several separate areas expressed as a single GeoJSON MultiPolygon geometry.","title":"GeoJSON MultiPolygon"},{"type":"null"}],"description":"Shape of this feature: a Point for a site centre, a Polygon for a single boundary, or a MultiPolygon where the site is in several separate parts. Null when the source geometry could not be read."},"properties":{"type":"object","additionalProperties":{},"description":"Whatever the planning authority published alongside the geometry, such as an area measurement, a boundary description or a source attribution. The keys vary by council."}},"required":["type","geometry"]},"description":"The features making up the site geometry. A site in several separate parts arrives as one MultiPolygon feature rather than as several features."}},"required":["type","features"],"description":"Boundary of the application site, as a GeoJSON FeatureCollection (RFC 7946). Not present when the planning authority published no boundary; spatial still gives the centre point where one is held."},"distance":{"type":["number","null"],"description":"How far the application site is from the centre given in a `near` filter, in metres. Results carrying it are ordered closest first. Null when the request did not use `near`.","example":95},"documents":{"type":"array","items":{"$ref":"#/components/schemas/PlanningDocument"},"description":"Documents the planning authority published for the application: submitted plans, decision notices, consultation responses and supporting material. Empty when none have been collected."},"statusHistory":{"type":"array","items":{"$ref":"#/components/schemas/PlanningStatusHistory"},"description":"Every recorded status change for the application, newest change first, giving the trail of how it moved through the process. Empty when the source council publishes no history."},"extractions":{"type":["object","null"],"properties":{"decision":{"$ref":"#/components/schemas/PlanningDecisionExtractionEnvelope"},"development":{"$ref":"#/components/schemas/PlanningDevelopmentExtractionEnvelope"},"s106":{"$ref":"#/components/schemas/PlanningS106ExtractionEnvelope"},"officerAssessment":{"$ref":"#/components/schemas/PlanningOfficerAssessmentExtractionEnvelope"},"consulteeResponses":{"$ref":"#/components/schemas/PlanningConsulteeResponsesExtractionEnvelope"},"coverage":{"$ref":"#/components/schemas/PlanningExtractionCoverage"}},"required":["decision","development","s106","officerAssessment","consulteeResponses","coverage"],"description":"Structured, quote-backed data read out of the application's documents: the decision and any refusal reasons, what is being built, section 106 obligations, the case officer's assessment and the consultee responses. Present only when 'extractions' is requested through the include parameter on GET or the include array on POST /query. Each part is null when that extraction is not available, and coverage reports how many parts are present and how many have been verified."},"images":{"type":"array","items":{"$ref":"#/components/schemas/PlanningImage"},"description":"Plans, elevations and photographs taken from the application's documents, deduplicated, each with an address that can be rendered directly. Present only when 'images' is requested through the include parameter. Empty when no images have been extracted for the application."},"enrichment":{"type":["object","null"],"properties":{"classification":{"type":"array","items":{"$ref":"#/components/schemas/PlanningClassificationReasoning"},"description":"How the application's type, status and development category were decided, most recent run first, with the certainty and the doubts recorded at the time. Empty when no run was recorded for the application."},"semanticChunks":{"type":"array","items":{"$ref":"#/components/schemas/PlanningSemanticChunk"},"description":"How the application's documents were divided into sections, with a written summary of each. Carries structure and summaries only, not the document text. Empty when the application's documents have not been segmented."}},"required":["classification","semanticChunks"],"description":"How the application was classified and how its documents were segmented and summarised. Present only when 'enrichment' is requested through the include parameter. Either part is empty when that step has not run for the application."},"createdAt":{"type":"string","description":"When this application first appeared in the API, as an ISO 8601 timestamp. This is not the date the council received it; see receivedDate for that.","example":"2024-06-01T14:30:00.000Z"},"updatedAt":{"type":"string","description":"When this application was last updated, as an ISO 8601 timestamp. It moves when the planning authority publishes something new, such as a status change, a further document or an amended description.","example":"2024-08-15T09:00:00.000Z"}},"required":["id","provider","key","sourceId","status","createdAt","updatedAt"]},"PlanningApplicant":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Name of the applicant."},"company":{"type":["string","null"],"description":"Company or organisation the applicant acts for, where named."}}},"PlanningAgent":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Name of the planning agent."},"organisation":{"type":["string","null"],"description":"Company or practice the agent works for, where named."}}},"PlanningConstraint":{"type":"object","properties":{"name":{"type":["string","null"],"description":"Name of the constraint as the planning authority records it."},"description":{"type":["string","null"],"description":"Human-readable explanation of the constraint."},"type":{"type":["string","null"],"description":"Kind of constraint, for example 'Conservation Area' or 'Listed Building'."},"status":{"type":["string","null"],"description":"Standing of the constraint in the planning authority's own wording, which is not normalised."}}},"PlanningRelatedCase":{"type":"object","properties":{"type":{"type":["string","null"],"description":"How the other case relates to this one, for example 'appeal', 'amendment' or 'linked'."},"value":{"type":["string","null"],"description":"Reference number of the related case."},"url":{"type":["string","null"],"description":"Address at which the planning authority publishes the related case, where it gives one."}}},"PlanningDocument":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier for this document record.","example":"d1e2f3a4-b5c6-7890-1234-567890abcdef"},"planningApplicationId":{"type":"string","format":"uuid","description":"Identifier of the planning application this document belongs to.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"fileName":{"type":"string","description":"File name of the document as published by the planning authority. The extension gives the format.","example":"Decision_Notice.pdf"},"documentCategory":{"type":["string","null"],"description":"Broad category of the document: 'application_form', 'drawing_plan', 'design_statement', 'technical_assessment', 'legal_financial', 'consultation', 'decision', 'appeal', 'correspondence' or 'other'. Null when the document has not been categorised.","example":"decision"},"documentTypeDetailed":{"type":["string","null"],"description":"More specific type within the category, for example 'decision_notice', 'floor_plan' or 'flood_risk_assessment'. The value 'unclassified' means the category is known but the specific type could not be determined.","example":"decision_notice"},"sourceUrl":{"type":"string","description":"Address at which the planning authority publishes this document. Council sites may require cookies or a session, and an address may stop resolving over time.","example":"https://planning.lambeth.gov.uk/documents/12345/Decision_Notice.pdf"},"fileSize":{"type":["number","null"],"description":"Size of the file in bytes. Null when the source did not state a size.","example":245760},"pageCount":{"type":["number","null"],"description":"Number of pages in the document. Null when the page count is not known.","example":3},"fileUrl":{"type":["string","null"],"description":"Address of the stored copy of the document, served from a content delivery network and needing no signed parameters, so it can be rendered straight in a browser. Present only when 'content' is requested through the include parameter, and null when no copy is stored; fall back to sourceUrl in that case.","example":"https://atlas.cdn.vepler.com/planning/lambeth/24-00123-FUL/decision-notice.pdf"},"ocrUrl":{"type":["string","null"],"description":"Address of the document's text, extracted and served as Markdown from the same content delivery network. Present only when 'content' is requested through the include parameter, and null when no text has been extracted from the document.","example":"https://atlas.cdn.vepler.com/planning/lambeth/24-00123-FUL/decision-notice.md"},"createdAt":{"type":"string","description":"When this document record first appeared in the API, as an ISO 8601 timestamp.","example":"2024-06-01T14:30:00.000Z"}},"required":["id","planningApplicationId","fileName","sourceUrl","createdAt"]},"PlanningStatusHistory":{"type":"object","properties":{"id":{"type":"string","description":"Identifier for this status change.","example":"h1i2j3k4-l5m6-7890-nopq-rstuvwxyz123"},"applicationId":{"type":"string","description":"Identifier of the planning application this status change belongs to.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890"},"status":{"type":"string","description":"The normalised status the application moved to at this point in its history.","example":"approved"},"statusExternal":{"type":["string","null"],"description":"The council's own wording for that status, before normalisation. Null when the council published no wording.","example":"Application Permitted"},"changedAt":{"type":"string","description":"When the planning authority recorded the change, as an ISO 8601 timestamp.","example":"2024-07-15T10:00:00.000Z"},"createdAt":{"type":"string","description":"When this status change first appeared in the API, as an ISO 8601 timestamp.","example":"2024-07-16T08:00:00.000Z"}},"required":["id","applicationId","status","changedAt","createdAt"]},"PlanningDecisionExtractionEnvelope":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["extracted","verified"],"description":"How far the extraction has been checked: 'extracted' was read out of the documents automatically and has not been checked since, 'verified' has been through a second pass that confirmed it against the source. Weight a verified extraction above an extracted one."},"schemaVersion":{"type":"integer","description":"Version of the extraction schema this payload follows."},"modelConfidence":{"type":["number","null"],"description":"How certain the extraction is, from 0 to 1, with higher values meaning more certain. Null when no score was recorded."},"selfConfidence":{"type":"string","enum":["high","medium","low"],"description":"How well the source supported the extraction: 'high' one unambiguous statement carries it, 'medium' inferred from format or surrounding text with some ambiguity, 'low' faint or conflicting signals that are worth checking."},"uncertainty":{"type":["string","null"],"description":"Note naming the ambiguity that was met while extracting. Null when none was recorded."},"snapshotDate":{"type":"string","description":"Date of the extraction, as an ISO 8601 date (YYYY-MM-DD).","example":"2024-08-15"},"extractedAt":{"type":["string","null"],"description":"When the extraction was produced, as an ISO 8601 timestamp. Null when the time was not recorded."},"verifiedAt":{"type":["string","null"],"description":"When the extraction was verified, as an ISO 8601 timestamp. Null when it has not been verified."},"data":{"$ref":"#/components/schemas/PlanningDecisionExtraction"}},"required":["status","schemaVersion","modelConfidence","selfConfidence","uncertainty","snapshotDate","extractedAt","verifiedAt","data"],"description":"The outcome, the conditions and any refusal reasons, read from the decision notice. Null when no decision extraction is available for this application."},"PlanningDecisionExtraction":{"type":"object","properties":{"outcome":{"type":"object","properties":{"value":{"type":"string","enum":["granted","granted_with_conditions","refused","withdrawn","split_decision","no_decision_required"],"description":"What the planning authority decided. 'split_decision' means one application drew different outcomes for different parts of the proposal, such as a partial refusal. 'no_decision_required' covers permitted-development confirmations and applications determined invalid."},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"What the planning authority decided, taken from the formal notice."},"decisionDate":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"When the decision was issued, as an ISO 8601 date (YYYY-MM-DD). Null when the notice omits it."},"decisionType":{"type":["object","null"],"properties":{"value":{"type":"string","enum":["delegated","committee","appeal","called_in"],"description":"Route by which the decision was reached: 'delegated' under officer authority, 'committee' by the planning committee, 'appeal' by the Planning Inspectorate, 'called_in' by the Secretary of State."},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Route by which the decision was reached. Null when the notice omits it."},"validityYears":{"type":["object","null"],"properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Number of years the permission stays valid for. Null when the notice omits it."},"conditions":{"type":"array","items":{"$ref":"#/components/schemas/PlanningDecisionCondition"},"description":"Every numbered condition attached to the decision. Empty when none were imposed."},"refusalReasons":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"]},"description":"The numbered reasons for refusal, each quoted from the notice. Empty unless the outcome was refusal."},"appealRights":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"The appeal-rights wording printed on the decision notice. Null when the notice carries none."}},"required":["outcome","decisionDate","decisionType","validityYears","conditions","refusalReasons","appealRights"]},"ExtractionCitation":{"type":["object","null"],"properties":{"quote":{"type":"string","description":"The words copied from the source document, unaltered, that carry this value.","example":"The application is hereby REFUSED for the following reasons"},"documentId":{"type":"string","description":"Identifier of the source document the quote was taken from.","example":"decision_notice_001"},"documentCategory":{"type":"string","description":"Category of that source document, for example 'decision', 'officer_report' or 'legal_financial'.","example":"decision"},"context":{"type":"string","description":"Up to 50 characters of the source text before the quote joined to up to 50 characters after it, so a phrase that occurs more than once in the source can be located precisely."}},"required":["quote","documentId","documentCategory","context"],"description":"Where in the documents this value comes from. Null when the value was inferred, or drawn from more than one place, so no single quote carries it."},"PlanningDecisionCondition":{"type":"object","properties":{"number":{"type":"integer","description":"Condition number as printed on the decision notice, counting from 1."},"body":{"type":"object","properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Full text of the condition as written on the decision notice."},"reason":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"The reason given for imposing the condition. Null when the notice gives none."},"triggerStage":{"type":["object","null"],"properties":{"value":{"type":"string","enum":["pre_commencement","pre_occupation","ongoing","compliance_with_plans","other"],"description":"Point at which a condition must be satisfied: 'pre_commencement' before any works start, 'pre_occupation' before the building is first occupied or used, 'ongoing' for the life of the permission, 'compliance_with_plans' where the work must follow the approved drawings."},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"When the condition must be satisfied. Null when the notice is unclear."}},"required":["number","body","reason","triggerStage"]},"PlanningDevelopmentExtractionEnvelope":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["extracted","verified"],"description":"How far the extraction has been checked: 'extracted' was read out of the documents automatically and has not been checked since, 'verified' has been through a second pass that confirmed it against the source. Weight a verified extraction above an extracted one."},"schemaVersion":{"type":"integer","description":"Version of the extraction schema this payload follows."},"modelConfidence":{"type":["number","null"],"description":"How certain the extraction is, from 0 to 1, with higher values meaning more certain. Null when no score was recorded."},"selfConfidence":{"type":"string","enum":["high","medium","low"],"description":"How well the source supported the extraction: 'high' one unambiguous statement carries it, 'medium' inferred from format or surrounding text with some ambiguity, 'low' faint or conflicting signals that are worth checking."},"uncertainty":{"type":["string","null"],"description":"Note naming the ambiguity that was met while extracting. Null when none was recorded."},"snapshotDate":{"type":"string","description":"Date of the extraction, as an ISO 8601 date (YYYY-MM-DD).","example":"2024-08-15"},"extractedAt":{"type":["string","null"],"description":"When the extraction was produced, as an ISO 8601 timestamp. Null when the time was not recorded."},"verifiedAt":{"type":["string","null"],"description":"When the extraction was verified, as an ISO 8601 timestamp. Null when it has not been verified."},"data":{"$ref":"#/components/schemas/PlanningDevelopmentExtraction"}},"required":["status","schemaVersion","modelConfidence","selfConfidence","uncertainty","snapshotDate","extractedAt","verifiedAt","data"],"description":"What is being built or changed: the kind of work, the unit counts, the storeys and the floor areas. Null when no development extraction is available for this application."},"PlanningDevelopmentExtraction":{"type":"object","properties":{"description":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"The formal proposal description, quoted from the source. Null when the source carries none."},"developmentType":{"type":["object","null"],"properties":{"value":{"type":"string","enum":["new_build","extension","conversion","change_of_use","demolition","refurbishment","advertisement","outline","reserved_matters","other"],"description":"What kind of work the proposal involves: 'new_build' an entirely new structure, 'extension' an addition to an existing one, 'conversion' internal restructuring, 'change_of_use' a change of legal use class, 'advertisement' signage, 'outline' consent for the principle of development, 'reserved_matters' the detail that follows an outline consent."},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"What kind of work the proposal involves. Null when the source is too unclear to say."},"useClass":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Use class the site would fall into after the change, as a UK use-class token such as 'C3', 'E(g)' or 'Sui Generis'. Null when the source does not state one."},"unitsTotal":{"type":["object","null"],"properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Total number of new units, residential and commercial together. Null when the proposal is not counted in units."},"unitsResidential":{"type":["object","null"],"properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Number of new dwellings. Null when the proposal is not residential."},"unitsCommercial":{"type":["object","null"],"properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Number of new commercial or other non-residential units. Null when the proposal is not commercial."},"storeys":{"type":["object","null"],"properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Number of storeys above ground. Null when it does not apply or the source does not state it."},"floorAreaGiaSqm":{"type":["object","null"],"properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Gross Internal Area in square metres. Null when the source does not state it."},"floorAreaNiaSqm":{"type":["object","null"],"properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Net Internal Area in square metres. Null when the source does not state it."},"maxHeightMetres":{"type":["object","null"],"properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Greatest height of the building above ground, in metres. Null when the source does not state it."},"hasAffordableHousing":{"type":["object","null"],"properties":{"value":{"type":"boolean"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"True when the proposal provides affordable housing. Null when the proposal is not residential or does not address it."},"affordableUnitsCount":{"type":["object","null"],"properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Number of affordable units. Null when the proposal is not residential or the source does not state it."},"parkingSpaces":{"type":["object","null"],"properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Number of car parking spaces provided. Null when the source does not state it."},"cycleSpaces":{"type":["object","null"],"properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Number of cycle parking spaces provided. Null when the source does not state it."},"isRetrospective":{"type":["object","null"],"properties":{"value":{"type":"boolean"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"True when the application covers work already carried out. Null when the source does not say."}},"required":["description","developmentType","useClass","unitsTotal","unitsResidential","unitsCommercial","storeys","floorAreaGiaSqm","floorAreaNiaSqm","maxHeightMetres","hasAffordableHousing","affordableUnitsCount","parkingSpaces","cycleSpaces","isRetrospective"]},"PlanningS106ExtractionEnvelope":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["extracted","verified"],"description":"How far the extraction has been checked: 'extracted' was read out of the documents automatically and has not been checked since, 'verified' has been through a second pass that confirmed it against the source. Weight a verified extraction above an extracted one."},"schemaVersion":{"type":"integer","description":"Version of the extraction schema this payload follows."},"modelConfidence":{"type":["number","null"],"description":"How certain the extraction is, from 0 to 1, with higher values meaning more certain. Null when no score was recorded."},"selfConfidence":{"type":"string","enum":["high","medium","low"],"description":"How well the source supported the extraction: 'high' one unambiguous statement carries it, 'medium' inferred from format or surrounding text with some ambiguity, 'low' faint or conflicting signals that are worth checking."},"uncertainty":{"type":["string","null"],"description":"Note naming the ambiguity that was met while extracting. Null when none was recorded."},"snapshotDate":{"type":"string","description":"Date of the extraction, as an ISO 8601 date (YYYY-MM-DD).","example":"2024-08-15"},"extractedAt":{"type":["string","null"],"description":"When the extraction was produced, as an ISO 8601 timestamp. Null when the time was not recorded."},"verifiedAt":{"type":["string","null"],"description":"When the extraction was verified, as an ISO 8601 timestamp. Null when it has not been verified."},"data":{"$ref":"#/components/schemas/PlanningS106Extraction"}},"required":["status","schemaVersion","modelConfidence","selfConfidence","uncertainty","snapshotDate","extractedAt","verifiedAt","data"],"description":"The obligations in the section 106 agreement, financial and otherwise. Null when no section 106 extraction is available for this application."},"PlanningS106Extraction":{"type":"object","properties":{"applicationRef":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Application reference quoted in the deed's recitals. Null when the deed cites none."},"deedDate":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"When the deed was executed, as an ISO 8601 date (YYYY-MM-DD). Null when the deed omits it."},"parties":{"type":"array","items":{"$ref":"#/components/schemas/PlanningS106Party"},"description":"Every party to the deed, as listed in its recitals."},"financialObligations":{"type":"array","items":{"$ref":"#/components/schemas/PlanningS106FinancialObligation"},"description":"Every payment or financial contribution the deed requires."},"nonFinancialObligations":{"type":"array","items":{"$ref":"#/components/schemas/PlanningS106NonFinancialObligation"},"description":"Every commitment the deed requires that is not a payment, such as a travel plan, a tenure mix or a phasing requirement."},"hasReviewMechanism":{"type":["object","null"],"properties":{"value":{"type":"boolean"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"True when the deed carries a viability review or recalculation clause. Null when the deed does not address it."},"hasIndexation":{"type":["object","null"],"properties":{"value":{"type":"boolean"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"True when at least one financial obligation rises with an index. Null when the deed does not address it."},"totalFinancialContributionGBP":{"type":["object","null"],"properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Total of the financial contributions, in pounds sterling, where the deed states one. Null when the deed gives no total."}},"required":["applicationRef","deedDate","parties","financialObligations","nonFinancialObligations","hasReviewMechanism","hasIndexation","totalFinancialContributionGBP"]},"PlanningS106Party":{"type":"object","properties":{"name":{"type":"object","properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Legal name of the party, whether an organisation or an individual."},"role":{"type":"object","properties":{"value":{"type":"string","enum":["council","applicant","landowner","mortgagee","leaseholder","other"],"description":"Role the party plays in the deed: 'council' the local planning authority, 'applicant' the developer, 'landowner' the freeholder, 'mortgagee' a lender giving consent, 'leaseholder' a leasehold interest."},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"]}},"required":["name","role"]},"PlanningS106FinancialObligation":{"type":"object","properties":{"label":{"type":"object","properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Short name for the obligation, for example 'Affordable Housing Contribution'."},"amountGBP":{"type":"object","properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Principal sum payable, in pounds sterling."},"indexed":{"type":"object","properties":{"value":{"type":"boolean"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"True when the sum rises with an index rather than staying fixed."},"indexFormula":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Index the sum is tied to, for example 'BCIS All-in TPI'. Null when the sum is not indexed."},"triggerEvent":{"type":"object","properties":{"value":{"type":"string","enum":["commencement","first_occupation","practical_completion","defined_date","signed_date","phased","other"],"description":"Event that makes a financial obligation fall due: 'commencement' the start of works, 'first_occupation' the first person occupying a unit, 'practical_completion' the certificate of practical completion, 'defined_date' a specific calendar date, 'signed_date' the date the deed was signed, 'phased' a trigger per phase of the development."},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"]},"purpose":{"type":"object","properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"What the money is for, for example 'off-site affordable housing'."},"recipient":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Body the money goes to, where the deed names one. Null when the council keeps the funds."}},"required":["label","amountGBP","indexed","indexFormula","triggerEvent","purpose","recipient"]},"PlanningS106NonFinancialObligation":{"type":"object","properties":{"label":{"type":"object","properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Short name for the obligation, for example 'Travel Plan'."},"body":{"type":"object","properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Full text of the obligation clause."},"triggerEvent":{"type":"object","properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"When the obligation must be performed, in the deed's own words."},"party":{"type":"object","properties":{"value":{"type":"string","enum":["applicant","council","owner","other"],"description":"Party who must perform a non-financial obligation."},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"]}},"required":["label","body","triggerEvent","party"]},"PlanningOfficerAssessmentExtractionEnvelope":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["extracted","verified"],"description":"How far the extraction has been checked: 'extracted' was read out of the documents automatically and has not been checked since, 'verified' has been through a second pass that confirmed it against the source. Weight a verified extraction above an extracted one."},"schemaVersion":{"type":"integer","description":"Version of the extraction schema this payload follows."},"modelConfidence":{"type":["number","null"],"description":"How certain the extraction is, from 0 to 1, with higher values meaning more certain. Null when no score was recorded."},"selfConfidence":{"type":"string","enum":["high","medium","low"],"description":"How well the source supported the extraction: 'high' one unambiguous statement carries it, 'medium' inferred from format or surrounding text with some ambiguity, 'low' faint or conflicting signals that are worth checking."},"uncertainty":{"type":["string","null"],"description":"Note naming the ambiguity that was met while extracting. Null when none was recorded."},"snapshotDate":{"type":"string","description":"Date of the extraction, as an ISO 8601 date (YYYY-MM-DD).","example":"2024-08-15"},"extractedAt":{"type":["string","null"],"description":"When the extraction was produced, as an ISO 8601 timestamp. Null when the time was not recorded."},"verifiedAt":{"type":["string","null"],"description":"When the extraction was verified, as an ISO 8601 timestamp. Null when it has not been verified."},"data":{"$ref":"#/components/schemas/PlanningOfficerAssessmentExtraction"}},"required":["status","schemaVersion","modelConfidence","selfConfidence","uncertainty","snapshotDate","extractedAt","verifiedAt","data"],"description":"The case officer's recommendation, the key issues, the policies cited and the levy and section 106 findings. Null when no officer assessment extraction is available for this application."},"PlanningOfficerAssessmentExtraction":{"type":"object","properties":{"recommendation":{"type":"object","properties":{"value":{"type":"string","enum":["grant","grant_with_conditions","refuse","defer","no_recommendation"],"description":"What the case officer recommended. 'defer' covers requests for more information or a site visit. 'no_recommendation' covers procedural reports, such as a determination of validity."},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"The recommendation line from the officer's report."},"caseOfficer":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Name or initials of the case officer. Null when the report names nobody."},"reportDate":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Date on the report, as an ISO 8601 date (YYYY-MM-DD). Null when the report is undated."},"proposalSummary":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"The officer's summary of the proposal. Null when the report has no summary section."},"keyIssues":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"]},"description":"The key issues or material considerations the report sets out, each quoted from it."},"policyRefs":{"type":"array","items":{"type":"object","properties":{"value":{"$ref":"#/components/schemas/PlanningPolicyRef"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"]},"description":"The policies the report cites, with repeats of the same code removed."},"consulteesSummary":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"The officer's summary of the consultee responses. Null when no consultees were involved."},"publicResponseSummary":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"The officer's summary of the public representations. Null when none were received."},"representationsBreakdown":{"type":["object","null"],"properties":{"value":{"$ref":"#/components/schemas/PlanningRepresentationsBreakdown"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Counts of the representations by stance. Null when the report does not break them down."},"cilLiable":{"type":["object","null"],"properties":{"value":{"type":"boolean"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"True when the report finds the proposal liable for the Community Infrastructure Levy. Null when the report is silent."},"cilAmountGBP":{"type":["object","null"],"properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Community Infrastructure Levy liability, in pounds sterling. Null when the proposal is not liable or the report gives no figure."},"s106Required":{"type":["object","null"],"properties":{"value":{"type":"boolean"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"True when the report says a section 106 agreement is required. Null when the report is silent."},"equalityImpactAssessed":{"type":["object","null"],"properties":{"value":{"type":"boolean"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"True when the report includes a Public Sector Equality Duty assessment. Null when the report does not address it."},"habitatRegsAssessed":{"type":["object","null"],"properties":{"value":{"type":"boolean"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"True when the report includes a Habitats Regulations Assessment screening. Null when the report does not address it."},"conclusion":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"The report's closing paragraph, headed Conclusion or Planning Balance, quoted from it. Null when the report has no such section."}},"required":["recommendation","caseOfficer","reportDate","proposalSummary","keyIssues","policyRefs","consulteesSummary","publicResponseSummary","representationsBreakdown","cilLiable","cilAmountGBP","s106Required","equalityImpactAssessed","habitatRegsAssessed","conclusion"]},"PlanningPolicyRef":{"type":"object","properties":{"code":{"type":"string","description":"Policy identifier as cited in the report, for example 'NPPF para 11', 'Policy H5' or 'Local Plan SP1'."},"description":{"type":["string","null"],"description":"Human-readable explanation of what the policy covers. Null when the report cites only the code."}},"required":["code","description"]},"PlanningRepresentationsBreakdown":{"type":"object","properties":{"objections":{"type":"integer","description":"Number of representations objecting to the application."},"support":{"type":"integer","description":"Number of representations supporting the application."},"neutral":{"type":"integer","description":"Number of representations that comment without taking a side."}},"required":["objections","support","neutral"]},"PlanningConsulteeResponsesExtractionEnvelope":{"type":["object","null"],"properties":{"status":{"type":"string","enum":["extracted","verified"],"description":"How far the extraction has been checked: 'extracted' was read out of the documents automatically and has not been checked since, 'verified' has been through a second pass that confirmed it against the source. Weight a verified extraction above an extracted one."},"schemaVersion":{"type":"integer","description":"Version of the extraction schema this payload follows."},"modelConfidence":{"type":["number","null"],"description":"How certain the extraction is, from 0 to 1, with higher values meaning more certain. Null when no score was recorded."},"selfConfidence":{"type":"string","enum":["high","medium","low"],"description":"How well the source supported the extraction: 'high' one unambiguous statement carries it, 'medium' inferred from format or surrounding text with some ambiguity, 'low' faint or conflicting signals that are worth checking."},"uncertainty":{"type":["string","null"],"description":"Note naming the ambiguity that was met while extracting. Null when none was recorded."},"snapshotDate":{"type":"string","description":"Date of the extraction, as an ISO 8601 date (YYYY-MM-DD).","example":"2024-08-15"},"extractedAt":{"type":["string","null"],"description":"When the extraction was produced, as an ISO 8601 timestamp. Null when the time was not recorded."},"verifiedAt":{"type":["string","null"],"description":"When the extraction was verified, as an ISO 8601 timestamp. Null when it has not been verified."},"data":{"$ref":"#/components/schemas/PlanningConsulteeResponsesExtraction"}},"required":["status","schemaVersion","modelConfidence","selfConfidence","uncertainty","snapshotDate","extractedAt","verifiedAt","data"],"description":"Where each consultee stood and how the public representations broke down. Null when no consultee extraction is available for this application."},"PlanningConsulteeResponsesExtraction":{"type":"object","properties":{"responses":{"type":"array","items":{"$ref":"#/components/schemas/PlanningConsulteeResponse"},"description":"One entry per consultee body that responded."},"totalRepresentations":{"type":["object","null"],"properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Number of representations received from the public and neighbours. Null when the source does not state it."},"representationsBreakdown":{"type":["object","null"],"properties":{"value":{"$ref":"#/components/schemas/PlanningRepresentationsBreakdown"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Those representations counted by stance. Null when the source does not break them down."},"petitionsReceived":{"type":["object","null"],"properties":{"value":{"type":"number"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Number of petitions received. Null when the source does not state it."},"consultationStartDate":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"When the consultation opened, as an ISO 8601 date (YYYY-MM-DD). Null when the source omits it."},"consultationEndDate":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"When the consultation closed, as an ISO 8601 date (YYYY-MM-DD). Null when the source omits it."}},"required":["responses","totalRepresentations","representationsBreakdown","petitionsReceived","consultationStartDate","consultationEndDate"]},"PlanningConsulteeResponse":{"type":"object","properties":{"consulteeName":{"type":"object","properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"Name of the body that responded."},"consulteeType":{"type":"object","properties":{"value":{"type":"string","enum":["statutory_consultee","parish_council","ward_member","highways_authority","environment_agency","historic_england","natural_england","fire_service","police","lead_local_flood_authority","designing_out_crime_officer","tree_officer","conservation_officer","other"],"description":"Kind of body that was consulted. Statutory consultees are the bodies a local planning authority must consult by law."},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"]},"position":{"type":"object","properties":{"value":{"type":"string","enum":["support","object","no_objection","no_comment","comment_only","conditional"],"description":"The consultee's stance: 'support' in favour, 'object' against, 'no_objection' a formal no-objection response, 'no_comment' a decision not to engage, 'comment_only' points raised without taking a side, 'conditional' acceptance subject to conditions."},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"The consultee's overall stance on the application."},"receivedDate":{"type":["object","null"],"properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"],"description":"When the response was received, as an ISO 8601 date (YYYY-MM-DD). Null when the source omits it."},"keyPoints":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"]},"description":"The substantive points the consultee made, each quoted from its response."},"suggestedConditions":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"]},"description":"Conditions the consultee asked the planning authority to impose."},"raisedConcerns":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"citation":{"$ref":"#/components/schemas/ExtractionCitation"}},"required":["value","citation"]},"description":"Concerns the consultee raised about the proposal."}},"required":["consulteeName","consulteeType","position","receivedDate","keyPoints","suggestedConditions","raisedConcerns"]},"PlanningExtractionCoverage":{"type":"object","properties":{"schemasPresent":{"type":"array","items":{"type":"string","enum":["decision","development","s106","officerAssessment","consulteeResponses"]},"description":"Which extractions are present for this application."},"verifiedCount":{"type":"integer","description":"How many of the extractions present have been verified."},"extractedCount":{"type":"integer","description":"How many of the extractions present have not yet been verified."}},"required":["schemasPresent","verifiedCount","extractedCount"]},"PlanningImage":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier for the image. One image reused across several of the application's documents is returned once, under a single identifier.","example":"c1d2e3f4-a5b6-7890-1234-567890abcdef"},"url":{"type":"string","description":"Address of the image, served from a content delivery network and needing no signed parameters, so it can be used directly as the source of an `img` tag.","example":"https://atlas.cdn.vepler.com/planning/lambeth/24-00123-FUL/images/site-plan-1.png"},"mimeType":{"type":["string","null"],"description":"Media type of the image, such as `image/png`. Null when the type is not known.","example":"image/png"},"width":{"type":["number","null"],"description":"Width of the image in pixels. Null when the dimensions are not known.","example":1654},"height":{"type":["number","null"],"description":"Height of the image in pixels. Null when the dimensions are not known.","example":1169},"classification":{"type":["string","null"],"description":"What the image depicts, assigned automatically, for example 'site_plan', 'floor_plan' or 'elevation'. Null when the image has not been classified.","example":"site_plan"},"classificationConfidence":{"type":["number","null"],"description":"How certain the classification is, from 0 to 1, with higher values meaning more certain. Null when the image has not been classified.","example":0.94},"pageNumber":{"type":["number","null"],"description":"Page of the source document on which the image first appears, counting from 1.","example":2},"refCount":{"type":"number","description":"How many times the image appears across the application's documents. A drawing repeated in several documents, such as a site plan, carries a higher count.","example":3},"documentFileName":{"type":["string","null"],"description":"File name of the document the image was extracted from. Null when the source document is not known.","example":"Site_Plan_Rev_A.pdf"}},"required":["id","url"]},"PlanningClassificationReasoning":{"type":"object","properties":{"finalClassification":{"type":["object","null"],"additionalProperties":{},"description":"The classification this run settled on, with the fields that carry it."},"confidenceBreakdown":{"type":["object","null"],"additionalProperties":{},"description":"How certain the run was in each dimension it judged. Null when the run recorded no breakdown."},"reasoning":{"type":["string","null"],"description":"Human-readable explanation of how the classification was reached. Null when none was recorded."},"validationIssues":{"type":"array","items":{},"description":"Inconsistencies the validation step raised against the classification. Empty when it raised none."},"uncertaintyFlags":{"type":"array","items":{},"description":"Points the run was unsure about. Empty when it flagged none."},"requiresHumanReview":{"type":["boolean","null"],"description":"True when the run marked this classification for human review. Null when the run recorded no verdict either way."},"classificationVersion":{"type":["string","null"],"description":"Version of the classification method that produced this result. Null when the version was not recorded."},"createdAt":{"type":"string","description":"When this classification run was recorded, as an ISO 8601 timestamp."}},"required":["createdAt"]},"PlanningSemanticChunk":{"type":"object","properties":{"id":{"type":"string","description":"Identifier for this chunk."},"documentId":{"type":["string","null"],"description":"Identifier of the document the chunk was taken from. Null when the chunk is not tied to one document."},"chunkType":{"type":["string","null"],"description":"Granularity of the chunk, for example 'document' or 'section'. Null when it was not recorded."},"contextSummary":{"type":["string","null"],"description":"Written summary of what surrounds this chunk in its document. Null when no summary was produced."},"sectionPath":{"type":["array","null"],"items":{"type":"string"},"description":"Headings leading to the chunk, outermost first, locating it in the document. Null when the document has no heading structure."},"pageStart":{"type":["number","null"],"description":"First page the chunk covers, counting from 1. Null when the page is not recorded."},"pageEnd":{"type":["number","null"],"description":"Last page the chunk covers, counting from 1. Null when the page is not recorded."}},"required":["id"]},"PlanningQueryRequest":{"type":"object","properties":{"query":{"$ref":"#/components/schemas/PlanningQueryFilters"},"limit":{"type":"number","minimum":1,"maximum":100,"default":50,"description":"Maximum number of applications to return. Defaults to 50. Minimum 1, maximum 100.","example":50},"offset":{"type":"number","minimum":0,"default":0,"description":"Number of applications to skip before the first one returned. Defaults to 0. An offset of 50 with a limit of 50 gives the second page. Offsets above 10000 are treated as 10000.","example":0},"sortBy":{"type":"string","enum":["receivedDate","validatedDate","appealedDate","createdAt","updatedAt"],"default":"receivedDate","description":"Which date to order results by. 'createdAt' and 'updatedAt' are when the record itself appeared in the API and when it last changed; the other three are the corresponding dates on the application. Defaults to 'receivedDate'. Ignored when the `near` filter is used, which orders by distance instead.","example":"receivedDate"},"sortOrder":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Direction to order results in: 'desc' puts the most recent first, 'asc' the oldest. Defaults to 'desc'. Ignored when the `near` filter is used, which orders by distance instead.","example":"desc"},"include":{"type":"array","items":{"type":"string","enum":["extractions","images","content","enrichment"]},"description":"Extra data to attach to each application returned. 'extractions' adds the structured, quote-backed extractions (decision, development, section 106, officer assessment, consultee responses). 'images' adds the deduplicated image gallery. 'content' adds fileUrl and ocrUrl to each document, so the file and its text can be rendered or searched in a browser. 'enrichment' adds the classification reasoning and the document segmentation summaries. All are left off by default, and 'extractions', 'images' and 'enrichment' each add a further lookup, so ask only for what you need.","example":["extractions","images","content"]}}},"PlanningQueryFilters":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier of a single planning application. This endpoint ignores this filter: to fetch an application by its identifier, call GET /{applicationIds} instead.","example":"550e8400-e29b-41d4-a716-446655440000"},"councils":{"type":"array","items":{"type":"string"},"description":"Return only applications from these local planning authorities. Values are the council slugs published in each application's provider field, for example 'lambeth'.","example":["lambeth","manchester"]},"key":{"type":"string","description":"A council's own reference number for an application. This endpoint ignores this filter: to look up an application by its council reference, call GET /sources/{sourceIds} with a `provider::key` identifier instead.","example":"24/00123/FUL"},"statuses":{"type":"array","items":{"type":"string"},"description":"Return only applications whose status is one of these. Use the values listed on the application status field; an unrecognised value is dropped rather than rejected, and a filter left with nothing usable stops narrowing the search at all.","example":["approved","rejected"]},"types":{"type":"array","items":{"type":"string"},"description":"Return only applications whose normalised type is one of these. Values are matched exactly against the application type field.","example":["Full Planning","Householder"]},"developmentCategories":{"type":"array","items":{"type":"string"},"description":"Return only applications whose development category is one of these. Values are matched exactly against the application developmentCategory field.","example":["Residential","Commercial"]},"receivedDateFrom":{"type":"string","description":"Return only applications the council received on or after this moment. Give an ISO 8601 date or timestamp. Pair it with receivedDateTo to bound both ends.","example":"2024-01-01"},"receivedDateTo":{"type":"string","description":"Return only applications the council received on or before this moment. Give an ISO 8601 date or timestamp. Pair it with receivedDateFrom to bound both ends.","example":"2024-12-31"},"validatedDateFrom":{"type":"string","description":"Return only applications validated on or after this moment. Give an ISO 8601 date or timestamp. Validation is the point at which the council registered the application as complete.","example":"2024-01-01"},"validatedDateTo":{"type":"string","description":"Return only applications validated on or before this moment. Give an ISO 8601 date or timestamp.","example":"2024-12-31"},"appealedDateFrom":{"type":"string","description":"Return only applications with an appeal lodged on or after this moment. Give an ISO 8601 date or timestamp. Applications that have never been appealed cannot match.","example":"2024-01-01"},"appealedDateTo":{"type":"string","description":"Return only applications with an appeal lodged on or before this moment. Give an ISO 8601 date or timestamp.","example":"2024-12-31"},"near":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the centre to search around, in WGS84 decimal degrees."},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the centre to search around, in WGS84 decimal degrees."},"radiusM":{"type":"integer","minimum":100,"maximum":50000,"description":"How far from the centre to search, in whole metres. Minimum 100, maximum 50000. Required whenever `near` is given."}},"required":["lat","lng","radiusM"],"description":"Return only applications whose site point lies within radiusM metres of this centre. Matches come back closest first, each carrying distance in metres, and that ordering replaces sortBy and sortOrder. This is the filter to reach for when you want the planning context around a property; combine it with the others to narrow further."}},"description":"Which applications to return. Separate filters are combined with AND, so an application must satisfy all of them; several values inside one array filter are combined with OR. Omit it, or pass an empty object, to match every application."},"StreetQueryResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/StreetRecord"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250},"attribution":{"type":"string","description":"The attribution that must be shown wherever the open-data street fields in this response are displayed. Present when at least one returned street carries open data.","example":"Contains OS data © Crown copyright and database right 2026."},"message":{"type":"string","description":"Explains an empty result, naming the identifier that matched no street."}},"required":["object","url","has_more","data"]},"StreetRecord":{"type":"object","properties":{"id":{"type":"string","description":"Stable identifier for the street, in the form `<country>-<scheme>:<value>`. Pass it as `starting_after` to fetch the page that follows this street.","example":"gb-usrn:21701338"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"Territory the street sits in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"usrn":{"type":"number","description":"The Unique Street Reference Number (USRN).","example":21701338},"dataset":{"$ref":"#/components/schemas/StreetSource"},"provenance":{"$ref":"#/components/schemas/StreetProvenance"},"name":{"type":["string","null"],"description":"Name of the street as the dataset that answered records it, with the dataset's own capitalisation. Names in other languages are in `descriptors`. Null when the dataset holds no name. Read `nameKind` before showing it as a street name.","example":"High Street"},"nameKind":{"$ref":"#/components/schemas/StreetNameKind"},"nameConfidence":{"$ref":"#/components/schemas/StreetNameConfidence"},"descriptors":{"type":"array","items":{"$ref":"#/components/schemas/StreetDescriptor"},"description":"How the street is named: `name` first, then each further name the dataset records, such as the name in another language. Empty when no name is recorded or `name` was not requested."},"locality":{"type":["string","null"],"description":"Locality the street sits in.","example":"Soho"},"town":{"type":["string","null"],"description":"Town or city the street sits in.","example":"London"},"district":{"type":["string","null"],"description":"Local authority district the street falls in.","example":"Westminster"},"county":{"type":["string","null"],"description":"County the street falls in.","example":"Greater London"},"postcodeDistrict":{"type":["string","null"],"description":"Postcode district the street falls in, the outward part of its postcodes.","example":"W1D"},"streetType":{"type":["string","null"],"description":"Type of street as the naming authority records it.","example":"Officially Designated Street Name"},"location":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Representative point for the street, at its centre.","title":"Coordinates"},"streetStartLat":{"type":"number","description":"Latitude where the street starts, in WGS84 decimal degrees. Present when the dataset that supplied the street records its start and end, which the NGD does and the open data does not.","example":51.5074},"streetStartLng":{"type":"number","description":"Longitude where the street starts, in WGS84 decimal degrees. Present alongside `streetStartLat`.","example":-0.1278},"streetEndLat":{"type":"number","description":"Latitude where the street ends, in WGS84 decimal degrees. Present alongside `streetStartLat`.","example":51.5076},"streetEndLng":{"type":"number","description":"Longitude where the street ends, in WGS84 decimal degrees. Present alongside `streetStartLat`.","example":-0.128},"propertyCount":{"type":"number","description":"Number of properties on the street. Present when `includeStatistics` is true.","example":42},"properties":{"$ref":"#/components/schemas/StreetProperties"},"distance":{"type":"number","description":"Distance from the query point to the street's centre in the dataset the search matched it in, in metres. Present on coordinate lookups. Under `open_then_ngd` that is the open data unless the open data has no street in the radius, so a street the NGD supplies whole because the open data holds no name for it is measured to its open data centre, and `distance` can differ from the distance to `location`.","example":35}},"required":["id","country","usrn","dataset","descriptors"],"description":"A street, identified by its Unique Street Reference Number (USRN)."},"StreetSource":{"type":"string","enum":["open","ngd"],"description":"The dataset that supplied the street record: 'open' for Ordnance Survey open data, 'ngd' for the Ordnance Survey National Geographic Database.","example":"open"},"StreetProvenance":{"type":"object","properties":{"name":{"$ref":"#/components/schemas/StreetSource"},"locality":{"$ref":"#/components/schemas/StreetSource"},"town":{"$ref":"#/components/schemas/StreetSource"},"district":{"$ref":"#/components/schemas/StreetSource"},"county":{"$ref":"#/components/schemas/StreetSource"},"postcodeDistrict":{"$ref":"#/components/schemas/StreetSource"},"streetType":{"$ref":"#/components/schemas/StreetSource"},"location":{"$ref":"#/components/schemas/StreetSource"}},"description":"Which dataset supplied each returned field. Present only when a street's fields came from more than one dataset.","example":{"name":"open","streetType":"ngd"}},"StreetNameKind":{"type":["string","null"],"enum":["name","descriptor",null],"description":"What `name` holds. 'name' is a street name. 'descriptor' is a description the naming authority records in place of a name, such as a road number or 'Access to ...', and is not a name the street is known by.","example":"name"},"StreetNameConfidence":{"type":"string","enum":["confident","ambiguous","absent"],"description":"How settled the open-data name is. 'confident' is a single name. 'ambiguous' means more than one open-data name competes for the street and `name` is one of them. 'absent' means the open data holds no name, so `name` is null.","example":"confident"},"StreetDescriptor":{"type":"object","properties":{"streetDescription":{"type":"string","description":"Full name of the street.","example":"High Street"},"locality":{"type":"string","description":"Locality the street sits in.","example":"Kensington"},"townName":{"type":"string","description":"Town or city the street sits in.","example":"London"},"administrativeArea":{"type":"string","description":"Administrative area the street falls in.","example":"Kensington and Chelsea"},"language":{"type":"string","description":"Language this naming is in, as a three-letter code: `ENG` for English, `CYM` for Welsh, `GLA` for Scottish Gaelic. Absent when the dataset does not record the language of the name.","example":"ENG"}},"required":["streetDescription"]},"StreetProperties":{"type":"object","properties":{"uprns":{"type":"array","items":{"type":"number"},"description":"Unique Property Reference Numbers (UPRNs) of properties on the street, in ascending order.","example":[100023336956,100023336957]},"hasMore":{"type":"boolean","description":"True when the street has further properties beyond this list.","example":false}},"required":["uprns","hasMore"],"description":"The properties on the street, paged by `propertyOptions`."},"StreetQueryRequest":{"type":"object","properties":{"identifier":{"oneOf":[{"$ref":"#/components/schemas/StreetQueryByUsrn"},{"$ref":"#/components/schemas/StreetQueryByUprn"},{"$ref":"#/components/schemas/StreetQueryByCoordinates"},{"$ref":"#/components/schemas/StreetQueryByName"},{"$ref":"#/components/schemas/StreetQueryByPostcode"}],"discriminator":{"propertyName":"type","mapping":{"usrn":"#/components/schemas/StreetQueryByUsrn","uprn":"#/components/schemas/StreetQueryByUprn","coordinates":"#/components/schemas/StreetQueryByCoordinates","name":"#/components/schemas/StreetQueryByName","postcode":"#/components/schemas/StreetQueryByPostcode"}},"description":"Which streets to return, given as one of five identifier types. Set `type` to `usrn`, `uprn`, `coordinates`, `name` or `postcode` and supply that type's own fields."},"dataset":{"$ref":"#/components/schemas/StreetDataset"},"fields":{"type":"array","items":{"$ref":"#/components/schemas/StreetField"},"minItems":1,"description":"The street fields to return. When omitted, every field the answering dataset holds is returned. Under `open_then_ngd`, a field named here that the open data lacks for a street is taken from the NGD, and `provenance` then shows which dataset supplied each field. A name is always taken whole from one dataset.","example":["name","town","streetType"]},"starting_after":{"type":"string","description":"Cursor for the next page: the `id` of the last street on the current page. Applies to name, coordinate and postcode lookups.","example":"gb-usrn:21701338"},"includeProperties":{"type":"boolean","default":false,"description":"Return the properties on each street under `properties`, as UPRNs. Defaults to false. Paged by `propertyOptions`.","example":true},"includeStatistics":{"type":"boolean","default":false,"description":"Return the number of properties on each street as `propertyCount`. Defaults to false.","example":true},"propertyOptions":{"$ref":"#/components/schemas/StreetPropertyOptions"}},"required":["identifier"],"additionalProperties":false},"StreetQueryByUsrn":{"type":"object","properties":{"type":{"type":"string","enum":["usrn"]},"usrn":{"type":"number","description":"The Unique Street Reference Number (USRN) to look up.","example":21701338}},"required":["type","usrn"],"additionalProperties":false},"StreetQueryByUprn":{"type":"object","properties":{"type":{"type":"string","enum":["uprn"]},"uprn":{"type":"number","description":"The Unique Property Reference Number (UPRN) whose street to return.","example":10094639688}},"required":["type","uprn"],"additionalProperties":false},"StreetQueryByCoordinates":{"type":"object","properties":{"type":{"type":"string","enum":["coordinates"]},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278},"radius":{"type":"number","minimum":1,"maximum":1000,"default":50,"description":"How far from the point to search, in metres, measured to each street's centre in the dataset searched. Under `open_then_ngd` that is the open data unless the open data has no street in the radius, so a street the NGD supplies whole can have its `location` outside the radius. Defaults to 50. Minimum 1, maximum 1000.","example":50},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"description":"Maximum number of streets to return on this page. Defaults to 10. Minimum 1, maximum 50.","example":10}},"required":["type","lat","lng"],"additionalProperties":false},"StreetQueryByName":{"type":"object","properties":{"type":{"type":"string","enum":["name"]},"searchTerm":{"type":"string","minLength":2,"description":"Street name to search for, optionally followed by its locality or town. Case is not significant and small misspellings are tolerated; every word must match. Minimum 2 characters.","example":"High Street Soho"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"description":"Maximum number of streets to return on this page. Defaults to 10. Minimum 1, maximum 50.","example":10}},"required":["type","searchTerm"],"additionalProperties":false},"StreetQueryByPostcode":{"type":"object","properties":{"type":{"type":"string","enum":["postcode"]},"postcode":{"type":"string","pattern":"^[A-Z]{1,2}[0-9][0-9A-Z]?\\s?[0-9][A-Z]{2}$","description":"A full UK postcode. The space is optional and case is not significant; the value is returned upper-cased.","example":"SW1A 1AA"},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"description":"Maximum number of streets to return on this page. Defaults to 10. Minimum 1, maximum 50.","example":10}},"required":["type","postcode"],"additionalProperties":false},"StreetDataset":{"type":"string","enum":["open","ngd","open_then_ngd"],"default":"open_then_ngd","description":"Which street dataset to read. 'open' reads Ordnance Survey open data published under the Open Government Licence. 'ngd' reads the Ordnance Survey National Geographic Database (NGD). 'open_then_ngd' reads the open data first and turns to the NGD only when the open data has no record or no name for the street, or when a search finds nothing in it. Postcode lookups are answered from the NGD only, so they are rejected under 'open'. Defaults to 'open_then_ngd'.","example":"open_then_ngd"},"StreetField":{"type":"string","enum":["name","locality","town","district","county","postcodeDistrict","streetType","location"],"example":"name"},"StreetPropertyOptions":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":500,"default":100,"description":"Maximum number of properties to return per street. Defaults to 100. Minimum 1, maximum 500.","example":100},"offset":{"type":"integer","minimum":0,"default":0,"description":"Number of properties to skip on each street before the first one returned. Defaults to 0.","example":0},"includeHistoric":{"type":"boolean","default":false,"description":"Include retired address records alongside the current ones. Defaults to false, which returns only approved and alternative addresses. Available only with `dataset` set to `ngd`.","example":false}},"additionalProperties":false,"description":"How to page and filter each street's property list. Accepted only when `includeProperties` is true."},"SchoolCatchmentBlock":{"type":"object","properties":{"matchBasis":{"type":"array","items":{"$ref":"#/components/schemas/SchoolMatchBasis"},"description":"Every piece of evidence that tied this school to the property, one entry per tier that matched. Empty when the school is only one of the nearest, with no catchment evidence behind it."},"verdict":{"type":"string","enum":["matched_via_designated_polygon","matched_via_outcomes","matched_via_faith","matched_via_feeder","distance_only"],"description":"The strongest evidence found for this school. A designated polygon outranks a faith jurisdiction, which outranks a feeder link, which outranks an admission distance. `distance_only` means the school is merely one of the nearest and should not be presented as serving the property.","example":"matched_via_designated_polygon"}},"required":["matchBasis","verdict"],"description":"Why this school matched the property named by `catchmentReference`, and how firm the match is. Present only when the request supplied `catchmentReference`. `verdict` is always populated; `matchBasis` is empty when the school is merely one of the nearest, with no catchment evidence behind it."},"SchoolMatchBasis":{"type":"object","properties":{"tier":{"type":"string","enum":["designated_polygon","last_admitted_distance","faith_jurisdiction","feeder_link","distance_ranking"],"description":"What evidence tied the school to the property. 'designated_polygon' means the property falls inside a catchment area the local authority publishes for the school. 'faith_jurisdiction' means it falls inside a parish or diocese tied to the school's faith criterion. 'last_admitted_distance' means it is at least as close as the furthest pupil the school admitted in the year read. 'feeder_link' means the school is named as a feeder destination by another school that already matched. 'distance_ranking' means the school is simply one of the nearest, the fallback that keeps a result set from being empty.","example":"designated_polygon"},"confidence":{"type":"string","enum":["hard","indicative","soft"],"description":"How firmly the match is evidenced, and so how strongly it should be presented. 'hard' comes from a published boundary or a published link, 'indicative' from an admission distance the school published for one year, and 'soft' from proximity alone.","example":"hard"},"detail":{"type":"object","additionalProperties":{},"description":"The particulars behind this basis. Which keys appear depends on `tier`: a designated-polygon match carries the polygon and its catchment type, a last-admitted-distance match carries that distance in metres alongside the published admission number, and a distance ranking carries the school's rank.","example":{"polygonId":12,"catchmentType":"designated","effectiveFrom":"2024-09-01"}},"asOfYear":{"type":"string","description":"Academic year this basis was published for. Present on last-admitted-distance and feeder-link matches only.","example":"GB_2024-2025"},"sourceUrl":{"type":"string","description":"Canonical address at which the publisher makes this basis available.","example":"https://example.lpa/catchments.pdf"}},"required":["tier","confidence","detail"]},"SchoolInspectionEvent":{"type":["object","null"],"properties":{"inspectorBody":{"$ref":"#/components/schemas/SchoolInspectorBody"},"framework":{"type":["string","null"],"description":"Which inspection framework the visit was carried out under, for example 'post_2025', 'oeif' or 'ungraded_only'."},"inspectionType":{"type":["string","null"],"description":"The type of inspection, as the inspectorate labels it."},"inspectionDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"When the inspection took place, as an ISO 8601 date."},"publicationDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"When the report was published, as an ISO 8601 date. Null where the inspectorate did not state one."},"rating":{"type":"string","enum":["outstanding","good","satisfactory","inadequate","exceptional","strong_standard","expected_standard","needs_attention","urgent_improvement","requires_improvement","not_yet_inspected","excellent","adequate","unsatisfactory","very_good","weak","important_area_for_improvement","requires_significant_improvement","fair"],"description":"The overall grade, in the wording of the inspectorate that issued it. Scales differ between inspectorates, so grades are not comparable across them."},"categoryOfConcern":{"type":["string","null"],"description":"The statutory category of concern the school was placed in, for example 'Special measures'. Null when none applies."},"ratings":{"type":["object","null"],"properties":{"overallEffectiveness":{"$ref":"#/components/schemas/SchoolInspectionGrade"},"qualityOfEducation":{"$ref":"#/components/schemas/SchoolInspectionGrade"},"behaviourAndAttitudes":{"$ref":"#/components/schemas/SchoolInspectionGrade"},"personalDevelopment":{"$ref":"#/components/schemas/SchoolInspectionGrade"},"leadershipAndManagement":{"$ref":"#/components/schemas/SchoolInspectionGrade"},"earlyYearsProvision":{"$ref":"#/components/schemas/SchoolInspectionGrade"},"sixthFormProvision":{"$ref":"#/components/schemas/SchoolInspectionGrade"}},"description":"Sub-judgements published under the Ofsted Education Inspection Framework, each graded 1 to 4. Null for inspections outside that framework."},"evaluationAreas":{"type":["array","null"],"items":{"$ref":"#/components/schemas/SchoolInspectionEvaluationArea"},"description":"Grades for each evaluation area under Ofsted's post-2025 framework. Null for inspections outside that framework."},"predecessor":{"$ref":"#/components/schemas/SchoolInspectionPredecessor"},"reportUrl":{"type":["string","null"],"format":"uri","description":"Canonical address of the published inspection report on the inspectorate's own site."}},"required":["inspectorBody","inspectionDate","rating"],"description":"The most recent inspection. Null when the school has no recorded inspection."},"SchoolInspectorBody":{"type":"string","enum":["ofsted","estyn","education_scotland","eti","des"],"description":"Which inspectorate issued the grade. `ofsted` covers England, `estyn` Wales, `education_scotland` Scotland, `eti` Northern Ireland and `des` Ireland."},"SchoolInspectionGrade":{"type":["object","null"],"properties":{"grade":{"type":"integer","minimum":1,"maximum":4,"description":"The grade, from 1 (outstanding) down to 4 (inadequate)."},"label":{"type":"string","description":"The same grade in words, for example 'Good'."}},"required":["grade","label"],"example":{"grade":2,"label":"good"}},"SchoolInspectionEvaluationArea":{"type":"object","properties":{"area":{"type":"string","description":"Which area was evaluated, for example 'leadership_governance'."},"grade":{"type":"string","description":"The grade awarded for that area, for example 'Strong standard'. Safeguarding is graded 'Met' or 'Not met'."}},"required":["area","grade"]},"SchoolInspectionPredecessor":{"type":["object","null"],"properties":{"urn":{"type":["integer","null"]},"name":{"type":["string","null"]},"schoolType":{"type":["string","null"]},"relatesToCurrentUrn":{"type":["boolean","null"]}}},"SchoolTrustMembership":{"type":"object","properties":{"organisationId":{"type":"integer","description":"Identifier for the organisation in this API."},"uid":{"type":"string","description":"Stable identifier for the organisation in the source register, such as its GIAS group UID."},"name":{"type":"string","description":"Name of the organisation."},"type":{"type":"string","description":"What kind of organisation it is, for example 'mat', 'sat', 'federation' or 'diocese'."},"groupType":{"type":["string","null"],"description":"The group-type label as the source register publishes it."},"role":{"type":"string","description":"The school's role in the organisation, for example 'lead', 'sponsor', 'founder' or 'member'."},"ukprn":{"type":["string","null"],"description":"The organisation's UK Provider Reference Number (UKPRN)."},"groupId":{"type":["string","null"],"description":"The group identifier used by the source register, such as a GIAS trust identifier beginning `TR`."},"status":{"type":["string","null"],"description":"The organisation's status, as the source register publishes it."}},"required":["organisationId","uid","name","type","role"]},"SchoolImage":{"type":"object","properties":{"url":{"type":"string","description":"Address the image is served from.","example":"https://hot-cdn.vepler.com/schools/12345/images/ab12cd.png"},"tag":{"type":["string","null"],"description":"What the image shows, for example 'classroom', 'sports_hall', 'library' or 'grounds'. Null when it has not been classified.","example":"sports_hall"},"description":{"type":["string","null"],"description":"Short caption for the image. Null when none is held."},"width":{"type":["integer","null"],"description":"Width of the image in pixels."},"height":{"type":["integer","null"],"description":"Height of the image in pixels."}},"required":["url","tag","description"]},"SocialMediaLinks":{"type":"object","properties":{"twitter":{"type":"string","description":"URL or handle of the profile on X (Twitter)."},"facebook":{"type":"string","description":"URL of the Facebook page."},"instagram":{"type":"string","description":"URL or handle of the Instagram profile."},"linkedin":{"type":"string","description":"URL of the LinkedIn page."},"youtube":{"type":"string","description":"URL of the YouTube channel."},"tiktok":{"type":"string","description":"URL or handle of the TikTok profile."}}},"SchoolAccreditation":{"type":"object","properties":{"url":{"type":"string","description":"Address the badge image is served from.","example":"https://hot-cdn.vepler.com/schools/12345/images/ef34gh.png"},"kind":{"type":["string","null"],"description":"What kind of badge it is, for example 'ofsted_badge', 'award', 'kitemark' or 'partner_badge'. Null when it has not been classified.","example":"ofsted_badge"},"description":{"type":["string","null"],"description":"Short explanation of what the badge attests. Null when none is held."}},"required":["url","kind","description"]},"SchoolVideo":{"type":"object","properties":{"provider":{"type":"string","enum":["youtube","vimeo","self_hosted"],"description":"Where the video is hosted. `self_hosted` covers videos served from the school's own site."},"externalId":{"type":"string","description":"The video's identifier at that provider. For a self-hosted video this is the path on the site."},"url":{"type":"string","description":"Canonical address at which the video can be watched."},"embedUrl":{"type":["string","null"],"description":"Address to load inside an `iframe` to embed the video. Null where no embed address is held."},"title":{"type":["string","null"],"description":"Title of the video as published. Null where none is held."},"thumbnailUrl":{"type":["string","null"],"description":"Address of the thumbnail image on the hosting provider. The image is referenced, not re-hosted."},"durationSeconds":{"type":["integer","null"],"description":"Length of the video in seconds. Null where it is not known."}},"required":["provider","externalId","url","embedUrl","title","thumbnailUrl"]},"SchoolTermDate":{"type":"object","properties":{"label":{"type":"string","description":"What the entry covers, for example 'Autumn term'."},"start":{"type":["string","null"],"description":"When the term or holiday starts, exactly as the school published it. Not normalised to a date."},"end":{"type":["string","null"],"description":"When the term or holiday ends, exactly as the school published it. Not normalised to a date."}},"required":["label","start","end"]},"CatchmentMeta":{"type":"object","properties":{"tiersApplied":{"type":"array","items":{"type":"string","enum":["designated_polygon","last_admitted_distance","faith_jurisdiction","feeder_link","distance_ranking"],"description":"What evidence tied the school to the property. 'designated_polygon' means the property falls inside a catchment area the local authority publishes for the school. 'faith_jurisdiction' means it falls inside a parish or diocese tied to the school's faith criterion. 'last_admitted_distance' means it is at least as close as the furthest pupil the school admitted in the year read. 'feeder_link' means the school is named as a feeder destination by another school that already matched. 'distance_ranking' means the school is simply one of the nearest, the fallback that keeps a result set from being empty.","example":"designated_polygon"},"description":"The tiers that were evaluated for this match."},"tiersSkipped":{"type":"array","items":{"$ref":"#/components/schemas/TierSkipReason"},"description":"The tiers that were not evaluated, each with the reason it was passed over."},"coverageWarnings":{"type":"array","items":{"type":"string"},"description":"Human-readable warnings about the data behind the match, such as an authority whose catchment polygons are not loaded yet."},"property":{"type":"object","properties":{"uprn":{"type":"string","description":"The Unique Property Reference Number (UPRN), when one was supplied."},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"The point the match was run against: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order)."},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"Country the property is in, as an ISO 3166-1 alpha-2 code."},"lpaCode":{"type":"string","description":"Code of the local authority the property falls in, once resolved."}},"required":["coordinates","countryCode"],"description":"The property the match was run against. Present only when the reference resolved to a location."},"queriedAt":{"type":"string","description":"When the match was run, as an ISO 8601 timestamp."}},"required":["tiersApplied","tiersSkipped","coverageWarnings","queriedAt"],"description":"How the catchment match was arrived at: which tiers were used, which were not, and why. Present only when the request supplied `catchmentReference`."},"TierSkipReason":{"type":"object","properties":{"tier":{"type":"string","enum":["designated_polygon","last_admitted_distance","faith_jurisdiction","feeder_link","distance_ranking"],"description":"What evidence tied the school to the property. 'designated_polygon' means the property falls inside a catchment area the local authority publishes for the school. 'faith_jurisdiction' means it falls inside a parish or diocese tied to the school's faith criterion. 'last_admitted_distance' means it is at least as close as the furthest pupil the school admitted in the year read. 'feeder_link' means the school is named as a feeder destination by another school that already matched. 'distance_ranking' means the school is simply one of the nearest, the fallback that keeps a result set from being empty.","example":"designated_polygon"},"code":{"type":"string","enum":["no_coverage_for_lpa","no_coverage_for_school","no_polygon_intersects","no_outcomes_in_year","no_faith_jurisdiction_for_school","no_feeder_link_resolves","out_of_max_distance"],"description":"Stable code identifying why the tier was skipped, safe to branch on."},"reason":{"type":"string","description":"Human-readable explanation of the skip, suitable for showing to an end user."}},"required":["tier","code","reason"]},"CatchmentReference":{"type":"object","properties":{"uprn":{"type":"string","pattern":"^\\d{6,12}$","description":"The Unique Property Reference Number (UPRN), of 6 to 12 digits. When it is supplied without `near` or `within`, the school search is centred on that property with a 10 km radius.","example":"100023456789"},"point":{"type":"object","properties":{"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the property, in WGS84 decimal degrees.","example":-1.4},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the property, in WGS84 decimal degrees.","example":53.83}},"required":["lng","lat"],"description":"The property's own coordinate. Use it instead of `uprn` when the coordinate is already to hand."},"phase":{"type":"array","items":{"type":"string"},"description":"Phases of education to consider, so a request can ask only about primary or secondary schools.","example":["primary"]},"intakeYear":{"type":"string","description":"Academic year to read admission outcomes for. Defaults to the current academic year.","example":"GB_2024-2025"}},"description":"The property to test the returned schools against, given as either a `uprn` or a `point`. Supplying it adds a `catchment` block to every school in the response and a `meta.catchment` block describing how the match was made."},"MetricsCompareRequest":{"type":"object","properties":{"schoolIds":{"type":"array","items":{"type":"integer","exclusiveMinimum":0},"minItems":2,"maxItems":50,"description":"Identifiers of the schools to compare, as returned in the `id` field of a school record. At least 2 and at most 50 per request.","example":[12345,12346,12347]},"metricCodes":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50,"description":"Metric codes to compare across those schools. At least 1 and at most 50 per request.","example":["KS2_READING_PROGRESS","KS2_MATHS_PROGRESS"]},"academicYear":{"type":"string","pattern":"^\\d{4}\\/\\d{2}$","description":"Academic year to compare, in YYYY/YY form such as 2023/24. Defaults to the current academic year.","example":"2023/24"}},"required":["schoolIds","metricCodes"]},"CatchmentCoverageResponse":{"type":"object","properties":{"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"Country these counts cover, as an ISO 3166-1 alpha-2 code.","example":"GB"},"totalLpas":{"type":"integer","description":"Number of local authorities tracked for this country.","example":152},"byTier":{"type":"object","properties":{"polygons":{"type":"object","properties":{"not_started":{"type":"integer"},"discovered":{"type":"integer"},"fetched":{"type":"integer"},"extracted":{"type":"integer"},"loaded":{"type":"integer"},"blocked":{"type":"integer"},"not_applicable":{"type":"integer"}},"required":["not_started","discovered","fetched","extracted","loaded","blocked","not_applicable"],"description":"How many local authorities sit at each ingest status for this kind of evidence."},"outcomes":{"type":"object","properties":{"not_started":{"type":"integer"},"discovered":{"type":"integer"},"fetched":{"type":"integer"},"extracted":{"type":"integer"},"loaded":{"type":"integer"},"blocked":{"type":"integer"},"not_applicable":{"type":"integer"}},"required":["not_started","discovered","fetched","extracted","loaded","blocked","not_applicable"],"description":"How many local authorities sit at each ingest status for this kind of evidence."},"feeders":{"type":"object","properties":{"not_started":{"type":"integer"},"discovered":{"type":"integer"},"fetched":{"type":"integer"},"extracted":{"type":"integer"},"loaded":{"type":"integer"},"blocked":{"type":"integer"},"not_applicable":{"type":"integer"}},"required":["not_started","discovered","fetched","extracted","loaded","blocked","not_applicable"],"description":"How many local authorities sit at each ingest status for this kind of evidence."},"faith":{"type":"object","properties":{"not_started":{"type":"integer"},"discovered":{"type":"integer"},"fetched":{"type":"integer"},"extracted":{"type":"integer"},"loaded":{"type":"integer"},"blocked":{"type":"integer"},"not_applicable":{"type":"integer"}},"required":["not_started","discovered","fetched","extracted","loaded","blocked","not_applicable"],"description":"How many local authorities sit at each ingest status for this kind of evidence."}},"required":["polygons","outcomes","feeders","faith"],"description":"Ingest progress broken down by the four kinds of catchment evidence: published catchment areas, admission outcomes, feeder links and faith jurisdictions."}},"required":["countryCode","totalLpas","byTier"]},"CatchmentFeatureCollection":{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"],"description":"GeoJSON type discriminator. Always `FeatureCollection`."},"features":{"type":"array","items":{"$ref":"#/components/schemas/CatchmentFeature"},"description":"One feature per catchment boundary in force for the school. Empty when none has been loaded."}},"required":["type","features"]},"CatchmentFeature":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"],"description":"GeoJSON type discriminator. Always `Feature`."},"properties":{"type":"object","properties":{"polygonId":{"type":"integer","description":"Identifier of this catchment polygon."},"catchmentType":{"type":"string","description":"What kind of catchment this boundary is. One of: designated, priority, shared, feeder_area, lottery_zone, other."},"phaseScope":{"type":["string","null"],"description":"Phase of education the boundary applies to. Null when the source does not distinguish one."},"effectiveFrom":{"type":"string","description":"Date from which this boundary applies, as an ISO 8601 date."},"effectiveTo":{"type":["string","null"],"description":"Date from which this boundary no longer applies, as an ISO 8601 date. Null while it stands."},"sourceUrl":{"type":"string","description":"Canonical address at which the publisher makes this boundary available."},"confidence":{"type":"string","enum":["hard","indicative"],"description":"How firmly the boundary is evidenced. A boundary published by an authority is `hard`."},"synthetic":{"type":"boolean"}},"required":["polygonId","catchmentType","phaseScope","effectiveFrom","effectiveTo","sourceUrl","confidence"],"additionalProperties":false},"geometry":{"type":"object","additionalProperties":{},"description":"The boundary itself, as GeoJSON geometry. Positions are longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order)."}},"required":["type","properties","geometry"]},"AdmissionAreaResponse":{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"],"description":"GeoJSON type discriminator. Always `FeatureCollection`."},"school":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier for the school within this API."},"name":{"type":"string","description":"Name of the school as its source register publishes it."},"centre":{"type":["array","null"],"prefixItems":[{"type":"number"},{"type":"number"}],"description":"Point location of the school: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order). Null when the school has no coordinate on record."}},"required":["id","name","centre"],"description":"The school the boundaries belong to."},"features":{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Feature"],"description":"GeoJSON type discriminator. Always `Feature`."},"properties":{"type":"object","properties":{"boundaryType":{"type":"string","enum":["polygon"],"description":"Always `polygon` on this branch: the boundary is an area published by an authority."},"confidence":{"type":"string","enum":["hard"],"description":"Always `hard` on this branch: the boundary is published, not derived."},"polygonId":{"type":"integer","description":"Identifier of this catchment polygon."},"catchmentType":{"type":"string","description":"What kind of catchment this boundary is. One of: designated, priority, shared, feeder_area, lottery_zone, other."},"phaseScope":{"type":["string","null"],"description":"Phase of education the boundary applies to. Null when the source does not distinguish one."},"effectiveFrom":{"type":"string","description":"Date from which this boundary applies, as an ISO 8601 date."},"effectiveTo":{"type":["string","null"],"description":"Date from which this boundary no longer applies, as an ISO 8601 date. Null while it stands."},"sourceUrl":{"type":"string","description":"Canonical address at which the publisher makes this boundary available."}},"required":["boundaryType","confidence","polygonId","catchmentType","phaseScope","effectiveFrom","effectiveTo","sourceUrl"],"additionalProperties":false},"geometry":{"type":"object","additionalProperties":{},"description":"The boundary itself, as GeoJSON geometry. Positions are longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order)."}},"required":["type","properties","geometry"]},{"type":"object","properties":{"type":{"type":"string","enum":["Feature"],"description":"GeoJSON type discriminator. Always `Feature`."},"properties":{"type":"object","properties":{"boundaryType":{"type":"string","enum":["distance_radius"],"description":"Always `distance_radius` on this branch: the boundary is a circle, not a published area."},"confidence":{"type":"string","enum":["indicative"],"description":"Always `indicative` on this branch: the circle is derived from one year's admissions."},"radiusM":{"type":"integer","description":"Distance in metres to the furthest pupil the school admitted that year. Draw a circle of this radius around the feature's point."},"academicYear":{"type":"string","description":"Academic year the distance was published for."},"phaseScope":{"type":["string","null"],"description":"Phase of education the distance applies to. Null when the source does not distinguish one."},"publishedAdmissionNumber":{"type":["integer","null"],"description":"Places the school published for that year's intake. Null when the authority did not publish it."},"totalOffersMade":{"type":["integer","null"],"description":"Offers the school made for that intake. Null when the authority did not publish it."},"wasOversubscribed":{"type":"boolean","description":"True when the published outcomes record the school as oversubscribed for that intake."},"sourceUrl":{"type":"string","description":"Canonical address at which the publisher makes these outcomes available."},"criteria":{"type":"array","items":{"$ref":"#/components/schemas/AdmissionAreaCriterion"},"description":"How the places broke down across the school's published admission criteria."}},"required":["boundaryType","confidence","radiusM","academicYear","phaseScope","publishedAdmissionNumber","totalOffersMade","wasOversubscribed","sourceUrl","criteria"],"additionalProperties":false},"geometry":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["Point"],"description":"Geometry type discriminator. Always `Point`."},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"Centre of the circle, at the school itself: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order)."}},"required":["type","coordinates"],"description":"The point the radius is drawn around. Null when the school has no coordinate on record."}},"required":["type","properties","geometry"]}]},"description":"The boundaries themselves, of both kinds. A `polygon` feature is a catchment area published by an authority; a `distance_radius` feature is a circle around the school, sized by the distance to the furthest pupil it admitted in the year read. Empty when neither has been loaded for the school."}},"required":["type","school","features"]},"AdmissionAreaCriterion":{"type":"object","properties":{"criterionNumber":{"type":"integer","description":"Number this criterion carries in the school's published list of admission criteria."},"category":{"type":"string","description":"What the criterion is based on, such as a sibling, faith or distance."},"applicationsCount":{"type":["integer","null"],"description":"Applications made under this criterion. Null when the authority did not publish it."},"offersCount":{"type":"integer","description":"Places offered under this criterion."},"lastDistanceM":{"type":["integer","null"],"description":"Distance in metres to the furthest pupil admitted under this criterion. Null when none was published for it."}},"required":["criterionNumber","category","applicationsCount","offersCount","lastDistanceM"]},"FrameworkListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Framework"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."},"Framework":{"type":"object","properties":{"framework":{"$ref":"#/components/schemas/SchoolFrameworkCode"},"country":{"$ref":"#/components/schemas/CountryCode"},"publishingAuthority":{"type":"string","minLength":1,"description":"The authority that publishes this framework's data, for example `Department for Education (England)`, `Education Scotland`, `Ofsted` or `ESFA`."},"publishingAuthorityUrl":{"type":["string","null"],"format":"uri"},"domain":{"type":"string","enum":["performance","destinations","value_added","census","finance","admissions","inspections"],"description":"Which top-level block of a School response this framework feeds."},"schoolBlockPath":{"type":"string","description":"Where this framework's data appears inside a School response, for example `performance.ks4` or `inspections.history[].framework=oeif`."},"metricCodes":{"type":"array","items":{"type":"string"},"default":[],"description":"Every metric code published in this framework, so a caller can see what is available without fetching each definition."},"examplePayload":{"type":["object","null"],"additionalProperties":{},"description":"A worked example of the framework's block as it appears on a School response."},"governingPublicationUrl":{"type":["string","null"],"format":"uri"},"publishedSince":{"type":["string","null"],"pattern":"^\\d{4}-\\d{4}$"},"cadence":{"type":"string","enum":["annual","monthly","rolling","ad_hoc"],"description":"How often the publishing authority releases an update."}},"required":["framework","country","publishingAuthority","domain","schoolBlockPath","cadence"]},"SchoolFrameworkCode":{"type":"string","enum":["gb_eng_dfes_ks2","gb_eng_dfes_ks4","gb_eng_dfes_ks5","gb_eng_dfes_destinations_ks4","gb_eng_dfes_destinations_ks5","gb_eng_dfes_value_added","gb_eng_dfes_school_census","gb_eng_esfa_cfr","gb_eng_esfa_aar","gb_eng_lpa_admissions","gb_eng_ofsted_oeif","gb_eng_ofsted_post_2025","gb_wls_welshgov_performance","gb_wls_estyn_inspections","gb_sct_education_scotland_performance","gb_sct_hmie_inspections","gb_nir_deni_performance","gb_nir_eti_inspections","ie_doe_performance","ie_doe_inspections"],"description":"Stable code identifying the framework, safe to match on."},"CountryCode":{"type":"string","minLength":2,"maxLength":2,"pattern":"^[A-Z]{2}$","description":"Territory the framework applies to, as an ISO 3166-1 alpha-2 code.","example":"GB"},"FrameworkDetailResponse":{"type":"object","properties":{"object":{"type":"string","enum":["framework_detail"]},"framework":{"$ref":"#/components/schemas/Framework"},"metrics":{"type":"array","items":{"$ref":"#/components/schemas/MetricDefinition"},"description":"Every metric defined in this framework."}},"required":["object","framework","metrics"]},"MetricDefinition":{"type":"object","properties":{"code":{"type":"string","minLength":1,"description":"The metric's code as the publishing authority issues it, for example `ATT8` (DfE Key Stage 4 Attainment 8) or `PTRWM_EXP` (DfE Key Stage 2 percentage reaching the expected standard in reading, writing and maths combined). Codes stay stable across years within a framework."},"framework":{"allOf":[{"$ref":"#/components/schemas/SchoolFrameworkCode"},{"description":"Which framework the metric belongs to. The same code can mean different things in different frameworks, so read the two together."}]},"label":{"type":"string","minLength":1,"description":"Short label for the metric, suitable for a table heading, for example `Attainment 8`."},"interpretedAs":{"type":"string","minLength":1,"description":"One-sentence plain definition of what the metric measures, for example `Average GCSE points across the 8 best subjects, on a 0-90 scale`."},"description":{"type":["string","null"],"description":"Longer explanation of what the metric measures, how it is calculated and what to watch for, taken from the publishing authority's methodology."},"unit":{"type":"string","minLength":1,"description":"Unit the values are expressed in, one of `percent`, `score_out_of_90`, `points`, `count`, `rate_per_1000`, `currency_gbp`, `metres`, `ratio`, `boolean` or `enum`. Use it to format a value for display, for instance appending a percent sign or rendering `currency_gbp` as money."},"range":{"type":["object","null"],"properties":{"min":{"type":["number","null"]},"max":{"type":["number","null"]},"nominalNationalAverage":{"type":["number","null"]}},"description":"The range a value normally falls in. `nominalNationalAverage` is the typical mid-point, which is enough to spot an outlier without loading a national distribution first."},"higherIsBetter":{"type":["boolean","null"],"description":"True when a higher value means stronger performance. Null when the metric describes rather than evaluates, as a pupil count does."},"isPercentile":{"type":"boolean","default":false,"description":"True when the value is a percentile rank rather than a raw measure. Defaults to false."},"cohortDimensionsSupported":{"type":"array","items":{"type":"string"},"default":[],"description":"Which cohort breakdowns the metric is published for, drawn from `all`, `boys`, `girls`, `disadvantaged`, `nonDisadvantaged`, `eal`, `nonEal`, `senSupport`, `ehcp`, `nonMobile`, `priorAttainmentLow`, `priorAttainmentMiddle` and `priorAttainmentHigh`."},"suppressionPolicy":{"type":["string","null"],"description":"The publishing authority's rule for withholding a value from a small cohort, for example `Suppressed when fewer than 6 pupils in cohort`. A null value can mean the figure was withheld rather than never measured."},"publishedSince":{"type":["string","null"],"pattern":"^\\d{4}-\\d{4}$","description":"The first academic year the metric was published for, as `YYYY-YYYY`."},"retiredIn":{"type":["string","null"],"pattern":"^\\d{4}-\\d{4}$","description":"The academic year after which the metric was withdrawn, as `YYYY-YYYY`. Null while it is still published."},"governingPublicationUrl":{"type":["string","null"],"format":"uri","description":"Canonical address of the publishing authority's methodology document."},"examplePayload":{"type":["object","null"],"additionalProperties":{},"description":"A worked example of how the metric appears inside a School response."}},"required":["code","framework","label","interpretedAs","unit"]},"CoverageMatrix":{"type":"object","properties":{"object":{"type":"string","enum":["coverage_matrix"]},"snapshotAt":{"type":"string","format":"date-time"},"objectVersion":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Dated shape version this report was generated under."},"cells":{"type":"array","items":{"$ref":"#/components/schemas/CoverageCell"},"description":"One row per territory and framework, ordered by territory then framework."},"summary":{"type":"object","properties":{"countriesCovered":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/CountryCode"},{"description":"A territory, as an ISO 3166-1 alpha-2 code."}]}},"frameworksCovered":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/SchoolFrameworkCode"},{"description":"Identifies a country × publishing authority × domain combination. Use to look up metric definitions via `/v1/schools/frameworks/{framework}`. Naming convention: `{country}_{authority}_{domain}`.\n\nSupported values:\n\n- `gb_eng_dfes_ks2` — England DfE Key Stage 2 performance — end-of-primary outcomes at age 11. Metrics include `PTRWM_EXP` (% at expected standard in reading/writing/maths combined) and progress scores `PROG_READ`/`PROG_WRIT`/`PROG_MAT`. Annual cadence.\n- `gb_eng_dfes_ks4` — England DfE Key Stage 4 performance — GCSE-stage outcomes at age 16. Metrics include `ATT8` (Attainment 8), `EBACCAPS` (EBacc Average Point Score), `P8MEA` (Progress 8). Annual cadence.\n- `gb_eng_dfes_ks5` — England DfE Key Stage 5 performance — post-16 outcomes for A-level, AS, technical and applied qualifications. Annual cadence.\n- `gb_eng_dfes_destinations_ks4` — England DfE post-KS4 destinations — education / apprenticeship / employment / NEET tracking for year-11 leavers, two-year lag.\n- `gb_eng_dfes_destinations_ks5` — England DfE post-KS5 destinations — higher-education entry, apprenticeships, employment for year-13 leavers.\n- `gb_eng_dfes_value_added` — England DfE KS5 value-added measures — by qualification and by subject.\n- `gb_eng_dfes_school_census` — England DfE School Census (Schools, Pupils and their Characteristics — SPC). Annual headcount + FSM + EAL + SEN by school.\n- `gb_eng_esfa_cfr` — England ESFA Consistent Financial Reporting — for maintained / local-authority schools. Annual income / expenditure / balances.\n- `gb_eng_esfa_aar` — England ESFA Academies Accounts Return — for academies, free schools and UTCs. Annual finance including trust central-services apportionment.\n- `gb_eng_lpa_admissions` — England local-authority published admissions outcomes — published-admission-number (PAN), preferences received, offers made, last-admitted distance, oversubscription criteria with offer counts. Cycle-keyed.\n- `gb_eng_ofsted_oeif` — England Ofsted Education Inspection Framework — pre-September-2025 inspection regime. Six numeric sub-judgements (1 outstanding..4 inadequate) plus optional early-years and sixth-form provision grades.\n- `gb_eng_ofsted_post_2025` — England Ofsted post-September-2025 reformed inspection — evaluation areas (1-5 ordinals) plus a special `safeguarding_grade` sentinel.\n- `gb_wls_welshgov_performance` — Wales Welsh Government performance data — scaffolded for future ingest; not currently populated.\n- `gb_wls_estyn_inspections` — Wales Estyn inspections — scaffolded for future ingest; not currently populated.\n- `gb_sct_education_scotland_performance` — Scotland Education Scotland performance — scaffolded for future ingest; not currently populated.\n- `gb_sct_hmie_inspections` — Scotland HMIE / Education Scotland inspections — scaffolded for future ingest; not currently populated.\n- `gb_nir_deni_performance` — Northern Ireland Department of Education performance — scaffolded for future ingest; not currently populated.\n- `gb_nir_eti_inspections` — Northern Ireland Education and Training Inspectorate (ETI) — scaffolded for future ingest; not currently populated.\n- `ie_doe_performance` — Ireland Department of Education performance — scaffolded for future ingest; not currently populated.\n- `ie_doe_inspections` — Ireland Department of Education inspections — scaffolded for future ingest; not currently populated."}]}},"totalSchools":{"type":"integer","minimum":0}},"required":["countriesCovered","frameworksCovered","totalSchools"],"description":"Totals across the whole matrix."}},"required":["object","snapshotAt","objectVersion","cells","summary"]},"CoverageCell":{"type":"object","properties":{"countryCode":{"allOf":[{"$ref":"#/components/schemas/CountryCode"},{"description":"A territory, as an ISO 3166-1 alpha-2 code."}]},"framework":{"allOf":[{"$ref":"#/components/schemas/SchoolFrameworkCode"},{"description":"Identifies a country × publishing authority × domain combination. Use to look up metric definitions via `/v1/schools/frameworks/{framework}`. Naming convention: `{country}_{authority}_{domain}`.\n\nSupported values:\n\n- `gb_eng_dfes_ks2` — England DfE Key Stage 2 performance — end-of-primary outcomes at age 11. Metrics include `PTRWM_EXP` (% at expected standard in reading/writing/maths combined) and progress scores `PROG_READ`/`PROG_WRIT`/`PROG_MAT`. Annual cadence.\n- `gb_eng_dfes_ks4` — England DfE Key Stage 4 performance — GCSE-stage outcomes at age 16. Metrics include `ATT8` (Attainment 8), `EBACCAPS` (EBacc Average Point Score), `P8MEA` (Progress 8). Annual cadence.\n- `gb_eng_dfes_ks5` — England DfE Key Stage 5 performance — post-16 outcomes for A-level, AS, technical and applied qualifications. Annual cadence.\n- `gb_eng_dfes_destinations_ks4` — England DfE post-KS4 destinations — education / apprenticeship / employment / NEET tracking for year-11 leavers, two-year lag.\n- `gb_eng_dfes_destinations_ks5` — England DfE post-KS5 destinations — higher-education entry, apprenticeships, employment for year-13 leavers.\n- `gb_eng_dfes_value_added` — England DfE KS5 value-added measures — by qualification and by subject.\n- `gb_eng_dfes_school_census` — England DfE School Census (Schools, Pupils and their Characteristics — SPC). Annual headcount + FSM + EAL + SEN by school.\n- `gb_eng_esfa_cfr` — England ESFA Consistent Financial Reporting — for maintained / local-authority schools. Annual income / expenditure / balances.\n- `gb_eng_esfa_aar` — England ESFA Academies Accounts Return — for academies, free schools and UTCs. Annual finance including trust central-services apportionment.\n- `gb_eng_lpa_admissions` — England local-authority published admissions outcomes — published-admission-number (PAN), preferences received, offers made, last-admitted distance, oversubscription criteria with offer counts. Cycle-keyed.\n- `gb_eng_ofsted_oeif` — England Ofsted Education Inspection Framework — pre-September-2025 inspection regime. Six numeric sub-judgements (1 outstanding..4 inadequate) plus optional early-years and sixth-form provision grades.\n- `gb_eng_ofsted_post_2025` — England Ofsted post-September-2025 reformed inspection — evaluation areas (1-5 ordinals) plus a special `safeguarding_grade` sentinel.\n- `gb_wls_welshgov_performance` — Wales Welsh Government performance data — scaffolded for future ingest; not currently populated.\n- `gb_wls_estyn_inspections` — Wales Estyn inspections — scaffolded for future ingest; not currently populated.\n- `gb_sct_education_scotland_performance` — Scotland Education Scotland performance — scaffolded for future ingest; not currently populated.\n- `gb_sct_hmie_inspections` — Scotland HMIE / Education Scotland inspections — scaffolded for future ingest; not currently populated.\n- `gb_nir_deni_performance` — Northern Ireland Department of Education performance — scaffolded for future ingest; not currently populated.\n- `gb_nir_eti_inspections` — Northern Ireland Education and Training Inspectorate (ETI) — scaffolded for future ingest; not currently populated.\n- `ie_doe_performance` — Ireland Department of Education performance — scaffolded for future ingest; not currently populated.\n- `ie_doe_inspections` — Ireland Department of Education inspections — scaffolded for future ingest; not currently populated."}]},"domain":{"type":"string","enum":["performance","destinations","value_added","census","finance","admissions","inspections","catchment"],"description":"Which top-level block of a School response this framework feeds."},"schoolBlockPath":{"type":"string","description":"Where this framework's data appears in a School response, for example `performance.ks4`."},"quality":{"$ref":"#/components/schemas/CoverageQuality"},"entitlementRequired":{"type":"string","description":"Identifier of the plan needed to access this block. The set of names is not fixed by this schema, so display the string as given rather than matching on it."},"notes":{"type":["string","null"]}},"required":["countryCode","framework","domain","schoolBlockPath","quality","entitlementRequired"]},"CoverageQuality":{"type":"object","properties":{"schoolsCovered":{"type":"integer","minimum":0,"description":"Number of schools that have data from this framework."},"schoolsExpected":{"type":"integer","minimum":0,"description":"Number of schools expected to have data from this framework. It is the denominator of `coveragePct`."},"coveragePct":{"type":"number","minimum":0,"maximum":100,"description":"`schoolsCovered` as a percentage of `schoolsExpected`. Minimum 0, maximum 100."},"latestAcademicYear":{"type":["string","null"],"pattern":"^\\d{4}-\\d{4}$"},"earliestAcademicYear":{"type":["string","null"],"pattern":"^\\d{4}-\\d{4}$"},"yearsLoaded":{"type":"integer","minimum":0,"description":"Number of distinct academic years held."},"cadence":{"type":"string","enum":["annual","monthly","rolling","ad_hoc","discontinued"]},"lastRefreshedAt":{"type":["string","null"],"format":"date-time"},"nextRefreshExpectedAt":{"type":["string","null"],"format":"date-time"}},"required":["schoolsCovered","schoolsExpected","coveragePct","latestAcademicYear","earliestAcademicYear","yearsLoaded","cadence","lastRefreshedAt","nextRefreshExpectedAt"]},"ChangelogListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/ChangelogEntry"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."},"ChangelogEntry":{"type":"object","properties":{"object":{"type":"string","enum":["changelog_entry"]},"objectVersion":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"Dated shape version this entry was published under."},"publishedAt":{"type":"string","format":"date-time"},"kind":{"type":"string","enum":["additive","deprecation","removal","fix"],"description":"What kind of change this entry records. `additive` adds a field or endpoint, `deprecation` marks one for later removal, `removal` takes away something already deprecated, and `fix` clarifies behaviour without changing the shape."},"affects":{"type":"array","items":{"type":"string"},"description":"The shapes and endpoints the change touches, for example `School.performance.ks4` or `endpoint:GET /v1/schools/{schoolId}`. Stable enough to compare between versions."},"description":{"type":"string","description":"Human-readable summary of the change."},"migrationNotes":{"type":["string","null"],"description":"What a client needs to change, on `deprecation` and `removal` entries."},"sunsetAt":{"type":["string","null"],"format":"date-time","description":"When the removal takes effect, on `deprecation` entries. The RFC 8594 `Sunset` header on the deprecated endpoint carries the same value."},"docUrl":{"type":["string","null"],"format":"uri"}},"required":["object","objectVersion","publishedAt","kind","affects","description"]},"GeocodePrecision":{"type":"string","enum":["rooftop","street_centre","approximate"],"description":"How the point for this match was derived.","example":"street_centre"},"StreetMatch":{"type":"object","properties":{"granularity":{"type":"string","enum":["street"],"description":"Always `street` on this branch: the result is a named street rather than a single premise."},"precision":{"allOf":[{"$ref":"#/components/schemas/GeocodePrecision"},{"description":"How the returned point was derived, which is what tells a caller how far to trust it. 'rooftop' is the premise itself. 'street_centre' is the centre of a street, returned with street-granularity results. 'approximate' is an area-level estimate, such as a postcode centroid, rather than the building."}]},"id":{"type":"string","description":"Stable identifier for the street, in the form `<country>-<scheme>:<value>` and unique across countries. Key street results on this rather than on a national identifier, which differs by country: the USRN in Great Britain, other schemes elsewhere.","example":"gb-usrn:34403617"},"country":{"type":"string","minLength":2,"maxLength":2,"description":"Territory the street sits in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"usrn":{"type":"number","description":"The Unique Street Reference Number (USRN), the statutory street identifier in Great Britain. Present on Great Britain results only.","example":34403617},"dataset":{"$ref":"#/components/schemas/StreetSource"},"name":{"type":"string","description":"Name of the street.","example":"West Street"},"town":{"type":"string","description":"Town the street sits in.","example":"Sheffield"},"locality":{"type":"string","description":"Locality within the town.","example":"City Centre"},"administrativeArea":{"type":"string","description":"Administrative area the street falls in.","example":"Sheffield"},"location":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Representative point for the street, at its centre.","title":"Coordinates"},"boundingBox":{"type":"object","properties":{"north":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the northern edge. Must be greater than `south`.","example":51.6},"south":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the southern edge. Must be less than `north`.","example":51.4},"east":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the eastern edge.","example":0},"west":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the western edge.","example":-0.3}},"required":["north","south","east","west"],"additionalProperties":false,"description":"Rectangle covering the street from its recorded start to its recorded end. Present when the dataset that supplied the street records its start and end, which the NGD does and the open data does not.","title":"Bounding Box"},"propertyCount":{"type":"number","description":"Number of addressable properties on the street.","example":1061},"confidence":{"type":"number","minimum":0,"maximum":100,"description":"How confident the match is, from 0 to 100.","example":88},"distance":{"type":"number","description":"Distance from the query point, in metres, to the nearest metre. Present when a point was supplied."}},"required":["granularity","precision","id","country","dataset","name","location","confidence"],"description":"A geocoding result at street granularity, identified by its street reference."},"AddressResolveRequest":{"type":"object","properties":{"address":{"type":"string","minLength":5,"maxLength":500,"description":"The address to resolve. Minimum 5 characters, maximum 500."},"options":{"type":"object","properties":{"confidenceThreshold":{"type":"number","minimum":0,"maximum":100,"description":"Minimum confidence, from 0 to 100, that a postcode-level fallback match must reach to count."},"fallbackThreshold":{"type":"number","minimum":0,"maximum":100,"description":"Confidence, from 0 to 100, below which postcode-level fallback matching runs as well. Defaults to 60."},"maxResults":{"type":"number","minimum":1,"maximum":100,"description":"Maximum number of matches to return. Defaults to 5. Minimum 1, maximum 100."},"enableFallback":{"type":"boolean","description":"Allow postcode-level fallback matching when the primary match is weak or absent. Defaults to true."},"includeProcessingDetails":{"type":"boolean","description":"Return what each stage of the match did, under `metadata.processingSteps`."},"timeout":{"type":"number","description":"Requested time budget for the match, in milliseconds."},"classification":{"type":"string","enum":["residential","commercial","all"],"description":"Filter matched addresses by how the property is used. 'residential' covers dwellings, including houses, flats and houses in multiple occupation. 'commercial' covers non-residential premises such as offices, retail and warehouses. 'all' applies no filter. Defaults to 'residential'."},"granularity":{"anyOf":[{"type":"string","enum":["address","street"]},{"type":"string","enum":["auto"]}],"description":"How specific the result should be. 'address', the default, resolves to a premise and its UPRN. 'street' resolves to a named street with a representative point, for partial inputs such as 'West Street, Sheffield' that carry no building number. 'auto' tries the premise first and drops to street level when no building matches."},"dataset":{"allOf":[{"$ref":"#/components/schemas/StreetDataset"},{"description":"Which street dataset street-level matches are read from, when `granularity` is 'street' or 'auto'. 'open' reads Ordnance Survey open data published under the Open Government Licence. 'ngd' reads the Ordnance Survey National Geographic Database (NGD). 'open_then_ngd' reads the open data first and turns to the NGD only when the open data matches no street. Defaults to 'open_then_ngd'. Rejected when `granularity` is 'address'."}]},"includeCoordinates":{"type":"boolean","description":"Return the matched premise's position as `coordinates` on each premise match. Defaults to false. A request that includes coordinates is charged at the full address record rate rather than the match rate."}},"description":"Settings that change how the address is matched."}},"required":["address"],"example":{"address":"10 Downing Street, London SW1A 2AA","options":{"classification":"residential","maxResults":5}}},"PostcodeLookupResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"postcode":{"type":"string","description":"The postcode these addresses belong to, formatted with a space.","example":"SW1A 2AA"},"url":{"type":"string","description":"Path this list was requested from."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PostcodeAddress"},"description":"The addresses on this page, ordered by house number ascending."},"total_count":{"type":"integer","description":"Total number of addresses at this postcode across all pages."},"has_more":{"type":"boolean","description":"True when further addresses exist beyond this page."},"geography":{"$ref":"#/components/schemas/GeographicContext"}},"required":["object","postcode","url","data","total_count","has_more"]},"PostcodeAddress":{"type":"object","properties":{"uprn":{"type":"string","description":"The Unique Property Reference Number (UPRN).","example":"100023336956"},"line_1":{"type":"string","description":"First line of the address: organisation, sub-building, building and street.","example":"10 DOWNING STREET"},"line_2":{"type":"string","description":"Second line of the address, carrying the Ordnance Survey locality (a suburb or estate within the settlement). Empty when the address has none. For the postal second line, the dependent locality, read `royal_mail.line_2`.","example":""},"line_3":{"type":"string","description":"Third line of the address. Empty when the address has no third line.","example":""},"post_town":{"type":"string","description":"The settlement the street sits in (city, town, village, hamlet or parish), as Ordnance Survey names it. Despite the field name this is the geographic town rather than the Royal Mail post town, and the two differ on roughly a quarter of addresses. The name and the value of this field are settled and stay as they are; for the postal town read `royal_mail.post_town`.","example":"LONDON"},"county":{"type":"string","description":"Ceremonial county for this address's postcode, from OS Boundary-Line, such as `Greater London`, `Merseyside` or `Powys`. Empty when it is not known: Northern Ireland has no ceremonial county, and the field is also empty when the geography service could not be reached. An empty string means the county is not known, never that the address has none. It is not part of `formatted`.","example":"Greater London"},"country":{"type":["string","null"],"description":"Nation this address sits in, as a slug: `england`, `scotland`, `wales` or `northern-ireland`. Null or absent when it is not known. Same vocabulary as `address.country` on the property surface.","example":"england"},"postcode":{"type":"string","description":"Full postcode of the address.","example":"SW1A 2AA"},"formatted":{"type":"string","description":"The whole address on one line, with the lines, town and postcode joined by commas.","example":"10 DOWNING STREET, LONDON, SW1A 2AA"},"coordinates":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Position of this address.","title":"Coordinates"},"classification_code":{"type":"string","description":"AddressBase classification code for how the property is used. Codes beginning `R` are residential and codes beginning `C` are commercial.","example":"RD"},"distance_metres":{"type":"number","description":"Distance from the query point, in metres. Returned by reverse geocoding only."},"royal_mail":{"$ref":"#/components/schemas/RoyalMailAddress"},"context":{"$ref":"#/components/schemas/AddressContext"}},"required":["uprn","line_1","line_2","line_3","post_town","county","postcode","formatted"]},"RoyalMailAddress":{"type":"object","properties":{"line_1":{"type":"string","description":"First postal address line: the premises and the street, composed by the Royal Mail PAF rules.","example":"3 Croftside Avenue"},"line_2":{"type":"string","description":"Second postal address line, carrying the dependent locality that the PAF rules give a line of its own. It is a different value from the flat `line_2`, which is the Ordnance Survey locality (a suburb or estate within the settlement).","example":"Whitburn"},"line_3":{"type":"string","description":"Any remaining address components, joined by commas. No part of the address is dropped.","example":""},"post_town":{"type":"string","description":"The town or city whose Royal Mail sorting office serves this address. The flat `post_town` field carries the Ordnance Survey settlement name instead, and the two differ on roughly a quarter of addresses.","example":"Sunderland"},"postcode":{"type":"string","description":"Postcode of this delivery point.","example":"SR6 7AU"},"udprn":{"type":"string","description":"Royal Mail's Unique Delivery Point Reference Number (UDPRN) for this delivery point.","example":"23188376"},"match_type":{"type":"string","description":"How closely Ordnance Survey tied this delivery point to the UPRN. `Direct`, which covers about 99.6% of the delivery points that carry a UPRN, is a match on the building itself; `Parent` matched a parent building and `Street` matched only the street, so anything other than `Direct` means the postal address is near this premise rather than exactly it. The vocabulary is Ordnance Survey's own and already includes a value their published feature specification does not list, so this is a plain string: read an unrecognised value as 'not a Direct match', not as an error.","example":"Direct"},"matched_feature_type":{"type":"string","description":"The Ordnance Survey feature type the delivery point was matched against.","example":"Built Address"}},"required":["line_1","line_2","line_3","post_town","postcode","udprn"],"description":"The postal view of this address, from Ordnance Survey's Royal Mail Address feature. Absent when the address has no Royal Mail delivery point, which is about one UPRN in six and includes many objects nothing can be delivered to. Absence means no postal address exists for this UPRN, which is a real answer rather than a gap."},"AddressContext":{"type":"object","properties":{"county":{"type":["string","null"],"description":"Ceremonial county for this address's postcode, from OS Boundary-Line. Null when it is not known: Boundary-Line covers Great Britain only, so Northern Ireland has no ceremonial county. Null means the county is not known, never that the address has none.","example":"Tyne & Wear"},"country":{"type":["string","null"],"description":"Nation this address sits in, as a slug: `england`, `scotland`, `wales` or `northern-ireland`. Null for the Channel Islands and the Isle of Man, which are Crown Dependencies rather than UK nations.","example":"england"}},"required":["county","country"],"description":"County and nation for this address's postcode. The flat `county` and `country` fields carry the same values; this object exists so the postcode-grained facts are identifiable as such."},"GeographicContext":{"type":"object","properties":{"lsoa":{"type":"object","properties":{"code":{"type":"string","description":"Code identifying the area. The statistical tiers carry the area's ONS GSS code."},"name":{"type":"string","description":"Name of the area."}},"required":["code","name"],"description":"Lower Layer Super Output Area (LSOA) containing the address."},"msoa":{"type":"object","properties":{"code":{"type":"string","description":"Code identifying the area. The statistical tiers carry the area's ONS GSS code."},"name":{"type":"string","description":"Name of the area."}},"required":["code","name"],"description":"Middle Layer Super Output Area (MSOA) containing the address."},"ward":{"type":"object","properties":{"code":{"type":"string","description":"Code identifying the area. The statistical tiers carry the area's ONS GSS code."},"name":{"type":"string","description":"Name of the area."}},"required":["code","name"],"description":"Electoral ward containing the address."},"constituency":{"type":"object","properties":{"code":{"type":"string","description":"Code identifying the area. The statistical tiers carry the area's ONS GSS code."},"name":{"type":"string","description":"Name of the area."}},"required":["code","name"],"description":"Westminster parliamentary constituency containing the address."},"parish":{"type":"object","properties":{"code":{"type":"string","description":"Code identifying the area. The statistical tiers carry the area's ONS GSS code."},"name":{"type":"string","description":"Name of the area."}},"required":["code","name"],"description":"Civil parish or community containing the address."},"district":{"type":"object","properties":{"code":{"type":"string","description":"Code identifying the area. The statistical tiers carry the area's ONS GSS code."},"name":{"type":"string","description":"Name of the area."}},"required":["code","name"],"description":"Local authority district containing the address."},"lpa":{"type":"object","properties":{"code":{"type":"string","description":"Code identifying the area. The statistical tiers carry the area's ONS GSS code."},"name":{"type":"string","description":"Name of the area."}},"required":["code","name"],"description":"Local planning authority for the address. It can differ from the district: national parks, development corporations and joint planning boards are the planning authority for their own areas."},"county":{"type":"object","properties":{"code":{"type":"string","description":"Code identifying the area. The statistical tiers carry the area's ONS GSS code."},"name":{"type":"string","description":"Name of the area."}},"required":["code","name"],"description":"Administrative county containing the address, as an ONS GSS area. Absent for unitary authorities, and across Scotland, Wales and Northern Ireland, which have no administrative county tier. For a county tier that covers all of Great Britain, read `ceremonialCounty`."},"ceremonialCounty":{"type":"object","properties":{"code":{"type":"string","description":"Code identifying the area. The statistical tiers carry the area's ONS GSS code."},"name":{"type":"string","description":"Name of the area."}},"required":["code","name"],"description":"Ceremonial county containing the address, from OS Boundary-Line. It covers the whole of Great Britain, unlike the administrative `county` tier, and is absent for Northern Ireland because Boundary-Line stops at the Great Britain coast. Ordnance Survey publishes no GSS or ISO identifier for ceremonial counties, so `code` here is a surrogate rather than a national statistical code: match on `name`, never on `code`. This is where the flat `county` string on each address in `data` comes from."},"region":{"type":"object","properties":{"code":{"type":"string","description":"Code identifying the area. The statistical tiers carry the area's ONS GSS code."},"name":{"type":"string","description":"Name of the area."}},"required":["code","name"],"description":"Region containing the address."},"country":{"type":"object","properties":{"code":{"type":"string","description":"Code identifying the area. The statistical tiers carry the area's ONS GSS code."},"name":{"type":"string","description":"Name of the area."}},"required":["code","name"],"description":"Country containing the address."}},"description":"Administrative and statistical geography for this postcode. Returned when `include=geography` is set."},"BulkPostcodeLookupResponse":{"type":"object","properties":{"object":{"type":"string","enum":["batch_result"]},"results":{"type":"object","additionalProperties":{"anyOf":[{"type":"object","properties":{"status":{"type":"number","enum":[200]},"data":{"type":"array","items":{"$ref":"#/components/schemas/PostcodeAddress"}},"total_count":{"type":"integer"}},"required":["status","data","total_count"]},{"type":"object","properties":{"status":{"type":"number","enum":[400]},"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["status","error"]},{"type":"object","properties":{"status":{"type":"number","enum":[404]},"error":{"type":"object","properties":{"message":{"type":"string"},"suggestions":{"type":"array","items":{"type":"string"}}},"required":["message"]}},"required":["status","error"]},{"type":"object","properties":{"status":{"type":"number","enum":[500]},"error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]}},"required":["status","error"]}]},"description":"One entry per postcode, keyed by the formatted postcode. Each entry carries its own status, so a postcode that could not be resolved does not fail the rest of the batch."},"total_postcodes":{"type":"integer","description":"Number of postcodes supplied in the request."},"successful":{"type":"integer","description":"Number of postcodes that resolved to at least one address."},"failed":{"type":"integer","description":"Number of postcodes that returned an error instead of addresses."}},"required":["object","results","total_postcodes","successful","failed"]},"BulkPostcodeLookupRequest":{"type":"object","properties":{"postcodes":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100,"description":"The postcodes to look up. Minimum 1, maximum 100."},"per_postcode":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of addresses to return for each postcode. Defaults to 50. Minimum 1, maximum 100."},"dataset":{"type":"string","enum":["os","paf"],"default":"os","description":"Which address dataset to read: 'os' for the Ordnance Survey address model, or 'paf' for the Royal Mail Postcode Address File. Defaults to 'os'."}},"required":["postcodes"]},"PostcodeValidationResponse":{"type":"object","properties":{"object":{"type":"string","enum":["postcode_validation"]},"postcode":{"type":"string","description":"The postcode as supplied, upper-cased, and formatted with a space when the format was recognised."},"valid":{"type":"boolean","description":"True when the postcode exists and is in use."},"format_valid":{"type":"boolean","description":"True when the postcode is well formed but could not be checked against the postcode index. Present only when that check could not be completed."},"active":{"type":"boolean","description":"True when the postcode is currently in use."},"coordinates":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Centroid of the postcode.","title":"Coordinates"},"country":{"type":"string","description":"Country the postcode sits in.","example":"England"},"region":{"type":"string","description":"Region the postcode sits in.","example":"London"},"codes":{"type":"object","properties":{"lsoa":{"type":"string"},"msoa":{"type":"string"},"ward":{"type":"string"}},"description":"Statistical area codes for the postcode: LSOA, MSOA and electoral ward."}},"required":["object","postcode","valid"]},"NearestPostcodesResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","description":"Path this list was requested from."},"data":{"type":"array","items":{"type":"object","properties":{"postcode":{"type":"string","description":"The nearby postcode.","example":"SW1A 2AB"},"distance_metres":{"type":"number","description":"Distance from the source postcode's centroid, in metres."},"coordinates":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Centroid of this postcode.","title":"Coordinates"},"country":{"type":"string","description":"Country this postcode sits in."}},"required":["postcode","distance_metres","coordinates"]},"description":"The nearby postcodes, nearest first."},"total_count":{"type":"integer","description":"Number of postcodes returned."},"source_postcode":{"type":"string","description":"The postcode the search started from, formatted with a space."},"source_coordinates":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Centroid of the source postcode, which is the point distances are measured from.","title":"Coordinates"},"radius":{"type":"number","description":"Search radius applied, in metres."},"has_more":{"type":"boolean","description":"Always false: this endpoint returns a single page of up to `limit` postcodes."}},"required":["object","url","data","source_postcode","source_coordinates","radius","has_more"]},"ReverseGeocodeResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string","description":"Path this list was requested from."},"data":{"type":"array","items":{"$ref":"#/components/schemas/PostcodeAddress"},"description":"Addresses near the query point, nearest first."},"coordinates":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"The point that was searched from.","title":"Coordinates"},"radius":{"type":"number","description":"Search radius applied, in metres."},"has_more":{"type":"boolean","description":"Always false: this endpoint returns a single page of up to `limit` addresses."},"total_count":{"type":"integer","description":"Number of addresses returned."}},"required":["object","url","data","coordinates","radius","has_more"]},"OutcodeLookupResponse":{"type":"object","properties":{"object":{"type":"string","enum":["outcode"]},"outcode":{"type":"string","description":"The outward code, the first part of a postcode, such as `SW1A`.","example":"SW1A"},"coordinates":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"A representative point for this area, taken from one of its postcodes rather than computed as a centroid.","title":"Coordinates"},"country":{"type":"string","description":"Country of the representative postcode for this area."},"region":{"type":"string","description":"Region of the representative postcode for this area."},"local_authority":{"type":"string","description":"Local authority of the representative postcode for this area."},"postcode_count":{"type":"integer","description":"Number of postcodes sharing this outward code."},"postcodes":{"type":"array","items":{"type":"string"},"description":"The postcodes in this outward code, in ascending order, up to 500. Returned when `include=postcodes` is set."}},"required":["object","outcode","postcode_count"]},"UprnLookupResponse":{"type":"object","properties":{"object":{"type":"string","enum":["address"]},"uprn":{"type":"string","description":"The Unique Property Reference Number (UPRN)."},"line_1":{"type":"string","description":"First line of the address: organisation, sub-building, building and street."},"line_2":{"type":"string","description":"Second line of the address, carrying the Ordnance Survey locality. Empty when there is none."},"line_3":{"type":"string","description":"Third line of the address. Empty when the address has no third line."},"post_town":{"type":"string","description":"The settlement the street sits in, as Ordnance Survey names it. For the postal town read `royal_mail.post_town`."},"county":{"type":"string","description":"Ceremonial county for this address's postcode, from OS Boundary-Line. Empty when it is not known; see `PostcodeAddress.county`."},"country":{"type":["string","null"],"description":"Nation this address sits in, as a slug: `england`, `scotland`, `wales` or `northern-ireland`. Null or absent when it is not known."},"postcode":{"type":"string","description":"Full postcode of the address."},"formatted":{"type":"string","description":"The whole address on one line, with the parts joined by commas."},"coordinates":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Position of this address.","title":"Coordinates"},"classification_code":{"type":"string","description":"AddressBase classification code for how the property is used."},"royal_mail":{"allOf":[{"$ref":"#/components/schemas/RoyalMailAddress"},{"description":"The postal view of this address. Absent when the UPRN has no Royal Mail delivery point."}]},"context":{"allOf":[{"$ref":"#/components/schemas/AddressContext"},{"description":"County and nation for this address's postcode."}]},"geography":{"allOf":[{"$ref":"#/components/schemas/GeographicContext"},{"description":"Administrative and statistical geography for this address's postcode. Returned when `include=geography` is set."}]}},"required":["object","uprn","line_1","line_2","line_3","post_town","county","postcode","formatted"]},"AddressCleanseResponse":{"type":"object","properties":{"object":{"type":"string","enum":["cleanse_result"]},"results":{"type":"array","items":{"type":"object","properties":{"input":{"type":"string","description":"The address string that was submitted."},"id":{"type":"string","description":"The identifier supplied with this address, when one was given."},"result":{"allOf":[{"$ref":"#/components/schemas/PostcodeAddress"},{"description":"The matched address. Absent when nothing matched."}]},"confidence":{"type":"number","minimum":0,"maximum":100,"description":"How confident the match is, from 0 to 100."},"corrected":{"type":"boolean","description":"True when the matched address differs from the text that was submitted."},"quality":{"type":"object","properties":{"grade":{"type":"string","enum":["A","B","C","D","F"],"description":"How good the match is, from `A` down to `F`. `A` and `B` are reliable enough to accept without review, `C` and `D` are put forward for review, and `F` is not usable. Read `action` for the recommendation that follows from the grade."},"action":{"type":"string","enum":["accept","review","reject"],"description":"What to do with this match, given its quality."},"isReliable":{"type":"boolean","description":"True when the match is strong enough to use without human review."},"reason":{"type":"string","description":"Human-readable explanation of the quality assessment."}},"required":["grade","action","isReliable","reason"],"description":"How good the match is, and what to do with it."},"changes":{"type":"object","additionalProperties":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}},"required":["from","to"]},"description":"The fields that changed, keyed by field name, each carrying its `from` and `to` value."}},"required":["input","confidence","corrected"]},"description":"One result per submitted address, in the order they were sent."},"total":{"type":"integer","description":"Number of addresses processed."},"summary":{"type":"object","properties":{"accepted":{"type":"integer","description":"Number of results whose recommended action is accept."},"review":{"type":"integer","description":"Number of results whose recommended action is review."},"rejected":{"type":"integer","description":"Number of results whose recommended action is reject, plus those that matched nothing."}},"required":["accepted","review","rejected"],"description":"Counts of the results by recommended action."}},"required":["object","results","total","summary"]},"AddressCleanseRequest":{"type":"object","properties":{"addresses":{"type":"array","items":{"type":"object","properties":{"input":{"type":"string","minLength":5,"maxLength":500,"description":"The raw address string to cleanse. Minimum 5 characters, maximum 500.","example":"10 Downing Street, London SW1A 2AA"},"id":{"type":"string","description":"Your own identifier for this address, returned on the matching result so the two line up."}},"required":["input"]},"minItems":1,"maxItems":25,"description":"The addresses to cleanse. Minimum 1, maximum 25."}},"required":["addresses"]},"AVMPredictResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"True when a valuation was produced.","example":true},"estimatedPrice":{"type":"number","description":"Estimated value of the property, in pounds. For a rental valuation this is the monthly rent.","example":2005366},"confidenceInterval":{"$ref":"#/components/schemas/AVMConfidenceInterval"},"metadata":{"$ref":"#/components/schemas/AVMMetadata"},"priceRatingInfo":{"$ref":"#/components/schemas/AVMPriceRating"}},"required":["success","estimatedPrice","confidenceInterval"],"description":"A completed property valuation.","example":{"success":true,"estimatedPrice":2005366,"confidenceInterval":{"lower":1866827,"upper":2236264},"metadata":{"modelName":"python-ml-ensemble","confidenceScore":0.73,"comparablesCount":39}}},"AVMConfidenceInterval":{"type":"object","properties":{"lower":{"type":"number","description":"Lower bound of the range, in pounds.","example":1866827},"upper":{"type":"number","description":"Upper bound of the range, in pounds.","example":2236264}},"required":["lower","upper"],"description":"A range for the value, in the same units as `estimatedPrice`. For a sale valuation it is a nominal 80 per cent range.","example":{"lower":1866827,"upper":2236264}},"AVMMetadata":{"type":"object","properties":{"modelName":{"type":"string","description":"Identifier of the model that produced the estimate.","example":"python-ml-ensemble"},"confidenceScore":{"type":"number","minimum":0,"maximum":1,"description":"How much confidence to place in the estimate, from 0 to 1, where 1 is the most confident. For a sale valuation it is one minus the typical error of past valuations of comparable properties, so 0.88 means half of those valuations landed within 12 per cent of the price the property sold for.","example":0.73},"comparablesCount":{"type":"integer","description":"Number of comparable properties the estimate was based on.","example":39}},"required":["modelName","confidenceScore"],"description":"Information about how the estimate was produced and the evidence behind it.","example":{"modelName":"python-ml-ensemble","confidenceScore":0.73,"comparablesCount":39}},"AVMPriceRating":{"type":"object","properties":{"rating":{"type":"number","minimum":1,"maximum":5,"description":"Where the supplied price sits against the estimated market value, from 1 (at least 10% below the estimate) to 5 (more than 5% above it).","example":4},"ratingLabel":{"type":"string","description":"Label for the rating, one of `Lower Price`, `Great Price`, `Good Price`, `Fair Price` and `Higher Price`.","example":"Good Value"},"explanation":{"type":"string","description":"Sentence explaining the rating, quoting how far the supplied price sits from the estimate.","example":"The input price is 2.0% below estimated market value, representing good value for buyers."},"percentageDifference":{"type":"number","description":"How far the supplied price sits from the estimate, as a percentage of the estimate. Negative when the supplied price is below the estimate, positive when it is above.","example":-2}},"required":["rating","ratingLabel","explanation","percentageDifference"],"description":"Comparison of `inputPrice` against the estimate. Present only when `ratePrice` is true and `inputPrice` was supplied.","example":{"rating":4,"ratingLabel":"Good Value","explanation":"The input price is 2.0% below estimated market value, representing good value for buyers.","percentageDifference":-2}},"AVMPredictRequest":{"type":"object","properties":{"propertyType":{"type":"string","enum":["detached","semiDetached","terraced","flat","bungalow","maisonette","cottage","chalet","lodge","characterProperty","mobileHome","retirement","blockOfFlats","farmhouse","unknown","other"],"description":"Type of the property being valued. Types outside the core set, such as `maisonette`, `cottage` and `chalet`, are mapped onto the closest core type before the valuation runs.","example":"flat"},"beds":{"type":"integer","minimum":0,"maximum":20,"description":"Number of bedrooms. Minimum 0, maximum 20.","example":2},"baths":{"type":"integer","minimum":0,"maximum":20,"description":"Number of bathrooms. Minimum 0, maximum 20.","example":1},"floorArea":{"type":"number","minimum":1,"maximum":10000,"description":"Floor area in square metres. Minimum 1, maximum 10000.","example":70},"condition":{"type":"string","enum":["poor","average","good","excellent","newBuild"],"description":"Physical condition of the property.","example":"good"},"yearBuilt":{"type":"integer","minimum":1700,"maximum":2100,"description":"Year the property was built. Minimum 1700, maximum 2100.","example":2010},"epc":{"type":"string","enum":["A","B","C","D","E","F","G"],"description":"Energy Performance Certificate band held for the property.","example":"C"},"listingPrice":{"type":"number","minimum":0,"description":"Current asking price for the property, in pounds, where it is on the market.","example":500000},"inputPrice":{"type":"number","minimum":0,"description":"Price to compare against the estimated market value. Rated only when `ratePrice` is true.","example":490000},"ratePrice":{"type":"boolean","description":"Set to true to rate `inputPrice` against the estimated market value. The rating comes back in `priceRatingInfo`, and both fields must be supplied for it to appear.","example":false},"transactionType":{"type":"string","enum":["sale","rent"],"default":"sale","description":"Whether to value the property for sale or for letting. Defaults to `sale`.","example":"sale"},"postcode":{"type":"string","description":"Postcode of the property. Supply either this or both `latitude` and `longitude`.","example":"SW1A 1AA"},"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the property in WGS84 decimal degrees. Must be supplied together with `longitude`, and can be used in place of `postcode`.","example":51.5014},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the property in WGS84 decimal degrees. Must be supplied together with `latitude`, and can be used in place of `postcode`.","example":-0.1419}},"required":["propertyType","beds"],"example":{"propertyType":"flat","beds":2,"baths":1,"floorArea":70,"transactionType":"sale","postcode":"SW1A 1AA"}},"AVMPredictByLocationRequest":{"type":"object","properties":{"locationId":{"type":"string","minLength":1,"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN).","example":"456def"},"transactionType":{"type":"string","enum":["sale","rent"],"default":"sale","description":"Whether to value the property for sale or for letting. Defaults to `sale`.","example":"sale"},"propertyType":{"type":"string","enum":["detached","semiDetached","terraced","flat","bungalow","maisonette","cottage","chalet","lodge","characterProperty","mobileHome","retirement","blockOfFlats","farmhouse","unknown","other"],"description":"Overrides the property type held for this location. Sending `unknown` leaves the held type in place.","example":"flat"},"beds":{"type":"integer","minimum":0,"maximum":20,"description":"Overrides the bedroom count held for this location. Minimum 0, maximum 20.","example":2},"baths":{"type":"integer","minimum":0,"maximum":20,"description":"Overrides the bathroom count held for this location. Minimum 0, maximum 20.","example":1},"floorArea":{"type":"number","minimum":1,"maximum":10000,"description":"Overrides the floor area held for this location, in square metres. Minimum 1, maximum 10000.","example":70},"condition":{"type":"string","enum":["poor","average","good","excellent","newBuild"],"description":"Overrides the condition held for this location.","example":"good"},"yearBuilt":{"type":"integer","minimum":1700,"maximum":2100,"description":"Overrides the build year held for this location. Minimum 1700, maximum 2100.","example":2010},"epc":{"type":"string","enum":["A","B","C","D","E","F","G"],"description":"Overrides the Energy Performance Certificate band held for this location.","example":"C"},"listingPrice":{"type":"number","minimum":0,"description":"Overrides the asking price held for this location, in pounds.","example":500000},"inputPrice":{"type":"number","minimum":0,"description":"Price to compare against the estimated market value. Rated only when `ratePrice` is true.","example":490000},"ratePrice":{"type":"boolean","description":"Set to true to rate `inputPrice` against the estimated market value. The rating comes back in `priceRatingInfo`, and both fields must be supplied for it to appear.","example":false}},"required":["locationId"],"description":"A valuation request for a known location. Any characteristic supplied here replaces the value held for that location.","example":{"locationId":"456def","transactionType":"sale"}},"AVMAnalysisResponse":{"type":"object","properties":{"success":{"type":"boolean","description":"True when a valuation was produced.","example":true},"valuation":{"type":"object","properties":{"estimatedPrice":{"type":"number","description":"Estimated value of the property, in pounds. For a rental valuation this is the monthly rent.","example":425000},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"How much confidence to place in the estimate, from 0 to 1, where 1 is the most confident. For a sale valuation it is one minus the typical error of past valuations of comparable properties, so 0.88 means half of those valuations landed within 12 per cent of the price the property sold for.","example":0.85},"confidenceInterval":{"allOf":[{"$ref":"#/components/schemas/AVMConfidenceInterval"},{"description":"A range for the value, on the same basis and in the same units as `estimatedPrice`. For a sale valuation it is a nominal 80 per cent range, built from how far past valuations of comparable properties landed from the price each property sold for. That range is not centred on `estimatedPrice` and is wider where the local evidence is more varied. For a rental valuation the bounds sit the same distance either side of the estimate, in the same units, and are wider where the models behind the estimate agreed less closely."}]},"modelAgreement":{"type":"number","minimum":0,"maximum":1,"description":"How closely the models in the ensemble agreed on the estimate, from 0 to 1.","example":0.92}},"required":["estimatedPrice","confidence","confidenceInterval"],"description":"The current valuation for the property."},"comparables":{"type":"object","properties":{"total":{"type":"integer","description":"Number of comparable properties found for the subject property.","example":42},"tierSummary":{"type":"object","properties":{"excellent":{"type":"integer"},"good":{"type":"integer"},"acceptable":{"type":"integer"},"excluded":{"type":"integer"}},"required":["excellent","good","acceptable","excluded"],"description":"How many comparables fall in each tier."},"list":{"type":"array","items":{"$ref":"#/components/schemas/AnalysisComparable"},"description":"The comparable properties, each with its tier and any price adjustment applied."}},"required":["total","tierSummary","list"],"description":"The comparable evidence behind the valuation."},"marketStats":{"type":"object","properties":{"medianPrice":{"type":"number","description":"Median price across the comparables, in pounds.","example":410000},"meanPrice":{"type":"number","description":"Mean price across the comparables, in pounds.","example":418000},"medianPricePerSqm":{"type":"number","description":"Median price per square metre across the comparables, in pounds.","example":4250},"priceRange":{"type":"object","properties":{"min":{"type":"number"},"max":{"type":"number"}},"required":["min","max"],"description":"Lowest and highest price among the comparables, in pounds."},"weightedAverage":{"type":"number","description":"Average price across the comparables, weighted by how much each one counted.","example":422000}},"required":["medianPrice","meanPrice","priceRange","weightedAverage"],"description":"Price statistics across the comparables used."},"propertyFactors":{"type":"object","properties":{"propertyType":{"type":"string"},"beds":{"type":"integer"},"baths":{"type":"integer"},"floorArea":{"type":"number"},"condition":{"type":"string"},"epc":{"type":"string"},"yearBuilt":{"type":"integer"}},"description":"The subject property's characteristics as the valuation used them, after any overrides."},"confidence":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":1},"modelAgreement":{"type":"number","minimum":0,"maximum":1},"dataQuality":{"type":"number","minimum":0,"maximum":1},"modelWeights":{"type":"object","properties":{"xgboost":{"type":"number"},"lightgbm":{"type":"number"},"neural":{"type":"number"}},"required":["xgboost","lightgbm","neural"],"description":"Share of the estimate contributed by each model in the ensemble."},"limitingFactors":{"type":"array","items":{"type":"string"},"description":"Human-readable reasons that confidence in this valuation is limited."},"comparablesQuality":{"type":"object","properties":{"highQualityRatio":{"type":"number","description":"Share of the comparables used that fall in the `excellent` or `good` tiers."},"floorAreaCoverage":{"type":"number","description":"Share of the comparables used whose floor area came from a verified record."},"avgDistanceKm":{"type":"number"},"avgTransactionAgeMonths":{"type":"number"}},"required":["highQualityRatio","floorAreaCoverage","avgDistanceKm","avgTransactionAgeMonths"],"description":"Quality measures for the comparable evidence."}},"description":"How much confidence to place in the valuation, broken down by model agreement, subject data quality and the quality of the comparable evidence."},"priceSpread":{"type":"object","properties":{"forecastStdDev":{"type":["number","null"],"description":"Spread of the comparable prices, as a percentage of their mean. Null when fewer than five comparables were usable."},"fsdBand":{"type":["string","null"],"enum":["low","moderate","high","very_high",null],"description":"Band the spread falls in: `low` under 15%, `moderate` under 25%, `high` under 40%, `very_high` at 40% or above. Null when fewer than five comparables were usable."},"coefficientOfVariation":{"type":["number","null"],"description":"Standard deviation of the comparable prices divided by their mean. Lower values mean the prices are more consistent."},"sameBedSpreadPct":{"type":["number","null"],"description":"Gap between the cheapest and dearest comparable with the same bedroom count, as a percentage of the cheapest."},"warnings":{"type":"array","items":{"type":"string"},"description":"Human-readable warnings about how widely the comparable prices vary."}},"required":["forecastStdDev","fsdBand","coefficientOfVariation","sameBedSpreadPct","warnings"],"description":"How widely the comparable prices vary, as a check on how much weight to put on the estimate. Absent when no spread analysis was produced."},"issues":{"type":"array","items":{"type":"object","properties":{"severity":{"type":"string","enum":["error","warning","info"]},"message":{"type":"string"}},"required":["severity","message"]},"description":"Data quality problems found while producing this analysis."},"history":{"type":"object","properties":{"valuations":{"type":"array","items":{"$ref":"#/components/schemas/HistoricalValuation"}},"summary":{"type":"object","properties":{"change12Month":{"type":"object","properties":{"amount":{"type":"number"},"percentage":{"type":"number"}},"required":["amount","percentage"]},"change6Month":{"type":"object","properties":{"amount":{"type":"number"},"percentage":{"type":"number"}},"required":["amount","percentage"]},"trend":{"type":"string","enum":["rising","stable","falling"]}},"required":["trend"]}},"required":["valuations","summary"],"description":"Valuations for the subject property over the requested window, with the change across it. Absent when history was not requested or none could be produced."},"saleHistory":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string"},"price":{"type":"number"}},"required":["date","price"]},"description":"Recorded sales of the subject property. Absent when none are held."}},"required":["success","valuation","comparables","marketStats","propertyFactors","confidence","issues"],"description":"A full valuation analysis: the estimate, the comparable evidence behind it, market statistics, confidence detail and history."},"AnalysisComparable":{"type":"object","properties":{"propertyId":{"type":"string","description":"Identifier for the comparable property.","example":"prop_123abc"},"price":{"type":"number","description":"Price recorded for the comparable, in pounds.","example":425000},"beds":{"type":"integer","description":"Number of bedrooms in the comparable.","example":3},"baths":{"type":"integer","description":"Number of bathrooms in the comparable.","example":2},"propertyType":{"type":"string","description":"Type of the comparable property.","example":"semiDetached"},"floorArea":{"type":"number","description":"Floor area of the comparable, in square metres.","example":95},"distanceMeters":{"type":"number","description":"Distance from the subject property, in metres.","example":450},"transactionAge":{"type":"number","description":"Age of the transaction, in days.","example":120},"tier":{"type":"string","enum":["excellent","good","acceptable","excluded"],"description":"How closely the comparable matches the subject property.","example":"excellent"},"tierReasons":{"type":"array","items":{"type":"string"},"description":"Human-readable reasons the comparable was placed in its tier.","example":["Same beds","Same property type","Within 1km"]},"weight":{"type":"number","description":"Relative influence this comparable had on the estimate. Larger values count for more.","example":0.85},"adjustedPrice":{"type":"number","description":"Price of the comparable after adjustment for differences in bedrooms, property type and floor area against the subject property.","example":438000},"hedonicAdjustment":{"type":"object","properties":{"originalPrice":{"type":"number","description":"Price of the comparable before adjustment, in pounds."},"adjustedPrice":{"type":"number","description":"Price of the comparable after adjustment, in pounds."},"adjustmentFactor":{"type":"number","description":"Multiplier applied to `originalPrice` to reach `adjustedPrice`. A value of 1.03 raises the price by 3%.","example":1.03},"breakdown":{"type":"object","properties":{"bedroomAdjustment":{"type":"number","description":"Bedroom component of the adjustment, as a proportion of the comparable's price, so 0.08 is an uplift of 8%."},"propertyTypeAdjustment":{"type":"number","description":"Property type component of the adjustment, as a proportion of the comparable's price."},"floorAreaAdjustment":{"type":"number","description":"Floor area component of the adjustment, as a proportion of the comparable's price."}},"required":["bedroomAdjustment","propertyTypeAdjustment","floorAreaAdjustment"]},"sourceLevel":{"type":"string","enum":["lsoa","lad","region","national"],"description":"How local the price coefficients behind the adjustment are: the property's own Lower Layer Super Output Area (LSOA), its local authority district, its region, or national."}},"required":["originalPrice","adjustedPrice","adjustmentFactor","breakdown","sourceLevel"],"description":"How this comparable's price was adjusted towards the subject property. Absent when no adjustment was applied."},"address":{"type":"string","description":"Display address of the comparable property.","example":"4 The Hollies, Manchester, M20 2GD"},"pricePerSqm":{"type":"number","description":"Price per square metre for the comparable, in pounds.","example":4500},"estimatedFloorArea":{"type":"boolean","description":"True when `floorArea` was estimated rather than taken from a verified record for the property."}},"required":["propertyId","price","tier","tierReasons"],"description":"A comparable property, with the tier it was placed in and any price adjustment applied to it."},"HistoricalValuation":{"type":"object","properties":{"date":{"type":"string","description":"Date the valuation applies to, as an ISO 8601 date.","example":"2025-01-01"},"estimatedPrice":{"type":"number","description":"Estimated value at that date, in pounds.","example":425000},"confidenceInterval":{"type":"object","properties":{"lower":{"type":"number"},"upper":{"type":"number"}},"required":["lower","upper"],"description":"Lower and upper bounds for the value at that date, in pounds. A wider range means less certainty in the valuation for that date."},"confidence":{"type":"number","minimum":0,"maximum":1,"description":"How much confidence to place in this valuation, from 0 to 1, where 1 is the most confident.","example":0.85},"comparablesCount":{"type":"integer","description":"Number of comparable properties behind this valuation.","example":42}},"required":["date","estimatedPrice","confidenceInterval","confidence","comparablesCount"],"description":"The valuation for the subject property at one point in the past."},"AVMAnalysisRequest":{"type":"object","properties":{"locationId":{"type":"string","minLength":1,"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN).","example":"456def"},"transactionType":{"type":"string","enum":["sale","rent"],"default":"sale","description":"Whether to value the property for sale or for letting. Defaults to `sale`.","example":"sale"},"includeHistory":{"type":"boolean","default":true,"description":"Set to false to leave the historical valuations out of the response. Defaults to true.","example":true},"historyMonths":{"type":"integer","minimum":3,"maximum":24,"default":12,"description":"How many months of history to return. Defaults to 12. Minimum 3, maximum 24.","example":12}},"required":["locationId"],"description":"A request for a full valuation analysis, with comparable evidence and history.","example":{"locationId":"456def","transactionType":"sale","includeHistory":true,"historyMonths":12}},"SearchResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/SearchResult"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250},"search_id":{"type":["string","null"],"description":"Identifies the set of candidates this response was drawn from. Send it back as the `search_id` query parameter on the next keystroke and the query narrows within that set instead of fetching again. Null when no set was formed.","example":"3f8a2c1e-9b7d-4e6f-8a2c-1e9b7d4e6f8a"},"set_complete":{"type":"boolean","description":"True when these results are every match for the query, so further keystrokes can be filtered in the client without another request. False when this is one page of a larger set, or the set was too big to fetch whole.","example":true},"metadata":{"type":"object","properties":{"queryPattern":{"type":"string","enum":["postcode","address","general"],"description":"What the query text was read as."},"sources":{"type":"array","items":{"type":"string","enum":["address","location"],"description":"Which body of UK data a result comes from. 'address' covers individual premises, each with its own Unique Property Reference Number (UPRN). 'location' covers postcodes, places, towns and other geographic areas."},"description":"The data sources this response drew on.","example":["location","address"]},"processingTime":{"type":"string","description":"How long the query took, in milliseconds, as a string such as '45ms'.","example":"45ms"},"attribution":{"type":"string","description":"The attribution that must be shown wherever the open-data street fields in this response are displayed. Present when at least one returned street carries open data.","example":"Contains OS data © Crown copyright and database right 2026."}},"description":"How the query was interpreted and how long it took."}},"required":["object","url","has_more","data"]},"SearchResult":{"type":"object","properties":{"id":{"type":"string","description":"Identifier for this result, unique within the response.","example":"addr-abc123"},"title":{"type":"string","description":"The result's label, ready to display.","example":"10 Downing Street"},"description":{"type":"string","description":"Supporting line to show beneath the title.","example":"Westminster, London SW1A 2AA"},"type":{"type":"string","description":"What kind of place this result is, such as `address`, `postcode`, `street` or `locality`.","example":"address"},"score":{"type":"number","description":"Raw relevance score, comparable only within one response.","example":0.95},"relevanceScore":{"type":"number","minimum":0,"maximum":1,"description":"Relevance rescaled to a 0 to 1 range across this response, so results here can be compared.","example":0.85},"source":{"type":"string","enum":["address","location"],"description":"Which body of data this result came from."},"path":{"type":"string","description":"Path identifying this result in the location hierarchy. Not present in every response.","example":"/property/abc123"},"address":{"type":"string","description":"The full address on one line.","example":"10 Downing Street, London SW1A 2AA"},"location":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Position of this result.","title":"Coordinates"},"distance":{"type":"number","description":"Distance from the query point, in metres, when the request supplied one.","example":500},"highlights":{"type":"array","items":{"$ref":"#/components/schemas/SearchHighlight"},"description":"Where the query matched, per field, for highlighting in a results list.","example":[{"field":"address","fragments":["10 <em>Downing</em> Street, Westminster"],"matchedTerms":["downing"]}]},"metadata":{"type":"object","additionalProperties":{},"description":"Extra fields for this result, which vary by result type.","example":{"postcode":"SW1A 1AA","town":"London","locality":"Westminster"}},"main_text":{"type":"string","description":"The line to show first: the building and street.","example":"10 Downing Street"},"secondary_text":{"type":"string","description":"The line to show underneath: the locality, town and postcode.","example":"Westminster, London, SW1A 2AA"},"matched_substrings":{"type":"array","items":{"$ref":"#/components/schemas/MatchedSubstring"},"description":"Where the query matched within `title`, as character ranges, in ascending order."},"main_text_matched_substrings":{"type":"array","items":{"$ref":"#/components/schemas/MatchedSubstring"},"description":"Where the query matched within `main_text`, as character ranges, in ascending order."},"uprn":{"type":"string","description":"The Unique Property Reference Number (UPRN). Present on address results.","example":"100023336956"},"postcode":{"type":"string","description":"Postcode of this result.","example":"SW1A 2AA"}},"required":["id","title","type","score","relevanceScore","source"]},"SearchHighlight":{"type":"object","properties":{"field":{"type":"string","description":"Name of the field these fragments come from.","example":"address"},"fragments":{"type":"array","items":{"type":"string"},"description":"Extracts of the field's text, with the matching words wrapped in an HTML tag.","example":["10 <em>Downing</em> Street, Westminster","London <em>SW1A 2AA</em>"]},"matchedTerms":{"type":"array","items":{"type":"string"},"description":"The query terms that matched in this field. Not present in every response.","example":["downing","sw1a"]}},"required":["field","fragments"]},"MatchedSubstring":{"type":"object","properties":{"offset":{"type":"integer","minimum":0,"description":"Zero-based character position where the match starts."},"length":{"type":"integer","minimum":1,"description":"Length of the match, in characters."}},"required":["offset","length"]},"CouncilListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`.","example":"list"},"url":{"type":"string","description":"URL this list was requested from.","example":"/v1/councils"},"has_more":{"type":"boolean","description":"True when further results exist beyond this page. Councils are returned in a single page, so it is always false.","example":false},"data":{"type":"array","items":{"$ref":"#/components/schemas/Council"},"description":"The councils matching the request."},"total_count":{"type":"number","description":"Total number of councils matching the request.","example":389}},"required":["object","url","has_more","data"]},"Council":{"type":"object","properties":{"object":{"type":"string","enum":["council"],"description":"Object type discriminator. Always `council`.","example":"council"},"id":{"type":"string","format":"uuid","description":"Stable identifier for the council.","example":"550e8400-e29b-41d4-a716-446655440000"},"name":{"type":"string","description":"Official name of the council.","example":"Manchester City Council"},"normalisedName":{"type":"string","description":"The council's name reduced to a normalised form for matching. Unique within a country.","example":"manchester city council"},"country":{"type":"string","enum":["GB","IE"],"description":"Country the council operates in: `GB` for Great Britain, `IE` for Ireland.","example":"GB"},"type":{"type":["string","null"],"enum":["unitary","metropolitan","county","london_borough","district","local_authority",null],"description":"Which kind of local authority the council is.","example":"metropolitan"},"status":{"type":"string","enum":["active","merged","abolished","inactive"],"description":"Whether the council is still operating, and if not, what became of it.","example":"active"},"providerId":{"type":["string","null"],"description":"Code identifying the council, unique across councils. It is the value to pass to `GET /v1/councils/{providerId}`.","example":"manchester-city"},"onsCode":{"type":["string","null"],"description":"Office for National Statistics code for the council's area.","example":"E08000003"},"gssCode":{"type":["string","null"],"description":"Government Statistical Service code for the council's area.","example":"E08000003"},"councilCode":{"type":["string","null"],"description":"Code identifying an Irish council.","example":"CarlowCC"},"contactDetails":{"$ref":"#/components/schemas/CouncilContactDetails"},"branding":{"$ref":"#/components/schemas/CouncilBranding"},"serviceUrls":{"$ref":"#/components/schemas/CouncilServiceUrls"},"metadata":{"$ref":"#/components/schemas/CouncilMetadata"},"verified":{"type":"boolean","description":"True when this council record has been verified. Unverified records are returned too.","example":true},"createdAt":{"type":"string","description":"When this record first appeared in the API, as an ISO 8601 timestamp.","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","description":"When this record was last updated, as an ISO 8601 timestamp.","example":"2024-01-01T00:00:00.000Z"}},"required":["object","id","name","normalisedName","country","type","status","providerId","onsCode","gssCode","verified","createdAt","updatedAt"]},"CouncilContactDetails":{"type":"object","properties":{"email":{"type":"string","description":"Contact email address the council publishes.","example":"planning@manchester.gov.uk"},"phone":{"type":"string","description":"Contact telephone number the council publishes.","example":"0161 234 5678"},"address":{"type":"object","properties":{"line1":{"type":"string"},"line2":{"type":"string"},"city":{"type":"string"},"postcode":{"type":"string"}},"description":"Postal address the council publishes for contact."},"openingHours":{"type":"object","properties":{"monday":{"type":"string"},"tuesday":{"type":"string"},"wednesday":{"type":"string"},"thursday":{"type":"string"},"friday":{"type":"string"},"saturday":{"type":"string"},"sunday":{"type":"string"}}},"emergencyContact":{"type":"string"}}},"CouncilBranding":{"type":"object","properties":{"logoUrl":{"type":"string","description":"Public URL of the logo or crest.","example":"https://hot-cdn.vepler.com/schools/12345/images/ab12cd.png"},"primaryColour":{"type":"string","description":"Primary brand colour, as a hex code.","example":"#00a1d5"},"secondaryColour":{"type":"string","description":"Secondary brand colour, as a hex code.","example":"#1c1c1c"},"socialMedia":{"$ref":"#/components/schemas/SocialMediaLinks"}}},"CouncilServiceUrls":{"type":"object","properties":{"planningPortal":{"type":"string","description":"URL of the council's planning applications portal.","example":"https://www.manchester.gov.uk/planning"},"planningSearch":{"type":"string","description":"URL of the council's planning application search page."},"planningDocuments":{"type":"string"},"councilTax":{"type":"string"},"parking":{"type":"string"},"waste":{"type":"string"},"housing":{"type":"string"},"benefits":{"type":"string"},"licensing":{"type":"string"},"buildingControl":{"type":"string"},"environmentalHealth":{"type":"string"}}},"CouncilMetadata":{"type":"object","properties":{"region":{"type":"string","description":"Region the council's area sits in.","example":"North West"},"tags":{"type":"array","items":{"type":"string"},"description":"Labels that categorise the council.","example":["major_city","metropolitan"]},"population":{"type":"number","description":"Estimated number of people living in the council's area.","example":547627},"areaSquareKm":{"type":"number","description":"Size of the council's area, in square kilometres.","example":115.6},"website":{"type":"string","description":"URL of the council's website.","example":"https://www.manchester.gov.uk"},"wikipediaUrl":{"type":"string"},"alternativeNames":{"type":"array","items":{"type":"string"}},"planningAuthorityName":{"type":"string"},"planningAuthorityAlternatives":{"type":"array","items":{"type":"string"}},"localAuthorityId":{"type":"number"}}},"CouncilErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"]}},"required":["error"]},"SiteListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Site"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."},"Site":{"type":"object","properties":{"object":{"type":"string","enum":["site"],"description":"Object type discriminator. Always `site`.","example":"site"},"siteId":{"type":"string","description":"Identifier for a single registered title, made up of the country, the registry and the title number joined by colons.","example":"GB:LR:AGL123456"},"country":{"type":"string","maxLength":2,"description":"Country the title is registered in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"registry":{"type":"string","description":"Code for the land registry the title is registered with, as it appears in `siteId`.","example":"LR"},"titleRef":{"type":"string","description":"Title number as issued by the land registry.","example":"AGL123456"},"sources":{"type":"array","items":{"type":"string"},"description":"Data sources that contributed to this site record.","example":["nps"]},"boundary":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"],"description":"Geometry type discriminator. Always `Polygon`."},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"description":"A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]},"minItems":4},"minItems":1,"description":"The rings that make up the polygon. The first ring is the outer boundary and any further rings are holes inside it. Each ring needs at least four positions and closes by repeating its first position as the last."}},"required":["type","coordinates"],"additionalProperties":false,"description":"An area expressed as a GeoJSON Polygon geometry.","title":"GeoJSON Polygon","example":{"type":"Polygon","coordinates":[[[-0.128,51.507],[-0.127,51.507],[-0.127,51.508],[-0.128,51.508],[-0.128,51.507]]]}},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"],"description":"Geometry type discriminator. Always `MultiPolygon`."},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"description":"A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]},"minItems":4},"minItems":1},"minItems":1,"description":"One entry per polygon, each holding that polygon's rings in the same form as a Polygon geometry."}},"required":["type","coordinates"],"additionalProperties":false,"description":"Several separate areas expressed as a single GeoJSON MultiPolygon geometry.","title":"GeoJSON MultiPolygon"}],"description":"Outline of the registered title, as a GeoJSON Polygon or MultiPolygon. Left out of the default attribute set because of its size; request it with `attributes: [\"boundary\"]`."},"centroid":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"additionalProperties":false,"description":"Centre point of the title boundary. Present whenever the site has a boundary, unless `centroid` is left out of the requested attributes.","title":"Coordinates"},"areaSqm":{"type":"number","minimum":0,"description":"Area enclosed by the title boundary, in square metres.","example":450.5},"estateInterestCode":{"type":["string","null"],"enum":["EL","RC","FO","PL",null],"description":"HM Land Registry estate interest code, which records the kind of interest the title covers. Almost always `EL`, an estate in land. It does not distinguish freehold from leasehold; read `classTitleCode` or `tenureType` for that. Left out of the default attribute set; request it with `attributes: [\"estateInterestCode\"]`.","example":"EL"},"classTitleCode":{"type":["string","null"],"enum":["AF","QF","PF","SF","AL","GL","QL","PL","SL","CF","CL","CN","AR","PR","QR",null],"description":"HM Land Registry class of title code, which records the quality of the title and the tenure it is held under. Left out of the default attribute set; request it with `attributes: [\"classTitleCode\"]`.","example":"AF"},"tenureType":{"type":["string","null"],"enum":["freehold","leasehold","commonhold","rentcharge","caution","other",null],"description":"Tenure the title is held under, derived from `classTitleCode`. Null when there is no class of title code.","example":"freehold"},"status":{"type":"string","enum":["active","pending","closed"],"description":"Where the title record stands: `active` for a current registered title, `pending` for one awaiting registration or enrichment, and `closed` for one that is no longer active."},"locationIds":{"type":"array","items":{"type":"string"},"description":"Identifiers for the addressable locations that fall within this title, matched against the Ordnance Survey AddressBase dataset. In Great Britain each one is a Unique Property Reference Number (UPRN). Left out of the default attribute set; request it with `attributes: [\"locationIds\"]`.","example":["100023336956","100023336957"]},"polygonIds":{"type":"array","items":{"type":"number"},"description":"Identifiers of the source polygons this boundary was assembled from, for tracing a shape back to the supplied data. Left out of the default attribute set; request it with `attributes: [\"polygonIds\"]`.","example":[12345]},"locationCount":{"type":"number","description":"Number of addressable locations linked to this title.","example":3},"overlays":{"type":"array","items":{"type":"string"},"description":"Codes for the designations and hazards recorded against this site, covering flood risk, road and rail noise, radon, landfill proximity and protected-area designations. The set is open rather than fixed: it depends on which area datasets cover the site.","example":["flood_zone_2","conservation_area","green_belt"]},"relationships":{"type":"array","items":{"type":"string"},"description":"Administrative and statistical areas that contain the site, each written as an area type and its code joined by two colons, such as `LSOA::E01000001`. Types include `COUNTRY`, `REGION`, `COUNTY`, `DISTRICT`, `BOROUGH`, `WARD`, `PARISH`, `LAD`, `LSOA`, `MSOA`, `OA`, `CONSTITUENCY` and `POSTCODE`.","example":["E07000026","E05009735"]},"landUse":{"type":"array","items":{"type":"string","enum":["residential","commercial","industrial","agricultural","mixed_use","recreational","community","transport","utilities","forestry","defence","vacant","protected","woodland","urban"]},"description":"Land use classifications recorded for the site.","example":["residential"]},"tags":{"$ref":"#/components/schemas/SiteTags"},"ownership":{"$ref":"#/components/schemas/SiteOwnership"},"propertyStats":{"$ref":"#/components/schemas/SitePropertyStats"},"planning":{"$ref":"#/components/schemas/SitePlanningStats"},"areaMetrics":{"$ref":"#/components/schemas/SiteAreaMetrics"},"registeredAt":{"type":["string","null"],"description":"When the title was first registered, as an ISO 8601 timestamp.","example":"2005-03-14T00:00:00.000Z"},"updatedAt":{"type":["string","null"],"description":"When this site record was last updated, as an ISO 8601 timestamp.","example":"2026-02-15T14:30:00.000Z"}}},"SiteTags":{"type":"object","properties":{"vacant":{"type":"boolean","description":"True when more than half of the properties linked to this site are vacant."},"agricultural":{"type":"boolean","description":"True when the site's land use includes agricultural land."},"multipleProperties":{"type":"boolean","description":"True when more than one property is linked to this site."},"noProperties":{"type":"boolean","description":"True when no properties are linked to this site."}},"default":{"vacant":false,"agricultural":false,"multipleProperties":false,"noProperties":false},"description":"Quick flags derived from the rest of the record, for filtering without composing a query."},"SiteOwnership":{"type":["object","null"],"properties":{"proprietors":{"type":"array","items":{"$ref":"#/components/schemas/SiteProprietor"},"description":"Every proprietor recorded on the title, with the primary one first."},"ownershipCategory":{"type":"string","enum":["company","corporate","government","individual","unknown"],"description":"Broad category the primary proprietor falls into, worked out from its entity type.","example":"company"},"primaryOwnerName":{"type":"string","description":"Name of the primary proprietor."},"companyNumber":{"type":["string","null"],"description":"Company registration number of the primary proprietor, where it is a company.","example":"08145739"},"isJointOwnership":{"type":"boolean","description":"True when the title is recorded as being held by more than one proprietor."},"dateProprietorAdded":{"type":["string","null"],"description":"When the primary proprietor was added to the title, as an ISO 8601 date."},"source":{"type":"string","enum":["ccod","ocod","title_deed","manual"],"description":"Which HM Land Registry record the ownership was taken from.","example":"ccod"}},"description":"Registered ownership of the title. Null when no proprietor records are held for it."},"SiteProprietor":{"type":"object","properties":{"name":{"type":"string","description":"Proprietor's name as recorded on the title."},"entityType":{"type":"string","description":"Kind of legal entity the proprietor is, for example 'limited_company', 'local_authority' or 'individual'.","example":"limited_company"},"companyNumber":{"type":["string","null"],"description":"Company registration number, where the proprietor is a company.","example":"08145739"},"countryIncorporated":{"type":["string","null"],"description":"Country the proprietor was incorporated in, where it is an overseas company.","example":"Jersey"},"address":{"type":["string","null"],"description":"First address recorded for the proprietor on the title."},"dateAdded":{"type":["string","null"],"description":"When this proprietor was added to the title, as an ISO 8601 date."}}},"SitePropertyStats":{"type":["object","null"],"properties":{"totalProperties":{"type":"number","description":"Number of linked properties these statistics cover.","example":12},"propertyTypes":{"type":"array","items":{"type":"string"},"description":"The distinct property types found across the linked properties.","example":["terraced","flat"]},"avgValue":{"type":"number","description":"Mean estimated sale value across the linked properties, in whole pounds.","example":350000},"avgRent":{"type":"number","description":"Mean estimated monthly rent across the linked properties, in whole pounds.","example":1500},"totalFloorArea":{"type":"number","description":"Combined floor area of the linked properties, in square metres.","example":1250.5},"vacancyRate":{"type":"number","description":"Share of the linked properties recorded as vacant, from 0 to 1, rounded to two decimal places.","example":0.08}},"description":"Statistics across the properties linked to this site. Null when no properties are linked."},"SitePlanningStats":{"type":["object","null"],"properties":{"totalApplications":{"type":"number","description":"Number of planning applications whose boundary intersects this site.","example":5},"approvals":{"type":"number","description":"How many of those applications were approved.","example":3},"refusals":{"type":"number","description":"How many of those applications were refused.","example":1},"pending":{"type":"number","description":"How many of those applications are still awaiting a decision.","example":1},"latestApplicationDate":{"type":"string","description":"When the most recent of those applications was received, as an ISO 8601 timestamp.","example":"2025-11-20T00:00:00.000Z"},"latestDecision":{"type":"string","description":"Status of the most recent application, in the wording the local authority published.","example":"approved"},"applicationTypes":{"type":"array","items":{"type":"string"},"description":"The distinct application types found across those applications.","example":["householder","full"]}},"description":"Statistics across the planning applications whose boundary intersects this site. Null when none intersect it."},"SiteAreaMetrics":{"type":["object","null"],"properties":{"crimeScore":{"type":"number","description":"Crime safety score for the Lower Layer Super Output Area (LSOA) containing the site, from 0 to 100, where higher is safer.","example":65},"deprivationIndex":{"type":"number","description":"Index of Multiple Deprivation for the local area containing the site.","example":4},"connectivityScore":{"type":"number","description":"Broadband and mobile connectivity score for the local area containing the site.","example":78},"prosperityScore":{"type":"number","description":"Prosperity Index score for the LSOA containing the site, from 0 to 100.","example":62},"prosperityDecile":{"type":"number","description":"National prosperity decile for the LSOA containing the site, from 1 to 10, where 10 is the most prosperous.","example":6}},"description":"Area-level measures for the LSOA containing the site centroid, covering crime, deprivation, connectivity and prosperity. Null when none of those measures are available for the site."},"SiteQueryRequest":{"type":"object","properties":{"filters":{"$ref":"#/components/schemas/SiteFilters"},"query":{"type":"array","items":{"$ref":"#/components/schemas/SiteQueryOperator"},"description":"Query operators for filtering the convenience filters cannot express. Each operator holds groups of conditions joined by its own `AND` or `OR`."},"area":{"type":"array","items":{"$ref":"#/components/schemas/SiteAreaFilter"},"description":"Geographic area filters. A site matches if it satisfies any one of them, and that has to hold on top of the other filters."},"sort":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["areaSqm","locationCount","areaMetrics.crimeScore","areaMetrics.deprivationIndex","areaMetrics.connectivityScore","areaMetrics.prosperityScore","areaMetrics.prosperityDecile","propertyStats.totalProperties","propertyStats.avgValue","propertyStats.avgRent","propertyStats.vacancyRate","propertyStats.totalFloorArea","planning.totalApplications","planning.approvals","registeredAt","updatedAt"],"description":"Field to sort on."},"order":{"type":"string","enum":["asc","desc"],"description":"Direction to sort in: `asc` puts the smallest or oldest first, `desc` the largest or newest."},"missing":{"type":"string","enum":["_first","_last"],"description":"Where sites with no value for this field go: `_first` at the start of the results, `_last` at the end. Defaults to `_last`."},"mode":{"type":"string","enum":["min","max","sum","avg","median"],"description":"Which value to sort on when a site holds several for this field: the lowest, the highest, the total, the mean or the median."}},"required":["field","order"]},"maxItems":3,"description":"How to order the results. Up to 3 fields, applied in the order given, so the first is the primary sort. When omitted, no particular ordering is applied."},"geoSort":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the reference point, in WGS84 decimal degrees.","example":51.5074},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the reference point, in WGS84 decimal degrees.","example":-0.1278},"order":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Direction to sort in: `asc` puts the nearest first, `desc` the furthest. Defaults to `asc`."}},"required":["lat","lon"],"description":"Order the results by how far each site's centroid is from a reference point. Applied after any field sort, so it breaks ties rather than replacing that order."},"attributes":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Fields to return, either as an array of names or as one comma-separated string such as \"siteId,tenureType,areaSqm\". Defaults to a standard set that leaves out the `boundary` geometry; name `boundary` to get site polygons back."},"limit":{"type":"number","minimum":1,"maximum":1000,"default":25,"description":"Maximum number of sites to return. Defaults to 25. Minimum 1, maximum 1000.","example":25},"offset":{"type":"number","minimum":0,"maximum":100000,"default":0,"description":"Number of results to skip before the first one returned. Defaults to 0. Maximum 100000.","example":0}}},"SiteFilters":{"type":"object","properties":{"tenureType":{"type":"array","items":{"type":"string"},"description":"Return only titles whose tenure is one of these: `freehold`, `leasehold`, `commonhold`, `rentcharge`, `caution` or `other`.","example":["freehold"]},"status":{"type":"array","items":{"type":"string","enum":["active","pending","closed"]},"description":"Return only titles whose record status is one of these."},"country":{"type":"string","description":"Return only titles registered in this country, as an ISO 3166-1 alpha-2 code.","example":"GB"},"classTitleCode":{"type":"array","items":{"type":"string"},"description":"Return only titles carrying one of these HM Land Registry class of title codes. The freehold codes are `AF`, `QF`, `PF` and `SF`; the leasehold codes are `AL`, `GL`, `QL`, `PL` and `SL`; `CF`, `CL` and `CN` cover cautions and `AR`, `PR` and `QR` cover rentcharges.","example":["AF","AL"]},"overlays":{"type":"array","items":{"type":"string"},"description":"Return only sites carrying one of these overlay codes.","example":["flood_zone_2"]},"tags":{"type":"object","properties":{"vacant":{"type":"boolean","description":"Match sites where more than half of the linked properties are vacant."},"brownfield":{"type":"boolean","description":"Match sites on brownfield land."},"agricultural":{"type":"boolean","description":"Match sites whose land use includes agricultural land."},"developmentPotential":{"type":"boolean","description":"Match sites flagged as having development potential."},"multipleProperties":{"type":"boolean","description":"Match sites with more than one linked property."},"noProperties":{"type":"boolean","description":"Match sites with no linked properties."}},"description":"Filter on the derived tags. Set a tag to `true` to require it, or `false` to exclude it."},"areaSqmMin":{"type":"number","description":"Smallest site area to include, in square metres, inclusive.","example":100},"areaSqmMax":{"type":"number","description":"Largest site area to include, in square metres, inclusive.","example":10000},"ownershipCategory":{"type":"array","items":{"type":"string"},"description":"Return only titles whose primary proprietor falls into one of these categories: `company`, `corporate`, `government`, `individual` or `unknown`.","example":["company"]},"ownerName":{"type":"string","description":"Return only titles whose primary proprietor's name contains this text, matched case-sensitively."},"companyNumber":{"type":"string","description":"Return only titles whose primary proprietor has this company registration number."}},"description":"Convenience filters covering the common cases. Every one supplied has to match."},"SiteQueryOperator":{"type":"object","properties":{"operator":{"type":"string","enum":["AND","OR"],"description":"How the conditions combine: `AND` needs every condition to match, `OR` needs at least one."},"groups":{"type":"array","items":{"$ref":"#/components/schemas/SiteQueryGroup"},"description":"Condition groups. Conditions from every group are flattened and joined by `operator`."}},"required":["operator","groups"],"example":{"operator":"AND","groups":[{"conditions":[{"field":"tenureType","comparator":"eq","value":"freehold"},{"field":"areaSqm","comparator":"gte","value":500}]}]}},"SiteQueryGroup":{"type":"object","properties":{"conditions":{"type":"array","items":{"$ref":"#/components/schemas/SiteQueryCondition"},"description":"Conditions in this group. They are joined by the operator set on the group's parent."}},"required":["conditions"]},"SiteQueryCondition":{"type":"object","properties":{"field":{"type":"string","enum":["siteId","country","registry","titleRef","sources","estateInterestCode","classTitleCode","tenureType","status","areaSqm","locationCount","overlays","relationships","locationId","locationIds","landUse","tags.vacant","tags.agricultural","tags.multipleProperties","tags.noProperties","propertyStats.totalProperties","propertyStats.avgValue","propertyStats.avgRent","propertyStats.totalFloorArea","propertyStats.vacancyRate","propertyStats.propertyTypes","planning.totalApplications","planning.approvals","planning.refusals","planning.pending","planning.latestDecision","planning.applicationTypes","planning.latestApplicationDate","areaMetrics.crimeScore","areaMetrics.deprivationIndex","areaMetrics.connectivityScore","areaMetrics.prosperityScore","areaMetrics.prosperityDecile","registeredAt","updatedAt"],"description":"Field the condition applies to."},"comparator":{"type":"string","enum":["eq","ne","gt","gte","lt","lte","in","nin","contains","startswith","endswith"],"description":"How `value` is compared with the field. `eq` and `ne` test exact equality. `gt`, `gte`, `lt` and `lte` compare numeric and date fields, with `gte` and `lte` inclusive. `in` and `nin` test whether the field is one of the values in an array. `contains`, `startswith` and `endswith` match part of a text field, case-sensitively."},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}],"description":"Value the field is compared against. Pass an array for `in` and `nin`."}},"required":["field","comparator","value"],"example":{"field":"areaSqm","comparator":"gte","value":500}},"SiteAreaFilter":{"oneOf":[{"$ref":"#/components/schemas/SitePolygonAreaFilter"},{"$ref":"#/components/schemas/SiteMultiPolygonAreaFilter"},{"$ref":"#/components/schemas/SitePointAreaFilter"},{"$ref":"#/components/schemas/SiteContainsPointAreaFilter"},{"$ref":"#/components/schemas/SiteBoundingBoxAreaFilter"}],"discriminator":{"propertyName":"type","mapping":{"polygon":"#/components/schemas/SitePolygonAreaFilter","multipolygon":"#/components/schemas/SiteMultiPolygonAreaFilter","point":"#/components/schemas/SitePointAreaFilter","containsPoint":"#/components/schemas/SiteContainsPointAreaFilter","boundingBox":"#/components/schemas/SiteBoundingBoxAreaFilter"}}},"SitePolygonAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"description":"The rings of the polygon to search within. The first ring is the outer boundary and any further rings are holes inside it. Each ring closes by repeating its first position as the last. Positions are longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order)."},"relation":{"type":"string","enum":["intersects","within","contains"],"description":"How the site boundary must relate to the polygon. `intersects` matches when the two overlap at all, `within` when the site boundary lies entirely inside the polygon, and `contains` when it entirely encloses the polygon. Defaults to `intersects`."}},"required":["type","coordinates"],"example":{"type":"polygon","coordinates":[[[-0.13,51.51],[-0.1,51.51],[-0.1,51.5],[-0.13,51.5],[-0.13,51.51]]]}},"SiteMultiPolygonAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["multipolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}},"description":"One entry per polygon to search within, each holding that polygon's rings in the same form as the polygon filter. Positions are longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order)."},"relation":{"type":"string","enum":["intersects","within","contains"],"description":"How the site boundary must relate to the polygons, using the same options as the polygon filter. Defaults to `intersects`."}},"required":["type","coordinates"]},"SitePointAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["point"]},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the centre point, in WGS84 decimal degrees.","example":51.5074},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the centre point, in WGS84 decimal degrees.","example":-0.1278},"radius":{"type":"string","description":"How far out from the centre point to search, measured from each site's centroid. Written as a number and a unit: `m` for metres, `km` for kilometres, `mi` for miles, `yd` for yards or `ft` for feet.","example":"5km"}},"required":["type","lat","lon","radius"]},"SiteContainsPointAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["containsPoint"]},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the point, in WGS84 decimal degrees.","example":51.5074},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the point, in WGS84 decimal degrees.","example":-0.1278}},"required":["type","lat","lon"],"description":"Match sites whose boundary encloses this point, a point-in-polygon test."},"SiteBoundingBoxAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["boundingBox"]},"topLeft":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the northern edge.","example":51.52},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the western edge.","example":-0.13}},"required":["lat","lon"],"description":"North-west corner of the box."},"bottomRight":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the southern edge.","example":51.5},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the eastern edge.","example":-0.1}},"required":["lat","lon"],"description":"South-east corner of the box."}},"required":["type","topLeft","bottomRight"],"description":"Match sites whose centroid falls inside a rectangular box. Useful for map viewport queries."},"SiteAggregateResponse":{"type":"object","properties":{"total":{"type":"number","description":"Total number of sites matching the request, counted before the aggregations were applied.","example":28500000},"aggregations":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/AggregationResult"},"description":"One result per aggregation, keyed by the `name` given in the request. The shape of each result follows the aggregation's type: grouping types return buckets with a key and a count, `stats` returns count, min, max, avg and sum, the single-value metric types return one number, and `percentiles` returns a values object keyed by percentile."}},"required":["total","aggregations"]},"SiteAggregateRequest":{"type":"object","properties":{"aggregations":{"type":"array","items":{"$ref":"#/components/schemas/SiteAggregationInput"},"minItems":1,"maxItems":10,"description":"The aggregations to run. At least one, and no more than 10 per request.","example":[{"name":"by_tenure","type":"terms","field":"tenureType"},{"name":"area_stats","type":"stats","field":"areaSqm"}]},"filters":{"allOf":[{"$ref":"#/components/schemas/SiteFilters"},{"description":"Convenience filters narrowing which sites are aggregated."}]},"query":{"type":"array","items":{"$ref":"#/components/schemas/SiteQueryOperator"},"description":"Query operators narrowing which sites are aggregated."},"area":{"type":"array","items":{"$ref":"#/components/schemas/SiteAreaFilter"},"description":"Geographic area filters. A site is aggregated if it satisfies any one of them."}},"required":["aggregations"]},"SiteAggregationInput":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":50,"description":"Name for this aggregation. It is the key its result appears under in the response `aggregations` object, so it must be unique within the request. Between 1 and 50 characters.","example":"tenure_breakdown"},"type":{"type":"string","enum":["terms","range","histogram","date_histogram","stats","extended_stats","min","max","avg","sum","count","cardinality","percentiles","geotile_grid"],"description":"How the matching sites are aggregated. Each type takes its own parameters and returns its own result shape."},"field":{"type":"string","minLength":1,"description":"Field to aggregate over. Each dataset allows a fixed set of fields, and each of those supports only certain aggregation types; a field or type outside that set is rejected.","example":"areaSqm"},"size":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of buckets a grouping aggregation returns, between 1 and 100. The single-value metric types ignore it. For the map-tile grouping type it sets the tile precision rather than a bucket count. When omitted, the default depends on the dataset and the field.","example":10},"interval":{"type":"number","exclusiveMinimum":0,"description":"Width of each bucket for a `histogram` aggregation, in the units of the field. Must be greater than zero. Some datasets reject a `histogram` aggregation that omits it rather than applying a default.","example":100000},"calendarInterval":{"type":"string","description":"Calendar-aware bucket width for a date aggregation: 1m (minute), 1h (hour), 1d (day), 1w (week), 1M (month), 1q (quarter) or 1y (year). Mutually exclusive with `fixedInterval`, so supply one or the other, never both.","example":"1M"},"fixedInterval":{"type":"string","description":"Fixed-duration bucket width for a date aggregation, written as a number and a unit (ms, s, m, h, d), for example \"30m\", \"1h\" or \"7d\". Unlike `calendarInterval` it takes no account of daylight saving or of months having different lengths. Mutually exclusive with `calendarInterval`, so supply one or the other, never both.","example":"1h"},"ranges":{"type":"array","items":{"$ref":"#/components/schemas/RangeDefinition"},"description":"The ranges a `range` aggregation groups into. At least one is needed, and each covers `from` inclusive up to `to` exclusive.","example":[{"key":"small","to":100},{"key":"medium","from":100,"to":1000},{"key":"large","from":1000}]},"percents":{"type":"array","items":{"type":"number","minimum":0,"maximum":100},"description":"The percentiles to compute, each between 0 and 100. Used by the `percentiles` type.","example":[25,50,75,90,99]},"minDocCount":{"type":"integer","minimum":0,"description":"Smallest number of matching records a bucket must hold to appear in the result. Set it to 0 to keep buckets that matched nothing. Only the bucketing types honour it; single-value metric types ignore it.","example":0},"order":{"type":"object","additionalProperties":{"type":"string","enum":["asc","desc"]},"description":"Order the buckets of a `terms` aggregation. The key is what to sort on, either `_count`, `_key`, or the name of one of this aggregation's sub-aggregations; the value is the direction.","example":{"_count":"desc"}},"format":{"type":"string","description":"Pattern used to render `key_as_string` on each date bucket, for example \"yyyy-MM-dd\".","example":"yyyy-MM"},"timeZone":{"type":"string","description":"IANA time zone that date bucket boundaries are aligned to, for example \"Europe/London\".","example":"Europe/London"},"aggs":{"type":"array","items":{"$ref":"#/components/schemas/SiteNestedAggregation"},"maxItems":5,"description":"Sub-aggregations run inside each bucket of this one. Up to 5, and they may nest one level further, giving two levels below the top."}},"required":["name","type","field"]},"SiteNestedAggregation":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":50,"description":"Name for this aggregation. It is the key its result appears under in the response `aggregations` object, so it must be unique within the request. Between 1 and 50 characters.","example":"tenure_breakdown"},"type":{"type":"string","enum":["terms","range","histogram","date_histogram","stats","extended_stats","min","max","avg","sum","count","cardinality","percentiles","geotile_grid"],"description":"How the matching sites are aggregated. Each type takes its own parameters and returns its own result shape."},"field":{"type":"string","minLength":1,"description":"Field to aggregate over. Each dataset allows a fixed set of fields, and each of those supports only certain aggregation types; a field or type outside that set is rejected.","example":"areaSqm"},"size":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of buckets a grouping aggregation returns, between 1 and 100. The single-value metric types ignore it. For the map-tile grouping type it sets the tile precision rather than a bucket count. When omitted, the default depends on the dataset and the field.","example":10},"interval":{"type":"number","exclusiveMinimum":0,"description":"Width of each bucket for a `histogram` aggregation, in the units of the field. Must be greater than zero. Some datasets reject a `histogram` aggregation that omits it rather than applying a default.","example":100000},"calendarInterval":{"type":"string","description":"Calendar-aware bucket width for a date aggregation: 1m (minute), 1h (hour), 1d (day), 1w (week), 1M (month), 1q (quarter) or 1y (year). Mutually exclusive with `fixedInterval`, so supply one or the other, never both.","example":"1M"},"fixedInterval":{"type":"string","description":"Fixed-duration bucket width for a date aggregation, written as a number and a unit (ms, s, m, h, d), for example \"30m\", \"1h\" or \"7d\". Unlike `calendarInterval` it takes no account of daylight saving or of months having different lengths. Mutually exclusive with `calendarInterval`, so supply one or the other, never both.","example":"1h"},"ranges":{"type":"array","items":{"$ref":"#/components/schemas/RangeDefinition"},"description":"The ranges a `range` aggregation groups into. At least one is needed, and each covers `from` inclusive up to `to` exclusive.","example":[{"key":"small","to":100},{"key":"medium","from":100,"to":1000},{"key":"large","from":1000}]},"percents":{"type":"array","items":{"type":"number","minimum":0,"maximum":100},"description":"The percentiles to compute, each between 0 and 100. Used by the `percentiles` type.","example":[25,50,75,90,99]},"minDocCount":{"type":"integer","minimum":0,"description":"Smallest number of matching records a bucket must hold to appear in the result. Set it to 0 to keep buckets that matched nothing. Only the bucketing types honour it; single-value metric types ignore it.","example":0},"order":{"type":"object","additionalProperties":{"type":"string","enum":["asc","desc"]},"description":"Order the buckets of a `terms` aggregation. The key is what to sort on, either `_count`, `_key`, or the name of one of this aggregation's sub-aggregations; the value is the direction.","example":{"_count":"desc"}},"format":{"type":"string","description":"Pattern used to render `key_as_string` on each date bucket, for example \"yyyy-MM-dd\".","example":"yyyy-MM"},"timeZone":{"type":"string","description":"IANA time zone that date bucket boundaries are aligned to, for example \"Europe/London\".","example":"Europe/London"},"aggs":{"type":"array","items":{"$ref":"#/components/schemas/SiteLeafAggregation"},"maxItems":5,"description":"Sub-aggregations run inside each bucket of this one. Up to 5, and they cannot nest any further."}},"required":["name","type","field"]},"SiteLeafAggregation":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":50,"description":"Name for this aggregation. It is the key its result appears under in the response `aggregations` object, so it must be unique within the request. Between 1 and 50 characters.","example":"tenure_breakdown"},"type":{"type":"string","enum":["terms","range","histogram","date_histogram","stats","extended_stats","min","max","avg","sum","count","cardinality","percentiles","geotile_grid"],"description":"How the matching sites are aggregated. Each type takes its own parameters and returns its own result shape."},"field":{"type":"string","minLength":1,"description":"Field to aggregate over. Each dataset allows a fixed set of fields, and each of those supports only certain aggregation types; a field or type outside that set is rejected.","example":"areaSqm"},"size":{"type":"integer","minimum":1,"maximum":100,"description":"Maximum number of buckets a grouping aggregation returns, between 1 and 100. The single-value metric types ignore it. For the map-tile grouping type it sets the tile precision rather than a bucket count. When omitted, the default depends on the dataset and the field.","example":10},"interval":{"type":"number","exclusiveMinimum":0,"description":"Width of each bucket for a `histogram` aggregation, in the units of the field. Must be greater than zero. Some datasets reject a `histogram` aggregation that omits it rather than applying a default.","example":100000},"calendarInterval":{"type":"string","description":"Calendar-aware bucket width for a date aggregation: 1m (minute), 1h (hour), 1d (day), 1w (week), 1M (month), 1q (quarter) or 1y (year). Mutually exclusive with `fixedInterval`, so supply one or the other, never both.","example":"1M"},"fixedInterval":{"type":"string","description":"Fixed-duration bucket width for a date aggregation, written as a number and a unit (ms, s, m, h, d), for example \"30m\", \"1h\" or \"7d\". Unlike `calendarInterval` it takes no account of daylight saving or of months having different lengths. Mutually exclusive with `calendarInterval`, so supply one or the other, never both.","example":"1h"},"ranges":{"type":"array","items":{"$ref":"#/components/schemas/RangeDefinition"},"description":"The ranges a `range` aggregation groups into. At least one is needed, and each covers `from` inclusive up to `to` exclusive.","example":[{"key":"small","to":100},{"key":"medium","from":100,"to":1000},{"key":"large","from":1000}]},"percents":{"type":"array","items":{"type":"number","minimum":0,"maximum":100},"description":"The percentiles to compute, each between 0 and 100. Used by the `percentiles` type.","example":[25,50,75,90,99]},"minDocCount":{"type":"integer","minimum":0,"description":"Smallest number of matching records a bucket must hold to appear in the result. Set it to 0 to keep buckets that matched nothing. Only the bucketing types honour it; single-value metric types ignore it.","example":0},"order":{"type":"object","additionalProperties":{"type":"string","enum":["asc","desc"]},"description":"Order the buckets of a `terms` aggregation. The key is what to sort on, either `_count`, `_key`, or the name of one of this aggregation's sub-aggregations; the value is the direction.","example":{"_count":"desc"}},"format":{"type":"string","description":"Pattern used to render `key_as_string` on each date bucket, for example \"yyyy-MM-dd\".","example":"yyyy-MM"},"timeZone":{"type":"string","description":"IANA time zone that date bucket boundaries are aligned to, for example \"Europe/London\".","example":"Europe/London"}},"required":["name","type","field"]},"SiteBatchIdsRequest":{"type":"object","properties":{"siteIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"The site identifiers to look up. At least one, and no more than 100 per request."},"attributes":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Fields to return, in the same form as the search request."}},"required":["siteIds"]},"SitePropertiesResponse":{"type":"object","properties":{"locationIds":{"type":"array","items":{"type":"string"},"description":"Identifiers for the addressable locations that fall within this site. In Great Britain each one is a Unique Property Reference Number (UPRN).","example":["100023336956","100023336957","100023336958"]},"total":{"type":"number","description":"Number of identifiers in `locationIds`.","example":3}},"required":["locationIds","total"]},"BuildingListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/Building"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."},"Building":{"type":"object","properties":{"object":{"type":"string","enum":["building"],"description":"Object type discriminator. Always `building`.","example":"building"},"buildingId":{"type":"string","description":"Identifier for a single building, made up of the country, the source dataset and that dataset's own identifier, joined by colons.","example":"GB:NGD:abc12345-67de-89f0-1234-567890abcdef"},"country":{"type":"string","maxLength":2,"description":"Country the building is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"provider":{"type":"string","enum":["NGD","BAG","OSM","HU"],"description":"Code for the dataset the building was sourced from.","example":"NGD"},"externalId":{"type":"string","description":"Identifier for the building in that source dataset.","example":"abc12345-67de-89f0-1234-567890abcdef"},"sources":{"type":"array","items":{"type":"string","enum":["paf","os","os_ngd","ngd_addresses","epc","hmlr","voa","hmrc","historic_england","listing","open_data","council","claim"]},"description":"Every data source that contributed at least one field to this building.","example":["os_ngd","epc"]},"dataSources":{"type":"array","items":{"type":"string","enum":["paf","os","os_ngd","ngd_addresses","epc","hmlr","voa","hmrc","historic_england","listing","open_data","council","claim"]},"default":[],"description":"Data sources behind this building record. Holds the same list as `sources`."},"status":{"type":"string","enum":["active","demolished","pending"],"description":"Where the building record stands: `active` for one present in the latest source data, `demolished` for one the source has flagged as demolished, and `pending` for one that has been observed but not yet enriched."},"footprint":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"],"description":"Geometry type discriminator. Always `Polygon`."},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"description":"A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]},"minItems":4},"minItems":1,"description":"The rings that make up the polygon. The first ring is the outer boundary and any further rings are holes inside it. Each ring needs at least four positions and closes by repeating its first position as the last."}},"required":["type","coordinates"],"additionalProperties":false,"description":"An area expressed as a GeoJSON Polygon geometry.","title":"GeoJSON Polygon","example":{"type":"Polygon","coordinates":[[[-0.128,51.507],[-0.127,51.507],[-0.127,51.508],[-0.128,51.508],[-0.128,51.507]]]}},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"],"description":"Geometry type discriminator. Always `MultiPolygon`."},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"description":"A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]},"minItems":4},"minItems":1},"minItems":1,"description":"One entry per polygon, each holding that polygon's rings in the same form as a Polygon geometry."}},"required":["type","coordinates"],"additionalProperties":false,"description":"Several separate areas expressed as a single GeoJSON MultiPolygon geometry.","title":"GeoJSON MultiPolygon"},{"type":"null"}],"description":"Outline of the building, as a GeoJSON Polygon or MultiPolygon. Left out of the default attribute set because of its size; request it with `attributes: [\"footprint\"]`."},"centroid":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"additionalProperties":false,"description":"Centre point of the building footprint.","title":"Coordinates"},"areaSqm":{"type":["number","null"],"minimum":0,"description":"Area covered by the building footprint, in square metres. Mirrors `structure.footprintAreaSqm`.","example":124.6},"heightMax":{"type":["number","null"],"description":"Absolute height of the highest point of the building, in metres. Mirrors `structure.heightMax`."},"heightRoofBase":{"type":["number","null"],"description":"Absolute height of the base of the roof, in metres. Mirrors `structure.heightRoofBase`."},"floors":{"type":["integer","null"],"description":"Number of floors above ground. Mirrors `structure.floors`."},"buildingUse":{"type":["string","null"],"description":"Primary use of the building, in the source's own wording.","example":"Residential"},"buildingUseTierA":{"type":["string","null"],"description":"Broader land use category that the primary use rolls up to.","example":"Residential"},"type":{"type":["string","null"],"description":"Descriptive classification of the structure, in the source's own wording.","example":"Building"},"physicalState":{"type":["string","null"],"enum":["Built","Demolished","Ruined","UnderConstruction",null],"description":"Whether the building is standing, demolished, ruined or still under construction. Mirrors `structure.physicalState`.","example":"Built"},"connectivity":{"type":["string","null"],"enum":["Standalone","Multi-Connected","Linked","Detached",null],"description":"Whether the building stands alone or is joined to neighbouring buildings. Mirrors `structure.connectivity`.","example":"Detached"},"partCount":{"type":"integer","minimum":0,"default":0,"description":"Number of parts recorded for this building."},"locationIds":{"type":"array","items":{"type":"string"},"default":[],"description":"Identifiers for the addressable locations linked to this building. In Great Britain each one is a Unique Property Reference Number (UPRN). Returned by default; the full address records come back only when requested with `attributes: [\"addresses\"]`.","example":["100023336956","100023336957"]},"addressCount":{"type":["object","null"],"properties":{"total":{"type":["integer","null"],"description":"Number of addressable locations linked to this building."},"residential":{"type":["integer","null"],"description":"How many of those locations are classified residential."},"commercial":{"type":["integer","null"],"description":"How many of those locations are classified commercial."},"other":{"type":["integer","null"],"description":"How many of those locations fall outside the residential and commercial classes."}},"description":"Counts of the linked addresses, split by classification."},"structure":{"type":["object","null"],"properties":{"footprintAreaSqm":{"type":["number","null"],"description":"Area covered by the building footprint, in square metres."},"heightMax":{"type":["number","null"],"description":"Absolute height of the highest point of the building, in metres. This is not a height above ground level."},"heightRoofBase":{"type":["number","null"],"description":"Absolute height of the base of the roof, in metres. This is not a height above ground level."},"floors":{"type":["integer","null"],"description":"Number of floors above ground."},"physicalState":{"type":["string","null"],"enum":["Built","Demolished","Ruined","UnderConstruction",null],"description":"Whether the building is standing, demolished, ruined or still under construction.","example":"Built"},"connectivity":{"type":["string","null"],"enum":["Standalone","Multi-Connected","Linked","Detached",null],"description":"Whether the building stands alone or is joined to neighbouring buildings.","example":"Detached"},"dataSources":{"type":"array","items":{"type":"string","enum":["paf","os","os_ngd","ngd_addresses","epc","hmlr","voa","hmrc","historic_england","listing","open_data","council","claim"]},"default":[],"description":"Data sources that contributed a value to this block."}},"description":"Physical dimensions and form of the building."},"construction":{"type":["object","null"],"properties":{"wallConstruction":{"type":["string","null"],"enum":["cavity","solid_brick","timber_frame","sandstone_or_limestone","sandstone","granite_or_whinstone","granite","system_built","solid_stone","cob","park_home","basement","curtain_wall",null],"description":"How the external walls are built, using the same vocabulary as the EPC wall construction field."},"materialDescription":{"type":["string","null"],"description":"Wall material in the source's own wording, for display alongside `wallConstruction`.","example":"Brick Or Block Or Stone"},"age":{"type":["object","null"],"properties":{"startYear":{"type":["integer","null"],"description":"First year of the construction period. Null when the band is open-ended, such as 'before 1900'."},"endYear":{"type":["integer","null"],"description":"Last year of the construction period. Null when the band is open-ended, such as '2007 onwards'."},"midYear":{"type":["integer","null"],"description":"Midpoint of the construction period, for when a single year is needed."},"isExact":{"type":"boolean","description":"True when the certificate gives an exact year of construction rather than a band."}},"description":"Period the building was constructed in, as a year range. Each source's own age band is parsed into this shape, so a certificate reading 'England and Wales: 1900-1929' and a survey reading '1870-1918' arrive in the same form."},"year":{"type":["integer","null"],"description":"Year the building was constructed, where one is recorded."},"evidenceDate":{"type":["string","null"],"description":"Date of the most recent evidence behind the construction values, as an ISO 8601 date."},"dataSources":{"type":"array","items":{"type":"string","enum":["paf","os","os_ngd","ngd_addresses","epc","hmlr","voa","hmrc","historic_england","listing","open_data","council","claim"]},"default":[],"description":"Data sources that contributed a value to this block."}},"description":"Construction age and materials, drawn from the building survey data and from EPC assessments."},"roof":{"type":["object","null"],"properties":{"type":{"type":["string","null"],"enum":["pitched","flat","thatched","another_dwelling_above","other_premises_above","roof_room",null],"description":"How the roof is built, using the same vocabulary as the EPC roof type field."},"material":{"type":["string","null"],"description":"Primary roof covering material, in the source's own wording.","example":"Slate"},"solar":{"type":["string","null"],"enum":["present","absent",null],"description":"Whether solar panels are present on the roof."},"greenRoof":{"type":["string","null"],"enum":["present","absent",null],"description":"Whether the roof is a green or living roof."},"dataSources":{"type":"array","items":{"type":"string","enum":["paf","os","os_ngd","ngd_addresses","epc","hmlr","voa","hmrc","historic_england","listing","open_data","council","claim"]},"default":[],"description":"Data sources that contributed a value to this block."}},"description":"Roof characteristics. Not included in responses from the buildings endpoints."},"basement":{"type":["object","null"],"properties":{"present":{"type":["string","null"],"enum":["present","absent",null],"description":"Whether the building has a basement."},"selfContained":{"type":["string","null"],"enum":["present","absent",null],"description":"Whether the basement is self-contained, with its own entrance."},"dataSources":{"type":"array","items":{"type":"string","enum":["paf","os","os_ngd","ngd_addresses","epc","hmlr","voa","hmrc","historic_england","listing","open_data","council","claim"]},"default":[],"description":"Data sources that contributed a value to this block."}},"description":"Whether the building has a basement, and whether that basement is self-contained."},"parts":{"type":["array","null"],"items":{"$ref":"#/components/schemas/BuildingPart"},"description":"The individual parts making up this building. Left out of the default attribute set; request it with `attributes: [\"parts\"]`."},"addresses":{"type":["array","null"],"items":{"$ref":"#/components/schemas/BuildingAddressLink"},"description":"The addresses linked to this building, each with its identifier, classification and address line. Left out of the default attribute set; request it with `attributes: [\"addresses\"]`."},"registeredAt":{"type":["string","null"],"description":"Version date of the source record this building was built from, as an ISO 8601 date."},"sourceUpdatedAt":{"type":["string","null"],"description":"Version date of the most recent source record contributing to this building, as an ISO 8601 date."},"updatedAt":{"type":["string","null"],"description":"When this building record was last rebuilt from its sources, as an ISO 8601 timestamp."},"indexedAt":{"type":["string","null"],"description":"When this record last became available to queries, as an ISO 8601 timestamp."}}},"BuildingPart":{"type":"object","properties":{"partId":{"type":"string","description":"Identifier for a single part of a building, made up of the building identifier, the word `part`, and the part's source identifier, joined by colons.","example":"GB:NGD:abc-uuid:part:def-uuid"},"externalId":{"type":"string","description":"Identifier for the part in the source dataset."},"footprint":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["Polygon"],"description":"Geometry type discriminator. Always `Polygon`."},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"description":"A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]},"minItems":4},"minItems":1,"description":"The rings that make up the polygon. The first ring is the outer boundary and any further rings are holes inside it. Each ring needs at least four positions and closes by repeating its first position as the last."}},"required":["type","coordinates"],"additionalProperties":false,"description":"An area expressed as a GeoJSON Polygon geometry.","title":"GeoJSON Polygon","example":{"type":"Polygon","coordinates":[[[-0.128,51.507],[-0.127,51.507],[-0.127,51.508],[-0.128,51.508],[-0.128,51.507]]]}},{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"],"description":"Geometry type discriminator. Always `MultiPolygon`."},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"description":"A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]},"minItems":4},"minItems":1},"minItems":1,"description":"One entry per polygon, each holding that polygon's rings in the same form as a Polygon geometry."}},"required":["type","coordinates"],"additionalProperties":false,"description":"Several separate areas expressed as a single GeoJSON MultiPolygon geometry.","title":"GeoJSON MultiPolygon"},{"type":"null"}],"description":"Outline of the part, as a GeoJSON Polygon or MultiPolygon. Present only when `parts` is among the requested attributes."},"areaSqm":{"type":["number","null"],"description":"Area covered by the part's footprint, in square metres."},"heightMax":{"type":["number","null"],"description":"Absolute height of the highest point of the part, in metres. This is not a height above ground level."},"heightRoofBase":{"type":["number","null"],"description":"Absolute height of the base of the part's roof, in metres. This is not a height above ground level."},"physicalLevel":{"type":["string","null"],"description":"Level the part sits at, such as above ground or below it, in the source's own wording."},"description":{"type":["string","null"],"description":"Description of the part, in the source's own wording."}}},"BuildingAddressLink":{"type":"object","properties":{"locationId":{"type":"string","description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN).","example":"100023336956"},"uprn":{"type":"string","description":"The Unique Property Reference Number (UPRN). Holds the same value as `locationId`."},"classification":{"type":["string","null"],"description":"Ordnance Survey classification code for the address, such as `RD01`."},"addressLine":{"type":["string","null"],"description":"Full address on a single line, for display."},"postcode":{"type":["string","null"],"description":"Postcode of the address."}}},"BuildingQueryRequest":{"type":"object","properties":{"filters":{"$ref":"#/components/schemas/BuildingFilters"},"query":{"type":"array","items":{"$ref":"#/components/schemas/BuildingQueryOperator"},"description":"Query operators for filtering the convenience filters cannot express. Each operator holds groups of conditions, and every operator has to be satisfied."},"area":{"type":"array","items":{"$ref":"#/components/schemas/BuildingAreaFilter"},"description":"Geographic area filters. A building matches if it satisfies any one of them, and that has to hold on top of `filters` and `query`."},"sort":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["areaSqm","heightMax","heightRoofBase","floors","partCount","addressCount.total","addressCount.residential","addressCount.commercial","addressCount.other","structure.footprintAreaSqm","structure.heightMax","structure.heightRoofBase","structure.floors","construction.year","construction.age.midYear","construction.evidenceDate","registeredAt","sourceUpdatedAt","updatedAt","indexedAt"],"description":"Field to sort on."},"order":{"type":"string","enum":["asc","desc"],"description":"Direction to sort in: `asc` puts the smallest or oldest first, `desc` the largest or newest."},"missing":{"type":"string","enum":["_first","_last"],"description":"Where buildings with no value for this field go: `_first` at the start of the results, `_last` at the end."}},"required":["field","order"]},"maxItems":3,"description":"How to order the results. Up to 3 fields, applied in the order given, so the first is the primary sort."},"geoSort":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the reference point, in WGS84 decimal degrees."},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the reference point, in WGS84 decimal degrees."},"order":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Direction to sort in: `asc` puts the nearest first, `desc` the furthest. Defaults to `asc`."}},"required":["lat","lon"],"description":"Order the results by how far each building's centroid is from a reference point. Applied after any field sort, so it breaks ties rather than replacing that order."},"attributes":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Fields to return, either as an array of names or as one comma-separated string. Defaults to a standard set that leaves out `footprint`, `parts`, `addresses` and `_provenance`; name them to get them back."},"limit":{"type":"number","minimum":1,"maximum":1000,"default":25,"description":"Maximum number of buildings to return. Defaults to 25. Anything above 100 is reduced to 100."},"offset":{"type":"number","minimum":0,"maximum":100000,"default":0,"description":"Number of results to skip before the first one returned. Defaults to 0. Anything above 10000 is reduced to 10000."}}},"BuildingFilters":{"type":"object","properties":{"status":{"type":"array","items":{"type":"string","enum":["active","demolished","pending"]},"description":"Return only buildings whose record status is one of these."},"country":{"type":"string","description":"Return only buildings in this country, as an ISO 3166-1 alpha-2 code.","example":"GB"},"provider":{"type":"string","description":"Return only buildings sourced from this dataset.","example":"NGD"},"sources":{"type":"array","items":{"type":"string","enum":["paf","os","os_ngd","ngd_addresses","epc","hmlr","voa","hmrc","historic_england","listing","open_data","council","claim"]},"description":"Return only buildings whose `sources` includes at least one of these, so passing `epc` keeps only those an EPC contributed to."},"buildingUse":{"type":"array","items":{"type":"string"},"description":"Return only buildings whose primary use is one of these, for example `Residential` or `Commercial`."},"buildingUseTierA":{"type":"array","items":{"type":"string"},"description":"Return only buildings whose broader land use category is one of these."},"connectivity":{"type":"array","items":{"type":"string","enum":["Standalone","Multi-Connected","Linked","Detached"]},"description":"Return only buildings whose relation to the neighbouring buildings is one of these."},"physicalState":{"type":"array","items":{"type":"string","enum":["Built","Demolished","Ruined","UnderConstruction"]},"description":"Return only buildings in one of these physical states."},"floorsMin":{"type":"integer","description":"Fewest floors above ground to include, inclusive."},"floorsMax":{"type":"integer","description":"Most floors above ground to include, inclusive."},"heightMaxMin":{"type":"number","description":"Lowest building height to include, in metres, inclusive."},"heightMaxMax":{"type":"number","description":"Greatest building height to include, in metres, inclusive."},"areaSqmMin":{"type":"number","description":"Smallest footprint area to include, in square metres, inclusive."},"areaSqmMax":{"type":"number","description":"Largest footprint area to include, in square metres, inclusive."},"hasUprnLink":{"type":"boolean","description":"Set to `true` to return only buildings with at least one linked addressable location. Setting it to `false` has no effect."}},"description":"Convenience filters covering the common cases. Every one supplied has to match, alongside anything in `query`."},"BuildingQueryOperator":{"type":"object","properties":{"operator":{"type":"string","enum":["AND","OR"],"description":"How the conditions combine: `AND` needs every condition to match, `OR` needs at least one."},"groups":{"type":"array","items":{"$ref":"#/components/schemas/BuildingQueryGroup"},"description":"Condition groups. A building matches this operator if it satisfies any one of the groups."}},"required":["operator","groups"]},"BuildingQueryGroup":{"type":"object","properties":{"conditions":{"type":"array","items":{"$ref":"#/components/schemas/BuildingQueryCondition"},"description":"Conditions in this group. They are joined by the operator set on the group's parent."}},"required":["conditions"]},"BuildingQueryCondition":{"type":"object","properties":{"field":{"type":"string","enum":["buildingId","country","provider","externalId","sources","dataSources","status","areaSqm","heightMax","heightRoofBase","floors","partCount","buildingUse","buildingUseTierA","type","physicalState","connectivity","locationIds","addressCount.total","addressCount.residential","addressCount.commercial","addressCount.other","structure.footprintAreaSqm","structure.heightMax","structure.heightRoofBase","structure.floors","structure.physicalState","structure.connectivity","structure.dataSources","construction.wallConstruction","construction.materialDescription","construction.age.startYear","construction.age.endYear","construction.age.midYear","construction.age.isExact","construction.year","construction.evidenceDate","construction.dataSources","basement.present","basement.selfContained","basement.dataSources","registeredAt","sourceUpdatedAt","updatedAt","indexedAt","centroid"],"description":"Field the condition applies to."},"comparator":{"type":"string","enum":["eq","ne","gt","gte","lt","lte","in","nin","contains","startswith","endswith"],"description":"How `value` is compared with the field. `eq` and `ne` test exact equality. `gt`, `gte`, `lt` and `lte` compare numeric and date fields, with `gte` and `lte` inclusive. `in` and `nin` test whether the field is one of the values in an array. `contains`, `startswith` and `endswith` match part of a text field, case-sensitively."},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}],"description":"Value the field is compared against. Pass an array for `in` and `nin`."}},"required":["field","comparator","value"],"example":{"field":"areaSqm","comparator":"gte","value":200}},"BuildingAreaFilter":{"oneOf":[{"$ref":"#/components/schemas/BuildingPolygonAreaFilter"},{"$ref":"#/components/schemas/BuildingMultiPolygonAreaFilter"},{"$ref":"#/components/schemas/BuildingPointAreaFilter"},{"$ref":"#/components/schemas/BuildingContainsPointAreaFilter"},{"$ref":"#/components/schemas/BuildingBoundingBoxAreaFilter"}],"discriminator":{"propertyName":"type","mapping":{"polygon":"#/components/schemas/BuildingPolygonAreaFilter","multipolygon":"#/components/schemas/BuildingMultiPolygonAreaFilter","point":"#/components/schemas/BuildingPointAreaFilter","containsPoint":"#/components/schemas/BuildingContainsPointAreaFilter","boundingBox":"#/components/schemas/BuildingBoundingBoxAreaFilter"}}},"BuildingPolygonAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"description":"The rings of the polygon to search within. The first ring is the outer boundary and any further rings are holes inside it. Positions are longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[[[-0.1278,51.5074],[-0.128,51.508],[-0.1275,51.507],[-0.1278,51.5074]]]},"relation":{"type":"string","enum":["intersects","within","contains"],"description":"How the building footprint must relate to the polygon. `intersects` matches when the two overlap at all, `within` when the footprint lies entirely inside the polygon, and `contains` when it entirely encloses the polygon. Defaults to `intersects`."}},"required":["type","coordinates"]},"BuildingMultiPolygonAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["multipolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}},"description":"One entry per polygon to search within, each holding that polygon's rings in the same form as the polygon filter. Positions are longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[[[[-0.1278,51.5074],[-0.128,51.508],[-0.1275,51.507],[-0.1278,51.5074]]]]},"relation":{"type":"string","enum":["intersects","within","contains"],"description":"How the building footprint must relate to the polygons, using the same options as the polygon filter. Defaults to `intersects`."}},"required":["type","coordinates"]},"BuildingPointAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["point"]},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the centre point, in WGS84 decimal degrees."},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the centre point, in WGS84 decimal degrees."},"radius":{"type":"string","description":"How far out from the centre point to search, measured from each building's centroid. Written as a number and a unit: `m` for metres, `km` for kilometres, `mi` for miles, `yd` for yards or `ft` for feet.","example":"500m"}},"required":["type","lat","lon","radius"]},"BuildingContainsPointAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["containsPoint"]},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the point, in WGS84 decimal degrees."},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the point, in WGS84 decimal degrees."}},"required":["type","lat","lon"],"description":"Match buildings whose footprint encloses this point, a point-in-polygon test."},"BuildingBoundingBoxAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["boundingBox"]},"topLeft":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the northern edge."},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the western edge."}},"required":["lat","lon"],"description":"North-west corner of the box."},"bottomRight":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the southern edge."},"lon":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the eastern edge."}},"required":["lat","lon"],"description":"South-east corner of the box."}},"required":["type","topLeft","bottomRight"],"description":"Match buildings whose centroid falls inside a rectangular box. Useful for map viewport queries."},"BuildingAggregateResponse":{"type":"object","properties":{"total":{"type":"number","description":"Total number of buildings matching the request, counted before the aggregations were applied."},"aggregations":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/AggregationResult"},"description":"One result per aggregation, keyed by the `name` given in the request. The shape of each result follows the aggregation's type."}},"required":["total","aggregations"]},"BuildingAggregateRequest":{"type":"object","properties":{"aggregations":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name for this aggregation. It is the key its result appears under in the response `aggregations` object, so it must be unique within the request."},"type":{"type":"string","enum":["terms","stats","min","max","avg","sum","cardinality","histogram","date_histogram","percentiles","geotile_grid"],"description":"How the matching buildings are aggregated. Each type takes its own parameters and returns its own result shape."},"field":{"type":"string","enum":["buildingId","country","provider","externalId","sources","dataSources","status","areaSqm","heightMax","heightRoofBase","floors","partCount","buildingUse","buildingUseTierA","type","physicalState","connectivity","locationIds","addressCount.total","addressCount.residential","addressCount.commercial","addressCount.other","structure.footprintAreaSqm","structure.heightMax","structure.heightRoofBase","structure.floors","structure.physicalState","structure.connectivity","structure.dataSources","construction.wallConstruction","construction.materialDescription","construction.age.startYear","construction.age.endYear","construction.age.midYear","construction.age.isExact","construction.year","construction.evidenceDate","construction.dataSources","basement.present","basement.selfContained","basement.dataSources","registeredAt","sourceUpdatedAt","updatedAt","indexedAt","centroid"],"description":"Field to aggregate over."},"size":{"type":"integer","minimum":1,"maximum":1000,"description":"Maximum number of buckets a grouping aggregation returns. Defaults to 20. Maximum 1000."},"interval":{"anyOf":[{"type":"number"},{"type":"string"}],"description":"Width of each bucket. Pass a number for a numeric histogram, which defaults to 100, or a calendar interval such as `1M` or `1y` for a date histogram, which defaults to `1M`."},"precision":{"type":"integer","minimum":0,"maximum":29,"description":"Tile precision for the map-tile grouping type, from 0 for the coarsest grid to 29 for the finest. Defaults to 6."},"percents":{"type":"array","items":{"type":"number","minimum":0,"maximum":100},"description":"The percentiles to compute, each between 0 and 100. Used by the `percentiles` type."}},"required":["name","type","field"]},"minItems":1,"maxItems":10,"description":"The aggregations to run. At least one, and no more than 10 per request."},"filters":{"allOf":[{"$ref":"#/components/schemas/BuildingFilters"},{"description":"Convenience filters narrowing which buildings are aggregated."}]},"query":{"type":"array","items":{"$ref":"#/components/schemas/BuildingQueryOperator"},"description":"Query operators narrowing which buildings are aggregated."},"area":{"type":"array","items":{"$ref":"#/components/schemas/BuildingAreaFilter"},"description":"Geographic area filters. A building is aggregated if it satisfies any one of them."}},"required":["aggregations"]},"BuildingByIdsRequest":{"type":"object","properties":{"buildingIds":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":100,"description":"The building identifiers to look up. At least one, and no more than 100 per request.","example":["GB:NGD:abc12345-67de-89f0-1234-567890abcdef"]},"attributes":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Fields to return, in the same form as the search request."}},"required":["buildingIds"]},"CompanyResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"description":"Always true. A failed request returns an error object instead."},"result":{"$ref":"#/components/schemas/Company"},"officers":{"type":"array","items":{"$ref":"#/components/schemas/OfficerSummary"},"description":"Active officer appointments at this company, up to 50 of them. Present only when the request sets includeOfficers=true."},"pscs":{"type":"array","items":{"$ref":"#/components/schemas/PscSummary"},"description":"Active PSC notifications for this company, up to 50 of them. Present only when the request sets includePscs=true."}},"required":["success","result"],"description":"One company, with officer and PSC summaries when the request asked for them."},"Company":{"type":"object","properties":{"companyNumber":{"type":"string","minLength":8,"maxLength":8,"description":"The company's registration number at Companies House, always eight characters. Most are digits, zero-padded, such as `00000006`. Some carry a letter prefix: `OC` for limited liability partnerships, `SC` for Scottish companies, `NI` for Northern Ireland and `OE` for overseas entities.","example":"00000006"},"companyName":{"type":"string","description":"The company's registered name as it appears on the register, normally in capitals. It includes the legal suffix, such as `LTD`, `PLC` or `LLP`, unless the company is exempt from using one.","example":"MARINE AND GENERAL MUTUAL LIFE ASSURANCE SOCIETY"},"companyStatus":{"type":"string","enum":["active","dissolved","liquidation","receivership","converted-closed","voluntary-arrangement","insolvency-proceedings","administration","open","closed","registered","removed"],"description":"Where the company stands on the Companies House register. `active` and `registered` are live, `dissolved` and `removed` have left the register, and `liquidation`, `receivership`, `administration`, `voluntary-arrangement` and `insolvency-proceedings` are stages of insolvency. Overseas entities use `open` and `closed` rather than `active` and `dissolved`.","example":"active"},"companyType":{"type":"string","enum":["private-unlimited","ltd","plc","old-public-company","private-limited-guarant-nsc-limited-exemption","limited-partnership","private-limited-guarant-nsc","converted-or-closed","private-unlimited-nsc","private-limited-shares-section-30-exemption","protected-cell-company","assurance-company","oversea-company","eeig-establishment","icvc-securities","icvc-warrant","icvc-umbrella","registered-society-non-jurisdictional","industrial-and-provident-society","northern-ireland","northern-ireland-other","llp","royal-charter","investment-company-with-variable-capital","unregistered-company","other","european-public-limited-liability-company-se","united-kingdom-societas","uk-establishment","scottish-partnership","charitable-incorporated-organisation","scottish-charitable-incorporated-organisation","further-education-or-sixth-form-college-corporation","eeig","ukeig","registered-overseas-entity"],"description":"The legal structure the entity is registered under. Most companies are `ltd` (private company limited by shares), `plc` (public limited company) or `llp` (limited liability partnership); the remaining values cover overseas entities, investment vehicles, charitable forms and older company types.","example":"private-unlimited"},"companySubtype":{"type":["string","null"],"enum":["community-interest-company","private-fund-limited-partnership","slp","pflp","spflp",null],"description":"A further classification on top of the company type, such as `community-interest-company`. Null for most companies."},"jurisdiction":{"type":"string","enum":["england-wales","wales","scotland","northern-ireland","european-union","united-kingdom","england","noneu"],"description":"The UK jurisdiction the company is registered in, which sets the legal framework that applies to it and the Companies House office that holds the record. Most companies are `england-wales`.","example":"england-wales"},"countryOfOrigin":{"type":["string","null"],"description":"For an entity incorporated outside the UK, the country it comes from. Null for UK-incorporated companies.","example":"United Kingdom"},"incorporationDate":{"type":["string","null"],"format":"date-time","description":"When the company came into legal existence, as an ISO 8601 date. Null when the register does not record one.","example":"1852-11-04T00:00:00Z"},"dissolutionDate":{"type":["string","null"],"format":"date-time","description":"When the company was dissolved and struck off the register, as an ISO 8601 date. Null for companies that have not been dissolved."},"lastMembersListDate":{"type":["string","null"],"format":"date-time","description":"The date of the most recent annual return or confirmation statement, as an ISO 8601 date. The confirmation statement replaced the annual return in June 2016."},"sicCodes":{"type":"array","items":{"$ref":"#/components/schemas/SicCode"},"maxItems":4,"description":"The Standard Industrial Classification (SIC 2007) codes recorded for the company's business activities, up to four of them. Each entry carries the four- or five-character code and, where the register supplies one, a plain-English label from the Office for National Statistics code list. A company search filtered by sicCodes matches these values in full, so `62020` matches that code and nothing else. The same codes appear on the company summaries returned by the search and location endpoints. The array is empty when the register carries no codes for the company.","example":[{"code":"65110","description":"Life insurance"}]},"previousNames":{"type":"array","items":{"$ref":"#/components/schemas/PreviousName"},"maxItems":10,"description":"Names the company was registered under before its current one, each with the dates it was in use. Up to 10 entries, which lets you trace a company across a rename."},"registeredOfficeAddress":{"type":["object","null"],"properties":{"premises":{"type":["string","null"],"description":"Building name or number.","example":"MGM House"},"addressLine1":{"type":["string","null"],"description":"First line of the street address.","example":"Heene Road"},"addressLine2":{"type":["string","null"],"description":"Second line of the address, such as a district or area within a town."},"locality":{"type":["string","null"],"description":"Town or city.","example":"Worthing"},"region":{"type":["string","null"],"description":"County or administrative area.","example":"West Sussex"},"postalCode":{"type":["string","null"],"description":"Postcode, or the equivalent postal code for an address outside the UK.","example":"BN11 2DY"},"country":{"type":["string","null"],"description":"Country as recorded on the register.","example":"United Kingdom"},"careOf":{"type":["string","null"],"description":"The name mail should be addressed care of, where correspondence goes through a third party."},"poBox":{"type":["string","null"],"description":"PO Box number, where the address uses one."},"formattedAddress":{"type":["string","null"],"description":"The whole address on one line, built from the components that are present.","example":"MGM House, Heene Road, Worthing, West Sussex, BN11 2DY"}},"description":"The company's registered office, the official address for serving legal documents and for correspondence from Companies House. Every UK company must have one."},"locationId":{"type":["string","null"],"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). It is the location of the registered office, and is null when that address could not be matched to one.","example":"100062039919"},"accountsType":{"type":["string","null"],"enum":["null","full","small","medium","group","dormant","interim","initial","total-exemption-full","total-exemption-small","partial-exemption","audit-exemption-subsidiary","filing-exemption-subsidiary","micro-entity","no-accounts-type-available","audited-abridged","unaudited-abridged",null],"description":"The kind of annual accounts the company files, which follows from its size. Null when the register does not record one."},"accountsNextDueDate":{"type":["string","null"],"format":"date-time","description":"The deadline for filing the next set of annual accounts, as an ISO 8601 date."},"accountsLastMadeUpToDate":{"type":["string","null"],"format":"date-time","description":"The end of the period covered by the most recently filed accounts, as an ISO 8601 date."},"confirmationStatementNextDueDate":{"type":["string","null"],"format":"date-time","description":"The deadline for the next confirmation statement, as an ISO 8601 date. A company must confirm its details with Companies House at least once every 12 months."},"confirmationStatementLastMadeUpToDate":{"type":["string","null"],"format":"date-time","description":"The date the most recent confirmation statement was made up to, as an ISO 8601 date."},"hasCharges":{"type":"boolean","description":"True when the company has charges registered against it, such as mortgages, debentures or other security interests. Charges are registered under Part 25 of the Companies Act 2006."},"hasInsolvencyHistory":{"type":"boolean","description":"True when the register holds insolvency events for the company, such as a winding-up petition, an administration order, a company voluntary arrangement or liquidation proceedings."},"canFile":{"type":"boolean","description":"True when the company can still file documents with Companies House. It is false once a company has been dissolved, and in some insolvency states."},"isOnRegisterInJurisdiction":{"type":["boolean","null"],"description":"For an overseas entity, true when it is still registered in its home jurisdiction. Null for UK-incorporated companies."},"externalRegistrationNumber":{"type":["string","null"],"description":"For an overseas entity, its registration number in its home jurisdiction. Null for UK-incorporated companies."},"createdAt":{"type":"string","format":"date-time","description":"When this record first appeared in the API, as an ISO 8601 timestamp."},"updatedAt":{"type":"string","format":"date-time","description":"When this record was last updated, as an ISO 8601 timestamp."}},"required":["companyNumber","companyName","companyStatus","companyType","jurisdiction","sicCodes","hasCharges","hasInsolvencyHistory","canFile","createdAt","updatedAt"],"description":"The company record."},"SicCode":{"type":"object","properties":{"code":{"type":"string","minLength":4,"maxLength":5,"description":"A UK SIC 2007 code identifying one of the company's business activities, four or five characters long. The code list is published by the Office for National Statistics.","example":"62020"},"description":{"type":"string","description":"Plain-English label for the code. Not present in every response.","example":"Information technology consultancy activities"}},"required":["code"],"description":"One Standard Industrial Classification (SIC 2007) code recording a business activity of the company."},"PreviousName":{"type":"object","properties":{"name":{"type":"string","description":"A name the company was registered under before its current one, exactly as it appeared.","example":"OLD COMPANY NAME LTD"},"effectiveFrom":{"type":["string","null"],"format":"date-time","description":"When the company started using this name, as an ISO 8601 date.","example":"2015-01-01T00:00:00Z"},"ceasedOn":{"type":["string","null"],"format":"date-time","description":"When the company stopped using this name, which is when the next name change took effect, as an ISO 8601 date.","example":"2020-06-15T00:00:00Z"}},"required":["name"],"description":"A name the company held previously, with the dates it was in use."},"OfficerSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier for this officer appointment, as a UUID."},"companyNumber":{"type":"string","minLength":8,"maxLength":8,"description":"The eight-character registration number of the company the officer is appointed to."},"officerRole":{"type":"string","enum":["cic-manager","corporate-director","corporate-llp-designated-member","corporate-llp-member","corporate-manager-of-an-eeig","corporate-managing-officer","corporate-member-of-a-management-organ","corporate-member-of-a-supervisory-organ","corporate-member-of-an-administrative-organ","corporate-nominee-director","corporate-nominee-secretary","corporate-secretary","director","general-partner-in-a-limited-partnership","judicial-factor","limited-partner-in-a-limited-partnership","llp-designated-member","llp-member","manager-of-an-eeig","managing-officer","member-of-a-management-organ","member-of-a-supervisory-organ","member-of-an-administrative-organ","nominee-director","nominee-secretary","person-authorised-to-accept","person-authorised-to-represent","person-authorised-to-represent-and-accept","receiver-and-manager","secretary"],"description":"The role the officer holds in this appointment. Most are `director`, `secretary`, `llp-member` or `llp-designated-member`. Values prefixed `corporate-` mean a body corporate holds the role rather than a person. The remaining values cover partnership roles, European entity roles and special roles such as a judicial factor or a person authorised to accept service."},"name":{"type":"string","description":"The officer's name as recorded on this appointment."},"appointedOn":{"type":["string","null"],"format":"date-time","description":"When the officer was appointed to this role, as an ISO 8601 date."},"resignedOn":{"type":["string","null"],"format":"date-time","description":"When the officer resigned or was removed, as an ISO 8601 date. Null while the appointment is still active."},"occupation":{"type":["string","null"],"description":"The occupation the officer declared on this appointment."},"personId":{"type":["string","null"],"format":"uuid","description":"The deduplicated person holding this appointment, as a UUID, set for natural persons. Use it with /companies/persons/{personId} for the full profile."}},"required":["id","companyNumber","officerRole","name"],"description":"An officer appointment as returned in list responses and nested inside company and person records."},"PscSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier for this PSC notification, as a UUID."},"companyNumber":{"type":"string","minLength":8,"maxLength":8,"description":"The eight-character registration number of the company this PSC has control over."},"kind":{"type":"string","enum":["individual-person-with-significant-control","corporate-entity-person-with-significant-control","legal-person-person-with-significant-control","super-secure-person-with-significant-control","individual-beneficial-owner","corporate-entity-beneficial-owner","legal-person-beneficial-owner","super-secure-beneficial-owner"],"description":"What kind of party holds the control: a natural person for the `individual-` kinds, a company for the `corporate-entity-` kinds, a non-company legal entity for the `legal-person-` kinds, and an individual whose identity is protected by court order for the `super-secure-` kinds. The beneficial owner kinds apply to overseas entities registered under the Economic Crime (Transparency and Enforcement) Act 2022."},"name":{"type":"string","description":"The PSC's name as recorded on the notification."},"naturesOfControl":{"type":"array","items":{"type":"string"},"description":"How this PSC controls the company, one entry per type and threshold of control."},"notifiedOn":{"type":["string","null"],"format":"date-time","description":"When the company was notified of this PSC, as an ISO 8601 date."},"ceasedOn":{"type":["string","null"],"format":"date-time","description":"When the PSC stopped having significant control, as an ISO 8601 date. Null while the control still stands."},"isSuperSecure":{"type":"boolean","description":"True when this PSC's identity is protected by a court order."},"isSanctioned":{"type":"boolean","description":"True when this PSC is subject to financial sanctions."},"personId":{"type":["string","null"],"format":"uuid","description":"The deduplicated person behind this notification, as a UUID, set for individual PSCs. Use it with /companies/persons/{personId} for the full profile."}},"required":["id","companyNumber","kind","name","naturesOfControl","isSuperSecure","isSanctioned"],"description":"A PSC notification as returned in list responses and nested inside company records."},"CompanyListResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"description":"Always true. A failed request returns an error object instead."},"results":{"type":"array","items":{"$ref":"#/components/schemas/CompanySummary"},"description":"The companies matching the search, one summary each."},"total":{"type":"integer","description":"Total number of results matching the request across all pages."},"limit":{"type":"integer","description":"The page size applied to this request."},"offset":{"type":"integer","description":"The number of results skipped before this page."},"hasMore":{"type":"boolean","description":"True when further results exist beyond this page. Add limit to offset to request the next one."}},"required":["success","results","total","limit","offset","hasMore"],"description":"A page of companies matching the search, with the total number of matches."},"CompanySummary":{"type":"object","properties":{"companyNumber":{"type":"string","minLength":8,"maxLength":8,"description":"The company's eight-character registration number at Companies House."},"companyName":{"type":"string","description":"The company's registered name as it appears on the register."},"companyStatus":{"type":"string","enum":["active","dissolved","liquidation","receivership","converted-closed","voluntary-arrangement","insolvency-proceedings","administration","open","closed","registered","removed"],"description":"Where the company stands on the Companies House register. `active` and `registered` are live, `dissolved` and `removed` have left the register, and `liquidation`, `receivership`, `administration`, `voluntary-arrangement` and `insolvency-proceedings` are stages of insolvency. Overseas entities use `open` and `closed` rather than `active` and `dissolved`."},"companyType":{"type":"string","enum":["private-unlimited","ltd","plc","old-public-company","private-limited-guarant-nsc-limited-exemption","limited-partnership","private-limited-guarant-nsc","converted-or-closed","private-unlimited-nsc","private-limited-shares-section-30-exemption","protected-cell-company","assurance-company","oversea-company","eeig-establishment","icvc-securities","icvc-warrant","icvc-umbrella","registered-society-non-jurisdictional","industrial-and-provident-society","northern-ireland","northern-ireland-other","llp","royal-charter","investment-company-with-variable-capital","unregistered-company","other","european-public-limited-liability-company-se","united-kingdom-societas","uk-establishment","scottish-partnership","charitable-incorporated-organisation","scottish-charitable-incorporated-organisation","further-education-or-sixth-form-college-corporation","eeig","ukeig","registered-overseas-entity"],"description":"The legal structure the entity is registered under. Most companies are `ltd` (private company limited by shares), `plc` (public limited company) or `llp` (limited liability partnership); the remaining values cover overseas entities, investment vehicles, charitable forms and older company types."},"jurisdiction":{"type":"string","enum":["england-wales","wales","scotland","northern-ireland","european-union","united-kingdom","england","noneu"],"description":"The UK jurisdiction the company is registered in, which sets the legal framework that applies to it and the Companies House office that holds the record. Most companies are `england-wales`."},"incorporationDate":{"type":["string","null"],"format":"date-time","description":"When the company came into legal existence, as an ISO 8601 date."},"sicCodes":{"type":"array","items":{"$ref":"#/components/schemas/SicCode"},"maxItems":4,"description":"The SIC 2007 codes the company registered for its business activities, up to four of them. The array is empty when the register carries none."},"registeredOfficeAddress":{"type":["object","null"],"properties":{"premises":{"type":["string","null"],"description":"Building name or number.","example":"MGM House"},"addressLine1":{"type":["string","null"],"description":"First line of the street address.","example":"Heene Road"},"addressLine2":{"type":["string","null"],"description":"Second line of the address, such as a district or area within a town."},"locality":{"type":["string","null"],"description":"Town or city.","example":"Worthing"},"region":{"type":["string","null"],"description":"County or administrative area.","example":"West Sussex"},"postalCode":{"type":["string","null"],"description":"Postcode, or the equivalent postal code for an address outside the UK.","example":"BN11 2DY"},"country":{"type":["string","null"],"description":"Country as recorded on the register.","example":"United Kingdom"},"careOf":{"type":["string","null"],"description":"The name mail should be addressed care of, where correspondence goes through a third party."},"poBox":{"type":["string","null"],"description":"PO Box number, where the address uses one."},"formattedAddress":{"type":["string","null"],"description":"The whole address on one line, built from the components that are present.","example":"MGM House, Heene Road, Worthing, West Sussex, BN11 2DY"}},"description":"The company's registered office address. Not returned in list responses; fetch the company by its number to read it."},"locationId":{"type":["string","null"],"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). Null when the registered office address could not be matched to one."},"hasCharges":{"type":"boolean","description":"True when the company has charges registered against it."},"hasInsolvencyHistory":{"type":"boolean","description":"True when the register holds insolvency events for the company."}},"required":["companyNumber","companyName","companyStatus","companyType","jurisdiction","sicCodes","hasCharges","hasInsolvencyHistory"],"description":"A company as returned in list and search responses: identification, status, classification and the location of its registered office, without the filing dates and name history."},"CompanyQueryRequest":{"type":"object","properties":{"name":{"type":"string","description":"Return only companies whose registered name contains this text, ignoring case. It is a substring match, so partial names work but misspellings do not.","example":"Vepler"},"companyNumber":{"type":"string","description":"Return only the company with this registration number, so at most one result. Shorter values are zero-padded to eight characters, so `6` matches `00000006`.","example":"12345678"},"statuses":{"type":"array","items":{"type":"string","enum":["active","dissolved","liquidation","receivership","converted-closed","voluntary-arrangement","insolvency-proceedings","administration","open","closed","registered","removed"],"description":"Where the company stands on the Companies House register. `active` and `registered` are live, `dissolved` and `removed` have left the register, and `liquidation`, `receivership`, `administration`, `voluntary-arrangement` and `insolvency-proceedings` are stages of insolvency. Overseas entities use `open` and `closed` rather than `active` and `dissolved`."},"description":"Return only companies whose status is one of these values, such as `active` or `dissolved`.","example":["active"]},"types":{"type":"array","items":{"type":"string","enum":["private-unlimited","ltd","plc","old-public-company","private-limited-guarant-nsc-limited-exemption","limited-partnership","private-limited-guarant-nsc","converted-or-closed","private-unlimited-nsc","private-limited-shares-section-30-exemption","protected-cell-company","assurance-company","oversea-company","eeig-establishment","icvc-securities","icvc-warrant","icvc-umbrella","registered-society-non-jurisdictional","industrial-and-provident-society","northern-ireland","northern-ireland-other","llp","royal-charter","investment-company-with-variable-capital","unregistered-company","other","european-public-limited-liability-company-se","united-kingdom-societas","uk-establishment","scottish-partnership","charitable-incorporated-organisation","scottish-charitable-incorporated-organisation","further-education-or-sixth-form-college-corporation","eeig","ukeig","registered-overseas-entity"],"description":"The legal structure the entity is registered under. Most companies are `ltd` (private company limited by shares), `plc` (public limited company) or `llp` (limited liability partnership); the remaining values cover overseas entities, investment vehicles, charitable forms and older company types."},"description":"Return only companies whose legal structure is one of these values, such as `ltd` for a private company limited by shares, `plc` for a public limited company or `llp` for a limited liability partnership.","example":["ltd","plc"]},"jurisdictions":{"type":"array","items":{"type":"string","enum":["england-wales","wales","scotland","northern-ireland","european-union","united-kingdom","england","noneu"],"description":"The UK jurisdiction the company is registered in, which sets the legal framework that applies to it and the Companies House office that holds the record. Most companies are `england-wales`."},"description":"Return only companies registered in one of these UK jurisdictions, such as `england-wales`, `scotland` or `northern-ireland`.","example":["england-wales"]},"sicCodes":{"type":"array","items":{"type":"string"},"description":"Return only companies that registered one or more of these SIC 2007 codes. Codes are matched in full, so `62020` matches that code and nothing else.","example":["62020","62090"]},"locationId":{"type":"string","description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). Returns only companies whose registered office is at that location.","example":"100023336956"},"postcode":{"type":"string","description":"Return only companies whose registered office is at this full postcode. Spaces and letter case are ignored, so `sw1a1aa` matches `SW1A 1AA`.","example":"SW1A 1AA"},"postcodePrefix":{"type":"string","description":"Return only companies whose registered office postcode starts with this text, ignoring case. Pass its outward code (the first part, such as `SW1A`) to search a whole area.","example":"SW1A"},"incorporatedAfter":{"type":"string","format":"date-time","description":"Return only companies incorporated on or after this date. Send an ISO 8601 timestamp.","example":"2020-01-01T00:00:00Z"},"incorporatedBefore":{"type":"string","format":"date-time","description":"Return only companies incorporated on or before this date. Send an ISO 8601 timestamp.","example":"2024-01-01T00:00:00Z"},"hasCharges":{"type":"boolean","description":"Set to true for companies that have charges registered against them, false for those that have none. Leave it out to include both."},"hasInsolvencyHistory":{"type":"boolean","description":"Set to true for companies with insolvency events on the register, false for those with none. Leave it out to include both."},"includeOfficers":{"type":"boolean","default":false,"description":"Officer summaries are not part of a company search result. Read them from /companies/{companyNumber}/officers, or from /companies/{companyNumber} with includeOfficers=true."},"includePscs":{"type":"boolean","default":false,"description":"PSC summaries are not part of a company search result. Read them from /companies/{companyNumber}/pscs, or from /companies/{companyNumber} with includePscs=true."},"includeAddress":{"type":"boolean","default":true,"description":"The registered office address is not part of a company search result. Read the full company record from /companies/{companyNumber} to get it."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Maximum number of items to return. Defaults to 25. Minimum 1, maximum 100."},"offset":{"type":"integer","minimum":0,"default":0,"description":"Number of results to skip before the first one returned. Defaults to 0."},"sortBy":{"type":"string","enum":["companyName","incorporationDate","updatedAt"],"default":"companyName","description":"Which field orders the results: `companyName` alphabetically, `incorporationDate` by age, `updatedAt` by when the record last changed. Defaults to `companyName`."},"sortOrder":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Direction of the sort: `asc` for ascending, `desc` for descending. Defaults to `asc`."}},"description":"Filters, paging and sort order for a company search."},"CompaniesByLocationResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"description":"Always true. A failed request returns an error object instead."},"locationId":{"type":"string","description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). Echoes the location identifier from the request."},"companies":{"type":"array","items":{"$ref":"#/components/schemas/CompanySummary"},"description":"The companies whose registered office is at this location, ordered by name."},"total":{"type":"integer","description":"How many companies were returned. This response is not paginated."}},"required":["success","locationId","companies","total"],"description":"Every company registered at one location, for checking who trades from an address and for ownership and due-diligence work."},"OfficerListResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"description":"Always true. A failed request returns an error object instead."},"results":{"type":"array","items":{"$ref":"#/components/schemas/OfficerSummary"},"description":"The officer appointments matching the filters, one summary each."},"total":{"type":"integer","description":"Total number of results matching the request across all pages."},"limit":{"type":"integer","description":"The page size applied to this request."},"offset":{"type":"integer","description":"The number of results skipped before this page."},"hasMore":{"type":"boolean","description":"True when further results exist beyond this page."}},"required":["success","results","total","limit","offset","hasMore"],"description":"A page of officer appointments at one company, with the total number of matches."},"PscListResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"description":"Always true. A failed request returns an error object instead."},"results":{"type":"array","items":{"$ref":"#/components/schemas/PscSummary"},"description":"The PSC notifications matching the filters, one summary each."},"total":{"type":"integer","description":"Total number of results matching the request across all pages."},"limit":{"type":"integer","description":"The page size applied to this request."},"offset":{"type":"integer","description":"The number of results skipped before this page."},"hasMore":{"type":"boolean","description":"True when further results exist beyond this page."}},"required":["success","results","total","limit","offset","hasMore"],"description":"A page of PSC notifications for one company, with the total number of matches."},"PersonResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"description":"Always true. A failed request returns an error object instead."},"result":{"$ref":"#/components/schemas/Person"},"appointments":{"type":"array","items":{"$ref":"#/components/schemas/OfficerSummary"},"description":"Officer appointments held by this person. Not returned here; read them from /companies/persons/{personId}/appointments."},"pscNotifications":{"type":"array","items":{"$ref":"#/components/schemas/PscSummary"},"description":"PSC notifications linked to this person. Not returned here."}},"required":["success","result"],"description":"One person, deduplicated across the officer appointments and PSC notifications that name them."},"Person":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier for this person record, as a UUID. Officer and PSC records point at it as personId.","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479"},"name":{"type":"string","description":"The person's full name, normally in capitals as recorded by Companies House.","example":"JOHN WILLIAM SMITH"},"title":{"type":["string","null"],"description":"Personal title as declared on the appointment, such as `Mr`, `Mrs`, `Dr` or `Sir`.","example":"Mr"},"forename":{"type":["string","null"],"description":"First name.","example":"John"},"otherForenames":{"type":["string","null"],"description":"Middle or other forenames, where declared.","example":"William"},"surname":{"type":["string","null"],"description":"Family name.","example":"Smith"},"dateOfBirth":{"type":["object","null"],"properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of birth, from 1 for January to 12 for December.","example":3},"year":{"type":"integer","minimum":1900,"maximum":2100,"description":"Year of birth, as four digits between 1900 and 2100.","example":1965}},"required":["month","year"],"description":"Month and year of birth. Companies House does not disclose the day. Null when the register carries no date of birth for this person."},"nationality":{"type":["string","null"],"description":"Nationality as declared to Companies House.","example":"British"},"countryOfResidence":{"type":["string","null"],"description":"The country the person usually lives in, as declared to Companies House.","example":"United Kingdom"},"totalAppointments":{"type":"integer","description":"How many officer appointments this person holds or has held across all companies, active and resigned combined.","example":5},"activeAppointments":{"type":"integer","description":"How many officer appointments this person currently holds.","example":2},"clusterId":{"type":["string","null"],"format":"uuid","description":"Identifier of the cluster this record belongs to, as a UUID. Records sharing it are judged to represent the same individual, and the whole cluster can be read from /companies/persons/cluster/{clusterId}. Not currently populated.","example":"c47ac10b-58cc-4372-a567-0e02b2c3d480"},"isCanonical":{"type":"boolean","description":"True when this is the primary record for the individual. Where several records have been merged, one is primary and the rest point at it, and searches return only primary records unless includeNonCanonical is set."},"createdAt":{"type":"string","format":"date-time","description":"When this record first appeared in the API, as an ISO 8601 timestamp."},"updatedAt":{"type":"string","format":"date-time","description":"When this record was last updated, as an ISO 8601 timestamp."}},"required":["id","name","totalAppointments","activeAppointments","isCanonical","createdAt","updatedAt"],"description":"The person record."},"AppointmentsResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"description":"Always true. A failed request returns an error object instead."},"personId":{"type":"string","format":"uuid","description":"The person whose appointments these are, as a UUID."},"personName":{"type":"string","description":"The person's full name."},"totalAppointments":{"type":"integer","description":"How many officer appointments this person holds or has held, active and resigned combined."},"activeAppointments":{"type":"integer","description":"How many officer appointments this person currently holds."},"appointments":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/OfficerSummary"},{"type":"object","properties":{"companyName":{"type":"string","description":"The registered name of the company this appointment is at."},"companyStatus":{"type":["string","null"],"enum":["active","dissolved","liquidation","receivership","converted-closed","voluntary-arrangement","insolvency-proceedings","administration","open","closed","registered","removed",null],"description":"The company's current status on the register, which tells you whether the appointment is at a live company or one that has been dissolved."}}}],"description":"An officer appointment as returned in list responses and nested inside company and person records."},"description":"One entry per appointment, each carrying the name and status of the company it is at."},"limit":{"type":"integer","description":"The page size applied to this request."},"offset":{"type":"integer","description":"The number of results skipped before this page."},"hasMore":{"type":"boolean","description":"True when further results exist beyond this page."}},"required":["success","personId","personName","totalAppointments","activeAppointments","appointments","limit","offset","hasMore"],"description":"The officer appointments held by one person across companies, each with the name and current status of the company behind it."},"PersonClusterResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"description":"Always true. A failed request returns an error object instead."},"result":{"$ref":"#/components/schemas/PersonCluster"}},"required":["success","result"],"description":"One entity resolution cluster: the person records judged to represent the same individual. Requires the Companies House Premium product."},"PersonCluster":{"type":"object","properties":{"clusterId":{"type":"string","format":"uuid","description":"Identifier for this cluster, as a UUID."},"clusterConfidence":{"type":["number","null"],"minimum":0,"maximum":1,"description":"Overall quality score for the cluster, from 0 to 1, where 1 is the strongest. Null when it has not been computed."},"canonicalPerson":{"type":["object","null"],"properties":{"id":{"type":"string","format":"uuid","description":"Identifier for this person record, as a UUID. Officer and PSC records point at it as personId."},"name":{"type":"string","description":"The person's full name, normally in capitals as recorded by Companies House."},"forename":{"type":["string","null"],"description":"First name."},"surname":{"type":["string","null"],"description":"Family name."},"dateOfBirth":{"type":["object","null"],"properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of birth, from 1 for January to 12 for December.","example":3},"year":{"type":"integer","minimum":1900,"maximum":2100,"description":"Year of birth, as four digits between 1900 and 2100.","example":1965}},"required":["month","year"],"description":"Month and year of birth. Companies House does not disclose the day."},"nationality":{"type":["string","null"],"description":"Nationality as declared to Companies House."},"countryOfResidence":{"type":["string","null"],"description":"The country the person usually lives in."},"totalAppointments":{"type":"integer","description":"How many officer appointments this person holds or has held, active and resigned combined."},"activeAppointments":{"type":"integer","description":"How many officer appointments this person currently holds."},"clusterId":{"type":["string","null"],"format":"uuid","description":"Identifier of the cluster this record belongs to, as a UUID. Records sharing it are judged to represent the same individual. Not currently populated."},"isCanonical":{"type":"boolean","description":"True when this is the primary record for the individual."}},"required":["id","name","totalAppointments","activeAppointments","isCanonical"],"description":"The primary record for the individual, the one to treat as authoritative. Null when no record has been marked primary."},"members":{"type":"array","items":{"$ref":"#/components/schemas/PersonSummary"},"description":"Every person record in the cluster, including the primary one."},"totalRecords":{"type":"integer","description":"How many person records the cluster holds."},"combinedAppointments":{"type":"integer","description":"Officer appointments across every record in the cluster, active and resigned combined. Use this rather than the count on a single record when a person appears more than once."},"combinedActiveAppointments":{"type":"integer","description":"Active officer appointments across every record in the cluster."}},"required":["clusterId","members","totalRecords","combinedAppointments","combinedActiveAppointments"],"description":"The cluster, with every member record."},"PersonSummary":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier for this person record, as a UUID. Officer and PSC records point at it as personId."},"name":{"type":"string","description":"The person's full name, normally in capitals as recorded by Companies House."},"forename":{"type":["string","null"],"description":"First name."},"surname":{"type":["string","null"],"description":"Family name."},"dateOfBirth":{"type":["object","null"],"properties":{"month":{"type":"integer","minimum":1,"maximum":12,"description":"Month of birth, from 1 for January to 12 for December.","example":3},"year":{"type":"integer","minimum":1900,"maximum":2100,"description":"Year of birth, as four digits between 1900 and 2100.","example":1965}},"required":["month","year"],"description":"Month and year of birth. Companies House does not disclose the day."},"nationality":{"type":["string","null"],"description":"Nationality as declared to Companies House."},"countryOfResidence":{"type":["string","null"],"description":"The country the person usually lives in."},"totalAppointments":{"type":"integer","description":"How many officer appointments this person holds or has held, active and resigned combined."},"activeAppointments":{"type":"integer","description":"How many officer appointments this person currently holds."},"clusterId":{"type":["string","null"],"format":"uuid","description":"Identifier of the cluster this record belongs to, as a UUID. Records sharing it are judged to represent the same individual. Not currently populated."},"isCanonical":{"type":"boolean","description":"True when this is the primary record for the individual."}},"required":["id","name","totalAppointments","activeAppointments","isCanonical"],"description":"A person as returned in list responses and nested inside officer and PSC records."},"PersonListResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"description":"Always true. A failed request returns an error object instead."},"results":{"type":"array","items":{"$ref":"#/components/schemas/PersonSummary"},"description":"The people matching the search, one summary each."},"total":{"type":"integer","description":"Total number of results matching the request across all pages."},"limit":{"type":"integer","description":"The page size applied to this request."},"offset":{"type":"integer","description":"The number of results skipped before this page."},"hasMore":{"type":"boolean","description":"True when further results exist beyond this page."}},"required":["success","results","total","limit","offset","hasMore"],"description":"A page of deduplicated people matching the search, with the total number of matches."},"PersonQueryRequest":{"type":"object","properties":{"name":{"type":"string","description":"Return only people whose name contains this text, ignoring case. It is a substring match, so partial names work but misspellings do not.","example":"John Smith"},"surname":{"type":"string","description":"Return only people whose family name contains this text, ignoring case.","example":"Smith"},"dobMonth":{"type":"integer","minimum":1,"maximum":12,"description":"Return only people born in this month, from 1 for January to 12 for December. Pair it with dobYear to separate people who share a name."},"dobYear":{"type":"integer","minimum":1900,"maximum":2100,"description":"Return only people born in this year, as four digits between 1900 and 2100. Companies House discloses the month and year of birth but not the day."},"nationality":{"type":"string","description":"Return only people whose declared nationality contains this text, ignoring case.","example":"British"},"countryOfResidence":{"type":"string","description":"Return only people whose declared country of residence contains this text, ignoring case.","example":"United Kingdom"},"minAppointments":{"type":"integer","minimum":0,"description":"Return only people with at least this many officer appointments, active and resigned combined. Raise it to find the people who sit on the most boards."},"minActiveAppointments":{"type":"integer","minimum":0,"description":"Return only people who currently hold at least this many officer appointments."},"clusterId":{"type":"string","format":"uuid","description":"Identifier of an entity resolution cluster, as a UUID. This filter is not currently applied, so results are unaffected by it. Read a whole cluster from /companies/persons/cluster/{clusterId}."},"includeNonCanonical":{"type":"boolean","default":false,"description":"Set to true to include the records that have been merged into a primary record. Defaults to false, which returns only primary records so a person appears once."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":25,"description":"Maximum number of items to return. Defaults to 25. Minimum 1, maximum 50."},"offset":{"type":"integer","minimum":0,"default":0,"description":"Number of results to skip before the first one returned. Defaults to 0."},"sortBy":{"type":"string","enum":["name","totalAppointments","activeAppointments","updatedAt"],"default":"name","description":"Which field orders the results: `name` alphabetically, `totalAppointments` or `activeAppointments` by how many appointments the person holds, `updatedAt` by when the record last changed. Defaults to `name`."},"sortOrder":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Direction of the sort: `asc` for ascending, `desc` for descending. Defaults to `asc`."}},"description":"Filters, paging and sort order for a search over deduplicated person records."},"OfficerResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"description":"Always true. A failed request returns an error object instead."},"result":{"$ref":"#/components/schemas/Officer"}},"required":["success","result"],"description":"One officer appointment."},"Officer":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier for this officer appointment, as a UUID."},"appointmentId":{"type":["string","null"],"description":"The identifier Companies House uses for this appointment, for cross-referencing against their own officer appointment endpoint."},"companyNumber":{"type":"string","minLength":8,"maxLength":8,"description":"The eight-character registration number of the company the officer is appointed to."},"officerRole":{"type":"string","enum":["cic-manager","corporate-director","corporate-llp-designated-member","corporate-llp-member","corporate-manager-of-an-eeig","corporate-managing-officer","corporate-member-of-a-management-organ","corporate-member-of-a-supervisory-organ","corporate-member-of-an-administrative-organ","corporate-nominee-director","corporate-nominee-secretary","corporate-secretary","director","general-partner-in-a-limited-partnership","judicial-factor","limited-partner-in-a-limited-partnership","llp-designated-member","llp-member","manager-of-an-eeig","managing-officer","member-of-a-management-organ","member-of-a-supervisory-organ","member-of-an-administrative-organ","nominee-director","nominee-secretary","person-authorised-to-accept","person-authorised-to-represent","person-authorised-to-represent-and-accept","receiver-and-manager","secretary"],"description":"The role the officer holds in this company, such as `director`, `secretary`, `llp-member` or `llp-designated-member`. Values prefixed `corporate-` mean a body corporate holds the role rather than a person.","example":"director"},"name":{"type":"string","description":"The officer's name as recorded on this appointment, normally in capitals. For a body corporate it is the entity name. The same person can appear with small differences in formatting across appointments, so match on personId rather than on the name.","example":"JOHN WILLIAM SMITH"},"appointedOn":{"type":["string","null"],"format":"date-time","description":"When the officer was appointed to this role, as an ISO 8601 date.","example":"2015-01-15T00:00:00Z"},"resignedOn":{"type":["string","null"],"format":"date-time","description":"When the officer resigned or was removed from this role, as an ISO 8601 date. Null while the appointment is still active.","example":null},"occupation":{"type":["string","null"],"description":"The occupation the officer declared on this appointment.","example":"Company Director"},"nationality":{"type":["string","null"],"description":"The nationality the officer declared on this appointment.","example":"British"},"countryOfResidence":{"type":["string","null"],"description":"The country the officer declared as their usual residence on this appointment.","example":"United Kingdom"},"serviceAddress":{"type":["object","null"],"properties":{"premises":{"type":["string","null"],"description":"Building name or number.","example":"MGM House"},"addressLine1":{"type":["string","null"],"description":"First line of the street address.","example":"Heene Road"},"addressLine2":{"type":["string","null"],"description":"Second line of the address, such as a district or area within a town."},"locality":{"type":["string","null"],"description":"Town or city.","example":"Worthing"},"region":{"type":["string","null"],"description":"County or administrative area.","example":"West Sussex"},"postalCode":{"type":["string","null"],"description":"Postcode, or the equivalent postal code for an address outside the UK.","example":"BN11 2DY"},"country":{"type":["string","null"],"description":"Country as recorded on the register.","example":"United Kingdom"},"careOf":{"type":["string","null"],"description":"The name mail should be addressed care of, where correspondence goes through a third party."},"poBox":{"type":["string","null"],"description":"PO Box number, where the address uses one."},"formattedAddress":{"type":["string","null"],"description":"The whole address on one line, built from the components that are present.","example":"MGM House, Heene Road, Worthing, West Sussex, BN11 2DY"}},"description":"The officer's service address, published for official correspondence in place of their home address, which is protected under s.240 of the Companies Act 2006. Not currently populated."},"formerNames":{"type":["string","null"],"description":"Former names of the officer, as declared on the appointment form."},"responsibilities":{"type":["string","null"],"description":"What the officer is responsible for. Used mainly for LLP designated members, who carry statutory duties beyond those of other members."},"consentFiled":{"type":["string","null"],"format":"date-time","description":"When the officer's consent to act was filed with Companies House, as an ISO 8601 timestamp."},"personId":{"type":["string","null"],"format":"uuid","description":"The deduplicated person holding this appointment, as a UUID, set for natural persons. Use it with /companies/persons/{personId} for the full profile, and with /companies/persons/{personId}/appointments for every company they are appointed to."},"corporateEntityId":{"type":["string","null"],"format":"uuid","description":"The corporate entity holding this appointment, as a UUID, set when a body corporate acts as an officer of another company."},"createdAt":{"type":"string","format":"date-time","description":"When this record first appeared in the API, as an ISO 8601 timestamp."},"updatedAt":{"type":"string","format":"date-time","description":"When this record was last updated, as an ISO 8601 timestamp."}},"required":["id","companyNumber","officerRole","name","createdAt","updatedAt"],"description":"The officer appointment."},"PscResponse":{"type":"object","properties":{"success":{"type":"boolean","enum":[true],"description":"Always true. A failed request returns an error object instead."},"result":{"$ref":"#/components/schemas/Psc"}},"required":["success","result"],"description":"One PSC notification."},"Psc":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier for this PSC notification, as a UUID."},"notificationId":{"type":["string","null"],"description":"The identifier Companies House uses for this notification, for cross-referencing against their own PSC endpoint."},"companyNumber":{"type":"string","minLength":8,"maxLength":8,"description":"The eight-character registration number of the company this PSC has control over."},"kind":{"type":"string","enum":["individual-person-with-significant-control","corporate-entity-person-with-significant-control","legal-person-person-with-significant-control","super-secure-person-with-significant-control","individual-beneficial-owner","corporate-entity-beneficial-owner","legal-person-beneficial-owner","super-secure-beneficial-owner"],"description":"What kind of party holds the control, which decides which of the other fields are filled in. The `individual-` kinds carry nationality and date of birth, the `corporate-entity-` kinds carry corporateEntityId, and the `super-secure-` kinds carry little personal detail because a court order protects the identity.","example":"individual-person-with-significant-control"},"name":{"type":"string","description":"The PSC's name as recorded on the notification. For an individual this includes the title; for a corporate entity it is the registered entity name.","example":"Mr John William Smith"},"naturesOfControl":{"type":"array","items":{"type":"string"},"description":"How this PSC controls the company, one entry per type and threshold of control, such as `ownership-of-shares-25-to-50-percent` or `voting-rights-50-to-75-percent`. A PSC can hold several at once.","example":["ownership-of-shares-25-to-50-percent","voting-rights-25-to-50-percent"]},"notifiedOn":{"type":["string","null"],"format":"date-time","description":"When the company was notified of this PSC, as an ISO 8601 date.","example":"2016-04-06T00:00:00Z"},"ceasedOn":{"type":["string","null"],"format":"date-time","description":"When the PSC stopped having significant control over the company, as an ISO 8601 date. Null while the control still stands.","example":null},"nationality":{"type":["string","null"],"description":"The PSC's nationality. Set for individuals only.","example":"British"},"countryOfResidence":{"type":["string","null"],"description":"The country the PSC usually lives in. Set for individuals only.","example":"United Kingdom"},"address":{"type":["object","null"],"properties":{"premises":{"type":["string","null"],"description":"Building name or number.","example":"MGM House"},"addressLine1":{"type":["string","null"],"description":"First line of the street address.","example":"Heene Road"},"addressLine2":{"type":["string","null"],"description":"Second line of the address, such as a district or area within a town."},"locality":{"type":["string","null"],"description":"Town or city.","example":"Worthing"},"region":{"type":["string","null"],"description":"County or administrative area.","example":"West Sussex"},"postalCode":{"type":["string","null"],"description":"Postcode, or the equivalent postal code for an address outside the UK.","example":"BN11 2DY"},"country":{"type":["string","null"],"description":"Country as recorded on the register.","example":"United Kingdom"},"careOf":{"type":["string","null"],"description":"The name mail should be addressed care of, where correspondence goes through a third party."},"poBox":{"type":["string","null"],"description":"PO Box number, where the address uses one."},"formattedAddress":{"type":["string","null"],"description":"The whole address on one line, built from the components that are present.","example":"MGM House, Heene Road, Worthing, West Sussex, BN11 2DY"}},"description":"The PSC's publicly disclosed correspondence address: a service address for an individual, or the registered or principal office for a corporate entity. Not currently populated."},"isSuperSecure":{"type":"boolean","description":"True when this PSC's identity is protected by a court order under s.790ZG of the Companies Act 2006, granted to individuals at serious risk of violence or intimidation. Personal details are withheld from the public register for these records.","example":false},"isSanctioned":{"type":"boolean","description":"True when this PSC is subject to financial sanctions. UK sanctions are administered by the Office of Financial Sanctions Implementation (OFSI).","example":false},"statement":{"type":["string","null"],"description":"The statement a company filed in place of naming a PSC, for example that no individual or entity meets the conditions."},"linkingKind":{"type":["string","null"],"description":"How this record links to a higher entity in an ownership chain, for relevant legal entities."},"personId":{"type":["string","null"],"format":"uuid","description":"The deduplicated person behind this notification, as a UUID, set for individual PSCs. Use it with /companies/persons/{personId} for the full profile."},"corporateEntityId":{"type":["string","null"],"format":"uuid","description":"The corporate entity behind this notification, as a UUID, set when a company or other legal person holds the control."},"createdAt":{"type":"string","format":"date-time","description":"When this record first appeared in the API, as an ISO 8601 timestamp."},"updatedAt":{"type":"string","format":"date-time","description":"When this record was last updated, as an ISO 8601 timestamp."}},"required":["id","companyNumber","kind","name","naturesOfControl","isSuperSecure","isSanctioned","createdAt","updatedAt"],"description":"The PSC notification."},"TitleDeedDocumentListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["title_deed_document_list"]},"title_number":{"type":"string"},"documents":{"type":"array","items":{"type":"object","properties":{"document_type":{"type":"string","enum":["register-extract","official-title","title-plan"],"description":"Which of the title's documents this is. `register-extract` is the full register of the title, carrying its proprietors, charges and restrictions; `official-title` is the official copy of that register; `title-plan` is the plan showing the extent of the property."},"status":{"type":"string","enum":["pending","uploaded","failed"],"description":"How far the document has got: `pending` while it is being prepared, `uploaded` once it can be downloaded, and `failed` if it could not be produced."},"size_bytes":{"type":["number","null"],"description":"Size of the document in bytes. Null while the document is pending or failed."},"content_type":{"type":"string","description":"Media type of the document, for example 'application/pdf'."},"uploaded_at":{"type":["string","null"],"description":"When the document became available, as an ISO 8601 timestamp. Null until it has been uploaded."},"download_url":{"type":["string","null"],"description":"Path for downloading the document, relative to the API root. Null unless `status` is `uploaded`."}},"required":["document_type","status","size_bytes","content_type","uploaded_at","download_url"]}}},"required":["object","title_number","documents"]},"TitleDeedPurchaseResponse":{"type":"object","properties":{"object":{"type":"string","enum":["title_deed_purchase"]},"already_owned":{"type":"boolean","description":"True when this title had already been purchased on this account, so nothing was charged again."},"credits_charged":{"type":"number","description":"Number of credits deducted for this request. Zero when the title was already owned."},"purchase":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier of the purchase record."},"titleNumber":{"type":"string"},"creditsCharged":{"type":"number","description":"Number of credits deducted for this purchase."},"createdAt":{"type":"string","description":"When the purchase was made, as an ISO 8601 timestamp."}},"required":["id","titleNumber","creditsCharged","createdAt"]},"title_deed":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"titleNumber":{"type":"string"},"version":{"type":"number","description":"Version of the stored title deed data. `isLatest` marks the most recent one."},"isLatest":{"type":"boolean","description":"True when this is the most recent version of the title deed data."},"propertyInfo":{"type":"object","properties":{"typeCode":{"type":"string","description":"Property type code as recorded by HM Land Registry."},"tenureType":{"type":"string","description":"Tenure of the title, for example 'Freehold' or 'Leasehold'."},"address":{"type":"object","properties":{"buildingNumber":{"type":"string"},"streetName":{"type":"string"},"cityName":{"type":"string"},"postcode":{"type":"string"}}}},"required":["address"]},"createdAt":{"type":"string","description":"When this record first appeared in the API, as an ISO 8601 timestamp."},"updatedAt":{"type":"string","description":"When this record was last updated, as an ISO 8601 timestamp."}},"required":["id","titleNumber","version","isLatest","propertyInfo","createdAt","updatedAt"]},"proprietors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"titleNumber":{"type":"string"},"proprietorOrder":{"type":"number","description":"Position of this proprietor in the proprietorship register, counting from 1."},"entityType":{"type":"string","description":"What kind of legal entity the proprietor is, for example 'individual', 'limited_company' or 'corporate_body'."},"name":{"type":"string","description":"Name to display for this proprietor: the full name of an individual, or the registered name of an organisation."},"companyNumber":{"type":["string","null"],"description":"Companies House registration number of the proprietor, where it has one."},"forenames":{"type":["string","null"],"description":"Forenames of a proprietor who is an individual."},"surname":{"type":["string","null"],"description":"Surname of a proprietor who is an individual."},"addresses":{"type":["array","null"],"items":{"type":"string"},"description":"Addresses recorded for this proprietor in the register."},"tenure":{"type":["string","null"],"description":"Tenure recorded for this proprietor's interest when the extract was taken, for example 'Freehold' or 'Leasehold'."},"isCurrent":{"type":"boolean","description":"True when this proprietor is the current registered owner."},"createdAt":{"type":"string","description":"When this record first appeared in the API, as an ISO 8601 timestamp."},"updatedAt":{"type":"string","description":"When this record was last updated, as an ISO 8601 timestamp."}},"required":["id","titleNumber","proprietorOrder","entityType","name","companyNumber","forenames","surname","addresses","tenure","isCurrent","createdAt","updatedAt"]}},"documents":{"type":"array","items":{"type":"object","properties":{"document_type":{"type":"string","enum":["register-extract","official-title","title-plan"],"description":"Which of the title's documents this is. `register-extract` is the full register of the title, carrying its proprietors, charges and restrictions; `official-title` is the official copy of that register; `title-plan` is the plan showing the extent of the property."},"status":{"type":"string","enum":["pending","uploaded","failed"],"description":"How far the document has got: `pending` while it is being prepared, `uploaded` once it can be downloaded, and `failed` if it could not be produced."},"size_bytes":{"type":["number","null"],"description":"Size of the document in bytes. Null while the document is pending or failed."},"content_type":{"type":"string","description":"Media type of the document, for example 'application/pdf'."},"uploaded_at":{"type":["string","null"],"description":"When the document became available, as an ISO 8601 timestamp. Null until it has been uploaded."},"download_url":{"type":["string","null"],"description":"Path for downloading the document, relative to the API root. Null unless `status` is `uploaded`."}},"required":["document_type","status","size_bytes","content_type","uploaded_at","download_url"]},"description":"The documents held for this title deed, each with its current status."}},"required":["object","already_owned","credits_charged","purchase","title_deed","proprietors","documents"]},"TitleDeedPurchasePending":{"type":"object","properties":{"object":{"type":"string","enum":["title_deed_purchase_pending"]},"title_number":{"type":"string","example":"HP343456"},"money_state":{"$ref":"#/components/schemas/MoneyState"},"expected_response_at":{"type":["string","null"],"description":"When HM Land Registry expects to deliver the title, as an ISO 8601 timestamp, or null when no estimate was given. Treat it as an estimate and keep polling past it.","example":"2026-08-21T14:00:00.000Z"},"message":{"type":"string","description":"A description of the pending purchase suitable for showing to a person."}},"required":["object","title_number","money_state","expected_response_at","message"]},"MoneyState":{"type":"string","enum":["charged","not_charged","unknown"],"description":"What this account has been charged for the purchase, stated rather than implied. `charged` means the credits have been taken and the purchase is live, either already delivered or accepted by HM Land Registry for delivery shortly, so a platform reselling it must not refund its own customer. `not_charged` means nothing is held for this attempt, because it was never debited or has been refunded in full, so a refund downstream is safe and a retry starts clean. `unknown` means the outcome could not be established, and the purchase should be held for reconciliation rather than refunded or retried blindly. Responses whose outcome the status code already implies, such as a delivered 200, do not repeat it.","example":"not_charged"},"TitleDeedPurchaseNotFound":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error"]},"code":{"type":"string"},"message":{"type":"string"}},"required":["type","message"]},"money_state":{"$ref":"#/components/schemas/MoneyState"},"purchase_status":{"$ref":"#/components/schemas/PurchaseStatus"},"failure_code":{"type":["string","null"],"description":"Why the purchase did not complete, as a stable code, when this account was refunded. `HMLR_PURCHASE_REJECTED` with a pending-application reason means the title cannot be bought until the application completes, so retrying will fail the same way."},"failure_message":{"type":["string","null"],"description":"The refusal in the words HM Land Registry used, when one was given."}},"required":["error","money_state","purchase_status","failure_code","failure_message"]},"PurchaseStatus":{"type":"string","enum":["refunded","none"],"description":"Why the purchase status GET found no active purchase. `refunded` means this account bought the title and was refunded; `none` means it has never bought it. Both mean `money_state` is `not_charged`, but only `refunded` implies a purchase attempt happened."},"TitleDeedPurchaseError":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error"]},"code":{"type":"string"},"message":{"type":"string"}},"required":["type","message"]},"money_state":{"$ref":"#/components/schemas/MoneyState"}},"required":["error","money_state"]},"TitleDeedAvailabilityResponse":{"type":"object","properties":{"object":{"type":"string","enum":["title_deed_availability"]},"title_number":{"type":"string"},"purchasable":{"type":"boolean","description":"True when a purchase of this title would be accepted today. False means a purchase would be refused and refunded, so check this before buying."},"reason_code":{"type":["string","null"],"enum":["register_unavailable","applications_pending",null],"description":"Why the title cannot be bought, or null when it can. `applications_pending` means an application is lodged against the title and HM Land Registry will not issue a standard official copy until it completes. `register_unavailable` means the register cannot be delivered electronically at all."},"reason":{"type":["string","null"],"description":"The refusal explained in a sentence, or null when the title can be bought."},"title_status":{"type":["string","null"],"description":"The registration status HM Land Registry holds for this title."},"applications_pending":{"type":["boolean","null"],"description":"True when one or more applications are lodged against this title and not yet completed."},"register":{"type":"object","properties":{"availability_code":{"type":["string","null"]},"backdated":{"type":["boolean","null"]}},"required":["availability_code","backdated"]},"title_plan":{"type":"object","properties":{"availability_code":{"type":["string","null"]},"backdated":{"type":["boolean","null"]}},"required":["availability_code","backdated"]}},"required":["object","title_number","purchasable","reason_code","reason","title_status","applications_pending","register","title_plan"]},"TitleDeedApplicationListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["title_deed_application_list"]},"title_number":{"type":"string"},"applications_pending":{"type":"boolean","description":"True when at least one application is lodged against this title. While that is the case a standard official copy cannot be purchased."},"applications":{"type":"array","items":{"$ref":"#/components/schemas/TitleDeedApplication"}}},"required":["object","title_number","applications_pending","applications"]},"TitleDeedApplication":{"type":"object","properties":{"reference":{"type":"string","description":"The reference HM Land Registry allocated to this application."},"type":{"type":"string","description":"What kind of application this is, such as a dealing or a first lease."},"type_code":{"type":"string","description":"The numeric code behind `type`, for callers that prefer to switch on a stable value."},"expedited":{"type":"boolean","description":"True when the applicant has asked HM Land Registry to expedite the application."},"priority_date":{"type":["string","null"],"description":"The date the application takes priority from, where one applies."},"priority_time":{"type":["string","null"]},"priority_start_date":{"type":["string","null"],"description":"Start of the priority period, on a search that carries one."},"priority_end_date":{"type":["string","null"],"description":"End of the priority period, after which the protection lapses."},"applicant":{"type":["string","null"],"description":"Who the application was made for, where it is recorded."},"progress":{"type":["string","null"],"description":"How far HM Land Registry has taken the application, in their own words."},"customer_reference":{"type":["string","null"]},"received_by":{"type":["string","null"],"description":"The channel the application arrived through."},"property_description":{"type":["string","null"],"description":"The part of the property the application concerns, where it names one."},"lodged_by":{"type":["string","null"],"description":"The firm that lodged the application."},"search_certificate_number":{"type":["string","null"]},"search_interest":{"type":["string","null"]},"parent_titles":{"type":["array","null"],"items":{"type":"string"},"description":"Titles this application is being carved out of."},"new_titles":{"type":["array","null"],"items":{"type":"string"},"description":"Titles this application will create, such as a new leasehold title over part of the property."}},"required":["reference","type","type_code","expedited","priority_date","priority_time","priority_start_date","priority_end_date","applicant","progress","customer_reference","received_by","property_description","lodged_by","search_certificate_number","search_interest","parent_titles","new_titles"]},"InsufficientCreditsError":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error"]},"code":{"type":"string","enum":["insufficient_credits"]},"message":{"type":"string"},"current_balance":{"type":"number","description":"Credit balance on the account when the request was made."},"required_credits":{"type":"number","description":"Number of credits the purchase costs."}},"required":["type","code","message","current_balance","required_credits"]},"money_state":{"type":"string","enum":["not_charged"],"description":"Nothing was taken; the debit rolled back when the balance fell short."}},"required":["error","money_state"]},"AsyncPurchaseTitleDeedResponse":{"type":"object","properties":{"object":{"type":"string","enum":["title_purchase_async"]},"title_number":{"type":"string"},"status":{"type":"string","enum":["pending","analysing","complete","failed"]},"already_owned":{"type":"boolean","description":"True when this title had already been purchased on this account, so nothing was charged again."}},"required":["object","title_number","status","already_owned"]},"TitleExtractionPollResponse":{"type":"object","properties":{"object":{"type":"string","enum":["title_extraction"]},"title_number":{"type":"string"},"status":{"type":"string","enum":["pending","analysing","complete","failed"]},"extraction":{"$ref":"#/components/schemas/TitleExtractionPayload"},"failure_code":{"type":["string","null"]},"failure_message":{"type":["string","null"]}},"required":["object","title_number","status","extraction","failure_code","failure_message"]},"TitleExtractionPayload":{"type":["object","null"],"properties":{"titleNumber":{"type":"string","minLength":1},"registerAsOf":{"type":"string","format":"date-time","example":"2026-01-16T09:30:00.000Z","description":"The instant the official copy states it shows the register at (\"shows the entries on the register of title on 17 SEP 2026 at 12:56:56\"), as an ISO 8601 UTC timestamp. Not our fetch clock."},"tenure":{"type":"string","enum":["freehold","leasehold","commonhold"]},"classOfTitle":{"type":["string","null"],"enum":["absolute","good_leasehold","possessory","qualified","other",null],"default":null,"description":"The class of title recorded in the register. `possessory` and `qualified` are material defects a lender will want to see. Null when the register does not state a class."},"qualification":{"type":["string","null"],"default":null,"description":"The qualification entry, quoted verbatim from the register. Null on titles that carry no qualification."},"scheduleOfNoticesOfLeases":{"type":"array","items":{"$ref":"#/components/schemas/TitleScheduleNoticeOfLease"},"default":[],"description":"Leases noted against the title, quoted verbatim from the schedule of notices of leases. Empty when the title has none."},"leaseTermDescription":{"type":"string","minLength":1,"description":"Plain-English summary of the lease term, or a statement that a lease term does not apply on a freehold title."},"currentOwnerDisplay":{"type":"string","minLength":1,"description":"The current owner, formatted as a single line ready to display."},"ownership":{"type":"object","properties":{"proprietors":{"type":"array","items":{"$ref":"#/components/schemas/TitleProprietor"},"minItems":1}},"required":["proprietors"],"additionalProperties":false},"alerts":{"type":"array","items":{"$ref":"#/components/schemas/TitleAlert"},"default":[],"description":"Facts that no single entry states but a buyer must know: an ended lease term, a title divided by floor, a price that is a value, a premium or nominal, a class of title weaker than absolute. Empty when there are none."},"pricePaid":{"$ref":"#/components/schemas/TitlePricePaid"},"propertyRights":{"type":"array","items":{"$ref":"#/components/schemas/TitlePropertyRight"},"description":"Every Property Register entry other than the estate description and the lease particulars: easements, party-wall provisions, exceptions. Empty when the A register has no such entries."},"registeredCharges":{"$ref":"#/components/schemas/RegisteredCharges"},"restrictions":{"type":"array","items":{"$ref":"#/components/schemas/TitleRestriction"}},"covenants":{"type":"array","items":{"$ref":"#/components/schemas/TitleCovenant"}},"notices":{"type":"array","items":{"$ref":"#/components/schemas/TitleNotice"}},"documents":{"type":"array","items":{"$ref":"#/components/schemas/TitleDocumentSummary"},"description":"The title's documents as they stood when the extraction ran. Document uploads run concurrently with extraction, so this is a snapshot: the API overlays the live document rows on every read, and a consumer must never treat a `pending` here as current."},"summaryCounts":{"$ref":"#/components/schemas/TitleSummaryCounts"},"promptVersion":{"type":"string","minLength":1},"extractedAt":{"type":"string","format":"date-time","example":"2026-01-16T09:30:00.000Z"}},"required":["titleNumber","registerAsOf","tenure","leaseTermDescription","currentOwnerDisplay","ownership","pricePaid","propertyRights","registeredCharges","restrictions","covenants","notices","documents","summaryCounts","promptVersion","extractedAt"],"additionalProperties":false},"TitleScheduleNoticeOfLease":{"type":"object","properties":{"rawText":{"type":"string","minLength":1,"description":"The schedule of notices of leases, quoted verbatim from the register."}},"required":["rawText"],"additionalProperties":false},"TitleProprietor":{"type":"object","properties":{"entityType":{"type":"string","enum":["individual","limited_company","llp","corporate_body","local_authority","county_council","registered_society","housing_association","unlimited_company","overseas_company","charity","unknown"]},"proprietorOrder":{"type":"integer","minimum":1,"description":"Position of this proprietor in the proprietorship register, counting from 1.","example":1},"name":{"type":"string","minLength":1,"description":"Name to display for this proprietor: the full name of an individual, or the registered name of a company or trust.","example":"OMIS HOLDINGS LIMITED"},"forenames":{"type":["string","null"]},"surname":{"type":["string","null"]},"companyRegistrationNumber":{"type":["string","null"],"description":"Companies House registration number of the proprietor, where it has one.","example":"12345678"},"overseasRegistrationNumber":{"type":["string","null"],"description":"Registration number recorded for a proprietor registered outside the UK.","example":"FC029423"},"countryIncorporated":{"type":["string","null"],"description":"Country the proprietor is incorporated in.","example":"United Arab Emirates"},"addresses":{"type":"array","items":{"type":"string","minLength":1},"maxItems":3,"description":"Addresses recorded for this proprietor in the register. At most three are held.","example":["3rd Floor, 2 Basil Street, Knightsbridge, London SW3 1AA"]}},"required":["entityType","proprietorOrder","name","forenames","surname","companyRegistrationNumber","overseasRegistrationNumber","countryIncorporated","addresses"],"additionalProperties":false},"TitleAlert":{"type":"object","properties":{"kind":{"type":"string","enum":["lease_term_ended","divided_by_floor","value_not_price","price_covers_other_titles","lease_premium","nominal_price","possessory_title","qualified_title","good_leasehold_title"]},"message":{"type":"string","minLength":20,"description":"Plain-English statement of the fact and why it matters."},"sourceEntryRef":{"type":["string","null"],"minLength":1,"example":"A1"}},"required":["kind","message","sourceEntryRef"],"additionalProperties":false},"TitlePricePaid":{"type":["object","null"],"properties":{"basis":{"type":"string","enum":["price","value","lease_premium"],"default":"price","description":"What the amount is. `price`: the price paid on a sale. `value`: a value stated where no price was paid (a gift, a transfer into joint names); never show it as a price. `lease_premium`: the premium paid on the grant of the lease, not a price on a later sale."},"amountPounds":{"type":"integer","minimum":0,"description":"The price as stated in the register, in whole pounds.","example":492500},"date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2011-07-22","description":"The date the price is stated to have been paid on. Null when the entry states no date (a leasehold grant price, for instance)."},"registrationDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2011-07-22","description":"The date the entry was made in the register (the entry's `(dd.mm.yyyy)` prefix). Null when the entry carries no registration date."},"rawText":{"type":"string","minLength":10,"description":"The entry, quoted verbatim from the register."},"sourceEntryRef":{"type":"string","minLength":1,"example":"B2"}},"required":["amountPounds","date","registrationDate","rawText","sourceEntryRef"],"additionalProperties":false,"description":"The price-paid entry from the Proprietorship Register. Null when the register records none."},"TitlePropertyRight":{"type":"object","properties":{"nature":{"type":"string","enum":["benefit","burden","both","provision"],"description":"`benefit`: a right this land enjoys over other land. `burden`: a right other land enjoys over this land. `both`: the entry grants and reserves. `provision`: a declaration or exception that is neither (a party-wall agreement, an exception from registration, a note that the lessor's title is registered)."},"title":{"type":"string","minLength":1,"description":"Short plain-English label for the entry.","example":"Shared drain and party wall with number 72"},"date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2011-07-22","description":"The date the entry was made in the register (the entry's `(dd.mm.yyyy)` prefix). Null when the entry carries no registration date."},"instrumentDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2011-07-22","description":"The date of the deed the entry refers to (the conveyance, transfer, lease or charge that created it), when the entry states one. Null otherwise. Distinct from `date`, which is when the entry was registered."},"rawText":{"type":"string","minLength":10,"description":"The entry, quoted verbatim from the Property Register."},"whyThisMatters":{"type":"string","minLength":20,"description":"Plain-English explanation of what the entry means for the current owner, written by a language model from the register entry."},"sourceEntryRef":{"type":"string","minLength":1,"example":"A2"}},"required":["nature","title","date","instrumentDate","rawText","whyThisMatters","sourceEntryRef"],"additionalProperties":false},"RegisteredCharges":{"type":"object","properties":{"active":{"type":"array","items":{"$ref":"#/components/schemas/MortgageCharge"}},"discharged":{"type":"array","items":{"$ref":"#/components/schemas/MortgageCharge"}},"other":{"type":"array","items":{"$ref":"#/components/schemas/OtherCharge"}}},"required":["active","discharged","other"],"additionalProperties":false},"MortgageCharge":{"type":"object","properties":{"status":{"type":"string","enum":["active","discharged"]},"chargeHolder":{"$ref":"#/components/schemas/TitleProprietor"},"registrationDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2011-07-22"},"chargeDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2011-07-22"},"dischargedDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2011-07-22","description":"When the charge was discharged, as an ISO 8601 date. Null while `status` is `active`."},"titleAffected":{"type":"string","minLength":1,"description":"Title number this charge affects. It may be this title or a related one.","example":"NGL199903"},"alsoAffectsTitles":{"type":"array","items":{"type":"string","minLength":1},"description":"Other title numbers the same charge is registered against, read from an `affecting also title …` clause. Empty when the charge affects only `titleAffected`.","example":["SH20541"]},"effectOfCharge":{"type":"string","minLength":20,"description":"Plain-English explanation of how this charge affects the owner's freedom to deal with the property, written by a language model from the register entry.","example":"You must obtain written consent from Emirates NDB before any sale or transfer can be registered."},"sourceEntryRef":{"type":"string","minLength":1,"description":"The register entry this charge was read from, so a value can be traced back to the register.","example":"C1"}},"required":["status","chargeHolder","registrationDate","chargeDate","dischargedDate","titleAffected","alsoAffectsTitles","effectOfCharge","sourceEntryRef"],"additionalProperties":false},"OtherCharge":{"type":"object","properties":{"chargeType":{"type":"string","minLength":1,"description":"The kind of charge, as the register labels it.","example":"Rights Reserved to Third Parties"},"date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2011-07-22","description":"The date the entry was made in the register (the entry's `(dd.mm.yyyy)` prefix). Null when the entry carries no registration date."},"instrumentDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2011-07-22","description":"The date of the deed the entry refers to (the conveyance, transfer, lease or charge that created it), when the entry states one. Null otherwise. Distinct from `date`, which is when the entry was registered."},"originalParties":{"type":"array","items":{"type":"string","minLength":1},"description":"The parties the entry names, verbatim, in the order the deed lists them. Empty when the entry names nobody. Never a placeholder: an entry that names parties and reports none here is an extraction defect, not a register fact.","example":["Thomas William Digby","Douglas Burden","Derek John Chamberlain"]},"effectOfCharge":{"type":"string","minLength":20,"description":"Plain-English explanation of what this charge means for the owner, written by a language model from the register entry."},"sourceEntryRef":{"type":"string","minLength":1}},"required":["chargeType","date","instrumentDate","originalParties","effectOfCharge","sourceEntryRef"],"additionalProperties":false},"TitleRestriction":{"type":"object","properties":{"title":{"type":"string","minLength":1,"description":"Short plain-English label for the entry.","example":"Restriction on Disposal"},"date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2011-07-22","description":"The date the entry was made in the register (the entry's `(dd.mm.yyyy)` prefix). Null when the entry carries no registration date."},"instrumentDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2011-07-22","description":"The date of the deed the entry refers to (the conveyance, transfer, lease or charge that created it), when the entry states one. Null otherwise. Distinct from `date`, which is when the entry was registered."},"rawText":{"type":"string","minLength":10,"description":"The legal text, quoted verbatim from the register entry."},"whyThisMatters":{"type":"string","minLength":20,"description":"Plain-English explanation of what the entry means for the current owner, written by a language model from the register entry."},"sourceEntryRef":{"type":"string","minLength":1}},"required":["title","date","instrumentDate","rawText","whyThisMatters","sourceEntryRef"],"additionalProperties":false},"TitleCovenant":{"type":"object","properties":{"title":{"type":"string","minLength":1,"description":"Short plain-English label for the entry.","example":"Restriction on Disposal"},"date":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2011-07-22","description":"The date the entry was made in the register (the entry's `(dd.mm.yyyy)` prefix). Null when the entry carries no registration date."},"instrumentDate":{"type":["string","null"],"pattern":"^\\d{4}-\\d{2}-\\d{2}$","example":"2011-07-22","description":"The date of the deed the entry refers to (the conveyance, transfer, lease or charge that created it), when the entry states one. Null otherwise. Distinct from `date`, which is when the entry was registered."},"rawText":{"type":"string","minLength":10,"description":"The legal text, quoted verbatim from the register entry."},"whyThisMatters":{"type":"string","minLength":20,"description":"Plain-English explanation of what the entry means for the current owner, written by a language model from the register entry."},"sourceEntryRef":{"type":"string","minLength":1}},"required":["title","date","instrumentDate","rawText","whyThisMatters","sourceEntryRef"],"additionalProperties":false},"TitleNotice":{"allOf":[{"$ref":"#/components/schemas/TitleRestriction"},{"type":"object","properties":{"noticeType":{"type":"string","enum":["agreed","unilateral","caution","home_rights","bankruptcy"]},"partyName":{"type":["string","null"]}},"required":["noticeType","partyName"],"additionalProperties":false}]},"TitleDocumentSummary":{"type":"object","properties":{"documentType":{"type":"string","enum":["register-extract","official-title","title-plan"]},"displayName":{"type":"string","minLength":1},"description":{"type":"string","minLength":1},"status":{"type":"string","enum":["pending","uploaded","failed"]},"sizeBytes":{"type":["integer","null"],"minimum":0},"uploadedAt":{"type":["string","null"],"format":"date-time","example":"2026-01-16T09:30:00.000Z"}},"required":["documentType","displayName","description","status","sizeBytes","uploadedAt"],"additionalProperties":false},"TitleSummaryCounts":{"type":"object","properties":{"activeMortgages":{"type":"integer","minimum":0},"dischargedMortgages":{"type":"integer","minimum":0},"otherCharges":{"type":"integer","minimum":0},"restrictions":{"type":"integer","minimum":0},"covenants":{"type":"integer","minimum":0},"notices":{"type":"integer","minimum":0},"propertyRights":{"type":"integer","minimum":0}},"required":["activeMortgages","dischargedMortgages","otherCharges","restrictions","covenants","notices","propertyRights"],"additionalProperties":false},"AirQualityListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/AirQuality"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."},"AirQuality":{"type":"object","properties":{"airQualityId":{"$ref":"#/components/schemas/AirQualityId"},"cellId":{"$ref":"#/components/schemas/AirQualityCellId"},"centroid":{"type":"object","properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"The centre of the cell: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order)."}},"required":["type","coordinates"]},"computedAt":{"type":"string","format":"date-time"},"provenance":{"$ref":"#/components/schemas/Provenance"},"confidence":{"$ref":"#/components/schemas/Confidence"},"summary":{"$ref":"#/components/schemas/AirQualitySummary"},"officialIndices":{"type":"array","items":{"$ref":"#/components/schemas/OfficialIndex"},"description":"Indices published by government bodies, carried alongside the platform score. Cells in Great Britain carry the Daily Air Quality Index (DAQI). Branch on each entry's `system`."},"pollutants":{"$ref":"#/components/schemas/AirQualityPollutants"},"regulatoryZones":{"$ref":"#/components/schemas/AirQualityRegulatoryZones"},"nearestRoad":{"$ref":"#/components/schemas/AirQualityNearestRoad"},"nearestMotorway":{"$ref":"#/components/schemas/AirQualityNearestRoad"},"nearestStation":{"type":["object","null"],"properties":{"siteCode":{"type":"string","description":"The station's site code in the Defra UK-AIR network.","example":"MY1"},"siteName":{"type":"string","description":"Name of the monitoring station.","example":"London Marylebone Road"},"environmentType":{"type":"string","description":"How the station's surroundings are classified, such as 'Urban Background', 'Roadside' or 'Rural Background'.","example":"Urban Background"},"distanceM":{"type":"number","minimum":0,"description":"Distance to the feature, in metres.","example":42.3},"bearingDeg":{"type":"number","minimum":0,"maximum":360,"description":"Direction to the feature, in degrees clockwise from true north. Between 0 and 360.","example":137.5}},"required":["siteCode","siteName","environmentType","distanceM"],"description":"The closest active Defra UK-AIR monitoring station, given for reference. The concentrations here are modelled rather than read off it."},"exposure":{"$ref":"#/components/schemas/AirQualityExposure"},"installations":{"$ref":"#/components/schemas/AirQualityInstallations"},"healthImpact":{"$ref":"#/components/schemas/HealthImpact"},"propertyValueImpact":{"$ref":"#/components/schemas/PropertyValueImpact"}},"required":["airQualityId","cellId","centroid","computedAt","provenance","summary","pollutants"]},"AirQualityId":{"type":"string","pattern":"^aq-cell-\\d+-\\d+-aq-[a-z0-9-]+$","example":"aq-cell-530-180-aq-20260517-04"},"AirQualityCellId":{"type":"string","pattern":"^\\d+:\\d+$","example":"530:180"},"Confidence":{"type":"object","properties":{"level":{"$ref":"#/components/schemas/ConfidenceLevel"},"factors":{"type":"array","items":{"$ref":"#/components/schemas/ConfidenceFactor"},"description":"The individual factors behind the level."}},"required":["level"],"description":"How much confidence to place in this response, and why."},"ConfidenceLevel":{"type":"string","enum":["high","medium","low"],"description":"How much confidence to place in the result."},"ConfidenceFactor":{"type":"object","properties":{"code":{"type":"string","minLength":1,"description":"Stable code identifying the factor, safe to match on.","example":"scotland_no_authoritative_crosswalk"},"severity":{"$ref":"#/components/schemas/ConfidenceFactorSeverity"},"description":{"type":"string","minLength":1,"description":"Human-readable explanation of the factor.","example":"Scotland matches are derived spatially because SEPA publishes no authoritative NIC↔permit crosswalk."}},"required":["code","severity","description"],"description":"One reason the confidence was set where it was."},"ConfidenceFactorSeverity":{"type":"string","enum":["info","warning","blocker"],"description":"How seriously to take the factor: `info` is context only, `warning` means the result should be treated with care, and `blocker` means it should not be relied on."},"AirQualitySummary":{"type":"object","properties":{"score":{"type":"number","description":"The score itself, on the scale given in `scale`.","example":78},"scale":{"$ref":"#/components/schemas/Scale"},"band":{"$ref":"#/components/schemas/AirQualityBand"},"bandReason":{"type":"string","description":"Explanation of why the score falls in this band.","example":"Score 78 falls within the 'good' band (60-79)."},"trend":{"$ref":"#/components/schemas/Trend"},"asOf":{"type":"string","description":"When the score was computed, as an ISO 8601 timestamp.","example":"2026-05-17T12:00:00Z"},"worstPollutant":{"$ref":"#/components/schemas/AirQualityPollutantCode"},"dominantSource":{"$ref":"#/components/schemas/AirQualityDominantSource"},"headline":{"type":"string","description":"One-line plain-English summary of the air quality here, ready to display."}},"required":["score","scale","band","dominantSource","headline"]},"Scale":{"type":"object","properties":{"min":{"type":"number","description":"Lowest value the score can take.","example":0},"max":{"type":"number","description":"Highest value the score can take.","example":100},"higherIsBetter":{"type":"boolean","description":"True when a higher score is the better outcome, false when a lower one is.","example":true},"unit":{"type":"string","description":"Unit the values are expressed in, such as 'µg/m³'. Absent when the score is a bare number.","example":"µg/m³"}},"required":["min","max","higherIsBetter"],"description":"The range a score is measured on, and which end of it is good."},"AirQualityBand":{"type":"string","enum":["very_good","good","moderate","poor","very_poor"]},"Trend":{"type":"object","properties":{"direction":{"$ref":"#/components/schemas/TrendDirection"},"changePerYear":{"type":"number","description":"Change in the score per year, signed to match `direction`.","example":-2.4},"windowYears":{"type":"integer","exclusiveMinimum":0,"description":"Number of years the movement was measured over.","example":5},"significance":{"$ref":"#/components/schemas/TrendSignificance"}},"required":["direction"],"description":"How the score has changed over time."},"TrendDirection":{"type":"string","enum":["up","down","stable"],"description":"Which way the score has moved over time."},"TrendSignificance":{"type":"string","enum":["high","medium","low"],"description":"How significant the movement is, statistically or practically."},"AirQualityPollutantCode":{"type":"string","enum":["no2","pm25","pm10","ozone","so2"],"description":"The pollutant driving the band, where one dominates."},"AirQualityDominantSource":{"type":"string","enum":["roadTransport","domestic","industrial","commercial","agriculture","other"],"description":"The source category contributing the largest share of the pollution here."},"OfficialIndex":{"type":"object","properties":{"system":{"type":"string","minLength":1,"description":"Which published index this value comes from, for example 'DAQI', 'USAQI', 'IMD', 'AQHI', 'CAQI' or 'SAFAR'. Branch on this to interpret `value` and `band`.","example":"DAQI"},"systemVersion":{"type":"string","description":"Edition, year or revision of that index, where it has more than one.","example":"2019"},"jurisdiction":{"type":"string","minLength":1,"description":"Territory the index applies to, as an ISO 3166-1 alpha-2 code with an optional subdivision.","example":"GB"},"value":{"type":"number","description":"The published index value, on the scale given in `scale`.","example":3},"band":{"type":"string","description":"The band label the index itself gives this value.","example":"low"},"scale":{"$ref":"#/components/schemas/Scale"},"reference":{"type":"string","format":"uri","description":"Canonical address at which the index definition is published.","example":"https://uk-air.defra.gov.uk/air-pollution/daqi"}},"required":["system","jurisdiction","value","scale"],"description":"An index value as published by a government body, carried through unchanged, with the scheme and scale needed to read it."},"AirQualityPollutants":{"type":"object","properties":{"no2":{"$ref":"#/components/schemas/AirQualityPollutantBlock"},"pm25":{"$ref":"#/components/schemas/AirQualityPollutantBlock"},"pm10":{"$ref":"#/components/schemas/AirQualityPollutantBlock"},"ozone":{"$ref":"#/components/schemas/AirQualityPollutantBlock"},"so2":{"$ref":"#/components/schemas/AirQualityPollutantBlock"}}},"AirQualityPollutantBlock":{"type":"object","properties":{"pollutant":{"$ref":"#/components/schemas/AirQualityPollutantCode"},"concentration":{"$ref":"#/components/schemas/AirQualityPollutantConcentration"},"band":{"$ref":"#/components/schemas/AirQualityPollutantBand"},"compliance":{"type":"array","items":{"$ref":"#/components/schemas/ComplianceStatus"},"description":"One entry per standard the concentration was checked against, such as 'UK_AQS_2010' and 'WHO_AQG_2021'. Branch on each entry's `framework` to read a particular regulator's judgement."},"trend":{"$ref":"#/components/schemas/Trend"}},"required":["pollutant","concentration","compliance"]},"AirQualityPollutantConcentration":{"type":"object","properties":{"value":{"type":"number","description":"Concentration of the pollutant, in the unit given by `unit`."},"unit":{"type":"string","enum":["ugm3"],"description":"Unit `value` is given in. Always `ugm3`, micrograms per cubic metre."},"basis":{"$ref":"#/components/schemas/AirQualityConcentrationBasis"}},"required":["value","unit","basis"]},"AirQualityConcentrationBasis":{"type":"string","enum":["annual_mean","max_daily_8hr","max_24hr","max_1hr"]},"AirQualityPollutantBand":{"type":"string","enum":["very_good","good","moderate","poor","very_poor"],"description":"The band for this pollutant on its own, worked out independently of the overall band in `summary`."},"ComplianceStatus":{"type":"object","properties":{"framework":{"type":"string","minLength":1,"description":"Which standard the value is checked against, for example 'UK_AQS_2010', 'WHO_AQG_2021', 'EU_2008_50_EC', 'US_NAAQS' or 'EA_NOISE_BS4142'.","example":"UK_AQS_2010"},"frameworkVersion":{"type":"string","description":"Edition or revision of that framework, where it has more than one.","example":"2010_consolidated"},"metric":{"type":"string","minLength":1,"description":"Code for the quantity being checked, for example 'annual_mean_no2' or 'max_daily_8hr_o3'.","example":"annual_mean_no2"},"value":{"type":"number","description":"The measured value, in the unit given by `unit`.","example":38.2},"unit":{"type":"string","minLength":1,"description":"Unit that `value` and `limit` are expressed in, for example 'µg/m³', 'mg/m³' or 'dB(A)'.","example":"µg/m³"},"limit":{"type":"number","description":"The limit this framework sets for the metric, in the same unit as `value`.","example":40},"status":{"$ref":"#/components/schemas/ComplianceStatusValue"},"marginPct":{"type":"number","description":"How far the value sits from the limit, as a percentage of it: (limit - value) / limit * 100. Positive while within the limit, negative once past it.","example":4.5},"exceedanceLevel":{"$ref":"#/components/schemas/ExceedanceLevel"},"reference":{"type":"string","format":"uri","description":"Canonical address at which the framework is published."}},"required":["framework","metric","value","unit","limit","status"],"description":"A value checked against one framework's limit. The same metric may carry several of these, one per framework, and they can disagree."},"ComplianceStatusValue":{"type":"string","enum":["compliant","exceedance","approaching"],"description":"Whether the value sits within the framework's limit, is approaching it, or exceeds it."},"ExceedanceLevel":{"type":"string","enum":["minor","significant","severe"],"description":"How far past the limit the value sits. Given when `status` is `exceedance`."},"AirQualityRegulatoryZones":{"type":"array","items":{"$ref":"#/components/schemas/AirQualityRegulatoryZoneMembership"},"description":"Which regulator-defined zones this location sits in, covering air quality management areas, clean air, ultra low emission and low emission zones, and smoke control areas. Each entry branches on `inside`: read the scheme from `zone.system` when inside, and from `nearest.system` when outside."},"AirQualityRegulatoryZoneMembership":{"oneOf":[{"type":"object","properties":{"inside":{"type":"boolean","enum":[true],"description":"Always `true` on this branch: the location falls inside a zone."},"zone":{"$ref":"#/components/schemas/RegulatoryZone"}},"required":["inside","zone"],"description":"The location is inside a zone of this kind, which is given in full."},{"type":"object","properties":{"inside":{"type":"boolean","enum":[false],"description":"Always `false` on this branch: the location falls outside every zone of this kind."},"nearest":{"type":"object","properties":{"system":{"type":"string","minLength":1,"description":"Which designation scheme this zone belongs to, for example 'AQMA', 'CAZ', 'ULEZ', 'LEZ', 'SMOKE_CONTROL', 'US_NONATTAINMENT', 'DE_UMWELTZONE' or 'FR_CRITAIR'. Branch on this to interpret the rest of the zone.","example":"AQMA"},"systemVersion":{"type":"string","description":"Edition or revision of the scheme, where it has more than one.","example":"2019_revision"},"jurisdiction":{"type":"string","minLength":1,"description":"Territory the zone sits in, as an ISO 3166-1 alpha-2 code with an optional subdivision.","example":"GB-ENG"},"name":{"type":"string","minLength":1,"description":"Name the regulator gave the zone when designating it.","example":"Manchester City Centre AQMA"},"code":{"type":"string","description":"Identifier the regulator issued for the zone.","example":"AQMA_E08000003_01"},"classification":{"type":"string","description":"How the scheme classifies this particular zone, for example 'Class D' for a clean air zone or 'PM2.5 nonattainment' in the US.","example":"Class D"},"authority":{"$ref":"#/components/schemas/AuthorityRef"},"effectiveDate":{"type":"string","description":"When the designation took effect, as an ISO 8601 date.","example":"2022-06-08"},"declaredPollutants":{"type":"array","items":{"type":"string"},"description":"Pollutants the zone was declared for. Present on air-quality schemes only."},"description":{"type":"string","description":"The regulator's own description of the zone."},"reference":{"type":"string","format":"uri","description":"Canonical address of the designation document."},"charges":{"$ref":"#/components/schemas/RegulatoryZoneCharges"},"distanceM":{"type":"number","minimum":0,"description":"Distance to the feature, in metres.","example":42.3},"bearingDeg":{"type":"number","minimum":0,"maximum":360,"description":"Direction to the feature, in degrees clockwise from true north. Between 0 and 360.","example":137.5}},"required":["system","jurisdiction","name","distanceM"],"description":"The closest zone of this kind and how far away it is. Not present in every response."}},"required":["inside"],"description":"The location is outside every zone of this kind, optionally with the closest one."}],"description":"Whether the location falls inside a zone of this kind. Branch on `inside`: when it is `false`, the closest zone may be given instead."},"RegulatoryZone":{"type":"object","properties":{"system":{"type":"string","minLength":1,"description":"Which designation scheme this zone belongs to, for example 'AQMA', 'CAZ', 'ULEZ', 'LEZ', 'SMOKE_CONTROL', 'US_NONATTAINMENT', 'DE_UMWELTZONE' or 'FR_CRITAIR'. Branch on this to interpret the rest of the zone.","example":"AQMA"},"systemVersion":{"type":"string","description":"Edition or revision of the scheme, where it has more than one.","example":"2019_revision"},"jurisdiction":{"type":"string","minLength":1,"description":"Territory the zone sits in, as an ISO 3166-1 alpha-2 code with an optional subdivision.","example":"GB-ENG"},"name":{"type":"string","minLength":1,"description":"Name the regulator gave the zone when designating it.","example":"Manchester City Centre AQMA"},"code":{"type":"string","description":"Identifier the regulator issued for the zone.","example":"AQMA_E08000003_01"},"classification":{"type":"string","description":"How the scheme classifies this particular zone, for example 'Class D' for a clean air zone or 'PM2.5 nonattainment' in the US.","example":"Class D"},"authority":{"$ref":"#/components/schemas/AuthorityRef"},"effectiveDate":{"type":"string","description":"When the designation took effect, as an ISO 8601 date.","example":"2022-06-08"},"declaredPollutants":{"type":"array","items":{"type":"string"},"description":"Pollutants the zone was declared for. Present on air-quality schemes only."},"description":{"type":"string","description":"The regulator's own description of the zone."},"reference":{"type":"string","format":"uri","description":"Canonical address of the designation document."},"charges":{"$ref":"#/components/schemas/RegulatoryZoneCharges"}},"required":["system","jurisdiction","name"],"description":"An area designated by a regulator under a named scheme, with the rules that come with it."},"AuthorityRef":{"type":"object","properties":{"code":{"type":"string","minLength":1,"description":"Official identifier for the authority in its own national registry: an ONS GSS code in the UK, a FIPS code in the US, a NUTS code in the EU, and the local registry code elsewhere.","example":"E08000003"},"name":{"type":"string","minLength":1,"description":"Full name of the authority.","example":"Manchester City Council"},"type":{"$ref":"#/components/schemas/AuthorityType"},"jurisdiction":{"type":"string","minLength":1,"description":"Territory the authority governs, as an ISO 3166-1 alpha-2 code with an optional subdivision.","example":"GB-ENG"},"country":{"type":"string","description":"Name of that country or subdivision, spelled out for display.","example":"England"}},"required":["code","name","type","jurisdiction"],"description":"An administrative authority, named and coded so it can be matched against other registers."},"AuthorityType":{"type":"string","enum":["local_authority","mayoral","national","devolved","supranational","transport_authority","regional"],"description":"Tier of government the authority sits at."},"RegulatoryZoneCharges":{"type":"object","properties":{"year":{"type":"integer","description":"Calendar year these rates are in force for.","example":2026},"model":{"type":"string","enum":["daily","penalty"],"description":"How the scheme charges. Under 'daily' a non-compliant vehicle pays a charge for each day it enters, as in the English clean air zones, the London ULEZ and LEZ, and the Oxford ZEZ. Under 'penalty' there is nothing to pay in advance and a non-compliant entry is fined, as in the Scottish low emission zones."},"rates":{"type":"array","items":{"$ref":"#/components/schemas/RegulatoryZoneChargeRate"},"description":"One line per vehicle class the schedule covers."},"source":{"type":["string","null"],"description":"The authority page these rates were taken from."},"asOf":{"type":["string","null"],"description":"When the rates were last checked against that source, as an ISO 8601 date."}},"required":["year","model","rates"],"description":"What it costs to enter the zone in a non-compliant vehicle. Present only for schemes that levy something, such as clean air zones, the ULEZ, low emission zones, zero emission zones and their international equivalents. Absent for designations that carry no charge, such as air quality management areas and flood zones."},"RegulatoryZoneChargeRate":{"type":"object","properties":{"vehicleClass":{"type":"string","description":"Class of vehicle this rate applies to: car, lgv, taxi, phv, hgv, bus_coach, minibus or motorcycle. The value 'all' is used where the scheme charges per vehicle rather than per class.","example":"car"},"chargeGbp":{"type":["number","null"],"description":"Amount charged in pounds sterling. Null when this class is exempt in this zone.","example":12.5},"complianceStandard":{"type":["string","null"],"description":"Emission standard a vehicle of this class must meet to avoid the charge.","example":"Euro 6 (diesel), Euro 4 (petrol)"},"notes":{"type":["string","null"],"description":"Anything qualifying the rate, such as weight bands, tiering, or a planned escalation."}},"required":["vehicleClass","chargeGbp","complianceStandard"]},"AirQualityNearestRoad":{"type":["object","null"],"properties":{"roadNumber":{"type":"string","description":"The road's number, such as 'A40', 'M25' or 'A100(M)'. Reads 'Unknown' where the road has none."},"roadClass":{"type":"string","description":"How the road is classified in the traffic-count data it came from, for example 'Motorway', 'A' or 'B'. On `nearestMotorway` it always reads 'M'."},"year":{"type":"integer","description":"Year the traffic count this road entry is built from was reported for."},"aadt":{"type":["integer","null"],"description":"Annual average daily traffic: the mean number of motor vehicles a day, from Department for Transport counts. Null where no count is held for this road."},"aadtBreakdown":{"type":["object","null"],"properties":{"cars":{"type":["integer","null"]},"lgv":{"type":["integer","null"]},"hgv":{"type":["integer","null"]},"bus":{"type":["integer","null"]},"motorcycle":{"type":["integer","null"]}},"required":["cars","lgv","hgv","bus","motorcycle"],"description":"The same daily traffic count split by vehicle class. Each class is null where the count omits it."},"roadside":{"type":"object","properties":{"no2Ugm3":{"type":["number","null"]},"pm25Ugm3":{"type":["number","null"]},"pm10Ugm3":{"type":["number","null"]}},"required":["no2Ugm3","pm25Ugm3","pm10Ugm3"],"description":"Pollutant concentrations at this road's kerbside, in micrograms per cubic metre. Each is null where the source carries no value."},"distanceM":{"type":"number","minimum":0,"description":"Distance to the feature, in metres.","example":42.3},"bearingDeg":{"type":"number","minimum":0,"maximum":360,"description":"Direction to the feature, in degrees clockwise from true north. Between 0 and 360.","example":137.5}},"required":["roadNumber","roadClass","year","roadside","distanceM"]},"AirQualityExposure":{"type":"object","properties":{"band":{"$ref":"#/components/schemas/AirQualityExposureBand"},"decayed":{"$ref":"#/components/schemas/AirQualityDecayedExposure"},"withinRadiusCount":{"type":"integer"},"radiusM":{"type":"integer"}},"required":["band","withinRadiusCount","radiusM"]},"AirQualityExposureBand":{"type":"string","enum":["negligible","low","moderate","high"]},"AirQualityDecayedExposure":{"type":"object","properties":{"no2":{"type":"object","properties":{"totalAtCentroid":{"type":"number"},"incrementUgm3":{"type":"number"},"decayFraction":{"type":"number"},"model":{"type":"string"}},"required":["totalAtCentroid","incrementUgm3","decayFraction","model"]},"pm25":{"type":"object","properties":{"totalAtCentroid":{"type":"number"},"incrementUgm3":{"type":"number"},"decayFraction":{"type":"number"},"model":{"type":"string"}},"required":["totalAtCentroid","incrementUgm3","decayFraction","model"]},"pm10":{"type":"object","properties":{"totalAtCentroid":{"type":"number"},"incrementUgm3":{"type":"number"},"decayFraction":{"type":"number"},"model":{"type":"string"}},"required":["totalAtCentroid","incrementUgm3","decayFraction","model"]},"ozone":{"type":"object","properties":{"totalAtCentroid":{"type":"number"},"incrementUgm3":{"type":"number"},"decayFraction":{"type":"number"},"model":{"type":"string"}},"required":["totalAtCentroid","incrementUgm3","decayFraction","model"]},"so2":{"type":"object","properties":{"totalAtCentroid":{"type":"number"},"incrementUgm3":{"type":"number"},"decayFraction":{"type":"number"},"model":{"type":"string"}},"required":["totalAtCentroid","incrementUgm3","decayFraction","model"]}}},"AirQualityInstallations":{"type":"object","properties":{"withinRadius":{"type":"object","properties":{"count":{"type":"integer"},"radiusM":{"type":"integer"}},"required":["count","radiusM"]},"nearby":{"type":"object","properties":{"radiusM":{"type":"number","exclusiveMinimum":0,"description":"Radius searched around the requested location, in metres.","example":5000},"capacity":{"type":"integer","exclusiveMinimum":0,"description":"Maximum number of features `items` can hold. Any beyond this are not returned.","example":10},"count":{"type":"integer","minimum":0,"description":"How many features matched within the radius, counted before the cap was applied.","example":14},"capped":{"type":"boolean","description":"True when more features matched than `capacity` allows, so `items` is a shortened list.","example":true},"items":{"type":"array","items":{"type":"object","properties":{"permitReference":{"type":"string","description":"The installation's permit reference with its regulator."},"operator":{"type":["string","null"]},"sector":{"type":["string","null"]},"regulator":{"$ref":"#/components/schemas/Regulator"},"compliance":{"type":"array","items":{},"description":"Compliance assessments the regulator has recorded against this installation, each tagged with the framework it was made under."},"distanceM":{"type":"number","minimum":0,"description":"Distance to the feature, in metres.","example":42.3},"bearingDeg":{"type":"number","minimum":0,"maximum":360,"description":"Direction to the feature, in degrees clockwise from true north. Between 0 and 360.","example":137.5}},"required":["permitReference","operator","sector","regulator","distanceM"]},"description":"The matching features, nearest first, each with its distance."}},"required":["radiusM","capacity","count","capped","items"],"description":"The nearest features within a radius, capped at a fixed number and reporting how many matched."},"topReleases":{"type":"array","items":{"$ref":"#/components/schemas/AirQualityTopRelease"}}},"required":["withinRadius","topReleases"]},"Regulator":{"type":"object","properties":{"code":{"type":"string","minLength":1,"description":"Short code for the regulator, for example 'EA', 'SEPA', 'NRW', 'NIEA', 'EPA', 'ARPA_LOM' or 'UBA'.","example":"EA"},"name":{"type":"string","minLength":1,"description":"Full name of the regulator.","example":"Environment Agency"},"jurisdiction":{"type":"string","minLength":1,"description":"Territory the regulator operates in, as an ISO 3166-1 alpha-2 code with an optional subdivision.","example":"GB-ENG"},"domains":{"type":"array","items":{"$ref":"#/components/schemas/RegulatoryDomain"},"minItems":1,"description":"Subject areas this regulator has statutory powers over. At least one is always present."},"url":{"type":"string","format":"uri","description":"The regulator's public website.","example":"https://www.gov.uk/government/organisations/environment-agency"}},"required":["code","name","jurisdiction","domains"],"description":"A statutory regulator, named and coded so it can be matched against other registers."},"RegulatoryDomain":{"type":"string","enum":["air_quality","water","industrial_emissions","waste","noise","planning","flood","education","health","transport","energy"],"description":"A subject area a regulator has statutory powers over."},"AirQualityTopRelease":{"type":"object","properties":{"pollutantCode":{"type":"string"},"totalKgYr":{"type":"number"},"facilities":{"type":"integer"},"reportingYear":{"type":"integer"}},"required":["pollutantCode","totalKgYr","facilities","reportingYear"]},"HealthImpact":{"type":"object","properties":{"severity":{"$ref":"#/components/schemas/HealthImpactSeverity"},"generalAdvice":{"type":"string","minLength":1,"description":"Guidance for the general population.","example":"Outdoor air quality is generally acceptable; no precautions required."},"atRiskGroups":{"type":"array","items":{"$ref":"#/components/schemas/AtRiskGroup"},"description":"The groups at greater risk under these conditions."},"atRiskAdvice":{"type":"string","minLength":1,"description":"Guidance for the groups listed in `atRiskGroups`.","example":"People with respiratory conditions may notice mild irritation during prolonged outdoor activity."},"mechanism":{"type":"string","description":"How the hazard affects the body, in clinical terms.","example":"Fine particulates penetrate alveolar membranes and trigger systemic inflammatory response."},"evidenceLevel":{"$ref":"#/components/schemas/HealthEvidenceLevel"},"references":{"type":"array","items":{"type":"string","format":"uri"},"description":"Links to the studies or official guidance this advice rests on."}},"required":["severity","generalAdvice","atRiskGroups","atRiskAdvice","evidenceLevel"],"description":"What the air quality here means for health: how serious it is, who is most affected, and what to do. Included by default."},"HealthImpactSeverity":{"type":"string","enum":["negligible","low","moderate","high","severe"],"description":"How serious the effect on health is."},"AtRiskGroup":{"type":"string","enum":["children","infants","elderly","pregnant","respiratory_conditions","cardiovascular_conditions","immunocompromised","outdoor_workers"],"description":"A group of people more affected by this hazard than the general population."},"HealthEvidenceLevel":{"type":"string","enum":["established","emerging","indicative"],"description":"How strong the evidence behind this guidance is."},"PropertyValueImpact":{"type":"object","properties":{"valueImpact":{"$ref":"#/components/schemas/ValueImpact"},"liquidity":{"$ref":"#/components/schemas/LiquidityImpact"},"framework":{"type":"string","minLength":1,"description":"Which policy framework this assessment as a whole rests on, for example 'NPPF_Ch15'.","example":"NPPF_Ch15"},"considerations":{"type":"array","items":{"$ref":"#/components/schemas/PlanningConsideration"},"description":"The planning policy points this risk raises."},"mitigations":{"type":"array","items":{"$ref":"#/components/schemas/MitigationMeasure"},"description":"Measures a developer or occupier can take to reduce the risk."},"insurance":{"$ref":"#/components/schemas/InsuranceImpact"},"lenderImpact":{"$ref":"#/components/schemas/LenderImpact"}},"required":["valueImpact","framework","considerations","mitigations"],"description":"How the air quality here is expected to bear on property value, saleability, insurance and lending. Included by default."},"ValueImpact":{"type":"string","enum":["none","negligible","minor","moderate","major"],"description":"How much the risk is expected to move the value of a property."},"LiquidityImpact":{"type":"string","enum":["no_change","slower","much_slower"],"description":"How much longer the risk is expected to make a property take to sell."},"PlanningConsideration":{"type":"object","properties":{"topic":{"type":"string","minLength":1,"description":"What the consideration covers.","example":"Air Quality Assessment"},"required":{"type":"boolean","description":"True when a development here must address this consideration.","example":true},"framework":{"type":"string","minLength":1,"description":"Which policy framework the consideration comes from, for example 'NPPF_Ch15', 'PPG_Noise' or 'PPG_Flood_Risk'.","example":"NPPF_Ch15"},"description":{"type":"string","minLength":1,"description":"Human-readable explanation of the consideration.","example":"An Air Quality Assessment will likely be required as the site is within an AQMA."},"reference":{"type":"string","format":"uri","description":"Canonical address of the framework document."}},"required":["topic","required","framework","description"],"description":"A planning policy point this risk raises for a development."},"MitigationMeasure":{"type":"object","properties":{"category":{"type":"string","minLength":1,"description":"Kind of measure, for example 'ventilation', 'glazing', 'barriers' or 'raised_floor'.","example":"ventilation"},"description":{"type":"string","minLength":1,"description":"What the measure involves.","example":"Mechanical ventilation with PM2.5 filtration to reduce indoor exposure."},"estimatedCostBand":{"$ref":"#/components/schemas/CostBand"},"effectiveness":{"$ref":"#/components/schemas/Effectiveness"}},"required":["category","description"],"description":"A measure that can be taken to reduce the risk."},"CostBand":{"type":"string","enum":["low","medium","high"]},"Effectiveness":{"type":"string","enum":["low","medium","high"]},"InsuranceImpact":{"type":"object","properties":{"premiumImpact":{"$ref":"#/components/schemas/InsurancePremiumImpact"},"availability":{"$ref":"#/components/schemas/InsuranceAvailability"},"notes":{"type":"string","description":"Anything qualifying the insurance position."}},"required":["premiumImpact","availability"],"description":"What the risk means for insuring the property."},"InsurancePremiumImpact":{"type":"string","enum":["none","minor","moderate","major"],"description":"How much the risk is expected to push up an insurance premium."},"InsuranceAvailability":{"type":"string","enum":["standard","specialist","restricted"],"description":"How readily cover can be bought for this risk: on standard terms, from specialist insurers only, or restricted."},"LenderImpact":{"type":"string","enum":["none","some_caution","high_caution","refused"],"description":"How mortgage lenders typically treat the risk, from no concern through to refusing to lend."},"AirQualityQueryRequest":{"type":"object","properties":{"area":{"type":"array","items":{"$ref":"#/components/schemas/AirQualityAreaFilter"},"minItems":1,"maxItems":10,"description":"The areas to search, between one and ten of them. Cells matching any of the areas are returned, deduplicated by `airQualityId`."},"snapshotId":{"$ref":"#/components/schemas/AirQualitySnapshotId"},"filters":{"$ref":"#/components/schemas/AirQualityFilters"},"sort":{"type":"array","items":{"$ref":"#/components/schemas/AirQualitySortField"},"maxItems":3,"description":"How to order the results, up to three keys applied in turn. By default, nearest first when the area is a point, postcode or outward code, and lowest score first otherwise."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25},"offset":{"type":"integer","minimum":0,"maximum":10000,"default":0},"attributes":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Which top-level attributes to return, as a comma-separated string or an array, to keep light queries small. `airQualityId`, `cellId`, `centroid` and `computedAt` are always returned. Omit it for the standard set: `summary`, `officialIndices`, `pollutants`, `regulatoryZones`, `provenance`, `healthImpact` and `propertyValueImpact`. `nearestRoad`, `nearestMotorway` and `installations` are returned only on licences carrying the `airQualityPremium` permission.","example":"summary,pollutants,regulatoryZones,provenance"},"track":{"type":"boolean","default":false,"description":"Has no effect on the response or on how the request is billed."}},"required":["area"]},"AirQualityAreaFilter":{"oneOf":[{"$ref":"#/components/schemas/AirQualityPointAreaFilter"},{"$ref":"#/components/schemas/AirQualityPostcodeAreaFilter"},{"$ref":"#/components/schemas/AirQualityOutcodeAreaFilter"},{"$ref":"#/components/schemas/AirQualityBboxAreaFilter"},{"$ref":"#/components/schemas/AirQualityPolygonAreaFilter"},{"$ref":"#/components/schemas/AirQualityMultiPolygonAreaFilter"}],"discriminator":{"propertyName":"type","mapping":{"point":"#/components/schemas/AirQualityPointAreaFilter","postcode":"#/components/schemas/AirQualityPostcodeAreaFilter","outcode":"#/components/schemas/AirQualityOutcodeAreaFilter","boundingBox":"#/components/schemas/AirQualityBboxAreaFilter","polygon":"#/components/schemas/AirQualityPolygonAreaFilter","multipolygon":"#/components/schemas/AirQualityMultiPolygonAreaFilter"}}},"AirQualityPointAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["point"]},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"The point to search from: latitude first, then longitude, in WGS84 decimal degrees. This is the reverse of the GeoJSON order used by geometry fields.","example":[51.5074,-0.1278]},"radius":{"type":"integer","minimum":0,"maximum":50000,"default":0,"description":"Radius to search around the point, in metres. 0 returns the single nearest cell; any larger value returns every cell whose centre falls inside it. Defaults to 0. Maximum 50000."}},"required":["type","coordinates"]},"AirQualityPostcodeAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["postcode"]},"value":{"type":"string","pattern":"^[A-Z]{1,2}[0-9][0-9A-Z]?\\s?[0-9][A-Z]{2}$","description":"A full UK postcode. The space is optional and case is not significant; the value is returned upper-cased.","example":"SW1A 1AA"},"radius":{"type":"integer","minimum":0,"maximum":50000,"default":0,"description":"Radius to search around the centre of the postcode, in metres. 0 returns the single nearest cell. Defaults to 0. Maximum 50000."}},"required":["type","value"]},"AirQualityOutcodeAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["outcode"]},"value":{"type":"string","pattern":"^[A-Z]{1,2}[0-9][0-9A-Z]?(\\s?[0-9][A-Z]{2})?$","description":"The outward code to search, meaning the first part of a postcode, such as `SW1A` or `M1`. Cells within 5 km of its centre are returned.","example":"SW1"}},"required":["type","value"]},"AirQualityBboxAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["boundingBox"]},"southWest":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"The south-west corner: latitude first, then longitude, in WGS84 decimal degrees. This is the reverse of the GeoJSON order used by geometry fields.","example":[51.4,-0.5]},"northEast":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"The north-east corner: latitude first, then longitude, in WGS84 decimal degrees.","example":[51.6,0.1]}},"required":["type","southWest","northEast"]},"AirQualityPolygonAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"description":"Rings of the polygon to search, each point given as latitude first, then longitude, in WGS84 decimal degrees. This is the reverse of the GeoJSON order used by geometry fields. Give the outer ring first; any further rings are holes, and each ring's first and last point must match.","example":[[[51.5074,-0.1278],[51.508,-0.128],[51.507,-0.1275],[51.5074,-0.1278]]]}},"required":["type","coordinates"]},"AirQualityMultiPolygonAreaFilter":{"type":"object","properties":{"type":{"type":"string","enum":["multipolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}},"description":"The polygons to search, each given as rings of points with latitude first, then longitude, in WGS84 decimal degrees. This is the reverse of the GeoJSON order used by geometry fields."}},"required":["type","coordinates"]},"AirQualitySnapshotId":{"type":"string","pattern":"^aq-[a-z0-9-]+$","example":"aq-20260517-04","description":"Pin the request to one published snapshot so repeated calls read the same data. When omitted the latest published snapshot is used, and either way the snapshot read is reported in `provenance.snapshotId`."},"AirQualityFilters":{"type":"object","properties":{"band":{"type":"array","items":{"type":"string","enum":["very_good","good","moderate","poor","very_poor"]},"description":"Return only cells in one of these bands."},"dominantSource":{"type":"array","items":{"type":"string","enum":["roadTransport","domestic","industrial","commercial","agriculture","other"]},"description":"Return only cells whose largest pollution source is one of these."},"insideAqma":{"type":"boolean","description":"Set true to return only cells inside an air quality management area, or false for only those outside one."},"insideVehicleEmissionZone":{"type":"boolean","description":"Set true to return only cells inside a clean air, ultra low emission or low emission zone, or false for only those outside one."},"scoreMin":{"type":"integer","minimum":0,"maximum":100,"description":"Lowest score to return, on the 0 to 100 scale where a higher score is better air quality."},"scoreMax":{"type":"integer","minimum":0,"maximum":100,"description":"Highest score to return, on the 0 to 100 scale where a higher score is better air quality."}}},"AirQualitySortField":{"type":"object","properties":{"field":{"type":"string","enum":["score","band","distanceM"]},"order":{"type":"string","enum":["asc","desc"],"default":"asc"}},"required":["field"]},"AirQualityPointResponse":{"allOf":[{"$ref":"#/components/schemas/AirQuality"},{"type":"object","properties":{"coordinate":{"$ref":"#/components/schemas/AirQualityCoordinate"},"decay":{"$ref":"#/components/schemas/AirQualityDecay"}},"required":["coordinate","decay"]}]},"AirQualityCoordinate":{"type":"object","properties":{"lat":{"type":"number","minimum":49,"maximum":61,"description":"Latitude in WGS84 decimal degrees. Between 49 and 61."},"lon":{"type":"number","minimum":-9,"maximum":2,"description":"Longitude in WGS84 decimal degrees. Between -9 and 2."}},"required":["lat","lon"]},"AirQualityDecay":{"type":"object","properties":{"applied":{"type":"boolean","enum":[true],"description":"Always `true`: every response carries this block. Read `model` to see whether an overlay was actually applied."},"model":{"type":"string","description":"Identifier of the model used. Reads `passthrough` when the request switched the overlay off, in which case the cell values are returned unchanged."},"modelVersion":{"type":"string","description":"Semantic version of that model."},"calibration":{"$ref":"#/components/schemas/AirQualityDecayCalibration"},"calculation":{"type":"object","properties":{"pollutants":{"type":"object","properties":{"no2":{"$ref":"#/components/schemas/AirQualityDecayPollutantBreakdown"},"pm25":{"$ref":"#/components/schemas/AirQualityDecayPollutantBreakdown"},"pm10":{"$ref":"#/components/schemas/AirQualityDecayPollutantBreakdown"},"ozone":{"$ref":"#/components/schemas/AirQualityDecayPollutantBreakdown"},"so2":{"$ref":"#/components/schemas/AirQualityDecayPollutantBreakdown"}},"description":"The step-by-step calculation for each pollutant. Present only when `options.explain` was set on a licence carrying the `airQualityPremium` permission."}},"required":["pollutants"]}},"required":["applied","model","modelVersion","calibration"]},"AirQualityDecayCalibration":{"type":"object","properties":{"fittedAt":{"type":"string","description":"When the model was last fitted, as an ISO 8601 date. Reads `n/a` when no overlay was applied."},"groundTruthSource":{"type":"string","description":"Identifier of the ground-truth data the model was fitted against."},"stations":{"type":"integer","description":"Number of monitoring stations the fit used."},"residualStats":{"type":"object","additionalProperties":{"type":"object","properties":{"stddev":{"type":"number","description":"Standard deviation of the fit's residuals, in micrograms per cubic metre."},"ci95Pct":{"type":"number","description":"Width of the 95% confidence interval, as a percentage of a typical urban annual mean."}},"required":["stddev","ci95Pct"]},"description":"How far the fitted model missed the ground truth by, given per pollutant."}},"required":["fittedAt","groundTruthSource","stations","residualStats"]},"AirQualityDecayPollutantBreakdown":{"type":"object","properties":{"background":{"type":"number","description":"The 1 km cell background the calculation starts from, in micrograms per cubic metre."},"roadContribution":{"type":"number","description":"How much the nearest road adds, in micrograms per cubic metre."},"motorwayContribution":{"type":"number","description":"How much the nearest motorway adds, in micrograms per cubic metre."},"installationContribution":{"type":"number","description":"How much nearby regulated installations add between them, in micrograms per cubic metre."},"zoneModifier":{"type":"number","description":"Adjustment made for the zones containing the point, in micrograms per cubic metre."},"total":{"type":"number","description":"The resulting concentration at the requested coordinate, in micrograms per cubic metre."},"decayInputs":{"type":"object","properties":{"roadDistanceM":{"type":["number","null"]},"roadAadt":{"type":["number","null"]},"roadClass":{"type":["string","null"]},"decayLength":{"type":["number","null"]}},"required":["roadDistanceM","roadAadt","roadClass","decayLength"]}},"required":["background","roadContribution","motorwayContribution","installationContribution","zoneModifier","total","decayInputs"]},"AirQualityPointRequest":{"type":"object","properties":{"coordinate":{"$ref":"#/components/schemas/AirQualityCoordinate"},"attributes":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Which top-level attributes to return, as a comma-separated string or an array. Omit it for the standard set: `summary`, `officialIndices`, `pollutants`, `regulatoryZones`, `nearestStation`, `provenance`, `healthImpact` and `propertyValueImpact`. `nearestRoad`, `nearestMotorway` and `installations` are returned only on licences carrying the `airQualityPremium` permission."},"snapshotId":{"type":"string","description":"Pin the request to one published snapshot so repeated calls read the same data. When omitted the latest published snapshot is used, and either way the snapshot read is reported in `provenance.snapshotId`."},"options":{"$ref":"#/components/schemas/AirQualityPointOptions"},"track":{"type":"boolean","default":false,"description":"Has no effect on the response or on how the request is billed."}},"required":["coordinate"]},"AirQualityPointOptions":{"type":"object","properties":{"decay":{"type":"boolean","default":true,"description":"Whether to adjust the cell's concentrations to the exact coordinate. Defaults to true; set it false to read the 1 km cell values unchanged."},"decayModel":{"type":"string","enum":["v1"],"default":"v1","description":"Which decay model to apply. `v1`, the only value today, adjusts the cell background for distance from the nearest road and motorway, nearby regulated installations, and the zones containing the point. Defaults to `v1`. The response's `decay.calibration` block reports how it was fitted."},"explain":{"type":"boolean","default":false,"description":"Include the per-pollutant calculation trail in `decay.calculation`. Defaults to false, and it is returned only on licences carrying the `airQualityPremium` permission."}}},"FloodRiskPoint":{"type":"object","properties":{"floodRiskId":{"type":"string","description":"Stable identifier for this assessment, built from the data version and the coordinate, so the same request returns the same id."},"coordinate":{"$ref":"#/components/schemas/FloodRiskCoordinate"},"dataAvailability":{"$ref":"#/components/schemas/FloodDataAvailability"},"summary":{"$ref":"#/components/schemas/FloodRiskSummary"},"riversAndSeaRisk":{"$ref":"#/components/schemas/FloodRiversAndSeaRisk"},"surfaceWaterRisk":{"$ref":"#/components/schemas/FloodSurfaceWaterRisk"},"planning":{"$ref":"#/components/schemas/FloodPlanning"},"defences":{"$ref":"#/components/schemas/FloodDefence"},"climate2080":{"$ref":"#/components/schemas/FloodClimate2080"},"provenance":{"$ref":"#/components/schemas/Provenance"}},"required":["floodRiskId","coordinate","dataAvailability","summary","riversAndSeaRisk","surfaceWaterRisk","provenance"]},"FloodRiskCoordinate":{"type":"object","properties":{"lat":{"type":"number","minimum":49,"maximum":61,"description":"Latitude in WGS84 decimal degrees. Between 49 and 61."},"lon":{"type":"number","minimum":-9,"maximum":2,"description":"Longitude in WGS84 decimal degrees. Between -9 and 2."}},"required":["lat","lon"]},"FloodDataAvailability":{"type":"string","enum":["assessed","assessed_no_modelled_risk","not_assessed","out_of_coverage","partial_query_failure"]},"FloodRiskSummary":{"type":"object","properties":{"overallRiskLevel":{"$ref":"#/components/schemas/FloodRiskLevel"},"primarySource":{"$ref":"#/components/schemas/FloodPrimarySource"},"countryCode":{"type":["string","null"],"enum":["ENG","SCO","WAL",null]},"label":{"type":"string"}},"required":["overallRiskLevel","primarySource","countryCode","label"]},"FloodRiskLevel":{"type":["string","null"],"enum":["very_low","low","medium","high",null]},"FloodPrimarySource":{"type":["string","null"],"enum":["rivers_sea","surface_water",null]},"FloodRiversAndSeaRisk":{"type":["object","null"],"properties":{"riskLevel":{"$ref":"#/components/schemas/FloodRiskLevel"},"probability":{"$ref":"#/components/schemas/FloodProbability"},"maxDepthMetres":{"type":["number","null"],"description":"Deepest water the models show at this point if it does flood, in metres. Null where depth has not been modelled here."},"depthImpact":{"type":["string","null"],"description":"What that depth would mean in practice, in plain English, such as 'Waist deep' or 'Above head height'. Null when no depth is modelled."}},"required":["riskLevel","maxDepthMetres","depthImpact"]},"FloodProbability":{"type":"object","properties":{"annualPercentage":{"type":"number","minimum":0,"maximum":100,"description":"Chance of flooding in any one year, as a percentage. 3.3 is about a 1-in-30 chance. Between 0 and 100."},"returnPeriod":{"type":"number","minimum":1,"description":"The same chance expressed as a return period in years: 30 means about a 1-in-30 chance each year."},"description":{"type":"string","description":"The annual chance written out in plain English, such as 'about a 1-in-30 chance each year'."}},"required":["annualPercentage","returnPeriod","description"]},"FloodSurfaceWaterRisk":{"type":["object","null"],"properties":{"riskLevel":{"$ref":"#/components/schemas/FloodRiskLevel"},"probability":{"$ref":"#/components/schemas/FloodProbability"},"hazardRating":{"$ref":"#/components/schemas/FloodHazardRating"},"velocityMps":{"type":["number","null"]}},"required":["riskLevel","hazardRating","velocityMps"]},"FloodHazardRating":{"type":["string","null"],"enum":["low","moderate","significant","extreme",null]},"FloodPlanning":{"type":"object","properties":{"floodZone":{"$ref":"#/components/schemas/FloodZone"},"fraRequired":{"type":"boolean"},"sequentialTestRequired":{"type":"boolean"},"exceptionTestMayApply":{"type":"boolean"}},"required":["floodZone","fraRequired","sequentialTestRequired","exceptionTestMayApply"]},"FloodZone":{"type":"string","enum":["1","2","3a","3b"]},"FloodDefence":{"type":"object","properties":{"hasDefencesNearby":{"type":"boolean"},"nearbyCount":{"type":"integer","minimum":0},"nearestDefence":{"$ref":"#/components/schemas/FloodNearestDefence"},"withinDefendedArea":{"type":["object","null"],"properties":{"defendsAgainst":{"type":"string","enum":["river","sea"]},"standardOfProtectionYears":{"type":"number"}},"required":["defendsAgainst","standardOfProtectionYears"]},"residualRiskNote":{"type":"string"}},"required":["hasDefencesNearby","nearbyCount","nearestDefence","withinDefendedArea","residualRiskNote"]},"FloodNearestDefence":{"type":["object","null"],"properties":{"defenceType":{"type":"string","description":"The kind of defence, such as 'Raised embankment' or 'Flood wall'. Reads 'Flood defence' where the source records no more specific type."},"distanceMetres":{"type":"number"},"watercourseName":{"type":["string","null"]},"standardOfProtectionYears":{"type":["number","null"]},"condition":{"type":"string","enum":["good","fair","poor","unknown"]},"maintainedBy":{"type":"string"}},"required":["defenceType","distanceMetres","watercourseName","standardOfProtectionYears","condition","maintainedBy"]},"FloodClimate2080":{"type":"object","properties":{"projectedRiskLevel":{"$ref":"#/components/schemas/FloodRiskLevel"},"direction":{"type":"string","enum":["increased","unchanged","decreased"]}},"required":["projectedRiskLevel","direction"]},"FloodRiskPointRequest":{"type":"object","properties":{"coordinate":{"$ref":"#/components/schemas/FloodRiskCoordinate"},"scenario":{"$ref":"#/components/schemas/FloodScenario"},"track":{"type":"boolean","default":false,"description":"Has no effect on the response or on how the request is billed."}},"required":["coordinate"]},"FloodScenario":{"type":"string","enum":["present","cc_2080","both"],"default":"both","description":"Which scenarios to assess: `present` for today, `cc_2080` for the 2080 climate projection, or `both`. Defaults to `both`."},"TransactionsListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Transaction"}},"has_more":{"type":"boolean","description":"True when further results exist beyond this page."},"next_cursor":{"type":["string","null"],"description":"Opaque cursor for the next page. Null when this is the last page."}},"required":["object","data","has_more","next_cursor"],"description":"One page of transactions, with the cursor needed to fetch the next."},"Transaction":{"type":"object","properties":{"object":{"type":"string","enum":["transaction"],"description":"Object type discriminator. Always `transaction`."},"id":{"type":"string","description":"Identifier for this transaction, formed as `{country}:{provider}:{externalId}`. Pass it to the by-id endpoint to fetch the record again.","example":"gb:hmlr_ppd:{0A1B2C3D-...}"},"country":{"type":"string","description":"Territory the transaction took place in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"kind":{"type":"string","enum":["sale","lease_grant"],"description":"What the record represents: a completed sale and transfer, or the grant of a new lease. A lease grant also carries the `lease` object."},"price":{"$ref":"#/components/schemas/TransactionPrice"},"date":{"type":"string","format":"date-time","description":"When the sale completed, or when the lease grant was registered, as an ISO 8601 timestamp.","example":"2024-01-15T10:30:00Z"},"tenure":{"type":["string","null"],"enum":["freehold","leasehold",null],"description":"Tenure of the interest the transaction covers. Null when the source did not record a usable tenure."},"propertyType":{"type":"string","description":"Type of property, normalised onto a shared taxonomy. `other` covers a source type outside that taxonomy, and `unknown` a source that gave none.","example":"flat"},"newBuild":{"type":["boolean","null"],"description":"True when the property was newly built at the time of the transaction. Null when the source does not record it."},"lease":{"type":["object","null"],"properties":{"termText":{"type":["string","null"],"description":"The lease term exactly as the register records it, for example '125 years from 11 February 2004'."},"termYears":{"type":["number","null"],"description":"Length of the lease term in years, where the term gives one."},"startDate":{"type":["string","null"],"format":"date-time","description":"When the lease term starts, as an ISO 8601 timestamp, where the term gives one.","example":"2024-01-15T10:30:00Z"}},"description":"Detail of the lease term. Present only when `kind` is `lease_grant`."},"address":{"$ref":"#/components/schemas/TransactionAddress"},"location":{"$ref":"#/components/schemas/TransactionLocation"},"provider":{"type":"string","description":"Stable code identifying the registry the record came from, safe to match on. Returned only to API keys entitled to source data."},"sources":{"type":"array","items":{"type":"string"},"description":"Stable codes for every data source behind the record, safe to match on. Returned only to API keys entitled to source data."}},"description":"A property transaction, normalised to one shape across registries. Monetary values are in the minor unit of their currency."},"TransactionPrice":{"type":"object","properties":{"amount":{"type":"integer","description":"Amount paid, in the minor unit of `currency`, so pence for GBP. Divide by 100 for pounds.","example":22900000},"currency":{"type":"string","description":"The currency the amount is in, as an ISO 4217 code.","example":"GBP"}}},"TransactionAddress":{"type":"object","properties":{"paon":{"type":["string","null"],"description":"Primary addressable object name: the building number or name."},"saon":{"type":["string","null"],"description":"Secondary addressable object name: the flat or unit within the building."},"street":{"type":["string","null"]},"locality":{"type":["string","null"]},"town":{"type":["string","null"]},"district":{"type":["string","null"]},"county":{"type":["string","null"]},"postcode":{"type":["string","null"],"description":"Full postcode of the transacted property."},"outcode":{"type":["string","null"],"description":"The postcode's outward code (the first part, such as `SW1A`)."},"incode":{"type":["string","null"],"description":"The postcode's inward code (the part after the space)."}}},"TransactionLocation":{"type":["object","null"],"properties":{"propertyId":{"type":["string","null"],"description":"Identifier of the property record this transaction is linked to. Null when no property record is linked."},"uprn":{"type":["number","null"],"description":"The Unique Property Reference Number (UPRN) the transaction was matched to. Null when no match was made."},"confidence":{"type":["number","null"],"description":"How strong that match was judged to be. A higher value is a stronger match."},"point":{"type":["object","null"],"properties":{"lon":{"type":"number"},"lat":{"type":"number"}},"description":"Position of the location, as `lon` and `lat` in WGS84 decimal degrees. Null when no coordinates are held."}}},"TransactionQueryRequest":{"type":"object","properties":{"area":{"type":"array","items":{"$ref":"#/components/schemas/TransactionAreaFilter"},"description":"Areas to search within. A transaction inside any of them matches."},"query":{"type":"array","items":{"$ref":"#/components/schemas/TransactionQueryOperator"},"description":"Structured filter. Blocks at the top level combine with AND, each one narrowing the result further; within a block the groups combine by the block's operator, and the conditions in a group combine with AND."},"sort":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string","enum":["date","price.amount"],"description":"Which field to order by."},"order":{"type":"string","enum":["asc","desc"],"description":"Which direction to order in."}},"required":["field","order"]},"maxItems":3,"description":"How to order the results. Up to three entries are accepted, and the first is applied. Defaults to `date` descending.","example":[{"field":"date","order":"desc"}]},"attributes":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Top-level fields to return for each transaction, as an array or a comma-separated string. `object` and `id` are always returned."},"limit":{"type":"number","minimum":1,"maximum":100,"default":25,"description":"Maximum number of transactions to return. Defaults to 25. Minimum 1, maximum 100."},"cursor":{"type":"string","description":"Opaque cursor from the `next_cursor` of a previous response. Send it with the same `sort` as the request that produced it; a cursor from a different sort is ignored."}},"description":"Search criteria for property transactions: the areas, field conditions, ordering, fields and page size to search with."},"TransactionAreaFilter":{"anyOf":[{"$ref":"#/components/schemas/TransactionPostcodeArea"},{"$ref":"#/components/schemas/TransactionOutcodeArea"},{"$ref":"#/components/schemas/TransactionPointArea"},{"$ref":"#/components/schemas/TransactionPolygonArea"}],"description":"One area to search within. Give several and a transaction inside any of them matches."},"TransactionPostcodeArea":{"type":"object","properties":{"type":{"type":"string","enum":["postcode"]},"value":{"type":"string","minLength":2,"maxLength":10,"description":"A full postcode, or the start of one. Every postcode beginning with it matches, spaces ignored.","example":"SW1A"}},"required":["type","value"]},"TransactionOutcodeArea":{"type":"object","properties":{"type":{"type":"string","enum":["outcode"]},"value":{"type":"string","minLength":2,"maxLength":4,"description":"An outward code (the first part of a postcode, such as `SW1A`). It has to match exactly."}},"required":["type","value"]},"TransactionPointArea":{"type":"object","properties":{"type":{"type":"string","enum":["point"]},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"Centre of the search, given as longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order)."},"radius":{"type":"number","exclusiveMinimum":0,"description":"How far to search around that centre, in metres."}},"required":["type","coordinates","radius"]},"TransactionPolygonArea":{"type":"object","properties":{"type":{"type":"string","enum":["polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"description":"Polygon rings, each a list of positions given as longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order). Every ring has to be closed, repeating its first position as its last, and hold at least four positions."}},"required":["type","coordinates"]},"TransactionQueryOperator":{"type":"object","properties":{"operator":{"type":"string","enum":["AND","OR"],"description":"How the groups in this block combine. Conditions within a single group always combine with AND."},"groups":{"type":"array","items":{"$ref":"#/components/schemas/TransactionQueryGroup"},"description":"The groups of conditions this block combines."}},"required":["operator","groups"]},"TransactionQueryGroup":{"type":"object","properties":{"conditions":{"type":"array","items":{"$ref":"#/components/schemas/TransactionQueryCondition"},"description":"The conditions in this group. A record has to satisfy all of them."}},"required":["conditions"]},"TransactionQueryCondition":{"type":"object","properties":{"field":{"type":"string","description":"The field to filter on. Supported paths are `country`, `kind`, `tenure`, `propertyType`, `newBuild`, `provider`, `price.amount`, `date`, `address.postcode`, `address.outcode` and `location.uprn`.","example":"price.amount"},"comparator":{"type":"string","enum":["eq","ne","gt","gte","lt","lte","in","nin"],"description":"How `value` is compared with the field. `in` and `nin` take an array of values and every other comparator takes a single value; `ne` and `nin` also keep records where the field has no value."},"value":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"},{"type":"array","items":{"anyOf":[{"type":"string"},{"type":"number"},{"type":"boolean"}]}}],"description":"The value to compare against. Use an array with `in` and `nin`, and a single value with every other comparator. A `price.amount` value must be a non-negative whole number in minor currency units.","example":45000000}},"required":["field","comparator","value"]},"CensusAreaProfileRequest":{"type":"object","properties":{"datasetCode":{"type":"string","description":"Identifier for a census dataset: one nation's census at one vintage.","example":"ew-2021"},"geographyCodes":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100,"description":"The areas to profile, as ONS geography codes. Between 1 and 100 codes.","example":["E01004736","E01004737"]},"variableSlugs":{"type":"array","items":{"type":"string"},"description":"Limits the profile to these variables, identified by the slugs the variables endpoint returns. Omit to profile every variable in the dataset.","example":["tenure"]},"codeSystem":{"type":"string","enum":["ons_gss","cso_sa","cso_ed"],"default":"ons_gss","description":"Declares which code system `geographyCodes` are given in. Defaults to `ons_gss`, the ONS GSS codes used for UK areas, and codes are resolved as ONS GSS codes whichever value is passed."}},"required":["datasetCode","geographyCodes"],"description":"The areas to profile and, optionally, the variables to limit the profile to."},"CensusRollupRequest":{"type":"object","properties":{"datasetCode":{"type":"string","description":"Identifier for a census dataset: one nation's census at one vintage.","example":"ew-2021"},"geographyCodes":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":100,"description":"The areas that make up the custom area, as ONS geography codes. Between 1 and 100 codes.","example":["E01004736","E01004737"]},"categoryCodes":{"type":"array","items":{"type":"string"},"minItems":1,"description":"The categories to aggregate over the custom area, each formed as `{classificationCode}-{NNN}`. At least one is required, and there is no wildcard, so list every code needed.","example":["ts054-002","ts054-003"]},"codeSystem":{"type":"string","enum":["ons_gss","cso_sa","cso_ed"],"default":"ons_gss","description":"Declares which code system `geographyCodes` are given in. Defaults to `ons_gss`, the ONS GSS codes used for UK areas, and codes are resolved as ONS GSS codes whichever value is passed."}},"required":["datasetCode","geographyCodes","categoryCodes"],"description":"The areas that make up a custom area and the categories to aggregate over it. Each ratio is the summed count divided by the summed base, not an average of the individual areas' ratios."},"CensusHealthResponse":{"type":"object","properties":{"status":{"type":"string","description":"Status of the service. `ok` when it is answering requests.","example":"ok"},"service":{"type":"string","description":"Name of the service that answered.","example":"census"},"timestamp":{"type":"string","description":"When the check was answered, as an ISO 8601 timestamp.","example":"2026-05-31T12:00:00.000Z"}},"required":["status","service","timestamp"]},"ProsperityListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/ProsperityData"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."},"ProsperityData":{"type":"object","properties":{"geographicCode":{"type":"string","description":"Small area the score is published for: a Lower Layer Super Output Area (LSOA) in England and Wales, a Data Zone in Scotland, or a Super Output Area in Northern Ireland.","example":"E01000001"},"score":{"type":"number","minimum":0,"maximum":100,"description":"Overall prosperity score for the area, from 0 to 100, where 100 is the most prosperous.","example":64.2},"decile":{"type":"integer","minimum":1,"maximum":10,"description":"Which tenth of areas nationally the score falls in, from 1 to 10, where 10 is the most prosperous.","example":7},"percentile":{"type":"integer","minimum":1,"maximum":100,"description":"Where the score ranks nationally, from 1 to 100.","example":68},"version":{"type":"string","description":"Version of the prosperity dataset this score comes from.","example":"2026.1"},"computedAt":{"type":"string","format":"date-time","description":"When the score was computed, as an ISO 8601 timestamp.","example":"2026-01-15T00:00:00.000Z"},"dataQuality":{"type":"string","enum":["full","partial","limited","estimated"],"description":"How complete the data behind this score is, taken from whichever dimension is least complete.","example":"partial"},"dimensions":{"type":"object","properties":{"income":{"$ref":"#/components/schemas/ProsperityDimensionScore"},"housing":{"$ref":"#/components/schemas/ProsperityDimensionScore"},"employment":{"$ref":"#/components/schemas/ProsperityDimensionScore"},"livingStandards":{"$ref":"#/components/schemas/ProsperityDimensionScore"}},"description":"The four dimensions the overall score is built from, each with its own score and weight."},"indicators":{"type":"array","items":{"$ref":"#/components/schemas/ProsperityIndicator"},"description":"The individual measures behind the dimension scores. Indicators the publisher withheld are omitted."},"classification":{"type":["object","null"],"properties":{"scheme":{"type":"string","description":"Which classification the labels below come from, for example 'oac_2021'.","example":"oac_2021"},"supergroupLabel":{"type":"string","description":"Broadest segment the area falls in, naming the kind of place it is.","example":"Rural Residents"},"groupLabel":{"type":"string","description":"Middle segment the area falls in, one step finer than the supergroup.","example":"Farming Communities"},"subgroup":{"type":"string","description":"Finest segment the area falls in.","example":"Rural Workers and Families"}},"description":"What kind of place the area is, as segment labels from the Office for National Statistics Output Area Classification. Null for Scotland and Northern Ireland, which the classification does not cover."}},"required":["geographicCode","score","decile","percentile","version","computedAt","dataQuality"]},"ProsperityDimensionScore":{"type":"object","properties":{"score":{"type":"number","minimum":0,"maximum":100,"description":"Score for this dimension, from 0 to 100, where 100 is the most prosperous.","example":62.4},"percentile":{"type":"integer","minimum":1,"maximum":100,"description":"Where this dimension's score ranks nationally, from 1 to 100.","example":58},"dataQuality":{"type":"string","enum":["full","partial","limited","estimated"],"description":"How complete the data behind this dimension is, from a full set of indicators down to an estimate.","example":"full"},"weight":{"type":"number","minimum":0,"maximum":1,"description":"Share of the overall prosperity score this dimension carries, from 0 to 1.","example":0.3},"calculation":{"type":"string","description":"The weighted sum behind the dimension score, written out so it can be shown to an end user.","example":"(68.0x0.30) + (72.0x0.25) = 51.4"}},"required":["score","percentile","dataQuality","weight","calculation"]},"ProsperityIndicator":{"type":"object","properties":{"code":{"type":"string","description":"Stable code identifying the indicator, safe to match on.","example":"imd_income_2025"},"dimension":{"type":"string","description":"Which dimension this indicator feeds: income, housing, employment or living_standards.","example":"income"},"name":{"type":"string","description":"Name of the indicator, ready to show to an end user.","example":"Income Deprivation"},"fact":{"type":"string","description":"A sentence summarising this indicator for the area, ready to show as it stands.","example":"12% of households are income-deprived"},"displayValue":{"type":"string","description":"The value formatted with its unit, ready to show.","example":"12%"},"raw":{"type":"number","description":"The value as published, in the unit given by `unit`.","example":0.12},"unit":{"type":"string","description":"Unit the raw value is in, for example 'rate', 'GBP', '%' or 'score'.","example":"%"},"normalised":{"type":"number","minimum":0,"maximum":100,"description":"The value rescaled to run from 0 to 100, where 100 is the most prosperous.","example":73.5},"percentile":{"type":"integer","minimum":1,"maximum":100,"description":"Where this indicator ranks nationally, from 1 to 100.","example":64},"nationalMedian":{"type":["number","null"],"description":"Median of this indicator across all areas, in the same unit as `raw`. Null when not published.","example":0.15},"nationalMean":{"type":["number","null"],"description":"Mean of this indicator across all areas, in the same unit as `raw`. Null when not published.","example":0.17},"sourceName":{"type":"string","description":"Name of the dataset the value came from.","example":"English Indices of Deprivation 2025"},"sourcePublisher":{"type":"string","description":"Organisation that publishes the dataset.","example":"MHCLG"},"sourceUrl":{"type":"string","description":"Canonical address at which the publisher makes the dataset available.","example":"https://www.gov.uk/government/statistics/english-indices-of-deprivation-2025"},"year":{"type":"integer","description":"Year the value relates to.","example":2025},"apportioned":{"type":"boolean","description":"True when the value was shared out from a larger area rather than published for this one.","example":false},"suppressed":{"type":"boolean","description":"True when the publisher withheld the value rather than releasing it.","example":false}},"required":["code","dimension","name","displayValue","raw","unit","normalised","percentile","nationalMedian","nationalMean","sourceName","sourcePublisher","year","apportioned","suppressed"]},"HeritageDesignationListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/HeritageDesignationFeature"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."},"HeritageDesignationFeature":{"allOf":[{"$ref":"#/components/schemas/DesignationFeature"},{"type":"object","properties":{"metadata":{"type":"object","additionalProperties":{},"description":"Extra detail the custodian publishes, narrowed to `status`, `legal_regime` and `parish`. `legal_regime` names the Act the designation is made under, and `status` is the register status the custodian records for it. Only the keys the source actually carries appear. Requires the `designationSourceData` permission on the licence.","example":{"legal_regime":"Ancient Monuments and Archaeological Areas Act 1979"}},"monumentClassCanonical":{"type":"array","items":{"type":"string"},"description":"The monument's classes, mapped to the FISH thesaurus. Requires the `designationValueData` permission on the licence."},"monumentClassPrimary":{"type":"string","description":"The monument's primary class. Requires the `designationValueData` permission on the licence."},"unescoInscriptionType":{"type":"string","description":"How the World Heritage Site is inscribed. Requires the `designationValueData` permission on the licence."},"unescoInscriptionCriteria":{"type":"array","items":{"type":"string"},"description":"The World Heritage inscription criteria met, numbered i to x. Requires the `designationValueData` permission on the licence."},"zoneSubtype":{"type":"string","description":"Which zone of the World Heritage Site boundary this is. Requires the `designationValueData` permission on the licence."},"battleTypeCanonical":{"type":"string","description":"The kind of engagement the battlefield commemorates, harmonised across sources. Requires the `designationValueData` permission on the licence."},"wreckProtectionTypeCanonical":{"type":"string","description":"The regime the wreck is protected under, harmonised across sources. Requires the `designationValueData` permission on the licence."},"listedGrade":{"type":"string","description":"The listing or registration grade, harmonised across the nations. The token is nation-local, such as `grade_i`, `grade_ii_star`, `category_a` or `grade_b_plus`, and reads `unassigned` where the source gives none. Scottish categories A, B and C are not equivalents of English and Welsh grades I, II* and II. Requires the `designationValueData` permission on the licence."}}}]},"DesignationId":{"type":"string","pattern":"^design\\.[a-z_]+\\.[A-Z]{3}\\.[a-z_]+\\..+$","description":"Stable identifier for the designation, formed as `design.{product}.{nation}.{type}.{reference}`. It carries no snapshot, so it stays the same when the data is republished and is safe to store as a key.","example":"design.heritage.ENG.scheduled_monument.1010140"},"DesignationGeometry":{"type":"object","properties":{"centroid":{"$ref":"#/components/schemas/DesignationCentroid"},"boundary":{"$ref":"#/components/schemas/DesignationBoundary"}},"required":["centroid"]},"DesignationCentroid":{"type":"object","properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"Longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order)."}},"required":["type","coordinates"],"description":"A single point representing the designation. Always present."},"DesignationBoundary":{"type":"object","properties":{"type":{"type":"string","enum":["MultiPolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}}}},"required":["type","coordinates"],"description":"The full boundary, as a MultiPolygon in WGS84. Returned only when the request asks for `geometry` in `attributes`, since it can run well past 100 KB."},"DesignationFeature":{"type":"object","properties":{"designationId":{"$ref":"#/components/schemas/DesignationId"},"reference":{"type":"string","description":"The designation's reference in the custodian's own register."},"nation":{"type":"string","enum":["ENG","SCO","WAL","NIR"],"description":"UK nation the designation lies in."},"designationType":{"type":"string","description":"Which designation dataset this record belongs to. Treat it as an open set; the `types` endpoint lists every value present in the current snapshot."},"name":{"type":["string","null"]},"nameCy":{"type":["string","null"],"description":"Welsh-language name, where the source is bilingual."},"designatedDate":{"type":["string","null"],"description":"When the designation was made, as an ISO 8601 date. Read it alongside `datePrecision`, which says how exact it is."},"amendedDate":{"type":["string","null"]},"datePrecision":{"type":"string","enum":["day","month","year","none"],"description":"How exact `designatedDate` is: down to the day, the month, the year, or not known at all. Absent on products that record no precision."},"category":{"type":["string","null"],"description":"Class label for the designation, either the custodian's own or its harmonised equivalent."},"localAuthority":{"type":["string","null"]},"areaHectares":{"type":["number","null"]},"sourceUrl":{"type":["string","null"],"description":"Canonical address at which the custodian publishes this designation's entry."},"geometry":{"$ref":"#/components/schemas/DesignationGeometry"},"licence":{"type":["string","null"],"description":"Identifier of the licence this designation is published under. Returned on every licence tier."},"attribution":{"type":["string","null"],"description":"The attribution that must be shown wherever this designation is displayed. Returned on every licence tier."},"provenance":{"$ref":"#/components/schemas/Provenance"},"distanceM":{"type":["number","null"],"description":"Distance in metres from the query point to the designation's boundary, or 0 when the point falls inside it. Present only when the search area was a point, a postcode or an outward code."},"source":{"type":"string","description":"Identifier of the custodian register the record came from. Requires the `designationSourceData` permission on the licence."},"designatedDateSource":{"type":["string","null"],"description":"Where `designatedDate` was taken from. Requires the `designationSourceData` permission on the licence."},"metadata":{"type":"object","additionalProperties":{},"description":"Extra detail the custodian publishes, narrowed to a fixed set of keys that varies by product. Only the keys the source actually carries appear. Requires the `designationSourceData` permission on the licence.","example":{"legal_regime":"Ancient Monuments and Archaeological Areas Act 1979"}}},"required":["designationId","reference","nation","designationType","geometry","licence","attribution","provenance"]},"DesignationQueryRequest":{"type":"object","properties":{"area":{"type":"array","items":{"$ref":"#/components/schemas/DesignationArea"},"minItems":1,"maxItems":10,"description":"The areas to search, between one and ten of them. Designations matching any of the areas are returned, deduplicated by `designationId`."},"snapshotId":{"type":"string","minLength":1,"maxLength":50,"description":"Pin the request to one published snapshot, which holds the data steady across paging and republishes. When omitted the current snapshot is used, and either way the snapshot read is reported in `provenance.snapshotId`."},"filters":{"$ref":"#/components/schemas/DesignationFilters"},"sort":{"type":"array","items":{"$ref":"#/components/schemas/DesignationSortField"},"maxItems":3,"description":"How to order the results, up to three keys applied in turn. By default, nearest first when the area is a point, postcode or outward code, and by name otherwise."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25},"offset":{"type":"integer","minimum":0,"maximum":10000,"default":0},"attributes":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Which heavy attributes to add, as a comma-separated string or an array. Pass `geometry` for the full MultiPolygon boundary; the centroid is always returned. Which licensed fields appear is decided by the permissions on the API key, not here.","example":"geometry"}},"required":["area"]},"DesignationArea":{"oneOf":[{"$ref":"#/components/schemas/DesignationPointArea"},{"$ref":"#/components/schemas/DesignationPostcodeArea"},{"$ref":"#/components/schemas/DesignationOutcodeArea"},{"$ref":"#/components/schemas/DesignationBboxArea"},{"$ref":"#/components/schemas/DesignationPolygonArea"},{"$ref":"#/components/schemas/DesignationMultiPolygonArea"}],"discriminator":{"propertyName":"type","mapping":{"point":"#/components/schemas/DesignationPointArea","postcode":"#/components/schemas/DesignationPostcodeArea","outcode":"#/components/schemas/DesignationOutcodeArea","boundingBox":"#/components/schemas/DesignationBboxArea","polygon":"#/components/schemas/DesignationPolygonArea","multipolygon":"#/components/schemas/DesignationMultiPolygonArea"}}},"DesignationPointArea":{"type":"object","properties":{"type":{"type":"string","enum":["point"]},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"The point to search from: latitude first, then longitude, in WGS84 decimal degrees. This is the reverse of the GeoJSON order used by geometry fields, so a `centroid` from a response must be reversed before it is sent back here.","example":[51.1789,-1.8262]},"radius":{"type":"integer","minimum":0,"maximum":50000,"default":0,"description":"Radius to search around the point, in metres. 0 returns the designations whose boundary contains the point; any larger value returns every designation lying within that distance. Defaults to 0. Maximum 50000."}},"required":["type","coordinates"]},"DesignationPostcodeArea":{"type":"object","properties":{"type":{"type":"string","enum":["postcode"]},"value":{"type":"string","pattern":"^[A-Z]{1,2}[0-9][0-9A-Z]?\\s?[0-9][A-Z]{2}$","description":"A full UK postcode. The space is optional and case is not significant; the value is returned upper-cased.","example":"SW1A 1AA"},"radius":{"type":"integer","minimum":0,"maximum":50000,"default":0,"description":"Radius to search around the centre of the postcode, in metres. 0 returns the designations containing that centre. Defaults to 0. Maximum 50000."}},"required":["type","value"]},"DesignationOutcodeArea":{"type":"object","properties":{"type":{"type":"string","enum":["outcode"]},"value":{"type":"string","pattern":"^[A-Z]{1,2}[0-9][0-9A-Z]?(\\s?[0-9][A-Z]{2})?$","description":"The outward code to search, meaning the first part of a postcode, such as `SP4` or `M1`. Designations within 5 km of its centre are returned.","example":"SW1"}},"required":["type","value"]},"DesignationBboxArea":{"type":"object","properties":{"type":{"type":"string","enum":["boundingBox"]},"southWest":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"The south-west corner: latitude first, then longitude, in WGS84 decimal degrees. This is the reverse of the GeoJSON order used by geometry fields.","example":[51.1,-1.9]},"northEast":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"The north-east corner: latitude first, then longitude, in WGS84 decimal degrees.","example":[51.2,-1.7]}},"required":["type","southWest","northEast"]},"DesignationPolygonArea":{"type":"object","properties":{"type":{"type":"string","enum":["polygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}},"description":"Rings of the polygon to search, each point given as latitude first, then longitude, in WGS84 decimal degrees. This is the reverse of the GeoJSON order used by geometry fields. Give the outer ring first; any further rings are holes, and each ring's first and last point must match."}},"required":["type","coordinates"]},"DesignationMultiPolygonArea":{"type":"object","properties":{"type":{"type":"string","enum":["multipolygon"]},"coordinates":{"type":"array","items":{"type":"array","items":{"type":"array","items":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}]}}},"description":"The polygons to search, each given as rings of points with latitude first, then longitude, in WGS84 decimal degrees. This is the reverse of the GeoJSON order used by geometry fields."}},"required":["type","coordinates"]},"DesignationFilters":{"type":"object","properties":{"designationType":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"Return only designations of these types, for example 'scheduled_monument' or 'sac'. The `types` endpoint lists every value present in the current snapshot.","example":"scheduled_monument"},"nation":{"anyOf":[{"type":"string","enum":["ENG","SCO","WAL","NIR"]},{"type":"array","items":{"type":"string","enum":["ENG","SCO","WAL","NIR"]}}],"description":"Return only designations in these UK nations."},"localAuthority":{"type":"string","description":"Return only designations whose local authority label matches this exactly."}}},"DesignationSortField":{"type":"object","properties":{"field":{"type":"string","enum":["distanceM","name","designatedDate","areaHectares"]},"order":{"type":"string","enum":["asc","desc"],"default":"asc"}},"required":["field"]},"DesignationSnapshotListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/DesignationSnapshot"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."},"DesignationSnapshot":{"type":"object","properties":{"snapshotId":{"type":"string","description":"Identifier of the snapshot, which is the value to pass as `snapshotId` on a query.","example":"htg-20260620-01"},"status":{"type":"string","enum":["published"],"description":"Always `published`: only published snapshots are listed."},"publishedAt":{"type":["string","null"],"description":"When the snapshot was published, as an ISO 8601 timestamp."},"productVersion":{"type":"string","description":"Semantic version of the product that built the snapshot.","example":"1.0.0"},"recordCount":{"type":["integer","null"],"description":"Number of designations the snapshot holds."}},"required":["snapshotId","status","publishedAt","productVersion","recordCount"]},"DesignationTypeListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/DesignationType"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."},"DesignationType":{"type":"object","properties":{"designationType":{"type":"string","description":"Code identifying the designation dataset. Pass it as the `designationType` filter on a query.","example":"scheduled_monument"},"label":{"type":"string","description":"Human-readable name for the type.","example":"Scheduled monument"},"count":{"type":"integer","description":"Number of designations of this type in the current snapshot."}},"required":["designationType","label","count"]},"ConservationDesignationListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/ConservationDesignationFeature"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."},"ConservationDesignationFeature":{"allOf":[{"$ref":"#/components/schemas/DesignationFeature"},{"type":"object","properties":{"metadata":{"type":"object","additionalProperties":{},"description":"Extra detail the custodian publishes, narrowed to `status`, `legal_regime`, `woodland_composition`, `native_pct`, `canopy_pct`, `dominant_habitat`, `maturity`, `parish`, `geographic_location` and `stat_area_km2`. Only the keys the source actually carries appear. Requires the `designationSourceData` permission on the licence.","example":{"status":"designated","legal_regime":"Conservation of Habitats and Species Regulations 2017 (retained Habitats Directive)","woodland_composition":"Broadleaved"}}}}]},"GeographyArea":{"type":"object","properties":{"code":{"type":"string","description":"The GSS code, e.g. `E01000001`."},"areaType":{"type":"string","description":"The layer as its publisher names it, such as `lsoa`, `sct_dz` or `nir_dz`. Never carries a vintage."},"vintage":{"type":["string","null"],"description":"The layer edition, e.g. `2021`."},"name":{"type":["string","null"],"description":"Publisher name. Null where none is published (ONS issues no names for Output Areas). Names are not unique, so never key on one."},"nation":{"type":["string","null"],"description":"`ENG` | `WAL` | `SCO` | `NIR`, or null for a genuinely cross-border area."},"tier":{"type":["string","null"],"description":"Cross-nation tier: `small_area` is an LSOA in England and Wales and a Data Zone in Scotland and Northern Ireland."}},"required":["code","areaType","vintage","name","nation","tier"]},"GeographyRelatedArea":{"allOf":[{"$ref":"#/components/schemas/GeographyArea"},{"type":"object","properties":{"depth":{"type":"integer","description":"Hops from the area asked about. 1 is a direct parent or child."},"minFit":{"type":"string","description":"Worst fit along the whole path: `exact`, `best_fit` or `spatial`. Anything other than `exact` means aggregating across this relationship gives an approximate answer."}},"required":["depth","minFit"]}]},"LandConstraintDesignationListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/LandConstraintDesignationFeature"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."},"LandConstraintDesignationFeature":{"allOf":[{"$ref":"#/components/schemas/DesignationFeature"},{"type":"object","properties":{"metadata":{"type":"object","additionalProperties":{},"description":"Extra detail the custodian publishes, narrowed to `status`, `legal_regime`, `permitted_development_rights` and `bmv`. On an Article 4 direction area, `permitted_development_rights` records which rights that direction withdraws, in the wording the local authority used: most entries are semicolon-separated class codes from the Town and Country Planning (General Permitted Development) (England) Order 2015, such as `1A;1C;1D;1F;2A;2B`, but a substantial minority are a sentence naming the Parts and Classes instead, so parse it defensively. On an agricultural land classification area, `bmv` is true where the grade counts as Best and Most Versatile agricultural land. Only the keys the source actually carries appear, and this field requires the `designationSourceData` permission on the licence.","example":{"status":"designated","permitted_development_rights":"1A;1C;1D;1F;2A;2B"}}}}]},"ModelList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}},"required":["object","data"]},"Model":{"type":"object","properties":{"id":{"type":"string","description":"Id to pass as `model`."},"object":{"type":"string","enum":["model"]},"created":{"type":"integer","description":"Unix time in seconds when the served version was published."},"owned_by":{"type":"string","enum":["vepler"]},"vepler":{"type":"object","properties":{"description":{"type":"string","description":"What the model reads and returns."},"input_type":{"type":"string","enum":["image"],"description":"Kind of input the model takes in the user message."},"version":{"type":"string","description":"Version currently served, as reported in `system_fingerprint`."},"output_schema":{"type":"object","additionalProperties":{},"description":"JSON Schema of the result. A `json_schema` response format may carry it unchanged as `schema`."},"output_schema_name":{"type":"string","description":"Name to send as `response_format.json_schema.name`."}},"required":["description","input_type","version","output_schema","output_schema_name"]}},"required":["id","object","created","owned_by","vepler"]},"ModelApiError":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable explanation of what went wrong."},"type":{"type":"string","enum":["invalid_request_error","authentication_error","rate_limit_error","api_error"],"description":"Broad category of the failure: a request problem, an authentication problem, a rate limit or a server fault."},"param":{"type":["string","null"],"description":"Request parameter at fault, or null when the failure has none."},"code":{"type":["string","null"],"description":"Stable code identifying the failure, safe to branch on, or null."}},"required":["message","type","param","code"]}},"required":["error"]},"ChatCompletion":{"type":"object","properties":{"id":{"type":"string","description":"Identifier of this completion."},"object":{"type":"string","enum":["chat.completion"]},"created":{"type":"integer","description":"Unix time in seconds when the result was produced."},"model":{"type":"string","description":"Id of the model that ran."},"system_fingerprint":{"type":"string","description":"Version of the model that produced the result."},"choices":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"message":{"type":"object","properties":{"role":{"type":"string","enum":["assistant"]},"content":{"type":"string","description":"The result: one JSON object, as a string, matching the model's output schema."},"refusal":{"type":"null"}},"required":["role","content","refusal"]},"logprobs":{"type":"null"},"finish_reason":{"type":"string","enum":["stop"]}},"required":["index","message","logprobs","finish_reason"]},"description":"Exactly one result."},"usage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","description":"Tokens the model read as input, including the model's fixed instructions."},"completion_tokens":{"type":"integer","description":"Tokens the model produced."},"total_tokens":{"type":"integer","description":"Sum of prompt and completion tokens."},"vepler_units":{"type":"integer","description":"Inputs charged for by this request. Zero when the result is a repeat served without charge."},"vepler_credits":{"type":"integer","description":"Credits charged for this request. Zero when the result is a repeat served without charge."}},"required":["prompt_tokens","completion_tokens","total_tokens","vepler_units","vepler_credits"]}},"required":["id","object","created","model","system_fingerprint","choices","usage"],"example":{"id":"chatcmpl-3f0c2a9e5b8d4e1fa7c6b2d9e0f1a2b3","object":"chat.completion","created":1791100800,"model":"epc-vision","system_fingerprint":"epc-vision@v7","choices":[{"index":0,"message":{"role":"assistant","content":"{\"energy_efficiency\":{\"current_band\":\"D\",\"current_score\":68,\"potential_band\":\"C\",\"potential_score\":78,\"scale\":\"sap\"},\"environmental_impact\":null}","refusal":null},"logprobs":null,"finish_reason":"stop"}],"usage":{"prompt_tokens":1120,"completion_tokens":57,"total_tokens":1177,"vepler_units":1,"vepler_credits":2}}},"ChatCompletionRequest":{"type":"object","properties":{"model":{"type":"string","minLength":1,"description":"Id of the model to run, from `GET /models`.","example":"epc-vision"},"messages":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string"},"content":{}},"required":["role"],"additionalProperties":{}},"description":"Exactly one message with role `user`, whose content is one `image_url` part: an `https` URL on a public host name, or a base64 `data:` URL with a raster image type. The image can be up to 20 MiB. System messages and text parts are refused because the model's instructions are fixed."},"stream":{"type":["boolean","null"],"description":"When true, the result arrives as server-sent events in one chunk."},"stream_options":{"type":["object","null"],"properties":{"include_usage":{"type":"boolean"}},"description":"With `include_usage: true`, a final chunk carries `usage`."},"n":{"type":["integer","null"],"description":"Number of results. Only 1 is supported."},"response_format":{"type":["object","null"],"properties":{"type":{"type":"string"}},"required":["type"],"additionalProperties":{},"description":"Output format: `json_object`, or `json_schema` with `name` set to the model's `output_schema_name` and `schema` either omitted or equal to its `output_schema`. The result is the same JSON object either way."},"tools":{"type":["array","null"],"items":{},"description":"Not supported. A non-empty list is refused."},"tool_choice":{"description":"Not supported. Any value other than `none` is refused."},"functions":{"type":["array","null"],"items":{},"description":"Not supported. A non-empty list is refused."},"function_call":{"description":"Not supported. Any value other than `none` is refused."},"temperature":{"type":["number","null"],"description":"Accepted and ignored. The model always runs at temperature 0."},"top_p":{"type":["number","null"],"description":"Accepted and ignored."},"frequency_penalty":{"type":["number","null"],"description":"Accepted and ignored."},"presence_penalty":{"type":["number","null"],"description":"Accepted and ignored."},"seed":{"type":["integer","null"],"description":"Accepted and ignored."},"stop":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Accepted and ignored."},"max_tokens":{"type":["integer","null"],"description":"Accepted and ignored. Each model has a fixed output limit."},"max_completion_tokens":{"type":["integer","null"],"description":"Accepted and ignored. Each model has a fixed output limit."},"logprobs":{"type":["boolean","null"],"description":"Accepted and ignored."},"top_logprobs":{"type":["integer","null"],"description":"Accepted and ignored."},"logit_bias":{"type":["object","null"],"additionalProperties":{"type":"number"},"description":"Accepted and ignored."},"user":{"type":["string","null"],"description":"Accepted and ignored."},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Accepted and ignored."},"store":{"type":["boolean","null"],"description":"Accepted and ignored. A completed result is kept for 15 minutes, only to answer an identical repeat from the same account without a charge."},"service_tier":{"type":["string","null"],"description":"Accepted and ignored."},"parallel_tool_calls":{"type":["boolean","null"],"description":"Accepted and ignored."}},"required":["model","messages"],"additionalProperties":false,"example":{"model":"epc-vision","messages":[{"role":"user","content":[{"type":"image_url","image_url":{"url":"https://example.com/epc-chart.png"}}]}]}},"ModelResponse":{"type":"object","properties":{"id":{"type":"string","description":"Identifier of this response."},"object":{"type":"string","enum":["response"]},"created_at":{"type":"integer","description":"Unix time in seconds when the result was produced."},"status":{"type":"string","enum":["completed"]},"model":{"type":"string","description":"Id of the model that ran."},"output":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["message"]},"id":{"type":"string"},"status":{"type":"string","enum":["completed"]},"role":{"type":"string","enum":["assistant"]},"content":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["output_text"]},"text":{"type":"string","description":"The result: one JSON object, as a string, matching the model's output schema."},"annotations":{"type":"array","items":{},"maxItems":0,"description":"Always empty."}},"required":["type","text","annotations"]}}},"required":["type","id","status","role","content"]},"description":"Exactly one message holding one `output_text` part."},"error":{"type":"null"},"incomplete_details":{"type":"null"},"usage":{"type":"object","properties":{"input_tokens":{"type":"integer","description":"Tokens the model read as input, including the model's fixed instructions."},"output_tokens":{"type":"integer","description":"Tokens the model produced."},"total_tokens":{"type":"integer","description":"Sum of input and output tokens."},"vepler_units":{"type":"integer","description":"Inputs charged for by this request. Zero when the result is a repeat served without charge."},"vepler_credits":{"type":"integer","description":"Credits charged for this request. Zero when the result is a repeat served without charge."}},"required":["input_tokens","output_tokens","total_tokens","vepler_units","vepler_credits"]}},"required":["id","object","created_at","status","model","output","error","incomplete_details","usage"]},"ResponseRequest":{"type":"object","properties":{"model":{"type":"string","minLength":1,"description":"Id of the model to run, from `GET /models`.","example":"epc-vision"},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{},"additionalProperties":{}}}],"description":"Exactly one message with role `user`, whose content is one `input_image` part: an `https` URL on a public host name, or a base64 `data:` URL with a raster image type. The image can be up to 20 MiB. Text input is refused because the model's instructions are fixed."},"instructions":{"type":["string","null"],"description":"Not supported. Any non-empty value is refused."},"stream":{"type":["boolean","null"],"description":"Not supported on this route. Use chat completions to stream."},"text":{"type":["object","null"],"properties":{"format":{"type":"object","properties":{"type":{"type":"string"}},"required":["type"],"additionalProperties":{},"description":"Output format: `json_object`, or `json_schema` with `name` set to the model's `output_schema_name` and `schema` either omitted or equal to its `output_schema`. The result is the same JSON object either way."}},"additionalProperties":{},"description":"Output format, under `format`, with the same rules as `response_format` on chat completions."},"tools":{"type":["array","null"],"items":{},"description":"Not supported. A non-empty list is refused."},"tool_choice":{"description":"Not supported. Any value other than `none` is refused."},"temperature":{"type":["number","null"],"description":"Accepted and ignored. The model always runs at temperature 0."},"top_p":{"type":["number","null"],"description":"Accepted and ignored."},"max_output_tokens":{"type":["integer","null"],"description":"Accepted and ignored. Each model has a fixed output limit."},"user":{"type":["string","null"],"description":"Accepted and ignored."},"metadata":{"type":["object","null"],"additionalProperties":{"type":"string"},"description":"Accepted and ignored."},"store":{"type":["boolean","null"],"description":"Accepted and ignored. A completed result is kept for 15 minutes, only to answer an identical repeat from the same account without a charge."},"service_tier":{"type":["string","null"],"description":"Accepted and ignored."},"truncation":{"type":["string","null"],"description":"Accepted and ignored."},"parallel_tool_calls":{"type":["boolean","null"],"description":"Accepted and ignored."}},"required":["model","input"],"additionalProperties":false,"example":{"model":"epc-vision","input":[{"role":"user","content":[{"type":"input_image","image_url":"https://example.com/epc-chart.png"}]}]}}},"parameters":{}},"paths":{"/v1/property/attributes":{"get":{"operationId":"getPropertyAttributes","x-speakeasy-name-override":"getPropertyAttributes","tags":["Property"],"summary":"Get the property attribute catalogue","description":"Lists every attribute the property endpoints can return, with its dotted path, type, the billing tier it puts a request into and any extended permission it needs, alongside the field names, comparators and sort fields that `POST /v1/property/query` accepts. Read it to build a request without guessing, and to price one before sending it. This endpoint is free to call.","responses":{"200":{"description":"The attribute catalogue, with the permissions the calling key holds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyAttributeCatalogue"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/property/{locationIds}":{"get":{"operationId":"getPropertiesByLocation","x-speakeasy-name-override":"getPropertiesByLocation","tags":["Property"],"summary":"Get properties by location ID","description":"Returns one property per location ID supplied, which in Great Britain is the Unique Property Reference Number (UPRN). Pass several at once by separating them with commas. Use `attributes` to choose what comes back; without it you get the default set of identity and address fields. Add `monitor` to also monitor the properties it returns, for a whole number of months or `true` for one; the response then carries a short `monitoring` object and is otherwise unchanged.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":2000,"description":"One or more location IDs, separated by commas. Each identifies a single addressable location; in Great Britain that is the Unique Property Reference Number (UPRN)."},"required":true,"description":"One or more location IDs, separated by commas. Each identifies a single addressable location; in Great Britain that is the Unique Property Reference Number (UPRN).","name":"locationIds","in":"path"},{"schema":{"type":"string","description":"Maximum number of properties to return. Defaults to 25."},"required":false,"description":"Maximum number of properties to return. Defaults to 25.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Number of results to skip before the first one returned."},"required":false,"description":"Number of results to skip before the first one returned.","name":"offset","in":"query"},{"schema":{"type":"string","description":"Attributes to return, as dotted paths separated by commas. Only these are returned, plus `locationId`, which is always included. Omit it to receive the default set. `GET /v1/property/attributes` lists every path."},"required":false,"description":"Attributes to return, as dotted paths separated by commas. Only these are returned, plus `locationId`, which is always included. Omit it to receive the default set. `GET /v1/property/attributes` lists every path.","name":"attributes","in":"query"},{"schema":{"type":"string","description":"Sovereign state the request is aimed at, as an ISO 3166-1 alpha-2 code such as `GB`. Taken as a hint only: it does not filter the results, and the data covers Great Britain."},"required":false,"description":"Sovereign state the request is aimed at, as an ISO 3166-1 alpha-2 code such as `GB`. Taken as a hint only: it does not filter the results, and the data covers Great Britain.","name":"countryCode","in":"query"},{"schema":{"type":"string","description":"Monitor the properties this request returns. Pass a whole number of calendar months, or pass `true` for one month. Monitoring is set up with the request, and the response carries a short `monitoring` object saying how many properties it covers. It needs an active property_monitoring licence grant. Properties already monitored have their term extended to this length rather than being registered twice, so re-sending it on every check keeps a property monitored without a gap. Pass `false` or omit it and the response is unchanged."},"required":false,"description":"Monitor the properties this request returns. Pass a whole number of calendar months, or pass `true` for one month. Monitoring is set up with the request, and the response carries a short `monitoring` object saying how many properties it covers. It needs an active property_monitoring licence grant. Properties already monitored have their term extended to this length rather than being registered twice, so re-sending it on every check keeps a property monitored without a gap. Pass `false` or omit it and the response is unchanged.","name":"monitor","in":"query"}],"responses":{"200":{"description":"The matching properties, carrying the requested attributes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/property/propertyId/{propertyIds}":{"get":{"operationId":"getProperties","x-speakeasy-name-override":"getProperties","tags":["Property"],"summary":"Get properties by property ID","description":"Returns one property per property ID supplied, separated by commas. Reach for it when you already hold property IDs from an earlier response; look properties up by location ID when you hold a UPRN instead.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":2000,"description":"One or more property IDs, separated by commas."},"required":true,"description":"One or more property IDs, separated by commas.","name":"propertyIds","in":"path"},{"schema":{"type":"string","description":"Maximum number of properties to return. Defaults to 25."},"required":false,"description":"Maximum number of properties to return. Defaults to 25.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Number of results to skip before the first one returned."},"required":false,"description":"Number of results to skip before the first one returned.","name":"offset","in":"query"},{"schema":{"type":"string","description":"Attributes to return, as dotted paths separated by commas. Only these are returned, plus `locationId`, which is always included. Omit it to receive the default set. `GET /v1/property/attributes` lists every path."},"required":false,"description":"Attributes to return, as dotted paths separated by commas. Only these are returned, plus `locationId`, which is always included. Omit it to receive the default set. `GET /v1/property/attributes` lists every path.","name":"attributes","in":"query"},{"schema":{"type":"string","description":"Sovereign state the request is aimed at, as an ISO 3166-1 alpha-2 code such as `GB`. Taken as a hint only: it does not filter the results, and the data covers Great Britain."},"required":false,"description":"Sovereign state the request is aimed at, as an ISO 3166-1 alpha-2 code such as `GB`. Taken as a hint only: it does not filter the results, and the data covers Great Britain.","name":"countryCode","in":"query"}],"responses":{"200":{"description":"The matching properties, carrying the requested attributes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/property/query":{"post":{"operationId":"searchProperties","x-speakeasy-name-override":"searchProperties","tags":["Property"],"summary":"Search properties","description":"Searches properties inside one or more areas, narrowed by any combination of attributes: price, bedrooms, energy rating, market status and the rest of the catalogue at `GET /v1/property/attributes`. Only residential properties are returned, and a `propertyCategory` condition cannot widen that, so a query asking for commercial properties matches nothing. A page may hold up to 10,000 properties, and `limit` plus `offset` may not exceed 10,000 either, so reach a deeper result set by narrowing the area rather than paging on; a request beyond that depth is rejected instead of being quietly answered with a different page. The optional `monitor` parameter registers every property the query matches, which is the whole match set rather than the page returned, for monitoring billed monthly per property. That registration runs in the background and needs an active property_monitoring licence grant, and the response carries a `monitoring` receipt describing what happened to it.","requestBody":{"description":"The area to search, the filters to apply, and the attributes to return.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyQueryRequest"}}}},"responses":{"200":{"description":"The matching properties, carrying the requested attributes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/property/aggregate":{"post":{"operationId":"aggregateProperties","x-speakeasy-name-override":"aggregateProperties","tags":["Property"],"summary":"Aggregate property statistics for an area","description":"Counts, averages and distributions calculated over the properties in an area, without returning the properties themselves. Use it for market summaries and charts where a full result set would be wasteful. The areas may cover 500 km² in total at most, and a request may carry up to 10 aggregations.","requestBody":{"description":"The area to cover, any filters to apply, and the statistics to calculate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyAggregateRequest"}}}},"responses":{"200":{"description":"The calculated statistics, with the number of properties they were taken over.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyAggregateResponse"}}}},"400":{"description":"The request was rejected, because the area is larger than 500 km² or a field or aggregation is not supported. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/property/sources/{sourceIds}":{"get":{"operationId":"getPropertiesBySource","x-speakeasy-name-override":"getPropertiesBySource","tags":["Property"],"summary":"Get properties by source ID","description":"Returns the property behind each source ID supplied, separated by commas. A source ID is written `provider::key`, naming the provider and its own identifier for the record, so this is the way back from a provider's listing reference to the property it belongs to.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":2000,"description":"One or more source IDs, separated by commas. Each is written `provider::key`, naming the provider and its own identifier for the record."},"required":true,"description":"One or more source IDs, separated by commas. Each is written `provider::key`, naming the provider and its own identifier for the record.","name":"sourceIds","in":"path"},{"schema":{"type":"string","description":"Maximum number of properties to return. Defaults to 25."},"required":false,"description":"Maximum number of properties to return. Defaults to 25.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Number of results to skip before the first one returned."},"required":false,"description":"Number of results to skip before the first one returned.","name":"offset","in":"query"},{"schema":{"type":"string","description":"Attributes to return, as dotted paths separated by commas. Only these are returned, plus `locationId`, which is always included. Omit it to receive the default set. `GET /v1/property/attributes` lists every path."},"required":false,"description":"Attributes to return, as dotted paths separated by commas. Only these are returned, plus `locationId`, which is always included. Omit it to receive the default set. `GET /v1/property/attributes` lists every path.","name":"attributes","in":"query"},{"schema":{"type":"string","description":"Sovereign state the request is aimed at, as an ISO 3166-1 alpha-2 code such as `GB`. Taken as a hint only: it does not filter the results, and the data covers Great Britain."},"required":false,"description":"Sovereign state the request is aimed at, as an ISO 3166-1 alpha-2 code such as `GB`. Taken as a hint only: it does not filter the results, and the data covers Great Britain.","name":"countryCode","in":"query"}],"responses":{"200":{"description":"The matching properties, carrying the requested attributes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/property/properties/by-slugs":{"post":{"operationId":"getPropertiesBySlugs","x-speakeasy-name-override":"getPropertiesBySlugs","tags":["Property"],"summary":"Get properties by slug","description":"Returns the properties matching a list of address slugs, the URL-safe form carried in each property's `slug` field. Up to 1,000 slugs per request.","requestBody":{"description":"The slugs to look up, and the attributes to return.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyBySlugsRequest"}}}},"responses":{"200":{"description":"The matching properties, carrying the requested attributes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PropertyListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/property/health":{"get":{"operationId":"checkPropertyHealth","x-speakeasy-name-override":"checkPropertyHealth","tags":["System"],"summary":"Check property service health","description":"Reports whether the property service is answering requests. It takes no parameters.","responses":{"200":{"description":"The service is answering requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/property/tiles/{z}/{x}/{y}":{"get":{"operationId":"getPropertyTiles","x-speakeasy-name-override":"getPropertyTiles","tags":["Property"],"summary":"Get property map tiles","description":"Returns properties as a Mapbox Vector Tile, ready to drop into a map style. Tiles follow the standard Web Mercator z/x/y scheme, so a map library requests them by URL template. A tile carries up to 10,000 properties; use `mode=density` at low zoom, where a grid of counts replaces the individual properties and nothing is dropped. Narrow what a tile draws with `query` and `area`, and choose what each feature carries with `attributes`.","parameters":[{"schema":{"type":"string","description":"Zoom level of the requested tile.","example":"14"},"required":true,"description":"Zoom level of the requested tile.","name":"z","in":"path"},{"schema":{"type":"string","description":"Tile column index at this zoom level.","example":"8192"},"required":true,"description":"Tile column index at this zoom level.","name":"x","in":"path"},{"schema":{"type":"string","description":"Tile row index at this zoom level.","example":"5461"},"required":true,"description":"Tile row index at this zoom level.","name":"y","in":"path"},{"schema":{"type":"string","description":"Filters narrowing which properties the tile draws, as a JSON-encoded array in the same shape as the `query` field of `POST /v1/property/query`.","example":"[{\"operator\":\"AND\",\"groups\":[{\"conditions\":[{\"field\":\"saleListingStatus\",\"comparator\":\"in\",\"value\":[\"live\"]}]}]}]"},"required":false,"description":"Filters narrowing which properties the tile draws, as a JSON-encoded array in the same shape as the `query` field of `POST /v1/property/query`.","name":"query","in":"query"},{"schema":{"type":"string","description":"Areas the tile is restricted to, as a JSON-encoded array in the same shape as the `area` field of `POST /v1/property/query`.","example":"[{\"type\":\"postcode\",\"value\":\"SW1A\"}]"},"required":false,"description":"Areas the tile is restricted to, as a JSON-encoded array in the same shape as the `area` field of `POST /v1/property/query`.","name":"area","in":"query"},{"schema":{"type":"string","description":"Which attributes to encode on each feature, as dotted paths separated by commas. Omit it and every feature carries `propertyId`, `locationId`, `pricing.currentSale` and `marketStatus.forSale`. Tiles can serve those four, plus `address`, which expands to the whole address block, and the individual address fields: `address.displayAddress`, `address.line_1`, `address.line_2`, `address.line_3`, `address.post_town`, `address.postcode`, `address.postcodeNoSpace`, `address.outcode`, `address.incode`, `address.country`, `address.countryCode` and `address.eircode`. `locationId` is always included. Anything else is dropped rather than rejected, so a tile still renders. Density tiles carry no per-feature attributes, so this is ignored there.","example":"propertyId,locationId,address.displayAddress,address.postcode"},"required":false,"description":"Which attributes to encode on each feature, as dotted paths separated by commas. Omit it and every feature carries `propertyId`, `locationId`, `pricing.currentSale` and `marketStatus.forSale`. Tiles can serve those four, plus `address`, which expands to the whole address block, and the individual address fields: `address.displayAddress`, `address.line_1`, `address.line_2`, `address.line_3`, `address.post_town`, `address.postcode`, `address.postcodeNoSpace`, `address.outcode`, `address.incode`, `address.country`, `address.countryCode` and `address.eircode`. `locationId` is always included. Anything else is dropped rather than rejected, so a tile still renders. Density tiles carry no per-feature attributes, so this is ignored there.","name":"attributes","in":"query"},{"schema":{"type":"string","enum":["hits","density"],"description":"What the tile contains. `hits`, the default, draws one feature per property in the `hits` layer, up to 10,000 per tile; past that the highest-priced survive. `density` draws no individual properties and instead fills the `aggs` layer with a fine grid of cells, each carrying a property count and an average sale price. The grid is never truncated, which makes it the one to use at low zoom.","example":"density"},"required":false,"description":"What the tile contains. `hits`, the default, draws one feature per property in the `hits` layer, up to 10,000 per tile; past that the highest-priced survive. `density` draws no individual properties and instead fills the `aggs` layer with a fine grid of cells, each carrying a property count and an average sale price. The grid is never truncated, which makes it the one to use at low zoom.","name":"mode","in":"query"}],"responses":{"200":{"description":"The tile, as Mapbox Vector Tile binary data.","content":{"application/x-protobuf":{"schema":{"description":"The tile, as Mapbox Vector Tile binary data."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/safety/health":{"get":{"operationId":"getSafetyHealth","x-speakeasy-name-override":"getSafetyHealth","tags":["System"],"summary":"Safety service health check","description":"Check whether the safety service is operating.","responses":{"200":{"description":"The service is operating, with its name and the time the check ran.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/safety/crime":{"get":{"operationId":"getCrimeIncidents","x-speakeasy-name-override":"getCrimeIncidents","tags":["Safety"],"summary":"Get crime incidents near a point","description":"Return the individual crime incidents recorded within `radius` metres of a point, covering England and Wales from August 2020 onwards. Incident locations are anonymised at source to a nearby map point, accurate to roughly 150m, and are published monthly around two months in arrears, dated to the first of the month they were recorded in. The response always covers six months: supplying `date` ends that window at the month given, or at the most recent month with significant reporting if that is earlier, and leaving `date` out ends it at the most recent month with significant reporting in the area. A single request returns at most 5,000 incidents, and sets `summary.truncated` to `true` when it hits that cap, so narrow the radius or the date window to see the rest.","parameters":[{"schema":{"type":"string","pattern":"^-?\\d+\\.?\\d*$","description":"Latitude of the point to search around, in WGS84 decimal degrees.","example":"51.5074"},"required":true,"description":"Latitude of the point to search around, in WGS84 decimal degrees.","name":"latitude","in":"query"},{"schema":{"type":"string","pattern":"^-?\\d+\\.?\\d*$","description":"Longitude of the point to search around, in WGS84 decimal degrees.","example":"-0.1278"},"required":true,"description":"Longitude of the point to search around, in WGS84 decimal degrees.","name":"longitude","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","default":"1000","description":"How far to search around the point, in metres. Defaults to 1000. Minimum 100, maximum 50000.","example":"1000"},"required":false,"description":"How far to search around the point, in metres. Defaults to 1000. Minimum 100, maximum 50000.","name":"radius","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$","description":"Month to anchor the response on, in `YYYY-MM` form. The response covers the six months ending at this month, or at the most recent month with significant reporting in the area if that is earlier. When omitted, the six months end at the most recent month with significant reporting in the area.","example":"2024-01"},"required":false,"description":"Month to anchor the response on, in `YYYY-MM` form. The response covers the six months ending at this month, or at the most recent month with significant reporting in the area if that is earlier. When omitted, the six months end at the most recent month with significant reporting in the area.","name":"date","in":"query"}],"responses":{"200":{"description":"The incidents in the requested area and window, with a count for each crime category.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrimeIncidentsListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/safety/crime/stats":{"get":{"operationId":"getCrimeAreaStats","x-speakeasy-name-override":"getCrimeAreaStats","tags":["Safety"],"summary":"Get monthly crime category counts within a radius","description":"Count crimes by category and month for the area within `radius` metres of a point. The response covers the 12 months ending at the most recent month with significant reporting in that area, oldest month first, and leaves out months with no recorded incidents. Use it to chart how an area's crime mix moves over a year without pulling every incident.","parameters":[{"schema":{"type":"string","pattern":"^-?\\d+\\.?\\d*$","description":"Latitude of the point to search around, in WGS84 decimal degrees.","example":"51.5074"},"required":true,"description":"Latitude of the point to search around, in WGS84 decimal degrees.","name":"latitude","in":"query"},{"schema":{"type":"string","pattern":"^-?\\d+\\.?\\d*$","description":"Longitude of the point to search around, in WGS84 decimal degrees.","example":"-0.1278"},"required":true,"description":"Longitude of the point to search around, in WGS84 decimal degrees.","name":"longitude","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","default":"1000","description":"How far to search around the point, in metres. Defaults to 1000. Minimum 100, maximum 50000.","example":"1000"},"required":false,"description":"How far to search around the point, in metres. Defaults to 1000. Minimum 100, maximum 50000.","name":"radius","in":"query"}],"responses":{"200":{"description":"One entry per month, each holding the incident count for every crime category.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonthlyCategoryStatsListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/safety/crime/category-stats":{"get":{"operationId":"getCrimePointStats","x-speakeasy-name-override":"getCrimePointStats","tags":["Safety"],"summary":"Get per-point monthly crime category counts within a radius","description":"Count crimes by category and month over the same 12-month window as `/stats`, but grouped by each anonymised reporting point rather than for the area as a whole. Every point inside the radius gets its own entry per month, with the coordinates needed to place it on a map, which is what heat-map style overlays require.","parameters":[{"schema":{"type":"string","pattern":"^-?\\d+\\.?\\d*$","description":"Latitude of the point to search around, in WGS84 decimal degrees.","example":"51.5074"},"required":true,"description":"Latitude of the point to search around, in WGS84 decimal degrees.","name":"latitude","in":"query"},{"schema":{"type":"string","pattern":"^-?\\d+\\.?\\d*$","description":"Longitude of the point to search around, in WGS84 decimal degrees.","example":"-0.1278"},"required":true,"description":"Longitude of the point to search around, in WGS84 decimal degrees.","name":"longitude","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","default":"1000","description":"How far to search around the point, in metres. Defaults to 1000. Minimum 100, maximum 50000.","example":"1000"},"required":false,"description":"How far to search around the point, in metres. Defaults to 1000. Minimum 100, maximum 50000.","name":"radius","in":"query"}],"responses":{"200":{"description":"One entry per reporting point and month, each holding the count for every crime category.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PointCategoryStatsListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/safety/catalog":{"get":{"operationId":"listCatalogCountries","x-speakeasy-name-override":"listCatalogCountries","tags":["Safety"],"summary":"List crime data availability by country","description":"List the countries that hold crime data and, for each one, the yearly and monthly periods that have been ingested, most recent first. Call this before a dated query to find out which periods can be asked for; the per-country endpoint breaks the same information out into one entry per period. Periods come back as `YYYY` for yearly entries and `YYYY-MM` for monthly ones, ready to pass straight into the other safety endpoints.","parameters":[{"schema":{"type":"boolean","example":true,"description":"When true, only periods that have been ingested appear in the country buckets. Defaults to true."},"required":false,"description":"When true, only periods that have been ingested appear in the country buckets. Defaults to true.","name":"onlyAvailable","in":"query"}],"responses":{"200":{"description":"The yearly and monthly periods held for each country.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrimeCatalogCountriesResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/safety/catalog/{country}":{"get":{"operationId":"getCatalogByCountry","x-speakeasy-name-override":"getCatalogByCountry","tags":["Safety"],"summary":"Get crime data availability for a single country","description":"Return one entry per period held for the supplied country, newest period first, each saying whether that period has been ingested. Narrow the result to one granularity with `periodType=yearly` or `periodType=monthly`. Periods come back as `YYYY` for yearly entries and `YYYY-MM` for monthly ones.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Country to return catalogue entries for, for example 'england' or 'wales'.","example":"england"},"required":true,"description":"Country to return catalogue entries for, for example 'england' or 'wales'.","name":"country","in":"path"},{"schema":{"type":"boolean","example":true,"description":"When true, only periods that have been ingested are returned. Defaults to true."},"required":false,"description":"When true, only periods that have been ingested are returned. Defaults to true.","name":"onlyAvailable","in":"query"},{"schema":{"type":"string","enum":["yearly","monthly"],"description":"Return only entries of this granularity. When omitted, both yearly and monthly entries come back.","example":"monthly"},"required":false,"description":"Return only entries of this granularity. When omitted, both yearly and monthly entries come back.","name":"periodType","in":"query"}],"responses":{"200":{"description":"One entry per period held for the country, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CrimeCatalogByCountryResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/safety/geography/metrics":{"get":{"operationId":"getGeographyMetrics","x-speakeasy-name-override":"getGeographyMetrics","tags":["Safety"],"summary":"Get crime metrics for one or more geographic areas (England and Wales)","description":"Return scored crime metrics for one or more areas across one or more months, each with a per-category breakdown and an optional monthly history. Areas are identified by GSS code at eight levels: Lower Layer Super Output Area (LSOA, `E01`/`W01`), Middle Layer Super Output Area (MSOA, `E02`/`W02`), ward (`E05`/`W05`), built-up area (`E63`/`W45`/`K08`), local authority district or unitary authority (`E06`-`E09`, `W06`), county (`E10`), English region (`E12`) and country (`E92`, `W92`). Coverage is England and Wales; codes at other levels, such as parishes, and codes in Scotland or Northern Ireland come back as `data: []`. Ward and built-up-area figures are aggregated from the Lower Layer Super Output Areas assigned to each area rather than counted on its own boundary, so they are approximations, and `geographyFit` on every row reports how much of the area's footprint those smaller areas cover. A built-up area smaller than the Lower Layer Super Output Area containing it has no figures and comes back as `data: []`. Percentiles rank an area against others of the same type, so a ward is ranked among wards and not among districts. Every month summarises the trailing 24-month window ending at that month, so counts are window totals and rates are per 1,000 residents per year. Months are published two months in arrears, roughly monthly; the catalogue endpoint lists the months held. Scores are null, never 0, where a police force did not report; read `dataAvailability` beside every number. By default the response carries one row per area and month; with `mergeAreas=true` it carries one row per month, with counts and population summed across every requested area and scores, percentiles and trends set to null because they cannot be combined across areas. Choose the months either explicitly with `periods=YYYY-MM,YYYY-MM` or as a range with `startDate` and `endDate`, never both, and set how far each row's history reaches back with `months`, which defaults to 12. An empty result comes back as `data: []` with `total_count: 0`, never as a 204.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Comma-separated area codes to return metrics for: Lower Layer Super Output Area (LSOA), ward or authority codes. Whitespace around each code is trimmed. At least one code is required, and at most 100 per request.","example":"E01000001,E01000002"},"required":true,"description":"Comma-separated area codes to return metrics for: Lower Layer Super Output Area (LSOA), ward or authority codes. Whitespace around each code is trimmed. At least one code is required, and at most 100 per request.","name":"geographicCodes","in":"query"},{"schema":{"type":"string","description":"Comma-separated months to return, each in `YYYY-MM` form. Supply either this or `startDate` with `endDate`, never both.","example":"2024-01,2024-02"},"required":false,"description":"Comma-separated months to return, each in `YYYY-MM` form. Supply either this or `startDate` with `endDate`, never both.","name":"periods","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$","description":"First month of the range to return, in `YYYY-MM` form, inclusive. Requires `endDate`.","example":"2023-12"},"required":false,"description":"First month of the range to return, in `YYYY-MM` form, inclusive. Requires `endDate`.","name":"startDate","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}-\\d{2}$","description":"Last month of the range to return, in `YYYY-MM` form, inclusive. Requires `startDate`.","example":"2024-02"},"required":false,"description":"Last month of the range to return, in `YYYY-MM` form, inclusive. Requires `startDate`.","name":"endDate","in":"query"},{"schema":{"type":"boolean","example":false,"description":"When true, every requested area is combined into a single row per month. Defaults to false. Scores, percentiles and trends come back null on merged rows, because they cannot be combined across areas."},"required":false,"description":"When true, every requested area is combined into a single row per month. Defaults to false. Scores, percentiles and trends come back null on merged rows, because they cannot be combined across areas.","name":"mergeAreas","in":"query"},{"schema":{"type":"boolean","example":true,"description":"When true, each row carries the monthly history leading up to its period. Defaults to true."},"required":false,"description":"When true, each row carries the monthly history leading up to its period. Defaults to true.","name":"includeTimeSeries","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","default":"12","description":"How many months of history each row carries. Defaults to 12. Minimum 1, maximum 60.","example":"12"},"required":false,"description":"How many months of history each row carries. Defaults to 12. Minimum 1, maximum 60.","name":"months","in":"query"}],"responses":{"200":{"description":"The metric rows for the requested areas and months. Areas with no scored data are left out, and a request that matches nothing returns `data: []`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeographyMetricsListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/epc/{locationId}":{"get":{"operationId":"getEpcByLocationId","tags":["EPC"],"summary":"Get EPC certificates by location ID","description":"Returns every certificate held for one location, most recently lodged first: domestic and non-domestic Energy Performance Certificates as well as Display Energy Certificates. Each one carries its energy ratings, fabric assessment, recommended improvements with costed estimates, and its Minimum Energy Efficiency Standard status. Returns up to 1000 certificates per request; page through the rest with `limit` and `offset`.","parameters":[{"schema":{"type":"string","pattern":"^\\d+$","description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN)."},"required":true,"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN).","name":"locationId","in":"path"},{"schema":{"type":"string","description":"Maximum number of items to return. Defaults to 100. Minimum 1, maximum 1000."},"required":false,"description":"Maximum number of items to return. Defaults to 100. Minimum 1, maximum 1000.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Number of results to skip before the first one returned. Defaults to 0."},"required":false,"description":"Number of results to skip before the first one returned. Defaults to 0.","name":"offset","in":"query"},{"schema":{"type":"string","enum":["domestic","non_domestic","dec"],"description":"Return only certificates of this type. Omit to get every type."},"required":false,"description":"Return only certificates of this type. Omit to get every type.","name":"certificateType","in":"query"}],"responses":{"200":{"description":"The EPC certificates held for this location.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Type of this response. Always `list`."},"url":{"type":"string","description":"The path that produced this list."},"has_more":{"type":"boolean","description":"True when further results exist beyond this page."},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Identifier for this certificate within the API."},"certificateType":{"type":"string","enum":["domestic","non_domestic","dec"],"description":"What kind of certificate this is. `domestic` and `non_domestic` are Energy Performance Certificates for dwellings and for other buildings; `dec` is a Display Energy Certificate, which rates a public building's measured energy use."},"assessmentMethodology":{"type":"string","enum":["rdsap","sap","sbem","dsm","operational"],"description":"Which procedure the assessment followed. `rdsap` is the reduced-data procedure for existing dwellings and `sap` the full procedure for new ones; `sbem` covers non-domestic buildings and `dsm` the dynamic simulation modelling used for the most complex of them; `operational` is the metered assessment behind a Display Energy Certificate."},"source":{"type":"string","enum":["mhclg","scottish_government"],"description":"Which national register the certificate came from: `mhclg` for England and Wales, `scottish_government` for Scotland."},"sourceReference":{"type":"string","description":"The certificate's own reference number in the register it came from."},"buildingReferenceNumber":{"type":["string","null"],"description":"Reference that ties successive assessments of the same building together. It is issued by the source register and is not a location ID."},"locationId":{"type":["integer","null"],"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). Null when the certificate has not been matched to a location."},"address":{"type":"object","properties":{"displayAddress":{"type":"string","description":"The address formatted as a single line, ready to show to an end user."},"line1":{"type":["string","null"],"description":"First line of the address."},"line2":{"type":["string","null"],"description":"Second line of the address, where there is one."},"line3":{"type":["string","null"],"description":"Third line of the address. Scottish certificates carry the post town here."},"postTown":{"type":["string","null"],"description":"The post town."},"postcode":{"type":"string","description":"The full UK postcode."},"postcodeNoSpace":{"type":"string","description":"The same postcode with the space removed, for matching."}},"required":["displayAddress","line1","line2","line3","postTown","postcode","postcodeNoSpace"],"description":"The certificate's address, in the same form as the rest of the API."},"coordinates":{"type":["object","null"],"properties":{"latitude":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees."},"longitude":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees."}},"required":["latitude","longitude"],"description":"Where the building is. Taken from the matched location where there is one, otherwise the centre of the postcode."},"localAuthority":{"type":["string","null"],"description":"ONS code for the local authority the building sits in."},"localAuthorityLabel":{"type":["string","null"],"description":"Name of that local authority."},"constituency":{"type":["string","null"],"description":"Code for the parliamentary constituency, or on Scottish certificates the electoral ward."},"constituencyLabel":{"type":["string","null"],"description":"Name of that constituency or ward."},"county":{"type":["string","null"],"description":"The county. England and Wales only."},"dataZone":{"type":["string","null"],"description":"Code for the Scottish data zone the building sits in. Scotland only."},"inspectionDate":{"type":"string","description":"When the assessor inspected the building, as an ISO 8601 date."},"lodgementDate":{"type":"string","description":"When the certificate was lodged on the national register, as an ISO 8601 date."},"validUntil":{"type":["string","null"],"description":"When the certificate expires, as an ISO 8601 date. Energy Performance Certificates run for ten years from lodgement; Display Energy Certificates run for one."},"propertyType":{"type":["string","null"],"description":"What kind of building this is, mapped to a standard set of categories. Domestic certificates use `house`, `flat`, `bungalow`, `maisonette` or `park_home`; non-domestic certificates use categories such as `office_workshop`, `retail_financial` and `storage_distribution`. `propertyTypeExternal` carries the wording used on the certificate."},"propertyTypeExternal":{"type":["string","null"],"description":"The property type exactly as the certificate words it, for example 'House' or 'Offices and Workshop businesses'."},"totalFloorArea":{"type":["number","null"],"description":"Floor area of the building, in square metres. Domestic certificates give the total internal floor area; non-domestic certificates give the conditioned floor area."},"transactionType":{"type":["string","null"],"enum":["marketed_sale","non_marketed_sale","rental","new_dwelling","voluntary","voluntary_reissue","stock_condition_survey","grant_scheme","display_public_building","construction","other",null],"description":"What prompted the assessment, mapped to a standard set of categories."},"transactionTypeExternal":{"type":["string","null"],"description":"What prompted the assessment, exactly as the certificate words it."},"rating":{"type":"object","properties":{"current":{"type":"object","properties":{"band":{"type":"string","enum":["A+","A","B+","B","C+","C","D+","D","E+","E","F+","F","G"],"description":"Energy efficiency band, where A+ and A are the most efficient and G the least. Domestic certificates use A to G, non-domestic certificates add A+, and Scotland non-domestic certificates also use half-bands such as B+ and C+."},"score":{"type":"number","description":"Numeric score behind the band, read alongside `scoreType`. A `sap` score runs from 1 to 100 and higher is better. An `asset` score is in kg CO2 per m² and an `operational` score is measured against a benchmark; both are unbounded and lower is better. An `epi` score is in kg CO2 per m² calculated with Scottish weather data."},"scoreType":{"type":"string","enum":["sap","asset","operational","epi"],"description":"Which scale `score` is on. Read it before comparing scores across certificates."}},"required":["band","score","scoreType"],"description":"The rating the building holds as assessed."},"potential":{"type":["object","null"],"properties":{"band":{"type":"string","enum":["A+","A","B+","B","C+","C","D+","D","E+","E","F+","F","G"],"description":"Energy efficiency band, where A+ and A are the most efficient and G the least. Domestic certificates use A to G, non-domestic certificates add A+, and Scotland non-domestic certificates also use half-bands such as B+ and C+."},"score":{"type":"number","description":"Numeric score behind the band, read alongside `scoreType`. A `sap` score runs from 1 to 100 and higher is better. An `asset` score is in kg CO2 per m² and an `operational` score is measured against a benchmark; both are unbounded and lower is better. An `epi` score is in kg CO2 per m² calculated with Scottish weather data."},"scoreType":{"type":"string","enum":["sap","asset","operational","epi"],"description":"Which scale `score` is on. Read it before comparing scores across certificates."}},"required":["band","score","scoreType"],"description":"The rating the building would reach if the recommended improvements were carried out. Null on Display Energy Certificates, which rate measured use rather than potential, and on England and Wales non-domestic certificates, which do not publish one. Scotland non-domestic does."},"carbonNeutral":{"type":"boolean","description":"True when the building is rated carbon neutral. Scotland non-domestic certificates record this as a 'Carbon Neu' band, which is published here as band `A+` with this flag set."}},"required":["current","potential","carbonNeutral"],"description":"The building's energy rating. Every certificate type carries one, so filter on `rating.current.band` to compare efficiency across types."},"emissions":{"type":"object","properties":{"co2Current":{"type":["number","null"],"description":"Annual carbon dioxide emissions at the assessed efficiency. Domestic certificates report tonnes per year and non-domestic certificates report kg CO2 per m² per year; read `co2Unit` for the unit that applies to this record."},"co2Potential":{"type":["number","null"],"description":"Annual carbon dioxide emissions once the recommended improvements are carried out. Domestic only; null on non-domestic certificates and Display Energy Certificates."},"co2PerFloorArea":{"type":["number","null"],"description":"Annual carbon dioxide emissions per square metre of floor area, in kg CO2 per m² per year. On non-domestic certificates this is the building emission rate."},"co2Unit":{"type":"string","enum":["tonnes_per_year","kg_co2_per_m2_per_year"],"description":"The unit `co2Current` is expressed in. Domestic certificates use `tonnes_per_year`; non-domestic certificates and Display Energy Certificates use `kg_co2_per_m2_per_year`."},"environmentalScoreCurrent":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"Environmental impact score from 1 to 100, where higher is better. Domestic only."},"environmentalScorePotential":{"type":["integer","null"],"minimum":1,"maximum":100,"description":"The environmental impact score the property would reach once the recommended improvements are carried out, on the same 1 to 100 scale. Domestic only."},"energyConsumptionCurrent":{"type":["number","null"],"description":"Annual energy consumption at the assessed efficiency. Domestic certificates report kWh per year and non-domestic certificates report kWh per m² per year; read `energyConsumptionUnit` for the unit that applies to this record."},"energyConsumptionPotential":{"type":["number","null"],"description":"Annual energy consumption once the recommended improvements are carried out. Domestic only."},"energyConsumptionUnit":{"type":["string","null"],"enum":["kwh_per_year","kwh_per_m2_per_year",null],"description":"The unit `energyConsumptionCurrent` is expressed in."}},"required":["co2Current","co2Potential","co2PerFloorArea","co2Unit","environmentalScoreCurrent","environmentalScorePotential","energyConsumptionCurrent","energyConsumptionPotential","energyConsumptionUnit"],"description":"Carbon dioxide emissions, environmental impact scores and energy consumption."},"runningCosts":{"type":["object","null"],"properties":{"heating":{"type":"object","properties":{"current":{"type":"integer","description":"Estimated annual heating cost at the assessed efficiency, in GBP."},"potential":{"type":"integer","description":"Estimated annual heating cost once the recommended improvements are carried out, in GBP."}},"required":["current","potential"],"description":"Estimated annual heating cost, as assessed and after improvement."},"hotWater":{"type":"object","properties":{"current":{"type":"integer","description":"Estimated annual hot water cost at the assessed efficiency, in GBP."},"potential":{"type":"integer","description":"Estimated annual hot water cost once the recommended improvements are carried out, in GBP."}},"required":["current","potential"],"description":"Estimated annual hot water cost, as assessed and after improvement."},"lighting":{"type":"object","properties":{"current":{"type":"integer","description":"Estimated annual lighting cost at the assessed efficiency, in GBP."},"potential":{"type":"integer","description":"Estimated annual lighting cost once the recommended improvements are carried out, in GBP."}},"required":["current","potential"],"description":"Estimated annual lighting cost, as assessed and after improvement."}},"required":["heating","hotWater","lighting"],"description":"Estimated annual running costs in GBP. Domestic only; null on non-domestic certificates and Display Energy Certificates."},"fabric":{"type":["object","null"],"properties":{"walls":{"type":"object","properties":{"construction":{"type":["string","null"],"enum":["cavity","solid_brick","timber_frame","sandstone_or_limestone","sandstone","granite_or_whinstone","granite","system_built","solid_stone","cob","park_home","basement","curtain_wall",null],"description":"How the external walls are built."},"material":{"type":["string","null"],"description":"The wall material, for example 'brick', where the assessor's description identifies one."},"insulationType":{"type":["string","null"],"enum":["none","as_built","filled_cavity","external","internal","filled_cavity_and_external","filled_cavity_and_internal","partial","retro_fitted","loft","rafter",null],"description":"How the walls are insulated, if at all."},"insulationPresent":{"type":["boolean","null"],"description":"True when the walls are insulated."},"insulationAssumed":{"type":"boolean","description":"True when the assessor assumed the insulation rather than confirming it."},"thermalTransmittance":{"type":["number","null"],"description":"Thermal transmittance (U-value) of the walls, in W/m²K, where the assessment reports one."},"description":{"type":["string","null"],"description":"The assessor's own description of the walls, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient the walls are, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How the walls score for environmental impact, on the certificate's five-point scale."},"dataQuality":{"type":["string","null"],"enum":["truncated_thermal_transmittance","quality_label_only","welsh_language","corrupted_encoding","source_error",null],"description":"Set when the source value could not be read as recorded, giving the reason. Null when the value came through intact."}},"required":["construction","material","insulationType","insulationPresent","insulationAssumed","thermalTransmittance","description","energyEfficiency","environmentalEfficiency","dataQuality"],"description":"The external walls and their insulation."},"roof":{"type":"object","properties":{"roofType":{"type":["string","null"],"enum":["pitched","flat","thatched","another_dwelling_above","other_premises_above","roof_room",null],"description":"How the roof is built, including the cases where another dwelling or premises sits above."},"insulationType":{"type":["string","null"],"enum":["none","as_built","filled_cavity","external","internal","filled_cavity_and_external","filled_cavity_and_internal","partial","retro_fitted","loft","rafter",null],"description":"How the roof is insulated, if at all."},"insulationDepthMm":{"type":["integer","null"],"description":"Depth of the loft insulation, in millimetres."},"insulationPresent":{"type":["boolean","null"],"description":"True when the roof is insulated."},"insulationAssumed":{"type":"boolean","description":"True when the assessor assumed the insulation rather than confirming it."},"thermalTransmittance":{"type":["number","null"],"description":"Thermal transmittance (U-value) of the roof, in W/m²K, where the assessment reports one."},"description":{"type":["string","null"],"description":"The assessor's own description of the roof, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient the roof is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How the roof scores for environmental impact, on the certificate's five-point scale."},"dataQuality":{"type":["string","null"],"enum":["truncated_thermal_transmittance","quality_label_only","welsh_language","corrupted_encoding","source_error",null],"description":"Set when the source value could not be read as recorded, giving the reason. Null when the value came through intact."}},"required":["roofType","insulationType","insulationDepthMm","insulationPresent","insulationAssumed","thermalTransmittance","description","energyEfficiency","environmentalEfficiency","dataQuality"],"description":"The roof and its insulation."},"floor":{"type":"object","properties":{"floorType":{"type":["string","null"],"enum":["solid","suspended_timber","suspended_sealed","another_dwelling_below","other_premises_below",null],"description":"How the ground floor is built, including the cases where another dwelling or premises sits below."},"insulationPresent":{"type":["boolean","null"],"description":"True when the floor is insulated."},"insulationAssumed":{"type":"boolean","description":"True when the assessor assumed the insulation rather than confirming it."},"insulationType":{"type":["string","null"],"enum":["none","as_built","filled_cavity","external","internal","filled_cavity_and_external","filled_cavity_and_internal","partial","retro_fitted","loft","rafter",null],"description":"How the floor is insulated, where insulation is present."},"thermalTransmittance":{"type":["number","null"],"description":"Thermal transmittance (U-value) of the floor, in W/m²K, where the assessment reports one."},"description":{"type":["string","null"],"description":"The assessor's own description of the floor, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient the floor is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How the floor scores for environmental impact, on the certificate's five-point scale."},"dataQuality":{"type":["string","null"],"enum":["truncated_thermal_transmittance","quality_label_only","welsh_language","corrupted_encoding","source_error",null],"description":"Set when the source value could not be read as recorded, giving the reason. Null when the value came through intact."}},"required":["floorType","insulationPresent","insulationAssumed","insulationType","thermalTransmittance","description","energyEfficiency","environmentalEfficiency","dataQuality"],"description":"The ground floor and its insulation."},"mainHeating":{"type":"object","properties":{"systemType":{"type":["string","null"],"enum":["boiler_radiators","boiler_underfloor","storage_heaters","room_heaters","warm_air","heat_pump_radiators","heat_pump_underfloor","underfloor_electric","community_scheme","micro_chp","none_assumed",null],"description":"What kind of main heating system is installed."},"fuel":{"type":["string","null"],"enum":["mains_gas","lpg","oil","electricity","biomass","coal","anthracite","smokeless_fuel","biogas","district_heating","heat_pump","dual_fuel","waste_heat","other",null],"description":"The fuel this heating system runs on."},"heatPumpType":{"type":["string","null"],"enum":["air_source","ground_source","water_source",null],"description":"Where the heat pump draws its heat from, where the system is a heat pump."},"isMultiSystem":{"type":"boolean","description":"True when the certificate records more than one heating system."},"description":{"type":["string","null"],"description":"The assessor's own description of the heating system, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient the heating system is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How the heating system scores for environmental impact, on the certificate's five-point scale."},"dataQuality":{"type":["string","null"],"enum":["truncated_thermal_transmittance","quality_label_only","welsh_language","corrupted_encoding","source_error",null],"description":"Set when the source value could not be read as recorded, giving the reason. Null when the value came through intact."}},"required":["systemType","fuel","heatPumpType","isMultiSystem","description","energyEfficiency","environmentalEfficiency","dataQuality"],"description":"The main heating system."},"windows":{"type":"object","properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"required":["description","energyEfficiency","environmentalEfficiency"],"description":"The windows and their glazing."},"heatingControls":{"type":"object","properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"required":["description","energyEfficiency","environmentalEfficiency"],"description":"How the heating is controlled."},"hotWater":{"type":"object","properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"required":["description","energyEfficiency","environmentalEfficiency"],"description":"The hot water system."},"lighting":{"type":"object","properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"required":["description","energyEfficiency","environmentalEfficiency"],"description":"The lighting installed."},"secondaryHeating":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"required":["description","energyEfficiency","environmentalEfficiency"],"description":"Any secondary heating system. Null when the property has none."},"airTightness":{"type":["object","null"],"properties":{"description":{"type":["string","null"],"description":"The assessor's own description of this component, as written on the certificate."},"energyEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How energy efficient this component is, on the certificate's five-point scale."},"environmentalEfficiency":{"type":["string","null"],"enum":["very_good","good","average","poor","very_poor",null],"description":"How this component scores for environmental impact, on the certificate's five-point scale."}},"required":["description","energyEfficiency","environmentalEfficiency"],"description":"The air tightness assessment. Scotland only; null on England and Wales certificates."}},"required":["walls","roof","floor","mainHeating","windows","heatingControls","hotWater","lighting","secondaryHeating","airTightness"],"description":"Component-by-component assessment of the building fabric. Domestic only; null on non-domestic certificates and Display Energy Certificates."},"systems":{"type":"object","properties":{"mainFuel":{"type":["string","null"],"enum":["mains_gas","lpg","oil","electricity","biomass","coal","anthracite","smokeless_fuel","biogas","district_heating","heat_pump","dual_fuel","waste_heat","other",null],"description":"The main fuel the building uses, mapped to a standard set of categories. `mainFuelExternal` carries the wording used on the certificate."},"mainFuelExternal":{"type":["string","null"],"description":"The fuel exactly as the certificate words it, for example 'mains gas (not community)' or 'electricity (7-hour tariff)'."},"mainsGas":{"type":["boolean","null"],"description":"True when the property has a mains gas connection. Domestic only; null when the certificate does not say."},"energyTariff":{"type":["string","null"],"enum":["single","dual","off_peak_7hr","off_peak_10hr","off_peak_18hr","off_peak_24hr","unknown",null],"description":"The electricity tariff the property is on, including the off-peak arrangements. Domestic only."},"mainHeatingControls":{"type":["string","null"],"description":"The heating controls recorded on the certificate, as a source code. Domestic only."},"renewables":{"type":"object","properties":{"solarThermal":{"type":["boolean","null"],"description":"True when the building has solar thermal panels heating its hot water."},"photovoltaic":{"type":["object","null"],"properties":{"present":{"type":"boolean","description":"True when solar photovoltaic panels are installed."},"supplyPercentage":{"type":["number","null"],"description":"The photovoltaic supply figure recorded on the certificate, as a percentage. Domestic only."}},"required":["present","supplyPercentage"],"description":"The solar photovoltaic installation."},"windTurbines":{"type":["integer","null"],"description":"Number of wind turbines installed. Domestic only."},"description":{"type":["string","null"],"description":"The renewable sources in the assessor's own words. Non-domestic only."}},"required":["solarThermal","photovoltaic","windTurbines","description"],"description":"Renewable energy generated on site."},"ventilation":{"type":["string","null"],"enum":["natural","mechanical_extract","mechanical_supply_and_extract",null],"description":"How the property is ventilated. Domestic only."},"heatLossCorridor":{"type":["string","null"],"enum":["no_corridor","heated_corridor","unheated_corridor",null],"description":"Whether the dwelling is reached by a corridor and whether that corridor is heated. Recorded for flats and maisonettes only."},"unheatedCorridorLength":{"type":["number","null"],"description":"Length of the unheated corridor, in metres. Recorded for flats and maisonettes only."},"airConditioning":{"type":["object","null"],"properties":{"present":{"type":"boolean","description":"True when the building has air conditioning."},"kwRating":{"type":["number","null"],"description":"Rated capacity of the air conditioning system, in kW."},"estimatedKwRating":{"type":["number","null"],"description":"Estimated capacity of the air conditioning system, in kW, used when the rated capacity is unknown."},"inspectionStatus":{"type":["string","null"],"enum":["completed","commissioned","not_commissioned","not_relevant","unknown",null],"description":"Whether an air conditioning inspection has been carried out, commissioned, or is not relevant."}},"required":["present","kwRating","estimatedKwRating","inspectionStatus"],"description":"The building's air conditioning. Recorded on non-domestic certificates and Display Energy Certificates; null for domestic."}},"required":["mainFuel","mainFuelExternal","mainsGas","energyTariff","mainHeatingControls","renewables","ventilation","heatLossCorridor","unheatedCorridorLength","airConditioning"],"description":"The building's energy systems: fuel, heating, renewables and ventilation."},"domesticDetails":{"type":["object","null"],"properties":{"builtForm":{"type":["string","null"],"enum":["detached","semi_detached","mid_terrace","end_terrace","enclosed_mid_terrace","enclosed_end_terrace",null],"description":"How the dwelling sits in relation to its neighbours."},"tenure":{"type":["string","null"],"enum":["owner_occupied","rented_social","rented_private","unknown",null],"description":"Whether the dwelling is owner occupied or rented, and if rented, socially or privately."},"constructionAge":{"type":["object","null"],"properties":{"startYear":{"type":["integer","null"],"description":"First year of the construction period. Null when the band is open-ended, such as 'before 1900'."},"endYear":{"type":["integer","null"],"description":"Last year of the construction period. Null when the band is open-ended, such as '2007 onwards'."},"midYear":{"type":["integer","null"],"description":"Midpoint of the construction period, for when a single year is needed."},"isExact":{"type":"boolean","description":"True when the certificate gives an exact year of construction rather than a band."}},"required":["startYear","endYear","midYear","isExact"],"description":"The period the dwelling was built in, as a year range."},"constructionAgeBandExternal":{"type":["string","null"],"description":"The construction age band exactly as the certificate words it, for example 'England and Wales: 1930-1949' or 'before 1919'."},"habitableRooms":{"type":["integer","null"],"description":"Number of habitable rooms."},"heatedRooms":{"type":["integer","null"],"description":"Number of heated rooms."},"floorLevel":{"type":["string","null"],"description":"Which floor the dwelling is on, as recorded on the certificate. Recorded for flats."},"flatTopStorey":{"type":["boolean","null"],"description":"True when the flat is on the top storey of its building."},"flatStoreyCount":{"type":["integer","null"],"description":"Number of storeys in the building the flat is in."},"extensionCount":{"type":["integer","null"],"description":"Number of extensions the dwelling has."},"openFireplaces":{"type":["integer","null"],"description":"Number of open fireplaces."},"floorHeight":{"type":["number","null"],"description":"Average floor-to-ceiling height, in metres."},"glazing":{"type":"object","properties":{"type":{"type":["string","null"],"enum":["single","double_pre_2002","double_post_2002","double_unknown","triple","secondary","secondary_low_emissivity","not_defined",null],"description":"What kind of glazing is fitted, with double glazing split by whether it was installed before 2002."},"proportion":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Percentage of the windows that are double or triple glazed, from 0 to 100."},"area":{"type":["string","null"],"enum":["much_less_than_typical","less_than_typical","normal","more_than_typical","much_more_than_typical",null],"description":"How much glazing the dwelling has compared with a typical property of its type. Only older assessments carry it, as the current assessment procedure no longer records it."}},"required":["type","proportion","area"],"description":"The dwelling's glazing."},"lowEnergyLighting":{"type":["integer","null"],"minimum":0,"maximum":100,"description":"Percentage of the light fittings that are low energy, from 0 to 100."},"spaceHeatingDemand":{"type":["number","null"],"description":"Annual space heating demand, in kWh per year. Scotland only."},"waterHeatingDemand":{"type":["number","null"],"description":"Annual water heating demand, in kWh per year. Scotland only."},"threeYearEnergyCostCurrent":{"type":["number","null"],"description":"Estimated energy cost over three years at the assessed efficiency, in GBP. Scotland only."},"threeYearEnergySavingPotential":{"type":["number","null"],"description":"Estimated energy saving over three years if the recommended improvements are carried out, in GBP. Scotland only."},"impactLoftInsulation":{"type":["number","null"],"description":"Estimated change in SAP score from installing loft insulation. Scotland only."},"impactCavityWallInsulation":{"type":["number","null"],"description":"Estimated change in SAP score from installing cavity wall insulation. Scotland only."},"impactSolidWallInsulation":{"type":["number","null"],"description":"Estimated change in SAP score from installing solid wall insulation. Scotland only."},"lzcEnergySources":{"type":["string","null"],"description":"The low and zero carbon energy sources present, as described on the certificate. Scotland only."}},"required":["builtForm","tenure","constructionAge","constructionAgeBandExternal","habitableRooms","heatedRooms","floorLevel","flatTopStorey","flatStoreyCount","extensionCount","openFireplaces","floorHeight","glazing","lowEnergyLighting","spaceHeatingDemand","waterHeatingDemand","threeYearEnergyCostCurrent","threeYearEnergySavingPotential","impactLoftInsulation","impactCavityWallInsulation","impactSolidWallInsulation","lzcEnergySources"],"description":"Details that apply to dwellings only: construction, rooms, glazing and the Scotland-specific measures. Null on non-domestic certificates and Display Energy Certificates."},"benchmarks":{"type":["object","null"],"properties":{"newBuild":{"type":["number","null"],"description":"The benchmark rating an equivalent new building would achieve. On Scottish certificates this is in kg CO2 per m² per year."},"newBuildBand":{"type":["string","null"],"enum":["A+","A","B+","B","C+","C","D+","D","E+","E","F+","F","G",null],"description":"Band for the new build benchmark. Scotland only."},"existingStock":{"type":["string","null"],"description":"The benchmark for typical existing stock. England and Wales only."},"standardEmissions":{"type":["number","null"],"description":"Standard Emission Rate: the improvement-adjusted baseline the building is measured against, in kg CO2 per m² per year. England and Wales only."},"targetEmissions":{"type":["number","null"],"description":"Target Emission Rate: the emissions the Building Regulations require of this building, in kg CO2 per m² per year."},"typicalEmissions":{"type":["number","null"],"description":"Typical Emission Rate: the industry comparison baseline, in kg CO2 per m² per year. England and Wales only."},"buildingEmissions":{"type":["number","null"],"description":"Building Emission Rate: the building's own annual emissions, in kg CO2 per m² per year."},"buildingLevel":{"type":["integer","null"],"minimum":3,"maximum":5,"description":"How complex the building is to assess, from 3 to 5. Level 3 covers small, naturally ventilated buildings, level 4 those with more sophisticated heating and cooling, and level 5 the most complex, such as airports and large shopping centres, which need dynamic simulation modelling. England and Wales only."},"buildingEnvironment":{"type":["string","null"],"enum":["heating_and_natural_ventilation","heating_and_mechanical_ventilation","air_conditioning","mixed_mode_natural","mixed_mode_mechanical","unconditioned",null],"description":"How the building is serviced for heating, ventilation and cooling, which sets the basis for its emissions calculation."},"meets2002Standard":{"type":["boolean","null"],"description":"True when the building meets the 2002 Scottish building standards. Scotland only."},"electricitySource":{"type":["string","null"],"description":"Where the building's electricity comes from. Scotland only."},"approximateEnergyUse":{"type":["number","null"],"description":"Total energy use less on-site generation, in kWh per m² per year. Scotland only."}},"required":["newBuild","newBuildBand","existingStock","standardEmissions","targetEmissions","typicalEmissions","buildingEmissions","buildingLevel","buildingEnvironment","meets2002Standard","electricitySource","approximateEnergyUse"],"description":"Benchmarks and complexity classification for non-domestic buildings. Null on domestic certificates."},"scotlandNativeRating":{"type":["object","null"],"properties":{"currentRating":{"type":"number","description":"The building's energy performance rating calculated with Scottish weather data, in kg CO2 per m² per year."},"currentBand":{"type":"string","enum":["A+","A","B+","B","C+","C","D+","D","E+","E","F+","F","G"],"description":"Band for that rating. Scotland uses half-bands such as B+ and C+, and a carbon neutral building is published here as `A+`."},"potentialRating":{"type":["number","null"],"description":"The rating the building would reach if the recommended improvements were carried out. Scotland publishes this; England and Wales does not."},"potentialBand":{"type":["string","null"],"enum":["A+","A","B+","B","C+","C","D+","D","E+","E","F+","F","G",null],"description":"Band for the achievable rating."}},"required":["currentRating","currentBand","potentialRating","potentialBand"],"description":"Scotland's own non-domestic rating, calculated with Scottish weather data. Null on domestic certificates and on England and Wales certificates."},"operationalPerformance":{"type":["object","null"],"properties":{"currentRating":{"type":"number","description":"Operational rating for the current year, comparing the building's carbon dioxide emissions with the benchmark for its type. 100 is typical for the type and lower is better. A value of 9999 means the assessment is incomplete."},"ratingBand":{"type":"string","enum":["A+","A","B+","B","C+","C","D+","D","E+","E","F+","F","G"],"description":"Band for the operational rating. Display Energy Certificates run A to G, with no A+."},"yr1Rating":{"type":["number","null"],"description":"Operational rating for the previous year."},"yr2Rating":{"type":["number","null"],"description":"Operational rating for the year before that."},"thermalUsage":{"type":["object","null"],"properties":{"actual":{"type":"number","description":"Measured annual thermal fuel use, in kWh per m² per year."},"typical":{"type":"number","description":"Benchmark thermal fuel use for a building of this type, in kWh per m² per year."}},"required":["actual","typical"],"description":"Thermal fuel use measured against its benchmark."},"electricalUsage":{"type":["object","null"],"properties":{"actual":{"type":"number","description":"Measured annual electricity use, in kWh per m² per year."},"typical":{"type":"number","description":"Benchmark electricity use for a building of this type, in kWh per m² per year."}},"required":["actual","typical"],"description":"Electricity use measured against its benchmark."},"renewablesThermalPercentage":{"type":["number","null"],"description":"Percentage of the building's heat supplied from renewable sources."},"renewablesElectricalPercentage":{"type":["number","null"],"description":"Percentage of the building's electricity supplied from renewable sources."},"buildingCategory":{"type":"array","items":{"type":"string","enum":["C1","C2","C3","C4","C5","C6","H1","H2","H3","H4","H5","H6","H7","H8","S1","S2","S3","S4","S5","S6","S7","S8","S9","S10","W1","W2","W3","W4","W5"]},"description":"The CIBSE TM46 benchmark categories the building is measured against. A mixed-use building carries more than one."},"mainBenchmark":{"type":["string","null"],"description":"The main benchmark category in words, for example 'General Office'."},"occupancyLevel":{"type":["string","null"],"description":"How heavily the building is occupied during its operating hours."},"nominatedDate":{"type":["string","null"],"description":"The reference date the assessor chose for this assessment, as an ISO 8601 date."},"assessmentEndDate":{"type":["string","null"],"description":"The last day of the 12-month period the assessment covers, as an ISO 8601 date."}},"required":["currentRating","ratingBand","yr1Rating","yr2Rating","thermalUsage","electricalUsage","renewablesThermalPercentage","renewablesElectricalPercentage","buildingCategory","mainBenchmark","occupancyLevel","nominatedDate","assessmentEndDate"],"description":"Operational performance taken from the building's metered energy use. Null on domestic and non-domestic certificates."},"recommendations":{"type":"array","items":{"type":"object","properties":{"sequence":{"type":"integer","description":"Position in the recommended order. Carrying the measures out in this order gives the most cost-effective path."},"measure":{"type":["string","null"],"enum":["wall_insulation","wall_insulation_combined","cavity_wall_insulation","loft_insulation","floor_insulation_solid","floor_insulation_suspended","flat_roof_insulation","room_in_roof_insulation","party_wall_insulation","draught_proofing","external_doors","double_glazing","replacement_glazing","secondary_glazing","condensing_boiler","gas_condensing_boiler","oil_condensing_boiler","room_to_condensing_boiler","condensing_unit","gas_condensing_unit","warm_air_unit","storage_heaters","storage_heaters_dual_immersion","heating_controls","zone_control","flue_gas_recovery","shower_heat_recovery","cylinder_jacket","cylinder_insulation","cylinder_thermostat","water_heating_controls","heat_pump","heat_pump_underfloor","biomass_boiler","solar_thermal","solar_pv","wind_turbine","pv_battery","pv_diverter","low_energy_lighting",null],"description":"Which improvement is recommended, mapped to a standard set of measures."},"category":{"type":["string","null"],"enum":["insulation","glazing","heating","hot_water","renewables","lighting",null],"description":"What kind of improvement the measure is."},"summary":{"type":["string","null"],"description":"The measure in a short line, as worded on the certificate."},"description":{"type":["string","null"],"description":"The fuller explanation of the measure, as worded on the certificate."},"cost":{"type":["object","null"],"properties":{"min":{"type":["integer","null"],"description":"Low end of the estimated cost, in GBP."},"max":{"type":["integer","null"],"description":"High end of the estimated cost, in GBP."},"currency":{"type":"string","enum":["GBP"],"description":"The currency of the cost figures. Always `GBP`."},"year":{"type":["integer","null"],"description":"The year the cost was estimated in. Treat it as the base year when adjusting for inflation."},"indicative":{"type":["string","null"],"description":"The cost range exactly as the certificate words it, for example '£100 - £350'."}},"required":["min","max","currency","year","indicative"],"description":"What the measure is estimated to cost, as numeric bounds in GBP. Use `cost.year` as the base year when adjusting for inflation."},"saving":{"type":["object","null"],"properties":{"annual":{"type":["integer","null"],"description":"Estimated saving each year, in GBP."},"currency":{"type":"string","enum":["GBP"],"description":"The currency of the saving. Always `GBP`."}},"required":["annual","currency"],"description":"What the measure is estimated to save each year, in GBP."},"projectedRating":{"type":["object","null"],"properties":{"band":{"type":["string","null"],"description":"The energy band the dwelling reaches once this measure is in place, for example 'C'."},"energyScore":{"type":["integer","null"],"description":"The SAP score the dwelling reaches with this measure and every measure before it in the sequence."},"environmentalScore":{"type":["integer","null"],"description":"The environmental impact score the dwelling reaches with this measure and every measure before it."}},"required":["band","energyScore","environmentalScore"],"description":"The rating reached once this measure is carried out. Domestic only."},"greenDealEligible":{"type":["boolean","null"],"description":"True when the measure qualifies for Green Deal financing."},"paybackType":{"type":["string","null"],"enum":["short","medium","long","other",null],"description":"How long the measure takes to pay for itself. Non-domestic only."},"co2Impact":{"type":["string","null"],"enum":["low","medium","high",null],"description":"How much the measure cuts carbon dioxide emissions. Scotland non-domestic only."},"measureCode":{"type":["string","null"],"description":"The code this measure carries on the source certificate. Scottish certificates prefix theirs with 'EPC-', such as 'EPC-R4'."}},"required":["sequence","measure","category","summary","description","cost","saving","projectedRating","greenDealEligible","paybackType","co2Impact","measureCode"],"description":"One recommended improvement, with its cost and saving estimates, its standard measure classification, and the rating it would achieve."},"description":"The improvements recommended on the certificate, in the order they should be carried out. Empty when no recommendations are held for this certificate."},"meesCompliance":{"type":"string","enum":["compliant","at_risk","non_compliant","not_applicable","exempt","unknown"],"description":"Whether the building meets the Minimum Energy Efficiency Standard, worked out from the current rating band, the certificate type and the nation. `compliant` covers bands A to D, `non_compliant` bands F and G, and `at_risk` marks band E as lettable today with no headroom under the expected tightening to C. The standard is SI 2015/962, which covers both domestic and non-domestic private rented property in England and Wales but does not extend to Scotland, and which is assessed on an asset rating rather than the operational rating a Display Energy Certificate carries. Scottish certificates and DECs are therefore `not_applicable`. `exempt` means a registered PRS exemption and appears only on legacy rows; it is never derived from certificate data. `unknown` means there is not enough data to decide."},"createdAt":{"type":"string","description":"When this certificate first appeared in the API, as an ISO 8601 timestamp."},"updatedAt":{"type":"string","description":"When this record was last updated, as an ISO 8601 timestamp."}},"required":["id","certificateType","assessmentMethodology","source","sourceReference","buildingReferenceNumber","locationId","address","coordinates","localAuthority","localAuthorityLabel","constituency","constituencyLabel","county","dataZone","inspectionDate","lodgementDate","validUntil","propertyType","propertyTypeExternal","totalFloorArea","transactionType","transactionTypeExternal","rating","emissions","runningCosts","fabric","systems","domesticDetails","benchmarks","scotlandNativeRating","operationalPerformance","recommendations","meesCompliance","createdAt","updatedAt"],"description":"A single Energy Performance Certificate, covering domestic and non-domestic EPCs and Display Energy Certificates across England, Wales and Scotland. Filter on `certificateType` to narrow to one kind, and on `rating.current.band` to compare efficiency across all three."},"description":"The certificates on this page, most recently lodged first."},"total_count":{"type":"number","description":"Total number of results matching the request across all pages."}},"required":["object","url","has_more","data"]}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/epc/health":{"get":{"operationId":"getEpcHealth","tags":["EPC"],"summary":"Check EPC service health","responses":{"200":{"description":"The EPC service is reachable.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"}},"required":["status"]}}}}}}},"/v1/epc/query":{"post":{"operationId":"queryEpc","tags":["EPC"],"summary":"Search EPC certificates","description":"Search certificates by area, energy rating, building fabric, heating system, running costs and Minimum Energy Efficiency Standard status. Geographic filters accept a postcode, a point and radius, a polygon, or a local authority code. Returns up to 10000 certificates per request, most recently lodged first unless `sort` says otherwise.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EPCQueryRequest"}}}},"responses":{"200":{"description":"The EPC certificates matching the search.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EPCQueryResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/listings/{id}":{"get":{"operationId":"getListingById","x-speakeasy-name-override":"getListingById","tags":["Listings"],"summary":"Get listing by ID","description":"Returns one property listing by its identifier. Reach for it when you already hold the listing ID, from a search or from an earlier response.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Identifier of the listing to return."},"required":true,"description":"Identifier of the listing to return.","name":"id","in":"path"}],"responses":{"200":{"description":"The listing, with every field the API key is entitled to see.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier for this listing. It stays the same across updates, so a listing keeps its identifier when the price or status changes.","example":"123e4567-e89b-12d3-a456-426614174000"},"locationId":{"type":["string","null"],"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). Null when the listing has not been matched to a location.","example":"SW1A1AA"},"provider":{"type":"string","description":"Identifier for the data provider that supplied this listing. Together with `key` it names one source record.","example":"provider-a"},"key":{"type":"string","description":"The listing's own reference within the provider's system. Together with `provider` it names one source record.","example":"12345678"},"currency":{"type":"string","default":"GBP","description":"ISO 4217 currency code for the monetary values in this listing. Defaults to `GBP`.","example":"GBP"},"price":{"type":["number","null"],"exclusiveMinimum":0,"description":"Current price for the listing, in pounds: the asking price for a sale, or the rent for a rental. It reflects the most recent revision. Null when the source publishes no price.","example":50000000},"priceHistory":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"When the price change was recorded, as an ISO 8601 timestamp.","example":"2024-01-15T10:30:00Z"},"price":{"type":"number","exclusiveMinimum":0,"description":"The price after the change, in pounds: the revised asking price for a sale listing, or the revised rent for a rental.","example":50000000},"oldPrice":{"type":"number","exclusiveMinimum":0,"description":"The price before the change, in pounds. Not present for the first price recorded for a listing.","example":52000000},"amount":{"type":"number","description":"The new price minus the old one, in pounds, rounded to two decimal places. Negative when the price was cut.","example":-2000000},"percent":{"type":"number","description":"The change as a percentage of the previous price, rounded to two decimal places. Negative when the price was cut, so -3.85 is a cut of 3.85 per cent.","example":-3.85},"direction":{"type":"string","enum":["increase","decrease","nochange"],"description":"Whether the price went up, went down, or stayed the same at this revision.","example":"decrease"}},"required":["date","price"],"description":"One price revision recorded against the listing, with the size of the change in pounds."},"description":"Price revisions recorded against the listing, one entry per change. Use it to track asking-price cuts and increases over time."},"propertyType":{"type":"string","description":"What kind of property this is, standardised from each provider's own wording to one set of values: unknown, other, flat, detached, semiDetached, terraced, bungalow, maisonette, cottage, chalet, lodge, mobileHome, houseboat, retirement, characterProperty, blockOfFlats, houseShare, farmhouse, mill, barn, coachHouse, statelyHome, farm, parking, equestrian, restaurant, industrial, warehouse, leisure, retail, land, office, riad, hotel, studentAccommodation, commercial, pub, bar, hotelRoom, shop, retailHighStreet, retailOutOfTown, industrialDevelopment, distributionWarehouse, industrialPark, storage, servicedOffice, residentialDevelopment, commercialDevelopment, mixedUse. The field is a plain string rather than a fixed enumeration, so an occasional value outside that set is possible.","example":"terraced"},"subPropertyType":{"type":["string","null"],"description":"Further detail on the kind of property, such as its period or style. Null when the source gives no such detail.","example":"Victorian"},"beds":{"type":["number","null"],"description":"Number of bedrooms advertised. Null when the listing does not state one.","example":3},"baths":{"type":["number","null"],"description":"Number of bathrooms advertised. Null when the listing does not state one.","example":2},"receptions":{"type":["number","null"],"description":"Number of reception rooms advertised, meaning the living, dining and sitting rooms. Null when the listing does not state one.","example":1},"isRetirement":{"type":"boolean","description":"True when the property is age-restricted retirement or sheltered housing.","example":false},"isNewBuild":{"type":"boolean","description":"True when the property is newly built and has not been lived in before.","example":false},"isSharedOwnership":{"type":"boolean","description":"True when the property is offered under a shared ownership scheme, where the buyer owns a share and pays rent on the rest.","example":false},"isAuction":{"type":"boolean","description":"True when the property is being sold at auction rather than by private treaty.","example":false},"type":{"type":"string","enum":["sale","rent"],"description":"Whether the property is advertised for sale or to rent. This governs how to read the price: an asking price for 'sale', the rent quoted by the source for 'rent'.","example":"sale"},"status":{"type":"string","enum":["live","archived","removed"],"description":"Where the listing stands in its marketing life. 'live': currently being marketed. 'removed': withdrawn, or no longer present in the source feed.","example":"live"},"category":{"type":["string","null"],"enum":["residential","commercial",null],"description":"Broad category the property falls into: a residential dwelling, or commercial premises such as offices, retail units, warehouses and industrial space.","example":"residential"},"spatial":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["Point"],"description":"Geometry type discriminator. Always `Point`."},"coordinates":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"description":"A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]}},"required":["type","coordinates"],"additionalProperties":false,"description":"Where the property sits, as a GeoJSON Point. Null when the listing carries no coordinates.","title":"GeoJSON Point","example":{"type":"Point","coordinates":[-0.1278,51.5074]}},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the property in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the property in WGS84 decimal degrees.","example":-0.1278},"address":{"type":"object","properties":{"propertyNumber":{"type":["string","null"],"description":"Building number for the property, including any suffix such as '12A' or a range such as '3-5'.","example":"123"},"street":{"type":["string","null"],"description":"Name of the street the property sits on, without the building number.","example":"High Street"},"city":{"type":["string","null"],"description":"Town, city or village used in the postal address.","example":"London"},"region":{"type":["string","null"],"description":"County or wider administrative area the property sits in.","example":"Greater London"},"district":{"type":["string","null"],"description":"District, borough or neighbourhood within the town or city.","example":"Westminster"},"postcode":{"type":"string","description":"Full UK postcode for the property, such as `SW1A 1AA`.","example":"SW1A 1AA"},"outcode":{"type":["string","null"],"description":"The postcode's outward code (the first part, such as `SW1A`), which groups a wider area.","example":"SW1A"},"incode":{"type":["string","null"],"description":"The part of the postcode after the space, such as `1AA`. With the outward code it forms the full postcode.","example":"1AA"},"country":{"type":"string","default":"GB","description":"Country the property is in, as an ISO 3166-1 alpha-2 code. Defaults to `GB`.","example":"GB"},"originalAddress":{"type":"string","description":"The address exactly as the source supplied it, before it was parsed into the fields above.","example":"123 High Street, London SW1A 1AA"}},"required":["postcode","originalAddress"],"description":"Postal address of the listed property, parsed into its parts. A part is absent when the source did not supply it; the postcode is always present."},"displayAddress":{"type":"string","description":"The address as the listing presents it, ready to show in search results and listing cards. Use `address` for the parsed parts.","example":"High Street, London SW1A 1AA"},"publishedDate":{"type":["string","null"],"format":"date-time","description":"When the listing was first published by the source, as an ISO 8601 timestamp. It does not change when the listing is later updated, and is null when the source does not publish one.","example":"2024-01-15T10:30:00Z"},"removedDate":{"type":["string","null"],"format":"date-time","description":"When the listing was removed from the source, as an ISO 8601 timestamp. Null while the listing is still there.","example":"2024-01-15T10:30:00Z"},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Photographs of the property, in the order the source supplied them. Empty when there are none. Returned only to API keys entitled to listing media."},"energyRatingImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Energy Performance Certificate chart images. Empty when there are none. Returned only to API keys entitled to listing media."},"floorPlanImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Floor plan images showing the layout of the property, sometimes one per storey. Empty when there are none. Returned only to API keys entitled to listing media."},"brochureImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Images taken from the marketing brochure. Empty when there are none. Returned only to API keys entitled to listing media."},"features":{"type":["array","null"],"items":{"type":"object","properties":{"featureId":{"type":"string","description":"Key naming the feature, for example 'TENURE', 'FLOORS' or 'FLOOR_AREA'. Feature keys are an open set that varies by data provider, so treat this as free-form rather than a fixed list.","example":"parking"},"value":{"type":"string","description":"The value stated for the feature, as supplied with the listing. It may be a yes or no answer, a measurement, or a category such as 'Freehold'.","example":"Driveway parking"}},"required":["featureId","value"],"description":"One property feature stated in the listing, as a key and the value given for it."},"description":"Features stated in the listing as key and value pairs, covering things such as tenure and floor area. Null when the source supplied none."},"narratives":{"type":["array","null"],"items":{"type":"object","properties":{"type":{"type":"string","enum":["summary","description","features","location","other"],"description":"What this block of marketing text covers: a short overview, the full description, the list of key features, the surrounding area, or anything that fits none of those.","example":"description"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"The text itself. A string holds one block of prose; an array holds an ordered list of paragraphs or bullet points, one per element. Null when the block carries no text.","example":"Beautiful property in prime location"}},"required":["type","content"],"description":"A block of marketing copy supplied with the listing. It is written to sell the property, so treat it as the agent's description rather than verified fact."},"description":"The marketing text written by the agent, split into blocks by what each one covers. Null when the source supplied none."},"agent":{"type":["object","null"],"properties":{"agentName":{"type":"string","description":"Name of the individual agent or negotiator handling this listing.","example":"John Smith"},"branchName":{"type":"string","description":"Name of the branch marketing this property. An agency may run several branches.","example":"London Branch"},"agencyName":{"type":"string","description":"Trading name of the agency the branch belongs to.","example":"Premier Estate Agents"},"agentId":{"type":"string","description":"Identifier for the individual agent in the source provider's system. Its format varies by provider."},"branchId":{"type":"string","description":"Identifier for the branch in the source provider's system, which can be used to group listings by branch."},"agencyId":{"type":"string","description":"Identifier for the agency in the source provider's system, which can be used to group listings across all of its branches."},"phone":{"type":"string","description":"Main contact telephone number for the branch. Formatting varies between sources.","example":"02012345678"},"phones":{"type":"array","items":{"type":"string"},"description":"Any further telephone numbers held for the branch."},"email":{"type":"string","description":"Main contact email address for the branch.","example":"agent@example.com"},"emails":{"type":"array","items":{"type":"string"},"description":"Any further email addresses held for the branch or its agents."},"website":{"type":"string","description":"URL of the agency's website. It may point at the branch page or the agency home page."},"address":{"type":"string","description":"Postal address of the branch office, as a single formatted string."},"postcode":{"type":"string","description":"Postcode of the branch office."}},"description":"The agent marketing this property. Null when the source supplied no agent details."},"createdAt":{"type":"string","format":"date-time","description":"When this listing first appeared in the API, as an ISO 8601 timestamp. It differs from `publishedDate` when a listing is imported after the event.","example":"2024-01-15T10:30:00Z"},"updatedAt":{"type":"string","format":"date-time","description":"When this listing was last updated, as an ISO 8601 timestamp. It moves whenever any field changes, including price revisions, status changes and new images.","example":"2024-01-15T10:30:00Z"},"object":{"type":"string","enum":["listing"],"description":"Object type discriminator. Always `listing`.","example":"listing"}},"required":["id","provider","key","propertyType","type","status","address","object"],"additionalProperties":{},"description":"A single property listing, with every field the caller is entitled to see."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/listings/location/{locationId}":{"get":{"operationId":"getListingsByLocation","x-speakeasy-name-override":"getListingsByLocation","tags":["Listings"],"summary":"Get listings by location ID","description":"Returns the listings recorded at one or more locations, newest first. Only listings that are currently live are returned, up to 25 of them, so it answers what is on the market at an address rather than its full history.","parameters":[{"schema":{"type":"string","description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). Separate several location IDs with commas to look them up in one request."},"required":true,"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). Separate several location IDs with commas to look them up in one request.","name":"locationId","in":"path"},{"schema":{"type":"string","enum":["true","false"],"default":"true","description":"Whether to return the enriched record built from everything held for the listing, including its pricing history, features, media, energy rating and extracted attributes. Defaults to 'true'; pass 'false' for the stored listing on its own.","example":"true"},"required":false,"description":"Whether to return the enriched record built from everything held for the listing, including its pricing history, features, media, energy rating and extracted attributes. Defaults to 'true'; pass 'false' for the stored listing on its own.","name":"forceAggregate","in":"query"}],"responses":{"200":{"description":"The live listings at the requested locations.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier for this listing. It stays the same across updates, so a listing keeps its identifier when the price or status changes.","example":"123e4567-e89b-12d3-a456-426614174000"},"locationId":{"type":["string","null"],"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). Null when the listing has not been matched to a location.","example":"SW1A1AA"},"provider":{"type":"string","description":"Identifier for the data provider that supplied this listing. Together with `key` it names one source record.","example":"provider-a"},"key":{"type":"string","description":"The listing's own reference within the provider's system. Together with `provider` it names one source record.","example":"12345678"},"currency":{"type":"string","default":"GBP","description":"ISO 4217 currency code for the monetary values in this listing. Defaults to `GBP`.","example":"GBP"},"price":{"type":["number","null"],"exclusiveMinimum":0,"description":"Current price for the listing, in pounds: the asking price for a sale, or the rent for a rental. It reflects the most recent revision. Null when the source publishes no price.","example":50000000},"priceHistory":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"When the price change was recorded, as an ISO 8601 timestamp.","example":"2024-01-15T10:30:00Z"},"price":{"type":"number","exclusiveMinimum":0,"description":"The price after the change, in pounds: the revised asking price for a sale listing, or the revised rent for a rental.","example":50000000},"oldPrice":{"type":"number","exclusiveMinimum":0,"description":"The price before the change, in pounds. Not present for the first price recorded for a listing.","example":52000000},"amount":{"type":"number","description":"The new price minus the old one, in pounds, rounded to two decimal places. Negative when the price was cut.","example":-2000000},"percent":{"type":"number","description":"The change as a percentage of the previous price, rounded to two decimal places. Negative when the price was cut, so -3.85 is a cut of 3.85 per cent.","example":-3.85},"direction":{"type":"string","enum":["increase","decrease","nochange"],"description":"Whether the price went up, went down, or stayed the same at this revision.","example":"decrease"}},"required":["date","price"],"description":"One price revision recorded against the listing, with the size of the change in pounds."},"description":"Price revisions recorded against the listing, one entry per change. Use it to track asking-price cuts and increases over time."},"propertyType":{"type":"string","description":"What kind of property this is, standardised from each provider's own wording to one set of values: unknown, other, flat, detached, semiDetached, terraced, bungalow, maisonette, cottage, chalet, lodge, mobileHome, houseboat, retirement, characterProperty, blockOfFlats, houseShare, farmhouse, mill, barn, coachHouse, statelyHome, farm, parking, equestrian, restaurant, industrial, warehouse, leisure, retail, land, office, riad, hotel, studentAccommodation, commercial, pub, bar, hotelRoom, shop, retailHighStreet, retailOutOfTown, industrialDevelopment, distributionWarehouse, industrialPark, storage, servicedOffice, residentialDevelopment, commercialDevelopment, mixedUse. The field is a plain string rather than a fixed enumeration, so an occasional value outside that set is possible.","example":"terraced"},"subPropertyType":{"type":["string","null"],"description":"Further detail on the kind of property, such as its period or style. Null when the source gives no such detail.","example":"Victorian"},"beds":{"type":["number","null"],"description":"Number of bedrooms advertised. Null when the listing does not state one.","example":3},"baths":{"type":["number","null"],"description":"Number of bathrooms advertised. Null when the listing does not state one.","example":2},"receptions":{"type":["number","null"],"description":"Number of reception rooms advertised, meaning the living, dining and sitting rooms. Null when the listing does not state one.","example":1},"isRetirement":{"type":"boolean","description":"True when the property is age-restricted retirement or sheltered housing.","example":false},"isNewBuild":{"type":"boolean","description":"True when the property is newly built and has not been lived in before.","example":false},"isSharedOwnership":{"type":"boolean","description":"True when the property is offered under a shared ownership scheme, where the buyer owns a share and pays rent on the rest.","example":false},"isAuction":{"type":"boolean","description":"True when the property is being sold at auction rather than by private treaty.","example":false},"type":{"type":"string","enum":["sale","rent"],"description":"Whether the property is advertised for sale or to rent. This governs how to read the price: an asking price for 'sale', the rent quoted by the source for 'rent'.","example":"sale"},"status":{"type":"string","enum":["live","archived","removed"],"description":"Where the listing stands in its marketing life. 'live': currently being marketed. 'removed': withdrawn, or no longer present in the source feed.","example":"live"},"category":{"type":["string","null"],"enum":["residential","commercial",null],"description":"Broad category the property falls into: a residential dwelling, or commercial premises such as offices, retail units, warehouses and industrial space.","example":"residential"},"spatial":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["Point"],"description":"Geometry type discriminator. Always `Point`."},"coordinates":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"description":"A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]}},"required":["type","coordinates"],"additionalProperties":false,"description":"Where the property sits, as a GeoJSON Point. Null when the listing carries no coordinates.","title":"GeoJSON Point","example":{"type":"Point","coordinates":[-0.1278,51.5074]}},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the property in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the property in WGS84 decimal degrees.","example":-0.1278},"address":{"type":"object","properties":{"propertyNumber":{"type":["string","null"],"description":"Building number for the property, including any suffix such as '12A' or a range such as '3-5'.","example":"123"},"street":{"type":["string","null"],"description":"Name of the street the property sits on, without the building number.","example":"High Street"},"city":{"type":["string","null"],"description":"Town, city or village used in the postal address.","example":"London"},"region":{"type":["string","null"],"description":"County or wider administrative area the property sits in.","example":"Greater London"},"district":{"type":["string","null"],"description":"District, borough or neighbourhood within the town or city.","example":"Westminster"},"postcode":{"type":"string","description":"Full UK postcode for the property, such as `SW1A 1AA`.","example":"SW1A 1AA"},"outcode":{"type":["string","null"],"description":"The postcode's outward code (the first part, such as `SW1A`), which groups a wider area.","example":"SW1A"},"incode":{"type":["string","null"],"description":"The part of the postcode after the space, such as `1AA`. With the outward code it forms the full postcode.","example":"1AA"},"country":{"type":"string","default":"GB","description":"Country the property is in, as an ISO 3166-1 alpha-2 code. Defaults to `GB`.","example":"GB"},"originalAddress":{"type":"string","description":"The address exactly as the source supplied it, before it was parsed into the fields above.","example":"123 High Street, London SW1A 1AA"}},"required":["postcode","originalAddress"],"description":"Postal address of the listed property, parsed into its parts. A part is absent when the source did not supply it; the postcode is always present."},"displayAddress":{"type":"string","description":"The address as the listing presents it, ready to show in search results and listing cards. Use `address` for the parsed parts.","example":"High Street, London SW1A 1AA"},"publishedDate":{"type":["string","null"],"format":"date-time","description":"When the listing was first published by the source, as an ISO 8601 timestamp. It does not change when the listing is later updated, and is null when the source does not publish one.","example":"2024-01-15T10:30:00Z"},"removedDate":{"type":["string","null"],"format":"date-time","description":"When the listing was removed from the source, as an ISO 8601 timestamp. Null while the listing is still there.","example":"2024-01-15T10:30:00Z"},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Photographs of the property, in the order the source supplied them. Empty when there are none. Returned only to API keys entitled to listing media."},"energyRatingImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Energy Performance Certificate chart images. Empty when there are none. Returned only to API keys entitled to listing media."},"floorPlanImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Floor plan images showing the layout of the property, sometimes one per storey. Empty when there are none. Returned only to API keys entitled to listing media."},"brochureImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Images taken from the marketing brochure. Empty when there are none. Returned only to API keys entitled to listing media."},"features":{"type":["array","null"],"items":{"type":"object","properties":{"featureId":{"type":"string","description":"Key naming the feature, for example 'TENURE', 'FLOORS' or 'FLOOR_AREA'. Feature keys are an open set that varies by data provider, so treat this as free-form rather than a fixed list.","example":"parking"},"value":{"type":"string","description":"The value stated for the feature, as supplied with the listing. It may be a yes or no answer, a measurement, or a category such as 'Freehold'.","example":"Driveway parking"}},"required":["featureId","value"],"description":"One property feature stated in the listing, as a key and the value given for it."},"description":"Features stated in the listing as key and value pairs, covering things such as tenure and floor area. Null when the source supplied none."},"narratives":{"type":["array","null"],"items":{"type":"object","properties":{"type":{"type":"string","enum":["summary","description","features","location","other"],"description":"What this block of marketing text covers: a short overview, the full description, the list of key features, the surrounding area, or anything that fits none of those.","example":"description"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"The text itself. A string holds one block of prose; an array holds an ordered list of paragraphs or bullet points, one per element. Null when the block carries no text.","example":"Beautiful property in prime location"}},"required":["type","content"],"description":"A block of marketing copy supplied with the listing. It is written to sell the property, so treat it as the agent's description rather than verified fact."},"description":"The marketing text written by the agent, split into blocks by what each one covers. Null when the source supplied none."},"agent":{"type":["object","null"],"properties":{"agentName":{"type":"string","description":"Name of the individual agent or negotiator handling this listing.","example":"John Smith"},"branchName":{"type":"string","description":"Name of the branch marketing this property. An agency may run several branches.","example":"London Branch"},"agencyName":{"type":"string","description":"Trading name of the agency the branch belongs to.","example":"Premier Estate Agents"},"agentId":{"type":"string","description":"Identifier for the individual agent in the source provider's system. Its format varies by provider."},"branchId":{"type":"string","description":"Identifier for the branch in the source provider's system, which can be used to group listings by branch."},"agencyId":{"type":"string","description":"Identifier for the agency in the source provider's system, which can be used to group listings across all of its branches."},"phone":{"type":"string","description":"Main contact telephone number for the branch. Formatting varies between sources.","example":"02012345678"},"phones":{"type":"array","items":{"type":"string"},"description":"Any further telephone numbers held for the branch."},"email":{"type":"string","description":"Main contact email address for the branch.","example":"agent@example.com"},"emails":{"type":"array","items":{"type":"string"},"description":"Any further email addresses held for the branch or its agents."},"website":{"type":"string","description":"URL of the agency's website. It may point at the branch page or the agency home page."},"address":{"type":"string","description":"Postal address of the branch office, as a single formatted string."},"postcode":{"type":"string","description":"Postcode of the branch office."}},"description":"The agent marketing this property. Null when the source supplied no agent details."},"createdAt":{"type":"string","format":"date-time","description":"When this listing first appeared in the API, as an ISO 8601 timestamp. It differs from `publishedDate` when a listing is imported after the event.","example":"2024-01-15T10:30:00Z"},"updatedAt":{"type":"string","format":"date-time","description":"When this listing was last updated, as an ISO 8601 timestamp. It moves whenever any field changes, including price revisions, status changes and new images.","example":"2024-01-15T10:30:00Z"}},"required":["id","provider","key","propertyType","type","status","address"],"additionalProperties":{},"description":"A single UK residential or commercial property advertised for sale or to rent. Listings come from several data providers, and an aggregated listing pulls together everything held for the property. Prices are in pounds."},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of property listings, with the counters needed to fetch the rest."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/listings/source/{provider}/{key}":{"get":{"operationId":"getListingBySource","x-speakeasy-name-override":"getListingBySource","tags":["Listings"],"summary":"Get listing by provider and key","description":"Returns one property listing by the data provider and that provider's own reference for it. Reach for it when your system stores the provider's reference rather than the listing identifier.","parameters":[{"schema":{"type":"string","description":"Identifier for the data provider that supplied the listing.","example":"provider-a"},"required":true,"description":"Identifier for the data provider that supplied the listing.","name":"provider","in":"path"},{"schema":{"type":"string","description":"The listing's own reference within that provider's system.","example":"12345678"},"required":true,"description":"The listing's own reference within that provider's system.","name":"key","in":"path"},{"schema":{"type":"string","enum":["true","false"],"default":"false","description":"Whether to return the enriched record built from everything held for the listing, including its pricing history, features, media, energy rating and extracted attributes. Defaults to 'false', which returns the stored listing on its own.","example":"true"},"required":false,"description":"Whether to return the enriched record built from everything held for the listing, including its pricing history, features, media, energy rating and extracted attributes. Defaults to 'false', which returns the stored listing on its own.","name":"forceAggregate","in":"query"}],"responses":{"200":{"description":"The listing, with every field the API key is entitled to see.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier for this listing. It stays the same across updates, so a listing keeps its identifier when the price or status changes.","example":"123e4567-e89b-12d3-a456-426614174000"},"locationId":{"type":["string","null"],"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). Null when the listing has not been matched to a location.","example":"SW1A1AA"},"provider":{"type":"string","description":"Identifier for the data provider that supplied this listing. Together with `key` it names one source record.","example":"provider-a"},"key":{"type":"string","description":"The listing's own reference within the provider's system. Together with `provider` it names one source record.","example":"12345678"},"currency":{"type":"string","default":"GBP","description":"ISO 4217 currency code for the monetary values in this listing. Defaults to `GBP`.","example":"GBP"},"price":{"type":["number","null"],"exclusiveMinimum":0,"description":"Current price for the listing, in pounds: the asking price for a sale, or the rent for a rental. It reflects the most recent revision. Null when the source publishes no price.","example":50000000},"priceHistory":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"When the price change was recorded, as an ISO 8601 timestamp.","example":"2024-01-15T10:30:00Z"},"price":{"type":"number","exclusiveMinimum":0,"description":"The price after the change, in pounds: the revised asking price for a sale listing, or the revised rent for a rental.","example":50000000},"oldPrice":{"type":"number","exclusiveMinimum":0,"description":"The price before the change, in pounds. Not present for the first price recorded for a listing.","example":52000000},"amount":{"type":"number","description":"The new price minus the old one, in pounds, rounded to two decimal places. Negative when the price was cut.","example":-2000000},"percent":{"type":"number","description":"The change as a percentage of the previous price, rounded to two decimal places. Negative when the price was cut, so -3.85 is a cut of 3.85 per cent.","example":-3.85},"direction":{"type":"string","enum":["increase","decrease","nochange"],"description":"Whether the price went up, went down, or stayed the same at this revision.","example":"decrease"}},"required":["date","price"],"description":"One price revision recorded against the listing, with the size of the change in pounds."},"description":"Price revisions recorded against the listing, one entry per change. Use it to track asking-price cuts and increases over time."},"propertyType":{"type":"string","description":"What kind of property this is, standardised from each provider's own wording to one set of values: unknown, other, flat, detached, semiDetached, terraced, bungalow, maisonette, cottage, chalet, lodge, mobileHome, houseboat, retirement, characterProperty, blockOfFlats, houseShare, farmhouse, mill, barn, coachHouse, statelyHome, farm, parking, equestrian, restaurant, industrial, warehouse, leisure, retail, land, office, riad, hotel, studentAccommodation, commercial, pub, bar, hotelRoom, shop, retailHighStreet, retailOutOfTown, industrialDevelopment, distributionWarehouse, industrialPark, storage, servicedOffice, residentialDevelopment, commercialDevelopment, mixedUse. The field is a plain string rather than a fixed enumeration, so an occasional value outside that set is possible.","example":"terraced"},"subPropertyType":{"type":["string","null"],"description":"Further detail on the kind of property, such as its period or style. Null when the source gives no such detail.","example":"Victorian"},"beds":{"type":["number","null"],"description":"Number of bedrooms advertised. Null when the listing does not state one.","example":3},"baths":{"type":["number","null"],"description":"Number of bathrooms advertised. Null when the listing does not state one.","example":2},"receptions":{"type":["number","null"],"description":"Number of reception rooms advertised, meaning the living, dining and sitting rooms. Null when the listing does not state one.","example":1},"isRetirement":{"type":"boolean","description":"True when the property is age-restricted retirement or sheltered housing.","example":false},"isNewBuild":{"type":"boolean","description":"True when the property is newly built and has not been lived in before.","example":false},"isSharedOwnership":{"type":"boolean","description":"True when the property is offered under a shared ownership scheme, where the buyer owns a share and pays rent on the rest.","example":false},"isAuction":{"type":"boolean","description":"True when the property is being sold at auction rather than by private treaty.","example":false},"type":{"type":"string","enum":["sale","rent"],"description":"Whether the property is advertised for sale or to rent. This governs how to read the price: an asking price for 'sale', the rent quoted by the source for 'rent'.","example":"sale"},"status":{"type":"string","enum":["live","archived","removed"],"description":"Where the listing stands in its marketing life. 'live': currently being marketed. 'removed': withdrawn, or no longer present in the source feed.","example":"live"},"category":{"type":["string","null"],"enum":["residential","commercial",null],"description":"Broad category the property falls into: a residential dwelling, or commercial premises such as offices, retail units, warehouses and industrial space.","example":"residential"},"spatial":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["Point"],"description":"Geometry type discriminator. Always `Point`."},"coordinates":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"description":"A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]}},"required":["type","coordinates"],"additionalProperties":false,"description":"Where the property sits, as a GeoJSON Point. Null when the listing carries no coordinates.","title":"GeoJSON Point","example":{"type":"Point","coordinates":[-0.1278,51.5074]}},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the property in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the property in WGS84 decimal degrees.","example":-0.1278},"address":{"type":"object","properties":{"propertyNumber":{"type":["string","null"],"description":"Building number for the property, including any suffix such as '12A' or a range such as '3-5'.","example":"123"},"street":{"type":["string","null"],"description":"Name of the street the property sits on, without the building number.","example":"High Street"},"city":{"type":["string","null"],"description":"Town, city or village used in the postal address.","example":"London"},"region":{"type":["string","null"],"description":"County or wider administrative area the property sits in.","example":"Greater London"},"district":{"type":["string","null"],"description":"District, borough or neighbourhood within the town or city.","example":"Westminster"},"postcode":{"type":"string","description":"Full UK postcode for the property, such as `SW1A 1AA`.","example":"SW1A 1AA"},"outcode":{"type":["string","null"],"description":"The postcode's outward code (the first part, such as `SW1A`), which groups a wider area.","example":"SW1A"},"incode":{"type":["string","null"],"description":"The part of the postcode after the space, such as `1AA`. With the outward code it forms the full postcode.","example":"1AA"},"country":{"type":"string","default":"GB","description":"Country the property is in, as an ISO 3166-1 alpha-2 code. Defaults to `GB`.","example":"GB"},"originalAddress":{"type":"string","description":"The address exactly as the source supplied it, before it was parsed into the fields above.","example":"123 High Street, London SW1A 1AA"}},"required":["postcode","originalAddress"],"description":"Postal address of the listed property, parsed into its parts. A part is absent when the source did not supply it; the postcode is always present."},"displayAddress":{"type":"string","description":"The address as the listing presents it, ready to show in search results and listing cards. Use `address` for the parsed parts.","example":"High Street, London SW1A 1AA"},"publishedDate":{"type":["string","null"],"format":"date-time","description":"When the listing was first published by the source, as an ISO 8601 timestamp. It does not change when the listing is later updated, and is null when the source does not publish one.","example":"2024-01-15T10:30:00Z"},"removedDate":{"type":["string","null"],"format":"date-time","description":"When the listing was removed from the source, as an ISO 8601 timestamp. Null while the listing is still there.","example":"2024-01-15T10:30:00Z"},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Photographs of the property, in the order the source supplied them. Empty when there are none. Returned only to API keys entitled to listing media."},"energyRatingImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Energy Performance Certificate chart images. Empty when there are none. Returned only to API keys entitled to listing media."},"floorPlanImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Floor plan images showing the layout of the property, sometimes one per storey. Empty when there are none. Returned only to API keys entitled to listing media."},"brochureImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Images taken from the marketing brochure. Empty when there are none. Returned only to API keys entitled to listing media."},"features":{"type":["array","null"],"items":{"type":"object","properties":{"featureId":{"type":"string","description":"Key naming the feature, for example 'TENURE', 'FLOORS' or 'FLOOR_AREA'. Feature keys are an open set that varies by data provider, so treat this as free-form rather than a fixed list.","example":"parking"},"value":{"type":"string","description":"The value stated for the feature, as supplied with the listing. It may be a yes or no answer, a measurement, or a category such as 'Freehold'.","example":"Driveway parking"}},"required":["featureId","value"],"description":"One property feature stated in the listing, as a key and the value given for it."},"description":"Features stated in the listing as key and value pairs, covering things such as tenure and floor area. Null when the source supplied none."},"narratives":{"type":["array","null"],"items":{"type":"object","properties":{"type":{"type":"string","enum":["summary","description","features","location","other"],"description":"What this block of marketing text covers: a short overview, the full description, the list of key features, the surrounding area, or anything that fits none of those.","example":"description"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"The text itself. A string holds one block of prose; an array holds an ordered list of paragraphs or bullet points, one per element. Null when the block carries no text.","example":"Beautiful property in prime location"}},"required":["type","content"],"description":"A block of marketing copy supplied with the listing. It is written to sell the property, so treat it as the agent's description rather than verified fact."},"description":"The marketing text written by the agent, split into blocks by what each one covers. Null when the source supplied none."},"agent":{"type":["object","null"],"properties":{"agentName":{"type":"string","description":"Name of the individual agent or negotiator handling this listing.","example":"John Smith"},"branchName":{"type":"string","description":"Name of the branch marketing this property. An agency may run several branches.","example":"London Branch"},"agencyName":{"type":"string","description":"Trading name of the agency the branch belongs to.","example":"Premier Estate Agents"},"agentId":{"type":"string","description":"Identifier for the individual agent in the source provider's system. Its format varies by provider."},"branchId":{"type":"string","description":"Identifier for the branch in the source provider's system, which can be used to group listings by branch."},"agencyId":{"type":"string","description":"Identifier for the agency in the source provider's system, which can be used to group listings across all of its branches."},"phone":{"type":"string","description":"Main contact telephone number for the branch. Formatting varies between sources.","example":"02012345678"},"phones":{"type":"array","items":{"type":"string"},"description":"Any further telephone numbers held for the branch."},"email":{"type":"string","description":"Main contact email address for the branch.","example":"agent@example.com"},"emails":{"type":"array","items":{"type":"string"},"description":"Any further email addresses held for the branch or its agents."},"website":{"type":"string","description":"URL of the agency's website. It may point at the branch page or the agency home page."},"address":{"type":"string","description":"Postal address of the branch office, as a single formatted string."},"postcode":{"type":"string","description":"Postcode of the branch office."}},"description":"The agent marketing this property. Null when the source supplied no agent details."},"createdAt":{"type":"string","format":"date-time","description":"When this listing first appeared in the API, as an ISO 8601 timestamp. It differs from `publishedDate` when a listing is imported after the event.","example":"2024-01-15T10:30:00Z"},"updatedAt":{"type":"string","format":"date-time","description":"When this listing was last updated, as an ISO 8601 timestamp. It moves whenever any field changes, including price revisions, status changes and new images.","example":"2024-01-15T10:30:00Z"},"object":{"type":"string","enum":["listing"],"description":"Object type discriminator. Always `listing`.","example":"listing"}},"required":["id","provider","key","propertyType","type","status","address","object"],"additionalProperties":{},"description":"A single property listing, with every field the caller is entitled to see."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/listings/query":{"post":{"operationId":"queryListings","x-speakeasy-name-override":"queryListings","tags":["Listings"],"summary":"Query listings with filters","description":"Returns the most recently published listings, newest first, optionally narrowed to one status. Of the fields in the body only `status` and `limit` change the result; for filtering by location, provider or price, and for paging and sorting, use POST /listings/query/advanced.","requestBody":{"description":"The filters to apply.","content":{"application/json":{"schema":{"type":"object","properties":{"locationIds":{"type":"array","items":{"type":"string"},"description":"Location IDs to match. This endpoint does not apply the filter; to search by location, use `POST /listings/query/advanced` with a `locationId` condition.","example":["SW1A1AA","SW1A2AA"]},"providers":{"type":"array","items":{"type":"string"},"description":"Data provider identifiers to match. This endpoint does not apply the filter; to search by provider, use `POST /listings/query/advanced` with a `provider` condition.","example":["provider-a","provider-b"]},"status":{"type":"string","enum":["live","archived","removed"],"description":"Return only listings with this status. Omit it to return listings of every status.","example":"live"},"limit":{"type":"number","minimum":1,"maximum":100,"default":25,"description":"Maximum number of listings to return. Defaults to 25. Minimum 1, maximum 100.","example":25},"offset":{"type":"number","minimum":0,"default":0,"description":"Number of results to skip before the first one returned. Defaults to 0. This endpoint does not page, so results always start with the most recently published listing.","example":0},"orderBy":{"type":"string","enum":["publishedDate","price","updatedAt"],"description":"Field to sort by. This endpoint always sorts by publication date, so the value has no effect; `POST /listings/query/advanced` offers a choice of sort fields.","example":"publishedDate"},"order":{"type":"string","enum":["asc","desc"],"default":"desc","description":"Sort direction. This endpoint always returns the most recently published listing first, so the value has no effect.","example":"desc"}},"description":"Filters for a listing search. Only `status` and `limit` change the result: the endpoint returns the most recently published listings, newest first."}}}},"responses":{"200":{"description":"The matching listings, most recently published first.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier for this listing. It stays the same across updates, so a listing keeps its identifier when the price or status changes.","example":"123e4567-e89b-12d3-a456-426614174000"},"locationId":{"type":["string","null"],"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). Null when the listing has not been matched to a location.","example":"SW1A1AA"},"provider":{"type":"string","description":"Identifier for the data provider that supplied this listing. Together with `key` it names one source record.","example":"provider-a"},"key":{"type":"string","description":"The listing's own reference within the provider's system. Together with `provider` it names one source record.","example":"12345678"},"currency":{"type":"string","default":"GBP","description":"ISO 4217 currency code for the monetary values in this listing. Defaults to `GBP`.","example":"GBP"},"price":{"type":["number","null"],"exclusiveMinimum":0,"description":"Current price for the listing, in pounds: the asking price for a sale, or the rent for a rental. It reflects the most recent revision. Null when the source publishes no price.","example":50000000},"priceHistory":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"When the price change was recorded, as an ISO 8601 timestamp.","example":"2024-01-15T10:30:00Z"},"price":{"type":"number","exclusiveMinimum":0,"description":"The price after the change, in pounds: the revised asking price for a sale listing, or the revised rent for a rental.","example":50000000},"oldPrice":{"type":"number","exclusiveMinimum":0,"description":"The price before the change, in pounds. Not present for the first price recorded for a listing.","example":52000000},"amount":{"type":"number","description":"The new price minus the old one, in pounds, rounded to two decimal places. Negative when the price was cut.","example":-2000000},"percent":{"type":"number","description":"The change as a percentage of the previous price, rounded to two decimal places. Negative when the price was cut, so -3.85 is a cut of 3.85 per cent.","example":-3.85},"direction":{"type":"string","enum":["increase","decrease","nochange"],"description":"Whether the price went up, went down, or stayed the same at this revision.","example":"decrease"}},"required":["date","price"],"description":"One price revision recorded against the listing, with the size of the change in pounds."},"description":"Price revisions recorded against the listing, one entry per change. Use it to track asking-price cuts and increases over time."},"propertyType":{"type":"string","description":"What kind of property this is, standardised from each provider's own wording to one set of values: unknown, other, flat, detached, semiDetached, terraced, bungalow, maisonette, cottage, chalet, lodge, mobileHome, houseboat, retirement, characterProperty, blockOfFlats, houseShare, farmhouse, mill, barn, coachHouse, statelyHome, farm, parking, equestrian, restaurant, industrial, warehouse, leisure, retail, land, office, riad, hotel, studentAccommodation, commercial, pub, bar, hotelRoom, shop, retailHighStreet, retailOutOfTown, industrialDevelopment, distributionWarehouse, industrialPark, storage, servicedOffice, residentialDevelopment, commercialDevelopment, mixedUse. The field is a plain string rather than a fixed enumeration, so an occasional value outside that set is possible.","example":"terraced"},"subPropertyType":{"type":["string","null"],"description":"Further detail on the kind of property, such as its period or style. Null when the source gives no such detail.","example":"Victorian"},"beds":{"type":["number","null"],"description":"Number of bedrooms advertised. Null when the listing does not state one.","example":3},"baths":{"type":["number","null"],"description":"Number of bathrooms advertised. Null when the listing does not state one.","example":2},"receptions":{"type":["number","null"],"description":"Number of reception rooms advertised, meaning the living, dining and sitting rooms. Null when the listing does not state one.","example":1},"isRetirement":{"type":"boolean","description":"True when the property is age-restricted retirement or sheltered housing.","example":false},"isNewBuild":{"type":"boolean","description":"True when the property is newly built and has not been lived in before.","example":false},"isSharedOwnership":{"type":"boolean","description":"True when the property is offered under a shared ownership scheme, where the buyer owns a share and pays rent on the rest.","example":false},"isAuction":{"type":"boolean","description":"True when the property is being sold at auction rather than by private treaty.","example":false},"type":{"type":"string","enum":["sale","rent"],"description":"Whether the property is advertised for sale or to rent. This governs how to read the price: an asking price for 'sale', the rent quoted by the source for 'rent'.","example":"sale"},"status":{"type":"string","enum":["live","archived","removed"],"description":"Where the listing stands in its marketing life. 'live': currently being marketed. 'removed': withdrawn, or no longer present in the source feed.","example":"live"},"category":{"type":["string","null"],"enum":["residential","commercial",null],"description":"Broad category the property falls into: a residential dwelling, or commercial premises such as offices, retail units, warehouses and industrial space.","example":"residential"},"spatial":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["Point"],"description":"Geometry type discriminator. Always `Point`."},"coordinates":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"description":"A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]}},"required":["type","coordinates"],"additionalProperties":false,"description":"Where the property sits, as a GeoJSON Point. Null when the listing carries no coordinates.","title":"GeoJSON Point","example":{"type":"Point","coordinates":[-0.1278,51.5074]}},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the property in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the property in WGS84 decimal degrees.","example":-0.1278},"address":{"type":"object","properties":{"propertyNumber":{"type":["string","null"],"description":"Building number for the property, including any suffix such as '12A' or a range such as '3-5'.","example":"123"},"street":{"type":["string","null"],"description":"Name of the street the property sits on, without the building number.","example":"High Street"},"city":{"type":["string","null"],"description":"Town, city or village used in the postal address.","example":"London"},"region":{"type":["string","null"],"description":"County or wider administrative area the property sits in.","example":"Greater London"},"district":{"type":["string","null"],"description":"District, borough or neighbourhood within the town or city.","example":"Westminster"},"postcode":{"type":"string","description":"Full UK postcode for the property, such as `SW1A 1AA`.","example":"SW1A 1AA"},"outcode":{"type":["string","null"],"description":"The postcode's outward code (the first part, such as `SW1A`), which groups a wider area.","example":"SW1A"},"incode":{"type":["string","null"],"description":"The part of the postcode after the space, such as `1AA`. With the outward code it forms the full postcode.","example":"1AA"},"country":{"type":"string","default":"GB","description":"Country the property is in, as an ISO 3166-1 alpha-2 code. Defaults to `GB`.","example":"GB"},"originalAddress":{"type":"string","description":"The address exactly as the source supplied it, before it was parsed into the fields above.","example":"123 High Street, London SW1A 1AA"}},"required":["postcode","originalAddress"],"description":"Postal address of the listed property, parsed into its parts. A part is absent when the source did not supply it; the postcode is always present."},"displayAddress":{"type":"string","description":"The address as the listing presents it, ready to show in search results and listing cards. Use `address` for the parsed parts.","example":"High Street, London SW1A 1AA"},"publishedDate":{"type":["string","null"],"format":"date-time","description":"When the listing was first published by the source, as an ISO 8601 timestamp. It does not change when the listing is later updated, and is null when the source does not publish one.","example":"2024-01-15T10:30:00Z"},"removedDate":{"type":["string","null"],"format":"date-time","description":"When the listing was removed from the source, as an ISO 8601 timestamp. Null while the listing is still there.","example":"2024-01-15T10:30:00Z"},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Photographs of the property, in the order the source supplied them. Empty when there are none. Returned only to API keys entitled to listing media."},"energyRatingImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Energy Performance Certificate chart images. Empty when there are none. Returned only to API keys entitled to listing media."},"floorPlanImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Floor plan images showing the layout of the property, sometimes one per storey. Empty when there are none. Returned only to API keys entitled to listing media."},"brochureImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Images taken from the marketing brochure. Empty when there are none. Returned only to API keys entitled to listing media."},"features":{"type":["array","null"],"items":{"type":"object","properties":{"featureId":{"type":"string","description":"Key naming the feature, for example 'TENURE', 'FLOORS' or 'FLOOR_AREA'. Feature keys are an open set that varies by data provider, so treat this as free-form rather than a fixed list.","example":"parking"},"value":{"type":"string","description":"The value stated for the feature, as supplied with the listing. It may be a yes or no answer, a measurement, or a category such as 'Freehold'.","example":"Driveway parking"}},"required":["featureId","value"],"description":"One property feature stated in the listing, as a key and the value given for it."},"description":"Features stated in the listing as key and value pairs, covering things such as tenure and floor area. Null when the source supplied none."},"narratives":{"type":["array","null"],"items":{"type":"object","properties":{"type":{"type":"string","enum":["summary","description","features","location","other"],"description":"What this block of marketing text covers: a short overview, the full description, the list of key features, the surrounding area, or anything that fits none of those.","example":"description"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"The text itself. A string holds one block of prose; an array holds an ordered list of paragraphs or bullet points, one per element. Null when the block carries no text.","example":"Beautiful property in prime location"}},"required":["type","content"],"description":"A block of marketing copy supplied with the listing. It is written to sell the property, so treat it as the agent's description rather than verified fact."},"description":"The marketing text written by the agent, split into blocks by what each one covers. Null when the source supplied none."},"agent":{"type":["object","null"],"properties":{"agentName":{"type":"string","description":"Name of the individual agent or negotiator handling this listing.","example":"John Smith"},"branchName":{"type":"string","description":"Name of the branch marketing this property. An agency may run several branches.","example":"London Branch"},"agencyName":{"type":"string","description":"Trading name of the agency the branch belongs to.","example":"Premier Estate Agents"},"agentId":{"type":"string","description":"Identifier for the individual agent in the source provider's system. Its format varies by provider."},"branchId":{"type":"string","description":"Identifier for the branch in the source provider's system, which can be used to group listings by branch."},"agencyId":{"type":"string","description":"Identifier for the agency in the source provider's system, which can be used to group listings across all of its branches."},"phone":{"type":"string","description":"Main contact telephone number for the branch. Formatting varies between sources.","example":"02012345678"},"phones":{"type":"array","items":{"type":"string"},"description":"Any further telephone numbers held for the branch."},"email":{"type":"string","description":"Main contact email address for the branch.","example":"agent@example.com"},"emails":{"type":"array","items":{"type":"string"},"description":"Any further email addresses held for the branch or its agents."},"website":{"type":"string","description":"URL of the agency's website. It may point at the branch page or the agency home page."},"address":{"type":"string","description":"Postal address of the branch office, as a single formatted string."},"postcode":{"type":"string","description":"Postcode of the branch office."}},"description":"The agent marketing this property. Null when the source supplied no agent details."},"createdAt":{"type":"string","format":"date-time","description":"When this listing first appeared in the API, as an ISO 8601 timestamp. It differs from `publishedDate` when a listing is imported after the event.","example":"2024-01-15T10:30:00Z"},"updatedAt":{"type":"string","format":"date-time","description":"When this listing was last updated, as an ISO 8601 timestamp. It moves whenever any field changes, including price revisions, status changes and new images.","example":"2024-01-15T10:30:00Z"}},"required":["id","provider","key","propertyType","type","status","address"],"additionalProperties":{},"description":"A single UK residential or commercial property advertised for sale or to rent. Listings come from several data providers, and an aggregated listing pulls together everything held for the property. Prices are in pounds."},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of property listings, with the counters needed to fetch the rest."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/listings/query/advanced":{"post":{"operationId":"queryListingsAdvanced","x-speakeasy-name-override":"queryListingsAdvanced","tags":["Listings"],"summary":"Advanced listing search","description":"Searches the aggregated listings by geographic area and by any filterable field, with sorting and a choice of which fields to return. It returns the full nested listing document, unlike the simpler POST /listings/query. A page holds at most 100 listings and the offset cannot exceed 10000.","requestBody":{"description":"The areas, filters, sort order, fields and page to return.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ListingAdvancedQueryRequest"}}}},"responses":{"200":{"description":"The matching aggregated listings, one page at a time.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"$ref":"#/components/schemas/AdvancedListing"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of aggregated listings matching the search, with the counters needed to fetch the rest."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/listings/source/query":{"post":{"operationId":"queryListingsBySource","x-speakeasy-name-override":"queryListingsBySource","tags":["Listings"],"summary":"Query listings by provider and keys","description":"Returns the aggregated listing for each of the provider references you supply, up to 500 per request. A reference that matches nothing is left out of the response rather than reported, so compare what comes back against what you sent.","requestBody":{"description":"The provider and the references to look up.","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","description":"The data provider to look the listings up in. Every key in the request must belong to this provider.","example":"provider-a"},"keys":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500,"description":"The provider's own listing references to look up. Minimum 1, maximum 500. A key that matches no listing is left out of the response rather than reported as an error.","example":["12345678","87654321"]}},"required":["provider","keys"],"description":"A lookup of several listings by the provider's own references. Returns the aggregated record for each key that matches, which suits keeping an external system in step with listings you already know."}}}},"responses":{"200":{"description":"The listings that matched the supplied references.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid","description":"Identifier for this listing. It stays the same across updates, so a listing keeps its identifier when the price or status changes.","example":"123e4567-e89b-12d3-a456-426614174000"},"locationId":{"type":["string","null"],"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN). Null when the listing has not been matched to a location.","example":"SW1A1AA"},"provider":{"type":"string","description":"Identifier for the data provider that supplied this listing. Together with `key` it names one source record.","example":"provider-a"},"key":{"type":"string","description":"The listing's own reference within the provider's system. Together with `provider` it names one source record.","example":"12345678"},"currency":{"type":"string","default":"GBP","description":"ISO 4217 currency code for the monetary values in this listing. Defaults to `GBP`.","example":"GBP"},"price":{"type":["number","null"],"exclusiveMinimum":0,"description":"Current price for the listing, in pounds: the asking price for a sale, or the rent for a rental. It reflects the most recent revision. Null when the source publishes no price.","example":50000000},"priceHistory":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date-time","description":"When the price change was recorded, as an ISO 8601 timestamp.","example":"2024-01-15T10:30:00Z"},"price":{"type":"number","exclusiveMinimum":0,"description":"The price after the change, in pounds: the revised asking price for a sale listing, or the revised rent for a rental.","example":50000000},"oldPrice":{"type":"number","exclusiveMinimum":0,"description":"The price before the change, in pounds. Not present for the first price recorded for a listing.","example":52000000},"amount":{"type":"number","description":"The new price minus the old one, in pounds, rounded to two decimal places. Negative when the price was cut.","example":-2000000},"percent":{"type":"number","description":"The change as a percentage of the previous price, rounded to two decimal places. Negative when the price was cut, so -3.85 is a cut of 3.85 per cent.","example":-3.85},"direction":{"type":"string","enum":["increase","decrease","nochange"],"description":"Whether the price went up, went down, or stayed the same at this revision.","example":"decrease"}},"required":["date","price"],"description":"One price revision recorded against the listing, with the size of the change in pounds."},"description":"Price revisions recorded against the listing, one entry per change. Use it to track asking-price cuts and increases over time."},"propertyType":{"type":"string","description":"What kind of property this is, standardised from each provider's own wording to one set of values: unknown, other, flat, detached, semiDetached, terraced, bungalow, maisonette, cottage, chalet, lodge, mobileHome, houseboat, retirement, characterProperty, blockOfFlats, houseShare, farmhouse, mill, barn, coachHouse, statelyHome, farm, parking, equestrian, restaurant, industrial, warehouse, leisure, retail, land, office, riad, hotel, studentAccommodation, commercial, pub, bar, hotelRoom, shop, retailHighStreet, retailOutOfTown, industrialDevelopment, distributionWarehouse, industrialPark, storage, servicedOffice, residentialDevelopment, commercialDevelopment, mixedUse. The field is a plain string rather than a fixed enumeration, so an occasional value outside that set is possible.","example":"terraced"},"subPropertyType":{"type":["string","null"],"description":"Further detail on the kind of property, such as its period or style. Null when the source gives no such detail.","example":"Victorian"},"beds":{"type":["number","null"],"description":"Number of bedrooms advertised. Null when the listing does not state one.","example":3},"baths":{"type":["number","null"],"description":"Number of bathrooms advertised. Null when the listing does not state one.","example":2},"receptions":{"type":["number","null"],"description":"Number of reception rooms advertised, meaning the living, dining and sitting rooms. Null when the listing does not state one.","example":1},"isRetirement":{"type":"boolean","description":"True when the property is age-restricted retirement or sheltered housing.","example":false},"isNewBuild":{"type":"boolean","description":"True when the property is newly built and has not been lived in before.","example":false},"isSharedOwnership":{"type":"boolean","description":"True when the property is offered under a shared ownership scheme, where the buyer owns a share and pays rent on the rest.","example":false},"isAuction":{"type":"boolean","description":"True when the property is being sold at auction rather than by private treaty.","example":false},"type":{"type":"string","enum":["sale","rent"],"description":"Whether the property is advertised for sale or to rent. This governs how to read the price: an asking price for 'sale', the rent quoted by the source for 'rent'.","example":"sale"},"status":{"type":"string","enum":["live","archived","removed"],"description":"Where the listing stands in its marketing life. 'live': currently being marketed. 'removed': withdrawn, or no longer present in the source feed.","example":"live"},"category":{"type":["string","null"],"enum":["residential","commercial",null],"description":"Broad category the property falls into: a residential dwelling, or commercial premises such as offices, retail units, warehouses and industrial space.","example":"residential"},"spatial":{"type":["object","null"],"properties":{"type":{"type":"string","enum":["Point"],"description":"Geometry type discriminator. Always `Point`."},"coordinates":{"type":"array","prefixItems":[{"type":"number","minimum":-180,"maximum":180},{"type":"number","minimum":-90,"maximum":90}],"description":"A single position: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1278,51.5074]}},"required":["type","coordinates"],"additionalProperties":false,"description":"Where the property sits, as a GeoJSON Point. Null when the listing carries no coordinates.","title":"GeoJSON Point","example":{"type":"Point","coordinates":[-0.1278,51.5074]}},"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the property in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the property in WGS84 decimal degrees.","example":-0.1278},"address":{"type":"object","properties":{"propertyNumber":{"type":["string","null"],"description":"Building number for the property, including any suffix such as '12A' or a range such as '3-5'.","example":"123"},"street":{"type":["string","null"],"description":"Name of the street the property sits on, without the building number.","example":"High Street"},"city":{"type":["string","null"],"description":"Town, city or village used in the postal address.","example":"London"},"region":{"type":["string","null"],"description":"County or wider administrative area the property sits in.","example":"Greater London"},"district":{"type":["string","null"],"description":"District, borough or neighbourhood within the town or city.","example":"Westminster"},"postcode":{"type":"string","description":"Full UK postcode for the property, such as `SW1A 1AA`.","example":"SW1A 1AA"},"outcode":{"type":["string","null"],"description":"The postcode's outward code (the first part, such as `SW1A`), which groups a wider area.","example":"SW1A"},"incode":{"type":["string","null"],"description":"The part of the postcode after the space, such as `1AA`. With the outward code it forms the full postcode.","example":"1AA"},"country":{"type":"string","default":"GB","description":"Country the property is in, as an ISO 3166-1 alpha-2 code. Defaults to `GB`.","example":"GB"},"originalAddress":{"type":"string","description":"The address exactly as the source supplied it, before it was parsed into the fields above.","example":"123 High Street, London SW1A 1AA"}},"required":["postcode","originalAddress"],"description":"Postal address of the listed property, parsed into its parts. A part is absent when the source did not supply it; the postcode is always present."},"displayAddress":{"type":"string","description":"The address as the listing presents it, ready to show in search results and listing cards. Use `address` for the parsed parts.","example":"High Street, London SW1A 1AA"},"publishedDate":{"type":["string","null"],"format":"date-time","description":"When the listing was first published by the source, as an ISO 8601 timestamp. It does not change when the listing is later updated, and is null when the source does not publish one.","example":"2024-01-15T10:30:00Z"},"removedDate":{"type":["string","null"],"format":"date-time","description":"When the listing was removed from the source, as an ISO 8601 timestamp. Null while the listing is still there.","example":"2024-01-15T10:30:00Z"},"images":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Photographs of the property, in the order the source supplied them. Empty when there are none. Returned only to API keys entitled to listing media."},"energyRatingImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Energy Performance Certificate chart images. Empty when there are none. Returned only to API keys entitled to listing media."},"floorPlanImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Floor plan images showing the layout of the property, sometimes one per storey. Empty when there are none. Returned only to API keys entitled to listing media."},"brochureImages":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","format":"uri","description":"Absolute URL of the image file.","example":"https://media.example.com/image/123/800x600.jpg"},"caption":{"type":["string","null"],"description":"Caption describing what the image shows, as supplied with the listing.","example":"Living room"},"order":{"type":"number","description":"Position of the image within its type group, counting from 0. The lowest number is the primary image.","example":1},"type":{"type":"string","enum":["standard","floorplan","epc","brochure"],"description":"What the image shows: property photography, a floor plan, an Energy Performance Certificate chart, or a page from the marketing brochure.","example":"standard"}},"required":["url"],"description":"One image belonging to a property listing."},"default":[],"description":"Images taken from the marketing brochure. Empty when there are none. Returned only to API keys entitled to listing media."},"features":{"type":["array","null"],"items":{"type":"object","properties":{"featureId":{"type":"string","description":"Key naming the feature, for example 'TENURE', 'FLOORS' or 'FLOOR_AREA'. Feature keys are an open set that varies by data provider, so treat this as free-form rather than a fixed list.","example":"parking"},"value":{"type":"string","description":"The value stated for the feature, as supplied with the listing. It may be a yes or no answer, a measurement, or a category such as 'Freehold'.","example":"Driveway parking"}},"required":["featureId","value"],"description":"One property feature stated in the listing, as a key and the value given for it."},"description":"Features stated in the listing as key and value pairs, covering things such as tenure and floor area. Null when the source supplied none."},"narratives":{"type":["array","null"],"items":{"type":"object","properties":{"type":{"type":"string","enum":["summary","description","features","location","other"],"description":"What this block of marketing text covers: a short overview, the full description, the list of key features, the surrounding area, or anything that fits none of those.","example":"description"},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"The text itself. A string holds one block of prose; an array holds an ordered list of paragraphs or bullet points, one per element. Null when the block carries no text.","example":"Beautiful property in prime location"}},"required":["type","content"],"description":"A block of marketing copy supplied with the listing. It is written to sell the property, so treat it as the agent's description rather than verified fact."},"description":"The marketing text written by the agent, split into blocks by what each one covers. Null when the source supplied none."},"agent":{"type":["object","null"],"properties":{"agentName":{"type":"string","description":"Name of the individual agent or negotiator handling this listing.","example":"John Smith"},"branchName":{"type":"string","description":"Name of the branch marketing this property. An agency may run several branches.","example":"London Branch"},"agencyName":{"type":"string","description":"Trading name of the agency the branch belongs to.","example":"Premier Estate Agents"},"agentId":{"type":"string","description":"Identifier for the individual agent in the source provider's system. Its format varies by provider."},"branchId":{"type":"string","description":"Identifier for the branch in the source provider's system, which can be used to group listings by branch."},"agencyId":{"type":"string","description":"Identifier for the agency in the source provider's system, which can be used to group listings across all of its branches."},"phone":{"type":"string","description":"Main contact telephone number for the branch. Formatting varies between sources.","example":"02012345678"},"phones":{"type":"array","items":{"type":"string"},"description":"Any further telephone numbers held for the branch."},"email":{"type":"string","description":"Main contact email address for the branch.","example":"agent@example.com"},"emails":{"type":"array","items":{"type":"string"},"description":"Any further email addresses held for the branch or its agents."},"website":{"type":"string","description":"URL of the agency's website. It may point at the branch page or the agency home page."},"address":{"type":"string","description":"Postal address of the branch office, as a single formatted string."},"postcode":{"type":"string","description":"Postcode of the branch office."}},"description":"The agent marketing this property. Null when the source supplied no agent details."},"createdAt":{"type":"string","format":"date-time","description":"When this listing first appeared in the API, as an ISO 8601 timestamp. It differs from `publishedDate` when a listing is imported after the event.","example":"2024-01-15T10:30:00Z"},"updatedAt":{"type":"string","format":"date-time","description":"When this listing was last updated, as an ISO 8601 timestamp. It moves whenever any field changes, including price revisions, status changes and new images.","example":"2024-01-15T10:30:00Z"}},"required":["id","provider","key","propertyType","type","status","address"],"additionalProperties":{},"description":"A single UK residential or commercial property advertised for sale or to rent. Listings come from several data providers, and an aggregated listing pulls together everything held for the property. Prices are in pounds."},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of property listings, with the counters needed to fetch the rest."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/listings/health":{"get":{"operationId":"checkListingsHealth","x-speakeasy-name-override":"checkListingsHealth","tags":["System"],"summary":"Listings service health check","description":"Reports whether the listings service is answering requests.","responses":{"200":{"description":"The service is answering, with its name and the time of the check.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"service":{"type":"string"},"timestamp":{"type":"string"}},"required":["status","service","timestamp"]}}}}}}},"/v1/planning/{applicationIds}":{"get":{"operationId":"getPlanningApplications","x-speakeasy-name-override":"getPlanningApplications","tags":["Planning"],"summary":"Get planning applications by ID","description":"Returns planning applications by the identifiers this API assigns to them. Give up to 100 identifiers in the path, separated by commas; identifiers that match nothing are left out of the response rather than reported. If you hold council reference numbers instead, use GET /sources/{sourceIds}. Set the include parameter to attach optional expansions, comma-separated: 'extractions' for the structured, quote-backed extractions, 'images' for the image gallery, 'content' for each document's file and text addresses, and 'enrichment' for the classification reasoning and document summaries.","parameters":[{"schema":{"type":"string","description":"One or more application identifiers, separated by commas, up to 100 per request. These are the values returned in each application's id field. If you hold council reference numbers instead, use GET /sources/{sourceIds}.","example":"a1b2c3d4-e5f6-7890-abcd-ef1234567890,b2c3d4e5-f6a7-8901-bcde-f12345678901"},"required":true,"description":"One or more application identifiers, separated by commas, up to 100 per request. These are the values returned in each application's id field. If you hold council reference numbers instead, use GET /sources/{sourceIds}.","name":"applicationIds","in":"path"},{"schema":{"type":"string","description":"Extra data to attach to each application returned, as a comma-separated list. Accepts 'extractions' (the structured, quote-backed extractions), 'images' (the deduplicated image gallery), 'content' (fileUrl and ocrUrl on each document) and 'enrichment' (classification reasoning and document segmentation summaries). All are left off by default, and 'extractions', 'images' and 'enrichment' each add a further lookup, so ask only for what you need. Names that are not recognised are ignored.","example":"extractions,images,content"},"required":false,"description":"Extra data to attach to each application returned, as a comma-separated list. Accepts 'extractions' (the structured, quote-backed extractions), 'images' (the deduplicated image gallery), 'content' (fileUrl and ocrUrl on each document) and 'enrichment' (classification reasoning and document segmentation summaries). All are left off by default, and 'extractions', 'images' and 'enrichment' each add a further lookup, so ask only for what you need. Names that are not recognised are ignored.","name":"include","in":"query"}],"responses":{"200":{"description":"The planning applications matching the identifiers supplied, all in one page. Identifiers that match nothing are omitted, so total_count can be lower than the number you sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why. This endpoint rejects a path with no identifiers in it, and one carrying more than 100.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/planning/sources/{sourceIds}":{"get":{"operationId":"getPlanningApplicationsBySource","x-speakeasy-name-override":"getPlanningApplicationsBySource","tags":["Planning"],"summary":"Get planning applications by source ID","description":"Returns planning applications by their source identifiers, each of the form `provider::key`, where provider is the council slug and key is that council's own reference number, for example 'lambeth::24/00123/FUL'. Give up to 100 in the path, separated by commas; identifiers that match nothing are left out of the response rather than reported. This is the lookup to use when you know the council and its reference number. Set the include parameter to attach optional expansions, comma-separated: 'extractions' for the structured, quote-backed extractions, 'images' for the image gallery, 'content' for each document's file and text addresses, and 'enrichment' for the classification reasoning and document summaries.","parameters":[{"schema":{"type":"string","description":"One or more source identifiers, separated by commas, up to 100 per request. Each takes the form `provider::key`, where provider is the council slug and key is that council's reference number, for example 'lambeth::24/00123/FUL'. This is the lookup to use when you know the council and its reference number.","example":"lambeth::24/00123/FUL,manchester::135026/FO/2024"},"required":true,"description":"One or more source identifiers, separated by commas, up to 100 per request. Each takes the form `provider::key`, where provider is the council slug and key is that council's reference number, for example 'lambeth::24/00123/FUL'. This is the lookup to use when you know the council and its reference number.","name":"sourceIds","in":"path"},{"schema":{"type":"string","description":"Extra data to attach to each application returned, as a comma-separated list. Accepts 'extractions' (the structured, quote-backed extractions), 'images' (the deduplicated image gallery), 'content' (fileUrl and ocrUrl on each document) and 'enrichment' (classification reasoning and document segmentation summaries). All are left off by default, and 'extractions', 'images' and 'enrichment' each add a further lookup, so ask only for what you need. Names that are not recognised are ignored.","example":"extractions,images,content"},"required":false,"description":"Extra data to attach to each application returned, as a comma-separated list. Accepts 'extractions' (the structured, quote-backed extractions), 'images' (the deduplicated image gallery), 'content' (fileUrl and ocrUrl on each document) and 'enrichment' (classification reasoning and document segmentation summaries). All are left off by default, and 'extractions', 'images' and 'enrichment' each add a further lookup, so ask only for what you need. Names that are not recognised are ignored.","name":"include","in":"query"}],"responses":{"200":{"description":"The planning applications matching the source identifiers supplied, all in one page. Identifiers that match nothing are omitted, so total_count can be lower than the number you sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why. This endpoint rejects a path with no source identifiers in it, one carrying more than 100, and any identifier that is not in `provider::key` form.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/planning/query":{"post":{"operationId":"searchPlanningApplications","x-speakeasy-name-override":"searchPlanningApplications","tags":["Planning"],"summary":"Search planning applications","description":"Searches planning applications by council, status, type, development category and date range. Use the `near` filter (lat, lng and radiusM) to find the applications around a point: matches come back closest first, each carrying `distance` in metres, and that ordering replaces sortBy and sortOrder. Separate filters are combined with AND, while several values inside one array filter are combined with OR. Results are paginated at up to 100 per page, and `include` attaches any of the extractions, the image gallery, document file and text addresses, or the classification reasoning to each application returned.","requestBody":{"description":"The filters, pagination, sort order and expansions that define the search.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningQueryRequest"}}}},"responses":{"200":{"description":"One page of planning applications matching the search. total_count gives the size of the whole match set and has_more says whether further pages remain; raise offset by the limit to fetch the next page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PlanningListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/planning/health":{"get":{"operationId":"checkPlanningHealth","x-speakeasy-name-override":"checkPlanningHealth","tags":["System"],"summary":"Check planning service health","description":"Confirms that the planning endpoints are reachable. The check does not read any planning data, so a healthy response says nothing about whether that data is available.","responses":{"200":{"description":"The service status, the name of the service, and the time the check was answered.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/location/street/query":{"post":{"operationId":"searchStreets","x-speakeasy-name-override":"searchStreets","tags":["Streets"],"summary":"Query streets by any identifier","description":"Returns the streets picked out by one of five identifiers: a USRN, a UPRN, a coordinate and radius, a name search, or a postcode. Each street comes back with its reference number, the dataset that supplied it, its name in each language it is recorded in, its place names and a representative point. `dataset` chooses between Ordnance Survey open data, the Ordnance Survey National Geographic Database (NGD), or open data with the NGD answering only where the open data has nothing. Name, coordinate and postcode lookups are paged: pass the `id` of the last street as `starting_after` while `has_more` is true. Responses that carry open data include the `attribution` that must be shown with it. When an identifier matches no street, the response is an empty list with a `message` explaining which one missed.","requestBody":{"description":"The identifier to look streets up by, and what to return alongside them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StreetQueryRequest"}}}},"responses":{"200":{"description":"The matching streets.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StreetQueryResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why. A postcode lookup under `dataset: open`, and a `starting_after` that is not a street in the result set, are rejected here.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/location/health":{"get":{"operationId":"checkLocationHealth","x-speakeasy-name-override":"checkLocationHealth","tags":["System"],"summary":"Check location service health","description":"Reports whether the location service is running. Use it as a liveness check.","responses":{"200":{"description":"The service is running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/schools/autocomplete":{"get":{"operationId":"autocompleteSchools","x-speakeasy-name-override":"autocomplete","tags":["Schools"],"summary":"Autocomplete schools by name","description":"Suggests schools as someone types a name. Names that start with the query come first, then close matches, so a small typo still returns results. The query must be at least 2 characters and at most 25 suggestions are returned. Results are cached for an hour.","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":100,"description":"Text to match against school names. Names that start with it come first, then close matches so a small typo still returns results.","example":"St Mary"},"required":true,"description":"Text to match against school names. Names that start with it come first, then close matches so a small typo still returns results.","name":"q","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":25,"default":10,"description":"Maximum number of suggestions to return. Defaults to 10. Minimum 1, maximum 25.","example":10},"required":false,"description":"Maximum number of suggestions to return. Defaults to 10. Minimum 1, maximum 25.","name":"limit","in":"query"},{"schema":{"anyOf":[{"type":"boolean"},{"type":"string"}],"default":true,"description":"Limits suggestions to schools with a status of 'open'. Defaults to true; set it to false to include closed and pending-closure schools.","example":true},"required":false,"description":"Limits suggestions to schools with a status of 'open'. Defaults to true; set it to false to include closed and pending-closure schools.","name":"onlyOpen","in":"query"}],"responses":{"200":{"description":"Schools whose name matches the query, closest match first.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier for the school within this API. Pass it to `/v1/schools/{id}` for the full record.","example":12345},"name":{"type":"string","description":"Name of the school as its source register publishes it.","example":"St Mary's Primary School"},"slug":{"type":["string","null"],"description":"URL-friendly form of the school name, safe to use in a path. Null when none has been generated.","example":"st-marys-primary-school-westminster"},"type":{"type":"string","enum":["nursery","primary","secondary","all-through","sixth-form","special","independent","academy","other"],"description":"The kind of institution the school is. 'nursery' is early years, 'primary' covers key stages 1 and 2, 'secondary' covers key stages 3 and 4, 'all-through' combines primary and secondary, and 'sixth-form' is post-16 only. 'special' is special educational needs provision, 'independent' is fee-paying, 'academy' is state-funded but independently run, and 'other' covers alternative provision, pupil referral units and anything the register leaves unclassified.","example":"primary"},"postcode":{"type":["string","null"],"description":"Postcode of the school. Null when the record holds none.","example":"SW1A 1AA"},"authority":{"type":["string","null"],"description":"Local authority the school falls under. Null when the record holds none.","example":"Westminster"},"countryCode":{"type":"string","minLength":2,"maxLength":2,"description":"Country the school is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"regionCode":{"type":"string","description":"Education system the school belongs to, as an ISO 3166-2 region code.","example":"GB-ENG"},"provider":{"type":"string","description":"Which national register issued `providerId`.","example":"dfe"},"providerId":{"type":"string","description":"The identifier that register uses for the school, such as a URN under `dfe`.","example":"100000"}},"required":["id","name","slug","type","postcode","authority","countryCode","regionCode","provider","providerId"],"description":"A short school record, carrying just enough to render a suggestion and follow it up."},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of suggestions, with the metadata needed to fetch the rest."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/schools/source/{provider}/{key}":{"get":{"operationId":"getSchoolBySource","x-speakeasy-name-override":"getSchoolBySource","tags":["Schools"],"summary":"Get school by provider and key","description":"Returns one school by the identifier its own national register uses, for callers holding a register key rather than an identifier from this API. The registers are `dfe` for England and cross-border Welsh URNs, `welshgov` for the Welsh Government school number, `seed` for the Scottish SEED code, `deni` for the Northern Ireland reference and `dept_edu_ie` for the Irish roll number. Use `attributes` to add aggregate blocks or trim the fields returned.","parameters":[{"schema":{"type":"string","enum":["dfe","welshgov","seed","deni","dept_edu_ie"],"description":"Which national register issued the school's `key`. 'dfe' is the Department for Education register for England, which also carries cross-border Welsh URNs. 'welshgov' is the Welsh Government school number. 'seed' is the Scottish SEED code. 'deni' is the Northern Ireland Department of Education reference. 'dept_edu_ie' is the Irish roll number.","example":"dfe"},"required":true,"description":"Which national register issued the school's `key`. 'dfe' is the Department for Education register for England, which also carries cross-border Welsh URNs. 'welshgov' is the Welsh Government school number. 'seed' is the Scottish SEED code. 'deni' is the Northern Ireland Department of Education reference. 'dept_edu_ie' is the Irish roll number.","name":"provider","in":"path"},{"schema":{"type":"string","description":"The identifier that register uses for the school, such as a URN under `dfe`.","example":"100000"},"required":true,"description":"The identifier that register uses for the school, such as a URN under `dfe`.","name":"key","in":"path"},{"schema":{"type":"string","description":"Comma-separated list of the fields and blocks to return. Omit it to get the whole school record with no aggregate blocks. Naming a block (`inspections`, `identifiers`, `trust`, `images`, `branding`, `accreditations`, `videos`, `about`) adds that block to the whole record; naming at least one ordinary field instead trims the response to the fields listed plus any blocks. `object` and `id` are always returned and names that are not recognised are ignored. Performance, census and finance figures are not part of this record, request them from `/v1/schools/metrics`.","example":"id,name,currentRating,inspections"},"required":false,"description":"Comma-separated list of the fields and blocks to return. Omit it to get the whole school record with no aggregate blocks. Naming a block (`inspections`, `identifiers`, `trust`, `images`, `branding`, `accreditations`, `videos`, `about`) adds that block to the whole record; naming at least one ordinary field instead trims the response to the fields listed plus any blocks. `object` and `id` are always returned and names that are not recognised are ignored. Performance, census and finance figures are not part of this record, request them from `/v1/schools/metrics`.","name":"attributes","in":"query"}],"responses":{"200":{"description":"The school registered under that provider and key.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["school"],"description":"Object type discriminator. Always `school`.","example":"school"},"id":{"type":"integer","description":"Identifier for the school within this API. Stable across updates.","example":12345},"country":{"type":"string","minLength":2,"maxLength":2,"default":"GB","description":"Country the school is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"region":{"type":"string","description":"Education system the school belongs to, as an ISO 3166-2 region code. `GB-ENG` is England, `GB-WLS` Wales, `GB-SCT` Scotland and `GB-NIR` Northern Ireland.","example":"GB-ENG"},"provider":{"type":"string","enum":["dfe","welshgov","seed","deni","dept_edu_ie"],"description":"Which national register issued the school's `key`. 'dfe' is the Department for Education register for England, which also carries cross-border Welsh URNs. 'welshgov' is the Welsh Government school number. 'seed' is the Scottish SEED code. 'deni' is the Northern Ireland Department of Education reference. 'dept_edu_ie' is the Irish roll number.","example":"dfe"},"key":{"type":"string","description":"The identifier the source register uses for this school, such as a URN under `dfe` or a SEED code under `seed`. Together with `provider` it identifies the school across jurisdictions.","example":"100000"},"name":{"type":"string","description":"Name of the school as its source register publishes it.","example":"St Mary's Primary School"},"slug":{"type":["string","null"],"description":"URL-friendly form of the school name, safe to use in a path. Null when none has been generated.","example":"st-marys-primary-school-westminster"},"type":{"type":"string","enum":["nursery","primary","secondary","all-through","sixth-form","special","independent","academy","other"],"description":"The kind of institution the school is. 'nursery' is early years, 'primary' covers key stages 1 and 2, 'secondary' covers key stages 3 and 4, 'all-through' combines primary and secondary, and 'sixth-form' is post-16 only. 'special' is special educational needs provision, 'independent' is fee-paying, 'academy' is state-funded but independently run, and 'other' covers alternative provision, pupil referral units and anything the register leaves unclassified.","example":"primary"},"subType":{"type":"string","description":"Finer-grained establishment type as the source register classifies it, for example 'Voluntary Aided School' or 'Academy Converter'.","example":"Voluntary Aided School"},"status":{"type":"string","enum":["open","closed","pending_closure"],"description":"Operating status of the school, as recorded by its source register. 'open' means it is operating, 'closed' means it has closed, and 'pending_closure' means the register has flagged it for closure. Filter on 'open' to exclude the other two.","example":"open"},"currentRating":{"type":["string","null"],"enum":["outstanding","good","satisfactory","inadequate","exceptional","strong_standard","expected_standard","needs_attention","urgent_improvement","requires_improvement","not_yet_inspected","excellent","adequate","unsatisfactory","very_good","weak","important_area_for_improvement","requires_significant_improvement","fair",null],"description":"The most recent inspection grade, in the words of the inspectorate that issued it: Ofsted in England, Estyn in Wales, Education Scotland, ETI in Northern Ireland and the DES Inspectorate in Ireland. The scales differ between inspectorates, so a grade is only comparable within one of them.","example":"good"},"lastInspectionDate":{"type":"string","description":"When the most recent inspection took place, as an ISO 8601 date.","example":"2024-01-15"},"location":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the school, in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the school, in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"description":"Point location of the school."},"address":{"type":"object","properties":{"street":{"type":"string","description":"Building number and street.","example":"123 High Street"},"locality":{"type":"string","description":"District or locality the school sits in.","example":"Westminster"},"town":{"type":"string","description":"Town or city.","example":"London"},"county":{"type":"string","description":"County or equivalent wider area.","example":"Greater London"},"postcode":{"type":"string","description":"Postcode in the format used by the school's own country, such as a UK postcode or an Eircode.","example":"SW1A 1AA"}},"description":"Postal address of the school."},"lsoaCode":{"type":["string","null"],"description":"Lower Layer Super Output Area (LSOA) code covering the school, for joining to area-level datasets. Null when no LSOA has been mapped to the school.","example":"E01004736"},"phase":{"type":"string","description":"Phase of education the source register assigns the school, in the register's own wording.","example":"Primary"},"ageRange":{"type":"string","description":"Age range the school covers, as the youngest and oldest age separated by a hyphen.","example":"4-11"},"gender":{"type":"string","description":"Whether the school admits boys, girls or both, in the source register's own wording.","example":"Mixed"},"religiousCharacter":{"type":"string","description":"Religious character the source register records for the school.","example":"Church of England"},"admissionsPolicy":{"type":"string","description":"Admissions policy the source register records for the school.","example":"Comprehensive"},"capacity":{"type":"integer","description":"Number of pupil places the source register records for the school.","example":420},"numberOfPupils":{"type":"integer","description":"Number of pupils the source register records for the school.","example":385},"specialClasses":{"type":"string"},"specialistResource":{"type":"string"},"trustName":{"type":"string","description":"Name of the trust the school belongs to, where the source register records one.","example":"London Academy Trust"},"trustId":{"type":"string","description":"Identifier of that trust in the source register.","example":"TR00123"},"laCode":{"type":"string","description":"Code of the local authority the school falls under.","example":"213"},"laName":{"type":"string","description":"Name of the local authority the school falls under.","example":"Westminster"},"establishmentNumber":{"type":"integer","description":"Establishment number the source register assigns the school.","example":3614},"headteacher":{"type":"string","description":"Name of the headteacher, where the source register records one.","example":"Mrs J Smith"},"telephone":{"type":"string","description":"Contact telephone number for the school.","example":"020 1234 5678"},"website":{"type":"string","description":"URL of the school's own website.","example":"https://www.example.sch.uk"},"distance":{"type":"number","description":"Distance from the search point, in metres. Present only on results from a `near` search.","example":1234.56},"catchment":{"$ref":"#/components/schemas/SchoolCatchmentBlock"},"inspections":{"type":["object","null"],"properties":{"current":{"$ref":"#/components/schemas/SchoolInspectionEvent"},"history":{"type":"array","items":{"$ref":"#/components/schemas/SchoolInspectionEvent"},"default":[],"description":"Every recorded inspection, newest first. The first entry is the same event as `current`."}},"required":["current"],"description":"The current inspection and the full history behind it. Present only when requested via `attributes=inspections`."},"identifiers":{"type":["object","null"],"properties":{"ukprn":{"type":["string","null"],"description":"The school's UK Provider Reference Number (UKPRN).","example":"10012345"},"estynId":{"type":["string","null"],"description":"The school's provider identifier with Estyn, the Welsh inspectorate."},"ofstedProviderId":{"type":["string","null"],"description":"The school's provider identifier with Ofsted, the English inspectorate."},"oldUrns":{"type":"array","items":{"type":"string"},"default":[],"description":"Unique Reference Numbers (URNs) this school was known by before. Empty when there are none."}},"description":"The identifiers this school carries in registers other than `provider`. Present only when requested via `attributes=identifiers`."},"trust":{"type":["object","null"],"properties":{"memberships":{"type":"array","items":{"$ref":"#/components/schemas/SchoolTrustMembership"},"default":[],"description":"The organisations the school currently belongs to, governance-leadership roles first."}},"description":"The trusts, federations and other organisations the school currently belongs to. Present only when requested via `attributes=trust`."},"images":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"$ref":"#/components/schemas/SchoolImage"},"default":[],"description":"Photographs of the school's buildings and facilities, newest first. Only images cleared for publication appear here, so the list can be empty."}},"description":"Photographs of the school's buildings and facilities, taken from its own website. Requested via `attributes=images`, and null until at least one photograph is cleared for publication."},"branding":{"type":["object","null"],"properties":{"logoUrl":{"type":"string","description":"Public URL of the logo or crest.","example":"https://hot-cdn.vepler.com/schools/12345/images/ab12cd.png"},"primaryColour":{"type":"string","description":"Primary brand colour, as a hex code.","example":"#00a1d5"},"secondaryColour":{"type":"string","description":"Secondary brand colour, as a hex code.","example":"#1c1c1c"},"socialMedia":{"$ref":"#/components/schemas/SocialMediaLinks"}},"description":"The school's logo or crest and its social profiles, taken from its own website. Requested via `attributes=branding`, and null until at least one of them is cleared for publication."},"accreditations":{"type":["object","null"],"properties":{"accreditations":{"type":"array","items":{"$ref":"#/components/schemas/SchoolAccreditation"},"default":[],"description":"Award, kitemark and partner badges shown on the school's own website, newest first. Only badges cleared for publication appear here, so the list can be empty."}},"description":"Awards, kitemarks and partner badges the school displays on its own website. Requested via `attributes=accreditations`, and null until they are cleared for publication."},"videos":{"type":["object","null"],"properties":{"videos":{"type":"array","items":{"$ref":"#/components/schemas/SchoolVideo"},"default":[],"description":"Videos published on the school's own website. Only videos cleared for publication appear here, so the list can be empty."}},"description":"References to videos the school publishes, as metadata rather than the video itself. Requested via `attributes=videos`, and null until they are cleared for publication."},"about":{"type":["object","null"],"properties":{"ethos":{"type":["string","null"],"description":"The school's stated ethos and values."},"headteacherWelcome":{"type":["string","null"],"description":"The headteacher's published welcome message."},"sendStatement":{"type":["string","null"],"description":"The school's statement on special educational needs and disabilities (SEND), and on inclusion."},"clubsDescription":{"type":["string","null"],"description":"What the school publishes about its extra-curricular clubs."},"facilitiesDescription":{"type":["string","null"],"description":"What the school publishes about its facilities."},"aboutDescription":{"type":["string","null"],"description":"The school's general description of itself."},"historyDescription":{"type":["string","null"],"description":"The school's account of its own history."},"curriculumDescription":{"type":["string","null"],"description":"What the school publishes about its curriculum."},"resultsSummary":{"type":["string","null"],"description":"The school's own summary of its results, in the wording it published."},"uniformSupplier":{"type":["string","null"],"description":"Name of the uniform supplier, where the school names one."},"prospectusUrl":{"type":["string","null"],"description":"Address of the school's prospectus."},"breakfastClub":{"type":["boolean","null"],"description":"True when the school states that it runs a breakfast club."},"afterSchoolCare":{"type":["boolean","null"],"description":"True when the school states that it offers after-school or wraparound care."},"termDates":{"type":"array","items":{"$ref":"#/components/schemas/SchoolTermDate"},"default":[],"description":"Term and holiday dates as the school publishes them."}},"description":"What the school says about itself: ethos, headteacher's welcome, term dates and similar narrative. Requested via `attributes=about`, and null until the profile has been reviewed."},"createdAt":{"type":"string","description":"When this school first appeared in the API, as an ISO 8601 timestamp.","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","description":"When this record was last changed, as an ISO 8601 timestamp.","example":"2024-01-01T00:00:00.000Z"},"lastUpdated":{"type":"string","description":"When the source register data behind this record was last refreshed, as an ISO 8601 timestamp.","example":"2024-01-01T00:00:00.000Z"}},"required":["object","id","region","provider","key","name","type","status","createdAt","updatedAt","lastUpdated"],"description":"One school record."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/schools/query":{"post":{"operationId":"querySchools","x-speakeasy-name-override":"querySchools","tags":["Schools","Schools Catchment"],"summary":"Query schools with filters and optional catchment enrichment","description":"Searches schools by country and region, by type, status, rating, authority, postcode or free text, or by geography with `near` for a radius and `within` for a bounding box. Page through the results with `limit` and `offset`, up to 100 schools per page. Supplying `catchmentReference`, with either a `uprn` or a `point`, also tests every returned school against that property: each one gains a `catchment` block saying why it matched and how firmly, and the response gains a `meta.catchment` block saying which kinds of evidence were used, which were not and why. When `catchmentReference` is supplied without `near` or `within`, the search is centred on the property with a 10 km radius.","requestBody":{"description":"The filters, paging and optional `catchmentReference` for the search.","content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","minLength":2,"maxLength":2,"description":"Return only schools in this country, given as an ISO 3166-1 alpha-2 code.","example":"GB"},"region":{"type":"string","description":"Return only schools in this education system, given as an ISO 3166-2 region code such as `GB-ENG` or `GB-SCT`.","example":"GB-ENG"},"providers":{"type":"array","items":{"type":"string","enum":["dfe","welshgov","seed","deni","dept_edu_ie"],"description":"Which national register issued the school's `key`. 'dfe' is the Department for Education register for England, which also carries cross-border Welsh URNs. 'welshgov' is the Welsh Government school number. 'seed' is the Scottish SEED code. 'deni' is the Northern Ireland Department of Education reference. 'dept_edu_ie' is the Irish roll number.","example":"dfe"},"description":"Return only schools sourced from these registers. A school matches if it came from any of them.","example":["dfe"]},"query":{"type":"string","description":"Free-text search. Matches schools whose name or postcode contains this text, or whose `key` is exactly this value.","example":"St Mary"},"type":{"anyOf":[{"type":"string","enum":["nursery","primary","secondary","all-through","sixth-form","special","independent","academy","other"],"description":"The kind of institution the school is. 'nursery' is early years, 'primary' covers key stages 1 and 2, 'secondary' covers key stages 3 and 4, 'all-through' combines primary and secondary, and 'sixth-form' is post-16 only. 'special' is special educational needs provision, 'independent' is fee-paying, 'academy' is state-funded but independently run, and 'other' covers alternative provision, pupil referral units and anything the register leaves unclassified.","example":"primary"},{"type":"array","items":{"type":"string","enum":["nursery","primary","secondary","all-through","sixth-form","special","independent","academy","other"],"description":"The kind of institution the school is. 'nursery' is early years, 'primary' covers key stages 1 and 2, 'secondary' covers key stages 3 and 4, 'all-through' combines primary and secondary, and 'sixth-form' is post-16 only. 'special' is special educational needs provision, 'independent' is fee-paying, 'academy' is state-funded but independently run, and 'other' covers alternative provision, pupil referral units and anything the register leaves unclassified.","example":"primary"}}],"description":"Return only schools of this type. Pass an array to match any one of several types."},"status":{"type":"string","enum":["open","closed","pending_closure"],"description":"Operating status of the school, as recorded by its source register. 'open' means it is operating, 'closed' means it has closed, and 'pending_closure' means the register has flagged it for closure. Filter on 'open' to exclude the other two.","example":"open"},"rating":{"anyOf":[{"type":"string","enum":["outstanding","good","satisfactory","inadequate","exceptional","strong_standard","expected_standard","needs_attention","urgent_improvement","requires_improvement","not_yet_inspected","excellent","adequate","unsatisfactory","very_good","weak","important_area_for_improvement","requires_significant_improvement","fair"],"description":"The most recent inspection grade, in the words of the inspectorate that issued it: Ofsted in England, Estyn in Wales, Education Scotland, ETI in Northern Ireland and the DES Inspectorate in Ireland. The scales differ between inspectorates, so a grade is only comparable within one of them.","example":"good"},{"type":"array","items":{"type":"string","enum":["outstanding","good","satisfactory","inadequate","exceptional","strong_standard","expected_standard","needs_attention","urgent_improvement","requires_improvement","not_yet_inspected","excellent","adequate","unsatisfactory","very_good","weak","important_area_for_improvement","requires_significant_improvement","fair"],"description":"The most recent inspection grade, in the words of the inspectorate that issued it: Ofsted in England, Estyn in Wales, Education Scotland, ETI in Northern Ireland and the DES Inspectorate in Ireland. The scales differ between inspectorates, so a grade is only comparable within one of them.","example":"good"}}],"description":"Return only schools on this inspection rating. Pass an array to match any one of several ratings."},"authority":{"type":"string","description":"Return only schools under this local authority. The name must match exactly.","example":"Westminster"},"postcode":{"type":"string","description":"Return only schools whose postcode starts with this text, so `SW1` matches every SW1 postcode.","example":"SW1"},"slug":{"type":"string","description":"Return the school with exactly this `slug`."},"near":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the centre point, in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the centre point, in WGS84 decimal degrees.","example":-0.1278},"radiusM":{"type":"number","exclusiveMinimum":0,"maximum":50000,"default":5000,"description":"How far from the centre point to search, in metres. Defaults to 5000. Maximum 50000.","example":5000}},"required":["lat","lng"],"description":"Search within a radius of a point. Results carry a `distance` field and come back nearest first. Cannot be combined with `within`."},"within":{"type":"object","properties":{"north":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the northern edge."},"south":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the southern edge."},"east":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the eastern edge."},"west":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the western edge."}},"required":["north","south","east","west"],"description":"Search inside a bounding box, in WGS84 decimal degrees. Cannot be combined with `near`."},"limit":{"type":"integer","minimum":1,"maximum":100,"default":25,"description":"Maximum number of schools to return. Defaults to 25. Minimum 1, maximum 100.","example":25},"offset":{"type":"integer","minimum":0,"default":0,"description":"Number of results to skip before the first one returned. Defaults to 0.","example":0},"orderBy":{"type":"string","enum":["name","rating","lastUpdated","distance"],"description":"Field to sort by, applied when the request has no geographic filter. Defaults to `name`. A `near` search always returns the closest schools first, whatever this is set to."},"order":{"type":"string","enum":["asc","desc"],"default":"asc","description":"Direction to sort in. Defaults to ascending.","example":"asc"},"catchmentReference":{"$ref":"#/components/schemas/CatchmentReference"},"attributes":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"The fields and blocks to return for each school, as a comma-separated string or an array. Omit it to get the whole school record with no aggregate blocks. Naming a block (`inspections`, `identifiers`, `trust`, `images`, `branding`, `accreditations`, `videos`, `about`) adds that block to the whole record; naming at least one ordinary field instead trims each school to the fields listed plus any blocks. `object` and `id` are always returned and names that are not recognised are ignored."}},"description":"Filters for a school search. Narrow by country, region and source register, by type, status, rating, authority, postcode or free text, or by geography with `near` or `within`. Page through the results with `limit` and `offset`."}}}},"responses":{"200":{"description":"Matching schools. `meta.catchment` is present when the request supplied `catchmentReference`.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["school"],"description":"Object type discriminator. Always `school`.","example":"school"},"id":{"type":"integer","description":"Identifier for the school within this API. Stable across updates.","example":12345},"country":{"type":"string","minLength":2,"maxLength":2,"default":"GB","description":"Country the school is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"region":{"type":"string","description":"Education system the school belongs to, as an ISO 3166-2 region code. `GB-ENG` is England, `GB-WLS` Wales, `GB-SCT` Scotland and `GB-NIR` Northern Ireland.","example":"GB-ENG"},"provider":{"type":"string","enum":["dfe","welshgov","seed","deni","dept_edu_ie"],"description":"Which national register issued the school's `key`. 'dfe' is the Department for Education register for England, which also carries cross-border Welsh URNs. 'welshgov' is the Welsh Government school number. 'seed' is the Scottish SEED code. 'deni' is the Northern Ireland Department of Education reference. 'dept_edu_ie' is the Irish roll number.","example":"dfe"},"key":{"type":"string","description":"The identifier the source register uses for this school, such as a URN under `dfe` or a SEED code under `seed`. Together with `provider` it identifies the school across jurisdictions.","example":"100000"},"name":{"type":"string","description":"Name of the school as its source register publishes it.","example":"St Mary's Primary School"},"slug":{"type":["string","null"],"description":"URL-friendly form of the school name, safe to use in a path. Null when none has been generated.","example":"st-marys-primary-school-westminster"},"type":{"type":"string","enum":["nursery","primary","secondary","all-through","sixth-form","special","independent","academy","other"],"description":"The kind of institution the school is. 'nursery' is early years, 'primary' covers key stages 1 and 2, 'secondary' covers key stages 3 and 4, 'all-through' combines primary and secondary, and 'sixth-form' is post-16 only. 'special' is special educational needs provision, 'independent' is fee-paying, 'academy' is state-funded but independently run, and 'other' covers alternative provision, pupil referral units and anything the register leaves unclassified.","example":"primary"},"subType":{"type":"string","description":"Finer-grained establishment type as the source register classifies it, for example 'Voluntary Aided School' or 'Academy Converter'.","example":"Voluntary Aided School"},"status":{"type":"string","enum":["open","closed","pending_closure"],"description":"Operating status of the school, as recorded by its source register. 'open' means it is operating, 'closed' means it has closed, and 'pending_closure' means the register has flagged it for closure. Filter on 'open' to exclude the other two.","example":"open"},"currentRating":{"type":["string","null"],"enum":["outstanding","good","satisfactory","inadequate","exceptional","strong_standard","expected_standard","needs_attention","urgent_improvement","requires_improvement","not_yet_inspected","excellent","adequate","unsatisfactory","very_good","weak","important_area_for_improvement","requires_significant_improvement","fair",null],"description":"The most recent inspection grade, in the words of the inspectorate that issued it: Ofsted in England, Estyn in Wales, Education Scotland, ETI in Northern Ireland and the DES Inspectorate in Ireland. The scales differ between inspectorates, so a grade is only comparable within one of them.","example":"good"},"lastInspectionDate":{"type":"string","description":"When the most recent inspection took place, as an ISO 8601 date.","example":"2024-01-15"},"location":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the school, in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the school, in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"description":"Point location of the school."},"address":{"type":"object","properties":{"street":{"type":"string","description":"Building number and street.","example":"123 High Street"},"locality":{"type":"string","description":"District or locality the school sits in.","example":"Westminster"},"town":{"type":"string","description":"Town or city.","example":"London"},"county":{"type":"string","description":"County or equivalent wider area.","example":"Greater London"},"postcode":{"type":"string","description":"Postcode in the format used by the school's own country, such as a UK postcode or an Eircode.","example":"SW1A 1AA"}},"description":"Postal address of the school."},"lsoaCode":{"type":["string","null"],"description":"Lower Layer Super Output Area (LSOA) code covering the school, for joining to area-level datasets. Null when no LSOA has been mapped to the school.","example":"E01004736"},"phase":{"type":"string","description":"Phase of education the source register assigns the school, in the register's own wording.","example":"Primary"},"ageRange":{"type":"string","description":"Age range the school covers, as the youngest and oldest age separated by a hyphen.","example":"4-11"},"gender":{"type":"string","description":"Whether the school admits boys, girls or both, in the source register's own wording.","example":"Mixed"},"religiousCharacter":{"type":"string","description":"Religious character the source register records for the school.","example":"Church of England"},"admissionsPolicy":{"type":"string","description":"Admissions policy the source register records for the school.","example":"Comprehensive"},"capacity":{"type":"integer","description":"Number of pupil places the source register records for the school.","example":420},"numberOfPupils":{"type":"integer","description":"Number of pupils the source register records for the school.","example":385},"specialClasses":{"type":"string"},"specialistResource":{"type":"string"},"trustName":{"type":"string","description":"Name of the trust the school belongs to, where the source register records one.","example":"London Academy Trust"},"trustId":{"type":"string","description":"Identifier of that trust in the source register.","example":"TR00123"},"laCode":{"type":"string","description":"Code of the local authority the school falls under.","example":"213"},"laName":{"type":"string","description":"Name of the local authority the school falls under.","example":"Westminster"},"establishmentNumber":{"type":"integer","description":"Establishment number the source register assigns the school.","example":3614},"headteacher":{"type":"string","description":"Name of the headteacher, where the source register records one.","example":"Mrs J Smith"},"telephone":{"type":"string","description":"Contact telephone number for the school.","example":"020 1234 5678"},"website":{"type":"string","description":"URL of the school's own website.","example":"https://www.example.sch.uk"},"distance":{"type":"number","description":"Distance from the search point, in metres. Present only on results from a `near` search.","example":1234.56},"catchment":{"$ref":"#/components/schemas/SchoolCatchmentBlock"},"inspections":{"type":["object","null"],"properties":{"current":{"$ref":"#/components/schemas/SchoolInspectionEvent"},"history":{"type":"array","items":{"$ref":"#/components/schemas/SchoolInspectionEvent"},"default":[],"description":"Every recorded inspection, newest first. The first entry is the same event as `current`."}},"required":["current"],"description":"The current inspection and the full history behind it. Present only when requested via `attributes=inspections`."},"identifiers":{"type":["object","null"],"properties":{"ukprn":{"type":["string","null"],"description":"The school's UK Provider Reference Number (UKPRN).","example":"10012345"},"estynId":{"type":["string","null"],"description":"The school's provider identifier with Estyn, the Welsh inspectorate."},"ofstedProviderId":{"type":["string","null"],"description":"The school's provider identifier with Ofsted, the English inspectorate."},"oldUrns":{"type":"array","items":{"type":"string"},"default":[],"description":"Unique Reference Numbers (URNs) this school was known by before. Empty when there are none."}},"description":"The identifiers this school carries in registers other than `provider`. Present only when requested via `attributes=identifiers`."},"trust":{"type":["object","null"],"properties":{"memberships":{"type":"array","items":{"$ref":"#/components/schemas/SchoolTrustMembership"},"default":[],"description":"The organisations the school currently belongs to, governance-leadership roles first."}},"description":"The trusts, federations and other organisations the school currently belongs to. Present only when requested via `attributes=trust`."},"images":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"$ref":"#/components/schemas/SchoolImage"},"default":[],"description":"Photographs of the school's buildings and facilities, newest first. Only images cleared for publication appear here, so the list can be empty."}},"description":"Photographs of the school's buildings and facilities, taken from its own website. Requested via `attributes=images`, and null until at least one photograph is cleared for publication."},"branding":{"type":["object","null"],"properties":{"logoUrl":{"type":"string","description":"Public URL of the logo or crest.","example":"https://hot-cdn.vepler.com/schools/12345/images/ab12cd.png"},"primaryColour":{"type":"string","description":"Primary brand colour, as a hex code.","example":"#00a1d5"},"secondaryColour":{"type":"string","description":"Secondary brand colour, as a hex code.","example":"#1c1c1c"},"socialMedia":{"$ref":"#/components/schemas/SocialMediaLinks"}},"description":"The school's logo or crest and its social profiles, taken from its own website. Requested via `attributes=branding`, and null until at least one of them is cleared for publication."},"accreditations":{"type":["object","null"],"properties":{"accreditations":{"type":"array","items":{"$ref":"#/components/schemas/SchoolAccreditation"},"default":[],"description":"Award, kitemark and partner badges shown on the school's own website, newest first. Only badges cleared for publication appear here, so the list can be empty."}},"description":"Awards, kitemarks and partner badges the school displays on its own website. Requested via `attributes=accreditations`, and null until they are cleared for publication."},"videos":{"type":["object","null"],"properties":{"videos":{"type":"array","items":{"$ref":"#/components/schemas/SchoolVideo"},"default":[],"description":"Videos published on the school's own website. Only videos cleared for publication appear here, so the list can be empty."}},"description":"References to videos the school publishes, as metadata rather than the video itself. Requested via `attributes=videos`, and null until they are cleared for publication."},"about":{"type":["object","null"],"properties":{"ethos":{"type":["string","null"],"description":"The school's stated ethos and values."},"headteacherWelcome":{"type":["string","null"],"description":"The headteacher's published welcome message."},"sendStatement":{"type":["string","null"],"description":"The school's statement on special educational needs and disabilities (SEND), and on inclusion."},"clubsDescription":{"type":["string","null"],"description":"What the school publishes about its extra-curricular clubs."},"facilitiesDescription":{"type":["string","null"],"description":"What the school publishes about its facilities."},"aboutDescription":{"type":["string","null"],"description":"The school's general description of itself."},"historyDescription":{"type":["string","null"],"description":"The school's account of its own history."},"curriculumDescription":{"type":["string","null"],"description":"What the school publishes about its curriculum."},"resultsSummary":{"type":["string","null"],"description":"The school's own summary of its results, in the wording it published."},"uniformSupplier":{"type":["string","null"],"description":"Name of the uniform supplier, where the school names one."},"prospectusUrl":{"type":["string","null"],"description":"Address of the school's prospectus."},"breakfastClub":{"type":["boolean","null"],"description":"True when the school states that it runs a breakfast club."},"afterSchoolCare":{"type":["boolean","null"],"description":"True when the school states that it offers after-school or wraparound care."},"termDates":{"type":"array","items":{"$ref":"#/components/schemas/SchoolTermDate"},"default":[],"description":"Term and holiday dates as the school publishes them."}},"description":"What the school says about itself: ethos, headteacher's welcome, term dates and similar narrative. Requested via `attributes=about`, and null until the profile has been reviewed."},"createdAt":{"type":"string","description":"When this school first appeared in the API, as an ISO 8601 timestamp.","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","description":"When this record was last changed, as an ISO 8601 timestamp.","example":"2024-01-01T00:00:00.000Z"},"lastUpdated":{"type":"string","description":"When the source register data behind this record was last refreshed, as an ISO 8601 timestamp.","example":"2024-01-01T00:00:00.000Z"}},"required":["object","id","region","provider","key","name","type","status","createdAt","updatedAt","lastUpdated"],"description":"A single school: who it is (country, region, provider and key), where it is, what it teaches, and how it was last inspected. Use `provider` with `key` to match the school against a national register, and `id` to refer to it in later calls to this API."},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250},"meta":{"type":"object","properties":{"catchment":{"$ref":"#/components/schemas/CatchmentMeta"}}}},"required":["object","url","has_more","data"],"description":"One page of school records, carrying a `meta.catchment` block when the request supplied `catchmentReference`."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/schools/source/query":{"post":{"operationId":"querySchoolsBySource","x-speakeasy-name-override":"querySchoolsBySource","tags":["Schools"],"summary":"Batch fetch schools by provider keys","description":"Looks up several schools in one national register in a single call, by the keys that register uses. At most 500 keys per request. Keys that match no school are left out of the response rather than reported as errors, so compare the results against what was sent.","requestBody":{"description":"The register to look in and the keys to look up, at most 500 of them.","content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["dfe","welshgov","seed","deni","dept_edu_ie"],"description":"Which national register issued the school's `key`. 'dfe' is the Department for Education register for England, which also carries cross-border Welsh URNs. 'welshgov' is the Welsh Government school number. 'seed' is the Scottish SEED code. 'deni' is the Northern Ireland Department of Education reference. 'dept_edu_ie' is the Irish roll number.","example":"dfe"},"keys":{"type":"array","items":{"type":"string"},"minItems":1,"maxItems":500,"description":"The identifiers to look up in that register, such as URNs or SEED codes. At least 1 and at most 500 per request.","example":["100000","100001"]},"attributes":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"description":"The fields and blocks to return for each school, as a comma-separated string or an array. Omit it to get the whole school record with no aggregate blocks. Naming a block (`inspections`, `identifiers`, `trust`, `images`, `branding`, `accreditations`, `videos`, `about`) adds that block to the whole record; naming at least one ordinary field instead trims each school to the fields listed plus any blocks. `object` and `id` are always returned and names that are not recognised are ignored."}},"required":["provider","keys"],"description":"A batch lookup by source-register key. Keys that match no school are left out of the response rather than reported as errors."}}}},"responses":{"200":{"description":"The schools that matched the supplied keys.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["school"],"description":"Object type discriminator. Always `school`.","example":"school"},"id":{"type":"integer","description":"Identifier for the school within this API. Stable across updates.","example":12345},"country":{"type":"string","minLength":2,"maxLength":2,"default":"GB","description":"Country the school is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"region":{"type":"string","description":"Education system the school belongs to, as an ISO 3166-2 region code. `GB-ENG` is England, `GB-WLS` Wales, `GB-SCT` Scotland and `GB-NIR` Northern Ireland.","example":"GB-ENG"},"provider":{"type":"string","enum":["dfe","welshgov","seed","deni","dept_edu_ie"],"description":"Which national register issued the school's `key`. 'dfe' is the Department for Education register for England, which also carries cross-border Welsh URNs. 'welshgov' is the Welsh Government school number. 'seed' is the Scottish SEED code. 'deni' is the Northern Ireland Department of Education reference. 'dept_edu_ie' is the Irish roll number.","example":"dfe"},"key":{"type":"string","description":"The identifier the source register uses for this school, such as a URN under `dfe` or a SEED code under `seed`. Together with `provider` it identifies the school across jurisdictions.","example":"100000"},"name":{"type":"string","description":"Name of the school as its source register publishes it.","example":"St Mary's Primary School"},"slug":{"type":["string","null"],"description":"URL-friendly form of the school name, safe to use in a path. Null when none has been generated.","example":"st-marys-primary-school-westminster"},"type":{"type":"string","enum":["nursery","primary","secondary","all-through","sixth-form","special","independent","academy","other"],"description":"The kind of institution the school is. 'nursery' is early years, 'primary' covers key stages 1 and 2, 'secondary' covers key stages 3 and 4, 'all-through' combines primary and secondary, and 'sixth-form' is post-16 only. 'special' is special educational needs provision, 'independent' is fee-paying, 'academy' is state-funded but independently run, and 'other' covers alternative provision, pupil referral units and anything the register leaves unclassified.","example":"primary"},"subType":{"type":"string","description":"Finer-grained establishment type as the source register classifies it, for example 'Voluntary Aided School' or 'Academy Converter'.","example":"Voluntary Aided School"},"status":{"type":"string","enum":["open","closed","pending_closure"],"description":"Operating status of the school, as recorded by its source register. 'open' means it is operating, 'closed' means it has closed, and 'pending_closure' means the register has flagged it for closure. Filter on 'open' to exclude the other two.","example":"open"},"currentRating":{"type":["string","null"],"enum":["outstanding","good","satisfactory","inadequate","exceptional","strong_standard","expected_standard","needs_attention","urgent_improvement","requires_improvement","not_yet_inspected","excellent","adequate","unsatisfactory","very_good","weak","important_area_for_improvement","requires_significant_improvement","fair",null],"description":"The most recent inspection grade, in the words of the inspectorate that issued it: Ofsted in England, Estyn in Wales, Education Scotland, ETI in Northern Ireland and the DES Inspectorate in Ireland. The scales differ between inspectorates, so a grade is only comparable within one of them.","example":"good"},"lastInspectionDate":{"type":"string","description":"When the most recent inspection took place, as an ISO 8601 date.","example":"2024-01-15"},"location":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the school, in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the school, in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"description":"Point location of the school."},"address":{"type":"object","properties":{"street":{"type":"string","description":"Building number and street.","example":"123 High Street"},"locality":{"type":"string","description":"District or locality the school sits in.","example":"Westminster"},"town":{"type":"string","description":"Town or city.","example":"London"},"county":{"type":"string","description":"County or equivalent wider area.","example":"Greater London"},"postcode":{"type":"string","description":"Postcode in the format used by the school's own country, such as a UK postcode or an Eircode.","example":"SW1A 1AA"}},"description":"Postal address of the school."},"lsoaCode":{"type":["string","null"],"description":"Lower Layer Super Output Area (LSOA) code covering the school, for joining to area-level datasets. Null when no LSOA has been mapped to the school.","example":"E01004736"},"phase":{"type":"string","description":"Phase of education the source register assigns the school, in the register's own wording.","example":"Primary"},"ageRange":{"type":"string","description":"Age range the school covers, as the youngest and oldest age separated by a hyphen.","example":"4-11"},"gender":{"type":"string","description":"Whether the school admits boys, girls or both, in the source register's own wording.","example":"Mixed"},"religiousCharacter":{"type":"string","description":"Religious character the source register records for the school.","example":"Church of England"},"admissionsPolicy":{"type":"string","description":"Admissions policy the source register records for the school.","example":"Comprehensive"},"capacity":{"type":"integer","description":"Number of pupil places the source register records for the school.","example":420},"numberOfPupils":{"type":"integer","description":"Number of pupils the source register records for the school.","example":385},"specialClasses":{"type":"string"},"specialistResource":{"type":"string"},"trustName":{"type":"string","description":"Name of the trust the school belongs to, where the source register records one.","example":"London Academy Trust"},"trustId":{"type":"string","description":"Identifier of that trust in the source register.","example":"TR00123"},"laCode":{"type":"string","description":"Code of the local authority the school falls under.","example":"213"},"laName":{"type":"string","description":"Name of the local authority the school falls under.","example":"Westminster"},"establishmentNumber":{"type":"integer","description":"Establishment number the source register assigns the school.","example":3614},"headteacher":{"type":"string","description":"Name of the headteacher, where the source register records one.","example":"Mrs J Smith"},"telephone":{"type":"string","description":"Contact telephone number for the school.","example":"020 1234 5678"},"website":{"type":"string","description":"URL of the school's own website.","example":"https://www.example.sch.uk"},"distance":{"type":"number","description":"Distance from the search point, in metres. Present only on results from a `near` search.","example":1234.56},"catchment":{"$ref":"#/components/schemas/SchoolCatchmentBlock"},"inspections":{"type":["object","null"],"properties":{"current":{"$ref":"#/components/schemas/SchoolInspectionEvent"},"history":{"type":"array","items":{"$ref":"#/components/schemas/SchoolInspectionEvent"},"default":[],"description":"Every recorded inspection, newest first. The first entry is the same event as `current`."}},"required":["current"],"description":"The current inspection and the full history behind it. Present only when requested via `attributes=inspections`."},"identifiers":{"type":["object","null"],"properties":{"ukprn":{"type":["string","null"],"description":"The school's UK Provider Reference Number (UKPRN).","example":"10012345"},"estynId":{"type":["string","null"],"description":"The school's provider identifier with Estyn, the Welsh inspectorate."},"ofstedProviderId":{"type":["string","null"],"description":"The school's provider identifier with Ofsted, the English inspectorate."},"oldUrns":{"type":"array","items":{"type":"string"},"default":[],"description":"Unique Reference Numbers (URNs) this school was known by before. Empty when there are none."}},"description":"The identifiers this school carries in registers other than `provider`. Present only when requested via `attributes=identifiers`."},"trust":{"type":["object","null"],"properties":{"memberships":{"type":"array","items":{"$ref":"#/components/schemas/SchoolTrustMembership"},"default":[],"description":"The organisations the school currently belongs to, governance-leadership roles first."}},"description":"The trusts, federations and other organisations the school currently belongs to. Present only when requested via `attributes=trust`."},"images":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"$ref":"#/components/schemas/SchoolImage"},"default":[],"description":"Photographs of the school's buildings and facilities, newest first. Only images cleared for publication appear here, so the list can be empty."}},"description":"Photographs of the school's buildings and facilities, taken from its own website. Requested via `attributes=images`, and null until at least one photograph is cleared for publication."},"branding":{"type":["object","null"],"properties":{"logoUrl":{"type":"string","description":"Public URL of the logo or crest.","example":"https://hot-cdn.vepler.com/schools/12345/images/ab12cd.png"},"primaryColour":{"type":"string","description":"Primary brand colour, as a hex code.","example":"#00a1d5"},"secondaryColour":{"type":"string","description":"Secondary brand colour, as a hex code.","example":"#1c1c1c"},"socialMedia":{"$ref":"#/components/schemas/SocialMediaLinks"}},"description":"The school's logo or crest and its social profiles, taken from its own website. Requested via `attributes=branding`, and null until at least one of them is cleared for publication."},"accreditations":{"type":["object","null"],"properties":{"accreditations":{"type":"array","items":{"$ref":"#/components/schemas/SchoolAccreditation"},"default":[],"description":"Award, kitemark and partner badges shown on the school's own website, newest first. Only badges cleared for publication appear here, so the list can be empty."}},"description":"Awards, kitemarks and partner badges the school displays on its own website. Requested via `attributes=accreditations`, and null until they are cleared for publication."},"videos":{"type":["object","null"],"properties":{"videos":{"type":"array","items":{"$ref":"#/components/schemas/SchoolVideo"},"default":[],"description":"Videos published on the school's own website. Only videos cleared for publication appear here, so the list can be empty."}},"description":"References to videos the school publishes, as metadata rather than the video itself. Requested via `attributes=videos`, and null until they are cleared for publication."},"about":{"type":["object","null"],"properties":{"ethos":{"type":["string","null"],"description":"The school's stated ethos and values."},"headteacherWelcome":{"type":["string","null"],"description":"The headteacher's published welcome message."},"sendStatement":{"type":["string","null"],"description":"The school's statement on special educational needs and disabilities (SEND), and on inclusion."},"clubsDescription":{"type":["string","null"],"description":"What the school publishes about its extra-curricular clubs."},"facilitiesDescription":{"type":["string","null"],"description":"What the school publishes about its facilities."},"aboutDescription":{"type":["string","null"],"description":"The school's general description of itself."},"historyDescription":{"type":["string","null"],"description":"The school's account of its own history."},"curriculumDescription":{"type":["string","null"],"description":"What the school publishes about its curriculum."},"resultsSummary":{"type":["string","null"],"description":"The school's own summary of its results, in the wording it published."},"uniformSupplier":{"type":["string","null"],"description":"Name of the uniform supplier, where the school names one."},"prospectusUrl":{"type":["string","null"],"description":"Address of the school's prospectus."},"breakfastClub":{"type":["boolean","null"],"description":"True when the school states that it runs a breakfast club."},"afterSchoolCare":{"type":["boolean","null"],"description":"True when the school states that it offers after-school or wraparound care."},"termDates":{"type":"array","items":{"$ref":"#/components/schemas/SchoolTermDate"},"default":[],"description":"Term and holiday dates as the school publishes them."}},"description":"What the school says about itself: ethos, headteacher's welcome, term dates and similar narrative. Requested via `attributes=about`, and null until the profile has been reviewed."},"createdAt":{"type":"string","description":"When this school first appeared in the API, as an ISO 8601 timestamp.","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","description":"When this record was last changed, as an ISO 8601 timestamp.","example":"2024-01-01T00:00:00.000Z"},"lastUpdated":{"type":"string","description":"When the source register data behind this record was last refreshed, as an ISO 8601 timestamp.","example":"2024-01-01T00:00:00.000Z"}},"required":["object","id","region","provider","key","name","type","status","createdAt","updatedAt","lastUpdated"],"description":"A single school: who it is (country, region, provider and key), where it is, what it teaches, and how it was last inspected. Use `provider` with `key` to match the school against a national register, and `id` to refer to it in later calls to this API."},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of school records, with the metadata needed to fetch the rest."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/schools/health":{"get":{"operationId":"checkSchoolsHealth","x-speakeasy-name-override":"checkSchoolsHealth","tags":["System"],"summary":"Schools service health check","description":"Reports whether the schools endpoints are answering. Returns no school data.","responses":{"200":{"description":"The schools endpoints are answering.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","description":"Always `ok` when the service answers."},"service":{"type":"string","description":"Which service answered. Always `schools`."},"timestamp":{"type":"string","description":"When the check ran, as an ISO 8601 timestamp."}},"required":["status","service","timestamp"]}}}}}}},"/v1/schools/metrics":{"get":{"operationId":"getSchoolMetrics","x-speakeasy-name-override":"getMetrics","tags":["Schools"],"summary":"Get school metrics","description":"Returns published figures for one or more schools: results, attendance, finance, pupil characteristics and destinations. Name the figures either with `metricCodes` or with a `profile`, never both. By default the response covers a single academic year; set `timeseries=true` with `startYear` and `endYear` for a value per year instead. `includeDefinitions` returns what each code means and `includeComparisons` returns national, regional and similar-school averages beside it.","parameters":[{"schema":{"type":"string","description":"Comma-separated school identifiers, as returned in the `id` field of a school record."},"required":true,"description":"Comma-separated school identifiers, as returned in the `id` field of a school record.","name":"schoolIds","in":"query"},{"schema":{"type":"string","description":"Comma-separated metric codes to return. Supply either this or `profile`, never both."},"required":false,"description":"Comma-separated metric codes to return. Supply either this or `profile`, never both.","name":"metricCodes","in":"query"},{"schema":{"type":"string","description":"Comma-separated metric profiles to expand into codes. Supply either this or `metricCodes`, never both. `/v1/schools/metrics/profiles` lists the profiles and what each one covers."},"required":false,"description":"Comma-separated metric profiles to expand into codes. Supply either this or `metricCodes`, never both. `/v1/schools/metrics/profiles` lists the profiles and what each one covers.","name":"profile","in":"query"},{"schema":{"type":"string","description":"Academic year to read, in YYYY/YY form such as 2023/24. Defaults to the current academic year."},"required":false,"description":"Academic year to read, in YYYY/YY form such as 2023/24. Defaults to the current academic year.","name":"academicYear","in":"query"},{"schema":{"type":"string","enum":["ks2","ks4","ks5","pupil","finance","ofsted"],"description":"Family of measures the requested codes belong to.","example":"ks4"},"required":false,"description":"Family of measures the requested codes belong to.","name":"category","in":"query"},{"schema":{"type":"string","enum":["all","disadvantaged","boys","girls","eal","senSupport","ehcp","english","unclassified"],"description":"Group of pupils the requested values relate to.","example":"all"},"required":false,"description":"Group of pupils the requested values relate to.","name":"cohortType","in":"query"},{"schema":{"type":"string","enum":["annual","termly","monthly"],"description":"How often the requested figures are reported.","example":"annual"},"required":false,"description":"How often the requested figures are reported.","name":"period","in":"query"},{"schema":{"type":"string","description":"Set to `true` to return one value per academic year rather than a single year. `startYear` and `endYear` are both required when it is set."},"required":false,"description":"Set to `true` to return one value per academic year rather than a single year. `startYear` and `endYear` are both required when it is set.","name":"timeseries","in":"query"},{"schema":{"type":"string","description":"First academic year of the series, in YYYY/YY form. Required when `timeseries` is `true`."},"required":false,"description":"First academic year of the series, in YYYY/YY form. Required when `timeseries` is `true`.","name":"startYear","in":"query"},{"schema":{"type":"string","description":"Last academic year of the series, in YYYY/YY form. Required when `timeseries` is `true`."},"required":false,"description":"Last academic year of the series, in YYYY/YY form. Required when `timeseries` is `true`.","name":"endYear","in":"query"},{"schema":{"type":"string","description":"Set to `true` to return the definition of each metric code alongside the values."},"required":false,"description":"Set to `true` to return the definition of each metric code alongside the values.","name":"includeDefinitions","in":"query"},{"schema":{"type":"string","description":"Set to `true` to return national, regional and similar-school averages alongside each value."},"required":false,"description":"Set to `true` to return national, regional and similar-school averages alongside each value.","name":"includeComparisons","in":"query"},{"schema":{"type":"string","description":"Maximum number of metric values to read. Defaults to 100. Minimum 1, maximum 500."},"required":false,"description":"Maximum number of metric values to read. Defaults to 100. Minimum 1, maximum 500.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Number of metric values to skip before the first one read. Defaults to 0."},"required":false,"description":"Number of metric values to skip before the first one read. Defaults to 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"The requested figures, grouped by school.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string"},"data":{"anyOf":[{"type":"array","items":{"type":"object","properties":{"schoolId":{"type":"number"},"metrics":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"value":{"anyOf":[{"type":"number"},{"type":"string"}]},"academicYear":{"type":"string"},"cohortType":{"type":"string"},"confidence":{"type":"object","properties":{"lower":{"type":"number"},"upper":{"type":"number"}},"description":"Confidence interval published with a value, where the publisher gives one."},"metadata":{"type":"object","additionalProperties":{}}},"required":["code","value"],"description":"One metric value for one school, in one academic year and for one group of pupils."}},"comparisons":{"type":"object","additionalProperties":{"type":"object","properties":{"national":{"type":"number"},"regional":{"type":"number"},"similarSchools":{"type":"number"},"localAuthority":{"type":"number"}},"description":"Benchmark averages for the same metric, to read a school's value against. Returned when `includeComparisons` is set."}},"definitions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"category":{"type":"string"},"subcategory":{"type":"string"},"description":{"type":"string"},"dataType":{"type":"string","enum":["percentage","score","count","currency","text"]},"units":{"type":"string"},"isHigherBetter":{"type":"boolean"},"nationalAverage":{"type":"number"}},"required":["code","category","subcategory","description","dataType"],"description":"What a metric code means and how to read its values. Returned when `includeDefinitions` is set."}}},"required":["schoolId","metrics"],"description":"One school's metric values for a single academic year."}},{"type":"array","items":{"type":"object","properties":{"schoolId":{"type":"number"},"metricCodes":{"type":"array","items":{"type":"string"}},"series":{"type":"array","items":{"type":"object","properties":{"year":{"type":"string"},"values":{"type":"object","additionalProperties":{"anyOf":[{"type":"number"},{"type":"string"}]}}},"required":["year","values"],"description":"One academic year of a series, carrying each requested metric the school has a point for that year."}},"definitions":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"category":{"type":"string"},"subcategory":{"type":"string"},"description":{"type":"string"},"dataType":{"type":"string","enum":["percentage","score","count","currency","text"]},"units":{"type":"string"},"isHigherBetter":{"type":"boolean"},"nationalAverage":{"type":"number"}},"required":["code","category","subcategory","description","dataType"],"description":"What a metric code means and how to read its values. Returned when `includeDefinitions` is set."}}},"required":["schoolId","metricCodes","series"],"description":"One school's metric values across a run of academic years, oldest year first."}}]},"has_more":{"type":"boolean"},"total_count":{"type":"number"}},"required":["object","url","data","has_more"],"description":"One page of metric results, carrying one entry for each school the request named, whether or not any of the requested figures were published for it."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/schools/metrics/profiles":{"get":{"operationId":"getMetricProfiles","x-speakeasy-name-override":"listProfiles","tags":["Schools"],"summary":"List metric profiles","description":"Lists the metric profiles accepted by the `profile` parameter on `/v1/schools/metrics`, with what each one covers and how many metric codes it expands to. Read this first to avoid naming codes by hand.","responses":{"200":{"description":"Every metric profile this API accepts.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"data":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name to pass as the `profile` parameter on `/v1/schools/metrics`."},"description":{"type":"string","description":"Human-readable explanation of what the profile covers."},"metricCount":{"type":"integer","description":"Number of metric codes the profile expands to."}},"required":["name","description","metricCount"],"description":"A named bundle of metric codes, so a caller can ask for a subject rather than list codes."},"description":"Every metric profile this API accepts."}},"required":["object","data"],"description":"The metric profiles available to `/v1/schools/metrics`."}}}}}}},"/v1/schools/metrics/compare":{"post":{"operationId":"compareSchoolMetrics","x-speakeasy-name-override":"compareMetrics","tags":["Schools"],"summary":"Compare metrics across schools","description":"Returns the same metric codes for 2 to 50 schools side by side, keyed by school and then by code, so a table can be built from one call. Reads the most recent academic year on record unless `academicYear` says otherwise, and covers all pupils rather than a narrower group. Schools and codes with nothing published are left out of the response.","requestBody":{"description":"The schools and metric codes to compare.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetricsCompareRequest"}}}},"responses":{"200":{"description":"The requested metrics for the requested schools, side by side.","content":{"application/json":{"schema":{"type":"object","properties":{"schools":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","description":"Identifier for the school within this API."},"name":{"type":"string","description":"Name of the school as its source register publishes it."},"provider":{"type":"string","description":"Which national register issued `providerId`."},"providerId":{"type":"string","description":"The identifier that register uses for the school, such as a URN under `dfe`."}},"required":["id","name","provider","providerId"],"description":"One school in the comparison, named so a row can be labelled without a second call."},"description":"The schools that had at least one of the requested values. Schools with none are left out."},"metrics":{"type":"array","items":{"type":"string"},"description":"The metric codes that had at least one value. Codes with none are left out."},"academicYearId":{"type":"string","description":"Academic year the values were read from, as a canonical year identifier such as `GB_2023-2024`. Empty when no academic year could be resolved."},"cohortType":{"type":"string","description":"Group of pupils the values cover. `all` is the whole cohort."},"data":{"type":"object","additionalProperties":{"type":"object","additionalProperties":{"type":"object","properties":{"value":{"type":["string","null"],"description":"The value itself, as a string. Cast it with the metric's data type. Null when the source recorded the metric without a value."},"confidence":{"type":["object","null"],"properties":{"lower":{"type":"number","description":"Lower bound of the interval."},"upper":{"type":"number","description":"Upper bound of the interval."}},"description":"Confidence interval published with this value, where the publisher gives one."}},"required":["value"],"description":"One school's value for one metric."}},"description":"The comparison itself, keyed by school identifier and then by metric code. A school and metric pair with nothing published has no entry at all."}},"required":["schools","metrics","academicYearId","cohortType","data"],"description":"A side-by-side comparison of the requested metrics across the requested schools."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/schools/metrics/geographic":{"get":{"operationId":"getGeographicMetricAggregation","x-speakeasy-name-override":"getGeographicAggregation","tags":["Schools"],"summary":"Aggregate a metric across geography","description":"Summarises one metric across areas rather than schools, giving the mean, minimum, maximum and standard deviation for each area along with how many schools contributed. Group by local authority, by region, or into a single national row. `schoolTypes` narrows which schools count towards the totals. Rows come back most-contributing first, and at most 1000 of them.","parameters":[{"schema":{"type":"string","minLength":1,"description":"The metric code to aggregate. One code per request.","example":"KS2_READING_PROGRESS"},"required":true,"description":"The metric code to aggregate. One code per request.","name":"metricCode","in":"query"},{"schema":{"type":"string","enum":["local_authority","regional","national"],"description":"How widely to group the schools: one row per local authority, one per region, or a single national row.","example":"local_authority"},"required":true,"description":"How widely to group the schools: one row per local authority, one per region, or a single national row.","name":"aggregationLevel","in":"query"},{"schema":{"type":"string","pattern":"^\\d{4}\\/\\d{2}$","description":"Academic year to aggregate, in YYYY/YY form such as 2023/24. Defaults to the current academic year.","example":"2023/24"},"required":false,"description":"Academic year to aggregate, in YYYY/YY form such as 2023/24. Defaults to the current academic year.","name":"academicYear","in":"query"},{"schema":{"type":"string","description":"Comma-separated school types to limit the aggregation to. A type outside the supported set is rejected rather than ignored.","example":"primary,secondary"},"required":false,"description":"Comma-separated school types to limit the aggregation to. A type outside the supported set is rejected rather than ignored.","name":"schoolTypes","in":"query"}],"responses":{"200":{"description":"The metric summarised for each area.","content":{"application/json":{"schema":{"type":"object","properties":{"metricCode":{"type":"string","description":"The metric code that was aggregated."},"metricName":{"type":"string","description":"Human-readable name of that metric, as the metric catalogue records it."},"academicYearId":{"type":"string","description":"Academic year the values were read from, as a canonical year identifier such as `GB_2023-2024`. Empty when no academic year could be resolved."},"aggregateBy":{"type":"string","enum":["authority","region","national"],"description":"How the rows were grouped: by local authority, by region, or into a single national row."},"cohortType":{"type":"string","description":"Group of pupils the values cover. `all` is the whole cohort."},"data":{"type":"array","items":{"type":"object","properties":{"area":{"type":["string","null"],"description":"The area this row covers: the local authority name, the region identifier, or `England` for the national row. Null when the contributing schools carry no area of that kind."},"schoolCount":{"type":"integer","description":"Number of distinct schools that contributed a value to this row."},"avgValue":{"type":["number","null"],"description":"Mean of those schools' values."},"minValue":{"type":["number","null"],"description":"Lowest of those schools' values."},"maxValue":{"type":["number","null"],"description":"Highest of those schools' values."},"stdDev":{"type":["number","null"],"description":"Standard deviation of those schools' values."}},"required":["area","schoolCount","avgValue","minValue","maxValue","stdDev"],"description":"One area, with the metric summarised across the schools in it."},"description":"One row per area, most-contributing first. At most 1000 rows are returned."}},"required":["metricCode","metricName","academicYearId","aggregateBy","cohortType","data"],"description":"A metric summarised across geography, one row per area."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/schools/catchment/coverage":{"get":{"operationId":"getCatchmentCoverage","x-speakeasy-name-override":"getCoverage","tags":["Schools Catchment"],"summary":"Nationwide catchment ingest coverage","description":"Reports how much catchment data is loaded across a country, by counting local authorities at each stage of ingest. The counts are broken down by the four kinds of evidence behind a catchment match: published catchment areas, admission outcomes, feeder links and faith jurisdictions. Read it to see where a catchment answer will be firm and where it will fall back to distance.","parameters":[{"schema":{"type":"string","minLength":2,"maxLength":2,"default":"GB","description":"Country to report on, as an ISO 3166-1 alpha-2 code. Defaults to `GB`.","example":"GB"},"required":false,"description":"Country to report on, as an ISO 3166-1 alpha-2 code. Defaults to `GB`.","name":"country","in":"query"}],"responses":{"200":{"description":"Ingest counts for the requested country.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatchmentCoverageResponse"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/schools/catchment/by-school/{id}":{"get":{"operationId":"getCatchmentBySchool","x-speakeasy-name-override":"getBySchool","tags":["Schools Catchment"],"summary":"Per-school catchment geometry","description":"Returns the catchment areas published for one school as a GeoJSON FeatureCollection, ready to draw on a map, with one feature per boundary in force. Pass `asOfDate` to see the boundaries as they stood on an earlier date, and `catchmentType` to keep only certain kinds, such as designated or priority areas.","parameters":[{"schema":{"type":"string","description":"Identifier of the school, as returned in the `id` field of a school record.","example":"47697"},"required":true,"description":"Identifier of the school, as returned in the `id` field of a school record.","name":"id","in":"path"},{"schema":{"type":"string","description":"Return the catchments in force on this date, as an ISO 8601 date. Defaults to today, so pass an earlier date to see a previous year's boundaries.","example":"2026-09-01"},"required":false,"description":"Return the catchments in force on this date, as an ISO 8601 date. Defaults to today, so pass an earlier date to see a previous year's boundaries.","name":"asOfDate","in":"query"},{"schema":{"type":"string","description":"Return only these kinds of catchment, comma-separated. One or more of: designated, priority, shared, feeder_area, lottery_zone, other.","example":"designated,priority"},"required":false,"description":"Return only these kinds of catchment, comma-separated. One or more of: designated, priority, shared, feeder_area, lottery_zone, other.","name":"catchmentType","in":"query"}],"responses":{"200":{"description":"The school's catchment boundaries. Empty when none has been loaded for it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CatchmentFeatureCollection"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/schools/catchment/admission-area/{id}":{"get":{"operationId":"getSchoolAdmissionArea","x-speakeasy-name-override":"getAdmissionArea","tags":["Schools Catchment"],"summary":"Per-school unified admission area","description":"Returns a school's admission area in whichever form the published data supports, as one GeoJSON FeatureCollection, so a map can be drawn from a single call. A `polygon` feature is a catchment area the authority publishes. A `distance_radius` feature is a circle around the school, sized by the distance to the furthest pupil it admitted, and carries that year's admission criteria and offer counts. Pass `academicYear` to pin the year the circle is drawn from and `asOfDate` to see earlier polygons.","parameters":[{"schema":{"type":"string","description":"Identifier of the school, as returned in the `id` field of a school record.","example":"47697"},"required":true,"description":"Identifier of the school, as returned in the `id` field of a school record.","name":"id","in":"path"},{"schema":{"type":"string","description":"Academic year to draw the distance radius from. Defaults to the most recent year for which the school published an admission distance.","example":"GB_2025-2026"},"required":false,"description":"Academic year to draw the distance radius from. Defaults to the most recent year for which the school published an admission distance.","name":"academicYear","in":"query"},{"schema":{"type":"string","description":"Return the catchment polygons in force on this date, as an ISO 8601 date. Defaults to today.","example":"2026-09-01"},"required":false,"description":"Return the catchment polygons in force on this date, as an ISO 8601 date. Defaults to today.","name":"asOfDate","in":"query"}],"responses":{"200":{"description":"The school's admission area. `features` is empty when no boundary has been loaded for it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdmissionAreaResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/schools/frameworks":{"get":{"operationId":"listFrameworks","x-speakeasy-group":"Schools.Frameworks","x-speakeasy-name-override":"list","tags":["Schools Reference"],"summary":"List all framework catalogue entries","description":"Lists every framework the Schools API publishes figures under, covering performance, destinations, census, finance, admissions and inspections. Each entry names the country, the authority that publishes it and the metric codes it carries, so metric codes seen in a school response can be interpreted without asking for definitions on every call. An entry with an empty `metricCodes` list is registered but not yet loaded. Responses are cacheable for 24 hours, and any change is mirrored to `/v1/schools/changelog`.","responses":{"200":{"description":"Every framework in the catalogue.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FrameworkListResponse"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/schools/frameworks/{framework}":{"get":{"operationId":"getFramework","x-speakeasy-group":"Schools.Frameworks","x-speakeasy-name-override":"get","tags":["Schools Reference"],"summary":"Get framework with full metric definitions","description":"Returns one framework together with the full definition of every metric code published under it: what the metric means in a sentence, its unit, its expected range and typical national average, which pupil cohorts it is broken down by, and the authority's rule for suppressing small cohorts. Fetch this once rather than guessing what a code such as `ATT8` stands for. Responses are cacheable for 24 hours.","parameters":[{"schema":{"allOf":[{"$ref":"#/components/schemas/SchoolFrameworkCode"},{"description":"Identifies a country × publishing authority × domain combination. Use to look up metric definitions via `/v1/schools/frameworks/{framework}`. Naming convention: `{country}_{authority}_{domain}`.\n\nSupported values:\n\n- `gb_eng_dfes_ks2` — England DfE Key Stage 2 performance — end-of-primary outcomes at age 11. Metrics include `PTRWM_EXP` (% at expected standard in reading/writing/maths combined) and progress scores `PROG_READ`/`PROG_WRIT`/`PROG_MAT`. Annual cadence.\n- `gb_eng_dfes_ks4` — England DfE Key Stage 4 performance — GCSE-stage outcomes at age 16. Metrics include `ATT8` (Attainment 8), `EBACCAPS` (EBacc Average Point Score), `P8MEA` (Progress 8). Annual cadence.\n- `gb_eng_dfes_ks5` — England DfE Key Stage 5 performance — post-16 outcomes for A-level, AS, technical and applied qualifications. Annual cadence.\n- `gb_eng_dfes_destinations_ks4` — England DfE post-KS4 destinations — education / apprenticeship / employment / NEET tracking for year-11 leavers, two-year lag.\n- `gb_eng_dfes_destinations_ks5` — England DfE post-KS5 destinations — higher-education entry, apprenticeships, employment for year-13 leavers.\n- `gb_eng_dfes_value_added` — England DfE KS5 value-added measures — by qualification and by subject.\n- `gb_eng_dfes_school_census` — England DfE School Census (Schools, Pupils and their Characteristics — SPC). Annual headcount + FSM + EAL + SEN by school.\n- `gb_eng_esfa_cfr` — England ESFA Consistent Financial Reporting — for maintained / local-authority schools. Annual income / expenditure / balances.\n- `gb_eng_esfa_aar` — England ESFA Academies Accounts Return — for academies, free schools and UTCs. Annual finance including trust central-services apportionment.\n- `gb_eng_lpa_admissions` — England local-authority published admissions outcomes — published-admission-number (PAN), preferences received, offers made, last-admitted distance, oversubscription criteria with offer counts. Cycle-keyed.\n- `gb_eng_ofsted_oeif` — England Ofsted Education Inspection Framework — pre-September-2025 inspection regime. Six numeric sub-judgements (1 outstanding..4 inadequate) plus optional early-years and sixth-form provision grades.\n- `gb_eng_ofsted_post_2025` — England Ofsted post-September-2025 reformed inspection — evaluation areas (1-5 ordinals) plus a special `safeguarding_grade` sentinel.\n- `gb_wls_welshgov_performance` — Wales Welsh Government performance data — scaffolded for future ingest; not currently populated.\n- `gb_wls_estyn_inspections` — Wales Estyn inspections — scaffolded for future ingest; not currently populated.\n- `gb_sct_education_scotland_performance` — Scotland Education Scotland performance — scaffolded for future ingest; not currently populated.\n- `gb_sct_hmie_inspections` — Scotland HMIE / Education Scotland inspections — scaffolded for future ingest; not currently populated.\n- `gb_nir_deni_performance` — Northern Ireland Department of Education performance — scaffolded for future ingest; not currently populated.\n- `gb_nir_eti_inspections` — Northern Ireland Education and Training Inspectorate (ETI) — scaffolded for future ingest; not currently populated.\n- `ie_doe_performance` — Ireland Department of Education performance — scaffolded for future ingest; not currently populated.\n- `ie_doe_inspections` — Ireland Department of Education inspections — scaffolded for future ingest; not currently populated.","example":"gb_eng_dfes_ks4"}]},"required":true,"description":"Identifies a country × publishing authority × domain combination. Use to look up metric definitions via `/v1/schools/frameworks/{framework}`. Naming convention: `{country}_{authority}_{domain}`.\n\nSupported values:\n\n- `gb_eng_dfes_ks2` — England DfE Key Stage 2 performance — end-of-primary outcomes at age 11. Metrics include `PTRWM_EXP` (% at expected standard in reading/writing/maths combined) and progress scores `PROG_READ`/`PROG_WRIT`/`PROG_MAT`. Annual cadence.\n- `gb_eng_dfes_ks4` — England DfE Key Stage 4 performance — GCSE-stage outcomes at age 16. Metrics include `ATT8` (Attainment 8), `EBACCAPS` (EBacc Average Point Score), `P8MEA` (Progress 8). Annual cadence.\n- `gb_eng_dfes_ks5` — England DfE Key Stage 5 performance — post-16 outcomes for A-level, AS, technical and applied qualifications. Annual cadence.\n- `gb_eng_dfes_destinations_ks4` — England DfE post-KS4 destinations — education / apprenticeship / employment / NEET tracking for year-11 leavers, two-year lag.\n- `gb_eng_dfes_destinations_ks5` — England DfE post-KS5 destinations — higher-education entry, apprenticeships, employment for year-13 leavers.\n- `gb_eng_dfes_value_added` — England DfE KS5 value-added measures — by qualification and by subject.\n- `gb_eng_dfes_school_census` — England DfE School Census (Schools, Pupils and their Characteristics — SPC). Annual headcount + FSM + EAL + SEN by school.\n- `gb_eng_esfa_cfr` — England ESFA Consistent Financial Reporting — for maintained / local-authority schools. Annual income / expenditure / balances.\n- `gb_eng_esfa_aar` — England ESFA Academies Accounts Return — for academies, free schools and UTCs. Annual finance including trust central-services apportionment.\n- `gb_eng_lpa_admissions` — England local-authority published admissions outcomes — published-admission-number (PAN), preferences received, offers made, last-admitted distance, oversubscription criteria with offer counts. Cycle-keyed.\n- `gb_eng_ofsted_oeif` — England Ofsted Education Inspection Framework — pre-September-2025 inspection regime. Six numeric sub-judgements (1 outstanding..4 inadequate) plus optional early-years and sixth-form provision grades.\n- `gb_eng_ofsted_post_2025` — England Ofsted post-September-2025 reformed inspection — evaluation areas (1-5 ordinals) plus a special `safeguarding_grade` sentinel.\n- `gb_wls_welshgov_performance` — Wales Welsh Government performance data — scaffolded for future ingest; not currently populated.\n- `gb_wls_estyn_inspections` — Wales Estyn inspections — scaffolded for future ingest; not currently populated.\n- `gb_sct_education_scotland_performance` — Scotland Education Scotland performance — scaffolded for future ingest; not currently populated.\n- `gb_sct_hmie_inspections` — Scotland HMIE / Education Scotland inspections — scaffolded for future ingest; not currently populated.\n- `gb_nir_deni_performance` — Northern Ireland Department of Education performance — scaffolded for future ingest; not currently populated.\n- `gb_nir_eti_inspections` — Northern Ireland Education and Training Inspectorate (ETI) — scaffolded for future ingest; not currently populated.\n- `ie_doe_performance` — Ireland Department of Education performance — scaffolded for future ingest; not currently populated.\n- `ie_doe_inspections` — Ireland Department of Education inspections — scaffolded for future ingest; not currently populated.","name":"framework","in":"path"}],"responses":{"200":{"description":"The framework and the definition of every metric under it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FrameworkDetailResponse"}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/schools/coverage":{"get":{"operationId":"getSchoolsCoverage","x-speakeasy-group":"Schools.CoverageMatrix","x-speakeasy-name-override":"get","tags":["Schools Reference"],"summary":"Get the schools coverage matrix","description":"Reports what schools data is held, one row per country and framework. Each row gives how many schools are covered against how many are expected, the earliest and latest academic years held, how often the source is refreshed, and the entitlement tier needed to read it. Read it before issuing per-school queries, so that an empty block on a school can be judged against what is actually loaded for that country and framework. Responses are cacheable for 1 hour.","responses":{"200":{"description":"What data is held for each country and framework.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CoverageMatrix"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/schools/changelog":{"get":{"operationId":"listSchoolsChangelog","x-speakeasy-group":"Schools.Changelog","x-speakeasy-name-override":"list","tags":["Schools Reference"],"summary":"List Schools API changelog entries","description":"Lists the changes made to the shape of the Schools API, newest first, so a cached schema can be reconciled without reading release notes. Each entry carries a dated `objectVersion`, whether the change was `additive`, a `deprecation`, a `removal` or a `fix`, and which shapes or endpoints it touched. A deprecation also carries the sunset date that the `Sunset` header on the affected endpoint reports. Entries are never edited once published. Responses are cacheable for 1 hour.","responses":{"200":{"description":"Changelog entries, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangelogListResponse"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/schools/{id}":{"get":{"operationId":"getSchoolById","x-speakeasy-name-override":"getSchoolById","tags":["Schools"],"summary":"Get school by id","description":"Returns one school by its identifier in this API. Use `attributes` to add aggregate blocks such as `inspections`, or to trim the response to the fields you need.","parameters":[{"schema":{"type":"string","description":"Identifier of the school, as returned in the `id` field of a school record.","example":"12345"},"required":true,"description":"Identifier of the school, as returned in the `id` field of a school record.","name":"id","in":"path"},{"schema":{"type":"string","description":"Comma-separated list of the fields and blocks to return. Omit it to get the whole school record with no aggregate blocks. Naming a block (`inspections`, `identifiers`, `trust`, `images`, `branding`, `accreditations`, `videos`, `about`) adds that block to the whole record; naming at least one ordinary field instead trims the response to the fields listed plus any blocks. `object` and `id` are always returned and names that are not recognised are ignored. Performance, census and finance figures are not part of this record, request them from `/v1/schools/metrics`.","example":"id,name,currentRating,inspections"},"required":false,"description":"Comma-separated list of the fields and blocks to return. Omit it to get the whole school record with no aggregate blocks. Naming a block (`inspections`, `identifiers`, `trust`, `images`, `branding`, `accreditations`, `videos`, `about`) adds that block to the whole record; naming at least one ordinary field instead trims the response to the fields listed plus any blocks. `object` and `id` are always returned and names that are not recognised are ignored. Performance, census and finance figures are not part of this record, request them from `/v1/schools/metrics`.","name":"attributes","in":"query"}],"responses":{"200":{"description":"The requested school.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["school"],"description":"Object type discriminator. Always `school`.","example":"school"},"id":{"type":"integer","description":"Identifier for the school within this API. Stable across updates.","example":12345},"country":{"type":"string","minLength":2,"maxLength":2,"default":"GB","description":"Country the school is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"region":{"type":"string","description":"Education system the school belongs to, as an ISO 3166-2 region code. `GB-ENG` is England, `GB-WLS` Wales, `GB-SCT` Scotland and `GB-NIR` Northern Ireland.","example":"GB-ENG"},"provider":{"type":"string","enum":["dfe","welshgov","seed","deni","dept_edu_ie"],"description":"Which national register issued the school's `key`. 'dfe' is the Department for Education register for England, which also carries cross-border Welsh URNs. 'welshgov' is the Welsh Government school number. 'seed' is the Scottish SEED code. 'deni' is the Northern Ireland Department of Education reference. 'dept_edu_ie' is the Irish roll number.","example":"dfe"},"key":{"type":"string","description":"The identifier the source register uses for this school, such as a URN under `dfe` or a SEED code under `seed`. Together with `provider` it identifies the school across jurisdictions.","example":"100000"},"name":{"type":"string","description":"Name of the school as its source register publishes it.","example":"St Mary's Primary School"},"slug":{"type":["string","null"],"description":"URL-friendly form of the school name, safe to use in a path. Null when none has been generated.","example":"st-marys-primary-school-westminster"},"type":{"type":"string","enum":["nursery","primary","secondary","all-through","sixth-form","special","independent","academy","other"],"description":"The kind of institution the school is. 'nursery' is early years, 'primary' covers key stages 1 and 2, 'secondary' covers key stages 3 and 4, 'all-through' combines primary and secondary, and 'sixth-form' is post-16 only. 'special' is special educational needs provision, 'independent' is fee-paying, 'academy' is state-funded but independently run, and 'other' covers alternative provision, pupil referral units and anything the register leaves unclassified.","example":"primary"},"subType":{"type":"string","description":"Finer-grained establishment type as the source register classifies it, for example 'Voluntary Aided School' or 'Academy Converter'.","example":"Voluntary Aided School"},"status":{"type":"string","enum":["open","closed","pending_closure"],"description":"Operating status of the school, as recorded by its source register. 'open' means it is operating, 'closed' means it has closed, and 'pending_closure' means the register has flagged it for closure. Filter on 'open' to exclude the other two.","example":"open"},"currentRating":{"type":["string","null"],"enum":["outstanding","good","satisfactory","inadequate","exceptional","strong_standard","expected_standard","needs_attention","urgent_improvement","requires_improvement","not_yet_inspected","excellent","adequate","unsatisfactory","very_good","weak","important_area_for_improvement","requires_significant_improvement","fair",null],"description":"The most recent inspection grade, in the words of the inspectorate that issued it: Ofsted in England, Estyn in Wales, Education Scotland, ETI in Northern Ireland and the DES Inspectorate in Ireland. The scales differ between inspectorates, so a grade is only comparable within one of them.","example":"good"},"lastInspectionDate":{"type":"string","description":"When the most recent inspection took place, as an ISO 8601 date.","example":"2024-01-15"},"location":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude of the school, in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude of the school, in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"description":"Point location of the school."},"address":{"type":"object","properties":{"street":{"type":"string","description":"Building number and street.","example":"123 High Street"},"locality":{"type":"string","description":"District or locality the school sits in.","example":"Westminster"},"town":{"type":"string","description":"Town or city.","example":"London"},"county":{"type":"string","description":"County or equivalent wider area.","example":"Greater London"},"postcode":{"type":"string","description":"Postcode in the format used by the school's own country, such as a UK postcode or an Eircode.","example":"SW1A 1AA"}},"description":"Postal address of the school."},"lsoaCode":{"type":["string","null"],"description":"Lower Layer Super Output Area (LSOA) code covering the school, for joining to area-level datasets. Null when no LSOA has been mapped to the school.","example":"E01004736"},"phase":{"type":"string","description":"Phase of education the source register assigns the school, in the register's own wording.","example":"Primary"},"ageRange":{"type":"string","description":"Age range the school covers, as the youngest and oldest age separated by a hyphen.","example":"4-11"},"gender":{"type":"string","description":"Whether the school admits boys, girls or both, in the source register's own wording.","example":"Mixed"},"religiousCharacter":{"type":"string","description":"Religious character the source register records for the school.","example":"Church of England"},"admissionsPolicy":{"type":"string","description":"Admissions policy the source register records for the school.","example":"Comprehensive"},"capacity":{"type":"integer","description":"Number of pupil places the source register records for the school.","example":420},"numberOfPupils":{"type":"integer","description":"Number of pupils the source register records for the school.","example":385},"specialClasses":{"type":"string"},"specialistResource":{"type":"string"},"trustName":{"type":"string","description":"Name of the trust the school belongs to, where the source register records one.","example":"London Academy Trust"},"trustId":{"type":"string","description":"Identifier of that trust in the source register.","example":"TR00123"},"laCode":{"type":"string","description":"Code of the local authority the school falls under.","example":"213"},"laName":{"type":"string","description":"Name of the local authority the school falls under.","example":"Westminster"},"establishmentNumber":{"type":"integer","description":"Establishment number the source register assigns the school.","example":3614},"headteacher":{"type":"string","description":"Name of the headteacher, where the source register records one.","example":"Mrs J Smith"},"telephone":{"type":"string","description":"Contact telephone number for the school.","example":"020 1234 5678"},"website":{"type":"string","description":"URL of the school's own website.","example":"https://www.example.sch.uk"},"distance":{"type":"number","description":"Distance from the search point, in metres. Present only on results from a `near` search.","example":1234.56},"catchment":{"$ref":"#/components/schemas/SchoolCatchmentBlock"},"inspections":{"type":["object","null"],"properties":{"current":{"$ref":"#/components/schemas/SchoolInspectionEvent"},"history":{"type":"array","items":{"$ref":"#/components/schemas/SchoolInspectionEvent"},"default":[],"description":"Every recorded inspection, newest first. The first entry is the same event as `current`."}},"required":["current"],"description":"The current inspection and the full history behind it. Present only when requested via `attributes=inspections`."},"identifiers":{"type":["object","null"],"properties":{"ukprn":{"type":["string","null"],"description":"The school's UK Provider Reference Number (UKPRN).","example":"10012345"},"estynId":{"type":["string","null"],"description":"The school's provider identifier with Estyn, the Welsh inspectorate."},"ofstedProviderId":{"type":["string","null"],"description":"The school's provider identifier with Ofsted, the English inspectorate."},"oldUrns":{"type":"array","items":{"type":"string"},"default":[],"description":"Unique Reference Numbers (URNs) this school was known by before. Empty when there are none."}},"description":"The identifiers this school carries in registers other than `provider`. Present only when requested via `attributes=identifiers`."},"trust":{"type":["object","null"],"properties":{"memberships":{"type":"array","items":{"$ref":"#/components/schemas/SchoolTrustMembership"},"default":[],"description":"The organisations the school currently belongs to, governance-leadership roles first."}},"description":"The trusts, federations and other organisations the school currently belongs to. Present only when requested via `attributes=trust`."},"images":{"type":["object","null"],"properties":{"images":{"type":"array","items":{"$ref":"#/components/schemas/SchoolImage"},"default":[],"description":"Photographs of the school's buildings and facilities, newest first. Only images cleared for publication appear here, so the list can be empty."}},"description":"Photographs of the school's buildings and facilities, taken from its own website. Requested via `attributes=images`, and null until at least one photograph is cleared for publication."},"branding":{"type":["object","null"],"properties":{"logoUrl":{"type":"string","description":"Public URL of the logo or crest.","example":"https://hot-cdn.vepler.com/schools/12345/images/ab12cd.png"},"primaryColour":{"type":"string","description":"Primary brand colour, as a hex code.","example":"#00a1d5"},"secondaryColour":{"type":"string","description":"Secondary brand colour, as a hex code.","example":"#1c1c1c"},"socialMedia":{"$ref":"#/components/schemas/SocialMediaLinks"}},"description":"The school's logo or crest and its social profiles, taken from its own website. Requested via `attributes=branding`, and null until at least one of them is cleared for publication."},"accreditations":{"type":["object","null"],"properties":{"accreditations":{"type":"array","items":{"$ref":"#/components/schemas/SchoolAccreditation"},"default":[],"description":"Award, kitemark and partner badges shown on the school's own website, newest first. Only badges cleared for publication appear here, so the list can be empty."}},"description":"Awards, kitemarks and partner badges the school displays on its own website. Requested via `attributes=accreditations`, and null until they are cleared for publication."},"videos":{"type":["object","null"],"properties":{"videos":{"type":"array","items":{"$ref":"#/components/schemas/SchoolVideo"},"default":[],"description":"Videos published on the school's own website. Only videos cleared for publication appear here, so the list can be empty."}},"description":"References to videos the school publishes, as metadata rather than the video itself. Requested via `attributes=videos`, and null until they are cleared for publication."},"about":{"type":["object","null"],"properties":{"ethos":{"type":["string","null"],"description":"The school's stated ethos and values."},"headteacherWelcome":{"type":["string","null"],"description":"The headteacher's published welcome message."},"sendStatement":{"type":["string","null"],"description":"The school's statement on special educational needs and disabilities (SEND), and on inclusion."},"clubsDescription":{"type":["string","null"],"description":"What the school publishes about its extra-curricular clubs."},"facilitiesDescription":{"type":["string","null"],"description":"What the school publishes about its facilities."},"aboutDescription":{"type":["string","null"],"description":"The school's general description of itself."},"historyDescription":{"type":["string","null"],"description":"The school's account of its own history."},"curriculumDescription":{"type":["string","null"],"description":"What the school publishes about its curriculum."},"resultsSummary":{"type":["string","null"],"description":"The school's own summary of its results, in the wording it published."},"uniformSupplier":{"type":["string","null"],"description":"Name of the uniform supplier, where the school names one."},"prospectusUrl":{"type":["string","null"],"description":"Address of the school's prospectus."},"breakfastClub":{"type":["boolean","null"],"description":"True when the school states that it runs a breakfast club."},"afterSchoolCare":{"type":["boolean","null"],"description":"True when the school states that it offers after-school or wraparound care."},"termDates":{"type":"array","items":{"$ref":"#/components/schemas/SchoolTermDate"},"default":[],"description":"Term and holiday dates as the school publishes them."}},"description":"What the school says about itself: ethos, headteacher's welcome, term dates and similar narrative. Requested via `attributes=about`, and null until the profile has been reviewed."},"createdAt":{"type":"string","description":"When this school first appeared in the API, as an ISO 8601 timestamp.","example":"2024-01-01T00:00:00.000Z"},"updatedAt":{"type":"string","description":"When this record was last changed, as an ISO 8601 timestamp.","example":"2024-01-01T00:00:00.000Z"},"lastUpdated":{"type":"string","description":"When the source register data behind this record was last refreshed, as an ISO 8601 timestamp.","example":"2024-01-01T00:00:00.000Z"}},"required":["object","id","region","provider","key","name","type","status","createdAt","updatedAt","lastUpdated"],"description":"One school record."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/area-reference/areas/{field}/{ids}":{"get":{"operationId":"getAreasByFieldAndIds","x-speakeasy-name-override":"getAreas","tags":["Areas"],"summary":"Get geographic areas by code","description":"Looks up areas by geography type and a comma-separated list of codes, and returns each one with its name, centre point and any geometry, relationships or hierarchy that was asked for. At most 100 codes can be given in a single request.","parameters":[{"schema":{"type":"string","description":"Geography type to look the codes up in, such as `postcode`, `ward` or `county`. Use `all` to search every type."},"required":true,"description":"Geography type to look the codes up in, such as `postcode`, `ward` or `county`. Use `all` to search every type.","name":"field","in":"path"},{"schema":{"type":"string","description":"Comma-separated area codes to retrieve, up to 100 per request."},"required":true,"description":"Comma-separated area codes to retrieve, up to 100 per request.","name":"ids","in":"path"},{"schema":{"type":"string","description":"Field to group the returned areas by, such as `type`.","example":"type"},"required":false,"description":"Field to group the returned areas by, such as `type`.","name":"groupBy","in":"query"},{"schema":{"type":"string","description":"Set to `true` to include each area's relationships with other areas.","example":"true"},"required":false,"description":"Set to `true` to include each area's relationships with other areas.","name":"includeRelationships","in":"query"},{"schema":{"type":"string","description":"Set to `true` to include the parent areas that contain each result, such as the ward and district a postcode sits in.","example":"true"},"required":false,"description":"Set to `true` to include the parent areas that contain each result, such as the ward and district a postcode sits in.","name":"includeHierarchy","in":"query"},{"schema":{"type":"string","description":"Set to `true` to include each area's boundary geometry.","example":"true"},"required":false,"description":"Set to `true` to include each area's boundary geometry.","name":"includeGeometry","in":"query"},{"schema":{"type":"string","default":"100","description":"Maximum number of areas to return. Defaults to 100.","example":"50"},"required":false,"description":"Maximum number of areas to return. Defaults to 100.","name":"limit","in":"query"},{"schema":{"type":"string","default":"0","description":"Number of results to skip before the first one returned. Defaults to 0.","example":"0"},"required":false,"description":"Number of results to skip before the first one returned. Defaults to 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"The areas matching the requested codes.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"True when the request succeeded.","example":true},"message":{"type":"string","description":"Human-readable note about the response. Not present in every response.","example":"Data retrieved successfully"},"result":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Numeric identifier for this area within the reference data. Not present in every response.","example":12345},"code":{"type":"string","description":"The code that identifies this area, such as a postcode unit or a statistical geography code.","example":"SW1A1AA"},"type":{"type":"string","enum":["postcode","outcode","uk_output_area","lsoa21","ward","parish","local_authority_district","county","country","county_electoral_division","district_borough_unitary","district_borough_unitary_ward","local_planning_authority","ceremonial_counties_region","english_region","country_region","unitary_electoral_division","province","electoral_division","greater_london_constituency","scotland_and_wales_constituency","scotland_and_wales_region","westminster_constituency","building","built_up_area_250","green_belt","common_land","parcels_gb","flood_risk","ramsar","natura_2000","aonb","area_natural_beauty","national_scenic_area","special_area_conservation","special_protection_area","ancient_woodland","native_woodland_survey","priority_habitats","protected_woodlands","protected_woodland","protected_scenic_landscapes","world_heritage_site","scheduled_monument","battlefield","protected_wreck_site","historic_landfill_site","radon_level","brownfield_land","noise_rail_lden","noise_road_lden","noise_industry_lden"],"example":"lsoa21","description":"Which geography or layer the area belongs to. The values cover postcode units and their outward codes (the first part of a postcode, such as `SW1A`), statistical geographies from the census Output Area and Lower Layer Super Output Area (LSOA) upwards, electoral and parliamentary boundaries, buildings and land parcels, flood risk, environmental and heritage designations, and noise mapping."},"name":{"type":"string","description":"Name of the area.","example":"Westminster"},"status":{"type":"string","description":"Status of the area in the reference data, such as `active`. Not present in every response.","example":"active"},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Extra attributes that vary by geography type, such as population or household counts. Null for geography types that carry no extra attributes.","example":{"population":242100,"households":118200}},"lat":{"type":["number","null"],"description":"Latitude of the centre of the area, in WGS84 decimal degrees.","example":51.5074},"long":{"type":["number","null"],"description":"Longitude of the centre of the area, in WGS84 decimal degrees.","example":-0.1278},"geometry":{"description":"Boundary of the area as a GeoJSON geometry, with coordinates given longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order). Returned only when `includeGeometry` is true.","example":{"type":"Polygon","coordinates":[[[-0.1278,51.5074],[-0.1268,51.5074],[-0.1268,51.5084],[-0.1278,51.5084],[-0.1278,51.5074]]]}},"areaSqm":{"type":["number","null"],"description":"Area of the geography in square metres.","example":2147000},"relationships":{"type":["array","null"],"items":{"type":"object","properties":{"targetId":{"type":"string","description":"Code of the related area.","example":"E09000001"},"targetType":{"type":"string","description":"Geography type of the related area, such as `local_authority_district`.","example":"local_authority_district"},"relationshipType":{"type":"string","description":"How this area relates to the one named by `targetId`, for example 'contains', 'borders' or 'overlaps'.","example":"contains"}},"required":["targetId","targetType","relationshipType"]},"description":"Relationships between this area and others. Returned only when `includeRelationships` is true."},"hierarchy":{"type":["array","null"],"items":{"type":"object","properties":{"entityId":{"type":"string","description":"Code of the area at this level of the hierarchy.","example":"E92000001"},"entityType":{"type":"string","description":"Geography type at this level, such as `country_region`.","example":"country_region"},"entityName":{"type":"string","description":"Name of the area at this level. Not present in every response.","example":"England"},"name":{"type":"string","description":"Label for the level itself, such as `Country`.","example":"Country"},"categoryName":{"type":"string","description":"Name of the area at this level, for use as a category label. Not present in every response.","example":"England"},"displayName":{"type":"string","description":"Name of the area at this level, formatted for display. Not present in every response.","example":"England"},"level":{"type":"number","description":"Position of this entry in the hierarchy.","example":1}},"required":["entityId","entityType","name","level"]},"description":"Parent areas that contain this one, at each level of the geographic hierarchy. Returned only when `includeHierarchy` is true."}},"required":["code","type","name"],"description":"An area in the geographic reference data, such as a postcode unit, an electoral ward or a statistical output area.","example":{"id":12345,"code":"SW1A1AA","type":"postcode","name":"Westminster, Buckingham Palace","status":"active","metadata":{"households":45,"population":112},"lat":51.5014,"long":-0.1419,"geometry":{"type":"Polygon","coordinates":[[[-0.1419,51.5014],[-0.1409,51.5014],[-0.1409,51.5024],[-0.1419,51.5024],[-0.1419,51.5014]]]},"areaSqm":125000,"relationships":[{"targetId":"E09000033","targetType":"local_authority_district","relationshipType":"contains"}],"hierarchy":[{"entityId":"E92000001","entityType":"country_region","entityName":"England","name":"Country","categoryName":"England","displayName":"England","level":1},{"entityId":"E12000007","entityType":"english_region","entityName":"London","name":"Region","categoryName":"London","displayName":"London","level":2}]}},"description":"The areas matching the requested codes."}},"required":["success","result"],"description":"Areas matching the requested codes, with any geometry, relationships and hierarchy that were asked for.","example":{"success":true,"result":[{"id":12345,"code":"SW1A1AA","type":"postcode","name":"Westminster, Buckingham Palace","status":"active","lat":51.5014,"long":-0.1419,"metadata":{"households":45,"population":112}}]}}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}}}}},"/v1/area-reference/areas/within":{"get":{"operationId":"getAreasWithinRadius","x-speakeasy-name-override":"getAreasWithin","tags":["Areas"],"summary":"Find areas within a radius of a location","description":"Returns the areas that fall within a radius of a point, each with its distance from that point. Narrow the search to a single geography type with `type`, and ask for boundaries with `includeGeometry`.","parameters":[{"schema":{"type":"string","description":"Latitude of the centre of the search, in WGS84 decimal degrees. Must be between -90 and 90.","example":"51.5074"},"required":true,"description":"Latitude of the centre of the search, in WGS84 decimal degrees. Must be between -90 and 90.","name":"lat","in":"query"},{"schema":{"type":"string","description":"Longitude of the centre of the search, in WGS84 decimal degrees. Must be between -180 and 180.","example":"-0.1278"},"required":true,"description":"Longitude of the centre of the search, in WGS84 decimal degrees. Must be between -180 and 180.","name":"lng","in":"query"},{"schema":{"type":"string","default":"1000","description":"How far from that point to search, in metres. Defaults to 1000.","example":"500"},"required":false,"description":"How far from that point to search, in metres. Defaults to 1000.","name":"radius","in":"query"},{"schema":{"type":"string","enum":["postcode","outcode","uk_output_area","lsoa21","ward","parish","local_authority_district","county","country","county_electoral_division","district_borough_unitary","district_borough_unitary_ward","local_planning_authority","ceremonial_counties_region","english_region","country_region","unitary_electoral_division","province","electoral_division","greater_london_constituency","scotland_and_wales_constituency","scotland_and_wales_region","westminster_constituency","building","built_up_area_250","green_belt","common_land","parcels_gb","flood_risk","ramsar","natura_2000","aonb","area_natural_beauty","national_scenic_area","special_area_conservation","special_protection_area","ancient_woodland","native_woodland_survey","priority_habitats","protected_woodlands","protected_woodland","protected_scenic_landscapes","world_heritage_site","scheduled_monument","battlefield","protected_wreck_site","historic_landfill_site","radon_level","brownfield_land","noise_rail_lden","noise_road_lden","noise_industry_lden"],"example":"lsoa21","description":"Return only areas of this geography type."},"required":false,"description":"Return only areas of this geography type.","name":"type","in":"query"},{"schema":{"type":"string","description":"Set to `true` to include each area's boundary geometry.","example":"false"},"required":false,"description":"Set to `true` to include each area's boundary geometry.","name":"includeGeometry","in":"query"},{"schema":{"type":"string","default":"100","description":"Maximum number of areas to return. Defaults to 100.","example":"10"},"required":false,"description":"Maximum number of areas to return. Defaults to 100.","name":"limit","in":"query"}],"responses":{"200":{"description":"Areas within the requested radius, with their distance from the search point.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"True when the request succeeded.","example":true},"message":{"type":"string","description":"Human-readable note about the response. Not present in every response.","example":"Data retrieved successfully"},"result":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Numeric identifier for this area within the reference data. Not present in every response.","example":12345},"code":{"type":"string","description":"The code that identifies this area, such as a postcode unit or a statistical geography code.","example":"SW1A1AA"},"type":{"type":"string","enum":["postcode","outcode","uk_output_area","lsoa21","ward","parish","local_authority_district","county","country","county_electoral_division","district_borough_unitary","district_borough_unitary_ward","local_planning_authority","ceremonial_counties_region","english_region","country_region","unitary_electoral_division","province","electoral_division","greater_london_constituency","scotland_and_wales_constituency","scotland_and_wales_region","westminster_constituency","building","built_up_area_250","green_belt","common_land","parcels_gb","flood_risk","ramsar","natura_2000","aonb","area_natural_beauty","national_scenic_area","special_area_conservation","special_protection_area","ancient_woodland","native_woodland_survey","priority_habitats","protected_woodlands","protected_woodland","protected_scenic_landscapes","world_heritage_site","scheduled_monument","battlefield","protected_wreck_site","historic_landfill_site","radon_level","brownfield_land","noise_rail_lden","noise_road_lden","noise_industry_lden"],"example":"lsoa21","description":"Which geography or layer the area belongs to. The values cover postcode units and their outward codes (the first part of a postcode, such as `SW1A`), statistical geographies from the census Output Area and Lower Layer Super Output Area (LSOA) upwards, electoral and parliamentary boundaries, buildings and land parcels, flood risk, environmental and heritage designations, and noise mapping."},"name":{"type":"string","description":"Name of the area.","example":"Westminster"},"status":{"type":"string","description":"Status of the area in the reference data, such as `active`. Not present in every response.","example":"active"},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Extra attributes that vary by geography type, such as population or household counts. Null for geography types that carry no extra attributes.","example":{"population":242100,"households":118200}},"lat":{"type":["number","null"],"description":"Latitude of the centre of the area, in WGS84 decimal degrees.","example":51.5074},"long":{"type":["number","null"],"description":"Longitude of the centre of the area, in WGS84 decimal degrees.","example":-0.1278},"geometry":{"description":"Boundary of the area as a GeoJSON geometry, with coordinates given longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order). Returned only when `includeGeometry` is true.","example":{"type":"Polygon","coordinates":[[[-0.1278,51.5074],[-0.1268,51.5074],[-0.1268,51.5084],[-0.1278,51.5084],[-0.1278,51.5074]]]}},"areaSqm":{"type":["number","null"],"description":"Area of the geography in square metres.","example":2147000},"relationships":{"type":["array","null"],"items":{"type":"object","properties":{"targetId":{"type":"string","description":"Code of the related area.","example":"E09000001"},"targetType":{"type":"string","description":"Geography type of the related area, such as `local_authority_district`.","example":"local_authority_district"},"relationshipType":{"type":"string","description":"How this area relates to the one named by `targetId`, for example 'contains', 'borders' or 'overlaps'.","example":"contains"}},"required":["targetId","targetType","relationshipType"]},"description":"Relationships between this area and others. Returned only when `includeRelationships` is true."},"hierarchy":{"type":["array","null"],"items":{"type":"object","properties":{"entityId":{"type":"string","description":"Code of the area at this level of the hierarchy.","example":"E92000001"},"entityType":{"type":"string","description":"Geography type at this level, such as `country_region`.","example":"country_region"},"entityName":{"type":"string","description":"Name of the area at this level. Not present in every response.","example":"England"},"name":{"type":"string","description":"Label for the level itself, such as `Country`.","example":"Country"},"categoryName":{"type":"string","description":"Name of the area at this level, for use as a category label. Not present in every response.","example":"England"},"displayName":{"type":"string","description":"Name of the area at this level, formatted for display. Not present in every response.","example":"England"},"level":{"type":"number","description":"Position of this entry in the hierarchy.","example":1}},"required":["entityId","entityType","name","level"]},"description":"Parent areas that contain this one, at each level of the geographic hierarchy. Returned only when `includeHierarchy` is true."},"distance":{"type":"number","description":"Distance from the search point, in metres.","example":342.7}},"required":["code","type","name","distance"],"description":"An area in the geographic reference data, such as a postcode unit, an electoral ward or a statistical output area.","example":{"id":12345,"code":"SW1A1AA","type":"postcode","name":"Westminster, Buckingham Palace","status":"active","metadata":{"households":45,"population":112},"lat":51.5014,"long":-0.1419,"geometry":{"type":"Polygon","coordinates":[[[-0.1419,51.5014],[-0.1409,51.5014],[-0.1409,51.5024],[-0.1419,51.5024],[-0.1419,51.5014]]]},"areaSqm":125000,"relationships":[{"targetId":"E09000033","targetType":"local_authority_district","relationshipType":"contains"}],"hierarchy":[{"entityId":"E92000001","entityType":"country_region","entityName":"England","name":"Country","categoryName":"England","displayName":"England","level":1},{"entityId":"E12000007","entityType":"english_region","entityName":"London","name":"Region","categoryName":"London","displayName":"London","level":2}]}},"description":"Areas that fall within the search radius, each with its distance from the search point."}},"required":["success","result"],"description":"Areas within the requested radius of a point.","example":{"success":true,"result":[{"id":12345,"code":"E05009372","type":"ward","name":"St James's","status":"active","lat":51.5074,"long":-0.1278,"distance":127.3},{"id":12346,"code":"E05009373","type":"ward","name":"Hyde Park","status":"active","lat":51.508,"long":-0.1285,"distance":342.7}]}}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}}}}},"/v1/area-reference/areas/children/{parentCode}":{"get":{"operationId":"getChildAreas","x-speakeasy-name-override":"getChildAreas","tags":["Areas"],"summary":"Get the areas inside a parent area","description":"Returns the areas contained by a parent area, such as the wards inside a local authority district. Narrow the result to one geography type with `childType`.","parameters":[{"schema":{"type":"string","description":"Code of the parent area, such as a local authority district code."},"required":true,"description":"Code of the parent area, such as a local authority district code.","name":"parentCode","in":"path"},{"schema":{"type":"string","description":"Set to `true` to include each child area's boundary geometry.","example":"false"},"required":false,"description":"Set to `true` to include each child area's boundary geometry.","name":"includeGeometry","in":"query"},{"schema":{"type":"string","description":"Return only child areas of this geography type."},"required":false,"description":"Return only child areas of this geography type.","name":"childType","in":"query"}],"responses":{"200":{"description":"The parent area and the areas it contains.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"True when the request succeeded.","example":true},"message":{"type":"string","description":"Human-readable note about the response. Not present in every response.","example":"Data retrieved successfully"},"parent":{"type":"object","properties":{"id":{"type":"number","description":"Numeric identifier for this area within the reference data. Not present in every response.","example":12345},"code":{"type":"string","description":"The code that identifies this area, such as a postcode unit or a statistical geography code.","example":"SW1A1AA"},"type":{"type":"string","enum":["postcode","outcode","uk_output_area","lsoa21","ward","parish","local_authority_district","county","country","county_electoral_division","district_borough_unitary","district_borough_unitary_ward","local_planning_authority","ceremonial_counties_region","english_region","country_region","unitary_electoral_division","province","electoral_division","greater_london_constituency","scotland_and_wales_constituency","scotland_and_wales_region","westminster_constituency","building","built_up_area_250","green_belt","common_land","parcels_gb","flood_risk","ramsar","natura_2000","aonb","area_natural_beauty","national_scenic_area","special_area_conservation","special_protection_area","ancient_woodland","native_woodland_survey","priority_habitats","protected_woodlands","protected_woodland","protected_scenic_landscapes","world_heritage_site","scheduled_monument","battlefield","protected_wreck_site","historic_landfill_site","radon_level","brownfield_land","noise_rail_lden","noise_road_lden","noise_industry_lden"],"example":"lsoa21","description":"Which geography or layer the area belongs to. The values cover postcode units and their outward codes (the first part of a postcode, such as `SW1A`), statistical geographies from the census Output Area and Lower Layer Super Output Area (LSOA) upwards, electoral and parliamentary boundaries, buildings and land parcels, flood risk, environmental and heritage designations, and noise mapping."},"name":{"type":"string","description":"Name of the area.","example":"Westminster"},"status":{"type":"string","description":"Status of the area in the reference data, such as `active`. Not present in every response.","example":"active"},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Extra attributes that vary by geography type, such as population or household counts. Null for geography types that carry no extra attributes.","example":{"population":242100,"households":118200}},"lat":{"type":["number","null"],"description":"Latitude of the centre of the area, in WGS84 decimal degrees.","example":51.5074},"long":{"type":["number","null"],"description":"Longitude of the centre of the area, in WGS84 decimal degrees.","example":-0.1278},"geometry":{"description":"Boundary of the area as a GeoJSON geometry, with coordinates given longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order). Returned only when `includeGeometry` is true.","example":{"type":"Polygon","coordinates":[[[-0.1278,51.5074],[-0.1268,51.5074],[-0.1268,51.5084],[-0.1278,51.5084],[-0.1278,51.5074]]]}},"areaSqm":{"type":["number","null"],"description":"Area of the geography in square metres.","example":2147000},"relationships":{"type":["array","null"],"items":{"type":"object","properties":{"targetId":{"type":"string","description":"Code of the related area.","example":"E09000001"},"targetType":{"type":"string","description":"Geography type of the related area, such as `local_authority_district`.","example":"local_authority_district"},"relationshipType":{"type":"string","description":"How this area relates to the one named by `targetId`, for example 'contains', 'borders' or 'overlaps'.","example":"contains"}},"required":["targetId","targetType","relationshipType"]},"description":"Relationships between this area and others. Returned only when `includeRelationships` is true."},"hierarchy":{"type":["array","null"],"items":{"type":"object","properties":{"entityId":{"type":"string","description":"Code of the area at this level of the hierarchy.","example":"E92000001"},"entityType":{"type":"string","description":"Geography type at this level, such as `country_region`.","example":"country_region"},"entityName":{"type":"string","description":"Name of the area at this level. Not present in every response.","example":"England"},"name":{"type":"string","description":"Label for the level itself, such as `Country`.","example":"Country"},"categoryName":{"type":"string","description":"Name of the area at this level, for use as a category label. Not present in every response.","example":"England"},"displayName":{"type":"string","description":"Name of the area at this level, formatted for display. Not present in every response.","example":"England"},"level":{"type":"number","description":"Position of this entry in the hierarchy.","example":1}},"required":["entityId","entityType","name","level"]},"description":"Parent areas that contain this one, at each level of the geographic hierarchy. Returned only when `includeHierarchy` is true."}},"required":["code","type","name"],"description":"The area whose children were requested.","example":{"id":12345,"code":"SW1A1AA","type":"postcode","name":"Westminster, Buckingham Palace","status":"active","metadata":{"households":45,"population":112},"lat":51.5014,"long":-0.1419,"geometry":{"type":"Polygon","coordinates":[[[-0.1419,51.5014],[-0.1409,51.5014],[-0.1409,51.5024],[-0.1419,51.5024],[-0.1419,51.5014]]]},"areaSqm":125000,"relationships":[{"targetId":"E09000033","targetType":"local_authority_district","relationshipType":"contains"}],"hierarchy":[{"entityId":"E92000001","entityType":"country_region","entityName":"England","name":"Country","categoryName":"England","displayName":"England","level":1},{"entityId":"E12000007","entityType":"english_region","entityName":"London","name":"Region","categoryName":"London","displayName":"London","level":2}]}},"children":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Numeric identifier for this area within the reference data. Not present in every response.","example":12345},"code":{"type":"string","description":"The code that identifies this area, such as a postcode unit or a statistical geography code.","example":"SW1A1AA"},"type":{"type":"string","enum":["postcode","outcode","uk_output_area","lsoa21","ward","parish","local_authority_district","county","country","county_electoral_division","district_borough_unitary","district_borough_unitary_ward","local_planning_authority","ceremonial_counties_region","english_region","country_region","unitary_electoral_division","province","electoral_division","greater_london_constituency","scotland_and_wales_constituency","scotland_and_wales_region","westminster_constituency","building","built_up_area_250","green_belt","common_land","parcels_gb","flood_risk","ramsar","natura_2000","aonb","area_natural_beauty","national_scenic_area","special_area_conservation","special_protection_area","ancient_woodland","native_woodland_survey","priority_habitats","protected_woodlands","protected_woodland","protected_scenic_landscapes","world_heritage_site","scheduled_monument","battlefield","protected_wreck_site","historic_landfill_site","radon_level","brownfield_land","noise_rail_lden","noise_road_lden","noise_industry_lden"],"example":"lsoa21","description":"Which geography or layer the area belongs to. The values cover postcode units and their outward codes (the first part of a postcode, such as `SW1A`), statistical geographies from the census Output Area and Lower Layer Super Output Area (LSOA) upwards, electoral and parliamentary boundaries, buildings and land parcels, flood risk, environmental and heritage designations, and noise mapping."},"name":{"type":"string","description":"Name of the area.","example":"Westminster"},"status":{"type":"string","description":"Status of the area in the reference data, such as `active`. Not present in every response.","example":"active"},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Extra attributes that vary by geography type, such as population or household counts. Null for geography types that carry no extra attributes.","example":{"population":242100,"households":118200}},"lat":{"type":["number","null"],"description":"Latitude of the centre of the area, in WGS84 decimal degrees.","example":51.5074},"long":{"type":["number","null"],"description":"Longitude of the centre of the area, in WGS84 decimal degrees.","example":-0.1278},"geometry":{"description":"Boundary of the area as a GeoJSON geometry, with coordinates given longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order). Returned only when `includeGeometry` is true.","example":{"type":"Polygon","coordinates":[[[-0.1278,51.5074],[-0.1268,51.5074],[-0.1268,51.5084],[-0.1278,51.5084],[-0.1278,51.5074]]]}},"areaSqm":{"type":["number","null"],"description":"Area of the geography in square metres.","example":2147000},"relationships":{"type":["array","null"],"items":{"type":"object","properties":{"targetId":{"type":"string","description":"Code of the related area.","example":"E09000001"},"targetType":{"type":"string","description":"Geography type of the related area, such as `local_authority_district`.","example":"local_authority_district"},"relationshipType":{"type":"string","description":"How this area relates to the one named by `targetId`, for example 'contains', 'borders' or 'overlaps'.","example":"contains"}},"required":["targetId","targetType","relationshipType"]},"description":"Relationships between this area and others. Returned only when `includeRelationships` is true."},"hierarchy":{"type":["array","null"],"items":{"type":"object","properties":{"entityId":{"type":"string","description":"Code of the area at this level of the hierarchy.","example":"E92000001"},"entityType":{"type":"string","description":"Geography type at this level, such as `country_region`.","example":"country_region"},"entityName":{"type":"string","description":"Name of the area at this level. Not present in every response.","example":"England"},"name":{"type":"string","description":"Label for the level itself, such as `Country`.","example":"Country"},"categoryName":{"type":"string","description":"Name of the area at this level, for use as a category label. Not present in every response.","example":"England"},"displayName":{"type":"string","description":"Name of the area at this level, formatted for display. Not present in every response.","example":"England"},"level":{"type":"number","description":"Position of this entry in the hierarchy.","example":1}},"required":["entityId","entityType","name","level"]},"description":"Parent areas that contain this one, at each level of the geographic hierarchy. Returned only when `includeHierarchy` is true."}},"required":["code","type","name"],"description":"An area in the geographic reference data, such as a postcode unit, an electoral ward or a statistical output area.","example":{"id":12345,"code":"SW1A1AA","type":"postcode","name":"Westminster, Buckingham Palace","status":"active","metadata":{"households":45,"population":112},"lat":51.5014,"long":-0.1419,"geometry":{"type":"Polygon","coordinates":[[[-0.1419,51.5014],[-0.1409,51.5014],[-0.1409,51.5024],[-0.1419,51.5024],[-0.1419,51.5014]]]},"areaSqm":125000,"relationships":[{"targetId":"E09000033","targetType":"local_authority_district","relationshipType":"contains"}],"hierarchy":[{"entityId":"E92000001","entityType":"country_region","entityName":"England","name":"Country","categoryName":"England","displayName":"England","level":1},{"entityId":"E12000007","entityType":"english_region","entityName":"London","name":"Region","categoryName":"London","displayName":"London","level":2}]}},"description":"The areas contained by that parent."},"total":{"type":"number","description":"Number of child areas within the parent.","example":24}},"required":["success","parent","children","total"],"description":"A parent area and the areas it contains.","example":{"success":true,"parent":{"code":"E09000033","type":"local_authority_district","name":"Westminster","status":"active","lat":51.5074,"long":-0.1419},"children":[{"code":"E05009372","type":"ward","name":"St James's","status":"active","lat":51.5074,"long":-0.1278},{"code":"E05009373","type":"ward","name":"Hyde Park","status":"active","lat":51.508,"long":-0.1285}],"total":24}}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}}}}},"/v1/area-reference/areas/border/{targetType}/{targetCode}/{sourceType}":{"get":{"operationId":"getBorderingAreas","x-speakeasy-name-override":"getBorderingAreas","tags":["Areas"],"summary":"Find areas that border a target area","description":"Returns every area of the requested type whose boundary touches the target area, for example the districts that border a given district.","parameters":[{"schema":{"type":"string","description":"Geography type of the target area."},"required":true,"description":"Geography type of the target area.","name":"targetType","in":"path"},{"schema":{"type":"string","description":"Code of the target area."},"required":true,"description":"Code of the target area.","name":"targetCode","in":"path"},{"schema":{"type":"string","description":"Geography type of the bordering areas to return."},"required":true,"description":"Geography type of the bordering areas to return.","name":"sourceType","in":"path"},{"schema":{"type":"string","description":"Set to `true` to include each bordering area's boundary geometry.","example":"false"},"required":false,"description":"Set to `true` to include each bordering area's boundary geometry.","name":"includeGeometry","in":"query"}],"responses":{"200":{"description":"The target area and the areas that border it.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"True when the request succeeded.","example":true},"message":{"type":"string","description":"Human-readable note about the response. Not present in every response.","example":"Data retrieved successfully"},"target":{"type":"object","properties":{"id":{"type":"number","description":"Numeric identifier for this area within the reference data. Not present in every response.","example":12345},"code":{"type":"string","description":"The code that identifies this area, such as a postcode unit or a statistical geography code.","example":"SW1A1AA"},"type":{"type":"string","enum":["postcode","outcode","uk_output_area","lsoa21","ward","parish","local_authority_district","county","country","county_electoral_division","district_borough_unitary","district_borough_unitary_ward","local_planning_authority","ceremonial_counties_region","english_region","country_region","unitary_electoral_division","province","electoral_division","greater_london_constituency","scotland_and_wales_constituency","scotland_and_wales_region","westminster_constituency","building","built_up_area_250","green_belt","common_land","parcels_gb","flood_risk","ramsar","natura_2000","aonb","area_natural_beauty","national_scenic_area","special_area_conservation","special_protection_area","ancient_woodland","native_woodland_survey","priority_habitats","protected_woodlands","protected_woodland","protected_scenic_landscapes","world_heritage_site","scheduled_monument","battlefield","protected_wreck_site","historic_landfill_site","radon_level","brownfield_land","noise_rail_lden","noise_road_lden","noise_industry_lden"],"example":"lsoa21","description":"Which geography or layer the area belongs to. The values cover postcode units and their outward codes (the first part of a postcode, such as `SW1A`), statistical geographies from the census Output Area and Lower Layer Super Output Area (LSOA) upwards, electoral and parliamentary boundaries, buildings and land parcels, flood risk, environmental and heritage designations, and noise mapping."},"name":{"type":"string","description":"Name of the area.","example":"Westminster"},"status":{"type":"string","description":"Status of the area in the reference data, such as `active`. Not present in every response.","example":"active"},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Extra attributes that vary by geography type, such as population or household counts. Null for geography types that carry no extra attributes.","example":{"population":242100,"households":118200}},"lat":{"type":["number","null"],"description":"Latitude of the centre of the area, in WGS84 decimal degrees.","example":51.5074},"long":{"type":["number","null"],"description":"Longitude of the centre of the area, in WGS84 decimal degrees.","example":-0.1278},"geometry":{"description":"Boundary of the area as a GeoJSON geometry, with coordinates given longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order). Returned only when `includeGeometry` is true.","example":{"type":"Polygon","coordinates":[[[-0.1278,51.5074],[-0.1268,51.5074],[-0.1268,51.5084],[-0.1278,51.5084],[-0.1278,51.5074]]]}},"areaSqm":{"type":["number","null"],"description":"Area of the geography in square metres.","example":2147000},"relationships":{"type":["array","null"],"items":{"type":"object","properties":{"targetId":{"type":"string","description":"Code of the related area.","example":"E09000001"},"targetType":{"type":"string","description":"Geography type of the related area, such as `local_authority_district`.","example":"local_authority_district"},"relationshipType":{"type":"string","description":"How this area relates to the one named by `targetId`, for example 'contains', 'borders' or 'overlaps'.","example":"contains"}},"required":["targetId","targetType","relationshipType"]},"description":"Relationships between this area and others. Returned only when `includeRelationships` is true."},"hierarchy":{"type":["array","null"],"items":{"type":"object","properties":{"entityId":{"type":"string","description":"Code of the area at this level of the hierarchy.","example":"E92000001"},"entityType":{"type":"string","description":"Geography type at this level, such as `country_region`.","example":"country_region"},"entityName":{"type":"string","description":"Name of the area at this level. Not present in every response.","example":"England"},"name":{"type":"string","description":"Label for the level itself, such as `Country`.","example":"Country"},"categoryName":{"type":"string","description":"Name of the area at this level, for use as a category label. Not present in every response.","example":"England"},"displayName":{"type":"string","description":"Name of the area at this level, formatted for display. Not present in every response.","example":"England"},"level":{"type":"number","description":"Position of this entry in the hierarchy.","example":1}},"required":["entityId","entityType","name","level"]},"description":"Parent areas that contain this one, at each level of the geographic hierarchy. Returned only when `includeHierarchy` is true."}},"required":["code","type","name"],"description":"The area whose neighbours were requested.","example":{"id":12345,"code":"SW1A1AA","type":"postcode","name":"Westminster, Buckingham Palace","status":"active","metadata":{"households":45,"population":112},"lat":51.5014,"long":-0.1419,"geometry":{"type":"Polygon","coordinates":[[[-0.1419,51.5014],[-0.1409,51.5014],[-0.1409,51.5024],[-0.1419,51.5024],[-0.1419,51.5014]]]},"areaSqm":125000,"relationships":[{"targetId":"E09000033","targetType":"local_authority_district","relationshipType":"contains"}],"hierarchy":[{"entityId":"E92000001","entityType":"country_region","entityName":"England","name":"Country","categoryName":"England","displayName":"England","level":1},{"entityId":"E12000007","entityType":"english_region","entityName":"London","name":"Region","categoryName":"London","displayName":"London","level":2}]}},"borderingAreas":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Numeric identifier for this area within the reference data. Not present in every response.","example":12345},"code":{"type":"string","description":"The code that identifies this area, such as a postcode unit or a statistical geography code.","example":"SW1A1AA"},"type":{"type":"string","enum":["postcode","outcode","uk_output_area","lsoa21","ward","parish","local_authority_district","county","country","county_electoral_division","district_borough_unitary","district_borough_unitary_ward","local_planning_authority","ceremonial_counties_region","english_region","country_region","unitary_electoral_division","province","electoral_division","greater_london_constituency","scotland_and_wales_constituency","scotland_and_wales_region","westminster_constituency","building","built_up_area_250","green_belt","common_land","parcels_gb","flood_risk","ramsar","natura_2000","aonb","area_natural_beauty","national_scenic_area","special_area_conservation","special_protection_area","ancient_woodland","native_woodland_survey","priority_habitats","protected_woodlands","protected_woodland","protected_scenic_landscapes","world_heritage_site","scheduled_monument","battlefield","protected_wreck_site","historic_landfill_site","radon_level","brownfield_land","noise_rail_lden","noise_road_lden","noise_industry_lden"],"example":"lsoa21","description":"Which geography or layer the area belongs to. The values cover postcode units and their outward codes (the first part of a postcode, such as `SW1A`), statistical geographies from the census Output Area and Lower Layer Super Output Area (LSOA) upwards, electoral and parliamentary boundaries, buildings and land parcels, flood risk, environmental and heritage designations, and noise mapping."},"name":{"type":"string","description":"Name of the area.","example":"Westminster"},"status":{"type":"string","description":"Status of the area in the reference data, such as `active`. Not present in every response.","example":"active"},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Extra attributes that vary by geography type, such as population or household counts. Null for geography types that carry no extra attributes.","example":{"population":242100,"households":118200}},"lat":{"type":["number","null"],"description":"Latitude of the centre of the area, in WGS84 decimal degrees.","example":51.5074},"long":{"type":["number","null"],"description":"Longitude of the centre of the area, in WGS84 decimal degrees.","example":-0.1278},"geometry":{"description":"Boundary of the area as a GeoJSON geometry, with coordinates given longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order). Returned only when `includeGeometry` is true.","example":{"type":"Polygon","coordinates":[[[-0.1278,51.5074],[-0.1268,51.5074],[-0.1268,51.5084],[-0.1278,51.5084],[-0.1278,51.5074]]]}},"areaSqm":{"type":["number","null"],"description":"Area of the geography in square metres.","example":2147000},"relationships":{"type":["array","null"],"items":{"type":"object","properties":{"targetId":{"type":"string","description":"Code of the related area.","example":"E09000001"},"targetType":{"type":"string","description":"Geography type of the related area, such as `local_authority_district`.","example":"local_authority_district"},"relationshipType":{"type":"string","description":"How this area relates to the one named by `targetId`, for example 'contains', 'borders' or 'overlaps'.","example":"contains"}},"required":["targetId","targetType","relationshipType"]},"description":"Relationships between this area and others. Returned only when `includeRelationships` is true."},"hierarchy":{"type":["array","null"],"items":{"type":"object","properties":{"entityId":{"type":"string","description":"Code of the area at this level of the hierarchy.","example":"E92000001"},"entityType":{"type":"string","description":"Geography type at this level, such as `country_region`.","example":"country_region"},"entityName":{"type":"string","description":"Name of the area at this level. Not present in every response.","example":"England"},"name":{"type":"string","description":"Label for the level itself, such as `Country`.","example":"Country"},"categoryName":{"type":"string","description":"Name of the area at this level, for use as a category label. Not present in every response.","example":"England"},"displayName":{"type":"string","description":"Name of the area at this level, formatted for display. Not present in every response.","example":"England"},"level":{"type":"number","description":"Position of this entry in the hierarchy.","example":1}},"required":["entityId","entityType","name","level"]},"description":"Parent areas that contain this one, at each level of the geographic hierarchy. Returned only when `includeHierarchy` is true."}},"required":["code","type","name"],"description":"An area in the geographic reference data, such as a postcode unit, an electoral ward or a statistical output area.","example":{"id":12345,"code":"SW1A1AA","type":"postcode","name":"Westminster, Buckingham Palace","status":"active","metadata":{"households":45,"population":112},"lat":51.5014,"long":-0.1419,"geometry":{"type":"Polygon","coordinates":[[[-0.1419,51.5014],[-0.1409,51.5014],[-0.1409,51.5024],[-0.1419,51.5024],[-0.1419,51.5014]]]},"areaSqm":125000,"relationships":[{"targetId":"E09000033","targetType":"local_authority_district","relationshipType":"contains"}],"hierarchy":[{"entityId":"E92000001","entityType":"country_region","entityName":"England","name":"Country","categoryName":"England","displayName":"England","level":1},{"entityId":"E12000007","entityType":"english_region","entityName":"London","name":"Region","categoryName":"London","displayName":"London","level":2}]}},"description":"Areas of the requested type that share a boundary with the target."},"total":{"type":"number","description":"Number of bordering areas found.","example":6}},"required":["success","target","borderingAreas","total"],"description":"A target area and the areas that border it.","example":{"success":true,"target":{"code":"E09000033","type":"local_authority_district","name":"Westminster","status":"active","lat":51.5074,"long":-0.1419},"borderingAreas":[{"code":"E09000001","type":"local_authority_district","name":"City of London","status":"active","lat":51.5155,"long":-0.0922},{"code":"E09000007","type":"local_authority_district","name":"Camden","status":"active","lat":51.529,"long":-0.1255}],"total":6}}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}}}}},"/v1/area-reference/areas/coverage":{"get":{"operationId":"getAreaCoverage","x-speakeasy-name-override":"getCoverage","tags":["Areas"],"summary":"Calculate geographic coverage","description":"Measures how much of one geography something else covers. Give `sourceCode` with `targetCode` to measure the overlap between two geographies, or with `coverageType` to measure a layer such as flood risk, noise, radon or a conservation designation within the source area. Add `intersectsWith` to count the buildings or land parcels the layer touches instead of measuring area. Exactly one of `targetCode` and `coverageType` must be supplied.","parameters":[{"schema":{"type":"string","description":"Code of the geography to measure coverage within, such as a ward or district code.","example":"E05000001"},"required":true,"description":"Code of the geography to measure coverage within, such as a ward or district code.","name":"sourceCode","in":"query"},{"schema":{"type":"string","description":"Code of a second geography, to measure the overlap between the two. Supply either this or `coverageType`, and not both.","example":"E09000033"},"required":false,"description":"Code of a second geography, to measure the overlap between the two. Supply either this or `coverageType`, and not both.","name":"targetCode","in":"query"},{"schema":{"type":"string","enum":["flood_risk","noise_road_lden","noise_rail_lden","noise_industry_lden","radon_level","ramsar","special_area_conservation","special_protection_area","ancient_woodland","native_woodland_survey","area_natural_beauty","national_scenic_area","priority_habitats","protected_woodlands","natura_2000","aonb","protected_scenic_landscapes","historic_landfill_site","world_heritage_site","protected_wreck_site","scheduled_monument","battlefield","brownfield_land","green_belt","common_land","built_up_area_250","parcels_gb","building"],"description":"Layer to measure within the source geography, such as flood risk or road noise. Supply either this or `targetCode`, and not both.","example":"flood_risk"},"required":false,"description":"Layer to measure within the source geography, such as flood risk or road noise. Supply either this or `targetCode`, and not both.","name":"coverageType","in":"query"},{"schema":{"type":"string","enum":["postcode","outcode","uk_output_area","lsoa21","ward","parish","local_authority_district","county","country","county_electoral_division","district_borough_unitary","district_borough_unitary_ward","local_planning_authority","ceremonial_counties_region","english_region","country_region","unitary_electoral_division","province","electoral_division","greater_london_constituency","scotland_and_wales_constituency","scotland_and_wales_region","westminster_constituency","building","built_up_area_250","green_belt","common_land","parcels_gb","flood_risk","ramsar","natura_2000","aonb","area_natural_beauty","national_scenic_area","special_area_conservation","special_protection_area","ancient_woodland","native_woodland_survey","priority_habitats","protected_woodlands","protected_woodland","protected_scenic_landscapes","world_heritage_site","scheduled_monument","battlefield","protected_wreck_site","historic_landfill_site","radon_level","brownfield_land","noise_rail_lden","noise_road_lden","noise_industry_lden"],"example":"lsoa21","description":"Report the coverage against the entities of this type inside the source geography, such as buildings or land parcels, rather than against its area. Can only be used alongside `coverageType`."},"required":false,"description":"Report the coverage against the entities of this type inside the source geography, such as buildings or land parcels, rather than against its area. Can only be used alongside `coverageType`.","name":"intersectsWith","in":"query"}],"responses":{"200":{"description":"Coverage of the source geography, one row per band, layer or geography measured.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"True when the request succeeded.","example":true},"message":{"type":"string","description":"Human-readable note about the response. Not present in every response.","example":"Data retrieved successfully"},"sourceCode":{"type":"string","description":"Code of the geography the coverage was measured within.","example":"E05000001"},"sourceName":{"type":"string","description":"Name of that geography.","example":"St James's"},"sourceType":{"type":"string","enum":["postcode","outcode","uk_output_area","lsoa21","ward","parish","local_authority_district","county","country","county_electoral_division","district_borough_unitary","district_borough_unitary_ward","local_planning_authority","ceremonial_counties_region","english_region","country_region","unitary_electoral_division","province","electoral_division","greater_london_constituency","scotland_and_wales_constituency","scotland_and_wales_region","westminster_constituency","building","built_up_area_250","green_belt","common_land","parcels_gb","flood_risk","ramsar","natura_2000","aonb","area_natural_beauty","national_scenic_area","special_area_conservation","special_protection_area","ancient_woodland","native_woodland_survey","priority_habitats","protected_woodlands","protected_woodland","protected_scenic_landscapes","world_heritage_site","scheduled_monument","battlefield","protected_wreck_site","historic_landfill_site","radon_level","brownfield_land","noise_rail_lden","noise_road_lden","noise_industry_lden"],"example":"lsoa21","description":"Geography type of that area."},"sourceArea":{"type":"number","description":"Total area of that geography, in square metres.","example":2147000},"targetCode":{"type":"string","description":"Code of the second geography. Returned when the request supplied `targetCode`.","example":"E09000033"},"targetName":{"type":"string","description":"Name of that second geography. Returned when the request supplied `targetCode`.","example":"Westminster"},"coverageType":{"type":"string","enum":["flood_risk","noise_road_lden","noise_rail_lden","noise_industry_lden","radon_level","ramsar","special_area_conservation","special_protection_area","ancient_woodland","native_woodland_survey","area_natural_beauty","national_scenic_area","priority_habitats","protected_woodlands","natura_2000","aonb","protected_scenic_landscapes","historic_landfill_site","world_heritage_site","protected_wreck_site","scheduled_monument","battlefield","brownfield_land","green_belt","common_land","built_up_area_250","parcels_gb","building"],"description":"The layer that was measured. Returned when the request supplied `coverageType`.","example":"flood_risk"},"intersectsWith":{"type":"string","enum":["postcode","outcode","uk_output_area","lsoa21","ward","parish","local_authority_district","county","country","county_electoral_division","district_borough_unitary","district_borough_unitary_ward","local_planning_authority","ceremonial_counties_region","english_region","country_region","unitary_electoral_division","province","electoral_division","greater_london_constituency","scotland_and_wales_constituency","scotland_and_wales_region","westminster_constituency","building","built_up_area_250","green_belt","common_land","parcels_gb","flood_risk","ramsar","natura_2000","aonb","area_natural_beauty","national_scenic_area","special_area_conservation","special_protection_area","ancient_woodland","native_woodland_survey","priority_habitats","protected_woodlands","protected_woodland","protected_scenic_landscapes","world_heritage_site","scheduled_monument","battlefield","protected_wreck_site","historic_landfill_site","radon_level","brownfield_land","noise_rail_lden","noise_road_lden","noise_industry_lden"],"example":"lsoa21","description":"The entity type the coverage was counted against, when the request asked for one."},"coverage":{"type":"array","items":{"type":"object","properties":{"identifier":{"type":"string","description":"What this row covers: a band of the requested layer such as `flood_risk_high`, a geography code, or a noise range.","example":"flood_risk_high"},"area":{"type":"number","description":"Area covered, in square metres.","example":125000},"percentage":{"type":"number","description":"Share of the source geography this row covers, as a percentage. For `intersectsWith` queries it is the share of those entities instead.","example":23.5},"metadata":{"type":"object","properties":{"category":{"type":"string","description":"Band this row falls in, where the layer is banded, such as `high`, `medium` or `low`.","example":"high"},"entityCount":{"type":"number","description":"Number of entities of the `intersectsWith` type that the layer touches. Returned only for `intersectsWith` queries.","example":42},"totalEntities":{"type":"number","description":"Total number of entities of that type inside the source geography. Returned only for `intersectsWith` queries.","example":156},"dbRange":{"type":"string","description":"Noise band this row covers, in decibels, such as `55-70dB`. Returned for the noise layers.","example":"55-70dB"},"featureCount":{"type":"number","description":"Number of source features that make up this row.","example":3},"componentLayers":{"type":"array","items":{"type":"string"},"description":"The individual layers a composite layer is built from.","example":["ancient_woodland","native_woodland_survey"]}},"additionalProperties":{},"description":"Extra detail about this row, varying by layer."}},"required":["identifier","area","percentage"],"description":"One row of a coverage calculation.","example":{"identifier":"flood_risk_high","area":125000,"percentage":23.5,"metadata":{"category":"high"}}},"description":"One row per band, layer or geography measured."}},"required":["success","sourceCode","sourceName","sourceType","sourceArea","coverage"],"description":"Coverage for a geography: either its overlap with a second geography, or how much of it a layer covers, depending on which parameter was supplied.","example":{"success":true,"sourceCode":"E05000001","sourceName":"St James's","sourceType":"ward","sourceArea":2147000,"coverageType":"flood_risk","coverage":[{"identifier":"flood_risk_high","area":125000,"percentage":5.8,"metadata":{"category":"high"}},{"identifier":"flood_risk_medium","area":340000,"percentage":15.8,"metadata":{"category":"medium"}},{"identifier":"flood_risk_low","area":680000,"percentage":31.7,"metadata":{"category":"low"}}]}}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}},"404":{"description":"No geography matches the supplied `sourceCode` or `targetCode`.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}}}}},"/v1/area-reference/connectivity/{geographicCodes}":{"get":{"operationId":"getConnectivityScores","x-speakeasy-name-override":"getConnectivityScores","tags":["Connectivity"],"summary":"Get broadband and mobile connectivity scores","description":"Returns fixed broadband and mobile coverage scores for one or more areas, from 0 to 100. Ask for the speed and technology figures behind the scores with `includeBreakdown`, and for earlier periods with `includePeriodHistory`.","parameters":[{"schema":{"type":"string","description":"Comma-separated area codes to score, such as postcode units or ward codes."},"required":true,"description":"Comma-separated area codes to score, such as postcode units or ward codes.","name":"geographicCodes","in":"path"},{"schema":{"type":"string","description":"Set to `true` to include the technology and speed band figures behind the scores.","example":"true"},"required":false,"description":"Set to `true` to include the technology and speed band figures behind the scores.","name":"includeBreakdown","in":"query"},{"schema":{"type":"string","description":"Set to `true` to include each area's name and geography type.","example":"true"},"required":false,"description":"Set to `true` to include each area's name and geography type.","name":"includeAreaInfo","in":"query"},{"schema":{"type":"string","description":"Return scores for this single period, as an ISO 8601 date.","example":"2024-01-01"},"required":false,"description":"Return scores for this single period, as an ISO 8601 date.","name":"dataPeriod","in":"query"},{"schema":{"type":"string","description":"Earliest period to return, as an ISO 8601 date.","example":"2024-01-01"},"required":false,"description":"Earliest period to return, as an ISO 8601 date.","name":"startPeriod","in":"query"},{"schema":{"type":"string","description":"Latest period to return, as an ISO 8601 date.","example":"2024-12-31"},"required":false,"description":"Latest period to return, as an ISO 8601 date.","name":"endPeriod","in":"query"},{"schema":{"type":"string","description":"Set to `true` to include earlier periods alongside the current scores.","example":"false"},"required":false,"description":"Set to `true` to include earlier periods alongside the current scores.","name":"includePeriodHistory","in":"query"},{"schema":{"type":"string","default":"10","description":"Maximum number of earlier periods to return. Defaults to 10.","example":"12"},"required":false,"description":"Maximum number of earlier periods to return. Defaults to 10.","name":"periodLimit","in":"query"},{"schema":{"type":"string","enum":["basic","detailed"],"default":"basic","description":"How much to return: `basic` for the scores alone, `detailed` for the scores with their metadata. Defaults to `basic`.","example":"basic"},"required":false,"description":"How much to return: `basic` for the scores alone, `detailed` for the scores with their metadata. Defaults to `basic`.","name":"format","in":"query"},{"schema":{"type":"string","default":"50","description":"Maximum number of areas to return. Defaults to 50.","example":"10"},"required":false,"description":"Maximum number of areas to return. Defaults to 50.","name":"limit","in":"query"}],"responses":{"200":{"description":"Connectivity scores for the requested areas.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"True when the request succeeded.","example":true},"message":{"type":"string","description":"Human-readable note about the response. Not present in every response.","example":"Data retrieved successfully"},"result":{"type":"array","items":{"type":"object","properties":{"geographicCode":{"type":"string","description":"Code of the area these figures describe.","example":"SW1A1AA"},"areaInfo":{"type":"object","properties":{"code":{"type":"string","description":"Code identifying the area.","example":"SW1A1AA"},"name":{"type":"string","description":"Name of the area.","example":"Westminster, Buckingham Palace"},"type":{"type":"string","description":"Geography type of the area, such as `postcode` or `ward`.","example":"postcode"}},"required":["code","name","type"],"description":"Name and geography type of the area. Returned only when `includeAreaInfo` is true."},"connectivityScores":{"type":"object","properties":{"overall":{"type":["number","null"],"description":"Combined connectivity score for the area, from 0 to 100, where higher is better.","example":87.5},"fixedBroadband":{"type":["number","null"],"description":"Score for fixed broadband alone, from 0 to 100.","example":92.3},"mobileCoverage":{"type":["number","null"],"description":"Score for mobile coverage alone, from 0 to 100.","example":82.7},"breakdown":{"type":"object","properties":{"fixedBroadband":{"type":"object","properties":{"availability":{"type":"object","properties":{"hasCoverage":{"type":"boolean","description":"True when any fixed broadband service is available in the area.","example":true},"coveragePercentage":{"type":"number","description":"Share of premises with some broadband service, as a percentage.","example":98.5},"premisesWithService":{"type":"number","description":"Number of premises with a broadband service available. Not present in every response.","example":1398},"totalPremises":{"type":"number","description":"Number of premises in the area. Not present in every response.","example":1420}},"required":["hasCoverage","coveragePercentage"],"description":"How much of the area has fixed broadband at all."},"speedBands":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the speed band, such as `Gigabit`, `Ultrafast` or `Superfast`.","example":"Gigabit"},"minSpeed":{"type":"number","description":"Lowest download speed in this band, in Mbps.","example":1000},"maxSpeed":{"type":["number","null"],"description":"Highest download speed in this band, in Mbps. Null when the band has no upper limit.","example":null},"coverage":{"type":"number","description":"Share of premises in the area that can get this band, as a percentage.","example":87.5},"premises":{"type":"number","description":"Number of premises that can get this band. Not present in every response.","example":1245}},"required":["name","minSpeed","maxSpeed","coverage"],"description":"Availability of one broadband speed band in an area.","example":{"name":"Gigabit","minSpeed":1000,"maxSpeed":null,"coverage":87.5,"premises":1245}},"description":"Availability broken down by speed band."},"technology":{"type":"object","properties":{"fiber":{"type":"number","description":"Share of premises able to get a fibre connection (FTTP or FTTH), as a percentage.","example":78.3},"cable":{"type":"number","description":"Share of premises able to get cable broadband, as a percentage.","example":12.5},"dsl":{"type":"number","description":"Share of premises able to get a DSL or ADSL connection, as a percentage.","example":8.2},"wireless":{"type":"number","description":"Share of premises able to get fixed wireless access, as a percentage.","example":1},"satellite":{"type":"number","description":"Share of premises able to get satellite broadband, as a percentage.","example":0.5}},"description":"Availability broken down by the technology carrying the connection. Not present in every response."},"rawData":{"type":"object","properties":{"gigabitCoverage":{"type":["number","null"],"description":"Share of premises able to get 1000 Mbps or more, as a percentage.","example":87.5},"ufbbCoverage":{"type":["number","null"],"description":"Share of premises able to get 100 Mbps or more, counted as ultrafast, as a percentage.","example":95.2},"sfbbCoverage":{"type":["number","null"],"description":"Share of premises able to get 30 Mbps or more, counted as superfast, as a percentage.","example":98.5},"poorCoverage":{"type":["number","null"],"description":"Share of premises limited to less than 10 Mbps, as a percentage.","example":1.5},"noServiceCoverage":{"type":["number","null"],"description":"Share of premises with no fixed broadband service available, as a percentage.","example":0.3}},"required":["gigabitCoverage","ufbbCoverage","sfbbCoverage","poorCoverage","noServiceCoverage"],"description":"Coverage figures at Ofcom's own speed thresholds. Not present in every response."}},"required":["availability","speedBands"],"description":"Fixed broadband availability for an area, in detail.","example":{"availability":{"hasCoverage":true,"coveragePercentage":98.5,"premisesWithService":1398,"totalPremises":1420},"speedBands":[{"name":"Gigabit","minSpeed":1000,"maxSpeed":null,"coverage":87.5,"premises":1242},{"name":"Ultrafast","minSpeed":100,"maxSpeed":999,"coverage":7.7,"premises":109}],"technology":{"fiber":78.3,"cable":12.5,"dsl":8.2,"wireless":1},"rawData":{"gigabitCoverage":87.5,"ufbbCoverage":95.2,"sfbbCoverage":98.5,"poorCoverage":1.5,"noServiceCoverage":0.3}}},"mobileCoverage":{"type":"object","properties":{"indoor":{"type":"object","properties":{"fourG":{"type":"number","description":"Indoor 4G coverage in the area, as a percentage.","example":92.3},"fiveG":{"type":"number","description":"Indoor 5G coverage in the area, as a percentage. Not present in every response.","example":45.8},"voice":{"type":"number","description":"Indoor voice call coverage, as a percentage.","example":98.5},"data":{"type":"number","description":"Indoor mobile data coverage, as a percentage.","example":94.2}},"required":["fourG","voice","data"],"description":"Coverage measured indoors. Not present in every response."},"outdoor":{"type":"object","properties":{"fourG":{"type":"number","description":"Outdoor 4G coverage in the area, as a percentage.","example":98.7},"fiveG":{"type":"number","description":"Outdoor 5G coverage in the area, as a percentage. Not present in every response.","example":67.3},"voice":{"type":"number","description":"Outdoor voice call coverage, as a percentage.","example":99.8},"data":{"type":"number","description":"Outdoor mobile data coverage, as a percentage.","example":99.2}},"required":["fourG","voice","data"],"description":"Coverage measured outdoors. Not present in every response."},"byOperator":{"type":"array","items":{"type":"object","properties":{"operator":{"type":"string","description":"Name of the mobile network operator.","example":"EE"},"indoor4G":{"type":"number","description":"Indoor 4G coverage from this operator, as a percentage.","example":95.2},"outdoor4G":{"type":"number","description":"Outdoor 4G coverage from this operator, as a percentage.","example":99.1},"indoor5G":{"type":"number","description":"Indoor 5G coverage from this operator, as a percentage. Not present in every response.","example":52.3},"outdoor5G":{"type":"number","description":"Outdoor 5G coverage from this operator, as a percentage. Not present in every response.","example":71.8}},"required":["operator","indoor4G","outdoor4G"]},"description":"The same coverage figures for each operator separately. Not present in every response."},"rawData":{"type":"object","additionalProperties":{},"description":"Further operator-level figures, keyed by field name. Not present in every response."}},"description":"Mobile network coverage for an area, in detail.","example":{"indoor":{"fourG":92.3,"fiveG":45.8,"voice":98.5,"data":94.2},"outdoor":{"fourG":98.7,"fiveG":67.3,"voice":99.8,"data":99.2},"byOperator":[{"operator":"EE","indoor4G":95.2,"outdoor4G":99.1,"indoor5G":52.3,"outdoor5G":71.8},{"operator":"O2","indoor4G":91.5,"outdoor4G":98.3,"indoor5G":41.2,"outdoor5G":64.5}]}}},"description":"The figures behind the scores. Returned only when `includeBreakdown` is true."}},"required":["overall","fixedBroadband","mobileCoverage"],"description":"Connectivity scores for the area.","example":{"overall":87.5,"fixedBroadband":92.3,"mobileCoverage":82.7}},"speedSummary":{"type":"object","properties":{"gigabitAvailable":{"type":"boolean","description":"True when gigabit speeds of 1000 Mbps or more are available in the area.","example":true},"gigabitCoverage":{"type":["number","null"],"description":"Share of premises that can get 1000 Mbps or more, as a percentage.","example":87.5},"ultrafastCoverage":{"type":["number","null"],"description":"Share of premises that can get 100 Mbps or more, as a percentage.","example":95.2},"superfastCoverage":{"type":["number","null"],"description":"Share of premises that can get 30 Mbps or more, as a percentage.","example":98.5},"poorCoveragePercentage":{"type":["number","null"],"description":"Share of premises limited to less than 10 Mbps, as a percentage.","example":1.5}},"required":["gigabitAvailable","gigabitCoverage","ultrafastCoverage","superfastCoverage","poorCoveragePercentage"],"description":"Headline broadband speed availability for the area.","example":{"gigabitAvailable":true,"gigabitCoverage":87.5,"ultrafastCoverage":95.2,"superfastCoverage":98.5,"poorCoveragePercentage":1.5}},"dataSources":{"type":"object","properties":{"fixed":{"type":"object","properties":{"method":{"type":"string","description":"How the fixed broadband figures for this area were produced, such as `spatial_aggregation`.","example":"spatial_aggregation"},"sourceCode":{"type":"string","description":"Code of the area the figures were taken from, when they did not come from this area directly.","example":"E05009372"}},"required":["method","sourceCode"],"description":"Where the fixed broadband figures came from. Not present in every response."},"mobile":{"type":"object","properties":{"method":{"type":"string","description":"How the mobile coverage figures for this area were produced, such as `direct_calculation`.","example":"direct_calculation"},"sourceCode":{"type":"string","description":"Code of the area the figures were taken from, when they did not come from this area directly.","example":"SW1A1AA"}},"required":["method","sourceCode"],"description":"Where the mobile coverage figures came from. Not present in every response."}},"description":"How the figures were produced."},"timeseries":{"type":"array","items":{"type":"object","properties":{"dataPeriod":{"type":"string","description":"The period this data point covers, as an ISO 8601 date.","example":"2024-01-01"},"connectivityScores":{"type":"object","properties":{"overall":{"type":["number","null"],"description":"Combined connectivity score for the area, from 0 to 100, where higher is better.","example":87.5},"fixedBroadband":{"type":["number","null"],"description":"Score for fixed broadband alone, from 0 to 100.","example":92.3},"mobileCoverage":{"type":["number","null"],"description":"Score for mobile coverage alone, from 0 to 100.","example":82.7},"breakdown":{"type":"object","properties":{"fixedBroadband":{"type":"object","properties":{"availability":{"type":"object","properties":{"hasCoverage":{"type":"boolean","description":"True when any fixed broadband service is available in the area.","example":true},"coveragePercentage":{"type":"number","description":"Share of premises with some broadband service, as a percentage.","example":98.5},"premisesWithService":{"type":"number","description":"Number of premises with a broadband service available. Not present in every response.","example":1398},"totalPremises":{"type":"number","description":"Number of premises in the area. Not present in every response.","example":1420}},"required":["hasCoverage","coveragePercentage"],"description":"How much of the area has fixed broadband at all."},"speedBands":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the speed band, such as `Gigabit`, `Ultrafast` or `Superfast`.","example":"Gigabit"},"minSpeed":{"type":"number","description":"Lowest download speed in this band, in Mbps.","example":1000},"maxSpeed":{"type":["number","null"],"description":"Highest download speed in this band, in Mbps. Null when the band has no upper limit.","example":null},"coverage":{"type":"number","description":"Share of premises in the area that can get this band, as a percentage.","example":87.5},"premises":{"type":"number","description":"Number of premises that can get this band. Not present in every response.","example":1245}},"required":["name","minSpeed","maxSpeed","coverage"],"description":"Availability of one broadband speed band in an area.","example":{"name":"Gigabit","minSpeed":1000,"maxSpeed":null,"coverage":87.5,"premises":1245}},"description":"Availability broken down by speed band."},"technology":{"type":"object","properties":{"fiber":{"type":"number","description":"Share of premises able to get a fibre connection (FTTP or FTTH), as a percentage.","example":78.3},"cable":{"type":"number","description":"Share of premises able to get cable broadband, as a percentage.","example":12.5},"dsl":{"type":"number","description":"Share of premises able to get a DSL or ADSL connection, as a percentage.","example":8.2},"wireless":{"type":"number","description":"Share of premises able to get fixed wireless access, as a percentage.","example":1},"satellite":{"type":"number","description":"Share of premises able to get satellite broadband, as a percentage.","example":0.5}},"description":"Availability broken down by the technology carrying the connection. Not present in every response."},"rawData":{"type":"object","properties":{"gigabitCoverage":{"type":["number","null"],"description":"Share of premises able to get 1000 Mbps or more, as a percentage.","example":87.5},"ufbbCoverage":{"type":["number","null"],"description":"Share of premises able to get 100 Mbps or more, counted as ultrafast, as a percentage.","example":95.2},"sfbbCoverage":{"type":["number","null"],"description":"Share of premises able to get 30 Mbps or more, counted as superfast, as a percentage.","example":98.5},"poorCoverage":{"type":["number","null"],"description":"Share of premises limited to less than 10 Mbps, as a percentage.","example":1.5},"noServiceCoverage":{"type":["number","null"],"description":"Share of premises with no fixed broadband service available, as a percentage.","example":0.3}},"required":["gigabitCoverage","ufbbCoverage","sfbbCoverage","poorCoverage","noServiceCoverage"],"description":"Coverage figures at Ofcom's own speed thresholds. Not present in every response."}},"required":["availability","speedBands"],"description":"Fixed broadband availability for an area, in detail.","example":{"availability":{"hasCoverage":true,"coveragePercentage":98.5,"premisesWithService":1398,"totalPremises":1420},"speedBands":[{"name":"Gigabit","minSpeed":1000,"maxSpeed":null,"coverage":87.5,"premises":1242},{"name":"Ultrafast","minSpeed":100,"maxSpeed":999,"coverage":7.7,"premises":109}],"technology":{"fiber":78.3,"cable":12.5,"dsl":8.2,"wireless":1},"rawData":{"gigabitCoverage":87.5,"ufbbCoverage":95.2,"sfbbCoverage":98.5,"poorCoverage":1.5,"noServiceCoverage":0.3}}},"mobileCoverage":{"type":"object","properties":{"indoor":{"type":"object","properties":{"fourG":{"type":"number","description":"Indoor 4G coverage in the area, as a percentage.","example":92.3},"fiveG":{"type":"number","description":"Indoor 5G coverage in the area, as a percentage. Not present in every response.","example":45.8},"voice":{"type":"number","description":"Indoor voice call coverage, as a percentage.","example":98.5},"data":{"type":"number","description":"Indoor mobile data coverage, as a percentage.","example":94.2}},"required":["fourG","voice","data"],"description":"Coverage measured indoors. Not present in every response."},"outdoor":{"type":"object","properties":{"fourG":{"type":"number","description":"Outdoor 4G coverage in the area, as a percentage.","example":98.7},"fiveG":{"type":"number","description":"Outdoor 5G coverage in the area, as a percentage. Not present in every response.","example":67.3},"voice":{"type":"number","description":"Outdoor voice call coverage, as a percentage.","example":99.8},"data":{"type":"number","description":"Outdoor mobile data coverage, as a percentage.","example":99.2}},"required":["fourG","voice","data"],"description":"Coverage measured outdoors. Not present in every response."},"byOperator":{"type":"array","items":{"type":"object","properties":{"operator":{"type":"string","description":"Name of the mobile network operator.","example":"EE"},"indoor4G":{"type":"number","description":"Indoor 4G coverage from this operator, as a percentage.","example":95.2},"outdoor4G":{"type":"number","description":"Outdoor 4G coverage from this operator, as a percentage.","example":99.1},"indoor5G":{"type":"number","description":"Indoor 5G coverage from this operator, as a percentage. Not present in every response.","example":52.3},"outdoor5G":{"type":"number","description":"Outdoor 5G coverage from this operator, as a percentage. Not present in every response.","example":71.8}},"required":["operator","indoor4G","outdoor4G"]},"description":"The same coverage figures for each operator separately. Not present in every response."},"rawData":{"type":"object","additionalProperties":{},"description":"Further operator-level figures, keyed by field name. Not present in every response."}},"description":"Mobile network coverage for an area, in detail.","example":{"indoor":{"fourG":92.3,"fiveG":45.8,"voice":98.5,"data":94.2},"outdoor":{"fourG":98.7,"fiveG":67.3,"voice":99.8,"data":99.2},"byOperator":[{"operator":"EE","indoor4G":95.2,"outdoor4G":99.1,"indoor5G":52.3,"outdoor5G":71.8},{"operator":"O2","indoor4G":91.5,"outdoor4G":98.3,"indoor5G":41.2,"outdoor5G":64.5}]}}},"description":"The figures behind the scores. Returned only when `includeBreakdown` is true."}},"required":["overall","fixedBroadband","mobileCoverage"],"description":"Scores for that period.","example":{"overall":87.5,"fixedBroadband":92.3,"mobileCoverage":82.7}},"speedSummary":{"type":"object","properties":{"gigabitAvailable":{"type":"boolean","description":"True when gigabit speeds of 1000 Mbps or more are available in the area.","example":true},"gigabitCoverage":{"type":["number","null"],"description":"Share of premises that can get 1000 Mbps or more, as a percentage.","example":87.5},"ultrafastCoverage":{"type":["number","null"],"description":"Share of premises that can get 100 Mbps or more, as a percentage.","example":95.2},"superfastCoverage":{"type":["number","null"],"description":"Share of premises that can get 30 Mbps or more, as a percentage.","example":98.5},"poorCoveragePercentage":{"type":["number","null"],"description":"Share of premises limited to less than 10 Mbps, as a percentage.","example":1.5}},"required":["gigabitAvailable","gigabitCoverage","ultrafastCoverage","superfastCoverage","poorCoveragePercentage"],"description":"Broadband speed availability for that period. Not present in every response.","example":{"gigabitAvailable":true,"gigabitCoverage":87.5,"ultrafastCoverage":95.2,"superfastCoverage":98.5,"poorCoveragePercentage":1.5}},"breakdown":{"type":"object","properties":{"fixedBroadband":{"type":"object","properties":{"availability":{"type":"object","properties":{"hasCoverage":{"type":"boolean","description":"True when any fixed broadband service is available in the area.","example":true},"coveragePercentage":{"type":"number","description":"Share of premises with some broadband service, as a percentage.","example":98.5},"premisesWithService":{"type":"number","description":"Number of premises with a broadband service available. Not present in every response.","example":1398},"totalPremises":{"type":"number","description":"Number of premises in the area. Not present in every response.","example":1420}},"required":["hasCoverage","coveragePercentage"],"description":"How much of the area has fixed broadband at all."},"speedBands":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the speed band, such as `Gigabit`, `Ultrafast` or `Superfast`.","example":"Gigabit"},"minSpeed":{"type":"number","description":"Lowest download speed in this band, in Mbps.","example":1000},"maxSpeed":{"type":["number","null"],"description":"Highest download speed in this band, in Mbps. Null when the band has no upper limit.","example":null},"coverage":{"type":"number","description":"Share of premises in the area that can get this band, as a percentage.","example":87.5},"premises":{"type":"number","description":"Number of premises that can get this band. Not present in every response.","example":1245}},"required":["name","minSpeed","maxSpeed","coverage"],"description":"Availability of one broadband speed band in an area.","example":{"name":"Gigabit","minSpeed":1000,"maxSpeed":null,"coverage":87.5,"premises":1245}},"description":"Availability broken down by speed band."},"technology":{"type":"object","properties":{"fiber":{"type":"number","description":"Share of premises able to get a fibre connection (FTTP or FTTH), as a percentage.","example":78.3},"cable":{"type":"number","description":"Share of premises able to get cable broadband, as a percentage.","example":12.5},"dsl":{"type":"number","description":"Share of premises able to get a DSL or ADSL connection, as a percentage.","example":8.2},"wireless":{"type":"number","description":"Share of premises able to get fixed wireless access, as a percentage.","example":1},"satellite":{"type":"number","description":"Share of premises able to get satellite broadband, as a percentage.","example":0.5}},"description":"Availability broken down by the technology carrying the connection. Not present in every response."},"rawData":{"type":"object","properties":{"gigabitCoverage":{"type":["number","null"],"description":"Share of premises able to get 1000 Mbps or more, as a percentage.","example":87.5},"ufbbCoverage":{"type":["number","null"],"description":"Share of premises able to get 100 Mbps or more, counted as ultrafast, as a percentage.","example":95.2},"sfbbCoverage":{"type":["number","null"],"description":"Share of premises able to get 30 Mbps or more, counted as superfast, as a percentage.","example":98.5},"poorCoverage":{"type":["number","null"],"description":"Share of premises limited to less than 10 Mbps, as a percentage.","example":1.5},"noServiceCoverage":{"type":["number","null"],"description":"Share of premises with no fixed broadband service available, as a percentage.","example":0.3}},"required":["gigabitCoverage","ufbbCoverage","sfbbCoverage","poorCoverage","noServiceCoverage"],"description":"Coverage figures at Ofcom's own speed thresholds. Not present in every response."}},"required":["availability","speedBands"],"description":"Fixed broadband availability for an area, in detail.","example":{"availability":{"hasCoverage":true,"coveragePercentage":98.5,"premisesWithService":1398,"totalPremises":1420},"speedBands":[{"name":"Gigabit","minSpeed":1000,"maxSpeed":null,"coverage":87.5,"premises":1242},{"name":"Ultrafast","minSpeed":100,"maxSpeed":999,"coverage":7.7,"premises":109}],"technology":{"fiber":78.3,"cable":12.5,"dsl":8.2,"wireless":1},"rawData":{"gigabitCoverage":87.5,"ufbbCoverage":95.2,"sfbbCoverage":98.5,"poorCoverage":1.5,"noServiceCoverage":0.3}}},"mobileCoverage":{"type":"object","properties":{"indoor":{"type":"object","properties":{"fourG":{"type":"number","description":"Indoor 4G coverage in the area, as a percentage.","example":92.3},"fiveG":{"type":"number","description":"Indoor 5G coverage in the area, as a percentage. Not present in every response.","example":45.8},"voice":{"type":"number","description":"Indoor voice call coverage, as a percentage.","example":98.5},"data":{"type":"number","description":"Indoor mobile data coverage, as a percentage.","example":94.2}},"required":["fourG","voice","data"],"description":"Coverage measured indoors. Not present in every response."},"outdoor":{"type":"object","properties":{"fourG":{"type":"number","description":"Outdoor 4G coverage in the area, as a percentage.","example":98.7},"fiveG":{"type":"number","description":"Outdoor 5G coverage in the area, as a percentage. Not present in every response.","example":67.3},"voice":{"type":"number","description":"Outdoor voice call coverage, as a percentage.","example":99.8},"data":{"type":"number","description":"Outdoor mobile data coverage, as a percentage.","example":99.2}},"required":["fourG","voice","data"],"description":"Coverage measured outdoors. Not present in every response."},"byOperator":{"type":"array","items":{"type":"object","properties":{"operator":{"type":"string","description":"Name of the mobile network operator.","example":"EE"},"indoor4G":{"type":"number","description":"Indoor 4G coverage from this operator, as a percentage.","example":95.2},"outdoor4G":{"type":"number","description":"Outdoor 4G coverage from this operator, as a percentage.","example":99.1},"indoor5G":{"type":"number","description":"Indoor 5G coverage from this operator, as a percentage. Not present in every response.","example":52.3},"outdoor5G":{"type":"number","description":"Outdoor 5G coverage from this operator, as a percentage. Not present in every response.","example":71.8}},"required":["operator","indoor4G","outdoor4G"]},"description":"The same coverage figures for each operator separately. Not present in every response."},"rawData":{"type":"object","additionalProperties":{},"description":"Further operator-level figures, keyed by field name. Not present in every response."}},"description":"Mobile network coverage for an area, in detail.","example":{"indoor":{"fourG":92.3,"fiveG":45.8,"voice":98.5,"data":94.2},"outdoor":{"fourG":98.7,"fiveG":67.3,"voice":99.8,"data":99.2},"byOperator":[{"operator":"EE","indoor4G":95.2,"outdoor4G":99.1,"indoor5G":52.3,"outdoor5G":71.8},{"operator":"O2","indoor4G":91.5,"outdoor4G":98.3,"indoor5G":41.2,"outdoor5G":64.5}]}}},"description":"The figures behind the scores. Returned only when `includeBreakdown` is true."},"metadata":{"type":"object","properties":{"dataVintage":{"type":["string","null"],"description":"When the underlying data was collected, as an ISO 8601 date.","example":"2024-01-01"},"computedAt":{"type":"string","description":"When the scores were computed, as an ISO 8601 timestamp.","example":"2024-01-15T10:30:00Z"}},"required":["dataVintage","computedAt"],"description":"Dates behind this data point."}},"required":["dataPeriod","connectivityScores","metadata"],"description":"Connectivity for one earlier period.","example":{"dataPeriod":"2024-01-01","connectivityScores":{"overall":87.5,"fixedBroadband":92.3,"mobileCoverage":82.7},"speedSummary":{"gigabitAvailable":true,"gigabitCoverage":87.5,"ultrafastCoverage":95.2,"superfastCoverage":98.5,"poorCoveragePercentage":1.5},"metadata":{"dataVintage":"2024-01-01","computedAt":"2024-01-15T10:30:00Z"}}},"description":"Earlier periods for the same area. Returned only when `includePeriodHistory` is true."},"metadata":{"type":"object","properties":{"processingTimeMs":{"type":"number","description":"How long this result took to produce, in milliseconds.","example":45},"dataVintage":{"type":["string","null"],"description":"When the underlying data was collected, as an ISO 8601 date. Not present in every response.","example":"2024-01-01"},"lastUpdated":{"type":"string","description":"When the scores were last computed, as an ISO 8601 timestamp. Not present in every response.","example":"2024-01-15T10:30:00Z"},"periodsAvailable":{"type":"number","description":"Number of earlier periods held for this area. Not present in every response.","example":12}},"required":["processingTimeMs"],"description":"Timings and data dates for this result."}},"required":["geographicCode","metadata"],"description":"Connectivity scores for a single area.","example":{"geographicCode":"SW1A1AA","areaInfo":{"code":"SW1A1AA","name":"Westminster, Buckingham Palace","type":"postcode"},"connectivityScores":{"overall":87.5,"fixedBroadband":92.3,"mobileCoverage":82.7},"speedSummary":{"gigabitAvailable":true,"gigabitCoverage":87.5,"ultrafastCoverage":95.2,"superfastCoverage":98.5,"poorCoveragePercentage":1.5},"dataSources":{"fixed":{"method":"direct_calculation","sourceCode":"SW1A1AA"},"mobile":{"method":"spatial_aggregation","sourceCode":"E05009372"}},"metadata":{"processingTimeMs":45,"dataVintage":"2024-01-01","lastUpdated":"2024-01-15T10:30:00Z"}}},"description":"One entry per requested area."}},"required":["success","result"],"description":"Connectivity scores for the requested areas.","example":{"success":true,"result":[{"geographicCode":"SW1A1AA","areaInfo":{"code":"SW1A1AA","name":"Westminster, Buckingham Palace","type":"postcode"},"connectivityScores":{"overall":87.5,"fixedBroadband":92.3,"mobileCoverage":82.7},"speedSummary":{"gigabitAvailable":true,"gigabitCoverage":87.5,"ultrafastCoverage":95.2,"superfastCoverage":98.5,"poorCoveragePercentage":1.5},"metadata":{"processingTimeMs":45,"dataVintage":"2024-01-01","lastUpdated":"2024-01-15T10:30:00Z"}}]}}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}}}}},"/v1/area-reference/poi/nearest":{"get":{"operationId":"getNearestPOI","x-speakeasy-name-override":"getNearestPOI","tags":["POI"],"summary":"Find nearest points of interest","description":"Returns the points of interest closest to a location, nearest first, with the straight-line distance to each. Narrow the search with `types`, and add distances and times along roads and paths with `routing`.","parameters":[{"schema":{"type":"string","description":"Latitude of the centre of the search, in WGS84 decimal degrees. Must be between -90 and 90."},"required":true,"description":"Latitude of the centre of the search, in WGS84 decimal degrees. Must be between -90 and 90.","name":"lat","in":"query"},{"schema":{"type":"string","description":"Longitude of the centre of the search, in WGS84 decimal degrees. Must be between -180 and 180."},"required":true,"description":"Longitude of the centre of the search, in WGS84 decimal degrees. Must be between -180 and 180.","name":"lng","in":"query"},{"schema":{"type":"string","description":"Comma-separated categories to include, for example 'education,health,transport'. Every category is returned when omitted."},"required":false,"description":"Comma-separated categories to include, for example 'education,health,transport'. Every category is returned when omitted.","name":"types","in":"query"},{"schema":{"type":"string","default":"5000","description":"How far from that point to search, in metres. Defaults to 5000. Places further away are not returned."},"required":false,"description":"How far from that point to search, in metres. Defaults to 5000. Places further away are not returned.","name":"radius","in":"query"},{"schema":{"type":"string","default":"10","description":"Maximum number of places to return for each category. Defaults to 10. Results come back nearest first."},"required":false,"description":"Maximum number of places to return for each category. Defaults to 10. Results come back nearest first.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Set to `true` to add the distance and travel time along roads and paths for each place, in `routingDistance` and `routingDuration`. Working these out takes longer than the straight-line distance alone."},"required":false,"description":"Set to `true` to add the distance and travel time along roads and paths for each place, in `routingDistance` and `routingDuration`. Working these out takes longer than the straight-line distance alone.","name":"routing","in":"query"}],"responses":{"200":{"description":"Points of interest near the requested location, nearest first.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"True when the request succeeded.","example":true},"message":{"type":"string","description":"Human-readable note about the response. Not present in every response.","example":"Data retrieved successfully"},"result":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Identifier for the point of interest.","example":98765},"name":{"type":"string","description":"Name of the place.","example":"Westminster Abbey"},"categoryId":{"type":"string","description":"Code identifying the category the place belongs to, such as `education`. Pass it in `types` to filter a search.","example":"education"},"location":{"type":"object","properties":{"type":{"type":"string","enum":["Point"],"description":"Geometry type discriminator. Always `Point`."},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"Position of the place: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order).","example":[-0.1275,51.4995]}},"required":["type","coordinates"],"description":"Location of the place, as a GeoJSON Point."},"address":{"type":["string","null"],"description":"Street address of the place. Not present in every response.","example":"20 Deans Yd, Westminster, London SW1P 3PA"},"source":{"type":["string","null"],"description":"Name of the source the record came from, such as `OpenStreetMap`.","example":"OpenStreetMap"},"sourceId":{"type":["string","null"],"description":"Identifier for this place within that source.","example":"way/123456789"},"distance":{"type":"number","description":"Straight-line distance from the search point, in metres. Returned by the nearest points of interest search.","example":245.8},"routingDistance":{"type":"number","description":"Distance from the search point along roads and paths, in metres. Returned only when `routing` is true.","example":312.5},"routingDuration":{"type":"number","description":"Estimated travel time along that route, in seconds. Returned only when `routing` is true.","example":240}},"required":["id","name","categoryId","location"],"description":"A point of interest, such as a school, a hospital or a transport hub.","example":{"id":98765,"name":"Westminster Abbey","categoryId":"education","location":{"type":"Point","coordinates":[-0.1275,51.4995]},"address":"20 Deans Yd, Westminster, London SW1P 3PA","source":"OpenStreetMap","sourceId":"way/123456789","distance":245.8,"routingDistance":312.5,"routingDuration":240}},"description":"Points of interest within the search radius, nearest first."},"metadata":{"type":"object","properties":{"searchLocation":{"type":"object","properties":{"lat":{"type":"number","description":"Latitude the search was centred on."},"lng":{"type":"number","description":"Longitude the search was centred on."}},"required":["lat","lng"],"description":"The point the search was centred on."},"searchRadius":{"type":"number","description":"The radius that was applied, in metres."},"totalResults":{"type":"number","description":"Number of points of interest found within that radius."},"categories":{"type":"array","items":{"type":"string"},"description":"The categories the search covered. Not present in every response."},"routingEnabled":{"type":"boolean","description":"True when distances and times along roads and paths were calculated."}},"required":["searchLocation","searchRadius","totalResults"],"description":"The search that produced these results."}},"required":["success","result","metadata"]}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}}}}},"/v1/area-reference/poi/bounds/{z}/{x}/{y}":{"get":{"operationId":"getPOITile","x-speakeasy-name-override":"getPOITile","tags":["POI"],"summary":"Get points of interest in a map tile","description":"Returns the points of interest inside one slippy map tile, addressed by its zoom, column and row. With `format=geojson` the tile comes back as JSON holding a GeoJSON FeatureCollection; with `format=mvt` it comes back as a binary Mapbox Vector Tile.","parameters":[{"schema":{"type":"string","description":"Zoom level of the requested tile.","example":"14"},"required":true,"description":"Zoom level of the requested tile.","name":"z","in":"path"},{"schema":{"type":"string","description":"Tile column index at this zoom level.","example":"8192"},"required":true,"description":"Tile column index at this zoom level.","name":"x","in":"path"},{"schema":{"type":"string","description":"Tile row index at this zoom level.","example":"5461"},"required":true,"description":"Tile row index at this zoom level.","name":"y","in":"path"},{"schema":{"type":"string","enum":["geojson","mvt"],"default":"geojson","description":"Format to return the tile in. Defaults to `geojson`."},"required":false,"description":"Format to return the tile in. Defaults to `geojson`.","name":"format","in":"query"}],"responses":{"200":{"description":"The points of interest in the requested tile, as GeoJSON or as a Mapbox Vector Tile.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"True when the request succeeded.","example":true},"message":{"type":"string","description":"Human-readable note about the response. Not present in every response.","example":"Data retrieved successfully"},"result":{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"properties":{"type":"object","properties":{"id":{"type":"number","description":"Identifier for the point of interest."},"name":{"type":"string","description":"Name of the place."},"categoryId":{"type":"string","description":"Code identifying the category the place belongs to, such as `education`."},"category":{"type":"string","description":"Name of that category. Not present in every response."},"address":{"type":["string","null"],"description":"Street address of the place. Not present in every response."},"source":{"type":["string","null"],"description":"Name of the source the record came from, such as `OpenStreetMap`."}},"required":["id","name","categoryId"]},"geometry":{"type":"object","properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"Position of the place: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order)."}},"required":["type","coordinates"]}},"required":["type","properties","geometry"],"description":"One point of interest, as a GeoJSON Feature."},"description":"One Feature per point of interest in the tile."},"metadata":{"type":"object","properties":{"tile":{"type":"object","properties":{"z":{"type":"number","description":"Zoom level of the tile."},"x":{"type":"number","description":"Column of the tile at that zoom level."},"y":{"type":"number","description":"Row of the tile at that zoom level."}},"required":["z","x","y"],"description":"Which tile these features came from, as slippy map coordinates."},"count":{"type":"number","description":"Number of points of interest in the tile."},"generated":{"type":"string","description":"When the tile was generated, as an ISO 8601 timestamp."}},"required":["tile","count","generated"],"description":"Which tile this is and when it was built. Not present in every response."}},"required":["type","features"],"description":"The points of interest in one map tile, as a GeoJSON FeatureCollection."}},"required":["success","result"]}},"application/vnd.mapbox-vector-tile":{"schema":{}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}}}}},"/v1/area-reference/poi/tiles":{"get":{"operationId":"getPOIMultipleTiles","x-speakeasy-name-override":"getPOIMultipleTiles","tags":["POI"],"summary":"Get points of interest from several map tiles","description":"Returns the points of interest for several tiles in one request, given as comma-separated `z/x/y` coordinates. Each tile is reported separately, so a tile that cannot be produced carries its own error rather than failing the request.","parameters":[{"schema":{"type":"string","description":"Comma-separated tile coordinates in `z/x/y` form, for example '14/8192/5461,14/8193/5461'. Use it to fetch neighbouring tiles in one request."},"required":true,"description":"Comma-separated tile coordinates in `z/x/y` form, for example '14/8192/5461,14/8193/5461'. Use it to fetch neighbouring tiles in one request.","name":"tiles","in":"query"},{"schema":{"type":"string","enum":["geojson","mvt"],"default":"geojson","description":"Format to return each tile in. Defaults to `geojson`."},"required":false,"description":"Format to return each tile in. Defaults to `geojson`.","name":"format","in":"query"}],"responses":{"200":{"description":"The points of interest in each requested tile.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"True when the request succeeded.","example":true},"message":{"type":"string","description":"Human-readable note about the response. Not present in every response.","example":"Data retrieved successfully"},"result":{"type":"array","items":{"type":"object","properties":{"tile":{"type":"string","description":"Coordinates of the tile, in `z/x/y` form."},"data":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["FeatureCollection"]},"features":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["Feature"]},"properties":{"type":"object","properties":{"id":{"type":"number","description":"Identifier for the point of interest."},"name":{"type":"string","description":"Name of the place."},"categoryId":{"type":"string","description":"Code identifying the category the place belongs to, such as `education`."},"category":{"type":"string","description":"Name of that category. Not present in every response."},"address":{"type":["string","null"],"description":"Street address of the place. Not present in every response."},"source":{"type":["string","null"],"description":"Name of the source the record came from, such as `OpenStreetMap`."}},"required":["id","name","categoryId"]},"geometry":{"type":"object","properties":{"type":{"type":"string","enum":["Point"]},"coordinates":{"type":"array","prefixItems":[{"type":"number"},{"type":"number"}],"description":"Position of the place: longitude first, then latitude, in WGS84 decimal degrees (the GeoJSON order)."}},"required":["type","coordinates"]}},"required":["type","properties","geometry"],"description":"One point of interest, as a GeoJSON Feature."},"description":"One Feature per point of interest in the tile."},"metadata":{"type":"object","properties":{"tile":{"type":"object","properties":{"z":{"type":"number","description":"Zoom level of the tile."},"x":{"type":"number","description":"Column of the tile at that zoom level."},"y":{"type":"number","description":"Row of the tile at that zoom level."}},"required":["z","x","y"],"description":"Which tile these features came from, as slippy map coordinates."},"count":{"type":"number","description":"Number of points of interest in the tile."},"generated":{"type":"string","description":"When the tile was generated, as an ISO 8601 timestamp."}},"required":["tile","count","generated"],"description":"Which tile this is and when it was built. Not present in every response."}},"required":["type","features"],"description":"The points of interest in one map tile, as a GeoJSON FeatureCollection."},{"type":"object","properties":{"tile":{"type":"string","description":"The Mapbox Vector Tile, base64 encoded."},"layerName":{"type":"string","description":"Name of the layer inside the tile."}},"required":["tile","layerName"]}],"description":"The tile itself, in the requested format."},"error":{"type":"string","description":"Why this tile could not be returned. The other tiles in the request are unaffected."}},"required":["tile","data"]},"description":"One entry per requested tile."},"metadata":{"type":"object","properties":{"requestedTiles":{"type":"number","description":"Number of tiles requested."},"successfulTiles":{"type":"number","description":"Number of tiles returned successfully."},"failedTiles":{"type":"number","description":"Number of tiles that could not be returned, each with its own `error`."},"format":{"type":"string","enum":["geojson","mvt"],"description":"The format the tiles were returned in."}},"required":["requestedTiles","successfulTiles","failedTiles","format"],"description":"Counts across the whole request, and the format the tiles were returned in."}},"required":["success","result","metadata"]}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}}}}},"/v1/area-reference/metric-values":{"get":{"operationId":"getMetricValues","x-speakeasy-name-override":"getMetricValues","tags":["Metrics"],"summary":"Get metric values for geographic areas","description":"Returns published statistics for geographic areas, such as median house price, population density or a deprivation rank. At least one of `geographicEntityIds`, `metricIds` or `metricName` must be supplied.","parameters":[{"schema":{"type":"string","description":"Comma-separated area codes to return values for, for example 'E01000001,E01000002'."},"required":false,"description":"Comma-separated area codes to return values for, for example 'E01000001,E01000002'.","name":"geographicEntityIds","in":"query"},{"schema":{"type":"string","description":"Comma-separated metric identifiers to return, for example '1,5,12'."},"required":false,"description":"Comma-separated metric identifiers to return, for example '1,5,12'.","name":"metricIds","in":"query"},{"schema":{"type":"string","description":"Return only values for the metric with this exact name."},"required":false,"description":"Return only values for the metric with this exact name.","name":"metricName","in":"query"},{"schema":{"type":"string","description":"Comma-separated geography types to filter by, for example 'lsoa21,ward'."},"required":false,"description":"Comma-separated geography types to filter by, for example 'lsoa21,ward'.","name":"geographicEntityTypes","in":"query"},{"schema":{"type":["number","null"],"description":"Return values from this year onwards, including the year itself."},"required":false,"description":"Return values from this year onwards, including the year itself.","name":"startYear","in":"query"},{"schema":{"type":["number","null"],"description":"Return values up to this year, including the year itself."},"required":false,"description":"Return values up to this year, including the year itself.","name":"endYear","in":"query"},{"schema":{"type":["number","null"],"description":"Earliest month to return within the year range, numbered 1 to 12."},"required":false,"description":"Earliest month to return within the year range, numbered 1 to 12.","name":"startMonth","in":"query"},{"schema":{"type":["number","null"],"description":"Latest month to return within the year range, numbered 1 to 12."},"required":false,"description":"Latest month to return within the year range, numbered 1 to 12.","name":"endMonth","in":"query"},{"schema":{"type":"string","description":"Return only values for metrics in this category, for example 'housing'."},"required":false,"description":"Return only values for metrics in this category, for example 'housing'.","name":"category","in":"query"},{"schema":{"type":"string","description":"Set to `true` to include each metric's definition alongside its value."},"required":false,"description":"Set to `true` to include each metric's definition alongside its value.","name":"includeMetric","in":"query"},{"schema":{"type":"string","description":"Set to `true` to include the code, name and geography type of each area alongside its value."},"required":false,"description":"Set to `true` to include the code, name and geography type of each area alongside its value.","name":"includeGeographicEntity","in":"query"},{"schema":{"type":"string","default":"100","description":"Maximum number of values to return. Defaults to 100."},"required":false,"description":"Maximum number of values to return. Defaults to 100.","name":"limit","in":"query"},{"schema":{"type":"string","default":"0","description":"Number of values to skip before the first one returned. Defaults to 0."},"required":false,"description":"Number of values to skip before the first one returned. Defaults to 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"Metric values for the requested areas, with the paging counters for the query.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","description":"True when the request succeeded.","example":true},"message":{"type":"string","description":"Human-readable note about the response. Not present in every response.","example":"Data retrieved successfully"},"result":{"type":"array","items":{"type":"object","properties":{"id":{"type":"number","description":"Identifier for this observation."},"metricId":{"type":"number","description":"Identifier of the metric this value belongs to."},"geographicCode":{"type":"string","description":"Code of the area the value applies to, such as an LSOA or local authority code."},"geographicType":{"type":"string","enum":["postcode","outcode","uk_output_area","lsoa21","ward","parish","local_authority_district","county","country","county_electoral_division","district_borough_unitary","district_borough_unitary_ward","local_planning_authority","ceremonial_counties_region","english_region","country_region","unitary_electoral_division","province","electoral_division","greater_london_constituency","scotland_and_wales_constituency","scotland_and_wales_region","westminster_constituency","building","built_up_area_250","green_belt","common_land","parcels_gb","flood_risk","ramsar","natura_2000","aonb","area_natural_beauty","national_scenic_area","special_area_conservation","special_protection_area","ancient_woodland","native_woodland_survey","priority_habitats","protected_woodlands","protected_woodland","protected_scenic_landscapes","world_heritage_site","scheduled_monument","battlefield","protected_wreck_site","historic_landfill_site","radon_level","brownfield_land","noise_rail_lden","noise_road_lden","noise_industry_lden"],"example":"lsoa21","description":"Geography type of that area."},"value":{"type":"number","description":"The observed value. Read it with the metric's `unit` to know what it means."},"period":{"type":["string","null"],"description":"Period the value covers, for example '2024', '2024-Q3' or '2024-01'. Null when the metric is not tied to a period."},"confidence":{"type":["number","null"],"description":"How reliable the value is, from 0 to 1, where 1 is most reliable. Null when not applicable."},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Further detail about this observation, varying by publisher."},"createdAt":{"type":"string","description":"When this value first appeared in the API, as an ISO 8601 timestamp."},"updatedAt":{"type":["string","null"],"description":"When this value was last changed, as an ISO 8601 timestamp. Null when it has not changed since it first appeared."},"metric":{"type":"object","properties":{"id":{"type":"number","description":"Identifier for the metric. Pass it in `metricIds` to fetch values for this metric."},"name":{"type":"string","description":"Machine-readable name of the metric, for example 'median_house_price'."},"description":{"type":["string","null"],"description":"Human-readable explanation of what the metric measures."},"unit":{"type":["string","null"],"description":"Unit the values are expressed in, for example 'GBP', 'percent' or 'count'. Null when the metric has no unit."},"aggregationLevel":{"type":["string","null"],"enum":["national","regional","local_authority","ward","lsoa","output_area","postcode",null],"description":"Finest geography the metric is published for."},"frequency":{"type":["string","null"],"enum":["annual","quarterly","monthly","weekly","daily","one_time","irregular",null],"description":"How often the source publisher updates the metric."},"source":{"type":["string","null"],"description":"Organisation that publishes the metric, for example 'ONS'."},"category":{"type":["string","null"],"description":"Theme the metric belongs to, for example 'housing' or 'income'."},"tags":{"type":["array","null"],"items":{"type":"string"},"description":"Further labels on the metric, for example 'census_2021'."},"metadata":{"type":["object","null"],"additionalProperties":{},"description":"Further detail about the metric, varying by publisher."}},"required":["id","name","description","unit","aggregationLevel","frequency","source","category"],"description":"Definition of a statistic published for geographic areas."},"geography":{"type":"object","properties":{"code":{"type":"string"},"name":{"type":"string"},"type":{"type":"string","enum":["postcode","outcode","uk_output_area","lsoa21","ward","parish","local_authority_district","county","country","county_electoral_division","district_borough_unitary","district_borough_unitary_ward","local_planning_authority","ceremonial_counties_region","english_region","country_region","unitary_electoral_division","province","electoral_division","greater_london_constituency","scotland_and_wales_constituency","scotland_and_wales_region","westminster_constituency","building","built_up_area_250","green_belt","common_land","parcels_gb","flood_risk","ramsar","natura_2000","aonb","area_natural_beauty","national_scenic_area","special_area_conservation","special_protection_area","ancient_woodland","native_woodland_survey","priority_habitats","protected_woodlands","protected_woodland","protected_scenic_landscapes","world_heritage_site","scheduled_monument","battlefield","protected_wreck_site","historic_landfill_site","radon_level","brownfield_land","noise_rail_lden","noise_road_lden","noise_industry_lden"],"example":"lsoa21","description":"Which geography or layer the area belongs to. The values cover postcode units and their outward codes (the first part of a postcode, such as `SW1A`), statistical geographies from the census Output Area and Lower Layer Super Output Area (LSOA) upwards, electoral and parliamentary boundaries, buildings and land parcels, flood risk, environmental and heritage designations, and noise mapping."}},"required":["code","name","type"]}},"required":["id","metricId","geographicCode","geographicType","value","period","confidence","createdAt","updatedAt"]}},"pagination":{"type":"object","properties":{"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"},"hasMore":{"type":"boolean"}},"required":["total","limit","offset","hasMore"]}},"required":["success","result","pagination"]}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","enum":[false],"description":"Always `false` on an error response."},"error":{"type":"string","description":"Short statement of what went wrong.","example":"Invalid request parameters"},"details":{"type":"string","description":"Fuller explanation of the failure, naming the parameter at fault where one can be identified. Not present in every response.","example":"Latitude must be between -90 and 90"},"code":{"type":"string","description":"Machine-readable code for the failure.","example":"VALIDATION_ERROR"}},"required":["success","error"],"description":"Body returned when a request fails.","example":{"success":false,"error":"Invalid request parameters","details":"Latitude must be between -90 and 90","code":"VALIDATION_ERROR"}}}}}}}},"/v1/area-reference/health":{"get":{"operationId":"checkAreaReferenceHealth","x-speakeasy-name-override":"checkAreaReferenceHealth","tags":["System"],"summary":"Check area reference service health","description":"Reports whether the area reference endpoints are serving requests.","responses":{"200":{"description":"The service is reachable, with its status and the current server time.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"service":{"type":"string"},"timestamp":{"type":"string"}},"required":["status","service","timestamp"]}}}}}}},"/v1/address/resolve":{"post":{"operationId":"resolveAddress","x-speakeasy-name-override":"resolveAddress","tags":["Address"],"summary":"Resolve an address to UPRNs","description":"Resolves a free-text address to one or more Unique Property Reference Numbers, each with a confidence score and a recommended action. It copes with multi-unit addresses, house-number ranges, incomplete addresses and inconsistent formatting, and falls back to postcode-level matching when the primary match is weak or absent. Only residential addresses are matched by default; pass `classification: 'commercial'` for commercial premises or `classification: 'all'` for every address type.","requestBody":{"description":"The address to resolve, with optional matching settings.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressResolveRequest"}}}},"responses":{"200":{"description":"The matches found for the address, with confidence scores and a recommended action.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["address_resolution"],"description":"Always `address_resolution`."},"result":{"type":"object","properties":{"matches":{"type":"array","items":{"oneOf":[{"type":"object","properties":{"granularity":{"type":"string","enum":["address"],"description":"Always `address` on this branch: the match is a single premise rather than a whole street."},"precision":{"$ref":"#/components/schemas/GeocodePrecision"},"uprn":{"type":"string","description":"The Unique Property Reference Number (UPRN) of the matched premise."},"address":{"type":"string","description":"The matched address on one line."},"county":{"type":"string","description":"Ceremonial county for the matched premise's postcode, from OS Boundary-Line. Absent when it is not known: the match carried no postcode, the address is in Northern Ireland (which has no ceremonial county), or the geography service was unavailable. It is never part of `address`.","example":"Greater London"},"coordinates":{"type":"object","properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Position of the matched premise. Returned only when `options.includeCoordinates` is true, and absent on postcode-level fallback matches, which have no premise point.","title":"Coordinates"},"classificationCode":{"type":"string","description":"Ordnance Survey classification code for how the matched premise is used. Codes beginning `R` are residential and codes beginning `C` are commercial. Absent on postcode-level fallback matches.","example":"RD06"},"confidence":{"type":"number","description":"How confident this match is, from 0 to 100."},"source":{"type":"string","enum":["direct-match","exact-match","partial-match","fuzzy-match","index-lookup","postcode-fallback","spatial-narrative"],"description":"Which strategy produced this match. `direct-match` came from the address index. `postcode-fallback` means street-level matching found nothing and the premise was chosen from the postcode instead, so it, like `spatial-narrative`, is positioned approximately rather than on the building itself."},"originalAddress":{"type":"string","description":"The part of the submitted text this match was made from."},"hopperComponents":{"type":"object","properties":{"building":{"type":"number","minimum":0,"maximum":1,"description":"How well the building number, building name and organisation matched, from 0 to 1. A 1 is an exact match on all three."},"locality":{"type":"number","minimum":0,"maximum":1,"description":"How well the street, town and postcode matched, from 0 to 1. A 1 is an exact match on all three."},"unit":{"type":"number","minimum":0,"maximum":1,"description":"How well the flat, apartment or other sub-building identifier matched, from 0 to 1. A 1 is an exact match on the sub-building."}},"required":["building","locality","unit"],"description":"Component-by-component scores for the match, following the ONS Address Index Matching Service methodology. Read them to see which parts of the address matched well and which were uncertain."}},"required":["granularity","uprn","address","confidence","source","originalAddress"]},{"$ref":"#/components/schemas/StreetMatch"}]},"description":"The matches found, most confident first. Each is either a premise or a named street; read `granularity` on a match to tell which."},"confidence":{"type":"number","description":"Overall confidence in this result set, from 0 to 100."},"unambiguityScore":{"type":"number","description":"How far ahead the best match is: the gap between the top two confidence scores, from 0 to 100. The wider the gap, the clearer the winner."},"confidenceZone":{"type":"string","enum":["H","M","L"],"description":"Confidence band of the best match. `H` is above 70, strong enough to automate. `M` is 50 to 70, worth reviewing in a critical workflow. `L` is below 50, where a human should look."},"recommendationCode":{"type":"string","enum":["A","I"],"description":"Recommended handling for the best match. `A` means accept it without review: the confidence band and the lead over the runner-up are both good enough. `I` means intervene: the match is ambiguous or weak, so put the candidates in front of a user."},"attribution":{"type":"string","description":"The attribution that must be shown wherever the open-data street fields in this response are displayed. Present when at least one returned street carries open data.","example":"Contains OS data © Crown copyright and database right 2026."},"matchQuality":{"type":"object","properties":{"grade":{"type":"string","enum":["A","B","C","D","F"],"description":"How good the match is, from `A` down to `F`. `A` and `B` are reliable enough to accept without review, `C` and `D` are put forward for review, and `F` is not usable. Read `action` for the recommendation that follows from the grade."},"action":{"type":"string","enum":["accept","review","reject"],"description":"What to do with this match, given its quality."},"isReliable":{"type":"boolean","description":"True when the match is strong enough to use without human review."},"reason":{"type":"string","description":"Human-readable explanation of the quality assessment."},"unambiguityScore":{"type":"number","description":"Gap between the top two confidence scores, from 0 to 100. It is 100 when there was only one candidate."},"factors":{"type":"object","properties":{"isSingleResult":{"type":"boolean","description":"True when only one candidate was found."},"hasPerfectBuildingMatch":{"type":"boolean","description":"True when the building component scored a perfect 1."},"hasClearWinner":{"type":"boolean","description":"True when the best match leads the runner-up by at least 15 points."},"hasHighConfidence":{"type":"boolean","description":"True when the best match scores 85 or above."}},"required":["isSingleResult","hasPerfectBuildingMatch","hasClearWinner","hasHighConfidence"],"description":"The individual signals behind the grade, so a caller can apply its own policy."}},"required":["grade","action","isReliable","reason","unambiguityScore","factors"],"description":"How good the best match is, weighing its component scores, its lead and its confidence."},"metadata":{"type":"object","properties":{"addressCount":{"type":"number","description":"How many addresses were parsed out of the submitted text."},"executionTimeMs":{"type":"number","description":"How long the whole resolution took, in milliseconds."},"pattern":{"type":"string","enum":["single","range","multiple","descriptive","complex","narrative"],"description":"What shape the submitted address was read as."},"processingSteps":{"type":"array","items":{"type":"object","properties":{"step":{"type":"string","description":"Name of the stage."},"status":{"type":"string","enum":["success","failed","skipped"],"description":"How the stage ended."},"confidence":{"type":"number","description":"Confidence this stage reached, from 0 to 100."},"executionTimeMs":{"type":"number","description":"How long this stage took, in milliseconds."},"details":{"type":"string","description":"Extra detail about what this stage found."}},"required":["step","status","confidence","executionTimeMs"]},"description":"What each stage of the match did. Returned when `includeProcessingDetails` is set."}},"required":["addressCount","executionTimeMs","pattern"],"description":"How the submitted text was parsed and how long the match took."}},"required":["matches","confidence","metadata"],"description":"The matches and how they were arrived at. Present when the resolution succeeded."},"error":{"type":"string","description":"What went wrong. Present only when the resolution failed."},"statusCode":{"type":"number","description":"HTTP status code for the failure, when one is reported."}}}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/address/postcodes/{postcode}":{"get":{"operationId":"lookupPostcode","x-speakeasy-name-override":"lookupPostcode","tags":["Address"],"summary":"Look up addresses by postcode","description":"Returns every address at a UK postcode, ordered by house number. Page through them with `limit` and `offset`, and add the administrative and statistical geography for the postcode with `include=geography`.","parameters":[{"schema":{"type":"string","description":"The postcode to look up. Case and spacing are ignored.","example":"SW1A2AA"},"required":true,"description":"The postcode to look up. Case and spacing are ignored.","name":"postcode","in":"path"},{"schema":{"type":"string","description":"Maximum number of addresses to return. Defaults to 50. Minimum 1, maximum 100.","example":"50"},"required":false,"description":"Maximum number of addresses to return. Defaults to 50. Minimum 1, maximum 100.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Number of addresses to skip before the first one returned. Defaults to 0.","example":"0"},"required":false,"description":"Number of addresses to skip before the first one returned. Defaults to 0.","name":"offset","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of extras to return. `geography` adds the administrative and statistical areas for the postcode.","example":"geography"},"required":false,"description":"Comma-separated list of extras to return. `geography` adds the administrative and statistical areas for the postcode.","name":"include","in":"query"},{"schema":{"type":"string","enum":["os","paf"],"default":"os","description":"Which address dataset to read: 'os' for the Ordnance Survey address model, or 'paf' for the Royal Mail Postcode Address File. Defaults to 'os'."},"required":false,"description":"Which address dataset to read: 'os' for the Ordnance Survey address model, or 'paf' for the Royal Mail Postcode Address File. Defaults to 'os'.","name":"dataset","in":"query"}],"responses":{"200":{"description":"The addresses at this postcode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostcodeLookupResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/address/postcodes/bulk":{"post":{"operationId":"bulkLookupPostcodes","x-speakeasy-name-override":"bulkLookupPostcodes","tags":["Address"],"summary":"Look up many postcodes at once","description":"Looks up addresses for up to 100 postcodes in one request. Results come back keyed by formatted postcode, each carrying its own status, so a postcode that cannot be resolved does not fail the rest of the batch.","requestBody":{"description":"The postcodes to look up, and how many addresses to return for each.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkPostcodeLookupRequest"}}}},"responses":{"200":{"description":"One result per postcode, keyed by the formatted postcode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BulkPostcodeLookupResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/address/postcodes/{postcode}/validate":{"get":{"operationId":"validatePostcode","x-speakeasy-name-override":"validatePostcode","tags":["Address"],"summary":"Validate a UK postcode","description":"Checks whether a UK postcode exists and is in use. The answer is always a 200 response: read the `valid` field for it. A valid postcode also returns its centroid and its statistical area codes.","parameters":[{"schema":{"type":"string","description":"The postcode to validate. Case and spacing are ignored.","example":"SW1A2AA"},"required":true,"description":"The postcode to validate. Case and spacing are ignored.","name":"postcode","in":"path"}],"responses":{"200":{"description":"The validation result. A postcode that does not exist is still a 200, with `valid` set false.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostcodeValidationResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/address/postcodes/{postcode}/nearest":{"get":{"operationId":"getNearestPostcodes","x-speakeasy-name-override":"getNearestPostcodes","tags":["Address"],"summary":"Find nearest postcodes","description":"Returns the postcodes closest to a given postcode's centroid, nearest first, with the distance to each in metres.","parameters":[{"schema":{"type":"string","description":"The postcode to measure from.","example":"SW1A2AA"},"required":true,"description":"The postcode to measure from.","name":"postcode","in":"path"},{"schema":{"type":"string","description":"How far to search, in metres. Defaults to 2000. Minimum 100, maximum 10000.","example":"2000"},"required":false,"description":"How far to search, in metres. Defaults to 2000. Minimum 100, maximum 10000.","name":"radius","in":"query"},{"schema":{"type":"string","description":"Maximum number of postcodes to return. Defaults to 10. Maximum 20.","example":"10"},"required":false,"description":"Maximum number of postcodes to return. Defaults to 10. Maximum 20.","name":"limit","in":"query"}],"responses":{"200":{"description":"The nearby postcodes, nearest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NearestPostcodesResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier, or it has no coordinates to measure from.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/address/reverse":{"get":{"operationId":"reverseGeocode","x-speakeasy-name-override":"reverseGeocode","tags":["Address"],"summary":"Find addresses near a coordinate","description":"Returns the addresses closest to a coordinate, nearest first, with the distance to each in metres. Both `lat` and `lng` are required.","parameters":[{"schema":{"type":"string","description":"Latitude of the point to search from, in WGS84 decimal degrees.","example":"51.5034"},"required":true,"description":"Latitude of the point to search from, in WGS84 decimal degrees.","name":"lat","in":"query"},{"schema":{"type":"string","description":"Longitude of the point to search from, in WGS84 decimal degrees.","example":"-0.1276"},"required":true,"description":"Longitude of the point to search from, in WGS84 decimal degrees.","name":"lng","in":"query"},{"schema":{"type":"string","description":"How far to search, in metres. Defaults to 50. Minimum 10, maximum 1000.","example":"50"},"required":false,"description":"How far to search, in metres. Defaults to 50. Minimum 10, maximum 1000.","name":"radius","in":"query"},{"schema":{"type":"string","description":"Maximum number of addresses to return. Defaults to 5. Maximum 20.","example":"5"},"required":false,"description":"Maximum number of addresses to return. Defaults to 5. Maximum 20.","name":"limit","in":"query"},{"schema":{"type":"string","enum":["os","paf"],"default":"os","description":"Which address dataset to read: 'os' for the Ordnance Survey address model, or 'paf' for the Royal Mail Postcode Address File. Defaults to 'os'."},"required":false,"description":"Which address dataset to read: 'os' for the Ordnance Survey address model, or 'paf' for the Royal Mail Postcode Address File. Defaults to 'os'.","name":"dataset","in":"query"}],"responses":{"200":{"description":"The addresses near the point, nearest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReverseGeocodeResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/address/outcodes/{outcode}":{"get":{"operationId":"lookupOutcode","x-speakeasy-name-override":"lookupOutcode","tags":["Address"],"summary":"Look up an outward code","description":"Returns what is known about an outward code, the first part of a postcode such as `SW1A`, `E1` or `M1`: a representative point, the country, region and local authority it sits in, and how many postcodes it holds. Add `include=postcodes` for the postcodes themselves.","parameters":[{"schema":{"type":"string","description":"The outward code, the first part of a postcode, such as `SW1A`.","example":"SW1A"},"required":true,"description":"The outward code, the first part of a postcode, such as `SW1A`.","name":"outcode","in":"path"},{"schema":{"type":"string","description":"Comma-separated list of extras to return. `postcodes` adds the postcodes in this outward code.","example":"postcodes"},"required":false,"description":"Comma-separated list of extras to return. `postcodes` adds the postcodes in this outward code.","name":"include","in":"query"}],"responses":{"200":{"description":"What is known about this outward code.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OutcodeLookupResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/address/uprn/{uprn}":{"get":{"operationId":"lookupUprn","x-speakeasy-name-override":"lookupUprn","tags":["Address"],"summary":"Look up an address by UPRN","description":"Returns the single address held for a Unique Property Reference Number, with its postal form alongside when the UPRN has a Royal Mail delivery point. Add `include=geography` for the administrative and statistical areas the address falls in.","parameters":[{"schema":{"type":"string","description":"The Unique Property Reference Number (UPRN) to look up. Between 1 and 12 digits.","example":"100023336956"},"required":true,"description":"The Unique Property Reference Number (UPRN) to look up. Between 1 and 12 digits.","name":"uprn","in":"path"},{"schema":{"type":"string","description":"Comma-separated list of extras to return. `geography` adds the administrative and statistical areas for the address's postcode.","example":"geography"},"required":false,"description":"Comma-separated list of extras to return. `geography` adds the administrative and statistical areas for the address's postcode.","name":"include","in":"query"},{"schema":{"type":"string","enum":["os","paf"],"default":"os","description":"Which address dataset to read: 'os' for the Ordnance Survey address model, or 'paf' for the Royal Mail Postcode Address File. Defaults to 'os'."},"required":false,"description":"Which address dataset to read: 'os' for the Ordnance Survey address model, or 'paf' for the Royal Mail Postcode Address File. Defaults to 'os'.","name":"dataset","in":"query"}],"responses":{"200":{"description":"The address held for this UPRN.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UprnLookupResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/address/cleanse":{"post":{"operationId":"cleanseAddresses","x-speakeasy-name-override":"cleanseAddresses","tags":["Address"],"summary":"Cleanse and verify addresses in bulk","description":"Matches up to 25 raw address strings against the national address register and returns the cleansed address for each, with a confidence score, a quality grade and the fields that changed. Use it to tidy an existing address list before loading it.","requestBody":{"description":"The address strings to cleanse.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressCleanseRequest"}}}},"responses":{"200":{"description":"One cleansed result per submitted address, with a count of the recommended actions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AddressCleanseResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/address/changelog":{"get":{"operationId":"listAddressChangelog","x-speakeasy-group":"Address.Changelog","x-speakeasy-name-override":"list","tags":["Address"],"summary":"List Address API changelog entries","description":"An append-only record of every shape change to the Address API, so an integration can watch for changes instead of discovering them. Each entry carries a dated `objectVersion`, the kind of change (`additive`, `deprecation`, `removal` or `fix`), the shapes or endpoints it affects, and, for a deprecation, the sunset date that matches the `Sunset` header on the endpoint being retired. Responses are cached for an hour, so this is cheap to poll.","responses":{"200":{"description":"The changelog entries, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangelogListResponse"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/avm/predict":{"post":{"operationId":"predictPropertyValue","x-speakeasy-name-override":"predictPropertyValue","tags":["AVM"],"summary":"Predict property value","description":"Estimate what a property is worth from its characteristics and location. Supply either a postcode or a latitude and longitude pair. The response carries the estimate, the bounds either side of it and, when `ratePrice` is set alongside an `inputPrice`, a rating of that price against the estimate.","requestBody":{"description":"The property's characteristics and its location.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AVMPredictRequest"}}}},"responses":{"200":{"description":"The estimated value, with the bounds either side of it and the metadata behind it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AVMPredictResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"422":{"description":"The request was understood but the property could not be valued: the location could not be resolved, or there is too little evidence to value it.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/avm/predict-by-location":{"post":{"operationId":"predictPropertyValueByLocation","x-speakeasy-name-override":"predictPropertyValueByLocation","tags":["AVM"],"summary":"Predict property value by location ID","description":"Estimate what a property is worth from its location ID. The details held for that location are fetched and valued, so no characteristics need to be supplied. Any characteristic sent on the request replaces the stored value, which is how to test what a different bedroom count or floor area does to the estimate.","requestBody":{"description":"The location ID, with any characteristics to override.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AVMPredictByLocationRequest"}}}},"responses":{"200":{"description":"The estimated value, with the bounds either side of it and the metadata behind it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AVMPredictResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"422":{"description":"The request was understood but the property could not be valued: details it needs are missing, or there is too little evidence to value it.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/avm/analysis":{"post":{"operationId":"getValuationAnalysis","x-speakeasy-name-override":"getValuationAnalysis","tags":["AVM"],"summary":"Get detailed valuation analysis","description":"Value a property and return the evidence behind the figure: every comparable property with the tier it was placed in, market statistics across those comparables, a confidence breakdown, and up to 24 months of past valuations. Reach for this when the estimate on its own is not enough and the workings matter.","requestBody":{"description":"The location ID and how much history to include.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AVMAnalysisRequest"}}}},"responses":{"200":{"description":"The valuation, with its comparables, market statistics, confidence breakdown and history.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AVMAnalysisResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"422":{"description":"The request was understood but the property could not be analysed: details it needs are missing, or there is too little evidence to value it.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/avm/health":{"get":{"operationId":"checkAVMHealth","x-speakeasy-name-override":"checkAVMHealth","tags":["System"],"summary":"AVM service health check","description":"Check whether the valuation service is operating.","responses":{"200":{"description":"The service is operating, with its name and the time the check ran.","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"service":{"type":"string","example":"avm"},"timestamp":{"type":"string","example":"2024-01-01T00:00:00.000Z"}},"required":["status","service","timestamp"]}}}}}}},"/v1/search/suggest":{"get":{"operationId":"searchSuggest","x-speakeasy-name-override":"searchSuggest","tags":["Search"],"summary":"Autocomplete UK addresses and locations","description":"Type-ahead search over UK addresses and locations, with fuzzy matching. It works out for itself whether the query is a postcode, an address or a place name, and returns suggestions in one list. Supplying a centre point (`lat` and `lng`) makes address results proximity-aware: `geo_mode=bias`, the default, is a soft preference that ranks nearby matches higher while still returning distant ones, and `geo_mode=restrict` is a hard cutoff that returns only results within `radius_meters` of the point. Proximity therefore changes the order of address results under `bias` and which ones appear at all under `restrict`; pair it with `source=address` for the most predictable behaviour. Suggestions are a discovery view: an address row carries its label, its UPRN and the match highlights, and never coordinates, distance or classification. Look the chosen UPRN up with `GET /v1/address/uprn/{uprn}` for the full record. Once a query narrows to a small exact match set the response also carries a `search_id`. Send it back on the next keystroke to narrow within that set rather than fetching again, and when `set_complete` is true the response already holds every match, so further narrowing can happen in the client. Suggest responses are not charged per request: each search session settles one small flat charge, and full-record lookups are charged by the address endpoints.","parameters":[{"schema":{"type":"string","minLength":1,"description":"What to search for: a postcode, an address, a place name, or the beginning of any of them.","example":"SW1A 1AA"},"required":true,"description":"What to search for: a postcode, an address, a place name, or the beginning of any of them.","name":"q","in":"query"},{"schema":{"type":"string","description":"Return results from this source only: 'address' for individual premises, 'location' for postcodes, places and towns. Omit to search both.","example":"address"},"required":false,"description":"Return results from this source only: 'address' for individual premises, 'location' for postcodes, places and towns. Omit to search both.","name":"source","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Maximum number of results to return. Defaults to 10. Values above 100 are capped at 100.","example":"10"},"required":false,"description":"Maximum number of results to return. Defaults to 10. Values above 100 are capped at 100.","name":"limit","in":"query"},{"schema":{"type":"string","pattern":"^\\d+$","description":"Number of results to skip before the first one returned. Defaults to 0. Capped at 10000.","example":"0"},"required":false,"description":"Number of results to skip before the first one returned. Defaults to 0. Capped at 10000.","name":"offset","in":"query"},{"schema":{"type":"string","enum":["residential","commercial","all"],"description":"Filter address results by how the property is used. 'residential' covers dwellings, including houses, flats and houses in multiple occupation. 'commercial' covers non-residential premises such as offices, retail and warehouses. 'all' applies no filter. Defaults to 'residential'.","example":"residential"},"required":false,"description":"Filter address results by how the property is used. 'residential' covers dwellings, including houses, flats and houses in multiple occupation. 'commercial' covers non-residential premises such as offices, retail and warehouses. 'all' applies no filter. Defaults to 'residential'.","name":"classification","in":"query"},{"schema":{"type":"string","description":"Restrict address results to current, addressable properties. When 'true', superseded and historical address records are left out, so every result resolves to a live property record. Defaults to 'false', which includes those historical entries. Applies to address results only.","enum":["true","false"],"example":"true"},"required":false,"description":"Restrict address results to current, addressable properties. When 'true', superseded and historical address records are left out, so every result resolves to a live property record. Defaults to 'false', which includes those historical entries. Applies to address results only.","name":"addressable_only","in":"query"},{"schema":{"type":"number","description":"Latitude of a centre point to search around, in WGS84 decimal degrees, from -90 to 90. Must be supplied together with `lng`. Supplying both makes address results proximity-aware, which is most predictable alongside `source=address`.","minimum":-90,"maximum":90,"example":51.5074},"required":false,"description":"Latitude of a centre point to search around, in WGS84 decimal degrees, from -90 to 90. Must be supplied together with `lng`. Supplying both makes address results proximity-aware, which is most predictable alongside `source=address`.","name":"lat","in":"query"},{"schema":{"type":"number","description":"Longitude of a centre point to search around, in WGS84 decimal degrees, from -180 to 180. Must be supplied together with `lat`.","minimum":-180,"maximum":180,"example":-0.1278},"required":false,"description":"Longitude of a centre point to search around, in WGS84 decimal degrees, from -180 to 180. Must be supplied together with `lat`.","name":"lng","in":"query"},{"schema":{"type":"integer","description":"How far from (`lat`, `lng`) to search, in metres. Minimum 1, maximum 200000. Required when `geo_mode=restrict`, where anything outside it is excluded. Under `geo_mode=bias` it sets how strong the preference is: it is the distance at which a result's text score is roughly halved, and defaults to 10000 metres when omitted.","minimum":1,"maximum":200000,"example":5000},"required":false,"description":"How far from (`lat`, `lng`) to search, in metres. Minimum 1, maximum 200000. Required when `geo_mode=restrict`, where anything outside it is excluded. Under `geo_mode=bias` it sets how strong the preference is: it is the distance at which a result's text score is roughly halved, and defaults to 10000 metres when omitted.","name":"radius_meters","in":"query"},{"schema":{"type":"string","description":"How the centre point shapes results, applied only when `lat` and `lng` are both supplied. 'bias', the default, is a soft preference: the best text matches are still returned, but results near the point rank higher. 'restrict' is a hard cutoff: only results within `radius_meters` of the point are returned, and `radius_meters` becomes required. Applies to address results.","enum":["bias","restrict"],"example":"bias"},"required":false,"description":"How the centre point shapes results, applied only when `lat` and `lng` are both supplied. 'bias', the default, is a soft preference: the best text matches are still returned, but results near the point rank higher. 'restrict' is a hard cutoff: only results within `radius_meters` of the point are returned, and `radius_meters` becomes required. Applies to address results.","name":"geo_mode","in":"query"},{"schema":{"type":"string","description":"The `search_id` from an earlier suggest response. While it is still valid the query narrows within the candidate set already fetched for it, so no new data is read. An unknown or expired value falls back to a normal search.","format":"uuid","example":"3f8a2c1e-9b7d-4e6f-8a2c-1e9b7d4e6f8a"},"required":false,"description":"The `search_id` from an earlier suggest response. While it is still valid the query narrows within the candidate set already fetched for it, so no new data is read. An unknown or expired value falls back to a normal search.","name":"search_id","in":"query"},{"schema":{"type":"string","description":"How specific the results should be. 'address', the default, returns premise-level suggestions. 'street' returns one result per named street with a representative centre point, for partial locations such as 'West Street, Sheffield'. Streets that share a name are told apart by the town in the query and, when supplied, by `lat`, `lng`, `radius_meters` and `geo_mode`.","enum":["address","street"],"example":"street"},"required":false,"description":"How specific the results should be. 'address', the default, returns premise-level suggestions. 'street' returns one result per named street with a representative centre point, for partial locations such as 'West Street, Sheffield'. Streets that share a name are told apart by the town in the query and, when supplied, by `lat`, `lng`, `radius_meters` and `geo_mode`.","name":"granularity","in":"query"},{"schema":{"type":"string","description":"Which street dataset street results are read from, with `granularity=street` only. 'open' reads Ordnance Survey open data published under the Open Government Licence. 'ngd' reads the Ordnance Survey National Geographic Database (NGD). 'open_then_ngd' reads the open data first and turns to the NGD only when the open data matches no street. Defaults to 'open_then_ngd'. Rejected with any other granularity.","example":"open_then_ngd","enum":["open","ngd","open_then_ngd"]},"required":false,"description":"Which street dataset street results are read from, with `granularity=street` only. 'open' reads Ordnance Survey open data published under the Open Government Licence. 'ngd' reads the Ordnance Survey National Geographic Database (NGD). 'open_then_ngd' reads the open data first and turns to the NGD only when the open data matches no street. Defaults to 'open_then_ngd'. Rejected with any other granularity.","name":"dataset","in":"query"}],"responses":{"200":{"description":"Suggestions matching the query.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"},"example":{"success":true,"results":[{"id":"loc-sw1a1aa","title":"SW1A 1AA","description":"Westminster, London","type":"postcode","score":0.95,"relevanceScore":0.95,"source":"location","metadata":{"postcode":"SW1A 1AA","town":"London","locality":"Westminster"}},{"id":"addr-100023336956","title":"10 Downing Street, London, SW1A 2AA","main_text":"10 Downing Street, London, SW1A 2AA","type":"address","source":"address","score":0.92,"relevanceScore":0.92,"uprn":"100023336956","matched_substrings":[{"offset":0,"length":2}],"main_text_matched_substrings":[{"offset":0,"length":2}]}],"totalResults":15,"size":2,"hasMore":true,"nextOffset":10,"search_id":null,"set_complete":false,"metadata":{"processingTime":"45ms"}}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/search/health":{"get":{"operationId":"checkSearchHealth","x-speakeasy-name-override":"checkSearchHealth","tags":["System"],"summary":"Check search service health","description":"Reports whether the search service is running. Use it as a liveness check.","responses":{"200":{"description":"The service is running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/councils":{"get":{"operationId":"listCouncils","x-speakeasy-name-override":"list","tags":["Councils"],"summary":"List councils","description":"Returns the councils and local authorities of Great Britain and Ireland, with their contact details, service links and administrative codes. Narrow the list by country, status or type. Only active councils are returned unless `status` says otherwise, and the whole list comes back in one response.","parameters":[{"schema":{"type":"string","enum":["GB","IE"],"description":"Return only councils in this country: `GB` for Great Britain, `IE` for Ireland.","example":"GB"},"required":false,"description":"Return only councils in this country: `GB` for Great Britain, `IE` for Ireland.","name":"country","in":"query"},{"schema":{"type":"string","enum":["active","merged","abolished","inactive"],"description":"Return only councils with this status. When omitted, only active councils are returned.","example":"active"},"required":false,"description":"Return only councils with this status. When omitted, only active councils are returned.","name":"status","in":"query"},{"schema":{"type":"string","enum":["unitary","metropolitan","county","london_borough","district","local_authority"],"description":"Return only councils of this type.","example":"metropolitan"},"required":false,"description":"Return only councils of this type.","name":"type","in":"query"}],"responses":{"200":{"description":"The councils matching the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CouncilListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CouncilErrorResponse"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CouncilErrorResponse"}}}}}}},"/v1/councils/{providerId}":{"get":{"operationId":"getCouncilByProviderId","x-speakeasy-name-override":"get","tags":["Councils"],"summary":"Get council by provider ID","description":"Returns one council by its provider code, with its contact details, service links and administrative codes. Councils of any status are returned here, so check `status` before treating one as current.","parameters":[{"schema":{"type":"string","description":"Stable code identifying the council, as returned in a council's `providerId`.","example":"manchester-city"},"required":true,"description":"Stable code identifying the council, as returned in a council's `providerId`.","name":"providerId","in":"path"}],"responses":{"200":{"description":"The requested council.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Council"}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CouncilErrorResponse"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CouncilErrorResponse"}}}}}}},"/v1/sites/query":{"post":{"operationId":"searchSites","x-speakeasy-name-override":"search","tags":["Sites"],"summary":"Search sites","description":"Search registered titles by their attributes, by geographic area, or by both, with sorting and pagination. Area filters accept a polygon, a multi-polygon, a point with a radius, a point the boundary must enclose, or a bounding box; a site matches the area clause if it satisfies any one of the filters supplied, and that has to hold on top of `filters` and `query`. The `boundary` geometry is left out by default because of its size, so pass `attributes: [\"boundary\"]` to get site polygons back. Up to 1000 sites come back per request, from an offset of at most 100000.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteQueryRequest"}}}},"responses":{"200":{"description":"One page of sites matching the search.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/sites/aggregate":{"post":{"operationId":"aggregateSites","x-speakeasy-name-override":"aggregate","tags":["Sites"],"summary":"Aggregate sites","description":"Summarise sites in bulk rather than listing them: counts by tenure, area statistics, distributions over time, map-tile groupings, and so on. The same filters and geographic areas as the search endpoint decide which sites are counted. There are 14 aggregation types, and a request may carry up to 10 aggregations, each nested up to two levels deep. Results come back keyed by the `name` given in each definition, so pick names that are unique within the request.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteAggregateRequest"}}}},"responses":{"200":{"description":"The aggregation results, with the total number of sites they were computed over.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteAggregateResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/sites/by-ids":{"post":{"operationId":"findSitesByIds","x-speakeasy-name-override":"findByIds","tags":["Sites"],"summary":"Batch lookup sites by IDs","description":"Retrieve up to 100 sites by identifier in a single request, choosing which fields come back with `attributes`. Identifiers that match nothing are left out of the response rather than raising an error, so compare `total_count` against the number of identifiers sent to spot the ones that were not found.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteBatchIdsRequest"}}}},"responses":{"200":{"description":"The sites that matched the identifiers supplied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/sites/by-property/{locationId}":{"get":{"operationId":"findSitesByProperty","x-speakeasy-name-override":"findByProperty","tags":["Sites"],"summary":"Find sites by property","description":"Find the registered titles that cover a single addressable location. One location often sits under several titles at once, so a flat in a freehold block matches both its leasehold title and the freehold above it. Up to 50 sites come back, and a location with no titles returns an empty list rather than a 404.","parameters":[{"schema":{"type":"string","example":"100023336956","description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN)."},"required":true,"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN).","name":"locationId","in":"path"}],"responses":{"200":{"description":"The sites covering that location.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteListResponse"}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/sites/by-point":{"get":{"operationId":"findSitesByPoint","x-speakeasy-name-override":"findByPoint","tags":["Sites"],"summary":"Find sites by point","description":"Find every registered title whose boundary encloses a single coordinate, given as latitude and longitude in WGS84 decimal degrees. Overlapping titles at one spot are common, such as a freehold and a leasehold over the same building. Up to 50 sites come back, and a point inside no title returns an empty list rather than a 404.","parameters":[{"schema":{"type":["number","null"],"minimum":-90,"maximum":90,"description":"Latitude of the point, in WGS84 decimal degrees.","example":51.5074},"required":false,"description":"Latitude of the point, in WGS84 decimal degrees.","name":"lat","in":"query"},{"schema":{"type":["number","null"],"minimum":-180,"maximum":180,"description":"Longitude of the point, in WGS84 decimal degrees.","example":-0.1278},"required":false,"description":"Longitude of the point, in WGS84 decimal degrees.","name":"lon","in":"query"}],"responses":{"200":{"description":"The sites whose boundary encloses the point.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SiteListResponse"}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/sites/properties/{siteId}":{"get":{"operationId":"getPropertiesInSite","x-speakeasy-name-override":"getProperties","tags":["Sites"],"summary":"Get properties in site","description":"List the addressable locations that fall within one registered title, matched against the Ordnance Survey AddressBase dataset. The response carries the identifiers and how many there are; pass them to the Property API to fetch the full property records.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Identifier for a single registered title, made up of the country, the registry and the title number joined by colons.","example":"GB:LR:AGL123456"},"required":true,"description":"Identifier for a single registered title, made up of the country, the registry and the title number joined by colons.","name":"siteId","in":"path"}],"responses":{"200":{"description":"The location identifiers linked to the site.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SitePropertiesResponse"}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/sites/tiles/{z}/{x}/{y}":{"get":{"operationId":"getSiteTiles","x-speakeasy-name-override":"getTiles","tags":["Sites"],"summary":"Get site boundary tiles","description":"Draw title boundaries on a map. Each tile comes back as a Mapbox Vector Tile (`application/x-protobuf`) carrying the real boundary polygons, not simplified shapes or clustered points, ready for MapLibre GL JS, Mapbox GL JS or any renderer that reads vector tiles. Tiles are served from zoom 12 upwards; below that the polygons are too small and too densely packed to draw usefully, and the request fails. A tile carries at most 10,000 features, and the same filter, query and area parameters as the search endpoint narrow what it holds. Responses carry `Cache-Control: public, max-age=30, s-maxage=60`, so a shared cache or CDN can serve repeat views.","parameters":[{"schema":{"type":"string","description":"Zoom level of the requested tile.","example":"14"},"required":true,"description":"Zoom level of the requested tile.","name":"z","in":"path"},{"schema":{"type":"string","description":"Tile column index at this zoom level.","example":"8192"},"required":true,"description":"Tile column index at this zoom level.","name":"x","in":"path"},{"schema":{"type":"string","description":"Tile row index at this zoom level.","example":"5461"},"required":true,"description":"Tile row index at this zoom level.","name":"y","in":"path"},{"schema":{"type":"string","description":"Convenience filters to apply, as a JSON-encoded `SiteFilters` object.","example":"{\"tenureType\":[\"freehold\"],\"status\":[\"active\"]}"},"required":false,"description":"Convenience filters to apply, as a JSON-encoded `SiteFilters` object.","name":"filters","in":"query"},{"schema":{"type":"string","description":"Query operators to apply, as a JSON-encoded array of `SiteQueryOperator`.","example":"[{\"operator\":\"AND\",\"groups\":[{\"conditions\":[{\"field\":\"areaSqm\",\"comparator\":\"gte\",\"value\":500}]}]}]"},"required":false,"description":"Query operators to apply, as a JSON-encoded array of `SiteQueryOperator`.","name":"query","in":"query"},{"schema":{"type":"string","description":"Geographic area filters to apply, as a JSON-encoded array of `SiteAreaFilter`.","example":"[{\"type\":\"boundingBox\",\"topLeft\":{\"lat\":51.52,\"lon\":-0.13},\"bottomRight\":{\"lat\":51.50,\"lon\":-0.10}}]"},"required":false,"description":"Geographic area filters to apply, as a JSON-encoded array of `SiteAreaFilter`.","name":"area","in":"query"},{"schema":{"type":"string","description":"Site fields to carry on each tile feature, as one comma-separated string. Defaults to `siteId`, `titleRef`, `tenureType`, `status`, `areaSqm`, `locationCount` and `areaMetrics.prosperityDecile`.","example":"siteId,titleRef,tenureType,areaSqm"},"required":false,"description":"Site fields to carry on each tile feature, as one comma-separated string. Defaults to `siteId`, `titleRef`, `tenureType`, `status`, `areaSqm`, `locationCount` and `areaMetrics.prosperityDecile`.","name":"fields","in":"query"}],"responses":{"200":{"description":"One vector tile of site boundaries.","content":{"application/x-protobuf":{"schema":{"description":"The tile, as Mapbox Vector Tile binary data."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/sites/{siteId}":{"get":{"operationId":"getSiteById","x-speakeasy-name-override":"get","tags":["Sites"],"summary":"Get site by ID","description":"Retrieve one registered title by its identifier, which joins the country, the registry and the title number with colons, as in `GB:LR:AGL123456`. This endpoint returns every attribute, including the boundary geometry, ownership, property statistics, planning statistics and area metrics.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Identifier for a single registered title, made up of the country, the registry and the title number joined by colons.","example":"GB:LR:AGL123456"},"required":true,"description":"Identifier for a single registered title, made up of the country, the registry and the title number joined by colons.","name":"siteId","in":"path"}],"responses":{"200":{"description":"The requested site.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Site"}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/buildings/query":{"post":{"operationId":"searchBuildings","x-speakeasy-name-override":"search","tags":["Buildings"],"summary":"Search buildings","description":"Search buildings by their attributes, by geographic area, or by both, with sorting and pagination. Everything in `filters` and `query` has to match, and area filters accept a polygon, a multi-polygon, a point with a radius, a point the footprint must enclose, or a bounding box; a building matches the area clause if it satisfies any one of them. The footprint geometry, the building parts, the linked address records and the provenance map are left out by default because of their size, so name them in `attributes` to get them back. Up to 100 buildings come back per request, from an offset of at most 10000.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildingQueryRequest"}}}},"responses":{"200":{"description":"One page of buildings matching the search.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildingListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/buildings/aggregate":{"post":{"operationId":"aggregateBuildings","x-speakeasy-name-override":"aggregate","tags":["Buildings"],"summary":"Aggregate buildings","description":"Summarise buildings in bulk rather than listing them: counts by use, height and footprint statistics, distributions over time, and map-tile groupings. The same filters and geographic areas as the search endpoint decide which buildings are counted. A request may carry up to 10 aggregations, and results come back keyed by the `name` given in each definition, so pick names that are unique within the request.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildingAggregateRequest"}}}},"responses":{"200":{"description":"The aggregation results, with the total number of buildings they were computed over.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildingAggregateResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/buildings/by-ids":{"post":{"operationId":"findBuildingsByIds","x-speakeasy-name-override":"findByIds","tags":["Buildings"],"summary":"Batch lookup buildings by IDs","description":"Retrieve up to 100 buildings by identifier in a single request, choosing which fields come back with `attributes`. Identifiers that match nothing are left out of the response rather than raising an error, so compare `total_count` against the number of identifiers sent to spot the ones that were not found.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildingByIdsRequest"}}}},"responses":{"200":{"description":"The buildings that matched the identifiers supplied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildingListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/buildings/by-point":{"get":{"operationId":"findBuildingsByPoint","x-speakeasy-name-override":"findByPoint","tags":["Buildings"],"summary":"Find buildings by point","description":"Find every building whose footprint encloses a single coordinate, given as latitude and longitude in WGS84 decimal degrees. Footprints can overlap at one spot, as they do under canopies and multi-storey decks, so more than one building may come back. Up to 50 are returned, and a point inside no footprint returns an empty list rather than a 404.","parameters":[{"schema":{"type":["number","null"],"minimum":-90,"maximum":90,"description":"Latitude of the point, in WGS84 decimal degrees."},"required":false,"description":"Latitude of the point, in WGS84 decimal degrees.","name":"lat","in":"query"},{"schema":{"type":["number","null"],"minimum":-180,"maximum":180,"description":"Longitude of the point, in WGS84 decimal degrees."},"required":false,"description":"Longitude of the point, in WGS84 decimal degrees.","name":"lon","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":50,"description":"Maximum number of buildings to return. Defaults to 50. Minimum 1, maximum 50."},"required":false,"description":"Maximum number of buildings to return. Defaults to 50. Minimum 1, maximum 50.","name":"limit","in":"query"}],"responses":{"200":{"description":"The buildings whose footprint encloses the point.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildingListResponse"}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/buildings/by-uprn/{uprn}":{"get":{"operationId":"findBuildingsByUprn","x-speakeasy-name-override":"findByUprn","tags":["Buildings"],"summary":"Find buildings linked to a UPRN","description":"Find the buildings linked to a single addressable location, given as its Unique Property Reference Number (UPRN). One location can resolve to several buildings where a property spans more than one structure. Up to 25 come back, and a location linked to no building returns an empty list rather than a 404.","parameters":[{"schema":{"type":"string","minLength":1,"description":"The Unique Property Reference Number (UPRN).","example":"100023336956"},"required":true,"description":"The Unique Property Reference Number (UPRN).","name":"uprn","in":"path"}],"responses":{"200":{"description":"The buildings linked to that location.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BuildingListResponse"}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/buildings/{buildingId}":{"get":{"operationId":"getBuildingById","x-speakeasy-name-override":"get","tags":["Buildings"],"summary":"Get building by ID","description":"Retrieve one building by its identifier, which joins the country, the source dataset and that dataset's own identifier with colons, as in `GB:NGD:abc12345-67de-89f0-1234-567890abcdef`. This endpoint always returns the standard attribute set, which covers the structure, construction and basement blocks. It takes no `attributes` parameter, so the footprint geometry, the building parts, the linked address records and the provenance map are not available here; request those from the search or batch endpoints, which do accept `attributes`.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Identifier for a single building, made up of the country, the source dataset and that dataset's own identifier, joined by colons.","example":"GB:NGD:abc12345-67de-89f0-1234-567890abcdef"},"required":true,"description":"Identifier for a single building, made up of the country, the source dataset and that dataset's own identifier, joined by colons.","name":"buildingId","in":"path"}],"responses":{"200":{"description":"The requested building.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Building"}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/companies/{companyNumber}":{"get":{"operationId":"getCompany","x-speakeasy-name-override":"getCompany","tags":["Companies"],"summary":"Get company by registration number","description":"Returns the full company record held on the Companies House register for one eight-character registration number, including its status, type, registered office and filing dates. Set includeOfficers=true or includePscs=true to add up to 50 active officer or PSC summaries.","parameters":[{"schema":{"type":"string","minLength":8,"maxLength":8,"description":"The company's eight-character Companies House registration number. Most are digits, zero-padded, such as `00000006`. Some carry a letter prefix: `OC` for limited liability partnerships, `SC` for Scottish companies, `NI` for Northern Ireland and `OE` for overseas entities. Lower-case letters are accepted.","example":"00000006"},"required":true,"description":"The company's eight-character Companies House registration number. Most are digits, zero-padded, such as `00000006`. Some carry a letter prefix: `OC` for limited liability partnerships, `SC` for Scottish companies, `NI` for Northern Ireland and `OE` for overseas entities. Lower-case letters are accepted.","name":"companyNumber","in":"path"},{"schema":{"type":"string","description":"Set to `true` to add up to 50 active officer summaries to the response. Any other value leaves them out."},"required":false,"description":"Set to `true` to add up to 50 active officer summaries to the response. Any other value leaves them out.","name":"includeOfficers","in":"query"},{"schema":{"type":"string","description":"Set to `true` to add up to 50 active PSC summaries to the response. Any other value leaves them out."},"required":false,"description":"Set to `true` to add up to 50 active PSC summaries to the response. Any other value leaves them out.","name":"includePscs","in":"query"}],"responses":{"200":{"description":"The company record, with officers and PSCs when they were requested.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/companies/query":{"post":{"operationId":"queryCompanies","x-speakeasy-name-override":"queryCompanies","tags":["Companies"],"summary":"Search companies with filters","description":"Searches the company register by name, number, status, type, jurisdiction, SIC code, location, incorporation date and the charge and insolvency flags. Returns a page of company summaries with the total number of matches; limit accepts up to 100 results per page. Officers, PSCs and the registered office address are not part of a search result.","requestBody":{"description":"Filters, paging and sort order for the search.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyQueryRequest"}}}},"responses":{"200":{"description":"A page of companies matching the search, with the total number of matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/companies/location/{locationId}":{"get":{"operationId":"getCompaniesByLocation","x-speakeasy-name-override":"getCompaniesByLocation","tags":["Companies"],"summary":"Get companies at a property location","description":"Returns every company whose registered office is at one location, ordered by company name. Use it to see who trades from an address, and for ownership and due-diligence checks. The response is not paginated.","parameters":[{"schema":{"type":"string","example":"100023336956","description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN)."},"required":true,"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN).","name":"locationId","in":"path"}],"responses":{"200":{"description":"The companies registered at this location.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompaniesByLocationResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/companies/{companyNumber}/officers":{"get":{"operationId":"getCompanyOfficers","x-speakeasy-name-override":"getCompanyOfficers","tags":["Companies"],"summary":"Get officers for a company","description":"Returns the officer appointments recorded against a company: directors, secretaries, LLP members and the other roles the register carries. Only active officers are returned unless activeOnly is set to `false`.","parameters":[{"schema":{"type":"string","minLength":8,"maxLength":8,"description":"The company's eight-character Companies House registration number. Most are digits, zero-padded, such as `00000006`. Some carry a letter prefix: `OC` for limited liability partnerships, `SC` for Scottish companies, `NI` for Northern Ireland and `OE` for overseas entities. Lower-case letters are accepted.","example":"00000006"},"required":true,"description":"The company's eight-character Companies House registration number. Most are digits, zero-padded, such as `00000006`. Some carry a letter prefix: `OC` for limited liability partnerships, `SC` for Scottish companies, `NI` for Northern Ireland and `OE` for overseas entities. Lower-case letters are accepted.","name":"companyNumber","in":"path"},{"schema":{"type":"string","description":"Set to `false` to include officers who have resigned or been removed. Defaults to true, which returns only appointments with no resignation date."},"required":false,"description":"Set to `false` to include officers who have resigned or been removed. Defaults to true, which returns only appointments with no resignation date.","name":"activeOnly","in":"query"},{"schema":{"type":"string","description":"Return only appointments in these roles, comma separated, for example `director,secretary`."},"required":false,"description":"Return only appointments in these roles, comma separated, for example `director,secretary`.","name":"roles","in":"query"},{"schema":{"type":"string","description":"Maximum number of items to return. Defaults to 25. Minimum 1, maximum 100."},"required":false,"description":"Maximum number of items to return. Defaults to 25. Minimum 1, maximum 100.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Number of results to skip before the first one returned. Defaults to 0. Anything above 10000 is treated as 10000."},"required":false,"description":"Number of results to skip before the first one returned. Defaults to 0. Anything above 10000 is treated as 10000.","name":"offset","in":"query"}],"responses":{"200":{"description":"A page of officer appointments at this company, with the total number of matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfficerListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/companies/{companyNumber}/pscs":{"get":{"operationId":"getCompanyPscs","x-speakeasy-name-override":"getCompanyPscs","tags":["Companies"],"summary":"Get persons with significant control for a company","description":"Returns the people and entities with significant control over a company, as defined by Part 21A of the Companies Act 2006, covering individuals, corporate entities and other legal persons. People whose identities are protected by court order are left out unless excludeSuperSecure is set to `false`.","parameters":[{"schema":{"type":"string","minLength":8,"maxLength":8,"description":"The company's eight-character Companies House registration number. Most are digits, zero-padded, such as `00000006`. Some carry a letter prefix: `OC` for limited liability partnerships, `SC` for Scottish companies, `NI` for Northern Ireland and `OE` for overseas entities. Lower-case letters are accepted.","example":"00000006"},"required":true,"description":"The company's eight-character Companies House registration number. Most are digits, zero-padded, such as `00000006`. Some carry a letter prefix: `OC` for limited liability partnerships, `SC` for Scottish companies, `NI` for Northern Ireland and `OE` for overseas entities. Lower-case letters are accepted.","name":"companyNumber","in":"path"},{"schema":{"type":"string","description":"Set to `false` to include PSCs whose control has ceased. Defaults to true, which returns only PSCs with no cessation date."},"required":false,"description":"Set to `false` to include PSCs whose control has ceased. Defaults to true, which returns only PSCs with no cessation date.","name":"activeOnly","in":"query"},{"schema":{"type":"string","default":"true","description":"Set to `false` to include people whose identities are protected by a court order under s.790ZG of the Companies Act 2006. Defaults to true, which leaves them out. Protection is granted to individuals at serious risk of harm, so ask for these records only where there is a genuine need to show them."},"required":false,"description":"Set to `false` to include people whose identities are protected by a court order under s.790ZG of the Companies Act 2006. Defaults to true, which leaves them out. Protection is granted to individuals at serious risk of harm, so ask for these records only where there is a genuine need to show them.","name":"excludeSuperSecure","in":"query"},{"schema":{"type":"string","description":"Return only PSCs of these kinds, comma separated, for example `individual-person-with-significant-control`."},"required":false,"description":"Return only PSCs of these kinds, comma separated, for example `individual-person-with-significant-control`.","name":"kinds","in":"query"},{"schema":{"type":"string","description":"Maximum number of items to return. Defaults to 25. Minimum 1, maximum 100."},"required":false,"description":"Maximum number of items to return. Defaults to 25. Minimum 1, maximum 100.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Number of results to skip before the first one returned. Defaults to 0. Anything above 10000 is treated as 10000."},"required":false,"description":"Number of results to skip before the first one returned. Defaults to 0. Anything above 10000 is treated as 10000.","name":"offset","in":"query"}],"responses":{"200":{"description":"A page of PSC notifications for this company, with the total number of matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PscListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/companies/persons/{personId}":{"get":{"operationId":"getPerson","x-speakeasy-name-override":"getPerson","tags":["Companies"],"summary":"Get person by ID","description":"Returns one person, deduplicated across the officer appointments and PSC notifications that name the same individual, with the counts of appointments they hold. Officer and PSC records carry the identifier to use here as personId.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Identifier of a deduplicated person record, as a UUID. Officer and PSC records carry it as personId, and person search results return it as id.","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479"},"required":true,"description":"Identifier of a deduplicated person record, as a UUID. Officer and PSC records carry it as personId, and person search results return it as id.","name":"personId","in":"path"}],"responses":{"200":{"description":"The person record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/companies/persons/{personId}/appointments":{"get":{"operationId":"getPersonAppointments","x-speakeasy-name-override":"getPersonAppointments","tags":["Companies"],"summary":"Get all appointments held by a person","description":"Returns the officer appointments one person holds across companies, each carrying the name and current status of the company it is at, so you can tell live directorships from dissolved ones. Only active appointments are returned unless activeOnly is set to `false`.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Identifier of a deduplicated person record, as a UUID. Officer and PSC records carry it as personId, and person search results return it as id.","example":"f47ac10b-58cc-4372-a567-0e02b2c3d479"},"required":true,"description":"Identifier of a deduplicated person record, as a UUID. Officer and PSC records carry it as personId, and person search results return it as id.","name":"personId","in":"path"},{"schema":{"type":"string","description":"Set to `false` to include appointments the person has resigned from. Defaults to true, which returns only appointments with no resignation date."},"required":false,"description":"Set to `false` to include appointments the person has resigned from. Defaults to true, which returns only appointments with no resignation date.","name":"activeOnly","in":"query"},{"schema":{"type":"string","description":"Maximum number of items to return. Defaults to 25. Minimum 1, maximum 100."},"required":false,"description":"Maximum number of items to return. Defaults to 25. Minimum 1, maximum 100.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Number of results to skip before the first one returned. Defaults to 0. Anything above 10000 is treated as 10000."},"required":false,"description":"Number of results to skip before the first one returned. Defaults to 0. Anything above 10000 is treated as 10000.","name":"offset","in":"query"}],"responses":{"200":{"description":"A page of the person's appointments, with the total number of matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppointmentsResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/companies/persons/cluster/{clusterId}":{"get":{"operationId":"getPersonCluster","x-speakeasy-name-override":"getPersonCluster","tags":["Companies"],"summary":"Get all persons in an entity resolution cluster (Premium)","description":"Returns every person record grouped into one cluster, with the primary record and the combined appointment counts across its members. A cluster groups the records judged to represent the same individual, so use it where one person appears under several spellings. Requires the Companies House Premium product.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Identifier of an entity resolution cluster, as a UUID. A cluster groups the person records judged to represent the same individual. Requires the Companies House Premium product.","example":"c47ac10b-58cc-4372-a567-0e02b2c3d480"},"required":true,"description":"Identifier of an entity resolution cluster, as a UUID. A cluster groups the person records judged to represent the same individual. Requires the Companies House Premium product.","name":"clusterId","in":"path"}],"responses":{"200":{"description":"The cluster, with every member record.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonClusterResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/companies/persons/query":{"post":{"operationId":"queryPersons","x-speakeasy-name-override":"queryPersons","tags":["Companies"],"summary":"Search persons with filters","description":"Searches deduplicated person records by name, family name, month and year of birth, nationality, country of residence and appointment counts. Returns a page of person summaries; limit accepts up to 50 results per page. Only primary records are returned unless includeNonCanonical is set to true.","requestBody":{"description":"Filters, paging and sort order for the search.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonQueryRequest"},"example":{"name":"John Smith","limit":25}}}},"responses":{"200":{"description":"A page of people matching the search, with the total number of matches.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/companies/officers/{officerId}":{"get":{"operationId":"getOfficer","x-speakeasy-name-override":"getOfficer","tags":["Companies"],"summary":"Get officer appointment by ID","description":"Returns one officer appointment: the role held, the company it is at, the dates it ran, and the person or body corporate holding it. Company officer lists return the identifier to use here as id.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Identifier of an officer appointment, as a UUID. Company officer lists and person appointment responses return it as id."},"required":true,"description":"Identifier of an officer appointment, as a UUID. Company officer lists and person appointment responses return it as id.","name":"officerId","in":"path"}],"responses":{"200":{"description":"The officer appointment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OfficerResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/companies/pscs/{pscId}":{"get":{"operationId":"getPsc","x-speakeasy-name-override":"getPsc","tags":["Companies"],"summary":"Get PSC notification by ID","description":"Returns one person with significant control: who they are, the company they control, how that control is held and when it was notified. Company PSC lists return the identifier to use here as id.","parameters":[{"schema":{"type":"string","format":"uuid","description":"Identifier of a PSC notification, as a UUID. Company PSC lists return it as id."},"required":true,"description":"Identifier of a PSC notification, as a UUID. Company PSC lists return it as id.","name":"pscId","in":"path"}],"responses":{"200":{"description":"The PSC notification.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PscResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/companies/health":{"get":{"operationId":"checkCompaniesHealth","x-speakeasy-name-override":"checkCompaniesHealth","tags":["System"],"summary":"Check Companies House service health","description":"Reports whether the Companies House endpoints are operational. Returns no company data.","responses":{"200":{"description":"The service is operational.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"}}}}}}},"/v1/title-deeds/{titleNumber}/documents":{"get":{"tags":["Title Deeds"],"summary":"List documents for a purchased title deed","description":"Lists the documents held for a title, each with the status that says whether it can be downloaded yet. The title must already have been purchased on this account.","parameters":[{"schema":{"type":"string","example":"HP725622","description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only."},"required":true,"description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only.","name":"titleNumber","in":"path"}],"responses":{"200":{"description":"The documents held for this title, with their current statuses.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleDeedDocumentListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"This title has not been purchased on this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/title-deeds/{titleNumber}/documents/{documentType}":{"get":{"tags":["Title Deeds"],"summary":"Download a document for a purchased title deed","description":"Downloads one of the title's documents as a PDF. Only documents whose status is `uploaded` can be downloaded, and the title must already have been purchased on this account.","parameters":[{"schema":{"type":"string","example":"HP725622","description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only."},"required":true,"description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only.","name":"titleNumber","in":"path"},{"schema":{"type":"string","enum":["register-extract","official-title","title-plan"],"description":"Which of the title's documents this is. `register-extract` is the full register of the title, carrying its proprietors, charges and restrictions; `official-title` is the official copy of that register; `title-plan` is the plan showing the extent of the property.","example":"register-extract"},"required":true,"description":"Which of the title's documents this is. `register-extract` is the full register of the title, carrying its proprietors, charges and restrictions; `official-title` is the official copy of that register; `title-plan` is the plan showing the extent of the property.","name":"documentType","in":"path"}],"responses":{"200":{"description":"The document, as a PDF.","content":{"application/pdf":{"schema":{"type":"string","format":"binary"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"This title has not been purchased on this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No such document for this title, or it cannot be downloaded because it is still being prepared or could not be produced.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/title-deeds/{titleNumber}/purchase-status":{"get":{"tags":["Title Deeds"],"summary":"Check the purchase status of a title deed","description":"Reports what this account has been charged for a title, without buying it. Use this before retrying a purchase whose result is uncertain, or to check whether an already-owned title can be fetched without charging a second time. Where the outcome is not implied by the status code, the body states it as `money_state`, so a caller never has to infer it.","parameters":[{"schema":{"type":"string","example":"HP725622","description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only."},"required":true,"description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only.","name":"titleNumber","in":"path"}],"responses":{"200":{"description":"The title is owned by this account: its property details, proprietors and documents. `credits_charged` is `0` because nothing was charged by this request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleDeedPurchaseResponse"}}}},"202":{"description":"The purchase succeeded and the credits were taken, but the title has not been delivered yet, either because HM Land Registry is delivering it later or because the earlier purchase is still being fetched. This is not a failure, so do not refund against it. Poll this endpoint until the purchase resolves: it settles into a 200, or in the rare case the fetch dies it is refunded and reported here as `not_charged`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleDeedPurchasePending"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"This account has never held this title, or held it and was refunded. `purchase_status` distinguishes the two; both carry `money_state: not_charged`. When the purchase was refunded because HM Land Registry refused it, `failure_code` and `failure_message` say why, so a refusal that cannot clear on retry (such as a pending application) is not mistaken for a transient failure.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleDeedPurchaseNotFound"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleDeedPurchaseError"}}}}}}},"/v1/title-deeds/{titleNumber}/availability":{"get":{"tags":["Title Deeds"],"summary":"Check whether a title deed can be purchased","description":"Reports whether HM Land Registry will sell an official copy of this title today, and if not, why not. Nothing is charged and no purchase is made, so this can be called before every purchase. The common reason a title cannot be bought is that an application is pending against it, in which case HM Land Registry will not issue a standard official copy until the application completes. Use `/{titleNumber}/applications` to see what is pending.","parameters":[{"schema":{"type":"string","example":"HP725622","description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only."},"required":true,"description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only.","name":"titleNumber","in":"path"}],"responses":{"200":{"description":"Whether the title can be bought right now, with the registration status and the delivery availability of the register and title plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleDeedAvailabilityResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No title with this number exists at HM Land Registry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"502":{"description":"HM Land Registry could not be reached, so availability is unknown. Treat this as unknown rather than as a title that cannot be bought.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/title-deeds/{titleNumber}/applications":{"get":{"tags":["Title Deeds"],"summary":"List applications pending against a title deed","description":"Returns the applications lodged against this title at HM Land Registry and not yet completed, with the type of each, who lodged it, its priority date and how far it has progressed. Nothing is charged. While any application is pending, a standard official copy of the title cannot be purchased.","parameters":[{"schema":{"type":"string","example":"HP725622","description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only."},"required":true,"description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only.","name":"titleNumber","in":"path"}],"responses":{"200":{"description":"The applications currently pending against this title. An empty list means nothing is pending.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleDeedApplicationListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No title with this number exists at HM Land Registry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"502":{"description":"HM Land Registry could not be reached, so the pending applications are unknown.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/title-deeds/{titleNumber}/purchase":{"post":{"tags":["Title Deeds"],"summary":"Purchase a title deed","description":"Buys the registered title for a title number and returns its property details, proprietors and documents. Each title costs a fixed number of credits, deducted when the purchase succeeds. A title already purchased on this account is returned again at no charge. Every documented error body states whether this account has been charged as `money_state`. Read that rather than inferring it from the status code, because a 202 means the purchase succeeded and is still being delivered, and must not be refunded.","parameters":[{"schema":{"type":"string","example":"HP725622","description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only."},"required":true,"description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only.","name":"titleNumber","in":"path"}],"responses":{"200":{"description":"The purchased title, its proprietors and its documents.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleDeedPurchaseResponse"}}}},"202":{"description":"The purchase succeeded and the credits have been taken, but HM Land Registry is delivering the title later rather than in this response. Poll `GET /v1/title-deeds/{titleNumber}` for it. This is not a failure and the charge is never reversed, so do not refund against it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleDeedPurchasePending"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"402":{"description":"The account does not hold enough credits to buy this title. Nothing has been charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCreditsError"}}}},"404":{"description":"HM Land Registry holds no such title, or the title is closed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleDeedPurchaseError"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleDeedPurchaseError"}}}},"502":{"description":"HM Land Registry rejected the purchase. Read `money_state` before refunding downstream.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleDeedPurchaseError"}}}},"503":{"description":"Title deed purchases are paused, or a purchase of this title is already in flight. Retry shortly.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleDeedPurchaseError"}}}}}}},"/v1/title-deeds/{titleNumber}/purchase-async":{"post":{"tags":["Title Deeds"],"summary":"Start a title deed purchase with structured extraction","description":"Starts a purchase that also reads the register into structured detail, and returns straight away with the current status. Poll `GET /v1/title-deeds/{titleNumber}` for the result. Calling it twice for the same title on the same account does not charge a second time.","parameters":[{"schema":{"type":"string","example":"HP725622","description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only."},"required":true,"description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only.","name":"titleNumber","in":"path"}],"responses":{"200":{"description":"The purchase has started, or the title was already owned and its current status is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AsyncPurchaseTitleDeedResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"402":{"description":"The account does not hold enough credits to buy this title.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientCreditsError"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"Title deed purchases are paused. Retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/title-deeds/{titleNumber}":{"get":{"tags":["Title Deeds"],"summary":"Get the structured extraction for a title deed","description":"Returns the structured reading of the register for a title purchased through the asynchronous route. Status moves from `pending` to `analysing` to `complete`, and the extraction payload is present only once it is complete. The title must already have been purchased on this account.","parameters":[{"schema":{"type":"string","example":"HP725622","description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only."},"required":true,"description":"HM Land Registry title number: up to three letters followed by one to six digits. Case is not significant and the value is upper-cased; older titles may be digits only.","name":"titleNumber","in":"path"}],"responses":{"200":{"description":"The current status, with the extraction payload once it is complete.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TitleExtractionPollResponse"}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"This title has not been purchased on this account.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No extraction has been started for this title.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/energy/substations/{code}":{"get":{"operationId":"getSubstationByCode","x-speakeasy-name-override":"getSubstation","tags":["Energy"],"summary":"Get substation by code","description":"Returns one electricity substation by its code, with the voltage it runs at, the peak demand it meets, its firm capacity and the headroom left for new connections. Codes are prefixed with the operator, as in `ukpn:PRI-1234` or `npg:12345`.","parameters":[{"schema":{"type":"string","example":"ukpn:PRI-1234","description":"Code of the substation, prefixed with the operator code."},"required":true,"description":"Code of the substation, prefixed with the operator code.","name":"code","in":"path"}],"responses":{"200":{"description":"The requested substation, with its current capacity and headroom.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["substation"],"description":"Object type discriminator. Always `substation`."},"code":{"type":"string","description":"Code identifying the substation, prefixed with the operator code.","example":"ukpn:PRI-1234"},"name":{"type":["string","null"],"description":"Name of the substation, where the operator publishes one.","example":"Bankside Primary"},"operator":{"type":"string","description":"Network operator that owns and runs this substation.","title":"OperatorCode","example":"ukpn"},"operatingRegion":{"type":["string","null"],"description":"Licence area or region the operator assigns this substation to.","example":"UKPN (SPN)"},"country":{"type":"string","description":"Country the substation is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"parentSubstationCode":{"type":["string","null"],"description":"Code of the substation one level up the hierarchy, such as the grid substation feeding a primary. Null where no parent is recorded.","example":"ukpn:GRD-100"},"substationType":{"type":["string","null"],"description":"Where this substation sits in the network hierarchy. Known values are 'gsp', 'bulk_supply', 'grid', 'primary', 'distribution'.","title":"SubstationType"},"voltageKv":{"type":["number","null"],"description":"Operating voltage, in kilovolts (kV).","example":33},"location":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Point location of the substation.","title":"Coordinates"},"demandMw":{"type":["number","null"],"description":"Peak electricity demand currently met by this substation, in megawatts (MW).","example":12.5},"firmCapacityMw":{"type":["number","null"],"description":"Capacity the substation can supply under all operating conditions, in megawatts (MW).","example":20},"demandHeadroomMw":{"type":["number","null"],"description":"Spare capacity for new demand connections, in megawatts (MW). Can be negative where there is no spare capacity left.","example":7.5},"generationHeadroomMw":{"type":["number","null"],"description":"Spare capacity for new generation connections, such as solar or wind, in megawatts (MW).","example":5},"reversePowerCapacityMw":{"type":["number","null"],"description":"Capacity for power flowing back up the network when generation exceeds local demand, in megawatts (MW)."},"utilisationPct":{"type":["number","null"],"description":"How much of the substation's capacity is in use, as a percentage. Higher values leave less room for new connections.","example":62.5}},"required":["object","code","name","operator","operatingRegion","country","parentSubstationCode","substationType","voltageKv","location","demandMw","firmCapacityMw","demandHeadroomMw","generationHeadroomMw","reversePowerCapacityMw","utilisationPct"],"description":"A network operator substation, with the capacity, demand and headroom currently recorded for it.","title":"Substation"}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/energy/substations/nearest":{"get":{"operationId":"findNearestSubstations","x-speakeasy-name-override":"findNearestSubstations","tags":["Energy"],"summary":"Find nearest substations","description":"Returns the electricity substations within a radius of a point, closest first, so you can see what sits near a location and how much capacity it has. The radius is in kilometres, defaults to 5 and can be up to 50. Ten substations come back by default and 100 at most. Results can be narrowed to one substation type or one country.","parameters":[{"schema":{"type":["number","null"],"minimum":-90,"maximum":90,"description":"Latitude of the centre of the search, in WGS84 decimal degrees.","example":51.5074},"required":false,"description":"Latitude of the centre of the search, in WGS84 decimal degrees.","name":"lat","in":"query"},{"schema":{"type":["number","null"],"minimum":-180,"maximum":180,"description":"Longitude of the centre of the search, in WGS84 decimal degrees.","example":-0.1278},"required":false,"description":"Longitude of the centre of the search, in WGS84 decimal degrees.","name":"lon","in":"query"},{"schema":{"type":"number","minimum":0.1,"maximum":50,"default":5,"description":"How far from that point to search, in kilometres. Defaults to 5. Minimum 0.1, maximum 50.","example":5},"required":false,"description":"How far from that point to search, in kilometres. Defaults to 5. Minimum 0.1, maximum 50.","name":"radius","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":100,"default":10,"description":"Maximum number of items to return. Defaults to 10. Minimum 1, maximum 100."},"required":false,"description":"Maximum number of items to return. Defaults to 10. Minimum 1, maximum 100.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Return only substations at this level of the network hierarchy. Known values are 'gsp', 'bulk_supply', 'grid', 'primary', 'distribution'.","title":"SubstationType"},"required":false,"description":"Return only substations at this level of the network hierarchy. Known values are 'gsp', 'bulk_supply', 'grid', 'primary', 'distribution'.","name":"substationType","in":"query"},{"schema":{"type":"string","description":"Return only substations in this country, as an ISO 3166-1 alpha-2 code.","example":"GB"},"required":false,"description":"Return only substations in this country, as an ISO 3166-1 alpha-2 code.","name":"country","in":"query"}],"responses":{"200":{"description":"Substations within the radius, ordered from closest to furthest.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["substation"],"description":"Object type discriminator. Always `substation`."},"code":{"type":"string","description":"Code identifying the substation, prefixed with the operator code.","example":"ukpn:PRI-1234"},"name":{"type":["string","null"],"description":"Name of the substation, where the operator publishes one.","example":"Bankside Primary"},"operator":{"type":"string","description":"Network operator that owns and runs this substation.","title":"OperatorCode","example":"ukpn"},"operatingRegion":{"type":["string","null"],"description":"Licence area or region the operator assigns this substation to.","example":"UKPN (SPN)"},"country":{"type":"string","description":"Country the substation is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"parentSubstationCode":{"type":["string","null"],"description":"Code of the substation one level up the hierarchy, such as the grid substation feeding a primary. Null where no parent is recorded.","example":"ukpn:GRD-100"},"substationType":{"type":["string","null"],"description":"Where this substation sits in the network hierarchy. Known values are 'gsp', 'bulk_supply', 'grid', 'primary', 'distribution'.","title":"SubstationType"},"voltageKv":{"type":["number","null"],"description":"Operating voltage, in kilovolts (kV).","example":33},"location":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Point location of the substation.","title":"Coordinates"},"demandMw":{"type":["number","null"],"description":"Peak electricity demand currently met by this substation, in megawatts (MW).","example":12.5},"firmCapacityMw":{"type":["number","null"],"description":"Capacity the substation can supply under all operating conditions, in megawatts (MW).","example":20},"demandHeadroomMw":{"type":["number","null"],"description":"Spare capacity for new demand connections, in megawatts (MW). Can be negative where there is no spare capacity left.","example":7.5},"generationHeadroomMw":{"type":["number","null"],"description":"Spare capacity for new generation connections, such as solar or wind, in megawatts (MW).","example":5},"reversePowerCapacityMw":{"type":["number","null"],"description":"Capacity for power flowing back up the network when generation exceeds local demand, in megawatts (MW)."},"utilisationPct":{"type":["number","null"],"description":"How much of the substation's capacity is in use, as a percentage. Higher values leave less room for new connections.","example":62.5}},"required":["object","code","name","operator","operatingRegion","country","parentSubstationCode","substationType","voltageKv","location","demandMw","firmCapacityMw","demandHeadroomMw","generationHeadroomMw","reversePowerCapacityMw","utilisationPct"],"description":"A network operator substation, with the capacity, demand and headroom currently recorded for it.","title":"Substation"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"The query timed out or the service is briefly overloaded. Retry, with a smaller radius if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/energy/substations/query":{"post":{"operationId":"searchSubstations","x-speakeasy-name-override":"searchSubstations","tags":["Energy"],"summary":"Search substations","description":"Searches substations across every network operator. Filter by operator, licence area, country, position in the network hierarchy, and by how much demand or generation headroom a substation has left. Every filter supplied must match. Results come back ordered by substation code, paged with `limit` and `offset`, and carry the total count of matches.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"operator":{"type":"string","description":"Return only substations belonging to this network operator.","title":"OperatorCode","example":"ukpn"},"operatingRegion":{"type":"string","description":"Return only substations in this licence area or region.","example":"UKPN (SPN)"},"country":{"type":"string","description":"Return only substations in this country, as an ISO 3166-1 alpha-2 code.","example":"GB"},"substationType":{"type":"string","description":"Return only substations at this level of the network hierarchy. Known values are 'gsp', 'bulk_supply', 'grid', 'primary', 'distribution'.","title":"SubstationType"},"minDemandHeadroomMw":{"type":["number","null"],"minimum":-500,"maximum":500,"description":"Return only substations with at least this much demand headroom, in megawatts (MW). Minimum -500, maximum 500.","example":5},"maxDemandHeadroomMw":{"type":["number","null"],"minimum":-500,"maximum":500,"description":"Return only substations with at most this much demand headroom, in megawatts (MW). Minimum -500, maximum 500.","example":50},"minGenerationHeadroomMw":{"type":["number","null"],"description":"Return only substations with at least this much generation headroom, in megawatts (MW).","example":2},"limit":{"type":"number","minimum":1,"maximum":1000,"default":100,"description":"Maximum number of items to return. Defaults to 100. Minimum 1, maximum 1000."},"offset":{"type":["number","null"],"minimum":0,"default":0,"description":"Number of results to skip before the first one returned. Defaults to 0."}},"title":"SearchSubstationsInput"}}}},"responses":{"200":{"description":"Matching substations, ordered by code, with the total number of matches.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["substation"],"description":"Object type discriminator. Always `substation`."},"code":{"type":"string","description":"Code identifying the substation, prefixed with the operator code.","example":"ukpn:PRI-1234"},"name":{"type":["string","null"],"description":"Name of the substation, where the operator publishes one.","example":"Bankside Primary"},"operator":{"type":"string","description":"Network operator that owns and runs this substation.","title":"OperatorCode","example":"ukpn"},"operatingRegion":{"type":["string","null"],"description":"Licence area or region the operator assigns this substation to.","example":"UKPN (SPN)"},"country":{"type":"string","description":"Country the substation is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"parentSubstationCode":{"type":["string","null"],"description":"Code of the substation one level up the hierarchy, such as the grid substation feeding a primary. Null where no parent is recorded.","example":"ukpn:GRD-100"},"substationType":{"type":["string","null"],"description":"Where this substation sits in the network hierarchy. Known values are 'gsp', 'bulk_supply', 'grid', 'primary', 'distribution'.","title":"SubstationType"},"voltageKv":{"type":["number","null"],"description":"Operating voltage, in kilovolts (kV).","example":33},"location":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Point location of the substation.","title":"Coordinates"},"demandMw":{"type":["number","null"],"description":"Peak electricity demand currently met by this substation, in megawatts (MW).","example":12.5},"firmCapacityMw":{"type":["number","null"],"description":"Capacity the substation can supply under all operating conditions, in megawatts (MW).","example":20},"demandHeadroomMw":{"type":["number","null"],"description":"Spare capacity for new demand connections, in megawatts (MW). Can be negative where there is no spare capacity left.","example":7.5},"generationHeadroomMw":{"type":["number","null"],"description":"Spare capacity for new generation connections, such as solar or wind, in megawatts (MW).","example":5},"reversePowerCapacityMw":{"type":["number","null"],"description":"Capacity for power flowing back up the network when generation exceeds local demand, in megawatts (MW)."},"utilisationPct":{"type":["number","null"],"description":"How much of the substation's capacity is in use, as a percentage. Higher values leave less room for new connections.","example":62.5}},"required":["object","code","name","operator","operatingRegion","country","parentSubstationCode","substationType","voltageKv","location","demandMw","firmCapacityMw","demandHeadroomMw","generationHeadroomMw","reversePowerCapacityMw","utilisationPct"],"description":"A network operator substation, with the capacity, demand and headroom currently recorded for it.","title":"Substation"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"The query timed out or the service is briefly overloaded. Retry, with fewer filters if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/energy/supply-areas/by-point":{"get":{"operationId":"findSupplyAreaByPoint","x-speakeasy-name-override":"findSupplyAreaByPoint","tags":["Energy"],"summary":"Find supply areas by point","description":"Returns every supply area boundary that contains the point, each carrying the code of the substation that serves it where one is recorded. The network is hierarchical, so one location can fall inside several boundaries at once: a distribution area, a primary area, a bulk supply point area and a grid supply point area. At most 50 boundaries are returned. Read `areaType` on each result to tell the levels apart.","parameters":[{"schema":{"type":["number","null"],"minimum":-90,"maximum":90,"description":"Latitude of the point to test, in WGS84 decimal degrees.","example":51.5074},"required":false,"description":"Latitude of the point to test, in WGS84 decimal degrees.","name":"lat","in":"query"},{"schema":{"type":["number","null"],"minimum":-180,"maximum":180,"description":"Longitude of the point to test, in WGS84 decimal degrees.","example":-0.1278},"required":false,"description":"Longitude of the point to test, in WGS84 decimal degrees.","name":"lon","in":"query"}],"responses":{"200":{"description":"The supply area boundaries containing the point.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["supply_area"],"description":"Object type discriminator. Always `supply_area`."},"code":{"type":"string","description":"Code identifying the supply area, prefixed with the operator code.","example":"ukpn:SA-001"},"name":{"type":["string","null"],"description":"Name of the supply area, where the operator publishes one."},"operator":{"type":"string","description":"Network operator that manages this supply area.","title":"OperatorCode","example":"ukpn"},"operatingRegion":{"type":["string","null"],"description":"Licence area or region the operator assigns this area to."},"country":{"type":"string","description":"Country the supply area is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"areaType":{"type":["string","null"],"description":"Level of the network hierarchy this boundary sits at. Known values are 'gsp', 'bsp', 'grid', 'primary', 'distribution'. A 'distribution' area covers the least ground and a grid supply point ('gsp') area the most.","title":"SupplyAreaType"},"substationCode":{"type":["string","null"],"description":"Code of the substation that serves this area."},"areaSqkm":{"type":["number","null"],"description":"Size of the area, in square kilometres."},"centroid":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Centre point of the area.","title":"Coordinates"}},"required":["object","code","name","operator","operatingRegion","country","areaType","substationCode","areaSqkm","centroid"],"description":"The geographic area served by one substation.","title":"SupplyArea"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/energy/substations/{code}/capacity":{"get":{"operationId":"getSubstationCapacity","x-speakeasy-name-override":"getCapacity","tags":["Energy"],"summary":"Get capacity time-series","description":"Returns the capacity snapshots recorded for a substation, oldest first, so you can track how its demand, firm capacity and headroom have moved. Snapshots are typically quarterly. Headroom is the capacity left for new connections: demand headroom for new consumers such as data centres or vehicle charging, generation headroom for new generators such as solar or wind. Use `from` and `to` to narrow the date range.","parameters":[{"schema":{"type":"string","example":"ukpn:PRI-1234","description":"Code of the substation, prefixed with the operator code."},"required":true,"description":"Code of the substation, prefixed with the operator code.","name":"code","in":"path"},{"schema":{"type":"string","description":"Earliest snapshot date to include, inclusive, as an ISO 8601 date.","example":"2024-01-01"},"required":false,"description":"Earliest snapshot date to include, inclusive, as an ISO 8601 date.","name":"from","in":"query"},{"schema":{"type":"string","description":"Latest snapshot date to include, inclusive, as an ISO 8601 date.","example":"2025-12-31"},"required":false,"description":"Latest snapshot date to include, inclusive, as an ISO 8601 date.","name":"to","in":"query"}],"responses":{"200":{"description":"Capacity snapshots for the substation, oldest first.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["capacity_snapshot"],"description":"Object type discriminator. Always `capacity_snapshot`."},"substationCode":{"type":"string","description":"Code of the substation this snapshot describes.","example":"ukpn:PRI-1234"},"snapshotDate":{"type":"string","description":"Date the snapshot describes, as an ISO 8601 date. Snapshots are typically published quarterly.","example":"2025-01-01"},"snapshotSource":{"type":"string","description":"Identifier for the published dataset this snapshot was taken from.","example":"ltds_2025"},"demandMw":{"type":["number","null"],"description":"Peak demand at the snapshot date, in megawatts (MW)."},"firmCapacityMw":{"type":["number","null"],"description":"Firm capacity at the snapshot date, in megawatts (MW)."},"demandHeadroomMw":{"type":["number","null"],"description":"Spare capacity for new demand connections at the snapshot date, in megawatts (MW)."},"generationHeadroomMw":{"type":["number","null"],"description":"Spare capacity for new generation connections at the snapshot date, in megawatts (MW)."},"utilisationPct":{"type":["number","null"],"description":"How much of the substation's capacity was in use at the snapshot date, as a percentage."},"batteryHeadroomMw":{"type":["number","null"],"description":"Spare capacity specific to battery connections, in megawatts (MW). Not published by every operator."},"evHeadroomMw":{"type":["number","null"],"description":"Spare capacity specific to electric vehicle charging connections, in megawatts (MW). Not published by every operator."},"solarHeadroomMw":{"type":["number","null"],"description":"Spare capacity specific to solar connections, in megawatts (MW). Not published by every operator."}},"required":["object","substationCode","snapshotDate","snapshotSource","demandMw","firmCapacityMw","demandHeadroomMw","generationHeadroomMw","utilisationPct","batteryHeadroomMw","evHeadroomMw","solarHeadroomMw"],"description":"Substation capacity and headroom as they stood on one date. Compare snapshots to see how available capacity is moving.","title":"CapacitySnapshot"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/energy/ecr":{"get":{"operationId":"searchECR","x-speakeasy-name-override":"searchECR","tags":["Energy"],"summary":"Search embedded capacity register","description":"Searches the Embedded Capacity Register (ECR), the public record of generation and storage connected to the electricity distribution network, covering technologies such as solar, wind, gas, biomass and batteries. Each entry carries its installed and export capacity, technology, connection status and location. Filter by operator, licence area, country, technology or connection status. Results come back largest installed capacity first, paged with `limit` and `offset`.","parameters":[{"schema":{"type":"string","description":"Return only entries published by this network operator.","title":"OperatorCode","example":"ukpn"},"required":false,"description":"Return only entries published by this network operator.","name":"operator","in":"query"},{"schema":{"type":"string","description":"Return only entries in this licence area or region.","example":"UKPN (SPN)"},"required":false,"description":"Return only entries in this licence area or region.","name":"operatingRegion","in":"query"},{"schema":{"type":"string","description":"Return only entries in this country, as an ISO 3166-1 alpha-2 code.","example":"GB"},"required":false,"description":"Return only entries in this country, as an ISO 3166-1 alpha-2 code.","name":"country","in":"query"},{"schema":{"type":"string","description":"Return only entries using this technology, for example 'solar', 'wind' or 'battery'.","example":"solar"},"required":false,"description":"Return only entries using this technology, for example 'solar', 'wind' or 'battery'.","name":"technologyType","in":"query"},{"schema":{"type":"string","description":"Return only entries at this stage of the connection process. Known values are 'connected', 'accepted', 'contracted', 'in_scoping'.","title":"ConnectionStatus","example":"connected"},"required":false,"description":"Return only entries at this stage of the connection process. Known values are 'connected', 'accepted', 'contracted', 'in_scoping'.","name":"connectionStatus","in":"query"},{"schema":{"type":"number","minimum":1,"maximum":1000,"default":100,"description":"Maximum number of items to return. Defaults to 100. Minimum 1, maximum 1000."},"required":false,"description":"Maximum number of items to return. Defaults to 100. Minimum 1, maximum 1000.","name":"limit","in":"query"},{"schema":{"type":["number","null"],"minimum":0,"default":0,"description":"Number of results to skip before the first one returned. Defaults to 0."},"required":false,"description":"Number of results to skip before the first one returned. Defaults to 0.","name":"offset","in":"query"}],"responses":{"200":{"description":"Matching register entries, largest installed capacity first, with the total number of matches.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["ecr_entry"],"description":"Object type discriminator. Always `ecr_entry`."},"code":{"type":"string","description":"Code identifying this register entry, unique for a given operator.","example":"ukpn:ECR-5678"},"operator":{"type":"string","description":"Network operator that publishes this entry.","title":"OperatorCode","example":"ukpn"},"operatingRegion":{"type":["string","null"],"description":"Licence area or region the connection sits in."},"country":{"type":"string","description":"Country the connection is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"substationCode":{"type":["string","null"],"description":"Code of the substation the connection is registered against."},"connectionType":{"type":["string","null"],"description":"Whether the site generates, stores, or does both.","title":"ConnectionType","example":"generation"},"technologyType":{"type":["string","null"],"description":"Technology the site uses, for example 'solar', 'wind' or 'battery'.","example":"solar"},"installedCapacityMw":{"type":["number","null"],"description":"Capacity installed at the site, in megawatts (MW).","example":5},"exportCapacityMw":{"type":["number","null"],"description":"Capacity the site may export to the network, in megawatts (MW), as agreed with the operator."},"connectionStatus":{"type":["string","null"],"description":"Stage this connection has reached. Known values are 'connected', 'accepted', 'contracted', 'in_scoping'.","title":"ConnectionStatus","example":"connected"},"connectionDate":{"type":["string","null"],"description":"Date the site connected, or is expected to connect, as an ISO 8601 date."},"location":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Point location of the generation or storage site.","title":"Coordinates"}},"required":["object","code","operator","operatingRegion","country","substationCode","connectionType","technologyType","installedCapacityMw","exportCapacityMw","connectionStatus","connectionDate","location"],"description":"An entry in the Embedded Capacity Register (ECR), the public record of generation and storage connected to the distribution network.","title":"EcrEntry"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/energy/substations/{code}/dfes":{"get":{"operationId":"getSubstationDFES","x-speakeasy-name-override":"getDFES","tags":["Energy"],"summary":"Get future energy scenario forecasts","description":"Returns the energy scenario projections published for a substation, showing how electricity demand, generation and storage capacity are expected to grow, by scenario, year and technology. Each country's energy planning framework defines its own scenarios; in Great Britain these are the Distribution Future Energy Scenarios (DFES), running from the fastest decarbonisation pathway ('leading_the_way') to the slowest ('falling_short'), alongside the operator's central estimate ('best_view'). Narrow the result with `scenario`, `yearFrom` and `yearTo`.","parameters":[{"schema":{"type":"string","example":"ukpn:PRI-1234","description":"Code of the substation, prefixed with the operator code."},"required":true,"description":"Code of the substation, prefixed with the operator code.","name":"code","in":"path"},{"schema":{"type":"string","description":"Return only projections following this planning scenario. Known values are 'leading_the_way', 'consumer_transformation', 'system_transformation', 'falling_short', 'best_view', 'holistic_transition'.","title":"ForecastScenario","example":"best_view"},"required":false,"description":"Return only projections following this planning scenario. Known values are 'leading_the_way', 'consumer_transformation', 'system_transformation', 'falling_short', 'best_view', 'holistic_transition'.","name":"scenario","in":"query"},{"schema":{"type":["number","null"],"description":"Earliest year to include, inclusive. Must be less than or equal to `yearTo`.","example":2025},"required":false,"description":"Earliest year to include, inclusive. Must be less than or equal to `yearTo`.","name":"yearFrom","in":"query"},{"schema":{"type":["number","null"],"description":"Latest year to include, inclusive.","example":2050},"required":false,"description":"Latest year to include, inclusive.","name":"yearTo","in":"query"}],"responses":{"200":{"description":"Projections for the substation, ordered by scenario, then year, then technology.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["dfes_forecast"],"description":"Object type discriminator. Always `dfes_forecast`."},"operator":{"type":"string","description":"Network operator that published this forecast.","title":"OperatorCode","example":"ukpn"},"operatingRegion":{"type":"string","description":"Licence area or region the forecast covers."},"country":{"type":"string","description":"Country the forecast covers, as an ISO 3166-1 alpha-2 code.","example":"GB"},"substationCode":{"type":["string","null"],"description":"Code of the substation the forecast covers. Null where the forecast covers a whole region rather than a single substation."},"scenario":{"type":"string","description":"Planning scenario this projection follows. Known values are 'leading_the_way', 'consumer_transformation', 'system_transformation', 'falling_short', 'best_view', 'holistic_transition'.","title":"ForecastScenario","example":"best_view"},"year":{"type":"number","description":"Year the projection applies to.","example":2030},"technologyType":{"type":["string","null"],"description":"Technology being projected, for example 'solar', 'heat_pump' or 'battery'."},"forecastMw":{"type":["number","null"],"description":"Projected value for this scenario, year and technology, in megawatts (MW)."},"forecastType":{"type":"string","description":"Whether the row projects demand, generation or storage capacity.","title":"ForecastType","example":"demand"}},"required":["object","operator","operatingRegion","country","substationCode","scenario","year","technologyType","forecastMw","forecastType"],"description":"One projection from an energy planning framework, such as the Distribution Future Energy Scenarios (DFES) in Great Britain, covering a single scenario, year and technology.","title":"DfesForecast"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/energy/connection-queue/query":{"post":{"operationId":"searchConnectionQueue","x-speakeasy-name-override":"searchConnectionQueue","tags":["Energy"],"summary":"Search connection queue","description":"Searches the grid connection queue for projects waiting for or holding an agreement to connect to the electricity network, covering both the transmission register (TEC) and the distribution register (Embedded). Filter by country, operator, technology, technology group, connection stage, network level, source register, matched substation and capacity range. Results come back largest capacity first, paged with `limit` and `offset`. The per-technology breakdown of a project is returned only by the single-entry endpoint.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"country":{"type":"string","description":"Return only projects in this country, as an ISO 3166-1 alpha-2 code.","example":"GB"},"operator":{"type":"string","description":"Return only projects handled by this network operator.","title":"OperatorCode","example":"ukpn"},"technologyType":{"type":"string","description":"Return only projects whose main technology is this one, for example 'solar' or 'battery'.","example":"solar"},"technologyCategory":{"type":"string","description":"Return only projects in this technology group: 'generation', 'storage', 'thermal', 'demand', 'infrastructure' or 'other'.","example":"generation"},"connectionStatus":{"type":"string","description":"Return only projects at this stage of the connection process, for example 'offer_accepted'.","example":"offer_accepted"},"networkLevel":{"type":"string","description":"Return only projects connecting at this level of the network: 'transmission', 'distribution', 'interconnector' or 'unknown'.","example":"transmission"},"sourceDataset":{"type":"string","description":"Return only projects from this register, for example 'neso_tec' or 'neso_embedded'.","example":"neso_tec"},"substationCode":{"type":"string","description":"Return only projects matched to this substation code."},"minCapacityMw":{"type":["number","null"],"description":"Return only projects with at least this much total capacity, in megawatts (MW).","example":10},"maxCapacityMw":{"type":["number","null"],"description":"Return only projects with at most this much total capacity, in megawatts (MW).","example":500},"limit":{"type":"number","minimum":1,"maximum":1000,"default":100,"description":"Maximum number of items to return. Defaults to 100. Minimum 1, maximum 1000."},"offset":{"type":["number","null"],"minimum":0,"default":0,"description":"Number of results to skip before the first one returned. Defaults to 0."}},"title":"ConnectionQueueSearchInput"}}}},"responses":{"200":{"description":"Matching connection queue projects, largest capacity first, with the total number of matches.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["connection_queue_entry"],"description":"Object type discriminator. Always `connection_queue_entry`."},"projectId":{"type":"string","description":"Identifier the source register gives the project.","example":"TEC-2024-001"},"projectNumber":{"type":["string","null"],"description":"Secondary reference number, where the register publishes one."},"projectName":{"type":["string","null"],"description":"Name of the project as published by the register.","example":"Greenfield Solar Farm"},"customerName":{"type":["string","null"],"description":"Customer or developer making the connection."},"operator":{"type":"string","description":"Network operator handling this connection.","title":"OperatorCode","example":"ukpn"},"operatingRegion":{"type":["string","null"],"description":"Licence area or region the connection sits in."},"country":{"type":"string","description":"Country the project is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"substationCode":{"type":["string","null"],"description":"Code of the substation the project connects at, once the published site name has been matched to one. Null where no match was made."},"connectionSite":{"type":["string","null"],"description":"Connection site name exactly as the register publishes it.","example":"Bankside 132kV Substation"},"technologyType":{"type":["string","null"],"description":"Main technology for the project, for example 'solar' or 'battery'.","example":"solar"},"technologyCategory":{"type":["string","null"],"description":"Group the main technology belongs to: 'generation', 'storage', 'thermal', 'demand', 'infrastructure' or 'other'."},"technologies":{"type":"array","items":{"type":"object","properties":{"technologyType":{"type":"string","description":"Technology used by this part of the project, for example 'solar' or 'battery'.","example":"solar"},"technologyCategory":{"type":["string","null"],"description":"Group the technology belongs to: 'generation', 'storage', 'thermal', 'demand', 'infrastructure' or 'other'."},"capacityMw":{"type":["number","null"],"description":"Capacity attributed to this technology, in megawatts (MW)."},"isPrimary":{"type":"boolean","description":"True when this is the project's main technology."}},"required":["technologyType","technologyCategory","capacityMw","isPrimary"],"description":"One technology within a project that combines several, such as solar with a co-located battery.","title":"ConnectionQueueTechnology"},"description":"One item for each technology the project combines. Returned only when fetching a single project by identifier."},"capacityMw":{"type":["number","null"],"description":"Total connection capacity for the project, in megawatts (MW).","example":50},"exportCapacityMw":{"type":["number","null"],"description":"Capacity the project may export to the network, in megawatts (MW)."},"importCapacityMw":{"type":["number","null"],"description":"Capacity the project may import from the network, in megawatts (MW)."},"networkLevel":{"type":["string","null"],"description":"Level of the network the project connects at. Known values are 'transmission', 'distribution', 'interconnector' and 'unknown'."},"connectionStatus":{"type":["string","null"],"description":"Stage the project has reached in the connection process, for example 'offer_accepted'.","example":"offer_accepted"},"queuePosition":{"type":["number","null"],"description":"Place in the queue, where the register publishes one."},"cumulativeCapacityMw":{"type":["number","null"],"description":"Combined capacity of every project ahead of this one in the queue, in megawatts (MW)."},"connectionDate":{"type":["string","null"],"description":"Date the project is contracted or expected to connect, as an ISO 8601 date."},"applicationDate":{"type":["string","null"],"description":"Date the connection application was submitted, as an ISO 8601 date."},"offerDate":{"type":["string","null"],"description":"Date the connection offer was made, as an ISO 8601 date."},"acceptanceDate":{"type":["string","null"],"description":"Date the connection offer was accepted, as an ISO 8601 date."},"sourceDataset":{"type":"string","description":"Register this entry came from, for example 'neso_tec' for the transmission register or 'neso_embedded' for the distribution register. A project identifier is unique only within one register.","example":"neso_tec"},"location":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Point location of the connection site, where the register gives one.","title":"Coordinates"}},"required":["object","projectId","projectNumber","projectName","customerName","operator","operatingRegion","country","substationCode","connectionSite","technologyType","technologyCategory","capacityMw","exportCapacityMw","importCapacityMw","networkLevel","connectionStatus","queuePosition","cumulativeCapacityMw","connectionDate","applicationDate","offerDate","acceptanceDate","sourceDataset","location"],"description":"A project in the grid connection queue, either waiting for or holding an agreement to connect to the electricity network. Covers transmission connections (the TEC Register) and distribution connections (the Embedded Register).","title":"ConnectionQueueEntry"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/energy/connection-queue/{projectId}":{"get":{"operationId":"getConnectionQueueEntry","x-speakeasy-name-override":"getConnectionQueueEntry","tags":["Energy"],"summary":"Get connection queue entry by project ID","description":"Returns one connection queue project by its identifier, including the `technologies` breakdown that lists each technology in a combined project, such as solar with a co-located battery. The same identifier can appear in both the transmission and distribution registers, so pass `sourceDataset` to choose which one to read.","parameters":[{"schema":{"type":"string","example":"TEC-2024-001","description":"Identifier the source register gives the project. The same identifier can appear in more than one register, so pair it with `sourceDataset` to pick one."},"required":true,"description":"Identifier the source register gives the project. The same identifier can appear in more than one register, so pair it with `sourceDataset` to pick one.","name":"projectId","in":"path"},{"schema":{"type":"string","description":"Read the project from this register, for example 'neso_tec' or 'neso_embedded'."},"required":false,"description":"Read the project from this register, for example 'neso_tec' or 'neso_embedded'.","name":"sourceDataset","in":"query"}],"responses":{"200":{"description":"The requested connection queue project, with its per-technology breakdown.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["connection_queue_entry"],"description":"Object type discriminator. Always `connection_queue_entry`."},"projectId":{"type":"string","description":"Identifier the source register gives the project.","example":"TEC-2024-001"},"projectNumber":{"type":["string","null"],"description":"Secondary reference number, where the register publishes one."},"projectName":{"type":["string","null"],"description":"Name of the project as published by the register.","example":"Greenfield Solar Farm"},"customerName":{"type":["string","null"],"description":"Customer or developer making the connection."},"operator":{"type":"string","description":"Network operator handling this connection.","title":"OperatorCode","example":"ukpn"},"operatingRegion":{"type":["string","null"],"description":"Licence area or region the connection sits in."},"country":{"type":"string","description":"Country the project is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"substationCode":{"type":["string","null"],"description":"Code of the substation the project connects at, once the published site name has been matched to one. Null where no match was made."},"connectionSite":{"type":["string","null"],"description":"Connection site name exactly as the register publishes it.","example":"Bankside 132kV Substation"},"technologyType":{"type":["string","null"],"description":"Main technology for the project, for example 'solar' or 'battery'.","example":"solar"},"technologyCategory":{"type":["string","null"],"description":"Group the main technology belongs to: 'generation', 'storage', 'thermal', 'demand', 'infrastructure' or 'other'."},"technologies":{"type":"array","items":{"type":"object","properties":{"technologyType":{"type":"string","description":"Technology used by this part of the project, for example 'solar' or 'battery'.","example":"solar"},"technologyCategory":{"type":["string","null"],"description":"Group the technology belongs to: 'generation', 'storage', 'thermal', 'demand', 'infrastructure' or 'other'."},"capacityMw":{"type":["number","null"],"description":"Capacity attributed to this technology, in megawatts (MW)."},"isPrimary":{"type":"boolean","description":"True when this is the project's main technology."}},"required":["technologyType","technologyCategory","capacityMw","isPrimary"],"description":"One technology within a project that combines several, such as solar with a co-located battery.","title":"ConnectionQueueTechnology"},"description":"One item for each technology the project combines. Returned only when fetching a single project by identifier."},"capacityMw":{"type":["number","null"],"description":"Total connection capacity for the project, in megawatts (MW).","example":50},"exportCapacityMw":{"type":["number","null"],"description":"Capacity the project may export to the network, in megawatts (MW)."},"importCapacityMw":{"type":["number","null"],"description":"Capacity the project may import from the network, in megawatts (MW)."},"networkLevel":{"type":["string","null"],"description":"Level of the network the project connects at. Known values are 'transmission', 'distribution', 'interconnector' and 'unknown'."},"connectionStatus":{"type":["string","null"],"description":"Stage the project has reached in the connection process, for example 'offer_accepted'.","example":"offer_accepted"},"queuePosition":{"type":["number","null"],"description":"Place in the queue, where the register publishes one."},"cumulativeCapacityMw":{"type":["number","null"],"description":"Combined capacity of every project ahead of this one in the queue, in megawatts (MW)."},"connectionDate":{"type":["string","null"],"description":"Date the project is contracted or expected to connect, as an ISO 8601 date."},"applicationDate":{"type":["string","null"],"description":"Date the connection application was submitted, as an ISO 8601 date."},"offerDate":{"type":["string","null"],"description":"Date the connection offer was made, as an ISO 8601 date."},"acceptanceDate":{"type":["string","null"],"description":"Date the connection offer was accepted, as an ISO 8601 date."},"sourceDataset":{"type":"string","description":"Register this entry came from, for example 'neso_tec' for the transmission register or 'neso_embedded' for the distribution register. A project identifier is unique only within one register.","example":"neso_tec"},"location":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Point location of the connection site, where the register gives one.","title":"Coordinates"}},"required":["object","projectId","projectNumber","projectName","customerName","operator","operatingRegion","country","substationCode","connectionSite","technologyType","technologyCategory","capacityMw","exportCapacityMw","importCapacityMw","networkLevel","connectionStatus","queuePosition","cumulativeCapacityMw","connectionDate","applicationDate","offerDate","acceptanceDate","sourceDataset","location"],"description":"A project in the grid connection queue, either waiting for or holding an agreement to connect to the electricity network. Covers transmission connections (the TEC Register) and distribution connections (the Embedded Register).","title":"ConnectionQueueEntry"}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/energy/substations/{code}/connection-queue":{"get":{"operationId":"getConnectionQueueBySubstation","x-speakeasy-name-override":"getConnectionQueueBySubstation","tags":["Energy"],"summary":"Get connection queue entries for a substation","description":"Returns every connection queue project matched to this substation, from both the transmission register (TEC) and the distribution register (Embedded), largest capacity first. Use it to see how much of a substation's remaining headroom is already spoken for.","parameters":[{"schema":{"type":"string","example":"ukpn:PRI-1234","description":"Code of the substation, prefixed with the operator code."},"required":true,"description":"Code of the substation, prefixed with the operator code.","name":"code","in":"path"}],"responses":{"200":{"description":"Connection queue projects at the substation, largest capacity first.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["connection_queue_entry"],"description":"Object type discriminator. Always `connection_queue_entry`."},"projectId":{"type":"string","description":"Identifier the source register gives the project.","example":"TEC-2024-001"},"projectNumber":{"type":["string","null"],"description":"Secondary reference number, where the register publishes one."},"projectName":{"type":["string","null"],"description":"Name of the project as published by the register.","example":"Greenfield Solar Farm"},"customerName":{"type":["string","null"],"description":"Customer or developer making the connection."},"operator":{"type":"string","description":"Network operator handling this connection.","title":"OperatorCode","example":"ukpn"},"operatingRegion":{"type":["string","null"],"description":"Licence area or region the connection sits in."},"country":{"type":"string","description":"Country the project is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"substationCode":{"type":["string","null"],"description":"Code of the substation the project connects at, once the published site name has been matched to one. Null where no match was made."},"connectionSite":{"type":["string","null"],"description":"Connection site name exactly as the register publishes it.","example":"Bankside 132kV Substation"},"technologyType":{"type":["string","null"],"description":"Main technology for the project, for example 'solar' or 'battery'.","example":"solar"},"technologyCategory":{"type":["string","null"],"description":"Group the main technology belongs to: 'generation', 'storage', 'thermal', 'demand', 'infrastructure' or 'other'."},"technologies":{"type":"array","items":{"type":"object","properties":{"technologyType":{"type":"string","description":"Technology used by this part of the project, for example 'solar' or 'battery'.","example":"solar"},"technologyCategory":{"type":["string","null"],"description":"Group the technology belongs to: 'generation', 'storage', 'thermal', 'demand', 'infrastructure' or 'other'."},"capacityMw":{"type":["number","null"],"description":"Capacity attributed to this technology, in megawatts (MW)."},"isPrimary":{"type":"boolean","description":"True when this is the project's main technology."}},"required":["technologyType","technologyCategory","capacityMw","isPrimary"],"description":"One technology within a project that combines several, such as solar with a co-located battery.","title":"ConnectionQueueTechnology"},"description":"One item for each technology the project combines. Returned only when fetching a single project by identifier."},"capacityMw":{"type":["number","null"],"description":"Total connection capacity for the project, in megawatts (MW).","example":50},"exportCapacityMw":{"type":["number","null"],"description":"Capacity the project may export to the network, in megawatts (MW)."},"importCapacityMw":{"type":["number","null"],"description":"Capacity the project may import from the network, in megawatts (MW)."},"networkLevel":{"type":["string","null"],"description":"Level of the network the project connects at. Known values are 'transmission', 'distribution', 'interconnector' and 'unknown'."},"connectionStatus":{"type":["string","null"],"description":"Stage the project has reached in the connection process, for example 'offer_accepted'.","example":"offer_accepted"},"queuePosition":{"type":["number","null"],"description":"Place in the queue, where the register publishes one."},"cumulativeCapacityMw":{"type":["number","null"],"description":"Combined capacity of every project ahead of this one in the queue, in megawatts (MW)."},"connectionDate":{"type":["string","null"],"description":"Date the project is contracted or expected to connect, as an ISO 8601 date."},"applicationDate":{"type":["string","null"],"description":"Date the connection application was submitted, as an ISO 8601 date."},"offerDate":{"type":["string","null"],"description":"Date the connection offer was made, as an ISO 8601 date."},"acceptanceDate":{"type":["string","null"],"description":"Date the connection offer was accepted, as an ISO 8601 date."},"sourceDataset":{"type":"string","description":"Register this entry came from, for example 'neso_tec' for the transmission register or 'neso_embedded' for the distribution register. A project identifier is unique only within one register.","example":"neso_tec"},"location":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Point location of the connection site, where the register gives one.","title":"Coordinates"}},"required":["object","projectId","projectNumber","projectName","customerName","operator","operatingRegion","country","substationCode","connectionSite","technologyType","technologyCategory","capacityMw","exportCapacityMw","importCapacityMw","networkLevel","connectionStatus","queuePosition","cumulativeCapacityMw","connectionDate","applicationDate","offerDate","acceptanceDate","sourceDataset","location"],"description":"A project in the grid connection queue, either waiting for or holding an agreement to connect to the electricity network. Covers transmission connections (the TEC Register) and distribution connections (the Embedded Register).","title":"ConnectionQueueEntry"},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One page of results, with the metadata needed to fetch the rest."}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/energy/by-property/{locationId}":{"get":{"operationId":"getEnergyForProperty","x-speakeasy-name-override":"getByProperty","tags":["Energy"],"summary":"Get energy infrastructure for a property","description":"Resolves a property's coordinates to the supply area and substation that serve it, then returns that substation's current capacity and headroom, its capacity history, the generation and storage registered against it, the projects queued to connect to it, and its future scenario projections. The `lat` and `lon` query parameters are required and carry the property's coordinates in WGS84 decimal degrees. Use `include` to ask for only the layers you need; all of them are returned by default.","parameters":[{"schema":{"type":"string","example":"100023336956","description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN)."},"required":true,"description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN).","name":"locationId","in":"path"},{"schema":{"type":["number","null"],"minimum":-90,"maximum":90,"description":"Latitude of the property, in WGS84 decimal degrees.","example":51.5074},"required":false,"description":"Latitude of the property, in WGS84 decimal degrees.","name":"lat","in":"query"},{"schema":{"type":["number","null"],"minimum":-180,"maximum":180,"description":"Longitude of the property, in WGS84 decimal degrees.","example":-0.1278},"required":false,"description":"Longitude of the property, in WGS84 decimal degrees.","name":"lon","in":"query"},{"schema":{"type":"string","description":"Comma-separated list of the layers to return: `supplyArea`, `substation`, `capacity`, `ecr`, `dfes` and `connections`. Every layer is returned when the parameter is omitted. Names that are not layers are ignored, but at least one recognised layer must be present.","example":"substation,capacity,ecr"},"required":false,"description":"Comma-separated list of the layers to return: `supplyArea`, `substation`, `capacity`, `ecr`, `dfes` and `connections`. Every layer is returned when the parameter is omitted. Names that are not layers are ignored, but at least one recognised layer must be present.","name":"include","in":"query"}],"responses":{"200":{"description":"The energy infrastructure serving the property, limited to the requested layers.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["energy_for_property"],"description":"Object type discriminator. Always `energy_for_property`."},"locationId":{"type":"string","description":"Identifier for a single addressable location. In Great Britain this is the Unique Property Reference Number (UPRN).","example":"100023336956"},"country":{"type":["string","null"],"description":"Country of the infrastructure serving this location, as an ISO 3166-1 alpha-2 code. Null when neither a supply area nor a substation could be resolved.","example":"GB"},"supplyArea":{"type":["object","null"],"properties":{"object":{"type":"string","enum":["supply_area"],"description":"Object type discriminator. Always `supply_area`."},"code":{"type":"string","description":"Code identifying the supply area, prefixed with the operator code.","example":"ukpn:SA-001"},"name":{"type":["string","null"],"description":"Name of the supply area, where the operator publishes one."},"operator":{"type":"string","description":"Network operator that manages this supply area.","title":"OperatorCode","example":"ukpn"},"operatingRegion":{"type":["string","null"],"description":"Licence area or region the operator assigns this area to."},"country":{"type":"string","description":"Country the supply area is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"areaType":{"type":["string","null"],"description":"Level of the network hierarchy this boundary sits at. Known values are 'gsp', 'bsp', 'grid', 'primary', 'distribution'. A 'distribution' area covers the least ground and a grid supply point ('gsp') area the most.","title":"SupplyAreaType"},"substationCode":{"type":["string","null"],"description":"Code of the substation that serves this area."},"areaSqkm":{"type":["number","null"],"description":"Size of the area, in square kilometres."},"centroid":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Centre point of the area.","title":"Coordinates"}},"required":["object","code","name","operator","operatingRegion","country","areaType","substationCode","areaSqkm","centroid"],"description":"Supply area boundary containing this location. Null when the coordinates fall outside every known boundary. Returned only when `supplyArea` is among the requested layers.","title":"SupplyArea"},"substation":{"type":["object","null"],"properties":{"object":{"type":"string","enum":["substation"],"description":"Object type discriminator. Always `substation`."},"code":{"type":"string","description":"Code identifying the substation, prefixed with the operator code.","example":"ukpn:PRI-1234"},"name":{"type":["string","null"],"description":"Name of the substation, where the operator publishes one.","example":"Bankside Primary"},"operator":{"type":"string","description":"Network operator that owns and runs this substation.","title":"OperatorCode","example":"ukpn"},"operatingRegion":{"type":["string","null"],"description":"Licence area or region the operator assigns this substation to.","example":"UKPN (SPN)"},"country":{"type":"string","description":"Country the substation is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"parentSubstationCode":{"type":["string","null"],"description":"Code of the substation one level up the hierarchy, such as the grid substation feeding a primary. Null where no parent is recorded.","example":"ukpn:GRD-100"},"substationType":{"type":["string","null"],"description":"Where this substation sits in the network hierarchy. Known values are 'gsp', 'bulk_supply', 'grid', 'primary', 'distribution'.","title":"SubstationType"},"voltageKv":{"type":["number","null"],"description":"Operating voltage, in kilovolts (kV).","example":33},"location":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Point location of the substation.","title":"Coordinates"},"demandMw":{"type":["number","null"],"description":"Peak electricity demand currently met by this substation, in megawatts (MW).","example":12.5},"firmCapacityMw":{"type":["number","null"],"description":"Capacity the substation can supply under all operating conditions, in megawatts (MW).","example":20},"demandHeadroomMw":{"type":["number","null"],"description":"Spare capacity for new demand connections, in megawatts (MW). Can be negative where there is no spare capacity left.","example":7.5},"generationHeadroomMw":{"type":["number","null"],"description":"Spare capacity for new generation connections, such as solar or wind, in megawatts (MW).","example":5},"reversePowerCapacityMw":{"type":["number","null"],"description":"Capacity for power flowing back up the network when generation exceeds local demand, in megawatts (MW)."},"utilisationPct":{"type":["number","null"],"description":"How much of the substation's capacity is in use, as a percentage. Higher values leave less room for new connections.","example":62.5}},"required":["object","code","name","operator","operatingRegion","country","parentSubstationCode","substationType","voltageKv","location","demandMw","firmCapacityMw","demandHeadroomMw","generationHeadroomMw","reversePowerCapacityMw","utilisationPct"],"description":"Substation serving this location, with its current capacity and headroom. Null when no serving substation could be resolved. Returned only when `substation` is among the requested layers.","title":"Substation"},"capacitySnapshots":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["capacity_snapshot"],"description":"Object type discriminator. Always `capacity_snapshot`."},"substationCode":{"type":"string","description":"Code of the substation this snapshot describes.","example":"ukpn:PRI-1234"},"snapshotDate":{"type":"string","description":"Date the snapshot describes, as an ISO 8601 date. Snapshots are typically published quarterly.","example":"2025-01-01"},"snapshotSource":{"type":"string","description":"Identifier for the published dataset this snapshot was taken from.","example":"ltds_2025"},"demandMw":{"type":["number","null"],"description":"Peak demand at the snapshot date, in megawatts (MW)."},"firmCapacityMw":{"type":["number","null"],"description":"Firm capacity at the snapshot date, in megawatts (MW)."},"demandHeadroomMw":{"type":["number","null"],"description":"Spare capacity for new demand connections at the snapshot date, in megawatts (MW)."},"generationHeadroomMw":{"type":["number","null"],"description":"Spare capacity for new generation connections at the snapshot date, in megawatts (MW)."},"utilisationPct":{"type":["number","null"],"description":"How much of the substation's capacity was in use at the snapshot date, as a percentage."},"batteryHeadroomMw":{"type":["number","null"],"description":"Spare capacity specific to battery connections, in megawatts (MW). Not published by every operator."},"evHeadroomMw":{"type":["number","null"],"description":"Spare capacity specific to electric vehicle charging connections, in megawatts (MW). Not published by every operator."},"solarHeadroomMw":{"type":["number","null"],"description":"Spare capacity specific to solar connections, in megawatts (MW). Not published by every operator."}},"required":["object","substationCode","snapshotDate","snapshotSource","demandMw","firmCapacityMw","demandHeadroomMw","generationHeadroomMw","utilisationPct","batteryHeadroomMw","evHeadroomMw","solarHeadroomMw"],"description":"Substation capacity and headroom as they stood on one date. Compare snapshots to see how available capacity is moving.","title":"CapacitySnapshot"},"description":"Capacity snapshots for the serving substation, oldest first. Returned only when `capacity` is among the requested layers, and empty when no substation was resolved."},"ecrEntries":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["ecr_entry"],"description":"Object type discriminator. Always `ecr_entry`."},"code":{"type":"string","description":"Code identifying this register entry, unique for a given operator.","example":"ukpn:ECR-5678"},"operator":{"type":"string","description":"Network operator that publishes this entry.","title":"OperatorCode","example":"ukpn"},"operatingRegion":{"type":["string","null"],"description":"Licence area or region the connection sits in."},"country":{"type":"string","description":"Country the connection is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"substationCode":{"type":["string","null"],"description":"Code of the substation the connection is registered against."},"connectionType":{"type":["string","null"],"description":"Whether the site generates, stores, or does both.","title":"ConnectionType","example":"generation"},"technologyType":{"type":["string","null"],"description":"Technology the site uses, for example 'solar', 'wind' or 'battery'.","example":"solar"},"installedCapacityMw":{"type":["number","null"],"description":"Capacity installed at the site, in megawatts (MW).","example":5},"exportCapacityMw":{"type":["number","null"],"description":"Capacity the site may export to the network, in megawatts (MW), as agreed with the operator."},"connectionStatus":{"type":["string","null"],"description":"Stage this connection has reached. Known values are 'connected', 'accepted', 'contracted', 'in_scoping'.","title":"ConnectionStatus","example":"connected"},"connectionDate":{"type":["string","null"],"description":"Date the site connected, or is expected to connect, as an ISO 8601 date."},"location":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Point location of the generation or storage site.","title":"Coordinates"}},"required":["object","code","operator","operatingRegion","country","substationCode","connectionType","technologyType","installedCapacityMw","exportCapacityMw","connectionStatus","connectionDate","location"],"description":"An entry in the Embedded Capacity Register (ECR), the public record of generation and storage connected to the distribution network.","title":"EcrEntry"},"description":"Generation and storage connections registered against the serving substation, largest installed capacity first. Returned only when `ecr` is among the requested layers."},"dfesForecasts":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["dfes_forecast"],"description":"Object type discriminator. Always `dfes_forecast`."},"operator":{"type":"string","description":"Network operator that published this forecast.","title":"OperatorCode","example":"ukpn"},"operatingRegion":{"type":"string","description":"Licence area or region the forecast covers."},"country":{"type":"string","description":"Country the forecast covers, as an ISO 3166-1 alpha-2 code.","example":"GB"},"substationCode":{"type":["string","null"],"description":"Code of the substation the forecast covers. Null where the forecast covers a whole region rather than a single substation."},"scenario":{"type":"string","description":"Planning scenario this projection follows. Known values are 'leading_the_way', 'consumer_transformation', 'system_transformation', 'falling_short', 'best_view', 'holistic_transition'.","title":"ForecastScenario","example":"best_view"},"year":{"type":"number","description":"Year the projection applies to.","example":2030},"technologyType":{"type":["string","null"],"description":"Technology being projected, for example 'solar', 'heat_pump' or 'battery'."},"forecastMw":{"type":["number","null"],"description":"Projected value for this scenario, year and technology, in megawatts (MW)."},"forecastType":{"type":"string","description":"Whether the row projects demand, generation or storage capacity.","title":"ForecastType","example":"demand"}},"required":["object","operator","operatingRegion","country","substationCode","scenario","year","technologyType","forecastMw","forecastType"],"description":"One projection from an energy planning framework, such as the Distribution Future Energy Scenarios (DFES) in Great Britain, covering a single scenario, year and technology.","title":"DfesForecast"},"description":"Energy scenario projections for the serving substation. Returned only when `dfes` is among the requested layers."},"connectionQueueEntries":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["connection_queue_entry"],"description":"Object type discriminator. Always `connection_queue_entry`."},"projectId":{"type":"string","description":"Identifier the source register gives the project.","example":"TEC-2024-001"},"projectNumber":{"type":["string","null"],"description":"Secondary reference number, where the register publishes one."},"projectName":{"type":["string","null"],"description":"Name of the project as published by the register.","example":"Greenfield Solar Farm"},"customerName":{"type":["string","null"],"description":"Customer or developer making the connection."},"operator":{"type":"string","description":"Network operator handling this connection.","title":"OperatorCode","example":"ukpn"},"operatingRegion":{"type":["string","null"],"description":"Licence area or region the connection sits in."},"country":{"type":"string","description":"Country the project is in, as an ISO 3166-1 alpha-2 code.","example":"GB"},"substationCode":{"type":["string","null"],"description":"Code of the substation the project connects at, once the published site name has been matched to one. Null where no match was made."},"connectionSite":{"type":["string","null"],"description":"Connection site name exactly as the register publishes it.","example":"Bankside 132kV Substation"},"technologyType":{"type":["string","null"],"description":"Main technology for the project, for example 'solar' or 'battery'.","example":"solar"},"technologyCategory":{"type":["string","null"],"description":"Group the main technology belongs to: 'generation', 'storage', 'thermal', 'demand', 'infrastructure' or 'other'."},"technologies":{"type":"array","items":{"type":"object","properties":{"technologyType":{"type":"string","description":"Technology used by this part of the project, for example 'solar' or 'battery'.","example":"solar"},"technologyCategory":{"type":["string","null"],"description":"Group the technology belongs to: 'generation', 'storage', 'thermal', 'demand', 'infrastructure' or 'other'."},"capacityMw":{"type":["number","null"],"description":"Capacity attributed to this technology, in megawatts (MW)."},"isPrimary":{"type":"boolean","description":"True when this is the project's main technology."}},"required":["technologyType","technologyCategory","capacityMw","isPrimary"],"description":"One technology within a project that combines several, such as solar with a co-located battery.","title":"ConnectionQueueTechnology"},"description":"One item for each technology the project combines. Returned only when fetching a single project by identifier."},"capacityMw":{"type":["number","null"],"description":"Total connection capacity for the project, in megawatts (MW).","example":50},"exportCapacityMw":{"type":["number","null"],"description":"Capacity the project may export to the network, in megawatts (MW)."},"importCapacityMw":{"type":["number","null"],"description":"Capacity the project may import from the network, in megawatts (MW)."},"networkLevel":{"type":["string","null"],"description":"Level of the network the project connects at. Known values are 'transmission', 'distribution', 'interconnector' and 'unknown'."},"connectionStatus":{"type":["string","null"],"description":"Stage the project has reached in the connection process, for example 'offer_accepted'.","example":"offer_accepted"},"queuePosition":{"type":["number","null"],"description":"Place in the queue, where the register publishes one."},"cumulativeCapacityMw":{"type":["number","null"],"description":"Combined capacity of every project ahead of this one in the queue, in megawatts (MW)."},"connectionDate":{"type":["string","null"],"description":"Date the project is contracted or expected to connect, as an ISO 8601 date."},"applicationDate":{"type":["string","null"],"description":"Date the connection application was submitted, as an ISO 8601 date."},"offerDate":{"type":["string","null"],"description":"Date the connection offer was made, as an ISO 8601 date."},"acceptanceDate":{"type":["string","null"],"description":"Date the connection offer was accepted, as an ISO 8601 date."},"sourceDataset":{"type":"string","description":"Register this entry came from, for example 'neso_tec' for the transmission register or 'neso_embedded' for the distribution register. A project identifier is unique only within one register.","example":"neso_tec"},"location":{"type":["object","null"],"properties":{"lat":{"type":"number","minimum":-90,"maximum":90,"description":"Latitude in WGS84 decimal degrees.","example":51.5074},"lng":{"type":"number","minimum":-180,"maximum":180,"description":"Longitude in WGS84 decimal degrees.","example":-0.1278}},"required":["lat","lng"],"additionalProperties":false,"description":"Point location of the connection site, where the register gives one.","title":"Coordinates"}},"required":["object","projectId","projectNumber","projectName","customerName","operator","operatingRegion","country","substationCode","connectionSite","technologyType","technologyCategory","capacityMw","exportCapacityMw","importCapacityMw","networkLevel","connectionStatus","queuePosition","cumulativeCapacityMw","connectionDate","applicationDate","offerDate","acceptanceDate","sourceDataset","location"],"description":"A project in the grid connection queue, either waiting for or holding an agreement to connect to the electricity network. Covers transmission connections (the TEC Register) and distribution connections (the Embedded Register).","title":"ConnectionQueueEntry"},"description":"Connection queue projects at the serving substation, largest capacity first. Returned only when `connections` is among the requested layers."}},"required":["object","locationId","country"],"description":"The energy infrastructure serving one property: the supply area and substation resolved from its coordinates, plus that substation's capacity history, registered connections, queue entries and scenario projections. Use the `include` query parameter to choose the layers; all of them are returned by default.","title":"EnergyForProperty"}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"403":{"description":"The API key is valid but does not have access to this resource.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"429":{"description":"Too many requests. Retry after the interval given in the Retry-After header.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"The query timed out or the service is briefly overloaded. Retry, with fewer layers in `include` if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/air-quality/query":{"post":{"operationId":"queryAirQuality","x-speakeasy-name-override":"query","tags":["Air Quality"],"summary":"Query air quality at one or more locations","description":"Returns air quality for one or more areas, given as a point (with a radius, or radius 0 for the nearest 1 km cell only), a postcode, an outward code, a bounding box or a polygon. Up to ten areas can be combined in one request, and their results are deduplicated by `airQualityId`. Every cell carries the score and band, the pollutant concentrations with their compliance against each standard, the published indices, the regulator-defined zones containing it, and provenance. `nearestRoad`, `nearestMotorway` and `installations` are returned only on licences carrying the `airQualityPremium` permission. For a single property, use `/v1/air-quality/point` instead.","requestBody":{"description":"The areas to search, and any filters, sorting and attribute selection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirQualityQueryRequest"}}}},"responses":{"200":{"description":"The air-quality cells matching the search areas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirQualityListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"The postcode or outward code could not be resolved to a location.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"No published air-quality snapshot is available to read. Retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/air-quality/point":{"post":{"operationId":"queryAirQualityPoint","x-speakeasy-name-override":"point","tags":["Air Quality"],"summary":"Get air quality at an exact coordinate","description":"Returns air quality at one latitude and longitude. It reads the 1 km cell the point falls in, then measures the exact distances to the nearest road, the nearest motorway, nearby regulated installations and the regulatory zones, and applies a versioned decay model so the pollutant concentrations reflect the point rather than the whole cell. Reach for this route for decisions about a single property, and for `/v1/air-quality/query` for neighbourhood-scale lookups. The response is the same shape as that route's, plus `coordinate`, `cellId` and `decay`. `nearestRoad`, `nearestMotorway`, `installations` and the calculation trail in `decay.calculation` are returned only on licences carrying the `airQualityPremium` permission.","requestBody":{"description":"The coordinate to read, and any attribute selection, options and snapshot pin.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirQualityPointRequest"}}}},"responses":{"200":{"description":"The air quality at the coordinate, with the decay overlay applied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AirQualityPointResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"The coordinate falls outside the modelled air-quality coverage.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"No published air-quality snapshot is available to read. Retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/flood-risk/point":{"post":{"operationId":"queryFloodRiskPoint","x-speakeasy-name-override":"point","tags":["Flood Risk"],"summary":"Assess flood risk at a coordinate","description":"Returns the flood risk at one latitude and longitude, from the Environment Agency National Flood Risk Assessment 2. Rivers and sea (with the depth if it floods) and surface water (with hazard and flow velocity) are reported separately, alongside the present-day risk and, where it differs, the 2080 climate projection. The planning flood zone and nearby defences are included when the point has them. Read `dataAvailability` on every response before reading the bands: it says whether the point was assessed, sits outside every modelled flood extent, or is not yet covered, and `overallRiskLevel` is null rather than reassuring wherever no assessment was possible.","requestBody":{"description":"The coordinate to assess, and optionally which scenarios to include.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FloodRiskPointRequest"}}}},"responses":{"200":{"description":"The flood-risk assessment for the coordinate.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FloodRiskPoint"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"The flood-risk data could not be read, so no assessment is returned rather than an incomplete one. Retry.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/transactions/query":{"post":{"operationId":"queryTransactions","x-speakeasy-name-override":"queryTransactions","tags":["Transactions"],"summary":"Search property transactions","description":"Searches completed sales and lease grants by geographic area, structured field conditions and sort order, narrowing each record to the fields named in `attributes` when one is given. Results are cursor-paginated, up to 100 per page. Monetary values are in the minor unit of their currency, so pence for GBP.","requestBody":{"description":"The areas, field conditions, ordering, fields and page size to search with.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionQueryRequest"}}}},"responses":{"200":{"description":"Transactions matching the search, with a cursor for the next page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionsListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/transactions/{id}":{"get":{"operationId":"getTransactionById","x-speakeasy-name-override":"getTransactionById","tags":["Transactions"],"summary":"Get a transaction by id","description":"Returns one transaction by the composite id that search results carry. An id whose provider segment names a source that is not currently served returns a 404.","parameters":[{"schema":{"type":"string","description":"Identifier for the transaction, formed as `{country}:{provider}:{externalId}`."},"required":true,"description":"Identifier for the transaction, formed as `{country}:{provider}:{externalId}`.","name":"id","in":"path"}],"responses":{"200":{"description":"The transaction.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Transaction"}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/transactions/by-uprn/{uprn}":{"get":{"operationId":"getTransactionsByUprn","x-speakeasy-name-override":"getTransactionsByUprn","tags":["Transactions"],"summary":"Get transactions for a UPRN","description":"Returns the transactions matched to one addressable location, newest first. Results are cursor-paginated, up to 100 per page.","parameters":[{"schema":{"type":"string","description":"The Unique Property Reference Number (UPRN) to return transactions for."},"required":true,"description":"The Unique Property Reference Number (UPRN) to return transactions for.","name":"uprn","in":"path"},{"schema":{"type":"number","minimum":1,"maximum":100,"description":"Maximum number of transactions to return. Minimum 1, maximum 100."},"required":false,"description":"Maximum number of transactions to return. Minimum 1, maximum 100.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Opaque cursor from the `next_cursor` of a previous response."},"required":false,"description":"Opaque cursor from the `next_cursor` of a previous response.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Transactions matched to that location, with a cursor for the next page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionsListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/census/catalog/{datasetCode}":{"get":{"operationId":"getCensusCatalog","x-speakeasy-name-override":"getCatalog","tags":["Census"],"summary":"Get the census catalogue for a dataset","description":"Lists every category in the dataset and the geography levels it can be served at. Use it to find the `categoryCode` values the tile, whole-country and breaks endpoints take.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":50,"description":"Identifier for a census dataset: one nation's census at one vintage. The datasets endpoint lists the codes in service.","example":"ew-2021"},"required":true,"description":"Identifier for a census dataset: one nation's census at one vintage. The datasets endpoint lists the codes in service.","name":"datasetCode","in":"path"}],"responses":{"200":{"description":"Every category in the dataset, with the geography levels each can be served at.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"categoryCode":{"type":"string","description":"Identifier for a single category, formed as `{classificationCode}-{NNN}`.","example":"ts054-002"},"categoryName":{"type":"string","description":"The category's published label.","example":"Owned: Owns outright"},"classificationCode":{"type":"string","description":"Identifier for the classification this category belongs to.","example":"ts054"},"isDefault":{"type":"boolean","description":"True when this category belongs to the variable's default classification."},"variableCode":{"type":"string","description":"Code for the variable this category belongs to, as published by the census.","example":"TS054"},"variableSlug":{"type":"string","description":"Identifier for the variable this category belongs to, used as the `slug` path parameter.","example":"tenure"},"availableGeotypes":{"type":"array","items":{"type":"string"},"description":"The geography levels this category can be requested at. Asking for a level outside this list returns a 404.","example":["lsoa","lad","region","country"]}},"required":["categoryCode","categoryName","classificationCode","isDefault","variableCode","variableSlug","availableGeotypes"],"description":"One catalogue entry: a category, the variable and classification it belongs to, and where it can be served."},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"Every category in the dataset, with the variable, classification and geography levels of each."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/census/datasets":{"get":{"operationId":"listCensusDatasets","x-speakeasy-name-override":"listDatasets","tags":["Census"],"summary":"List census datasets","description":"Lists the census datasets available, one per nation and vintage. Only the current release for each nation is returned.","responses":{"200":{"description":"The census datasets in service.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"datasetCode":{"type":"string","description":"Identifier for this dataset, used as the `datasetCode` path parameter.","example":"ew-2021"},"countryCode":{"type":"string","description":"Country the dataset covers, as an ISO 3166-1 alpha-3 code.","example":"GBR"},"censusCountry":{"type":"string","description":"Which nation the dataset covers, for example 'ew', 'sco' or 'ni'.","example":"ew"},"censusYear":{"type":"integer","description":"The year the census was taken.","example":2021},"referenceDate":{"type":"string","description":"The census's official reference date, as an ISO 8601 date.","example":"2021-03-21"},"version":{"type":"string","description":"Release version of this dataset.","example":"2026.1"},"isCurrent":{"type":"boolean","description":"True when this is the current release for the nation."},"methodology":{"type":["string","null"],"description":"Notes on how the dataset was produced. Null when the dataset carries none."}},"required":["datasetCode","countryCode","censusCountry","censusYear","referenceDate","version","isCurrent","methodology"],"description":"One census dataset: a single nation's census at one vintage."},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"The census datasets in service, one per nation and vintage."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/census/datasets/{datasetCode}":{"get":{"operationId":"getCensusDataset","x-speakeasy-name-override":"getDataset","tags":["Census"],"summary":"Get a census dataset","description":"Returns one census dataset by its code. Only the current release for each nation is served.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":50,"description":"Identifier for a census dataset: one nation's census at one vintage. The datasets endpoint lists the codes in service.","example":"ew-2021"},"required":true,"description":"Identifier for a census dataset: one nation's census at one vintage. The datasets endpoint lists the codes in service.","name":"datasetCode","in":"path"}],"responses":{"200":{"description":"The requested census dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"datasetCode":{"type":"string","description":"Identifier for this dataset, used as the `datasetCode` path parameter.","example":"ew-2021"},"countryCode":{"type":"string","description":"Country the dataset covers, as an ISO 3166-1 alpha-3 code.","example":"GBR"},"censusCountry":{"type":"string","description":"Which nation the dataset covers, for example 'ew', 'sco' or 'ni'.","example":"ew"},"censusYear":{"type":"integer","description":"The year the census was taken.","example":2021},"referenceDate":{"type":"string","description":"The census's official reference date, as an ISO 8601 date.","example":"2021-03-21"},"version":{"type":"string","description":"Release version of this dataset.","example":"2026.1"},"isCurrent":{"type":"boolean","description":"True when this is the current release for the nation."},"methodology":{"type":["string","null"],"description":"Notes on how the dataset was produced. Null when the dataset carries none."}},"required":["datasetCode","countryCode","censusCountry","censusYear","referenceDate","version","isCurrent","methodology"],"description":"The requested census dataset."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/census/datasets/{datasetCode}/variables":{"get":{"operationId":"listCensusVariables","x-speakeasy-name-override":"listVariables","tags":["Census"],"summary":"List census variables for a dataset","description":"Lists the variables (census topics) published in a dataset. Variables that carry no data at any geography level are left out, and at most 25 are returned.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":50,"description":"Identifier for a census dataset: one nation's census at one vintage. The datasets endpoint lists the codes in service.","example":"ew-2021"},"required":true,"description":"Identifier for a census dataset: one nation's census at one vintage. The datasets endpoint lists the codes in service.","name":"datasetCode","in":"path"}],"responses":{"200":{"description":"The variables published in the dataset.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"variableCode":{"type":"string","description":"Code for the variable as published by the census.","example":"TS054"},"variableSlug":{"type":"string","description":"Identifier for the variable, used as the `slug` path parameter.","example":"tenure"},"variableName":{"type":"string","description":"The variable's published name.","example":"Tenure"},"variableGroup":{"type":["string","null"],"description":"The catalogue topic the variable sits under. Null when it belongs to none.","example":"Housing"},"populationBase":{"type":["string","null"],"description":"The population the variable is measured against, such as all usual residents. Null when the source does not state one."},"description":{"type":["string","null"],"description":"Human-readable explanation of what the variable measures. Null when none is published."},"displayOrder":{"type":["integer","null"],"description":"Position of the variable within its catalogue topic, for ordering a list. Null when unset."}},"required":["variableCode","variableSlug","variableName","variableGroup","populationBase","description","displayOrder"],"description":"One census variable: a census topic, published at one or more classifications."},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"The variables published in the dataset."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/census/datasets/{datasetCode}/variables/{slug}":{"get":{"operationId":"getCensusVariable","x-speakeasy-name-override":"getVariable","tags":["Census"],"summary":"Get a census variable","description":"Returns one variable in a dataset by its slug.","parameters":[{"schema":{"type":"string","description":"Identifier for a census dataset: one nation's census at one vintage.","example":"ew-2021"},"required":true,"description":"Identifier for a census dataset: one nation's census at one vintage.","name":"datasetCode","in":"path"},{"schema":{"type":"string","description":"Identifier for a variable within the dataset, as returned by the variables endpoint.","example":"tenure"},"required":true,"description":"Identifier for a variable within the dataset, as returned by the variables endpoint.","name":"slug","in":"path"}],"responses":{"200":{"description":"The requested census variable.","content":{"application/json":{"schema":{"type":"object","properties":{"variableCode":{"type":"string","description":"Code for the variable as published by the census.","example":"TS054"},"variableSlug":{"type":"string","description":"Identifier for the variable, used as the `slug` path parameter.","example":"tenure"},"variableName":{"type":"string","description":"The variable's published name.","example":"Tenure"},"variableGroup":{"type":["string","null"],"description":"The catalogue topic the variable sits under. Null when it belongs to none.","example":"Housing"},"populationBase":{"type":["string","null"],"description":"The population the variable is measured against, such as all usual residents. Null when the source does not state one."},"description":{"type":["string","null"],"description":"Human-readable explanation of what the variable measures. Null when none is published."},"displayOrder":{"type":["integer","null"],"description":"Position of the variable within its catalogue topic, for ordering a list. Null when unset."}},"required":["variableCode","variableSlug","variableName","variableGroup","populationBase","description","displayOrder"],"description":"The requested census variable."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/census/datasets/{datasetCode}/classifications/{classificationCode}":{"get":{"operationId":"getCensusClassification","x-speakeasy-name-override":"getClassification","tags":["Census"],"summary":"Get a census classification","description":"Returns one classification of a variable: a single level of detail the variable is published at, with the geography levels it is served at.","parameters":[{"schema":{"type":"string","description":"Identifier for a census dataset: one nation's census at one vintage.","example":"ew-2021"},"required":true,"description":"Identifier for a census dataset: one nation's census at one vintage.","name":"datasetCode","in":"path"},{"schema":{"type":"string","description":"Identifier for a classification, which is one of the levels of detail a variable is published at.","example":"ts054"},"required":true,"description":"Identifier for a classification, which is one of the levels of detail a variable is published at.","name":"classificationCode","in":"path"}],"responses":{"200":{"description":"The requested census classification.","content":{"application/json":{"schema":{"type":"object","properties":{"classificationCode":{"type":"string","description":"Identifier for this classification, used as the `classificationCode` path parameter.","example":"ts054"},"classificationName":{"type":"string","description":"The classification's published name.","example":"Tenure (5 categories)"},"categoryCount":{"type":"integer","description":"How many categories this classification breaks the variable into.","example":5},"isDefault":{"type":"boolean","description":"True when this is the variable's default classification."},"availableGeotypes":{"type":"array","items":{"type":"string"},"description":"The geography levels this classification can be requested at. Asking for a level outside this list returns a 404.","example":["lsoa","lad","region","country"]},"comparisonGeotypes":{"type":["array","null"],"items":{"type":"string"},"description":"The geography levels that also carry change values, for requests with `mode=change`. Null when none do."}},"required":["classificationCode","classificationName","categoryCount","isDefault","availableGeotypes","comparisonGeotypes"],"description":"The requested census classification."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/census/datasets/{datasetCode}/categories/{categoryCode}":{"get":{"operationId":"getCensusCategory","x-speakeasy-name-override":"getCategory","tags":["Census"],"summary":"Get a census category","description":"Returns one category by its code, with the classification and variable it belongs to and the geography levels it can be requested at.","parameters":[{"schema":{"type":"string","description":"Identifier for a census dataset: one nation's census at one vintage.","example":"ew-2021"},"required":true,"description":"Identifier for a census dataset: one nation's census at one vintage.","name":"datasetCode","in":"path"},{"schema":{"type":"string","description":"Identifier for a single category, formed as `{classificationCode}-{NNN}`.","example":"ts054-002"},"required":true,"description":"Identifier for a single category, formed as `{classificationCode}-{NNN}`.","name":"categoryCode","in":"path"}],"responses":{"200":{"description":"The requested census category.","content":{"application/json":{"schema":{"type":"object","properties":{"categoryCode":{"type":"string","description":"Identifier for this category, formed as `{classificationCode}-{NNN}`.","example":"ts054-002"},"categoryName":{"type":"string","description":"The category's published label.","example":"Owned: Owns outright"},"categoryIndex":{"type":"integer","description":"Position of the category within its classification, and the numeric part of `categoryCode`.","example":2},"hierarchyLevel":{"type":"integer","description":"How deep the category sits in its classification's hierarchy, 1 being the top level.","example":1},"isTotal":{"type":"boolean","description":"True when this category is the total the others are measured against."},"classificationCode":{"type":"string","description":"Identifier for the classification this category belongs to.","example":"ts054"},"classificationName":{"type":"string","description":"Name of the classification this category belongs to.","example":"Tenure (5 categories)"},"availableGeotypes":{"type":"array","items":{"type":"string"},"description":"The geography levels this category can be requested at. Asking for a level outside this list returns a 404.","example":["lsoa","lad","region","country"]},"comparisonGeotypes":{"type":["array","null"],"items":{"type":"string"},"description":"The geography levels that also carry change values, for requests with `mode=change`. Null when none do."},"variableCode":{"type":"string","description":"Code for the variable this category belongs to, as published by the census.","example":"TS054"},"variableSlug":{"type":"string","description":"Identifier for the variable this category belongs to, used as the `slug` path parameter.","example":"tenure"},"variableName":{"type":"string","description":"Published name of the variable this category belongs to.","example":"Tenure"}},"required":["categoryCode","categoryName","categoryIndex","hierarchyLevel","isTotal","classificationCode","classificationName","availableGeotypes","comparisonGeotypes","variableCode","variableSlug","variableName"],"description":"The requested census category."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/census/datasets/{datasetCode}/profile":{"post":{"operationId":"postCensusAreaProfile","x-speakeasy-name-override":"areaProfile","tags":["Census"],"summary":"Build a multi-area census profile","description":"Returns the census values for up to 100 areas at once, one row per area and category. Each row carries the count and the category's share of its base, alongside the variable and classification it belongs to. Pass `variableSlugs` to narrow the profile to specific variables.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":50,"description":"Identifier for a census dataset: one nation's census at one vintage. The datasets endpoint lists the codes in service.","example":"ew-2021"},"required":true,"description":"Identifier for a census dataset: one nation's census at one vintage. The datasets endpoint lists the codes in service.","name":"datasetCode","in":"path"}],"requestBody":{"description":"The areas to profile and, optionally, the variables to limit the profile to.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CensusAreaProfileRequest"}}}},"responses":{"200":{"description":"One row per area and category profiled.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"geographyCode":{"type":"string","description":"The area this value is for, as an ONS geography code.","example":"E01004736"},"variableCode":{"type":"string","description":"Code for the variable this value belongs to, as published by the census.","example":"TS054"},"variableSlug":{"type":"string","description":"Identifier for the variable this value belongs to.","example":"tenure"},"variableName":{"type":"string","description":"Published name of the variable.","example":"Tenure"},"classificationCode":{"type":"string","description":"Identifier for the classification this value belongs to.","example":"ts054"},"categoryCode":{"type":"string","description":"Identifier for the category this value belongs to.","example":"ts054-002"},"categoryName":{"type":"string","description":"The category's published label.","example":"Owned: Owns outright"},"count":{"type":["string","null"],"description":"The census count for this category in this area. Null when the source suppressed it."},"ratio":{"type":["string","null"],"description":"The category's share of its base in this area, from 0 to 1, as a decimal string. Null when no share could be computed for the area."}},"required":["geographyCode","variableCode","variableSlug","variableName","classificationCode","categoryCode","categoryName","count","ratio"],"description":"One category value for one area in a profile."},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One row per area and category profiled."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/census/datasets/{datasetCode}/rollup":{"post":{"operationId":"postCensusRollup","x-speakeasy-name-override":"rollup","tags":["Census"],"summary":"Roll up census categories over a custom area","description":"Aggregates category counts across up to 100 areas treated as one custom area, such as a catchment. Each ratio is the summed count divided by the summed base, not an average of the individual areas' ratios.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":50,"description":"Identifier for a census dataset: one nation's census at one vintage. The datasets endpoint lists the codes in service.","example":"ew-2021"},"required":true,"description":"Identifier for a census dataset: one nation's census at one vintage. The datasets endpoint lists the codes in service.","name":"datasetCode","in":"path"}],"requestBody":{"description":"The areas that make up the custom area and the categories to aggregate over it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CensusRollupRequest"}}}},"responses":{"200":{"description":"One row per category aggregated over the custom area.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"categoryCode":{"type":"string","description":"Identifier for the category this value belongs to.","example":"ts054-002"},"total":{"type":["string","null"],"description":"The category's count summed across every area in the request."},"base":{"type":["string","null"],"description":"The category's base count summed across every area in the request."},"ratio":{"type":["string","null"],"description":"`total` divided by `base`, so the share is taken over the whole custom area rather than averaged across its parts. Null when there is no positive base to divide by."}},"required":["categoryCode","total","base","ratio"],"description":"One category aggregated over a custom set of areas."},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"One row per category aggregated over the custom area."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/census/tiles/{datasetCode}/{geotype}/{tile}/{categoryCode}":{"get":{"operationId":"getCensusTile","x-speakeasy-name-override":"getTile","tags":["Census"],"summary":"Get a census choropleth tile as CSV","description":"Returns the values for one map tile as CSV: every area of the requested geography level whose centroid falls inside the tile, as `geography_code,{categoryCode}` rows. The `tile` path segment is `{x}-{y}-{z}`. Pass `mode=change` for signed percentage-point change values. Responses may be cached for 24 hours.","parameters":[{"schema":{"type":"string","description":"Identifier for a census dataset: one nation's census at one vintage.","example":"ew-2021"},"required":true,"description":"Identifier for a census dataset: one nation's census at one vintage.","name":"datasetCode","in":"path"},{"schema":{"type":"string","enum":["oa","lsoa","msoa","lad","region","country","dz","iz","council","sa","sdz","lgd"],"description":"The geography level areas are reported at. Which levels a dataset offers varies by nation and by category; a category's `availableGeotypes` lists the levels it can be requested at.","example":"lsoa"},"required":true,"description":"The geography level areas are reported at. Which levels a dataset offers varies by nation and by category; a category's `availableGeotypes` lists the levels it can be requested at.","name":"geotype","in":"path"},{"schema":{"type":"string","pattern":"^\\d+-\\d+-\\d+$","description":"The tile to return, as `{x}-{y}-{z}`: the X and Y coordinates and the zoom level of a standard XYZ map tile. The grid endpoint lists the tiles a dataset holds.","example":"131-87-8"},"required":true,"description":"The tile to return, as `{x}-{y}-{z}`: the X and Y coordinates and the zoom level of a standard XYZ map tile. The grid endpoint lists the tiles a dataset holds.","name":"tile","in":"path"},{"schema":{"type":"string","description":"Identifier for a single category, formed as `{classificationCode}-{NNN}`. The same string is the value column header in the CSV returned.","example":"ts054-002"},"required":true,"description":"Identifier for a single category, formed as `{classificationCode}-{NNN}`. The same string is the value column header in the CSV returned.","name":"categoryCode","in":"path"},{"schema":{"type":"string","enum":["standard","change"],"default":"standard","description":"Which values the response carries. `standard` gives each category's share of its base, from 0 to 1; `change` gives the signed percentage-point change against an earlier census. Defaults to `standard`. The levels that carry change values are listed in a classification's `comparisonGeotypes`.","example":"standard"},"required":false,"description":"Which values the response carries. `standard` gives each category's share of its base, from 0 to 1; `change` gives the signed percentage-point change against an earlier census. Defaults to `standard`. The levels that carry change values are listed in a classification's `comparisonGeotypes`.","name":"mode","in":"query"}],"responses":{"200":{"description":"The tile's values as CSV, one row per area.","content":{"text/csv":{"schema":{"type":"string","description":"A `geography_code,{categoryCode}` header row followed by one row per area. An area with no value is returned with an empty second field.","example":"geography_code,ts054-002\nE01004736,0.450000\nE01004737,0.550000\n"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No dataset matches the supplied code, or the category is not served at the requested geography level.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/census/whole/{datasetCode}/{geotype}/{country}/{categoryCode}":{"get":{"operationId":"getCensusWholeLevel","x-speakeasy-name-override":"getWholeLevel","tags":["Census"],"summary":"Get a whole-country census level as CSV","description":"Returns every area of one coarse geography level in a single CSV, as `geography_code,{categoryCode}` rows. Use it for the levels the grid endpoint reports as a whole-country file rather than as tiles. Pass `mode=change` for signed percentage-point change values. Responses may be cached for 24 hours.","parameters":[{"schema":{"type":"string","description":"Identifier for a census dataset: one nation's census at one vintage.","example":"ew-2021"},"required":true,"description":"Identifier for a census dataset: one nation's census at one vintage.","name":"datasetCode","in":"path"},{"schema":{"type":"string","enum":["oa","lsoa","msoa","lad","region","country","dz","iz","council","sa","sdz","lgd"],"description":"The geography level areas are reported at. Which levels a dataset offers varies by nation and by category; a category's `availableGeotypes` lists the levels it can be requested at.","example":"lsoa"},"required":true,"description":"The geography level areas are reported at. Which levels a dataset offers varies by nation and by category; a category's `availableGeotypes` lists the levels it can be requested at.","name":"geotype","in":"path"},{"schema":{"type":"string","enum":["ew","sco","ni","ie"],"description":"Nation segment of the file path. Which nation the file covers is already fixed by the dataset.","example":"ew"},"required":true,"description":"Nation segment of the file path. Which nation the file covers is already fixed by the dataset.","name":"country","in":"path"},{"schema":{"type":"string","description":"Identifier for a single category, formed as `{classificationCode}-{NNN}`. The same string is the value column header in the CSV returned.","example":"ts054-002"},"required":true,"description":"Identifier for a single category, formed as `{classificationCode}-{NNN}`. The same string is the value column header in the CSV returned.","name":"categoryCode","in":"path"},{"schema":{"type":"string","enum":["standard","change"],"default":"standard","description":"Which values the response carries. `standard` gives each category's share of its base, from 0 to 1; `change` gives the signed percentage-point change against an earlier census. Defaults to `standard`. The levels that carry change values are listed in a classification's `comparisonGeotypes`.","example":"standard"},"required":false,"description":"Which values the response carries. `standard` gives each category's share of its base, from 0 to 1; `change` gives the signed percentage-point change against an earlier census. Defaults to `standard`. The levels that carry change values are listed in a classification's `comparisonGeotypes`.","name":"mode","in":"query"}],"responses":{"200":{"description":"The level's values as CSV, one row per area.","content":{"text/csv":{"schema":{"type":"string","description":"A `geography_code,{categoryCode}` header row followed by one row per area. An area with no value is returned with an empty second field.","example":"geography_code,ts054-002\nE01004736,0.450000\nE01004737,0.550000\n"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No dataset matches the supplied code, or the category is not served at the requested geography level.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/census/breaks/{datasetCode}/{geotype}/{categoryCode}":{"get":{"operationId":"getCensusBreaks","x-speakeasy-name-override":"getBreaks","tags":["Census"],"summary":"Get the legend class breaks for a category","description":"Returns the six values that split a category into five classes for a choropleth legend: the minimum, then the upper bound of each class. The body is a bare JSON array rather than a list envelope. Pass `mode=change` for breaks taken over signed percentage-point change values.","parameters":[{"schema":{"type":"string","description":"Identifier for a census dataset: one nation's census at one vintage.","example":"ew-2021"},"required":true,"description":"Identifier for a census dataset: one nation's census at one vintage.","name":"datasetCode","in":"path"},{"schema":{"type":"string","enum":["oa","lsoa","msoa","lad","region","country","dz","iz","council","sa","sdz","lgd"],"description":"The geography level areas are reported at. Which levels a dataset offers varies by nation and by category; a category's `availableGeotypes` lists the levels it can be requested at.","example":"lsoa"},"required":true,"description":"The geography level areas are reported at. Which levels a dataset offers varies by nation and by category; a category's `availableGeotypes` lists the levels it can be requested at.","name":"geotype","in":"path"},{"schema":{"type":"string","description":"Identifier for a single category, formed as `{classificationCode}-{NNN}`.","example":"ts054-002"},"required":true,"description":"Identifier for a single category, formed as `{classificationCode}-{NNN}`.","name":"categoryCode","in":"path"},{"schema":{"type":"string","enum":["standard","change"],"default":"standard","description":"Which values the response carries. `standard` gives each category's share of its base, from 0 to 1; `change` gives the signed percentage-point change against an earlier census. Defaults to `standard`. The levels that carry change values are listed in a classification's `comparisonGeotypes`.","example":"standard"},"required":false,"description":"Which values the response carries. `standard` gives each category's share of its base, from 0 to 1; `change` gives the signed percentage-point change against an earlier census. Defaults to `standard`. The levels that carry change values are listed in a classification's `comparisonGeotypes`.","name":"mode","in":"query"}],"responses":{"200":{"description":"Six values giving the five legend classes.","content":{"application/json":{"schema":{"type":"array","items":{"type":"number"},"description":"Six values that split the category into five classes for a choropleth legend: the minimum, then the upper bound of each class.","example":[0,0.15,0.3,0.55,0.8,1]}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No dataset matches the supplied code, or no class breaks exist for that category at that geography level.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/census/grid/{datasetCode}":{"get":{"operationId":"getCensusGrid","x-speakeasy-name-override":"getGrid","tags":["Census"],"summary":"Get the tile grid for a dataset","description":"Lists the tiles a dataset holds and the bounds of each, so a client can request only the tiles that carry data. Pass `geotype` to limit the list to one geography level.","parameters":[{"schema":{"type":"string","minLength":1,"maxLength":50,"description":"Identifier for a census dataset: one nation's census at one vintage. The datasets endpoint lists the codes in service.","example":"ew-2021"},"required":true,"description":"Identifier for a census dataset: one nation's census at one vintage. The datasets endpoint lists the codes in service.","name":"datasetCode","in":"path"},{"schema":{"type":"string","enum":["oa","lsoa","msoa","lad","region","country","dz","iz","council","sa","sdz","lgd"],"description":"Limits the grid to a single geography level. Omit to return the tiles for every level in the dataset.","example":"lsoa"},"required":false,"description":"Limits the grid to a single geography level. Omit to return the tiles for every level in the dataset.","name":"geotype","in":"query"}],"responses":{"200":{"description":"The tiles the dataset holds, with the bounds of each.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"],"description":"Object type discriminator. Always `list`."},"url":{"type":"string","description":"Path this list was requested from.","example":"/v1/items"},"has_more":{"type":"boolean","description":"True when further items exist beyond this page.","example":true},"data":{"type":"array","items":{"type":"object","properties":{"geographicType":{"type":"string","description":"The geography level this entry covers.","example":"lsoa"},"tilename":{"type":"string","description":"Name of the entry: `{x}-{y}-{z}` for a level served as tiles, or a nation code for a level served as one whole-country file.","example":"131-87-8"},"z":{"type":["integer","null"],"description":"Zoom level of the tile. Null for a level served as one whole-country file.","example":8},"x":{"type":["integer","null"],"description":"X coordinate of the tile. Null for a level served as one whole-country file.","example":131},"y":{"type":["integer","null"],"description":"Y coordinate of the tile. Null for a level served as one whole-country file.","example":87},"bboxWest":{"type":"string","description":"Longitude of the western edge, in WGS84 decimal degrees.","example":"-1.40625"},"bboxSouth":{"type":"string","description":"Latitude of the southern edge, in WGS84 decimal degrees.","example":"52.052490"},"bboxEast":{"type":"string","description":"Longitude of the eastern edge, in WGS84 decimal degrees.","example":"0.0"},"bboxNorth":{"type":"string","description":"Latitude of the northern edge, in WGS84 decimal degrees.","example":"52.482780"}},"required":["geographicType","tilename","z","x","y","bboxWest","bboxSouth","bboxEast","bboxNorth"],"description":"One entry in a dataset's tile grid: a tile, the geography level it serves, and its bounds."},"description":"The items on this page."},"total_count":{"type":"number","description":"Total number of items matching the request across all pages.","example":250}},"required":["object","url","has_more","data"],"description":"The tiles a dataset holds, with the bounds of each."}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/census/health":{"get":{"operationId":"checkCensusHealth","x-speakeasy-name-override":"checkCensusHealth","tags":["System"],"summary":"Check census service health","description":"Reports whether the census service is answering requests.","responses":{"200":{"description":"The service is answering requests.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CensusHealthResponse"}}}}}}},"/v1/prosperity/{geographicCodes}":{"get":{"operationId":"getProsperity","x-speakeasy-name-override":"get","tags":["Prosperity"],"summary":"Get the Prosperity Index for one or more small areas","description":"Returns the Vepler Prosperity Index for one or more small areas: a composite score from 0 to 100, with the area's national decile from 1 to 10 and its national percentile. Each result carries its own `geographicCode`, breaks the score down into four weighted dimensions (income, housing, employment and living standards) and up to 19 curated indicators behind them, and adds the Office for National Statistics Output Area Classification for areas in England and Wales. Pass a single code or a comma-separated list of up to 100; codes that hold no score are left out of the response rather than reported as errors, so a request for valid but unscored codes returns an empty list.","parameters":[{"schema":{"type":"string","description":"A single small-area code, or a comma-separated list of up to 100. These are Lower Layer Super Output Area (LSOA) codes in England and Wales, Data Zone codes in Scotland and Super Output Area (SOA) codes in Northern Ireland.","example":"E01000001"},"required":true,"description":"A single small-area code, or a comma-separated list of up to 100. These are Lower Layer Super Output Area (LSOA) codes in England and Wales, Data Zone codes in Scotland and Super Output Area (SOA) codes in Northern Ireland.","name":"geographicCodes","in":"path"}],"responses":{"200":{"description":"Prosperity scores for the codes that have one. Codes with no score are omitted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProsperityListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/heritage/designations/query":{"post":{"operationId":"queryHeritageDesignations","x-speakeasy-name-override":"query","tags":["Heritage"],"summary":"Query heritage designations near a place","description":"Returns heritage designations for one or more areas, given as a point with a radius, a postcode, an outward code, a bounding box, a polygon or a multipolygon. Up to ten areas can be combined in one request, and their results are deduplicated by `designationId`. A radius of 0 returns only the designations whose boundary contains the point. Ask for `geometry` in `attributes` to add the full MultiPolygon boundary; source lineage and the harmonised value fields need extended permissions on the licence.","requestBody":{"description":"The areas to search, and any filters, sorting and attribute selection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignationQueryRequest"},"example":{"area":[{"type":"point","coordinates":[51.1789,-1.8262],"radius":1000}],"limit":25}}}},"responses":{"200":{"description":"The designations matching the search areas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeritageDesignationListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"The postcode or outward code could not be resolved to a location.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"No published snapshot is available to read. Retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/heritage/designations/{designationId}":{"get":{"operationId":"getHeritageDesignation","x-speakeasy-name-override":"get","tags":["Heritage"],"summary":"Get one heritage designation","description":"Returns a single designation by its stable `designationId`. Add `?attributes=geometry` for the full boundary, and `?snapshotId=` to read an earlier published snapshot so a result can be reproduced.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Stable identifier for the designation, formed as `design.{product}.{nation}.{type}.{reference}` and returned as `designationId` on every result.","example":"design.heritage.ENG.scheduled_monument.1010140"},"required":true,"description":"Stable identifier for the designation, formed as `design.{product}.{nation}.{type}.{reference}` and returned as `designationId` on every result.","name":"designationId","in":"path"}],"responses":{"200":{"description":"The requested designation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HeritageDesignationFeature"}}}},"400":{"description":"The designation id is malformed, or belongs to a different product.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"No published snapshot is available to read. Retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/heritage/snapshots":{"get":{"operationId":"listHeritageSnapshots","x-speakeasy-name-override":"snapshots","tags":["Heritage"],"summary":"List heritage data snapshots","description":"Lists the published snapshots, newest first, with when each was published and how many designations it holds. Use it to check how fresh the data is, or to find a snapshot id to pin a query to.","responses":{"200":{"description":"The published snapshots, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignationSnapshotListResponse"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"No published snapshot is available to read. Retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/heritage/types":{"get":{"operationId":"listHeritageTypes","x-speakeasy-name-override":"types","tags":["Heritage"],"summary":"List heritage designation types","description":"Lists every designation type in the current snapshot with its label and how many designations carry it. It needs no licence, so coverage can be checked before buying, and the codes it returns are the ones to pass to the query endpoint's `designationType` filter.","responses":{"200":{"description":"The designation types in the current snapshot, with counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignationTypeListResponse"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"No published snapshot is available to read. Retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/conservation/designations/query":{"post":{"operationId":"queryConservationDesignations","x-speakeasy-name-override":"query","tags":["Conservation"],"summary":"Query conservation designations near a place","description":"Returns conservation designations for one or more areas, given as a point with a radius, a postcode, an outward code, a bounding box, a polygon or a multipolygon. Up to ten areas can be combined in one request, and their results are deduplicated by `designationId`. A radius of 0 returns only the designations whose boundary contains the point. Ask for `geometry` in `attributes` to add the full MultiPolygon boundary; source lineage and the harmonised value fields need extended permissions on the licence.","requestBody":{"description":"The areas to search, and any filters, sorting and attribute selection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignationQueryRequest"},"example":{"area":[{"type":"point","coordinates":[51.1789,-1.8262],"radius":1000}],"limit":25}}}},"responses":{"200":{"description":"The designations matching the search areas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConservationDesignationListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"The postcode or outward code could not be resolved to a location.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"No published snapshot is available to read. Retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/conservation/designations/{designationId}":{"get":{"operationId":"getConservationDesignation","x-speakeasy-name-override":"get","tags":["Conservation"],"summary":"Get one conservation designation","description":"Returns a single designation by its stable `designationId`. Add `?attributes=geometry` for the full boundary, and `?snapshotId=` to read an earlier published snapshot so a result can be reproduced.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Stable identifier for the designation, formed as `design.{product}.{nation}.{type}.{reference}` and returned as `designationId` on every result.","example":"design.heritage.ENG.scheduled_monument.1010140"},"required":true,"description":"Stable identifier for the designation, formed as `design.{product}.{nation}.{type}.{reference}` and returned as `designationId` on every result.","name":"designationId","in":"path"}],"responses":{"200":{"description":"The requested designation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConservationDesignationFeature"}}}},"400":{"description":"The designation id is malformed, or belongs to a different product.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"No published snapshot is available to read. Retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/conservation/snapshots":{"get":{"operationId":"listConservationSnapshots","x-speakeasy-name-override":"snapshots","tags":["Conservation"],"summary":"List conservation data snapshots","description":"Lists the published snapshots, newest first, with when each was published and how many designations it holds. Use it to check how fresh the data is, or to find a snapshot id to pin a query to.","responses":{"200":{"description":"The published snapshots, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignationSnapshotListResponse"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"No published snapshot is available to read. Retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/conservation/types":{"get":{"operationId":"listConservationTypes","x-speakeasy-name-override":"types","tags":["Conservation"],"summary":"List conservation designation types","description":"Lists every designation type in the current snapshot with its label and how many designations carry it. It needs no licence, so coverage can be checked before buying, and the codes it returns are the ones to pass to the query endpoint's `designationType` filter.","responses":{"200":{"description":"The designation types in the current snapshot, with counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignationTypeListResponse"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"No published snapshot is available to read. Retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/geography/release":{"get":{"operationId":"getGeographyRelease","tags":["Geography"],"summary":"Get the current geography release","description":"Returns the release every other geography endpoint answers from unless one is pinned. A release is a named set of publisher vintages that compose into one consistent tree. The nations publish on their own cycles, so a UK-wide release is a composition rather than a date.","responses":{"200":{"description":"The current release.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"release":{"type":"string"}},"required":["release"]}},"required":["data"]}}}}}}},"/v1/geography/areas/{codes}":{"get":{"operationId":"getGeographyAreas","tags":["Geography"],"summary":"Look up areas by code","description":"Resolves up to 100 comma-separated GSS codes to their name, type, vintage, nation and tier. A code can legitimately exist at more than one layer or edition, so every match is returned. Narrow with `areaType` when you want a single answer.","parameters":[{"schema":{"type":"string","description":"Comma-separated GSS codes, up to 100."},"required":true,"description":"Comma-separated GSS codes, up to 100.","name":"codes","in":"path"},{"schema":{"type":"string","description":"Restrict to one layer, e.g. `lsoa`."},"required":false,"description":"Restrict to one layer, e.g. `lsoa`.","name":"areaType","in":"query"},{"schema":{"type":"string","description":"Restrict to one edition, e.g. `2021`."},"required":false,"description":"Restrict to one edition, e.g. `2021`.","name":"vintage","in":"query"}],"responses":{"200":{"description":"The matching areas.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/GeographyArea"}},"total_count":{"type":"number"}},"required":["object","url","data"]}}}}}}},"/v1/geography/areas/{code}/ancestors":{"get":{"operationId":"getGeographyAncestors","tags":["Geography"],"summary":"Everything containing this area","description":"Walks the whole way up in one read: the containing area at every tier, with how many hops away it is and the worst fit along that path. Check `minFit` before aggregating: an LSOA reaches its local authority by best fit in the current release, because the exact-fit spine exists only at the 2022 boundaries.","parameters":[{"schema":{"type":"string","description":"The GSS code to walk up from."},"required":true,"description":"The GSS code to walk up from.","name":"code","in":"path"},{"schema":{"type":"string","description":"Pin a release, e.g. `2025.1`. Omit to follow the current one."},"required":false,"description":"Pin a release, e.g. `2025.1`. Omit to follow the current one.","name":"release","in":"query"},{"schema":{"type":"string","description":"The layer the code belongs to, when it is ambiguous."},"required":false,"description":"The layer the code belongs to, when it is ambiguous.","name":"areaType","in":"query"},{"schema":{"type":"string","description":"Return only ancestors at this tier, e.g. `ltla`."},"required":false,"description":"Return only ancestors at this tier, e.g. `ltla`.","name":"tier","in":"query"}],"responses":{"200":{"description":"Containing areas.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/GeographyRelatedArea"}},"total_count":{"type":"number"}},"required":["object","url","data"]}}}}}}},"/v1/geography/areas/{code}/descendants":{"get":{"operationId":"getGeographyDescendants","tags":["Geography"],"summary":"Everything inside this area","description":"Paged, because the set can be very large: England and Wales hold 188,880 Output Areas. `total_count` reports the full size of the set being paged through. Note that every unitary authority is both a district and a county under one code, so narrow with `areaType` or each descendant is returned once per matching type.","parameters":[{"schema":{"type":"string","description":"The GSS code to walk down from."},"required":true,"description":"The GSS code to walk down from.","name":"code","in":"path"},{"schema":{"type":"string","description":"Pin a release, e.g. `2025.1`. Omit to follow the current one."},"required":false,"description":"Pin a release, e.g. `2025.1`. Omit to follow the current one.","name":"release","in":"query"},{"schema":{"type":"string","description":"The layer the code belongs to, when it is ambiguous."},"required":false,"description":"The layer the code belongs to, when it is ambiguous.","name":"areaType","in":"query"},{"schema":{"type":"string","description":"Return only descendants of this layer, e.g. `lsoa`."},"required":false,"description":"Return only descendants of this layer, e.g. `lsoa`.","name":"descendantType","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":1000,"description":"Page size, up to 1000."},"required":false,"description":"Page size, up to 1000.","name":"limit","in":"query"},{"schema":{"type":["integer","null"],"minimum":0,"description":"Rows to skip."},"required":false,"description":"Rows to skip.","name":"offset","in":"query"}],"responses":{"200":{"description":"Contained areas.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string"},"data":{"type":"array","items":{"$ref":"#/components/schemas/GeographyRelatedArea"}},"total_count":{"type":"number"}},"required":["object","url","data"]}}}}}}},"/v1/geography/areas/{code}/children":{"get":{"operationId":"getGeographyChildren","tags":["Geography"],"summary":"The immediate children of this area","description":"One hop down the curated tree, with the fit of each link and the source that won it. Where publishers disagreed about a parent, `sourceId` names the one whose claim was kept.","parameters":[{"schema":{"type":"string","description":"The parent GSS code."},"required":true,"description":"The parent GSS code.","name":"code","in":"path"},{"schema":{"type":"string","description":"Pin a release, e.g. `2025.1`. Omit to follow the current one."},"required":false,"description":"Pin a release, e.g. `2025.1`. Omit to follow the current one.","name":"release","in":"query"},{"schema":{"type":"string","description":"The layer the parent belongs to, when it is ambiguous."},"required":false,"description":"The layer the parent belongs to, when it is ambiguous.","name":"areaType","in":"query"},{"schema":{"type":"string","description":"Return only children of this layer."},"required":false,"description":"Return only children of this layer.","name":"childType","in":"query"}],"responses":{"200":{"description":"Direct children.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string"},"data":{"type":"array","items":{"allOf":[{"$ref":"#/components/schemas/GeographyArea"},{"type":"object","properties":{"fitType":{"type":"string"},"sourceId":{"type":"string"}},"required":["fitType","sourceId"]}]}},"total_count":{"type":"number"}},"required":["object","url","data"]}}}}}}},"/v1/geography/areas/{code}/provenance":{"get":{"operationId":"getGeographyProvenance","tags":["Geography"],"summary":"Where this area's record came from","description":"The publisher, the pinned file, its licence, and the acknowledgement line that licence requires, verbatim, because the wording differs per custodian and anyone redistributing this data has to reproduce it. `sha256` identifies the exact file the record was parsed from; `fromArchive` is true when the publisher was unreachable and the file came from Vepler's archive.","parameters":[{"schema":{"type":"string","description":"The GSS code."},"required":true,"description":"The GSS code.","name":"code","in":"path"},{"schema":{"type":"string"},"required":false,"name":"areaType","in":"query"},{"schema":{"type":"string"},"required":false,"name":"vintage","in":"query"}],"responses":{"200":{"description":"Source records behind this area.","content":{"application/json":{"schema":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"url":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"sourceId":{"type":"string"},"custodian":{"type":"string"},"title":{"type":"string"},"url":{"type":"string"},"licence":{"type":"string"},"attribution":{"type":["string","null"]},"fetchedAt":{"type":"string"},"sha256":{"type":"string"},"fromArchive":{"type":"boolean"}},"required":["sourceId","custodian","title","url","licence","attribution","fetchedAt","sha256","fromArchive"]}},"total_count":{"type":"number"}},"required":["object","url","data"]}}}}}}},"/v1/land-constraint/designations/query":{"post":{"operationId":"queryLandConstraintDesignations","x-speakeasy-name-override":"query","tags":["Land Constraint"],"summary":"Query land constraint designations near a place","description":"Returns land constraint designations for one or more areas, given as a point with a radius, a postcode, an outward code, a bounding box, a polygon or a multipolygon. Up to ten areas can be combined in one request, and their results are deduplicated by `designationId`. A radius of 0 returns only the designations whose boundary contains the point. Ask for `geometry` in `attributes` to add the full MultiPolygon boundary; source lineage and the harmonised value fields need extended permissions on the licence.","requestBody":{"description":"The areas to search, and any filters, sorting and attribute selection.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignationQueryRequest"},"example":{"area":[{"type":"point","coordinates":[51.1789,-1.8262],"radius":1000}],"limit":25}}}},"responses":{"200":{"description":"The designations matching the search areas.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LandConstraintDesignationListResponse"}}}},"400":{"description":"The request was rejected. See the error body for which parameter failed and why.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"The postcode or outward code could not be resolved to a location.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"No published snapshot is available to read. Retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/land-constraint/designations/{designationId}":{"get":{"operationId":"getLandConstraintDesignation","x-speakeasy-name-override":"get","tags":["Land Constraint"],"summary":"Get one land constraint designation","description":"Returns a single designation by its stable `designationId`. Add `?attributes=geometry` for the full boundary, and `?snapshotId=` to read an earlier published snapshot so a result can be reproduced.","parameters":[{"schema":{"type":"string","minLength":1,"description":"Stable identifier for the designation, formed as `design.{product}.{nation}.{type}.{reference}` and returned as `designationId` on every result.","example":"design.heritage.ENG.scheduled_monument.1010140"},"required":true,"description":"Stable identifier for the designation, formed as `design.{product}.{nation}.{type}.{reference}` and returned as `designationId` on every result.","name":"designationId","in":"path"}],"responses":{"200":{"description":"The requested designation.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LandConstraintDesignationFeature"}}}},"400":{"description":"The designation id is malformed, or belongs to a different product.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"404":{"description":"No record matches the supplied identifier.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"No published snapshot is available to read. Retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/land-constraint/snapshots":{"get":{"operationId":"listLandConstraintSnapshots","x-speakeasy-name-override":"snapshots","tags":["Land Constraint"],"summary":"List land constraint data snapshots","description":"Lists the published snapshots, newest first, with when each was published and how many designations it holds. Use it to check how fresh the data is, or to find a snapshot id to pin a query to.","responses":{"200":{"description":"The published snapshots, newest first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignationSnapshotListResponse"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"No published snapshot is available to read. Retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/land-constraint/types":{"get":{"operationId":"listLandConstraintTypes","x-speakeasy-name-override":"types","tags":["Land Constraint"],"summary":"List land constraint designation types","description":"Lists every designation type in the current snapshot with its label and how many designations carry it. It needs no licence, so coverage can be checked before buying, and the codes it returns are the ones to pass to the query endpoint's `designationType` filter.","responses":{"200":{"description":"The designation types in the current snapshot, with counts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DesignationTypeListResponse"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}},"503":{"description":"No published snapshot is available to read. Retry later.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["api_error","invalid_request_error","authentication_error","rate_limit_error"],"description":"Broad category of the failure: a malformed request, an authentication problem, a rate limit, or a fault on the server side."},"code":{"type":"string","description":"Stable code identifying the specific failure, safe to branch on.","example":"resource_not_found"},"message":{"type":"string","description":"Human-readable explanation of what went wrong.","example":"The requested resource was not found"},"param":{"type":"string","description":"Name of the request parameter at fault, where the failure can be traced to one.","example":"id"},"doc_url":{"type":"string","description":"Link to the documentation for this error.","example":"https://docs.example.com/errors#resource_not_found"},"suggestions":{"type":"array","items":{"type":"string"},"description":"Alternative values worth retrying when the supplied one could not be matched."}},"required":["type","message"]}},"required":["error"],"description":"Returned in place of the normal payload whenever a request fails."}}}}}}},"/v1/ai/models":{"get":{"tags":["Models"],"summary":"List models","description":"Lists the models that can be run, each with what it reads and the JSON Schema of the result it returns. Listing models is free.","responses":{"200":{"description":"The models.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelList"}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"403":{"description":"The API key is not permitted to call the model API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"429":{"description":"Too many requests. Retry after the number of seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}}}}},"/v1/ai/models/{model}":{"get":{"tags":["Models"],"summary":"Retrieve a model","description":"Returns one model, with what it reads and the JSON Schema of the result it returns. Free.","parameters":[{"schema":{"type":"string","minLength":1,"example":"epc-vision","description":"Id of the model."},"required":true,"description":"Id of the model.","name":"model","in":"path"}],"responses":{"200":{"description":"The model.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Model"}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"403":{"description":"The API key is not permitted to call the model API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"404":{"description":"No model has the requested id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"429":{"description":"Too many requests. Retry after the number of seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"500":{"description":"The request could not be completed. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}}}}},"/v1/ai/chat/completions":{"post":{"tags":["Models"],"summary":"Run a model","description":"Runs a model on one input and returns its result as one JSON object in a standard chat completion. Send exactly one user message holding one image part. Each input is charged once, in credits, and the charge is shown in `usage`. A repeat of a completed request within 15 minutes is served from cache without charge. With `stream: true` the result arrives as server-sent events: one chunk holding the whole result, a usage chunk when `stream_options.include_usage` is true, then `[DONE]`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletion"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"The request was rejected. `error.param` names the parameter that failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"402":{"description":"The account does not hold enough credits for this request. Nothing has been charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"403":{"description":"The API key is not permitted to call the model API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"404":{"description":"No model has the requested id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"413":{"description":"The request body is over 28 MiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"429":{"description":"Too many requests. Retry after the number of seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"500":{"description":"The request could not be completed, including when the model's result failed validation. Nothing has been charged. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"503":{"description":"The model or the image service is temporarily unavailable. Nothing has been charged. Retry after the number of seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}}}}},"/v1/ai/responses":{"post":{"tags":["Models"],"summary":"Run a model (Responses)","description":"Runs a model on one input and returns its result as one `output_text` holding one JSON object. Send exactly one user message holding one `input_image` part. Charged, and repeats served from cache, exactly as chat completions. Streaming is not supported on this route.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResponseRequest"}}}},"responses":{"200":{"description":"The result.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelResponse"}}}},"400":{"description":"The request was rejected. `error.param` names the parameter that failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"401":{"description":"No valid API key was supplied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"402":{"description":"The account does not hold enough credits for this request. Nothing has been charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"403":{"description":"The API key is not permitted to call the model API.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"404":{"description":"No model has the requested id.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"413":{"description":"The request body is over 28 MiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"429":{"description":"Too many requests. Retry after the number of seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"500":{"description":"The request could not be completed, including when the model's result failed validation. Nothing has been charged. Retry, and contact support if it persists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}},"503":{"description":"The model or the image service is temporarily unavailable. Nothing has been charged. Retry after the number of seconds in the `Retry-After` header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelApiError"}}}}}}}},"webhooks":{}}