Overview

The Catchment API returns postcode-catchment, H3-cell and local-authority metrics. Access is enabled per organisation. A valid API key does not grant access to additional datasets or metrics. This reference describes the current implementation. The beta service available to an organisation depends on its deployed version and enabled access.

Endpoints

Method	Path	Response geography	Credits
`GET`	`/v1/catchment-metrics`	Postcode catchment, with separate authority values when requested	Usable metric values
`GET`	`/v1/hex-metrics`	One H3 resolution-8 cell	Usable metric values
`GET`	`/v1/local-authority-metrics`	Resolved social-care reporting authority	Usable metric values
`GET`	`/v1/area-cells`	Cells overlapping a statistical area	Free
`GET`	`/v1/cell-areas`	Statistical areas overlapping a cell	Free
`GET`	`/v1/metrics`	Available metric definitions	Free

Base URL

https://api.catchment.app/v1

The API is served on its dedicated host. The application host does not serve /v1 endpoints. Local development uses http://api.catchment.app.local:3002/v1.

Authentication and access

Authorization: Bearer <API_KEY>

Property	Contract
Format	`ck_` followed by 43 URL-safe characters
Issued by	Organisation admins under Account > Catchment API
Scope	The organisation, independently of the member who created the key
Storage	The key is shown once; only its hash is stored
Revocation	Subsequent requests using the key return `401`
API permission	The organisation must have API access enabled and unexpired
Metric permission	Care, planning and other restricted outputs retain their dataset and metric access requirements
Discovery	`GET /v1/metrics` lists only the metrics the organisation can request

Enabled external organisations can use the API. Membership of an internal organisation is not required. API access is opt-in; a plan or package alone does not enable it.

Requests

Property	Contract
Method	`GET`
Parameters	Query string
Unknown parameters	Rejected with `400`, except `/v1/metrics`, which ignores them
Repeated parameter names	Rejected with `400`, except `/v1/metrics`, which ignores them
`metrics`	Comma-separated keys; whitespace and empty entries are removed, duplicate keys count once
Metric limit	At most 50 distinct keys per request
Catchment size	Exactly one of `radius_miles` from 1–10 or `drive_minutes` from 1–25; whole numbers only
Projection	Optional `projection_year`, 2026–2035, on catchment and hex requests only

A postcode request can mix catchment and authority keys. Catchment values stay in values; authority values stay in local_authority.values. Neither section describes the other geography.

Responses

Field or header	Contract
Content type	`application/json`
Caching	`Cache-Control: no-store`
Request ID	UUID in `X-Request-Id` and `request_id`, except the unknown-path response
`values`	Requested numeric metric values, or `null` where unavailable
`metric_details`	Availability status, reason and source for each value; includes fee sample coverage or population projection basis where relevant
`local_authority`	Requested area, resolved social-care authority, requested authority values and their details
`credits`	Credits used by this request and remaining available organisation credits, after successful accounting

Missing values are not zero. Care counts preserve genuine zeros; existing demographic and housing metrics retain their own null policies. A valid request with unavailable metrics returns 200, with null values and status: "unavailable". A service failure returns 500 rather than being presented as unavailable data.

Credits

Rule	Contract
Initial allowance	1,000 API trial credits once per organisation when enabled; an already-enabled organisation is initialized on first use
Pool	Shared by every API key in the organisation
Cost	One credit per distinct requested metric returning a finite numeric value in a successful response; zero is a usable value
Free results	Unavailable/null values, failed or invalid requests, catalogue and area-mapping requests
Internal inputs	Dependencies used to calculate a requested metric do not consume additional credits
Reservation	The available balance must cover all distinct requested keys before the data work begins
Settlement	Unused reserved credits are released; only usable returned values are deducted
Interrupted requests	Outstanding holds expire after five minutes and are reclaimed by a subsequent request
Balance	`credits.remaining` excludes other outstanding reservations
Exhaustion	`403` with `error.code: "credits_exhausted"` and `error.required_credits`; no charge
Repeated successful requests	Consume credits each time
Renewal	No automatic reset. More credits can be added manually by the team managing access
Key/access changes	Creating a key or disabling/re-enabling access does not replenish credits

These credits are separate from PICSy Analyst credit. They are a trial usage allowance, not a payment or subscription charge. Requests that complete credit accounting return credits.used and credits.remaining, mirrored by X-Credits-Used and X-Credits-Remaining. Authentication failures, rate-limit failures and accounting failures may omit these fields. Free endpoints remain available at a zero credit balance, subject to access and rate limits. Client-supplied idempotency keys are not supported. A new attempt is a new request. If transport or accounting fails, settlement can be uncertain; include the original request ID when reporting a credit discrepancy.

Rate limits

Property	Contract
Default limit	60 requests per minute per API key; deployment configuration can set another value
Window	Fixed calendar minute; resets at the next minute
Scope	Every request with a valid key, including free endpoints
Response headers	`X-RateLimit-Limit` and `X-RateLimit-Remaining` after passing the rate-limit check
On limit	`429` with `Retry-After`, in seconds; no credits consumed

The rate limit and credit balance are separate. Rate limiting is per key; credits are shared across the organisation.

Errors

Status	`error.code`	Cause
`400`	`invalid_request`	Invalid parameters or unknown metric keys; `unknown_metrics` identifies unrecognized keys
`400`	`invalid_request`	Unsupported endpoint geography; `unsupported_metrics` identifies the affected keys
`401`	`unauthorized`	Missing, unknown or revoked key
`403`	`forbidden`	API access disabled/expired, or missing metric permission; `forbidden_metrics` identifies metric-level denials
`403`	`credits_exhausted`	The organisation cannot reserve the requested credits
`404`	`postcode_not_found`	Postcode not found
`404`	`area_not_found`	Area or authority code not found
`404`	`outside_coverage`	No precomputed catchment, cell data or area mapping at the requested location
`404`	`not_found`	Unknown endpoint path or wrong API host; no request ID
`405`	—	Unsupported HTTP method; framework response, not an API error object
`429`	`rate_limited`	Per-key request limit reached
`500`	`internal_error`	The request or its accounting could not complete

The OpenAPI reference defines the JSON error fields. Credits remain optional on error responses because authentication or accounting may not have completed.

Coverage and periods

Catchment and cell metrics cover Great Britain where the necessary source data is available. Postcodes in Northern Ireland have no precomputed catchment. Area mappings support output areas across Great Britain, LSOAs/MSOAs in England and Wales, and data zones/intermediate zones in Scotland. Authority occupancy covers English reporting areas only. Districts can resolve to parent counties. Each occupancy category uses its latest published source month; missing or suppressed authority values stay unavailable. No older month or England average is substituted. Council fees use the latest usable financial year independently for residential and nursing care; funding bases can differ between sources and nations. period_basis in the metric catalogue identifies source-period, current published, mixed population/supply, latest-financial-year or latest-reporting-month values. It does not make all datasets current-year observations. projection_year affects supported population inputs and derived demand; existing beds, quoted fees, planning and authority observations are not projected. Private residential and nursing fees are separate. Five years of historical private fees is not provided. Individual metric availability and the organisation’s current permitted keys are returned by GET /v1/metrics.

Catchments

Cells

Local authorities

Area mappings

Metrics

Overview

Endpoints

Base URL

Authentication and access

Requests

Responses

Credits

Rate limits

Errors

Coverage and periods

​Endpoints

​Base URL

​Authentication and access

​Requests

​Responses

​Credits

​Rate limits

​Errors

​Coverage and periods

Endpoints

Base URL

Authentication and access

Requests

Responses

Credits

Rate limits

Errors

Coverage and periods