> ## 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 cells for an area

> Returns the H3 cells an area overlaps, with the share of the area in each cell and the share of each cell the area covers. Cells are ordered by `share_of_area`, 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 |

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


## OpenAPI

````yaml /api-reference/openapi.json get /v1/area-cells
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/area-cells:
    get:
      tags:
        - Area mappings
      summary: List cells for an area
      description: >-
        Returns the H3 cells an area overlaps, with the share of the area in
        each cell and the share of each cell the area covers. Cells are ordered
        by `share_of_area`, largest first. This endpoint uses no credits.
      operationId: listAreaCells
      parameters:
        - name: type
          in: query
          required: true
          description: Area type.
          schema:
            $ref: '#/components/schemas/AreaType'
        - name: code
          in: query
          required: true
          description: 'Area code: a letter followed by eight digits. Case is ignored.'
          schema:
            type: string
            example: E01000001
      responses:
        '200':
          description: The cells the area overlaps.
          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/AreaCellsResponse'
              example:
                request_id: dcf66588-6358-4b1e-8e67-39a5efef8f3a
                area:
                  code: E01000001
                  type: lsoa
                cells:
                  - h3: 88194ad329fffff
                    share_of_area: 0.512728
                    share_of_cell: 0.122357
                  - h3: 88194ad363fffff
                    share_of_area: 0.408265
                    share_of_cell: 0.097457
                  - h3: 88194ad305fffff
                    share_of_area: 0.079011
                    share_of_cell: 0.018861
                credits:
                  used: 0
                  remaining: 977
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: No area of that type has that code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                request_id: 5fbb05d7-f776-4d66-b28d-9a2e998eb249
                error:
                  code: area_not_found
                  message: No lsoa E01999999 was found.
                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
    AreaCellsResponse:
      type: object
      required:
        - request_id
        - area
        - cells
        - credits
      properties:
        request_id:
          type: string
          format: uuid
        area:
          type: object
          required:
            - code
            - type
          properties:
            code:
              type: string
            type:
              $ref: '#/components/schemas/AreaType'
        cells:
          type: array
          items:
            type: object
            required:
              - h3
              - share_of_area
              - share_of_cell
            properties:
              h3:
                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.
        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.