Get catchment metrics
curl --request GET \
--url https://api.catchment.app/v1/catchment-metrics \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.catchment.app/v1/catchment-metrics"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.catchment.app/v1/catchment-metrics', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"request_id": "ee49f8a0-d6b2-46ec-91b5-b066641996a0",
"catchment": {
"cell_count": 133,
"miles": 3,
"type": "radius"
},
"data_version": "demographics_build:8eac09a5-bcf1-48cb-a2c2-d3a33a52ee7c",
"location": {
"latitude": 51.2786,
"longitude": 0.522342,
"postcode": "ME14 1XQ",
"postcode_terminated_on": null
},
"projection_year": null,
"values": {
"avg_price": 368531,
"population_85_plus_pct": 2.5,
"carehome_demand": 790,
"existing_beds_all": 1208,
"existing_beds_ensuite": 913,
"existing_beds_wetroom": 405,
"undersupply_existing_all": -418,
"undersupply_existing_ensuite": -123,
"undersupply_existing_wetroom": 385,
"bed_weighted_avg_fee_residential_week": 1609,
"bed_weighted_avg_fee_nursing_week": 1794,
"planned_permitted_beds": 0,
"planned_undecided_beds": 0
},
"metric_details": {
"avg_price": {
"status": "available",
"reason": null,
"source": "HM Land Registry Price Paid Data"
},
"population_85_plus_pct": {
"status": "available",
"reason": null,
"source": "ONS Census 2021"
},
"carehome_demand": {
"status": "available",
"reason": null,
"source": "PICSy age-based carehome demand model",
"population_projection_year": null
},
"existing_beds_all": {
"status": "available",
"reason": null,
"source": "PICSy published carehome supply and quoted fees"
},
"existing_beds_ensuite": {
"status": "available",
"reason": null,
"source": "PICSy published carehome supply and quoted fees"
},
"existing_beds_wetroom": {
"status": "available",
"reason": null,
"source": "PICSy published carehome supply and quoted fees"
},
"undersupply_existing_all": {
"status": "available",
"reason": null,
"source": "PICSy carehome demand and published bed supply",
"population_projection_year": null
},
"undersupply_existing_ensuite": {
"status": "available",
"reason": null,
"source": "PICSy carehome demand and published bed supply",
"population_projection_year": null
},
"undersupply_existing_wetroom": {
"status": "available",
"reason": null,
"source": "PICSy carehome demand and published bed supply",
"population_projection_year": null
},
"bed_weighted_avg_fee_residential_week": {
"status": "available",
"reason": null,
"source": "PICSy published carehome supply and quoted fees",
"sample_count": 18,
"beds_covered": 895
},
"bed_weighted_avg_fee_nursing_week": {
"status": "available",
"reason": null,
"source": "PICSy published carehome supply and quoted fees",
"sample_count": 12,
"beds_covered": 732
},
"planned_permitted_beds": {
"status": "available",
"reason": null,
"source": "PICSy published care planning pipeline"
},
"planned_undecided_beds": {
"status": "available",
"reason": null,
"source": "PICSy published care planning pipeline"
}
},
"local_authority": {
"requested_area": {
"code": "E07000110",
"name": "Maidstone",
"kind": "lad"
},
"authority": {
"code": "E10000016",
"name": "Kent",
"kind": "ctyua"
},
"values": {
"la_avg_fee_residential_week": 1063,
"la_avg_fee_nursing_week": 1240,
"la_occupancy_pct": 88.27
},
"metric_details": {
"la_avg_fee_residential_week": {
"status": "available",
"reason": null,
"period": "2024-25",
"source": "Local authority fee publications",
"source_metadata": null,
"reporting_authority": {
"code": "E10000016",
"name": "Kent",
"kind": "ctyua"
}
},
"la_avg_fee_nursing_week": {
"status": "available",
"reason": null,
"period": "2024-25",
"source": "Local authority fee publications",
"source_metadata": null,
"reporting_authority": {
"code": "E10000016",
"name": "Kent",
"kind": "ctyua"
}
},
"la_occupancy_pct": {
"status": "available",
"reason": null,
"period": "2026-08-01",
"source": "Capacity Tracker",
"reporting_authority": {
"code": "E10000016",
"name": "Kent",
"kind": "ctyua"
}
}
}
},
"credits": {
"used": 16,
"remaining": 984
}
}Catchments
Get catchment metrics
Requested catchment metrics and, when selected, separate local-authority fee/occupancy values for the postcode. Supply exactly one of drive_minutes or radius_miles. The request reserves the number of unique metrics; successful non-null values consume one credit each.
GET
/
v1
/
catchment-metrics
Get catchment metrics
curl --request GET \
--url https://api.catchment.app/v1/catchment-metrics \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.catchment.app/v1/catchment-metrics"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.catchment.app/v1/catchment-metrics', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"request_id": "ee49f8a0-d6b2-46ec-91b5-b066641996a0",
"catchment": {
"cell_count": 133,
"miles": 3,
"type": "radius"
},
"data_version": "demographics_build:8eac09a5-bcf1-48cb-a2c2-d3a33a52ee7c",
"location": {
"latitude": 51.2786,
"longitude": 0.522342,
"postcode": "ME14 1XQ",
"postcode_terminated_on": null
},
"projection_year": null,
"values": {
"avg_price": 368531,
"population_85_plus_pct": 2.5,
"carehome_demand": 790,
"existing_beds_all": 1208,
"existing_beds_ensuite": 913,
"existing_beds_wetroom": 405,
"undersupply_existing_all": -418,
"undersupply_existing_ensuite": -123,
"undersupply_existing_wetroom": 385,
"bed_weighted_avg_fee_residential_week": 1609,
"bed_weighted_avg_fee_nursing_week": 1794,
"planned_permitted_beds": 0,
"planned_undecided_beds": 0
},
"metric_details": {
"avg_price": {
"status": "available",
"reason": null,
"source": "HM Land Registry Price Paid Data"
},
"population_85_plus_pct": {
"status": "available",
"reason": null,
"source": "ONS Census 2021"
},
"carehome_demand": {
"status": "available",
"reason": null,
"source": "PICSy age-based carehome demand model",
"population_projection_year": null
},
"existing_beds_all": {
"status": "available",
"reason": null,
"source": "PICSy published carehome supply and quoted fees"
},
"existing_beds_ensuite": {
"status": "available",
"reason": null,
"source": "PICSy published carehome supply and quoted fees"
},
"existing_beds_wetroom": {
"status": "available",
"reason": null,
"source": "PICSy published carehome supply and quoted fees"
},
"undersupply_existing_all": {
"status": "available",
"reason": null,
"source": "PICSy carehome demand and published bed supply",
"population_projection_year": null
},
"undersupply_existing_ensuite": {
"status": "available",
"reason": null,
"source": "PICSy carehome demand and published bed supply",
"population_projection_year": null
},
"undersupply_existing_wetroom": {
"status": "available",
"reason": null,
"source": "PICSy carehome demand and published bed supply",
"population_projection_year": null
},
"bed_weighted_avg_fee_residential_week": {
"status": "available",
"reason": null,
"source": "PICSy published carehome supply and quoted fees",
"sample_count": 18,
"beds_covered": 895
},
"bed_weighted_avg_fee_nursing_week": {
"status": "available",
"reason": null,
"source": "PICSy published carehome supply and quoted fees",
"sample_count": 12,
"beds_covered": 732
},
"planned_permitted_beds": {
"status": "available",
"reason": null,
"source": "PICSy published care planning pipeline"
},
"planned_undecided_beds": {
"status": "available",
"reason": null,
"source": "PICSy published care planning pipeline"
}
},
"local_authority": {
"requested_area": {
"code": "E07000110",
"name": "Maidstone",
"kind": "lad"
},
"authority": {
"code": "E10000016",
"name": "Kent",
"kind": "ctyua"
},
"values": {
"la_avg_fee_residential_week": 1063,
"la_avg_fee_nursing_week": 1240,
"la_occupancy_pct": 88.27
},
"metric_details": {
"la_avg_fee_residential_week": {
"status": "available",
"reason": null,
"period": "2024-25",
"source": "Local authority fee publications",
"source_metadata": null,
"reporting_authority": {
"code": "E10000016",
"name": "Kent",
"kind": "ctyua"
}
},
"la_avg_fee_nursing_week": {
"status": "available",
"reason": null,
"period": "2024-25",
"source": "Local authority fee publications",
"source_metadata": null,
"reporting_authority": {
"code": "E10000016",
"name": "Kent",
"kind": "ctyua"
}
},
"la_occupancy_pct": {
"status": "available",
"reason": null,
"period": "2026-08-01",
"source": "Capacity Tracker",
"reporting_authority": {
"code": "E10000016",
"name": "Kent",
"kind": "ctyua"
}
}
}
},
"credits": {
"used": 16,
"remaining": 984
}
}Geography
Catchments use cumulative, precomputed H3 resolution-8 bands around the postcode’s origin cell. Postcodes in the same cell resolve to the same catchment. Radius is a grid approximation of a circle; drive time uses precomputed road-network bands. No saved-site filters or manually edited catchment boundaries are applied. The authority lookup uses the postcode point.local_authority.requested_area identifies its district; authority identifies the social-care authority, often the parent county. A radius crossing several authorities still returns authority metrics for the postcode, not an average across the circle. Each authority value also identifies its actual reporting_authority.
Values and availability
values and metric_details contain requested catchment keys. Authority keys, when requested, are returned separately in local_authority.values and local_authority.metric_details. Each metric is available or unavailable; missing data stays null. A valid request can contain both. Values follow the catalogue’s rounding and null policy.
Open, non-specialist care homes form the older-person bed supply. Undersupply subtracts each bed category from the same modelled demand and retains negative values for surplus. The three undersupply figures overlap and must not be added together. They exclude planning; permitted and undecided pipeline beds are separate metrics.
Private residential and nursing quoted fees remain separate. Bed-weighted means use each contributing home’s total beds, not an observed number of residents paying that fee. Residential fee publication requires at least five homes and 150 covered beds; nursing requires three homes and 100 beds. Below-threshold fees are null, with sample counts and bed coverage in the details. Five years of historical private fees is not available.
Projection and periods
Withoutprojection_year, demand uses the source-population age bands. With it, the postcode centroid is converted to a resolution-8 H3 cell. The projection service selects the LAD with the largest recorded overlap for that cell, and uses its factors for supported population counts and derived demand/undersupply. The same factors apply throughout the catchment. Current published supply, fees, planning and authority figures are unchanged. Missing required factors can make projected metrics unavailable.
population_projection_year on demand and undersupply details is null when unprojected. Unprojected undersupply combines source-period demand with current published supply. data_version identifies the demographic catchment build; other published datasets are read at request time and are not historical snapshots of that build.
Credits
The full number of unique requested metrics must be available for reservation. Only usable numeric values in the successful response consume credits, including zero. Unavailable values release their reservation. See the credit and request rules.Authorizations
An API key created under Account > Catchment API. Keys start with ck_.
Query Parameters
UK postcode. Case and spacing are ignored. Resolved to its centroid in the ONS Postcode Directory.
Example:
"ME14 1XQ"
Drive-time catchment in minutes. Mutually exclusive with radius_miles.
Required range:
1 <= x <= 25Example:
10
Radius catchment in miles, measured in a straight line. Mutually exclusive with drive_minutes.
Required range:
1 <= x <= 10Comma-separated keys supporting catchment or local_authority. At most 50 distinct keys; duplicates and empty entries are removed. The catalogue is filtered by organisation access.
Example:
"avg_price,carehome_demand,existing_beds_all,bed_weighted_avg_fee_residential_week,bed_weighted_avg_fee_nursing_week,la_occupancy_pct"
Year to project population counts to. Omit for observed values.
Required range:
2026 <= x <= 2035Example:
2032
Response
Metric values for the catchment.
- Option 1
- Option 2
Show child attributes
Show child attributes
Version of the precomputed demographic catchment. Care supply, fees, planning and authority observations are read from their published datasets at request time; this version does not identify a historical snapshot of those datasets.
Show child attributes
Show child attributes
The year population counts were projected to, or null for observed values.
Only requested metrics for this geography. Null means unavailable; zero can be a usable value.
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Included only when at least one local-authority metric is requested. These values describe the postcode's reporting authority, not the catchment.
Show child attributes
Show child attributes