openapi: 3.2.0
info:
  title: Use Land and Property Data Datasets API
  description: RESTful JSON API for the HM Land Registry "Use land and property data" service. Lists the bulk datasets available in the service, returns dataset metadata and its resources, returns the history of available files for a dataset, and mints a signed S3 download URL valid for 10 seconds for a named file. Datasets reachable through it include UK companies that own property in England and Wales (CCOD), Overseas companies that own property in England and Wales (OCOD), the National Polygon Service (NPS) and its sample, Restrictive Covenants and Registered Leases. An API key is issued automatically on self-serve account creation and is sent in the Authorization header. Download endpoints additionally require that the caller has signed the licence for that specific dataset and, where the dataset is chargeable, paid for it.
  version: v1
  termsOfService: https://use-land-property-data.service.gov.uk/service-terms-of-use
  license:
    name: Open Government Licence v3.0
    url: https://www.nationalarchives.gov.uk/doc/open-government-licence/version/3/
  contact:
    name: Use land and property data support
    url: https://use-land-property-data.service.gov.uk/contact
  x-apievangelist-method: generated
  x-apievangelist-generated: '2026-07-26'
  x-evidence:
    documentation: https://use-land-property-data.service.gov.uk/api-documentation
    note: 'Generated faithfully from the provider''s published API technical documentation, which names each endpoint, its HTTP method and a full example JSON response body. HM Land Registry does not publish an OpenAPI description for this service. Every path below was additionally probed anonymously on 2026-07-26 and returned HTTP 403 with {"error":"Access denied: You need to provide your API Key to perform this operation","success":false}, confirming the route exists and is key-gated. No field, parameter or response was invented beyond what the published documentation and the live 403 envelope show.'
    probed: '2026-07-26'
servers:
- url: https://use-land-property-data.service.gov.uk/api/v1
  description: Production
security:
- apiKey: []
tags:
- name: Datasets
  description: Dataset discovery, metadata and download URL minting.
paths:
  /datasets:
    get:
      operationId: listDatasets
      tags:
      - Datasets
      summary: List available datasets
      description: Returns a JSON list of the dataset names and titles that are available in the service.
      responses:
        '200':
          description: The list of available datasets.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetListResponse'
              example:
                result:
                - name: ccod
                  title: UK companies that own property in England and Wales
                - name: ocod
                  title: Overseas companies that own property in England and Wales
                - name: nps
                  title: National Polygon Service
                - name: nps_sample
                  title: National Polygon Service Sample
                success: true
        '403':
          $ref: '#/components/responses/AccessDenied'
  /datasets/{dataset_name}:
    get:
      operationId: getDataset
      tags:
      - Datasets
      summary: Get dataset metadata and resources
      description: Returns the metadata of a dataset and its resources.
      parameters:
      - $ref: '#/components/parameters/DatasetName'
      responses:
        '200':
          description: Dataset metadata.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetResponse'
              example:
                result:
                  description: Download data about UK companies that own land or property in England and Wales.
                  external: false
                  fee: Free of charge
                  file_count: 1
                  file_size: 1.23 MB
                  format: CSV
                  last_updated: 7 August 2019
                  licence_id: ccod
                  name: ccod
                  private: false
                  state: active
                  title: UK companies that own property in England and Wales
                  type: free
                  update_frequency: Monthly
                  version: v1
                success: true
        '403':
          $ref: '#/components/responses/AccessDenied'
  /datasets/{dataset_name}/{file_name}:
    get:
      operationId: getDatasetFileDownloadUrl
      tags:
      - Datasets
      summary: Get a signed download URL for a dataset file
      description: Returns a download URL valid for 10 seconds for a specific file in a dataset. This endpoint will only work if you have agreed to the dataset licence and have the correct access, which is arranged on the Use land and property data service.
      parameters:
      - $ref: '#/components/parameters/DatasetName'
      - name: file_name
        in: path
        required: true
        description: The file name of the resource within the dataset.
        schema:
          type: string
        example: CCOD_COU_2019_09.zip
      responses:
        '200':
          description: A short-lived signed download URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DownloadResponse'
        '403':
          $ref: '#/components/responses/AccessDenied'
  /datasets/history/{dataset_name}:
    get:
      operationId: getDatasetHistory
      tags:
      - Datasets
      summary: List historical resources for a dataset
      description: Returns a list of available historical resources for a dataset.
      parameters:
      - $ref: '#/components/parameters/DatasetName'
      responses:
        '200':
          description: The dataset history.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DatasetHistoryResponse'
              example:
                success: true
                dataset: ccod
                dataset_history:
                - file_size: 1.3 MB
                  filename: CCOD_COU_2019_08.zip
                  last_updated: August 2019
                  unsorted_date: 07-08-2019
        '403':
          $ref: '#/components/responses/AccessDenied'
components:
  schemas:
    Dataset:
      type: object
      properties:
        description:
          type: string
        external:
          type: boolean
        fee:
          type: string
        file_count:
          type: integer
        file_size:
          type: string
        format:
          type: string
        last_updated:
          type: string
        licence_id:
          type: string
        name:
          type: string
        private:
          type: boolean
        public_resources:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
        resources:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
        state:
          type: string
        tech_spec_url:
          type: string
          format: uri
        title:
          type: string
        type:
          type: string
        update_frequency:
          type: string
        version:
          type: string
    DatasetHistoryResponse:
      type: object
      properties:
        success:
          type: boolean
        dataset:
          type: string
        dataset_history:
          type: array
          items:
            $ref: '#/components/schemas/HistoryEntry'
    Download:
      type: object
      properties:
        download_url:
          type: string
          format: uri
          description: Pre-signed S3 URL.
        resource:
          type: string
        valid_for_seconds:
          type: integer
          example: 10
    Error:
      type: object
      properties:
        error:
          type: string
          description: Human readable error message.
        success:
          type: boolean
          description: Always false on an error response.
    DownloadResponse:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/Download'
        success:
          type: boolean
    HistoryEntry:
      type: object
      properties:
        file_size:
          type: string
        filename:
          type: string
        last_updated:
          type: string
        unsorted_date:
          type: string
    Resource:
      type: object
      properties:
        file_count:
          type: integer
        file_name:
          type: string
        file_size:
          type: string
        format:
          type: string
        name:
          type: string
        row_count:
          type: integer
    DatasetSummary:
      type: object
      properties:
        name:
          type: string
        title:
          type: string
    DatasetResponse:
      type: object
      properties:
        result:
          $ref: '#/components/schemas/Dataset'
        success:
          type: boolean
    DatasetListResponse:
      type: object
      properties:
        result:
          type: array
          items:
            $ref: '#/components/schemas/DatasetSummary'
        success:
          type: boolean
  responses:
    AccessDenied:
      description: Access denied. Returned when no API key is supplied, or when the caller has not signed the licence for the requested dataset.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: 'Access denied: You need to provide your API Key to perform this operation'
            success: false
  parameters:
    DatasetName:
      name: dataset_name
      in: path
      required: true
      description: The dataset name, for example ccod, ocod, nps or nps_sample. CCOD and OCOD remain the machine names for the renamed UK companies and Overseas companies datasets.
      schema:
        type: string
      example: ccod
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization
      description: 'The API key issued automatically on account creation, sent as the Authorization header on every request. Passing Accept: application/json is also advised.'