> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catchment.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Endpoint, authentication, response, credit and coverage reference for the Catchment API.

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`](https://docs.catchment.app/api-reference/catchments/get-catchment-metrics) | Postcode catchment, with separate authority values when requested | Usable metric values |
| `GET` | [`/v1/hex-metrics`](https://docs.catchment.app/api-reference/cells/get-hex-metrics) | One H3 resolution-8 cell | Usable metric values |
| `GET` | [`/v1/local-authority-metrics`](https://docs.catchment.app/api-reference/local-authorities/get-local-authority-metrics) | Resolved social-care reporting authority | Usable metric values |
| `GET` | [`/v1/area-cells`](https://docs.catchment.app/api-reference/area-mappings/list-cells-for-an-area) | Cells overlapping a statistical area | Free |
| `GET` | [`/v1/cell-areas`](https://docs.catchment.app/api-reference/area-mappings/list-areas-for-a-cell) | Statistical areas overlapping a cell | Free |
| `GET` | [`/v1/metrics`](https://docs.catchment.app/api-reference/metrics/list-metrics) | Available metric definitions | Free |

## Base URL

```text theme={null}
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

```text theme={null}
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](https://docs.catchment.app/api-reference/metric-catalogue.md) 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`](https://docs.catchment.app/api-reference/metrics/list-metrics).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.