Get hex metrics

Metric values for one H3 resolution-8 cell. Only keys supporting hex are accepted. Care supply, planning and authority metrics are not supported at this endpoint. Successful non-null requested values consume one credit each.

GET /v1/hex-metrics

Get hex metrics

cURL

curl --request GET \
  --url https://api.catchment.app/v1/hex-metrics \
  --header 'Authorization: Bearer <token>'

200

Example

{
  "request_id": "b08cbb07-16ad-4acc-b302-27464308ada6",
  "cell": {
    "h3": "88195da493fffff",
    "latitude": 51.50195883361916,
    "longitude": -0.13825777606139614
  },
  "projection_year": null,
  "values": {
    "population_total": 1167,
    "avg_price": 1673833
  },
  "metric_details": {
    "population_total": {
      "status": "available",
      "reason": null,
      "source": "ONS Census 2021"
    },
    "avg_price": {
      "status": "available",
      "reason": null,
      "source": "HM Land Registry Price Paid Data"
    }
  },
  "credits": {
    "used": 2,
    "remaining": 977
  }
}

​

Geography and values

Values describe the single resolution-8 cell. cell.latitude and cell.longitude are its centre. Source-area data is apportioned to H3 cells by the existing population/address and area rules. Null values are unavailable. The catalogue identifies which keys support hex; catchment-only and authority-only keys return invalid_request with unsupported_metrics.

​

Projection

Without projection_year, population values use their source period. With it, supported population counts and their derived metrics use factors for the LAD with the largest recorded overlap with the H3 cell. Other metrics are unchanged. Source periods are not necessarily the current year.

​

Credits

One credit is reserved per distinct requested key. Successful numeric values, including zero, consume credits; unavailable values do not. Metadata and internal calculation inputs are not separately charged.

Authorizations

Authorization · string · header · required

An API key created under Account > Catchment API. Keys start with ck_.

Query Parameters

h3 · string · required

H3 cell index at resolution 8. Case is ignored.

Example:

"88195da493fffff"

metrics · string · required

Comma-separated metric keys, at most 50. Duplicates are ignored. Keys are listed by GET /v1/metrics and in the metric catalogue.

Example:

"avg_price,population_75_plus,population_75_plus_pct"

projection_year · integer

Year to project population counts to. Omit for observed values.

Required range: 2026 <= x <= 2035

Example:

2032

Response

200

application/json

Metric values for the cell.

request_id · string<uuid> · required

cell · object · required

Show child attributes

projection_year · integer | null · required

The year population counts were projected to, or null for observed values.

values · object · required

Only requested metrics for this geography. Null means unavailable; zero can be a usable value.

Show child attributes

credits · object · required

Show child attributes

metric_details · object · required

Show child attributes