> ## 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.

# 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.

## 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.


## OpenAPI

````yaml /api-reference/openapi.json get /v1/hex-metrics
openapi: 3.1.0
info:
  title: Catchment API
  version: 1.1.0
  description: >-
    Postcode catchment, H3 cell and local-authority metrics, with a discoverable
    metric catalogue, area mappings and organisation-level trial credits. Access
    must be explicitly enabled for the organisation. This reference describes
    the current implementation; availability depends on the deployed version.
servers:
  - url: https://api.catchment.app
security:
  - bearerAuth: []
tags:
  - name: Catchments
    description: Metric values for a catchment around a postcode.
  - name: Cells
    description: Metric values for a single H3 cell.
  - name: Area mappings
    description: Overlaps between statistical areas and H3 cells.
  - name: Metrics
    description: The metrics available to request.
  - name: Local authorities
    description: Fee and occupancy values for the reporting authority.
paths:
  /v1/hex-metrics:
    get:
      tags:
        - Cells
      summary: Get hex metrics
      description: >-
        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.
      operationId: getHexMetrics
      parameters:
        - name: h3
          in: query
          required: true
          description: H3 cell index at resolution 8. Case is ignored.
          schema:
            type: string
            example: 88195da493fffff
        - name: metrics
          in: query
          required: true
          description: >-
            Comma-separated metric keys, at most 50. Duplicates are ignored.
            Keys are listed by `GET /v1/metrics` and in the metric catalogue.
          schema:
            type: string
            example: avg_price,population_75_plus,population_75_plus_pct
        - name: projection_year
          in: query
          required: false
          description: Year to project population counts to. Omit for observed values.
          schema:
            type: integer
            minimum: 2026
            maximum: 2035
            example: 2032
      responses:
        '200':
          description: Metric values for the cell.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-Credits-Used:
              $ref: '#/components/headers/CreditsUsed'
            X-Credits-Remaining:
              $ref: '#/components/headers/CreditsRemaining'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HexMetricsResponse'
              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
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/MetricForbidden'
        '404':
          description: The cell has no metric data.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                request_id: 261bfcf8-67ac-4d0b-bc7a-91d8d271189f
                error:
                  code: outside_coverage
                  message: >-
                    Metric data covers Great Britain. There is none for this
                    cell.
                credits:
                  used: 0
                  remaining: 1000
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-Credits-Used:
              $ref: '#/components/headers/CreditsUsed'
            X-Credits-Remaining:
              $ref: '#/components/headers/CreditsRemaining'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  headers:
    RequestId:
      description: Identifies the request. Quote it when reporting a problem.
      schema:
        type: string
        format: uuid
    RateLimitLimit:
      description: Requests allowed per minute for this key.
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests left for this key in the current minute.
      schema:
        type: integer
    CreditsUsed:
      schema:
        type: integer
        minimum: 0
        maximum: 50
      description: >-
        Credits used, once authenticated requests reach and complete credit
        accounting.
    CreditsRemaining:
      schema:
        type: integer
        minimum: 0
      description: >-
        Available organisation balance at settlement, excluding outstanding
        holds.
    CacheControl:
      schema:
        type: string
        const: no-store
      description: API JSON responses are not cached.
  schemas:
    HexMetricsResponse:
      type: object
      required:
        - request_id
        - cell
        - projection_year
        - values
        - credits
        - metric_details
      properties:
        request_id:
          type: string
          format: uuid
        cell:
          type: object
          required:
            - h3
            - latitude
            - longitude
          properties:
            h3:
              type: string
              description: The cell, lower case.
            latitude:
              type: number
              description: Latitude of the cell's centre.
            longitude:
              type: number
              description: Longitude of the cell's centre.
        projection_year:
          type:
            - integer
            - 'null'
          description: >-
            The year population counts were projected to, or null for observed
            values.
        values:
          type: object
          additionalProperties:
            type:
              - number
              - 'null'
          description: >-
            Only requested metrics for this geography. Null means unavailable;
            zero can be a usable value.
        credits:
          $ref: '#/components/schemas/Credits'
        metric_details:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MetricDetail'
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            Present on requests handled by an endpoint. The unknown-path 404
            response has no request ID.
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - area_not_found
                - forbidden
                - internal_error
                - invalid_request
                - not_found
                - outside_coverage
                - postcode_not_found
                - rate_limited
                - unauthorized
                - credits_exhausted
            message:
              type: string
            unknown_metrics:
              type: array
              description: >-
                The metric keys that were not recognised, when that is the
                problem.
              items:
                type: string
            forbidden_metrics:
              type: array
              items:
                type: string
              description: Requested keys without dataset access.
            unsupported_metrics:
              type: array
              items:
                type: string
              description: Requested keys unsupported by this endpoint's geography.
            required_credits:
              type: integer
              minimum: 1
              maximum: 50
              description: >-
                Requested reservation that the available organisation balance
                cannot cover.
        credits:
          $ref: '#/components/schemas/Credits'
    Credits:
      type: object
      required:
        - used
        - remaining
      properties:
        used:
          type: integer
          minimum: 0
          maximum: 50
          description: >-
            Credits used by this request. One per distinct usable numeric metric
            returned by a successful metric request; zero for free endpoints or
            errors.
        remaining:
          type: integer
          minimum: 0
          description: >-
            Organisation credits available after settlement, excluding other
            in-flight reservations. Shared by all keys in the organisation.
    MetricDetail:
      type: object
      required:
        - status
        - reason
        - source
      properties:
        status:
          type: string
          enum:
            - available
            - unavailable
        reason:
          type:
            - string
            - 'null'
          description: >-
            Explanation when the value is unavailable; null for an available
            value.
        source:
          type:
            - string
            - 'null'
        period:
          type:
            - string
            - 'null'
          description: >-
            Financial year such as 2024-25 for a fee, or ISO month-start date
            such as 2026-08-01 for occupancy. Null if unavailable or outside
            coverage. Catchment details do not include this field.
        reporting_authority:
          anyOf:
            - $ref: '#/components/schemas/Authority'
            - type: 'null'
          description: >-
            Authority whose published figure is returned. May differ from the
            requested district.
        source_metadata:
          type:
            - object
            - 'null'
          additionalProperties: true
          description: >-
            Source-dependent council-fee evidence. May identify sourceKind,
            feeBasis, sourceScope, sourceNationCode, effectivePeriod, sourceUrl,
            nursing contributions and review status. Null when detailed evidence
            is unavailable; do not infer a funding basis.
        sample_count:
          type:
            - number
            - 'null'
          description: Homes with usable private fees for the care type.
        beds_covered:
          type:
            - number
            - 'null'
          description: >-
            Total beds at the homes contributing to that private-fee sample; not
            a count of beds charged this fee.
        population_projection_year:
          type:
            - integer
            - 'null'
          description: >-
            Present on demand and undersupply details: selected projection year,
            or null for source-population demand.
    Authority:
      type: object
      required:
        - code
        - name
        - kind
      properties:
        code:
          type: string
          description: ONS authority code.
        name:
          type: string
        kind:
          type: string
          enum:
            - lad
            - ctyua
          description: District, or county/unitary authority.
  responses:
    InvalidRequest:
      description: >-
        Invalid parameters or unknown/unsupported metric keys.
        error.unknown_metrics and error.unsupported_metrics identify the
        rejected keys.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            unknown:
              value:
                request_id: 6d857aeb-3b97-4e6b-a03f-aa39400d9ed9
                error:
                  code: invalid_request
                  message: >-
                    Unknown metrics: not_a_metric. GET /v1/metrics lists the
                    metrics available.
                  unknown_metrics:
                    - not_a_metric
                credits:
                  used: 0
                  remaining: 974
            unsupported:
              value:
                request_id: f61583ed-950f-4ae8-9fe5-6eb44e389494
                error:
                  code: invalid_request
                  message: >-
                    These metrics do not support this endpoint's geography:
                    la_occupancy_pct. GET /v1/metrics lists supported
                    geographies.
                  unsupported_metrics:
                    - la_occupancy_pct
                credits:
                  used: 0
                  remaining: 974
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-Credits-Used:
          $ref: '#/components/headers/CreditsUsed'
        X-Credits-Remaining:
          $ref: '#/components/headers/CreditsRemaining'
    Unauthorized:
      description: The API key is missing, unknown or revoked.
      headers:
        WWW-Authenticate:
          schema:
            type: string
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            request_id: 4bc9eb08-0d69-4c6e-b226-1e66eda03bdc
            error:
              code: unauthorized
              message: >-
                A valid API key is required. Send it as an Authorization: Bearer
                header.
    MetricForbidden:
      description: >-
        Organisation API access is disabled/expired, required metric access is
        absent, or the available credit balance cannot cover the requested
        reservation. credits_exhausted consumes no credits. A valid request
        reserves one credit per unique requested metric before data is read.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            access:
              value:
                request_id: 0e2e47c8-e798-4247-a077-d6b4d66cb70f
                error:
                  code: forbidden
                  message: API access is not enabled for this organisation.
            credits:
              value:
                request_id: e91c7546-82f5-4af6-82de-f48ca6a5a469
                error:
                  code: credits_exhausted
                  message: >-
                    This organisation has insufficient API credits. Contact your
                    administrator for a top-up.
                  required_credits: 1
                credits:
                  used: 0
                  remaining: 0
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-Credits-Used:
          $ref: '#/components/headers/CreditsUsed'
        X-Credits-Remaining:
          $ref: '#/components/headers/CreditsRemaining'
    RateLimited:
      description: >-
        Per-key request limit reached in the current fixed calendar-minute
        window. The limit applies to free and metered requests. No credits are
        consumed.
      headers:
        Retry-After:
          description: Seconds until the next minute starts.
          schema:
            type: integer
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            request_id: c4c917f1-4162-47ac-b3d9-1642905491ba
            error:
              code: rate_limited
              message: Rate limit of 60 requests a minute reached.
    InternalError:
      description: >-
        The request or its accounting could not complete. Credits and rate-limit
        headers may be absent when accounting is unavailable. No metric data is
        sent before successful credit settlement.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            accountingFailure:
              summary: Illustrative server failure before credit accounting completes
              value:
                request_id: 9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d
                error:
                  code: internal_error
                  message: >-
                    The request could not be completed. Quote the request id if
                    this keeps happening.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-Credits-Used:
          $ref: '#/components/headers/CreditsUsed'
        X-Credits-Remaining:
          $ref: '#/components/headers/CreditsRemaining'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key created under **Account** > **Catchment API**. Keys start
        with `ck_`.

````

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