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

# List areas for a cell

> Returns the areas of one type that overlap an H3 cell, with the share of each area in the cell and the share of the cell each area covers. Areas are ordered by `share_of_cell`, largest first. This endpoint uses no credits.

## Area types

| `type` | Areas | Coverage |
| - | - | - |
| `oa` | Output areas: 2021 in England and Wales, 2022 in Scotland | Great Britain |
| `lsoa` | 2021 lower layer super output areas | England and Wales |
| `msoa` | 2021 middle layer super output areas | England and Wales |
| `data_zone` | 2022 data zones | Scotland |
| `intermediate_zone` | 2022 intermediate zones | Scotland |

A cell outside a type's coverage returns an empty `areas` list, for example an LSOA request for a cell in Scotland.

## Shares

| Field | Definition |
| - | - |
| `share_of_area` | Fraction of the area's land that lies in the cell. Summed over an area's cells it is 1, less a small remainder for some coastal areas. |
| `share_of_cell` | Fraction of the cell covered by the area. Summed over a cell's areas of one type it is 1 for a cell wholly on land, and less for a cell partly at sea. |

* Shares are by area, measured on the spheroid. They are not the address-weighted shares used for some metrics.
* Shares are rounded to 6 decimal places.
* Cells are H3 resolution 8, the grid the metrics are built on.
* A cell outside the grid returns `404` with `outside_coverage`.


## OpenAPI

````yaml /api-reference/openapi.json get /v1/cell-areas
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/cell-areas:
    get:
      tags:
        - Area mappings
      summary: List areas for a cell
      description: >-
        Returns the areas of one type that overlap an H3 cell, with the share of
        each area in the cell and the share of the cell each area covers. Areas
        are ordered by `share_of_cell`, largest first. This endpoint uses no
        credits.
      operationId: listCellAreas
      parameters:
        - name: h3
          in: query
          required: true
          description: H3 cell index at resolution 8. Case is ignored.
          schema:
            type: string
            example: 88195da493fffff
        - name: type
          in: query
          required: true
          description: Area type.
          schema:
            $ref: '#/components/schemas/AreaType'
      responses:
        '200':
          description: The areas that overlap 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/CellAreasResponse'
              example:
                request_id: 475e5c94-b1de-4ed8-9268-f243c89c50d8
                areas:
                  - code: E00023938
                    share_of_area: 0.762328
                    share_of_cell: 0.324435
                  - code: E00190384
                    share_of_area: 0.854688
                    share_of_cell: 0.247392
                  - code: E00023937
                    share_of_area: 0.368425
                    share_of_cell: 0.116549
                  - code: E00023939
                    share_of_area: 0.380803
                    share_of_cell: 0.066488
                  - code: E00023936
                    share_of_area: 0.12474
                    share_of_cell: 0.06293
                  - code: E00023941
                    share_of_area: 0.653133
                    share_of_cell: 0.03963
                  - code: E00023943
                    share_of_area: 1
                    share_of_cell: 0.032123
                  - code: E00175226
                    share_of_area: 0.190148
                    share_of_cell: 0.031734
                  - code: E00023935
                    share_of_area: 0.079619
                    share_of_cell: 0.030109
                  - code: E00023942
                    share_of_area: 0.331528
                    share_of_cell: 0.028748
                  - code: E00023946
                    share_of_area: 0.056701
                    share_of_cell: 0.019864
                cell:
                  h3: 88195da493fffff
                type: oa
                credits:
                  used: 0
                  remaining: 977
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: The cell is outside the grid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                request_id: f06982cd-c598-4b66-98d8-9b54a4201f72
                error:
                  code: outside_coverage
                  message: Area mappings cover Great Britain. This cell is outside it.
                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:
  schemas:
    AreaType:
      type: string
      enum:
        - oa
        - lsoa
        - msoa
        - data_zone
        - intermediate_zone
    CellAreasResponse:
      type: object
      required:
        - request_id
        - areas
        - cell
        - type
        - credits
      properties:
        request_id:
          type: string
          format: uuid
        areas:
          type: array
          items:
            type: object
            required:
              - code
              - share_of_area
              - share_of_cell
            properties:
              code:
                type: string
              share_of_area:
                type: number
                minimum: 0
                maximum: 1
                description: Fraction of the area's land in the cell.
              share_of_cell:
                type:
                  - number
                  - 'null'
                minimum: 0
                maximum: 1
                description: Fraction of the cell covered by the area.
        cell:
          type: object
          required:
            - h3
          properties:
            h3:
              type: string
        type:
          $ref: '#/components/schemas/AreaType'
        credits:
          $ref: '#/components/schemas/Credits'
    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.
  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.
  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.
    Forbidden:
      description: The key is valid but organisation API access is disabled or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            request_id: 0e2e47c8-e798-4247-a077-d6b4d66cb70f
            error:
              code: forbidden
              message: API access is not enabled for this organisation.
      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'
    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.