> ## 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 local authority metrics

> Requested fee and occupancy values for an ONS district, county or unitary authority code. Districts resolve to their social-care parent authority. No radius or projection year is accepted.

## Reporting authority

A district normally resolves to its administrative parent county. A county or unitary code can be requested directly. `requested_area` retains the supplied area and `authority` identifies the resolved social-care authority. Every value's details contain the actual `reporting_authority`; occupancy can use a further published reporting-area resolution.

## Fees

`la_avg_fee_residential_week` and `la_avg_fee_nursing_week` each select their latest usable financial year. The two periods can differ. `source_metadata` preserves source-dependent fee-basis and funding evidence when available. Published tariffs, observed fees and Scottish national contract benchmarks are not automatically comparable. No funding basis should be inferred when detailed metadata is absent. Scottish national benchmarks, when present, retain their national source metadata rather than claiming to be council-specific observed averages.

## Occupancy

`la_occupancy_pct` combines general/dementia residential and nursing beds, excluding specialist/other beds. The residential and nursing keys return the separate categories. Coverage is England only. Each category uses its latest published month across the source dataset; a missing or suppressed authority row in that month returns null with the reporting period. The API does not carry forward an older observation or substitute England's value.

These are authority observations, not occupancy of a radius or an individual care home. No projection year or catchment size is accepted. An existing authority with no available data returns 200 with null values and reasons; an unknown code returns 404.

## Credits

One credit is reserved per unique requested key and consumed only for each usable numeric value returned. Catalogue and geography-mapping endpoints are free.


## OpenAPI

````yaml /api-reference/openapi.json get /v1/local-authority-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/local-authority-metrics:
    get:
      tags:
        - Local authorities
      summary: Get local authority metrics
      description: >-
        Requested fee and occupancy values for an ONS district, county or
        unitary authority code. Districts resolve to their social-care parent
        authority. No radius or projection year is accepted.
      operationId: getLocalAuthorityMetrics
      parameters:
        - name: code
          in: query
          required: true
          schema:
            type: string
            example: E07000110
          description: >-
            ONS district, county or unitary authority code. Case and surrounding
            whitespace are normalized; an unknown authority returns 404.
        - name: metrics
          in: query
          required: true
          schema:
            type: string
            example: >-
              la_avg_fee_residential_week,la_avg_fee_nursing_week,la_occupancy_pct
          description: >-
            Comma-separated keys supporting local_authority. At most 50 distinct
            keys; duplicates and empty entries are removed.
      responses:
        '200':
          description: Local-authority values, availability, periods and credit settlement.
          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/LocalAuthorityMetricsResponse'
              example:
                request_id: 2709fafa-f73b-40f6-a26e-69c1398e0b46
                local_authority:
                  requested_area:
                    code: E07000110
                    name: Maidstone
                    kind: lad
                  authority:
                    code: E10000016
                    name: Kent
                    kind: ctyua
                  values:
                    la_avg_fee_residential_week: 1063
                    la_avg_fee_nursing_week: 1240
                    la_occupancy_pct: 88.27
                    la_residential_occupancy_pct: 87.8
                    la_nursing_occupancy_pct: 89
                  metric_details:
                    la_avg_fee_residential_week:
                      status: available
                      reason: null
                      period: 2024-25
                      source: Local authority fee publications
                      source_metadata: null
                      reporting_authority:
                        code: E10000016
                        name: Kent
                        kind: ctyua
                    la_avg_fee_nursing_week:
                      status: available
                      reason: null
                      period: 2024-25
                      source: Local authority fee publications
                      source_metadata: null
                      reporting_authority:
                        code: E10000016
                        name: Kent
                        kind: ctyua
                    la_occupancy_pct:
                      status: available
                      reason: null
                      period: '2026-08-01'
                      source: Capacity Tracker
                      reporting_authority:
                        code: E10000016
                        name: Kent
                        kind: ctyua
                    la_residential_occupancy_pct:
                      status: available
                      reason: null
                      period: '2026-08-01'
                      source: Capacity Tracker
                      reporting_authority:
                        code: E10000016
                        name: Kent
                        kind: ctyua
                    la_nursing_occupancy_pct:
                      status: available
                      reason: null
                      period: '2026-08-01'
                      source: Capacity Tracker
                      reporting_authority:
                        code: E10000016
                        name: Kent
                        kind: ctyua
                credits:
                  used: 5
                  remaining: 979
        '400':
          $ref: '#/components/responses/InvalidRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/MetricForbidden'
        '404':
          description: No district, county or unitary authority exists for the code.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                request_id: 9143fe28-7459-4e01-b3a2-aede4b832929
                error:
                  code: area_not_found
                  message: No local authority was found for this code.
                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'
        '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:
    LocalAuthorityMetricsResponse:
      type: object
      required:
        - request_id
        - local_authority
        - credits
      properties:
        request_id:
          type: string
          format: uuid
        local_authority:
          $ref: '#/components/schemas/LocalAuthorityResult'
        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'
    LocalAuthorityResult:
      type: object
      required:
        - requested_area
        - authority
        - values
        - metric_details
      properties:
        requested_area:
          anyOf:
            - $ref: '#/components/schemas/Authority'
            - type: 'null'
          description: >-
            District containing the postcode, or the direct endpoint's requested
            district/county/unitary authority.
        authority:
          anyOf:
            - $ref: '#/components/schemas/Authority'
            - type: 'null'
          description: >-
            Resolved authority responsible for adult social care. A district
            normally resolves to its parent county; null if none was found for
            the postcode.
        values:
          type: object
          additionalProperties:
            type:
              - number
              - 'null'
          description: >-
            Only requested metrics for this geography. Null means unavailable;
            zero can be a usable value.
        metric_details:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/MetricDetail'
    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.
    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.
    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.
  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.