openapi: 3.2.0
info:
  title: OS Places Postcode API
  version: v1.0
  x-apievangelist-provenance:
    method: searched
    generated: '2026-07-26'
    assembly: Assembled by the API Evangelist enrichment pipeline from the per-operation OpenAPI 3.0.1 documents Ordnance Survey publishes inline on each docs.os.uk technical-specification page. Paths, parameters, schemas, security schemes and responses are verbatim from those published documents; only the per-page fragments were merged into one document per API.
    sources:
    - https://docs.os.uk/os-apis/accessing-os-apis/os-places-api/technical-specification/bbox.md
    - https://docs.os.uk/os-apis/accessing-os-apis/os-places-api/technical-specification/find.md
    - https://docs.os.uk/os-apis/accessing-os-apis/os-places-api/technical-specification/nearest.md
    - https://docs.os.uk/os-apis/accessing-os-apis/os-places-api/technical-specification/polygon.md
    - https://docs.os.uk/os-apis/accessing-os-apis/os-places-api/technical-specification/postcode.md
    - https://docs.os.uk/os-apis/accessing-os-apis/os-places-api/technical-specification/radius.md
    - https://docs.os.uk/os-apis/accessing-os-apis/os-places-api/technical-specification/uprn.md
  description: A search based on a property’s postcode
servers:
- url: https://api.os.uk/search/places/v1
security:
- api-key: []
  api-key-header: []
  oauth2: []
tags:
- name: Postcode
  description: A search based on a property’s postcode
paths:
  /postcode:
    get:
      tags:
      - Postcode
      summary: Returns matched addresses based on a property's postcode.
      operationId: getPostcode
      parameters:
      - name: postcode
        in: query
        description: The postcode search parameter.
        required: true
        schema:
          type: string
      - name: format
        in: query
        description: 'The format the response will be returned in. Default: JSON.'
        required: false
        schema:
          type: string
          default: JSON
          enum:
          - JSON
          - XML
      - name: maxresults
        in: query
        description: 'The maximum number of results to return. Default: 100.'
        required: false
        schema:
          type: integer
          default: '100'
          minimum: 1
          maximum: 100
      - name: offset
        in: query
        description: Offset the list of returned results by this amount.
        required: false
        schema:
          type: integer
          default: '0'
      - name: dataset
        in: query
        description: 'The dataset to return. Multiple values can be sent, separated by a comma. Default: DPA.'
        required: false
        schema:
          type: string
          default: DPA
          enum:
          - DPA
          - LPI
      - name: lr
        in: query
        description: 'Which language of addresses to return. Default: EN, CY.'
        required: false
        schema:
          type: string
          enum:
          - EN
          - CY
      - name: output_srs
        in: query
        description: 'The intended output spatial reference system. Default: EPSG:27700'
        required: false
        schema:
          type: string
          default: EPSG:27700
          enum:
          - BNG
          - EPSG:27700
          - WGS84
          - EPSG:4326
          - EPSG:3857
          - EPSG:4258
      - name: fq
        in: query
        description: Filter for classification code, logical status code, LPI logical status code and/or country code. Filtering for classification code will accept wildcard ( * ) searches. Multiple searches can be done by separating the codes with a space. Multiple filters can be used together by including the parameter multiple times
        required: false
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: Retrieves matched addresses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SearchResult'
            application/xml:
              schema:
                $ref: '#/components/schemas/SearchResult'
components:
  schemas:
    LPI:
      type: object
      properties:
        UPRN:
          type: string
        ADDRESS:
          type: string
        USRN:
          type: string
        LPI_KEY:
          type: string
        ORGANISATION:
          type: string
        SAO_START_NUMBER:
          type: string
        SAO_START_SUFFIX:
          type: string
        SAO_END_NUMBER:
          type: string
        SAO_END_SUFFIX:
          type: string
        SAO_TEXT:
          type: string
        PAO_START_NUMBER:
          type: string
        PAO_START_SUFFIX:
          type: string
        PAO_END_NUMBER:
          type: string
        PAO_END_SUFFIX:
          type: string
        PAO_TEXT:
          type: string
        STREET_DESCRIPTION:
          type: string
        LOCALITY_NAME:
          type: string
        TOWN_NAME:
          type: string
        ADMINISTRATIVE_AREA:
          type: string
        AREA_NAME:
          type: string
        POSTCODE_LOCATOR:
          type: string
        RPC:
          type: string
        X_COORDINATE:
          type: number
        Y_COORDINATE:
          type: number
        LNG:
          type: number
        LAT:
          type: number
        STATUS:
          type: string
        LOGICAL_STATUS_CODE:
          type: string
        CLASSIFICATION_CODE:
          type: string
        CLASSIFICATION_CODE_DESCRIPTION:
          type: string
        LOCAL_CUSTODIAN_CODE:
          type: integer
        LOCAL_CUSTODIAN_CODE_DESCRIPTION:
          type: string
        COUNTRY_CODE:
          type: string
        COUNTRY_CODE_DESCRIPTION:
          type: string
        POSTAL_ADDRESS_CODE:
          type: string
        POSTAL_ADDRESS_CODE_DESCRIPTION:
          type: string
        BLPU_STATE_CODE:
          type: string
        BLPU_STATE_CODE_DESCRIPTION:
          type: string
        TOPOGRAPHY_LAYER_TOID:
          type: string
        WARD_CODE:
          type: string
        PARISH_CODE:
          type: string
        PARENT_UPRN:
          type: string
        LAST_UPDATE_DATE:
          type: string
        ENTRY_DATE:
          type: string
        LEGAL_NAME:
          type: string
        BLPU_STATE_DATE:
          type: string
        STREET_STATE_CODE:
          type: string
        STREET_STATE_CODE_DESCRIPTION:
          type: string
        STREET_CLASSIFICATION_CODE:
          type: string
        STREET_CLASSIFICATION_CODE_DESCRIPTION:
          type: string
        LPI_LOGICAL_STATUS_CODE:
          type: string
        LPI_LOGICAL_STATUS_CODE_DESCRIPTION:
          type: string
        LANGUAGE:
          type: string
        MATCH:
          type: number
        MATCH_DESCRIPTION:
          type: string
    SearchResult:
      type: object
      properties:
        header:
          type: object
          properties:
            uri:
              type: string
            query:
              type: string
            offset:
              type: integer
            totalresults:
              type: integer
            format:
              type: string
            dataset:
              type: string
            lr:
              type: string
            maxresults:
              type: integer
            matchprecision:
              type: integer
            epoch:
              type: string
            lastupdate:
              type: string
            output_srs:
              type: string
          required:
          - uri
          - query
          - offset
          - totalresults
          - format
          - dataset
          - lr
          - maxresults
          - matchprecision
          - epoch
          - lastupdate
          - output_srs
        results:
          type: array
          items:
            type: object
            properties:
              DPA:
                $ref: '#/components/schemas/DPA'
              LPI:
                $ref: '#/components/schemas/LPI'
    DPA:
      type: object
      properties:
        UPRN:
          type: string
        UDPRN:
          type: string
        ADDRESS:
          type: string
        ORGANISATION_NAME:
          type: string
        DEPARTMENT_NAME:
          type: string
        SUB_BUILDING_NAME:
          type: string
        BUILDING_NAME:
          type: string
        BUILDING_NUMBER:
          type: string
        DEPENDENT_THOROUGHFARE_NAME:
          type: string
        THOROUGHFARE_NAME:
          type: string
        DOUBLE_DEPENDENT_LOCALITY:
          type: string
        DEPENDENT_LOCALITY:
          type: string
        POST_TOWN:
          type: string
        POSTCODE:
          type: string
        RPC:
          type: string
        X_COORDINATE:
          type: number
        Y_COORDINATE:
          type: number
        LNG:
          type: number
        LAT:
          type: number
        STATUS:
          type: string
        LOGICAL_STATUS_CODE:
          type: string
        CLASSIFICATION_CODE:
          type: string
        CLASSIFICATION_CODE_DESCRIPTION:
          type: string
        LOCAL_CUSTODIAN_CODE:
          type: integer
        LOCAL_CUSTODIAN_CODE_DESCRIPTION:
          type: string
        COUNTRY_CODE:
          type: string
        COUNTRY_CODE_DESCRIPTION:
          type: string
        POSTAL_ADDRESS_CODE:
          type: string
        POSTAL_ADDRESS_CODE_DESCRIPTION:
          type: string
        BLPU_STATE_CODE:
          type: string
        BLPU_STATE_CODE_DESCRIPTION:
          type: string
        TOPOGRAPHY_LAYER_TOID:
          type: string
        WARD_CODE:
          type: string
        PARISH_CODE:
          type: string
        PARENT_UPRN:
          type: string
        LAST_UPDATE_DATE:
          type: string
        ENTRY_DATE:
          type: string
        LEGAL_NAME:
          type: string
        BLPU_STATE_DATE:
          type: string
        LANGUAGE:
          type: string
        MATCH:
          type: number
        MATCH_DESCRIPTION:
          type: string
        DELIVERY_POINT_SUFFIX:
          type: string
  securitySchemes:
    api-key:
      type: apiKey
      name: key
      in: query