openapi: 3.0.3
servers:
  - description: API Server
    url: https://api.ideal-postcodes.co.uk/v1
    variables: {}
info:
  contact:
    email: support@ideal-postcodes.co.uk
    name: Support
    url: https://ideal-postcodes.co.uk/support
  description: |
    # Getting Started

    ## Overview

    ### Access

    All API methods are either a `GET`, `POST` or `OPTIONS` request.

    The API communicates over both HTTPS and plain HTTP using IPv4 and IPv6.

    We recommend using HTTPS only although HTTP is available.

    We use appropriate HTTP status codes where possible to indicate the request status.

    ### Rate Limiting

    Each IP address is rate limited at 30 requests per second. Tripping the rate limit will result in a 503 response.

    The autocomplete API also has an additional rate limit.

    If you expect to breach the limit please contact us and we can move you to an endpoint with a higher limit.

    ### JSONP

    [JSONP](http://en.wikipedia.org/wiki/JSONP) requests are supported. Include a `callback=` in your request as a query parameter. Your results return wrapped in a function designated by your request.

    ## Authentication

    Most requests require an **API key** for authentication. Authenticate by passing an `api_key` as part of the query string. For example:

    ```
    api.ideal-postcodes.co.uk/v1/autocomplete/addresses?api_key=iddqd&q=parkside
    ```

    Alternatively, authentication can be transmitted via the `Authorization` header using the following scheme:

    ```
    Authorization: api_key="iddqd" [other_key="foo"]
    ```

    ## Versioning

    This API is versioned with a simple prefix in the URL. The current version is `/v1/`. We will maintain backwards-compatibility by releasing breaking changes under a new version.

    Please note that the following changes are backwards-compatible:

    - Adding new properties to existing API responses
    - Adding new API endpoints
    - Adding new optional request parameters to existing API endpoints
    - Changing the order of properties in existing API responses
    - Changing the autocomplete address suggestion format

    ## Error Handling

    A successful lookup is accompanied with a HTTP status code of 200 and a response code of 2000 (found in the body).

    An error has occurred if the HTTP status code is not 200. Errors can range from a benign 404 (resource not found) to more urgent errors (your API Key ran out of credit, failed authentication, etc).

    ## Testing

    Each new account comes with a free test balance. Contact us if you need more for testing and integration.

    ### Community Key

    Our documentation and demos make heavy use of our community key `iddqd`. This allows for convenient access for trialing the API.

    Many restrictions on this key are relaxed to allow developers make test requests. This key has a limit of 15 lookups per IP address per day as well as a daily usage cap. If you hit any limit restrictions, you can continue testing the API by creating a key of your own and using our free test methods.

    Please be kind with the community key. We're trusting everyone to use it responsibly so that other developers may trial the API. Thank you!

    ## Metadata

    Requests that affect your balance may be annotated with arbitrary metadata. This data is stored along with your lookup history and can be queried at a later date via the API or the dashboard. We call the ability to label your requests [tagging](https://docs.ideal-postcodes.co.uk/docs/guides/tags).

    # Response Codes

    The API returns two indicators to help you to determine the status of each HTTP request.

    The first is the **HTTP Status**, which is found in the status-line of all HTTP requests. The API will return status codes that adhere to HTTP /1.1 Specifications wherever possible.

    `2XX` status codes indicates success while `4XX` and `5XX` indicate client and server errors respectively.

    The second is the **API response code**, which can be found in the `code` property of the response body. This code will provide a more specific reason if a failure has occurred and can point you in the right direction when debugging.

    Please use the glossary of code numbers and HTTP status codes below when debugging your requests.

    ## 200 Request Success

    | HTTP Code | API Code | Description                                  |
    | --------- | -------- | -------------------------------------------- |
    | 200       | 2000     | Success. Request was completed successfully. |

    ## 400 Bad Request

    The request could not be understood due to some input error.

    | HTTP Code | API Code | Description                                                                                                                           |
    | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
    | 400       | 4000     | Invalid syntax submitted. Some part of your request was malformed or did not match our specifications.                                |
    | 400       | 4001     | Validation failed on your submitted data. Some of the data you provided did not meet our validation requirements, e.g. string length. |
    | 400       | 4005     | Invalid start date. Please ensure start dates are provided as a UTC Timestamp in milliseconds.                                        |
    | 400       | 4006     | Invalid end date. Please ensure end dates are provided as a UTC Timestamp in milliseconds.                                            |
    | 400       | 4007     | Invalid date range. Check if your start and end dates are in the right order.                                                         |
    | 400       | 4008     | Invalid date range. Check that your date range is 90 days or less.                                                                    |
    | 400       | 4009     | Too many tags. Please specify no more than 3 tags to query.                                                                           |

    ## 401 Unauthorised

    Authorization credentials are not valid.

    | HTTP Code | API Code | Description                                                                                                                                                        |
    | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | 401       | 4010     | Invalid Key. The `api_key` you provided is not valid.                                                                                                              |
    | 401       | 4011     | Requesting URL not on whitelist. The cross domain request is not coming from a whitelisted URL. You can update or disable your allowed URLs via your Key settings. |
    | 401       | 4012     | Failed user authentication. Invalid `user_token` presented.                                                                                                        |
    | 401       | 4013     | Licensee Key is required. Sublicensed keys require you need to present licensee credentials via the `licensee` parameter.                                          |

    ## 402 Request Failed

    Your request is well-formed but are not able to complete your request for another reason.

    | HTTP Code | API Code | Description                                                                                                                                                                                                                                                        |
    | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | 402       | 4020     | Key balance depleted. You're out of lookups on your API Key.                                                                                                                                                                                                       |
    | 402       | 4021     | Limit reached. One of your lookup limits has been breached for today. This could either be your total daily limit on your key or the individual IP limit. You can either wait for for the limit to reset (after a day) or manually disable or increase your limit. |

    ## 404 Resource Not Found

    The resource you requested does not exist.

    | HTTP Code | API Code | Description                                                                                   |
    | --------- | -------- | --------------------------------------------------------------------------------------------- |
    | 404       | 4040     | Postcode not found. The postcode you have submitted does not exist.                           |
    | 404       | 4041     | User not found. Your user could not be identified given the credentials you presented.        |
    | 404       | 4042     | Key not found. Your key could not be identified given the credentials you presented.          |
    | 404       | 4044     | No UDPRN found. No address is associated with the UDPRN queried                               |
    | 404       | 4045     | No licensee found. Your licensee could not be identified given the credentials you presented. |
    | 404       | 4046     | No UMPRN found. No Multiple Residence premise is associated with the UMPRN queried.           |

    ## 500 Server Error

    A error occurred on our server.

    | HTTP Code | API Code | Description                                                                                                                                                        |
    | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
    | 500       | 5000     | An error occurred on our end. These errors are logged and queued so we can understand what went wrong. However, if you need speedy resolution please email support |
    | 500       | 5001     | Akin to 5000.                                                                                                                                                      |
    | 500       | 5002     | The server took too long to process on our end, so we aborted the request. You may retry the request.                                                              |
  license:
    name: AGPLv3
    url: https://opensource.org/licenses/AGPL-3.0
  termsOfService: https://terms.ideal-postcodes.co.uk
  title: API Reference - Ideal Postcodes
  version: 3.7.0
  x-apisguru-categories:
    - location
  x-logo:
    url: https://ideal-postcodes.co.uk/apple-icon-57x57.png
  x-origin:
    - format: openapi
      url: https://openapi.ideal-postcodes.dev/openapi.json
      version: "3.0"
  x-providerName: ideal-postcodes.co.uk
externalDocs:
  description: More on our APIs, libraries with guides and examples
  url: https://docs.ideal-postcodes.co.uk
tags:
  - description: Global address autocomplete, for search-as-you-type
    name: Address Search
  - description: Global places search to identify geographical names and places
    name: Place Search
  - description: UK Address and Postcode Search
    name: UK
  - description: Monitor and manage API Keys
    name: Keys
  - description: |
      The Licensee resource represents an alternate legal End User of our data who may not be same entity as the owners of the account.

      The concept of Licensees underpins our sublicensing platform, which allows users to license multiple external organisations or individuals to access data under the same account.

      Sublicensing is ideal for platform vendors, who provide services to multiple clients who in turn each have their own users.
    name: Licensees
  - description: |
      The Config resource allows users to assign serialised configuration data to API Keys. The payloads assigned to a Config object can later be retrieved to dynamically configure your integration.

      Useful if you need to configure your integration remotely rather than editing code in situ.
    name: Configs
  - description: |
      Address Suggestions are simple, human readable representations of an address. This format is sufficient tfor a user to determine an address match in an address autocomplete interface. A second request must be made to the API to gather fully validated address.

      See our Address Search APIs for more information on address autocompletion.

      <SchemaDefinition schemaRef="#/components/schemas/AddressSuggestion" />
    name: suggestion
    x-displayName: Address Suggestion
  - description: |
      Standard US Address format as reported by USPS.

      <SchemaDefinition schemaRef="#/components/schemas/UspsAddress" />
    name: usps_address
    x-displayName: US Address
  - description: |
      Standard UK Address format as reported by Royal Mail's Postcode Address File (PAF). PAF is the most complete and up-to-date address database in the UK.

      <SchemaDefinition schemaRef="#/components/schemas/PafAddress" />
    name: uk_address
    x-displayName: UK Address
  - description: |
      Standard Republic of Ireland Address format as reported by the Eircode ECAF file.

      <SchemaDefinition schemaRef="#/components/schemas/EcafAddress" />
    name: ecaf_address
    x-displayName: IE Address
  - description: |
      ECAF file including additional data for each address.

      <SchemaDefinition schemaRef="#/components/schemas/EcadAddress" />
    name: ecad_address
    x-displayName: IE Address (ECAD)
  - description: |
      AddressBase Core Address. An alternative to UK PAF dataset from Ordnance Survey.

      Please contact us to have this enabled on your account.

      <SchemaDefinition schemaRef="#/components/schemas/AddressBaseCore" />
    name: ab_address
    x-displayName: AddressBase Core
  - description: |
      GeoNames place record

      <SchemaDefinition schemaRef="#/components/schemas/GeonamesPlace" />
    name: geonames_place
    x-displayName: GeoNames Place
paths:
  /addresses:
    get:
      description: |
        Extract a list of complete addresses that match the query ordered by relevance score. This query accepts an optional limit and page query (defaults to 10 and 0 respectively).

        If a valid postcode is passed as the query string, the entire address list for that postcode is passed as a result. Note, in these cases, limit and page parameters are ignored.

        This API is designed as a multi-purpose tool for generating address lists, cleansing and wholesale data extraction according to specific parameters.

        For address autocomplete, see our address finder API - which is designed for speed and address completion.

        ## Reverse Geocoding

        Return a list of addresses around a point using the lon= and lat= querystring arguments. Addresses will be sorted in order of distance to the point. The search radius is 100m.

        ## Filters

        You can strictly narrow your result by adding filters to your query string which correspond with an address attribute.

        For instance, you can restrict to postcode `SW1A 2AA` by appending `postcode=sw1a2aa`.

        If a filter term is invalid, e.g. `postcode=SW1A2AAA`, then an empty result set is returned and no lookup is incurred.

        You can also scope using multiple terms for the same filter with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: `postcode_outward=e1,e2,e3`. Multiple terms are `OR`'ed, i.e. the matching result sets are combined.

        All filters can accept multiple terms unless stated otherwise below.

        Multiple filters can also be combined. E.g. Restrict results to small user organisations in the N postcode area: `su_organisation_indicator=Y&postcode_area=n`. Multiple filters are `AND`'ed, i.e. each additional filter narrows the result set.

        A combined maximum of 5 terms are allowed across all filters.

        ## Biases

        You can boost certain addresses results that correspond with a certain address attribute. All bias searches are prefixed with `bias_`.

        Biased searches, unlike filtered searches, also allow unmatched addresses to appear . These will rank lower.

        For instance, you can boost addresses with postcode areas `SW` and `SE` by appending `bias_postcode_area=SW,SE`.

        If a bias term is invalid, e.g. `bias_postcode=SW1A2AAA` no bias effect is applied.

        You may scope using multiple terms for the same bias with a comma separated list of terms. E.g. Restrict results to `E1`, `E2` and `E3` outward codes: `bias_postcode_outward=e1,e2,e3`.

        All biases can accept multiple terms unless stated otherwise below.

        A combined maximum of 5 terms are allowed across all biases.

        ## Search by Postcode and Building Name or Number

        Search by postcode and building attribute with the postcode filter and query argument. E.g. For "SW1A 2AA Prime Minister" `/v1/addresses?postcode=sw1a2aa&q=prime minister`.

        The advantage of using filters is a postcode mismatch does not result in a lookup as no results are returned.

        #### Search By UPRN

        Search by UPRN using the `uprn` filter and excluding the query argument. E.g. `/v1/addresses?uprn=100`.

        ## Testing

        - **ID1 1QD** Returns a successful query response `2000`
        - **ID1 KFA** Returns an empty query response `2000`
        - **ID1 CLIP** Returns "no lookups remaining" error `4020`
        - **ID1 CHOP** Returns "daily (or individual) lookup limit breached" error `4021`

        Test request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.
      operationId: Addresses
      parameters:
        - explode: false
          in: query
          name: api_key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: form
        - description: Specifies the address you wish to query. Query can be shortened to `q=`
          explode: false
          in: query
          name: query
          schema:
            type: string
          style: form
        - explode: false
          in: query
          name: limit
          schema:
            $ref: "#/components/schemas/LimitParam"
          style: form
        - explode: false
          in: query
          name: page
          schema:
            $ref: "#/components/schemas/PageParam"
          style: form
        - explode: false
          in: query
          name: filter
          schema:
            $ref: "#/components/schemas/FilterParam"
          style: form
        - explode: false
          in: query
          name: lon
          schema:
            $ref: "#/components/schemas/AddressLongitudeParam"
          style: form
        - explode: false
          in: query
          name: lat
          schema:
            $ref: "#/components/schemas/AddressLatitudeParam"
          style: form
        - explode: false
          in: query
          name: postcode_outward
          schema:
            $ref: "#/components/schemas/PostcodeOutwardParam"
          style: form
        - explode: false
          in: query
          name: postcode
          schema:
            $ref: "#/components/schemas/PostcodeParam"
          style: form
        - explode: false
          in: query
          name: postcode_area
          schema:
            $ref: "#/components/schemas/PostcodeAreaParam"
          style: form
        - explode: false
          in: query
          name: postcode_sector
          schema:
            $ref: "#/components/schemas/PostcodeSectorParam"
          style: form
        - explode: false
          in: query
          name: post_town
          schema:
            $ref: "#/components/schemas/PostTownParam"
          style: form
        - explode: false
          in: query
          name: uprn
          schema:
            $ref: "#/components/schemas/UPRNParam"
          style: form
        - explode: false
          in: query
          name: country
          schema:
            $ref: "#/components/schemas/CountryParam"
          style: form
        - explode: false
          in: query
          name: postcode_type
          schema:
            $ref: "#/components/schemas/PostcodeTypeParam"
          style: form
        - explode: false
          in: query
          name: su_organisation_indicator
          schema:
            $ref: "#/components/schemas/SmallUserParam"
          style: form
        - explode: false
          in: query
          name: box
          schema:
            $ref: "#/components/schemas/BoxParam"
          style: form
        - explode: false
          in: query
          name: bias_postcode_outward
          schema:
            $ref: "#/components/schemas/BiasPostcodeOutwardParam"
          style: form
        - explode: false
          in: query
          name: bias_postcode
          schema:
            $ref: "#/components/schemas/BiasPostcodeParam"
          style: form
        - explode: false
          in: query
          name: bias_postcode_area
          schema:
            $ref: "#/components/schemas/BiasPostcodeAreaParam"
          style: form
        - explode: false
          in: query
          name: bias_postcode_sector
          schema:
            $ref: "#/components/schemas/BiasPostcodeSectorParam"
          style: form
        - explode: false
          in: query
          name: bias_post_town
          schema:
            $ref: "#/components/schemas/BiasPosttownParam"
          style: form
        - explode: false
          in: query
          name: bias_thoroughfare
          schema:
            $ref: "#/components/schemas/BiasThoroughfareParam"
          style: form
        - explode: false
          in: query
          name: bias_country
          schema:
            $ref: "#/components/schemas/BiasCountryParam"
          style: form
        - explode: false
          in: query
          name: bias_lonlat
          schema:
            $ref: "#/components/schemas/BiasLonLatParam"
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AddressResponse"
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostcodeNotFoundResponse"
          description: Postcode Not Found
      summary: Extract Addresses
      tags:
        - UK
      x-codeSamples:
        - label: URL
          lang: http
          source: |
            https://api.ideal-postcodes.co.uk/v1/addresses?api_key=iddqd&query=10%20downing%20street%20london
        - label: CLI
          lang: cURL
          source: |
            curl -k -G 'https://api.ideal-postcodes.co.uk/v1/addresses' \
              -d 'api_key=iddqd' \
              --data-urlencode 'query=10 downing street london'
  /autocomplete/addresses:
    get:
      description: |
        The address autocomplete API returns a list of address suggestions that match the query ordered by relevance.

        This API can be used to power realtime address finders, also known as address autofill or address autocomplete.

        Consider using our Address Autocomplete JavaScript libraries to add address lookup to a form in moments.

        ## Implementing Address Autocomplete

        Rapid address autocompletion using our Address Autocomplete API is a 2 step process.

        1. Retrieve partial address suggestions via `/autocomplete/addresses`
        2. Retrieve the entire address with the ID provided in the suggestion

        Step 2 will decrement your lookup balance.

        Please note, this API is not intended to be a free standalone resource.

        ## Filters

        You can strictly narrow your result by adding filters to your querystring. For instance, you can restrict to postcode `SW1A 2AA` by appending `postcode=sw1a2aa`.

        If a filter term is invalid, e.g. `postcode=SW1A2AAA`, then an empty result set is returned and no lookup is incurred.

        You can also scope using multiple terms for the same filter with a comma separated list of terms. E.g. Restrict results to E1, E2 and E3 outward codes: `postcode_outward=e1,e2,e3`. Multiple terms are `OR`'ed, i.e. the matching result sets are combined.

        All filters can accept multiple terms unless stated otherwise below.

        Filters can also be combined. E.g. Restrict results to small user organisations in the N postcode area: `su_organisation_indicator=Y&postcode_area=n`. Multiple filters are `AND`'ed, i.e. each additional filter narrows the result set.

        A maximum of **10** terms are allowed across all filters.

        ## Biases

        You can boost certain addresses results that match specific address criteria. All bias searches are prefixed with `bias_`.

        Biasing (unlike filtering) also allow unmatched addresses to appear with lower precedence.

        For instance, can boost addresses with postcode areas `SW` and `SE` by appending `bias_postcode_area=SW,SE`.

        No bias effect applies to bias terms that are invalid. e.g. `bias_postcode=SW1A2AAA`

        You may scope using multiple terms for the same bias with a comma separated list of terms. E.g. Restrict results to `E1`, `E2` and `E3` outward codes: <code>bias_postcode_outward=e1,e2,e3</code>.

        All biases can accept multiple terms unless stated otherwise below.

        A combined maximum of **5** terms are allowed across all biases.

        ## Suggestion Format

        The suggestion format is prone to change over time. Attempts to parse the suggestion may result in your integration breaking. Instead use the suggestion as-is.

        ## Rate Limiting

        You can make up to 3000 requests to the autocomplete API within a 5 minute span. The HTTP Header contains information on your current rate limit.

        | Header                  | Description                                                                            |
        | ----------------------- | -------------------------------------------------------------------------------------- |
        | `X-RateLimit-Limit`     | The maximum number of requests that can be made in 5 minutes                           |
        | `X-RateLimit-Remaining` | The remaining requests within the current rate limit window                            |
        | `X-RateLimit-Reset`     | The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds |

        ## Pricing

        This API currently does not affect your balance. However, resolving a suggestion into a full address requires a paid request.

        Please note, this API is not intended as a standalone free resource. Integrations that consistently make autocomplete requests without a paid request to resolve an address may be disrupted via tightened rate limits. Continued misuse will result in account suspension.
      operationId: AddressAutocomplete
      parameters:
        - explode: false
          in: query
          name: api_key
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: form
        - description: Specifies the address you wish to query. Query can be shortened to `q=`
          explode: false
          in: query
          name: query
          schema:
            type: string
          style: form
        - explode: false
          in: query
          name: context
          schema:
            $ref: "#/components/schemas/Context"
          style: form
        - description: |
            Limits number of address suggestions unless a postcode is detected. In this instance entire list of addreses for that postcode is returned.
          explode: false
          in: query
          name: limit
          schema:
            $ref: "#/components/schemas/LimitParam"
          style: form
        - explode: false
          in: query
          name: postcode_outward
          schema:
            $ref: "#/components/schemas/PostcodeOutwardParam"
          style: form
        - explode: false
          in: query
          name: postcode
          schema:
            $ref: "#/components/schemas/PostcodeParam"
          style: form
        - explode: false
          in: query
          name: postcode_area
          schema:
            $ref: "#/components/schemas/PostcodeAreaParam"
          style: form
        - explode: false
          in: query
          name: postcode_sector
          schema:
            $ref: "#/components/schemas/PostcodeSectorParam"
          style: form
        - explode: false
          in: query
          name: post_town
          schema:
            $ref: "#/components/schemas/PostTownParam"
          style: form
        - explode: false
          in: query
          name: uprn
          schema:
            $ref: "#/components/schemas/UPRNParam"
          style: form
        - explode: false
          in: query
          name: country
          schema:
            $ref: "#/components/schemas/CountryParam"
          style: form
        - explode: false
          in: query
          name: postcode_type
          schema:
            $ref: "#/components/schemas/PostcodeTypeParam"
          style: form
        - explode: false
          in: query
          name: su_organisation_indicator
          schema:
            $ref: "#/components/schemas/SmallUserParam"
          style: form
        - explode: false
          in: query
          name: box
          schema:
            $ref: "#/components/schemas/BoxParam"
          style: form
        - explode: false
          in: query
          name: bias_postcode_outward
          schema:
            $ref: "#/components/schemas/BiasPostcodeOutwardParam"
          style: form
        - explode: false
          in: query
          name: bias_postcode
          schema:
            $ref: "#/components/schemas/BiasPostcodeParam"
          style: form
        - explode: false
          in: query
          name: bias_postcode_area
          schema:
            $ref: "#/components/schemas/BiasPostcodeAreaParam"
          style: form
        - explode: false
          in: query
          name: bias_postcode_sector
          schema:
            $ref: "#/components/schemas/BiasPostcodeSectorParam"
          style: form
        - explode: false
          in: query
          name: bias_post_town
          schema:
            $ref: "#/components/schemas/BiasPosttownParam"
          style: form
        - explode: false
          in: query
          name: bias_thoroughfare
          schema:
            $ref: "#/components/schemas/BiasThoroughfareParam"
          style: form
        - explode: false
          in: query
          name: bias_country
          schema:
            $ref: "#/components/schemas/BiasCountryParam"
          style: form
        - explode: false
          in: query
          name: bias_lonlat
          schema:
            $ref: "#/components/schemas/BiasLonLatParam"
          style: form
        - explode: false
          in: query
          name: bias_ip
          schema:
            $ref: "#/components/schemas/BiasIpParam"
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AutocompleteResponse"
          description: Success
          headers:
            X-RateLimit-Limit:
              description: The maximum number of requests that can be made in 5 minutes
              schema:
                format: int32
                type: number
            X-RateLimit-Remaining:
              description: The remaining requests within the current rate limit window
              schema:
                format: int32
                type: number
            X-RateLimit-Reset:
              description: |
                The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds.
              schema:
                format: int32
                type: number
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
      summary: Find Address
      tags:
        - Address Search
      x-codeSamples:
        - label: URL
          lang: http
          source: |
            https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses?api_key=iddqd&q=10%20downing
        - label: CLI
          lang: cURL
          source: |
            curl -k -G 'https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses' \
              -d 'api_key=iddqd' \
              --data-urlencode 'query=10 downing'
  "/autocomplete/addresses/{address}/gbr":
    get:
      description: |
        Resolves an address autocompletion by its address ID.

        Resolved addresses (including global addresses) are returned in a UK format (up to 3 address lines) using UK nomenclature (like postcode and county).
      operationId: Resolve
      parameters:
        - description: ID of address suggestion
          explode: false
          in: path
          name: address
          required: true
          schema:
            type: string
          style: simple
        - explode: false
          in: query
          name: api_key
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/GbrResolveAddressResponse"
          description: Success
          headers: {}
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Resource not found
      summary: Resolve Address (GBR)
      tags:
        - Address Search
      x-codeSamples:
        - label: URL
          lang: http
          source: |
            https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses/paf_23747771/gbr?api_key=iddqd
        - label: CLI
          lang: cURL
          source: |
            curl -k -G https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses/paf_23747771/gbr?api_key=iddqd \
              -d "api_key=iddqd"
  "/autocomplete/addresses/{address}/usa":
    get:
      description: |
        Resolves an address autocompletion by its address ID.

        Resolved addresses (including global addresses) are returned in a US format (up to 2 address lines) using US nomenclature (like zipcode, state and city).
      operationId: ResolveUsa
      parameters:
        - description: ID of address suggestion
          explode: false
          in: path
          name: address
          required: true
          schema:
            type: string
          style: simple
        - explode: false
          in: query
          name: api_key
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UsaResolveAddressResponse"
          description: Success
          headers: {}
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Resource not found
      summary: Resolve Address (USA)
      tags:
        - Address Search
      x-codeSamples:
        - label: URL
          lang: http
          source: |
            https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses/usps_Z222446599|1||1101/usa?api_key=iddqd
        - label: CLI
          lang: cURL
          source: |
            curl -k -G https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses/usps_Z222446599|1||1101/usa?api_key=iddqd \
              -d "api_key=iddqd"
  /cleanse/addresses:
    post:
      description: |
        The address cleanse API attempts to return the closest matching address for any given address inputs. We also return a number of Match Level indicators that describe the degree to which the suggested address matches the input address. The more impaired the input address, the harder it is to cleanse.

        ## Confidence Score

        The confidence score is a number ranging between 0 and 1. Where 1 implies a full match and 0 implies no major elements completely match. Each incorrect, missing or misspelled element will subtract from the overall confidence score.

        ### Deciding on an Acceptable Confidence Score Threshold

        Different address cleanse projects can have radically different inputs. However, within each project, the inputs tend to repeat the same errors. For instance, some input datasets may be exclusively inputted manually and be prone to typos. Others may have a persistently missing datapoint such as organistation name or postcode. For this reason, it is important to understand that there is no absolute Confidence Score threshold. Instead, the acceptable confidence score must be determined on a project by project basis based on systematic errors present in the data and business goals.

        When determining an acceptable Confidence Score threshold you should load a subset of the dataset into a spreadsheet application like Excel and sort on the score. Scrolling from top-to-bottom you will be able to observe matches from best to worst. As you start to hit the lower quality searches, you will be able to roughly determine:
        - Which confidence scores indicate ambigious matches (i.e. up to building level only)
        - Which confidence scores indicate a poor or no match (i.e. the nearest matching address is too far from the input address)

        Depending on your business goals, you can also use the Match Levels to determine an acceptable match. For instance, do you need to match up to the throroughfare or building name only? Are accurate organisation names an important feature?
      operationId: AddressCleanse
      parameters:
        - explode: false
          in: query
          name: api_key
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: form
      requestBody:
        content:
          application/json:
            schema:
              properties:
                query:
                  description: |
                    Freeform address input to cleanse
                  example: 10 Downing Street, London, SW2A 2BN
                  type: string
              required:
                - query
              type: object
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CleanseResponse"
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
          description: Unauthorized
        "429":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RateLimitedResponse"
          description: Rate Limited
      summary: Cleanse
      tags:
        - UK
      x-codeSamples:
        - label: CLI
          lang: cURL
          source: |
            curl -k -G 'https://api.ideal-postcodes.co.uk/v1/cleanse/addresses' \
              -H 'Authorization: api_key="ak_test"'
              -H 'Content-Type: application/json'
              -d '{"query": "10 downing street sw1a"}'
  /emails:
    get:
      description: |
        Query for and validate email addresses.
      operationId: EmailValidation
      parameters:
        - explode: false
          in: query
          name: api_key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: form
        - description: Specifies the email address to validate
          explode: false
          in: query
          name: query
          required: true
          schema:
            type: string
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/EmailResponse"
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
      summary: Email Validation
      tags:
        - Emails
      x-codeSamples:
        - label: URL
          lang: http
          source: |
            https://api.ideal-postcodes.co.uk/v1/emails?api_key=ak_test&query=foo@domain.com
        - label: CLI
          lang: cURL
          source: |
            curl -k -G 'https://api.ideal-postcodes.co.uk/v1/emails' \
              -d 'api_key=iddqd' \
              --data-urlencode 'query=foo@domain.com'
  "/keys/{key}":
    get:
      description: |+
        Returns public information on key. Currently only returns whether the key is currently useable via the `available` property. Use this to discover if the key is useable before making further requests.

        You may pass both API Keys (beginning `ak_`) and Sub-licensed Keys (beginning `sl_`).
        ## Testing

        To test your implementation of our API, you may use the following test keys.

        - **iddqd** Availability will return as `true`
        - **idkfa** Availability will return as `false`

      operationId: KeyAvailability
      parameters:
        - explode: false
          in: path
          name: key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyResponse"
          description: Success
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Invalid Key
      summary: Availability
      tags:
        - Keys
  "/keys/{key}/configs":
    get:
      description: Lists configurations associated with a key
      operationId: ListConfigs
      parameters:
        - explode: false
          in: path
          name: key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: simple
        - explode: false
          in: query
          name: user_token
          schema:
            $ref: "#/components/schemas/UserTokenParam"
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfigsResponse"
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
          description: Unauthorized Request
      summary: List
      tags:
        - Configs
    post:
      description: Create a config
      operationId: CreateConfig
      parameters:
        - explode: false
          in: path
          name: key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: simple
        - explode: false
          in: query
          name: user_token
          schema:
            $ref: "#/components/schemas/UserTokenParam"
          style: form
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfigNewParam"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfigResponse"
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
          description: Unauthorized Request
      summary: Create
      tags:
        - Configs
  "/keys/{key}/configs/{config}":
    delete:
      description: Permanently deletes a configuration object.
      operationId: DeleteConfig
      parameters:
        - explode: false
          in: path
          name: key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: simple
        - explode: false
          in: path
          name: config
          required: true
          schema:
            $ref: "#/components/schemas/ConfigParam"
          style: simple
        - explode: false
          in: query
          name: user_token
          schema:
            $ref: "#/components/schemas/UserTokenParam"
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  code:
                    enum:
                      - 2000
                    format: int32
                    type: integer
                  message:
                    enum:
                      - Success
                    type: string
                  result:
                    properties:
                      deleted:
                        example: 1
                        format: int32
                        minimum: 0
                        type: number
                    required:
                      - deleted
                    type: object
                required:
                  - result
                  - code
                  - message
                title: Config Delete Response
                type: object
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
          description: Unauthorized Request
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundResponse"
          description: Not Found
      summary: Delete
      tags:
        - Configs
    get:
      description: Retrieve config object by name
      operationId: RetrieveConfig
      parameters:
        - explode: false
          in: path
          name: key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: simple
        - explode: false
          in: path
          name: config
          required: true
          schema:
            $ref: "#/components/schemas/ConfigParam"
          style: simple
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfigResponse"
          description: Success
          headers: {}
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundResponse"
          description: Not Found
      summary: Retrieve
      tags:
        - Configs
    post:
      description: Updates configuration object
      operationId: UpdateConfig
      parameters:
        - explode: false
          in: path
          name: key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: simple
        - explode: false
          in: path
          name: config
          required: true
          schema:
            $ref: "#/components/schemas/ConfigParam"
          style: simple
        - explode: false
          in: query
          name: user_token
          schema:
            $ref: "#/components/schemas/UserTokenParam"
          style: form
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ConfigUpdateParam"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ConfigResponse"
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedResponse"
          description: Unauthorized Request
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NotFoundResponse"
          description: Not Found
      summary: Update
      tags:
        - Configs
  "/keys/{key}/details":
    get:
      deprecated: false
      description: |
        Returns private data on the key including remaining lookups, available datasets and usage limits.
      operationId: KeyDetails
      parameters:
        - explode: false
          in: path
          name: key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: simple
        - explode: false
          in: query
          name: user_token
          schema:
            $ref: "#/components/schemas/UserTokenParam"
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyDetailsResponse"
          description: Success
        "401":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Unauthorised
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Resource not found
      summary: Details
      tags:
        - Keys
  "/keys/{key}/licensees":
    get:
      description: Returns a list of licensees for a key.
      operationId: ListLicensees
      parameters:
        - explode: false
          in: path
          name: key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: simple
        - description: Specify ID of the licensee after which you would like to list results
          explode: false
          in: query
          name: starting_after
          schema:
            format: int32
            type: integer
          style: form
        - explode: false
          in: query
          name: user_token
          schema:
            $ref: "#/components/schemas/UserTokenParam"
          style: form
        - description: Specify the maximum number of results to return per page. Default and maximum is `100`.
          explode: false
          in: query
          name: limit
          schema:
            $ref: "#/components/schemas/LimitParam"
          style: form
        - description: Filter result by licensee name. Query can be shortened to `q=`
          explode: false
          in: query
          name: query
          schema:
            type: string
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LicenseesResponse"
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
      summary: List
      tags:
        - Licensees
    post:
      description: Create a licensee for the specified API Key.
      operationId: CreateLicensee
      parameters:
        - explode: false
          in: path
          name: key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: simple
        - explode: false
          in: query
          name: user_token
          schema:
            $ref: "#/components/schemas/UserTokenParam"
          style: form
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LicenseeEditable"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LicenseeResponse"
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
      summary: Create
      tags:
        - Licensees
  "/keys/{key}/licensees/{licensee}":
    delete:
      description: Cancels a licensee key. This renders a licensee unusable. This action can be reversed if you get in contact with us.
      operationId: DeleteLicensee
      parameters:
        - explode: false
          in: path
          name: key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: simple
        - explode: false
          in: path
          name: licensee
          required: true
          schema:
            $ref: "#/components/schemas/LicenseeParam"
          style: simple
        - explode: false
          in: query
          name: user_token
          schema:
            $ref: "#/components/schemas/UserTokenParam"
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  code:
                    enum:
                      - 2000
                    format: int32
                    type: integer
                  message:
                    enum:
                      - Success
                    type: string
                  result:
                    properties:
                      deleted:
                        example: 1
                        format: int32
                        minimum: 0
                        type: number
                    required:
                      - deleted
                    type: object
                required:
                  - result
                  - code
                  - message
                title: Licensee Delete Response
                type: object
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
      summary: Cancel
      tags:
        - Licensees
    get:
      description: Returns licensee information as identified by the licensee key.
      operationId: RetrieveLicensee
      parameters:
        - explode: false
          in: path
          name: key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: simple
        - explode: false
          in: path
          name: licensee
          required: true
          schema:
            $ref: "#/components/schemas/LicenseeParam"
          style: simple
        - explode: false
          in: query
          name: user_token
          schema:
            $ref: "#/components/schemas/UserTokenParam"
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LicenseeResponse"
          description: Success
          headers: {}
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
      summary: Retrieve
      tags:
        - Licensees
    put:
      description: Update Licensee
      operationId: UpdateLicensee
      parameters:
        - explode: false
          in: path
          name: key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: simple
        - explode: false
          in: path
          name: licensee
          required: true
          schema:
            $ref: "#/components/schemas/LicenseeParam"
          style: simple
        - explode: false
          in: query
          name: user_token
          schema:
            $ref: "#/components/schemas/UserTokenParam"
          style: form
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LicenseeEditable"
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LicenseeResponse"
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
      summary: Update
      tags:
        - Licensees
  "/keys/{key}/lookups":
    get:
      description: |
        Reports lookup information on a key for paid lookups.

        This method requires a `user_token`, which can be found on your [accounts page](https://ideal-postcodes.co.uk/account).

        A maximum interval of 90 days can be provided for analysis. If no start or end date is provided, the last 21 days will be used as the default interval.

        ## Download Usage History (CSV)

        `GET /keys/:key/lookups`

        Returns a CSV download of lookups performed and associated information.

        Note that the Content-Type returned will be CSV (text/csv). For a non 200 response, the `Content-Type` will revert to JSON with the error code and message embedded.

        ## Data Redaction

        Personally Identifiable Data (PII) caught in this your usage log (including IP, search term and URL data) will be redacted on a weekly basis.

        By default, PII will be redacted if it is older than 21 days. This timeframe can be configured from your dashboard.

        You may prevent PII collection altogether by setting the interval to `0` days.
      operationId: KeyLogs
      parameters:
        - explode: false
          in: path
          name: key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: simple
        - description: An start date/time in the form of a UNIX Timestamp in milliseconds, e.g. `1418556452651`. If no start time is provided, the start time will be assigned to a time 21 days prior to the end time.
          explode: false
          in: query
          name: start
          schema:
            $ref: "#/components/schemas/StartParam"
          style: form
        - description: An end date/time in the form of a UNIX Timestamp in milliseconds, e.g. `1418556452651`. If no end time is provided, the current time will be used.
          explode: false
          in: query
          name: end
          schema:
            $ref: "#/components/schemas/EndParam"
          style: form
        - description: Sublicensed keys only. This will restrict the analysed dataset to a specific licensee.
          explode: false
          in: query
          name: licensee
          schema:
            $ref: "#/components/schemas/LicenseeParam"
          style: form
      responses:
        "200":
          content:
            text/csv:
              example: |
                2015-02-21T16:05:22.991Z,82.85.128.18,SW12AA,https://www.example.com/,Postcode Lookup,
                2015-02-21T16:05:38.298Z,82.85.128.18,10 Downing Street London,https://www.example.com/,Address Lookup,CRM
                2015-02-21T16:06:49.227Z,82.85.128.18,OX44PP,https://www.example.com/,Postcode Lookup,"Website,Live"
                2015-02-21T16:07:02.706Z,82.85.128.18,PL9 9HE,https://www.example.com/,Postcode Lookup,
              schema:
                description: Success
                type: string
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
      summary: Logs (CSV)
      tags:
        - Keys
      x-codeSamples:
        - label: URL
          lang: http
          source: |
            https://api.ideal-postcodes.co.uk/v1/keys/iddqd/lookups?user_token=my_secret_token
        - label: CLI
          lang: cURL
          source: |
            curl -k -G https://api.ideal-postcodes.co.uk/v1/keys/iddqd/lookups \
              -d "user_token=my_secret_token"
  "/keys/{key}/usage":
    get:
      description: |
        Reports the number of lookups consumed on a key for a range of days.

        A maximum interval of 90 days can be provided for analysis. If no start or end date is provided, the last 21 days will be used as the default interval.
      operationId: KeyUsage
      parameters:
        - explode: false
          in: path
          name: key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: simple
        - description: A start date/time in the form of a UNIX Timestamp in milliseconds, e.g. `1418556452651`. If no start time is provided, the start time will be assigned to a time 21 days prior to the end time.
          explode: false
          in: query
          name: start
          schema:
            $ref: "#/components/schemas/StartParam"
          style: form
        - description: An end date/time in the form of a UNIX Timestamp in milliseconds, e.g. `1418556452651`. If no end time is provided, the current time will be used.
          explode: false
          in: query
          name: end
          schema:
            $ref: "#/components/schemas/EndParam"
          style: form
        - explode: false
          in: query
          name: tags
          schema:
            $ref: "#/components/schemas/TagsParam"
          style: form
        - description: Sublicensed keys only. This will restrict the analysed dataset to a specific licensee.
          explode: false
          in: query
          name: licensee
          schema:
            $ref: "#/components/schemas/LicenseeParam"
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyUsageResponse"
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
      summary: Usage Stats
      tags:
        - Keys
      x-codeSamples:
        - label: URL
          lang: http
          source: |
            https://api.ideal-postcodes.co.uk/v1/keys/iddqd/usage?user_token=my_secret_token
        - label: CLI
          lang: cURL
          source: |
            curl -k -G https://api.ideal-postcodes.co.uk/v1/keys/iddqd/usage \
              -d "user_token=my_secret_token"
  /phone_numbers:
    get:
      description: |
        Query for and validate phone numbers.
      operationId: PhoneNumberValidation
      parameters:
        - explode: false
          in: query
          name: api_key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: form
        - description: Specifies the phone number to validate. Phone number must include a country code in acceptable format. For instance, UK phone numbers should be suffixed `+44`, `44` or `0044`.
          explode: false
          in: query
          name: query
          required: true
          schema:
            type: string
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PhoneNumberResponse"
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
        "429":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Rate Limit Timeout
      summary: Phone Number Validation
      tags:
        - Phone Numbers
      x-codeSamples:
        - label: URL
          lang: http
          source: |
            https://api.ideal-postcodes.co.uk/v1/phone_numbers?api_key=ak_test&query=02071128019
        - label: CLI
          lang: cURL
          source: |
            curl -k -G 'https://api.ideal-postcodes.co.uk/v1/phone_numbers' \
              -d 'api_key=iddqd' \
              --data-urlencode 'query=02071128019'
  /places:
    get:
      description: |
        Query for geographical places across countries. Each query will return a list of place suggestions, which consists of a place name, descriptive name and id.

        This API returns geographical information such as countries, capitals, administrative areas and more. It is ideal for correctly identifying a place along with any other details like geolocation.

        ## Implementing Place Autocomplete

        Extracting the full information of a place is a 2 step process:

        1. Retrieve place suggestions via /places
        2. Retrieve the entire place with the ID provided in the suggestion

        ## Suggestion Format

        Each place suggestion contains a descriptive name which you can provide to users to uniquely idenfity a place.

        ## Rate Limiting

        You can make up to 3000 requests to the autocomplete API within a 5 minute span. The HTTP Header contains information on your current rate limit.

        | Header                  | Description                                                                            |
        | ----------------------- | -------------------------------------------------------------------------------------- |
        | `X-RateLimit-Limit`     | The maximum number of requests that can be made in 5 minutes                           |
        | `X-RateLimit-Remaining` | The remaining requests within the current rate limit window                            |
        | `X-RateLimit-Reset`     | The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds |

        ## Pricing

        This API currently does not affect your balance. However, resolving a suggestion into a full place requires a paid request.

        Please note, this API is not intended as a standalone free resource. Integrations that consistently make autocomplete requests without a paid request to resolve an place may be disrupted via tightened rate limits.
      operationId: FindPlace
      parameters:
        - explode: false
          in: query
          name: api_key
          required: true
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: form
        - description: Specifies the place you wish to query. Query can be shortened to `q=`
          explode: false
          in: query
          name: query
          schema:
            type: string
          style: form
        - explode: false
          in: query
          name: country_iso
          schema:
            $ref: "#/components/schemas/CountryIsoParam"
          style: form
        - explode: false
          in: query
          name: bias_country_iso
          schema:
            $ref: "#/components/schemas/BiasCountryIsoParam"
          style: form
        - explode: false
          in: query
          name: bias_lonlat
          schema:
            $ref: "#/components/schemas/BiasLonLatParam"
          style: form
        - explode: false
          in: query
          name: bias_ip
          schema:
            $ref: "#/components/schemas/BiasIpParam"
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PlaceResponse"
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
      summary: Find Place
      tags:
        - Place Search
      x-codeSamples:
        - label: URL
          lang: http
          source: |
            https://api.ideal-postcodes.co.uk/v1/places?api_key=ak_test&query=london
        - label: CLI
          lang: cURL
          source: |
            curl -k -G 'https://api.ideal-postcodes.co.uk/v1/places' \
              -d 'api_key=ak_test' \
              --data-urlencode 'query=london'
  "/places/${place}":
    get:
      description: |
        Resolves a place autocompletion by its place ID.
      operationId: ResolvePlace
      parameters:
        - description: ID of place suggestion
          explode: false
          in: path
          name: place
          required: true
          schema:
            type: string
          style: simple
        - explode: false
          in: query
          name: api_key
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResolvePlaceResponse"
          description: Success
          headers: {}
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Resource not found
      summary: Resolve Place
      tags:
        - Place Search
      x-codeSamples:
        - label: URL
          lang: http
          source: |
            https://api.ideal-postcodes.co.uk/v1/places/geonames_5353?api_key=ak_test
        - label: CLI
          lang: cURL
          source: |
            curl -k -G https://api.ideal-postcodes.co.uk/v1/places/geonames_5355?api_key=ak_test \
              -d "api_key=ak_test"
  "/postcodes/{postcode}":
    get:
      description: |
        Returns the complete list of addresses for a postcode. Postcode searches are space and case insensitive.

        The Postcode Lookup API provides a JSON interface to search UK addresses from a postcode. It can be used to power Postcode Lookup driven address searches, like [Postcode Lookup](/postcode-lookup).

        ## Postcode Not Found

        Lookup balance is unaffected by invalid postcodes. The API returns a `404` response with response body:

        ```json
        {
          "code": 4040,
          "message": "Postcode not found",
          "suggestions": ["SW1A 0AA"]
        }
        ```

        ### Suggestions

        If a postcode cannot be found, the API will provide up to 5 closest matching postcodes. Common errors will be corrected first (e.g. mixing up `O` and `0` or `I` and `1`).

        If the suggestion list is small (fewer than 3), there is a high probability the correct postcode is there. You may notify the user or immediately trigger new searches.

        The suggestion list will be empty if the postcode has deviated too far from a valid postcode format.

        ## Multiple Residence

        A small number of postcodes will return more than 100 premises. These may require pagination. Use `page` to paginate the result set.
      operationId: Postcodes
      parameters:
        - description: Postcode to retrieve
          explode: false
          in: path
          name: postcode
          required: true
          schema:
            $ref: "#/components/schemas/paf_postcode"
          style: simple
        - explode: false
          in: query
          name: api_key
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: form
        - explode: false
          in: query
          name: filter
          required: false
          schema:
            $ref: "#/components/schemas/FilterParam"
          style: form
        - explode: false
          in: query
          name: page
          required: false
          schema:
            $ref: "#/components/schemas/PageParam"
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostcodeResponse"
          description: Success
        "400":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/BadRequestResponse"
          description: Bad Request
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PostcodeNotFoundResponse"
          description: Postcode Not Found
      summary: Lookup Postcode
      tags:
        - UK
      x-codeSamples:
        - label: URL
          lang: http
          source: |
            https://api.ideal-postcodes.co.uk/v1/postcodes/SW1A2AA?api_key=iddqd
        - label: CLI
          lang: cURL
          source: |
            curl -G -k \
            --url 'https://api.ideal-postcodes.co.uk/v1/postcodes/SW1A2AA' \
            --d "api_key=iddqd"
  "/udprn/{udprn}":
    get:
      description: |-
        Returns an address as identified by its Unique Delivery Point Reference Number (UDPRN).

        You may find it useful to store UDPRN information as it can be used to retrieve the most recent information for an address. It can also be used to test for a deleted address.

        UDPRNs are an eight digit unique numeric code (e.g. 25962203) for any premise on the Postcode Address File. It's essentially a unique identifier for every address in the UK that Royal Mail has in its database.

        ## Testing

        To test your implementation of our API we have a range of test UDPRNs that yield both successful and unsuccessful responses to your request.

        They are the following:

        - `0` Returns a successful UDPRN lookup response
          `2000`
        - `-1` Returns "UDPRN not found", error `4044`
        - `-2` Returns "no lookups remaining", error `4020`
        - `-3` Returns "daily (or individual) lookup limit breached",
          error `4021`

        Test request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.
      operationId: UDPRN
      parameters:
        - description: UDPRN to be retrieved
          explode: false
          in: path
          name: udprn
          required: true
          schema:
            type: string
          style: simple
        - explode: false
          in: query
          name: api_key
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: form
        - explode: false
          in: query
          name: filter
          schema:
            $ref: "#/components/schemas/FilterParam"
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UDPRNResponse"
          description: Success
          headers: {}
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Resource not found
      summary: Retrieve by UDPRN
      tags:
        - UK
      x-codeSamples:
        - label: URL
          lang: http
          source: |
            https://api.ideal-postcodes.co.uk/v1/udprn/0?api_key=iddqd
        - label: CLI
          lang: cURL
          source: |
            curl -k -G https://api.ideal-postcodes.co.uk/v1/udprn/0 \
              -d "api_key=iddqd"
  "/umprn/{umprn}":
    get:
      description: |
        Returns a multiple occupancy address identifited via its UMPRN (Multiple Residence Unique ID).

        UMPRNs are a unique numeric code for any Multiple Residence household on the optional Multiple Residence dataset.

        ## Testing

        To test your implementation of our API we have a range of test UMPRNs that yield both successful and unsuccessful responses to your request. They are the following

        - `0` Returns a successful UMPRN lookup response `2000`
        - `-1` Returns "UMPRN not found", error `4044`
        - `-2` Returns "no lookups remaining", error `4020`
        - `-3` Returns "daily (or individual) lookup limit breached", error `4021`

        Test request undergo the usual authentication and restriction rules. This is to help surface any issues that occur during implementation and does not cost you a lookup.

        ### Pricing

        Per lookup charges apply. Empty responses are not charged.
      operationId: UMPRN
      parameters:
        - description: UMPRN to be retrieved
          explode: false
          in: path
          name: umprn
          required: true
          schema:
            type: string
          style: simple
        - explode: false
          in: query
          name: api_key
          schema:
            $ref: "#/components/schemas/ApiKeyParam"
          style: form
        - explode: false
          in: query
          name: filter
          schema:
            $ref: "#/components/schemas/FilterParam"
          style: form
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UMPRNResponse"
          description: Success
          headers: {}
        "404":
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
          description: Resource not found
      summary: Retrieve by UMPRN
      tags:
        - UK
      x-codeSamples:
        - label: URL
          lang: http
          source: |
            https://api.ideal-postcodes.co.uk/v1/umprn/0?api_key=iddqdmr
        - label: CLI
          lang: cURL
          source: |
            curl -k -G https://api.ideal-postcodes.co.uk/v1/umprn/0 \
              -d "api_key=iddqdmr"
components:
  schemas:
    AbAddress:
      allOf:
        - $ref: "#/components/schemas/PafBase"
        - properties:
            country:
              enum:
                - England
                - Scotland
                - Wales
            country_iso:
              enum:
                - GBR
            country_iso_2:
              enum:
                - GB
            dataset:
              enum:
                - ab
              type: string
            language:
              enum:
                - en
            native:
              $ref: "#/components/schemas/AddressBaseCore"
            postcode_type:
              enum:
                - ""
              title: Postcode Type
              type: string
          required:
            - native
          type: object
      description: |-
        Address from Ordnance Survey AddressBase Ccore dataset.

        Please contact us to have this enabled on your account.

        All AddressBase Core address have a UPRN and a rooftop geolocation available however they may not have a UDPRN.
      title: AddressBase Core
    AddressBaseCore:
      description: Represents a GB address in Ordnance Survey's AddressBase Core dataset
      properties:
        administrative_county:
          $ref: "#/components/schemas/paf_administrative_county"
        building_name:
          description: The building name is a description applied to a single address or a group of addresses.
          maxLength: 110
          title: Building Name
          type: string
        building_number:
          description: The building number is a number or range of numbers given to a single address or a group of addresses.
          maxLength: 13
          title: Building Number
          type: string
        change_code:
          description: This enumeration is used in association with the attribute “CHANGE_CODE”. This enumeration identifies the type of change that has been made to a feature. The change type must be set when a feature is inserted, updated or deleted. Please see section 3 for more information. Example I = Insert, U = Update, D = Delete
          enum:
            - I
            - U
            - D
          maxLength: 50
          title: Change Code
          type: string
        classification_code:
          description: A code that describes the classification of the address record to a maximum of a secondary level.
          maxLength: 4
          title: Classification Code
          type: string
        country:
          $ref: "#/components/schemas/paf_country"
        country_iso:
          $ref: "#/components/schemas/paf_country_iso"
        county:
          $ref: "#/components/schemas/paf_county"
        dataset:
          description: Indicates the provenance of an address
          enum:
            - ab
          title: Dataset
          type: string
        delivery_point_suffix:
          description: A two-character code uniquely identifying an individual delivery point within a postcode, assigned by Royal Mail.
          maxLength: 2
          title: Delivery Point Suffix
          type: string
        district:
          $ref: "#/components/schemas/paf_district"
        eastings:
          description: A value in metres defining the x location in accordance with the British National Grid.
          maxLength: 8
          multipleOf: 0.01
          title: Easting
          type: number
        gss_code:
          description: The Office for National Statistics Governmental Statistical Service (GSS) code representing the contributing Local Authority.
          maxLength: 9
          title: Governmental Statistical Service
          type: string
        id:
          $ref: "#/components/schemas/ID"
        island:
          description: Third level of geographic area name to record island names where appropriate.
          maxLength: 50
          title: Island
          type: string
        language:
          $ref: "#/components/schemas/Language"
        last_update_date:
          description: The latest date on which any of the attributes on this record were last changed.
          format: date
          title: Last Update Date
          type: string
        latitude:
          description: A value in metres defining the y location in accordance with the British National Grid.
          title: Latitude
          type: number
        line_1:
          $ref: "#/components/schemas/paf_line1"
        line_2:
          $ref: "#/components/schemas/paf_line2"
        line_3:
          $ref: "#/components/schemas/paf_line3"
        locality:
          description: A locality defines an area or geographical identifier within a town, village or hamlet. Locality represents the lower level geographical area. The locality field should be used in conjunction with the town name and street description fields to uniquely identify geographic area where there may be more than one within an administrative area.
          maxLength: 35
          title: Locality
          type: string
        longitude:
          description: A value defining the Longitude location in accordance with the ETRS89 coordinate reference system.
          title: Longitude
          type: number
        northings:
          description: A value in metres defining the y location in accordance with the British National Grid.
          maxLength: 9
          multipleOf: 0.01
          title: Northing
          type: number
        organisation:
          description: The organisation name is the business name given, when appropriate, to an address record.
          maxLength: 100
          title: Organisation
          type: string
        parent_uprn:
          description: UPRN of the parent Record if a parent-child relationship exists.
          maxLength: 12
          title: PARENT_UPRN
          type: string
        po_box:
          description: Text concatenation of 'PO BOX' and the Post Office Box (PO Box) number or 'BFPO' and the British Forces Post Office number.
          maxLength: 13
          title: PO Box
          type: string
        post_town:
          description: |-
            The town or city in which the Royal Mail sorting office is located which services this address record.

            Condition:
            POST_TOWN is not populated if this is the same as TOWN_NAME.
          maxLength: 30
          title: Town Name
          type: string
        postal_county:
          $ref: "#/components/schemas/paf_postal_county"
        postcode:
          description: A postcode assigned by Royal Mail for the address record.
          maxLength: 8
          title: Postcode
          type: string
        premise:
          $ref: "#/components/schemas/paf_premise"
        rpc:
          description: Representative Point Code describes the accuracy of the coordinate that has been allocated to the UPRN as indicated by the Local Authority and enhanced using large scale OS data.
          maxLength: 1
          title: Representative Point Code
          type: number
        single_address_line:
          description: A single attribute containing text concatenation of the address elements separated by a comma.
          maxLength: 500
          title: Single Line Address
          type: string
        street_name:
          description: Street / Road name for the address record.
          maxLength: 100
          title: Single Line Address
          type: string
        sub_building:
          description: The sub-building name and/or number for the address record.
          maxLength: 110
          title: Sub-building
          type: string
        toid:
          description: The Topographic Identifier taken from OS MasterMap Topography Layer. This TOID is assigned to the UPRN by performing a spatial intersection between the two identifiers. It consists of the letters 'osgb' and is followed by up to sixteen digits.
          maxLength: 20
          title: TOID
          type: string
        town_name:
          description: Geographical town name assigned by the Local Authority. Please note this can be different from the Post Town value assigned by Royal Mail.
          maxLength: 35
          title: Town Name
          type: string
        traditional_county:
          $ref: "#/components/schemas/paf_traditional_county"
        udprn:
          description: Royal Mail's Unique Delivery Point Reference Number (UDPRN).
          maxLength: 8
          title: UDPRN
          type: number
        uprn:
          description: Unique Property Reference Number (UPRN) assigned by the LLPG Custodian or Ordnance Survey.
          maxLength: 12
          title: UPRN
          type: string
        usrn:
          description: |-
            Unique Street Reference Number assigned by the Street Name and Numbering Custodian OR

            Ordnance Survey depending on the address record.
          maxLength: 8
          title: USRN
          type: number
        ward:
          $ref: "#/components/schemas/paf_ward"
      required:
        - language
        - dataset
        - id
        - line_1
        - line_2
        - line_3
        - premise
        - uprn
        - udprn
        - parent_uprn
        - usrn
        - toid
        - classification_code
        - eastings
        - northings
        - latitude
        - longitude
        - single_address_line
        - street_name
        - locality
        - town_name
        - delivery_point_suffix
        - post_town
        - gss_code
        - rpc
        - last_update_date
        - island
        - change_code
        - building_name
        - building_number
        - sub_building
        - postcode
        - po_box
        - organisation
        - country
        - country_iso
        - county
        - district
        - ward
        - traditional_county
        - administrative_county
        - postal_county
      title: AddressBase Core
    AddressLatitudeParam:
      description: |
        Latitude query for reverse geocoding.

        An accompanying longitude (lon=) query must be submitted for a valid reverse geocode query.
      example: 51.503541
      format: float
      maximum: 90
      minimum: -90
      title: Latitude
      type: number
    AddressLongitudeParam:
      description: |
        Longitude query for reverse geocoding.

        An accompanying latitude (lat=) query must be submitted for a valid reverse geocode query.
      example: -0.12767
      format: float
      maximum: 90
      minimum: -90
      title: Longitude
      type: number
    AddressResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          properties:
            hits:
              description: |
                List of matching addresses
              items:
                oneOf:
                  - $ref: "#/components/schemas/PafAddress"
                  - $ref: "#/components/schemas/MrAddress"
                  - $ref: "#/components/schemas/NybAddress"
                  - $ref: "#/components/schemas/WelshPafAddress"
                  - $ref: "#/components/schemas/PafAliasAddress"
                  - $ref: "#/components/schemas/AbAddress"
              type: array
            limit:
              default: 10
              example: 10
              format: int32
              maximum: 100
              minimum: 0
              type: integer
            page:
              default: 0
              example: 0
              format: int32
              maximum: 10
              minimum: 0
              type: integer
            total:
              format: int32
              maximum: 10000
              minimum: 0
              type: integer
          required:
            - hits
            - total
            - limit
            - page
          type: object
      required:
        - message
        - code
        - result
      title: Address Search Response
      type: object
    AddressSuggestion:
      description: Represents an address suggestion for any address in the world
      properties:
        id:
          $ref: "#/components/schemas/ID"
        suggestion:
          description: Address Suggestion to be displayed to the user
          example: Flat 6, 12 Roskear, Camborne, TR14
          type: string
        urls:
          type: object
      required:
        - id
        - suggestion
        - urls
      title: Address Suggestion
      type: object
    ApiKey:
      properties:
        available:
          description: |
            Determines whether the key can be used by the requesting agent. 

            Returns false if one of the following conditions are met:
              - Key has no lookups remaining
              - Daily limit has been reached on the key
              - Daily individual limit has been reached
              - Key is not being used via an authorised URL
              - (Sublicensed key only) Key has a valid licensee attached
              - (Sublicensed key only) Key is not being used via an authorised URL specified by licensee
          example: true
          type: boolean
        context:
          description: |
            Returns current context if it is in the list of available contexts for this key.
          oneOf:
            - $ref: "#/components/schemas/Context"
            - $ref: "#/components/schemas/NoContext"
        contexts:
          $ref: "#/components/schemas/AvailableContexts"
      required:
        - available
        - context
        - contexts
      title: Key
      type: object
    ApiKeyAutomatedTopup:
      description: Automated topup status
      properties:
        enabled:
          description: Indicates whether automated top-ups are enabled
          example: true
          type: boolean
      required:
        - enabled
      title: API Key Automated Topup
      type: object
    ApiKeyCurrentPurchase:
      properties:
        consumed:
          description: Number of consumed lookups off this purchase.
          example: 121
          format: int32
          minimum: 0
          type: integer
        expires:
          description: |-
            `string` or `null` The date when this purchase will expire in simplified 
            extended ISO format (ISO 8601). This is typically 365 days from the time 
            of first use. This field will be `null` if the purchase has not yet been 
            used.
          example: 2022-01-06T11:41:27.092Z
          nullable: true
          type: string
        purchased:
          description: Number of procured lookups from this purchase.
          example: 20000
          format: int32
          minimum: 0
          type: integer
      required:
        - expires
        - purchased
        - consumed
      title: API Key Batch Purchase
      type: object
    ApiKeyDailyLimit:
      properties:
        consumed:
          description: Number of lookups performed today which count towards your daily limit.
          example: 288
          format: int32
          minimum: 0
          type: integer
        limit:
          description: |-
            `number` or `null`. The daily lookup limit currently set on your key. 
            `null` means the limit is currently disabled.
          example: 1000
          format: int32
          minimum: 0
          nullable: true
          type: integer
      required:
        - limit
        - consumed
      title: API Key Daily Limit
      type: object
    ApiKeyDatasets:
      description: Indicates which datasets are available and added by default to the address responses
      properties:
        ecad:
          description: IE Address File. Eircode Address Database
          example: false
          type: boolean
        ecaf:
          description: IE Base Address File. Eircode Address File
          example: false
          type: boolean
        herewe:
          description: Western Europe Address File
          example: true
          type: boolean
        mr:
          description: UK Multiple Residence Dataset
          example: true
          type: boolean
        nyb:
          description: UK Not Yet Built Dataset
          example: false
          type: boolean
        paf:
          description: UK Main Address File (Postcode Address File)
          example: true
          type: boolean
        pafa:
          description: UK Property Alias dataset
          example: false
          type: boolean
        pafw:
          description: UK Welsh Language Dataset
          example: false
          type: boolean
        usps:
          description: US Address Dataset
          example: true
          type: boolean
      required:
        - paf
        - mr
        - nyb
        - pafa
        - pafw
        - ecad
        - ecaf
        - usps
      title: API Key Dataset Availability
      type: object
    ApiKeyDetails:
      properties:
        allowed_urls:
          description: A list of allowed URLs. An empty list means that allowed URLs are disabled.
          items:
            type: string
          type: array
        automated_topups:
          $ref: "#/components/schemas/ApiKeyAutomatedTopup"
        current_purchases:
          description: Current balance purchases attached to key.
          items:
            $ref: "#/components/schemas/ApiKeyCurrentPurchase"
          type: array
        daily_limit:
          $ref: "#/components/schemas/ApiKeyDailyLimit"
        datasets:
          $ref: "#/components/schemas/ApiKeyDatasets"
        individual_limit:
          $ref: "#/components/schemas/ApiKeyIndividualLimit"
        lookups_remaining:
          example: 19889
          format: int32
          minimum: 0
          type: integer
        notifications:
          $ref: "#/components/schemas/ApiKeyNotifications"
      required:
        - lookups_remaining
        - daily_limit
        - individual_limit
        - allowed_urls
        - notificatinos
        - automated_topups
        - current_purchases
      title: API Key Details
      type: object
    ApiKeyDetailsResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          $ref: "#/components/schemas/ApiKeyDetails"
      required:
        - message
        - code
        - result
      title: API Key Details Response
      type: object
    ApiKeyIndividualLimit:
      properties:
        limit:
          description: |-
            `number` or `null` Limit set on the number of lookups that can be 
            performed from a single IP address. `null` means the limit is currently 
            disabled.
          example: 30
          format: int32
          minimum: 0
          nullable: true
          type: integer
      required:
        - limit
      title: API Key Individual Limit
      type: object
    ApiKeyNotifications:
      properties:
        emails:
          description: A list of email addresses designated by you to receive notifications about this key.
          items:
            example: person@example.com
            type: string
          type: array
        enabled:
          description: Indicates whether email notifications are enabled.
          type: boolean
      required:
        - emails
        - enabled
      title: API Key Notifications
      type: object
    ApiKeyParam:
      description: |
        Your API Key. Typically beings `ak_`.

        Available from your dashboard
      example: ak_test
      title: API Key
      type: string
    ApiKeyResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          $ref: "#/components/schemas/ApiKey"
      required:
        - message
        - code
        - result
      title: API Key Response
      type: object
    ApiKeyUsageResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          $ref: "#/components/schemas/KeyUsageResult"
      required:
        - message
        - code
        - result
      title: Key Usage Response
      type: object
    AutocompleteResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          properties:
            hits:
              items:
                oneOf:
                  - $ref: "#/components/schemas/AddressSuggestion"
                  - $ref: "#/components/schemas/UkAddressSuggestion"
              type: array
          required:
            - hits
          type: object
      required:
        - message
        - code
        - result
      title: Address Autocomplete Response
      type: object
    AvailableContexts:
      description: A list of available contexts for a key
      items:
        properties:
          description:
            description: |
              Country descriptor to show in Address Finder
            example: United States
            type: string
          emoji:
            description: Emoji text icon
            example: 🇺🇸
            type: string
          iso_2:
            description: 2 letter ISO code
            example: US
            type: string
          iso_3:
            description: 3 letter ISO code
            example: USA
            type: string
          rgeo:
            description: |
              Indicates availability of reverse geolocation search
            example: true
            type: boolean
        required:
          - iso_3
          - iso_2
          - description
          - emoji
          - rgeo
        type: object
      title: Available Contexts
      type: array
    BadRequestResponse:
      allOf:
        - $ref: "#/components/schemas/ErrorResponse"
        - properties:
            code:
              description: "`400X` type error response code"
              format: int32
              type: integer
            errors:
              items:
                properties:
                  errorCode:
                    example: required.openapi.validation
                    type: string
                  message:
                    description: Indicates location of error in request query or URL parameter
                    example: should have required property 'type'
                    type: string
                  path:
                    description: Indicates location of error in request query or URL parameter
                    example: .query.type
                    type: string
                required:
                  - path
                  - message
                type: object
              type: array
            message:
              description: Bad request error description
              type: string
          required:
            - code
            - message
          type: object
      title: Bad Request Error Response
    BiasCountryIsoParam:
      description: |-
        Bias by country ISO code. Uses 3 letter country code (ISO 3166-1) standard.
        Bias by multiple countries with a comma separated list. E.g. `GBR,IRL`
      example: GBR
      title: Country
      type: string
    BiasCountryParam:
      description: Bias by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.
      title: Bias Country
      type: string
    BiasIpParam:
      description: |-
        Biases search based on approximate geolocation of IP address.
        Set `bias_ip=true` to enable.
      enum:
        - "true"
      example: "true"
      title: Bias query by Geolocation of IP
      type: string
    BiasLonLatParam:
      description: Bias search to a geospatial circle determined by an origin and radius in meters. Max radius is `50000`.  Uses the format bias_lonlat=[longitude],[latitude],[radius in metres] Only one geospatial bias may be provided
      example: -2.095,57.15,100
      title: Bias Lon/Lat
      type: string
    BiasPostcodeAreaParam:
      description: Bias by postcode area, the first one or two non-numeric characters of a postcode.
      example: The postcode area of SW1A 2AA and N1 6RT are SW and N respectively
      title: Bias Postcode Area
      type: string
    BiasPostcodeOutwardParam:
      description: Bias by outward code
      title: Bias Postcode Outward
      type: string
    BiasPostcodeParam:
      description: Bias by postcode. Can be combined with query to perform a postcode + building number/name search.
      example: /addresses?postcode=SW1A2AA&q=10
      title: Bias Postcode
      type: string
    BiasPostcodeSectorParam:
      description: Bias by postcode sector, the outward code plus first numeric of the inward code.
      example: SW1A 2AA is SW1A 2
      title: Bias Postcode Sector
      type: string
    BiasPosttownParam:
      description: Bias by town.
      title: Bias Post Town
      type: string
    BiasThoroughfareParam:
      description: Bias by street name.
      title: Bias Thoroughfare
      type: string
    BoxParam:
      description: Restrict search to a geospatial box determined by the "top-left" and "bottom-right" gelocations.   Only one geospatial box can be provided.
      example: 2.095,57.15,-2.096,57.14
      title: Box
      type: string
    Carrier:
      nullable: true
      properties:
        country:
          description: Country that number is associated with. In ISO 3166-1 alpha-2 format.
          example: GB
          nullable: true
          title: Country ISO Alpha-2 Code
          type: string
        name:
          description: The full name of the carrier that number is associated with.
          example: BT Group
          nullable: true
          title: Name
          type: string
        network_code:
          description: The [Mobile Country Code](https://en.wikipedia.org/wiki/Mobile_country_code) for the carrier.
          example: "234"
          nullable: true
          title: Network Code
          type: string
        network_type:
          description: Type of network that number is associated with.
          enum:
            - mobile
            - landline
            - landline_premium
            - landline_tollfree
            - virtual
            - unknown
            - pager
          nullable: true
          title: Network Type
          type: string
      required:
        - network_code
        - name
        - country
        - network_type
      title: Carrier Object
      type: object
    CleanseResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          oneOf:
            - $ref: "#/components/schemas/GbrCleanseMatch"
            - $ref: "#/components/schemas/GbrCleanseNoMatch"
      required:
        - message
        - code
        - result
      title: Address Cleanse Response
      type: object
    Config:
      properties:
        createdAt:
          description: Timestamp for when the config was updated
          example: 2016-01-21T17:14:49.971Z
          type: string
        name:
          description: A unique name to identify the configuration payload
          example: woocommerce
          maximum: 32
          minimum: 0
          type: string
        payload:
          description: A serialised payload of up to `4096` characters
          example: |
            {
              "removeOrganisation": false
            }
          maximum: 4096
          minimum: 0
          type: string
        updatedAt:
          description: Timestamp for when the config was created
          example: 2016-01-21T17:14:49.971Z
          type: string
      required:
        - updatedAt
        - createdAt
        - name
        - payload
      title: Config Object
      type: object
    ConfigNewParam:
      description: Required configuration object parameters
      properties:
        name:
          description: A unique name to identify the configuration payload
          example: woocommerce
          maximum: 32
          minimum: 0
          type: string
        payload:
          description: A serialised payload of up to `4096` characters
          example: |
            {
              "removeOrganisation": false
            }
          maximum: 4096
          minimum: 0
          type: string
      required:
        - name
        - payload
      title: New Config Object
      type: object
    ConfigParam:
      description: User provided configuration object name
      example: idpc-be
      title: Configuration Name
      type: string
    ConfigResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          $ref: "#/components/schemas/Config"
      required:
        - result
        - code
        - message
      title: Config Response
      type: object
    ConfigUpdateParam:
      description: Config object update parameters
      properties:
        payload:
          description: A serialised payload of up to `4096` characters
          example: |
            {
              "removeOrganisation": false
            }
          maximum: 4096
          minimum: 0
          type: string
      title: Update Config Object
      type: object
    ConfigsResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          description: List of configurations
          properties:
            configs:
              items:
                $ref: "#/components/schemas/Config"
              type: array
          required:
            - configs
          type: object
      required:
        - message
        - code
        - result
      title: Config List Response
      type: object
    Context:
      description: Limits search results within a geographical boundary or country.
      title: Context
      type: string
    Country:
      description: |2
          Full country names (ISO 3166)
      enum:
        - United States
        - Guam
        - Puerto Rico
        - England
        - Scotland
        - Wales
        - Northern Ireland
        - Jersey
        - Guernsey
        - Isle of Man
        - Ireland
      example: England
      title: Country
      type: string
    CountryISO:
      description: |2
          3 letter country code (ISO 3166-1)
      enum:
        - GBR
        - IMN
        - JEY
        - GGY
        - USA
        - PRI
        - GUM
        - IRL
      title: ISO Country Code (3)
      type: string
    CountryISO2:
      description: |2
         2 letter country code (ISO 3166-1)
      enum:
        - GB
        - IM
        - JE
        - GG
        - US
        - PR
        - GU
        - IE
      title: ISO Country Code (2)
      type: string
    CountryIsoParam:
      description: |-
        Filter by country ISO code. Uses 3 letter country code (ISO 3166-1) standard.
        Filter by multiple countries with a comma separated list. E.g. `GBR,IRL`
      example: GBR
      title: Country
      type: string
    CountryParam:
      description: Filter by country. Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man.
      example: England
      title: Country
      type: string
    Dataset:
      description: |-
        Indicates the provenance of an address.

          - `paf` (GBR) Postcode Address File
          - `mr` (GBR) Multiple Residence File
          - `nyb` (GBR) Not Yet Built File
          - `pafa` (GBR) Alias File
          - `pafw` (GBR) Welsh File
          - `ab` (GBR) AddressBase Core
          - `ecaf` (IRL) Eircode ECAF
          - `ecad` (IRL) Eircode ECAD
          - `usps` (USA) USPS Zip+4
      enum:
        - paf
        - pafw
        - pafa
        - mr
        - nyb
        - usps
        - ecaf
        - ecad
        - ab
      title: Dataset
      type: string
    Eastings:
      description: |-
        Eastings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid).

        Northern Ireland Eastings uses the [Irish Grid Reference System](https://en.wikipedia.org/wiki/Irish_grid_reference_system).

        Metres from origin. E.g. `550458`

        Returns an empty string if no location data is available. Otherwise a number is returned.
      oneOf:
        - description: Empty string `""` if not available
          type: string
        - description: Metres offset east from origin
          example: 9382
          maximum: 999999
          minimum: 0
          type: number
      title: Eastings
    EcadAddress:
      allOf:
        - $ref: "#/components/schemas/EircBase"
        - properties:
            address_point_id:
              description: Address Point ID
              example: "10098783"
              maxLength: 10
              minLength: 1
              type: string
            address_type:
              description: |-
                Addresses points can assume one of the following values:

                - Residential Address Point. This type of address point has one residential addresses associated with it.
                - Non-Residential Address Point. This type of address point has one or more non-residential address (business, club or other organisation) associated with it.
                - Mixed Address Point. This is a special case where the residential and non residential addresses in the building are essentially the same address. The typical example is a farm house on an active farm. It is important to note that this is a special case. In general a building with both residential and non-residential addresses (e.g. an apartment over a shop) will receive two address points, one commercial and one residential, and hence two Eircodes.

                Buildings can contain multiple address points of type Residential and/or Non-Residential.
              minLength: 0
              type: string
            building_address_type:
              description: |-
                The building type can assume one of the following values:

                - Single Occupancy Residential Building. This type of building contains one residential address.
                - Multi Occupancy Residential Building. This type of building contains multiple residential addresses.
                - Single Occupancy Non-Residential Building. This type of building contains one non-residential address (business, club or other organisation).
                - Multi Occupancy Non-Residential Building. This type of building contains multiple non-residential addresses (business, club or other organisation).
                - Multi Occupancy Mixed Use Building. This type of building contains multiple residential and non- residential addresses.

                Buildings can also have a more specific address types such as a Hospital, School, Shopping Centre, etc.
              minLength: 0
              type: string
            building_group_address_type:
              description: |-
                The building group type can be:

                - Residential Building Group. This type of building group contains buildings with residential addresses only.
                - Non-Residential Building Group This type of building group contains buildings with non-residential addresses (business, club or other organisation) only.
                - Mixed Building Group. This type of building group contains buildings with residential and non-residential addresses. Can also have a more specific address type such as a Hospital, School, Shopping Centre, etc.

                Building groups can also have a more specific address type such as a Hospital, School, Shopping Centre, etc.
              minLength: 0
              type: string
            building_group_id:
              description: Building Group ID
              example: "10098783"
              type: string
            building_id:
              description: Building ID
              example: "10098783"
              maxLength: 10
              minLength: 1
              type: string
            building_type:
              description: Describes the type of building, e.g. detached, semi-detached, bungalow.
              minLength: 0
              type: string
            building_use:
              description: |-
                Can be one of:

                - `R` Residential 
                - `C` Commercial
                - `B` Both 
                - `U` Unknown
              enum:
                - R
                - C
                - B
                - U
            dataset:
              enum:
                - ecad
              type: string
            ded_id:
              description: |-
                Unique Identifier for Electoral Divisions 2017 data.

                Note that this field is subject to breaking changes if a new generation of government data IDs is released. Currently this uses 2017 IDs. Contact us to be notified ahead of his change.
              minLength: 0
              type: string
            ecad_id:
              description: Unique 10 digit ECAD ID
              example: "17000000"
              maxLength: 10
              minLength: 1
              type: string
            gaeltacht:
              description: |-
                Gaeltact refers to a district where the Irish government recognises that the Irish language is the predominant language.

                Returns `true` if address is in a Gaeltacht area and `false` if not.
              type: boolean
            gaeltacht_id:
              description: |-
                Unique Identifier for the 7 Gaeltacht areas 2017 data.

                Note that this field is subject to breaking changes if a new generation of government data IDs is released. Currently this uses 2017 IDs. Contact us to be notified ahead of his change.
              minLength: 0
              type: string
            holiday_home:
              description: A Yes/No field, indicating whether or not the building is a holiday home.
              enum:
                - N
                - Y
                - ""
            local_authority:
              description: Name of local authority
              minLength: 0
              type: string
            nace_category:
              description: Name of the NACE Category
              minLength: 0
              type: string
            nace_code:
              description: The NACE Code for the Category.
              minLength: 0
              type: string
            nua:
              description: |-
                NUA means "non-unique address".

                The NUA field contains `true` when the address is a non-unique address, and `false` when it is a unique address.

                Ireland has a very high level of non-unique addresses (NUA), i.e. the address does not contain a unique building number or name. Approximately 35% of all Irish addresses are non-unique which equates to 600,000 addresses.

                The typical example of NUA addressing is where every address in a townland is the same. The way that post is delivered is by local knowledge of postal delivery personnel of which addressee lives in which house.

                N.B. For a NUA address, it is impossible to match to a unique record in the ECAD and assign an Eircode.
              type: boolean
            org_vacant:
              description: A Yes/No field, indicating whether the organisation is vacant.
              enum:
                - Y
                - N
                - ""
            organisation_id:
              description: Organisation ID
              example: "10098783"
              maxLength: 10
              minLength: 1
              type: string
            post_county_id:
              description: Post County ID
              example: "10098783"
              maxLength: 10
              minLength: 1
              type: string
            post_town:
              description: |-
                The post town is a significant element of the Postal Address, however it is not always populated in an address. The official post office guide, Eolaí an Phoist1, describes post towns in the following manner:

                "A provincial postal address may include the name of a town or village several miles distant, with which the addressee has little or no connection, and, in some places, especially if this residence happens to be near a county boundary, the name of the neighbouring county instead of the county in which he actually resides. The explanation is that the main mail despatches have to be sent for more detailed sub division to certain centres known as post towns, chosen because of their accessibility and convenience."
              minLength: 0
              type: string
            post_town_id:
              description: Post Town ID
              example: "10098783"
              maxLength: 10
              minLength: 1
              type: string
            postaim_presort_152:
              description: An Post sorting information.
              minLength: 0
              type: string
            postaim_presort_61:
              description: An Post sorting information.
              minLength: 0
              type: string
            primary_locality_address_type:
              description: |-
                The locality type can be:
                  - Rural Locality. This is generally a townland.
                  - Industrial Estate. Industrial Estate, Industrial Park, Business Campus, etc.
                  - Shopping District. Shopping Centre.
                  - Housing Estate. Residential Housing Estate.
                  - Village. Based on Census 2011 population < 1,500.
                  - Town. Based on Census 2011 population > 1,500.
                  - Urban Area. Wholly within a village/town/city e.g. Rathmines.
                  - Suburban Locality. This is an area that is both rural and urban, as it is both a townland, and also an area name applied to houses in a town, as the town has extended partially into the townland.

                Where the locality is also the post town, the type can be:
                  - Village. Based on Census 2011 population < 1,500
                  - Town. Based on Census 2011 population > 1,500
                  - Postal District. Dublin 1 to 24
                  - City. Dublin, Cork, Limerick, Galway or Waterford
              minLength: 0
              type: string
            primary_locality_id:
              description: Primary Locality ID
              example: "10098783"
              maxLength: 10
              minLength: 1
              type: string
            primary_thoroughfare_id:
              description: Primary Thoroughfare ID
              example: "10098783"
              maxLength: 10
              minLength: 1
              type: string
            publicity_post_zone:
              description: An Post publicity post zone information.
              minLength: 0
              type: string
            secondary_locality_address_type:
              description: |-
                The locality type can be:
                  - Rural Locality. This is generally a townland.
                  - Industrial Estate. Industrial Estate, Industrial Park, Business Campus, etc.
                  - Shopping District. Shopping Centre.
                  - Housing Estate. Residential Housing Estate.
                  - Village. Based on Census 2011 population < 1,500.
                  - Town. Based on Census 2011 population > 1,500.
                  - Urban Area. Wholly within a village/town/city e.g. Rathmines.
                  - Suburban Locality. This is an area that is both rural and urban, as it is both a townland, and also an area name applied to houses in a town, as the town has extended partially into the townland.

                Where the locality is also the post town, the type can be:
                  - Village. Based on Census 2011 population < 1,500
                  - Town. Based on Census 2011 population > 1,500
                  - Postal District. Dublin 1 to 24
                  - City. Dublin, Cork, Limerick, Galway or Waterford
              minLength: 0
              type: string
            secondary_locality_id:
              description: Secondary Locality ID
              example: "10098783"
              type: string
            secondary_thoroughfare_id:
              description: Secondary Thoroughfare ID
              example: "10098783"
              type: string
            small_area_id:
              description: |-
                Unique Identifier for the Small Area 2017 data.

                Note that this field is subject to breaking changes if a new generation of government data IDs is released. Currently this uses 2017 IDs. Contact us to be notified ahead of his change.
              minLength: 0
              type: string
            townland_id:
              description: |-
                Unique Identifier for townland 2017 data.

                Note that this field is subject to breaking changes if a new generation of government data IDs is released. Currently this uses 2017 IDs. Contact us to be notified ahead of his change.
              minLength: 0
              type: string
            under_construction:
              description: A Yes/No field, indicating whether or not the building is under construction.
              enum:
                - N
                - Y
                - ""
            vacant:
              description: A Yes/No field, indicating whether the building is vacant.
              enum:
                - Y
                - N
                - ""
          type: object
      description: The ECAD contains additional data for each ECAF address.
      required:
        - organisation_id
        - address_point_id
        - building_id
        - building_group_id
        - primary_thoroughfare_id
        - secondary_thoroughfare_id
        - primary_locality_id
        - secondary_locality_id
        - post_town
        - post_town_id
        - post_county_id
        - nua
        - gaeltacht
        - address_type
        - building_address_type
        - building_group_address_type
        - primary_locality_address_type
        - secondary_locality_address_type
        - building_type
        - holiday_home
        - under_construction
        - building_use
        - vacant
        - org_vacant
        - nace_code
        - nace_category
        - local_authority
        - ded_id
        - small_area_id
        - townland_id
        - gaeltacht_id
        - postaim_presort_61
        - postaim_presort_152
        - publicity_post_zone
      title: Ireland ECAD Address
    EcafAddress:
      allOf:
        - $ref: "#/components/schemas/EircBase"
        - properties:
            dataset:
              enum:
                - ecaf
              type: string
            ecaf_id:
              description: The unique identifier in the ECAF is the `ecaf_id`. This unique identifier allows each address in the ECAF to be uniquely identified. It can also be used as index once the data has been imported into a relational database. This is a numeric field that can store values from 0 to 2,147,483,647. It is represented as a number up to 10 digits long. All other fields in ECAF are alphanumeric.
              maxLength: 10
              minLength: 0
              type: string
          type: object
      description: ECAF is the Eircode Address File which contains one record for each Postal Address. English language and Irish language versions are available. It is distributed as a flat file, details of data provision and updates are provided in section 2.
      required:
        - ecaf_id
      title: Ireland ECAF Address
    EircBase:
      properties:
        address_reference:
          description: The address reference is the An Post GeoDirectory address reference identifier used by the Universal Service Provider.
          maxLength: 16
          minLength: 0
          type: string
        building_group:
          description: A building group is a collection of buildings with a collective name, located on or near the same thoroughfare.
          example: Marrian Terrace
          maxLength: 60
          minLength: 0
          type: string
        building_name:
          description: The name given to the building. Prepended by sub building, if any, when the sub building does not appear on a line to itself. The building name is omitted if it is the same as either the Organisation or Building Group.
          example: Rose Cottage
          maxLength: 60
          minLength: 0
          type: string
        building_number:
          description: |-
            A number associated with the whole building. The building number may have a numeric and an alphanumeric component, which are concatenated e.g. 2A, or alternatively will have a simple building number or a complex building number. The building number always relates to the whole building and not a sub-unit within it.
            A complex building number may be one of the following:
              - Dual. Two number separated by '/' e.g. 63/64 = 63, 64
              - Sequence. An odd or even sequence of numbers with lower and upper bound separated by an underscore '_' e.g. `1_5` = 1,3,5 and `2_6` = 2,4,6 
              - Range. A range of consecutive numbers with lower and upper bound separated by a dash '-' e.g. `63-66` = 63, 64, 56, 66
            The building number never appears on a line by itself and can prepend Building Group, Primary Thoroughfare or Primary Locality.
          example: 22
          maxLength: 40
          minLength: 0
          type: string
        country:
          description: |2
              Full country names (ISO 3166)
          enum:
            - Ireland
          type: string
        country_iso:
          description: |2
              3 letter country code (ISO 3166-1)
          enum:
            - IRL
        country_iso_2:
          description: |2
             2 letter country code (ISO 3166-1)
          enum:
            - IE
          type: string
        dataset:
          description: Source of address
          type: string
        department:
          description: The department or division within an organisation. If the department element exists, then the organisation must also exist.
          example: Accounts Department
          maxLength: 60
          minLength: 0
          type: string
        eircode:
          description: |-
            The seven character Eircode has an A65 F4E2 format. The Eircode is a mandatory address element. The last line of a Postal Address will contain the Eircode, displayed with a space. e.g. `A65 F4E2`.

            The Eircode is always the last line of a Postal Address generated within the state, e.g. if an address has four lines then the Eircode will be on its own on Address Line 5. For inbound international mail the country name IRELAND should be appended as the last line of the Postal Address.
          example: A65 R2AF
          maxLength: 60
          minLength: 0
          type: string
        id:
          $ref: "#/components/schemas/ID"
        language:
          description: |
            Language represented by 2 letter ISO Code (639-1)
          enum:
            - en
            - ga
        latitude:
          $ref: "#/components/schemas/Latitude"
        line_1:
          description: Address Line 1
          maxLength: 200
          minLength: 0
          type: string
        line_2:
          description: Address Line 2
          maxLength: 200
          minLength: 0
          type: string
        line_3:
          description: Address Line 3
          maxLength: 200
          minLength: 0
          type: string
        line_4:
          description: Address Line 4
          maxLength: 200
          minLength: 0
          type: string
        line_5:
          description: Address Line 5
          maxLength: 200
          minLength: 0
          type: string
        line_6:
          description: Address Line 6
          maxLength: 200
          minLength: 0
          type: string
        line_7:
          description: Address Line 7
          maxLength: 200
          minLength: 0
          type: string
        line_8:
          description: Address Line 8
          maxLength: 200
          minLength: 0
          type: string
        line_9:
          description: Address Line 9
          maxLength: 200
          minLength: 0
          type: string
        longitude:
          $ref: "#/components/schemas/Longitude"
        organisation:
          description: Organisation name
          example: Oak Tree Limited
          maxLength: 60
          minLength: 0
          type: string
        post_county:
          description: One of the 26 Counties in the Republic of Ireland. These counties are sub-national divisions used for the purposes of administrative, geographical and political demarcation. Post County is the County associated with the Post Town, not the geographic county in which the building is located. The Post County is normally used as part of the Postal Address with some exceptions e.g. Dublin Postal Districts where the Post County is not used and some Post Towns (e.g. Tipperary, Kildare, etc.) that have the same name as the Post County.
          example: Cork
          maxLength: 30
          minLength: 0
          type: string
        primary_locality:
          description: |-
            First locality elements which can refer to areas, districts, industrial estates, towns, etc.

            The primary locality refers to the specific place the address is.

            In urban areas, the primary locality can be required to distinguish between two thoroughfares of the same name in the same district or town. Industrial estates with named thoroughfares are also held as localities. In rural areas the primary locality is generally a townland name.
          example: Cookstown Industrial Estate
          maxLength: 40
          minLength: 0
          type: string
        primary_thoroughfare:
          description: |-
            The name of the thoroughfare on which premises are located. It may appear on a line by itself or be appended to either a sub building or building number.

            Addresses with thoroughfares can sometimes have the thoroughfare excluded where a Building Group exists, such as a Retail Centre or Business Park, and the thoroughfare is not part of the Postal Address.
          example: Griffith Road
          maxLength: 40
          minLength: 0
          type: string
        secondary_locality:
          description: |-
            Never present without a primary locality. The secondary locality has a wider geographic scope than the primary locality.

            It is the secondary locality therefore which differentiates addresses with the same primary locality name within the same county.

            Secondary localities are more likely to be required for rural addresses.

            Second locality elements which can refer to areas, districts, industrial estates, towns, etc

            The secondary locality helps identify where the primary locality is located.
          example: Manorhamilton
          maxLength: 40
          minLength: 0
          type: string
        secondary_thoroughfare:
          description: |-
            It is never present without a primary thoroughfare. The primary thoroughfare is dependent on the secondary thoroughfare and appears before the secondary thoroughfare in any address.

            Secondary thoroughfare are generally used to assist locating a primary thoroughfare.
          example: Navan Road
          maxLength: 40
          minLength: 0
          type: string
        sub_building_name:
          description: The sub-building refers to an apartment, flat or unit within a building.
          example: Flat 1
          maxLength: 60
          minLength: 0
          type: string
        tertiary_locality:
          description: |-
            Also known as the Post Town.

            The name of the post town associated with the premises for postal delivery purposes. This includes Dublin Postal Districts "Dublin 1" to "Dublin 24".

            The post town is a significant element of the Postal Address, however it is not always populated in an address. The official post office guide, Eolaí an Phoist4, describes post towns in the following manner:

            "A provincial postal address may include the name of a town or village several miles distant, with which the addressee has little or no connection, and, in some places, especially if this residence happens to be near a county boundary, the name of the neighbouring county instead of the county in which he actually resides. The explanation is that the main mail despatches have to be sent for more detailed sub division to certain centres known as POST TOWNS, chosen because of their accessibility and convenience."
          example: Dublin 14
          maxLength: 40
          minLength: 0
          type: string
      required:
        - id
        - dataset
        - country
        - country_iso
        - country_iso_2
        - language
        - longitude
        - latitude
        - department
        - organisation
        - sub_building_name
        - building_name
        - building_number
        - building_group
        - primary_thoroughfare
        - secondary_thoroughfare
        - primary_locality
        - secondary_locality
        - tertiary_locality
        - post_county
        - eircode
        - line_1
        - line_2
        - line_3
        - line_4
        - line_5
        - line_6
        - line_7
        - line_8
        - line_9
        - address_reference
    Email:
      properties:
        catchall:
          description: Returns `true` if this domain accepts all emails regardless of username
          type: boolean
        deliverable:
          description: Returns `true` if the email can be delivered
          type: boolean
        disposable:
          description: Returns `true` if email comes from a disposable email service like temp-mail
          type: boolean
        free:
          description: Returns `true` if the email originates from a free service like Outlook or Gmail.
          type: boolean
        result:
          enum:
            - deliverable
            - not_deliverable
          type: string
        role:
          description: Returns `true` if email address represents an organisational role like `admin`, `support`, `postmaster` etc
          type: boolean
      required:
        - result
        - deliverable
        - role
        - free
        - disposable
        - catchall
      title: Email Object
      type: object
    EmailResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          oneOf:
            - $ref: "#/components/schemas/Email"
            - $ref: "#/components/schemas/UnknownEmail"
      required:
        - message
        - code
        - result
      title: Email Verification Response
      type: object
    EndParam:
      description: |
        An start date/time in the form of a UNIX Timestamp in milliseconds, e.g.  `1418556477882`.
      example: 1418556477882
      format: int32
      title: End Time
      type: integer
    ErrorResponse:
      properties:
        code:
          description: API Response Code. Non `2xxx` code indicates a failure. This code will provide a more specific reason when a failure occurs and facilitates debugging.
          format: int32
          type: integer
        message:
          description: Human readable error message supplied with every error response.
          type: string
      required:
        - code
        - message
      title: Basic Error Response
      type: object
    FilterParam:
      description: |
        Comma separated whitelist of address elements to return. 

        E.g. `filter=line_1,line_2,line_3` returns only `line_1`, `line_2` and `line_3` address elements in your response
      example: line_1,line_2,line_3
      title: Filter
      type: string
    GbrCleanseMatch:
      properties:
        confidence:
          description: |
            A confidence score represented as number between 1 and 0. 1 indicates a full match. 0 indicates no complete matching elements.
          maximum: 1
          minimum: 0
          type: number
        count:
          description: |
            The number of addresses we matched to the input. We return the closest match by default.
          maximum: 10
          minimum: 0
          type: number
        fit:
          description: |
            A score represented as number between 1 and 0. Fit compares the address elements present in your query against the matching address elements. It does not incorporate elements you have not presented in the score. A partial address (e.g. 12 Pye Green Road) will have a fit of 1 even though it is missing post town and postcode. Its confidence score will be less than 1 however because it is missing some crucial elements.
          maximum: 1
          minimum: 0
          type: number
        locality_match:
          description: Match indicator for the locality
          enum:
            - FULL
            - PARTIAL
            - INCORRECT
            - MISSING
            - NA
          type: string
        match:
          description: Nearest matching address
          oneOf:
            - $ref: "#/components/schemas/PafAddress"
            - $ref: "#/components/schemas/MrAddress"
            - $ref: "#/components/schemas/NybAddress"
            - $ref: "#/components/schemas/PafAliasAddress"
            - $ref: "#/components/schemas/WelshPafAddress"
        organisation_match:
          description: Match indicator for the organisation
          enum:
            - FULL
            - PARTIAL
            - INCORRECT
            - MISSING
            - NA
          type: string
        post_town_match:
          description: Match indicator for the post_town
          enum:
            - FULL
            - PARTIAL
            - INCORRECT
            - MISSING
            - NA
          type: string
        postcode_match:
          description: Match indicator for the postcode
          enum:
            - FULL
            - PARTIAL
            - INCORRECT
            - MISSING
            - NA
          type: string
        premise_match:
          description: Match indicator for the premise
          enum:
            - FULL
            - PARTIAL
            - INCORRECT
            - MISSING
            - NA
          type: string
        query:
          description: Originally submitted query
          type: string
        thoroughfare_match:
          description: Match indicator for the street
          enum:
            - FULL
            - PARTIAL
            - INCORRECT
            - MISSING
            - NA
          type: string
      required:
        - query
        - match
        - count
        - fit
        - confidence
        - organisation_match
        - premise_match
        - thoroughfare_match
        - postcode_match
        - locality_match
        - post_town_match
      title: Address Match
      type: object
    GbrCleanseNoMatch:
      properties:
        confidence:
          description: ""
          enum:
            - 0
          format: float
          type: number
        count:
          description: ""
          enum:
            - 0
          type: number
        fit:
          description: ""
          enum:
            - 0
          format: float
          type: number
        locality_match:
          description: ""
          enum:
            - NO_MATCH
          type: string
        match:
          description: Nearest matching address
          enum:
            - null
          nullable: true
          type: object
        organisation_match:
          description: ""
          enum:
            - NO_MATCH
          type: string
        post_town_match:
          description: ""
          enum:
            - NO_MATCH
          type: string
        postcode_match:
          description: ""
          enum:
            - NO_MATCH
          type: string
        premise_match:
          description: ""
          enum:
            - NO_MATCH
          type: string
        query:
          description: Originally submitted query
          type: string
        thoroughfare_match:
          description: ""
          enum:
            - NO_MATCH
          type: string
      required:
        - query
        - match
        - count
        - fit
        - confidence
        - organisation_match
        - premise_match
        - thoroughfare_match
        - postcode_match
        - locality_match
        - post_town_match
      title: No Address Match
      type: object
    GbrGlobalAddress:
      description: Global (non-UK) address in the UK address format
      properties:
        administrative_county:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        building_name:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        building_number:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        country:
          $ref: "#/components/schemas/Country"
        country_iso:
          $ref: "#/components/schemas/CountryISO"
        country_iso_2:
          $ref: "#/components/schemas/CountryISO2"
        county:
          description: State or county name
          example: Georgia
          type: string
        county_code:
          description: Code abbreviation for state or county used in some countries.
          example: GA
          type: string
        dataset:
          $ref: "#/components/schemas/Dataset"
        delivery_point_suffix:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        department_name:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        dependant_locality:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        dependant_thoroughfare:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        district:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        double_dependant_locality:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        eastings:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        id:
          $ref: "#/components/schemas/ID"
        language:
          $ref: "#/components/schemas/Language"
        latitude:
          $ref: "#/components/schemas/Latitude"
        line_1:
          description: First line of the address. Typically the building number and street name
          example: 10 Georgia Ave
          title: Address First Line
          type: string
        line_2:
          description: Second line of the address. Can be blank
          example: ""
          title: Address Second Line
          type: string
        line_3:
          description: Third line of the address. Can also be blank
          example: ""
          title: Address Third Line
          type: string
        longitude:
          $ref: "#/components/schemas/Longitude"
        native:
          description: The native representation of a non-UK address
          oneOf:
            - $ref: "#/components/schemas/EcadAddress"
            - $ref: "#/components/schemas/EcafAddress"
            - $ref: "#/components/schemas/UspsAddress"
            - $ref: "#/components/schemas/UspsAddress"
        northings:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        organisation_name:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        po_box:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        post_town:
          description: |
            The city, town or other primary locality
          example: Commerce
          type: string
        postal_county:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        postcode:
          description: Represents the postal or zip code
          example: 30529-2320
          title: Postal Code
          type: string
        postcode_inward:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        postcode_outward:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        postcode_type:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        premise:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        su_organisation_indicator:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        sub_building_name:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        thoroughfare:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        traditional_county:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
        udprn:
          description: Not available for non-UK addresses. See `id` for address identifier
          type: string
        umprn:
          description: Not available for non-UK addresses. See `id` for address identifier
          enum:
            - ""
          type: string
        uprn:
          description: Not available for non-UK addresses. See `id` for address identifier
          enum:
            - ""
          type: string
        ward:
          description: Not available for non-UK addresses
          enum:
            - ""
          type: string
      required:
        - postcode
        - postcode_outward
        - postcode_inward
        - post_town
        - dependant_locality
        - double_dependant_locality
        - thoroughfare
        - dependant_thoroughfare
        - building_number
        - building_name
        - sub_building_name
        - po_box
        - department_name
        - organisation_name
        - udprn
        - umprn
        - postcode_type
        - su_organisation_indicator
        - delivery_point_suffix
        - line_1
        - line_2
        - line_3
        - premise
        - country
        - administrative_county
        - postal_county
        - traditional_county
        - district
        - ward
        - longitude
        - latitude
        - eastings
        - northings
        - uprn
        - county
        - county_code
        - id
        - dataset
        - country_iso
        - country_iso_2
        - language
        - native
      title: Global Address
    GbrResolveAddressResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          oneOf:
            - $ref: "#/components/schemas/PafAddress"
            - $ref: "#/components/schemas/MrAddress"
            - $ref: "#/components/schemas/WelshPafAddress"
            - $ref: "#/components/schemas/PafAliasAddress"
            - $ref: "#/components/schemas/NybAddress"
            - $ref: "#/components/schemas/AbAddress"
            - $ref: "#/components/schemas/GbrGlobalAddress"
      required:
        - message
        - code
        - result
      title: Address Resolution Response (GBR)
      type: object
    GeonamesPlace:
      allOf:
        - properties:
            admin1_code:
              description: Fipscode (subject to change to iso code)
              example: ENG
              maxLength: 20
              minLength: 0
              type: string
            admin1_geonameid:
              description: GeoName ID for first administrative area
              example: 5353
              format: int32
              nullable: true
              type: integer
            admin1_name:
              description: Name of first administrative area
              example: England
              type: string
            admin2_code:
              description: Code for the second administrative division
              example: "06"
              maxLength: 20
              minLength: 0
              type: string
            admin2_geonameid:
              description: GeoName ID for second administrative area
              example: 5353
              format: int32
              nullable: true
              type: integer
            admin2_name:
              description: Name of second administrative area
              example: England
              type: string
            admin3_code:
              description: Code for third level administrative division
              example: "08"
              maxLength: 20
              minLength: 0
              type: string
            admin4_code:
              description: Code for fourth level administrative division
              example: "07"
              maxLength: 20
              minLength: 0
              type: string
            alternatenames:
              description: List of alternate ASCII names
              items:
                oneOf:
                  - description: Alternate name for place
                    example: London
                    maxLength: 40
                    minLength: 0
                    type: string
              type: array
            asciiname:
              description: Place Name (ASCII)
              example: London
              maxLength: 200
              minLength: 0
              type: string
            cc2:
              description: List of other countries codes mapping to this place
              items:
                oneOf:
                  - description: Alternate name for place
                    example: IE
                    maxLength: 2
                    minLength: 2
                    type: string
              type: array
            country_code:
              description: 2 Letter ISO country code
              example: GB
              maxLength: 2
              minLength: 2
              type: string
            dataset:
              enum:
                - geonames
              type: string
            dem:
              description: Digital elevation model
              example: 32
              format: int32
              nullable: true
              type: integer
            elevation:
              description: Elevation in meters
              format: int32
              nullable: true
              type: integer
            feature_class:
              description: GeoNames single letter feature code
              enum:
                - A
                - H
                - L
                - P
                - R
                - S
                - T
                - U
                - V
              type: string
            feature_code:
              description: Full GeoNames feature code (http://www.geonames.org/export/codes.html)
              example: ADM1
              maxLength: 7
              minLength: 0
              type: string
            geonameid:
              description: Unique identifier for GeoNames place
              example: 5353
              format: int32
              type: integer
            id:
              description: Unique place ID
              example: geonames_5353
              type: string
            latitude:
              $ref: "#/components/schemas/Latitude"
            longitude:
              $ref: "#/components/schemas/Longitude"
            modification_date:
              description: Datetime format
              example: 2015-03-09
              maxLength: 10
              minLength: 10
              type: string
            name:
              description: Place name (UTF8)
              example: London
              maxLength: 200
              minLength: 0
              type: string
            population:
              description: Population at place. Represented as string as it could be a larger than a 32bit integer
              example: "7392832"
              type: string
            timezone:
              description: The IANA timezone ID
              example: Europe/London
              maxLength: 40
              minLength: 0
              type: string
          type: object
      description: Full GeoNames place specification
      required:
        - geonameid
        - name
        - asciiname
        - alternatenames
        - latitude
        - longitude
        - feature_class
        - feature_code
        - country_code
        - cc2
        - admin1_geonameid
        - admin2_geonameid
        - admin1_name
        - admin2_name
        - admin1_code
        - admin2_code
        - admin3_code
        - admin4_code
        - population
        - elevation
        - dem
        - timezone
        - modification_date
      title: GeoNames Place
    ID:
      description: Global unique internally generated identifier for an address
      example: paf_8387729
      title: ID
      type: string
    InvalidPhoneNumber:
      properties:
        country:
          description: Full country name
          enum:
            - null
          nullable: true
          type: string
        current_carrier:
          description: Representation of current phone carrier information like network code, name, country, network type
          enum:
            - null
          nullable: true
          type: string
        international_format:
          description: Phone number formatted to international standard
          enum:
            - null
          nullable: true
          type: string
        iso_country:
          description: Country code in 3 letter ISO format
          enum:
            - null
          nullable: true
          type: string
        iso_country_2:
          description: Country code in 2 letter ISO format
          enum:
            - null
          nullable: true
          type: string
        national_format:
          description: Phone number formatted to local standard
          enum:
            - null
          nullable: true
          type: string
        original_carrier:
          description: Representation of original phone carrier information like network code, name, country, network type
          enum:
            - null
          nullable: true
          type: string
        valid:
          enum:
            - false
          type: boolean
      required:
        - valid
        - national_format
        - international_format
        - iso_country
        - iso_country_2
        - country
      title: Invalid Phone Number Object
      type: object
    KeyUsageResult:
      properties:
        dailyCount:
          description: |
            An array of objects representing number of paid lookups made on specific days, ordered by date. Each object contains a `date` attribute, which represents the day and a `count` attribute, which represents the number of paid lookups made on that day.
          items:
            properties:
              count:
                example: 132
                format: int32
                type: integer
              date:
                example: 2015-01-22T00:00:00.000Z
                type: string
            required:
              - date
              - count
            type: object
          type: array
        end:
          description: End date in ISO 8601 format.
          example: 2015-01-23T15:08:06.609Z
          type: string
        start:
          description: Start date in ISO 8601 format.
          example: 2015-01-22T15:08:06.609Z
          type: string
        total:
          description: Total of paid lookups performed in specified period.
          example: 132
          format: int32
          type: integer
      required:
        - start
        - end
        - total
        - dailyCount
      title: Key Usage
      type: object
    Language:
      description: |
        Language represented by 2 letter ISO Code (639-1)
      enum:
        - en
        - cy
        - ga
      title: Language
      type: string
    Latitude:
      description: |-
        The latitude of the postcode (WGS84/ETRS89).

        Can be a positive or negative decimal. E.g. `51.5083983`.

        Returns an empty string if no location data is available. 
      oneOf:
        - description: Empty string `""` if not available
          type: string
        - description: Represents latitude
          example: 52.938278
          maximum: 90
          minimum: -90
          type: number
      title: Longitude
    Licensee:
      allOf:
        - $ref: "#/components/schemas/LicenseeEditable"
        - properties:
            createdAt:
              description: Timestamp for when the licensee was created
              example: 2016-01-21T17:14:49.971Z
              type: string
            daily:
              properties:
                count:
                  description: The number lookups performed by the licensee on the day represented b `licesees.daily.updatedAt`
                  example: 232
                  format: int32
                  minimum: 0
                  type: number
                updatedAt:
                  description: The timestamp when the limit was last used.
                  example: 2016-08-05T16:43:28.865Z
                  type: string
              required:
                - count
                - updatedAt
              type: object
            id:
              description: |
                An immutable ID provided for every licensee. Primarily used for paginated list requests.
              example: 56a11209ebe230380bf104c3
              type: string
            key:
              description: |
                Uniquely identifies a licensee for a key. 

                Required to perform paid lookups for a specific licensee. Typically begins `sk_`.
              example: sl_ijoiqsxeQgXW2gkiE0X94
              type: string
          required:
            - id
            - key
            - createdAt
            - name
            - address
            - postcode
            - whitelist
            - daily
          type: object
      title: Licensee
    LicenseeEditable:
      description: Licensee object which can be defined by user
      properties:
        address:
          description: Licensee's first, second and third line address as well as post town concatenated by commas
          example: 12 High Street, Manchester
          type: string
        daily:
          properties:
            limit:
              description: The maximum number of lookups this licensee can perform in a day. `null` indicates the limit is not active
              example: 10000
              format: int32
              minimum: 0
              nullable: true
              type: number
          type: object
        name:
          description: Licensee individual or organisation name
          example: Qwerty Widgets Limited
          type: string
        postcode:
          description: Licensee's postcode
          example: ID1 1QD
          type: string
        whitelist:
          description: A list of allowed URLs. An empty list means that whitelisting is disabled
          items:
            example: https://www.example.com
            type: string
          type: array
      title: Licensee
      type: object
    LicenseeParam:
      description: |
        Uniquely identifies a licensee
      example: sk_hk71kco54zGSGvF9eXXrvvnMOLLNh
      title: Licensee Key
      type: string
    LicenseeResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          $ref: "#/components/schemas/Licensee"
      required:
        - message
        - code
        - result
      title: Licensee Response
      type: object
    LicenseesResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          description: List of licensees
          properties:
            hasMore:
              description: Returns true if there are more licensees listed after the maximum number of results as implied by `limit`
              type: boolean
            licensees:
              items:
                $ref: "#/components/schemas/Licensee"
              type: array
          type: object
      required:
        - message
        - code
        - result
      title: Licensee List Response
      type: object
    LimitParam:
      default: 10
      description: |
        Specifies the maximum number of suggestions to retrieve.

        By default the limit is 10, unless a postcode is queried (then all addresses at that postcode will be returned). Limit can be shortened to `l=`
      example: 5
      format: int32
      maximum: 100
      minimum: 1
      title: Limit
      type: integer
    Longitude:
      description: |-
        The longitude of the postcode (WGS84/ETRS89).

        Can be a positive or negative decimal. E.g. -0.1283983

        Returns an empty string if no location data is available. 
      oneOf:
        - description: Empty string `""` if not available
          type: string
        - description: Represents longitude
          example: 0.002823
          maximum: 180
          minimum: -180
          type: number
      title: Longitude
    MrAddress:
      allOf:
        - $ref: "#/components/schemas/PafBase"
        - properties:
            country:
              enum:
                - England
                - Scotland
                - Wales
                - Northern Ireland
                - Jersey
                - Guernsey
                - Isle of Man
            country_iso:
              enum:
                - GBR
                - IMN
                - JEY
                - GGY
            country_iso_2:
              enum:
                - GB
                - IM
                - JE
                - GG
            dataset:
              enum:
                - mr
            language:
              enum:
                - en
          type: object
      description: |
        Subdivision of a Postcode Address File address. Also known as a Multiple Residence or Multiple Occupancy address.

        A Multiple Residence address does not have its own deliverable endpoint. Instead it relies on the deliverable endpoint of a parent address, where the parent address can be found on the main Postcode Address File.
      title: Multiple Residence Address
    NoContext:
      description: Empty string if no context is provided or key check has failed
      enum:
        - ""
      title: No Context Provided
      type: string
    Northings:
      description: |-
        Northings reference using the [Ordnance Survey National Grid reference system](https://en.wikipedia.org/wiki/Ordnance_Survey_National_Grid)

        Northern Ireland Northings uses the [Irish Grid Reference System](https://en.wikipedia.org/wiki/Irish_grid_reference_system)

        Metres from origin. E.g. `180458`

        Returns an empty string if no location data is available. Otherwise a number is returned  
      oneOf:
        - description: Empty string `""` if not available
          type: string
        - description: Metres offset north from origin
          example: 123932
          maximum: 999999
          minimum: 0
          type: number
      title: Northings
    NotFoundResponse:
      allOf:
        - $ref: "#/components/schemas/ErrorResponse"
        - properties:
            code:
              description: "`404X` type error response code"
              format: int32
              type: integer
            message:
              description: Resource not found error description
              type: string
          required:
            - code
            - message
          type: object
      title: Not Found Response
    NybAddress:
      allOf:
        - $ref: "#/components/schemas/PafBase"
        - properties:
            country:
              enum:
                - England
                - Scotland
                - Wales
                - Northern Ireland
                - Jersey
                - Guernsey
                - Isle of Man
            country_iso:
              enum:
                - GBR
                - IMN
                - JEY
                - GGY
            country_iso_2:
              enum:
                - GB
                - IM
                - JE
                - GG
            dataset:
              enum:
                - nyb
            language:
              enum:
                - en
          type: object
      description: |-
        A UK premise under construction and currently not occupied.

        This dataset is updated by Royal Mail on a monthly cadence.
      title: Not Yet Built Address
    PafAddress:
      allOf:
        - $ref: "#/components/schemas/PafBase"
        - properties:
            country:
              enum:
                - England
                - Scotland
                - Wales
                - Northern Ireland
                - Jersey
                - Guernsey
                - Isle of Man
            country_iso:
              enum:
                - GBR
                - IMN
                - JEY
                - GGY
            country_iso_2:
              enum:
                - GB
                - IM
                - JE
                - GG
            dataset:
              enum:
                - paf
              type: string
            language:
              enum:
                - en
          type: object
      description: |-
        Standard UK Address. Also known as a Postcode Address File (PAF) address is defined by Royal Mail and updated on a daily cadence.

        A PAF Address represents a deliverable endpoint.
      title: Postcode Address File Address
    PafAliasAddress:
      allOf:
        - $ref: "#/components/schemas/PafBase"
        - properties:
            country:
              enum:
                - England
                - Scotland
                - Wales
                - Northern Ireland
                - Jersey
                - Guernsey
                - Isle of Man
            country_iso:
              enum:
                - GBR
                - IMN
                - JEY
                - GGY
            country_iso_2:
              enum:
                - GB
                - IM
                - JE
                - GG
            dataset:
              enum:
                - pafa
            language:
              enum:
                - en
          type: object
      description: |-
        PAF Aliases addresses are alternate ways to present an address already found on PAF.

        Alias data is information the public chooses to use when addressing mail, but which isn’t actually required for delivery purposes.  The Alias data contains records of alternative address details that are included in the address but not necessarily needed for delivery purposes.
      title: PAF Alias Address
    PafBase:
      properties:
        administrative_county:
          $ref: "#/components/schemas/paf_administrative_county"
        building_name:
          $ref: "#/components/schemas/paf_building_name"
        building_number:
          $ref: "#/components/schemas/paf_building_number"
        country:
          $ref: "#/components/schemas/paf_country"
        country_iso:
          $ref: "#/components/schemas/paf_country_iso"
        country_iso_2:
          $ref: "#/components/schemas/paf_country_iso_2"
        county:
          $ref: "#/components/schemas/paf_county"
        county_code:
          description: Short code representing the county or province. May be empty (`""`)
          example: ""
          title: County Code
          type: string
        dataset:
          $ref: "#/components/schemas/paf_dataset"
        delivery_point_suffix:
          $ref: "#/components/schemas/paf_delivery_point_suffix"
        department_name:
          $ref: "#/components/schemas/paf_department_name"
        dependant_locality:
          $ref: "#/components/schemas/paf_dependant_locality"
        dependant_thoroughfare:
          $ref: "#/components/schemas/paf_dependant_thoroughfare"
        district:
          $ref: "#/components/schemas/paf_district"
        double_dependant_locality:
          $ref: "#/components/schemas/paf_double_dependant_locality"
        eastings:
          $ref: "#/components/schemas/Eastings"
        id:
          $ref: "#/components/schemas/ID"
        language:
          $ref: "#/components/schemas/paf_language"
        latitude:
          $ref: "#/components/schemas/Latitude"
        line_1:
          $ref: "#/components/schemas/paf_line1"
        line_2:
          $ref: "#/components/schemas/paf_line2"
        line_3:
          $ref: "#/components/schemas/paf_line3"
        longitude:
          $ref: "#/components/schemas/Longitude"
        northings:
          $ref: "#/components/schemas/Northings"
        organisation_name:
          $ref: "#/components/schemas/paf_organisation_name"
        po_box:
          $ref: "#/components/schemas/paf_pobox"
        post_town:
          $ref: "#/components/schemas/paf_post_town"
        postal_county:
          $ref: "#/components/schemas/paf_postal_county"
        postcode:
          $ref: "#/components/schemas/paf_postcode"
        postcode_inward:
          $ref: "#/components/schemas/paf_postcode_inward"
        postcode_outward:
          $ref: "#/components/schemas/paf_postcode_outward"
        postcode_type:
          $ref: "#/components/schemas/paf_postcode_type"
        premise:
          $ref: "#/components/schemas/paf_premise"
        su_organisation_indicator:
          $ref: "#/components/schemas/paf_su_organisation_indicator"
        sub_building_name:
          $ref: "#/components/schemas/paf_sub_building_name"
        thoroughfare:
          $ref: "#/components/schemas/paf_thoroughfare"
        traditional_county:
          $ref: "#/components/schemas/paf_traditional_county"
        udprn:
          $ref: "#/components/schemas/paf_udprn"
        umprn:
          $ref: "#/components/schemas/paf_umprn"
        uprn:
          $ref: "#/components/schemas/paf_uprn"
        ward:
          $ref: "#/components/schemas/paf_ward"
      required:
        - postcode
        - postcode_outward
        - postcode_inward
        - post_town
        - dependant_locality
        - double_dependant_locality
        - thoroughfare
        - dependant_thoroughfare
        - building_number
        - building_name
        - sub_building_name
        - po_box
        - department_name
        - organisation_name
        - udprn
        - umprn
        - postcode_type
        - su_organisation_indicator
        - delivery_point_suffix
        - line_1
        - line_2
        - line_3
        - premise
        - country
        - administrative_county
        - postal_county
        - traditional_county
        - district
        - ward
        - longitude
        - latitude
        - eastings
        - northings
        - uprn
        - county
        - county_code
        - id
        - dataset
        - country_iso
        - country_iso_2
        - language
    PageParam:
      default: 0
      description: |
        0 indexed indicator of the page of results to receive. Virtually all postcode results are returned on page 0. 

        A small number of Multiple Residence postcodes may need pagination (i.e. have more than 100 premises).
      example: 0
      format: int32
      minimum: 0
      title: Page
      type: integer
    PhoneNumber:
      properties:
        country:
          description: Full country name
          example: United Kingdom
          type: string
        current_carrier:
          $ref: "#/components/schemas/Carrier"
          description: Representation of current phone carrier information like network code, name, country, network type
        international_format:
          description: Phone number formatted to international standard
          example: "442071128019"
          type: string
        iso_country:
          description: Country code in 3 letter ISO format
          example: GBR
          type: string
        iso_country_2:
          description: Country code in 2 letter ISO format
          example: GB
          type: string
        national_format:
          description: Phone number formatted to local standard
          example: 020 7112 8019
          type: string
        original_carrier:
          $ref: "#/components/schemas/Carrier"
          description: Representation of original phone carrier information like network code, name, country, network type
        valid:
          enum:
            - true
          type: boolean
      required:
        - valid
        - national_format
        - international_format
        - iso_country
        - iso_country_2
        - country
        - current_carrier
        - original_carrier
      title: Phone Number Object
      type: object
    PhoneNumberResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          oneOf:
            - $ref: "#/components/schemas/PhoneNumber"
            - $ref: "#/components/schemas/InvalidPhoneNumber"
      required:
        - message
        - code
        - result
      title: Phone Number Verification Response
      type: object
    Place:
      description: Represents a geographical place
      properties:
        country_iso:
          $ref: "#/components/schemas/place_country_iso"
        dataset:
          description: |-
            Indicates the provenance of a place.

              - `geonames` GeoNames place
          enum:
            - geonames
          title: Dataset
          type: string
        descriptive_name:
          $ref: "#/components/schemas/place_descriptive_name"
        id:
          description: Global unique internally generated identifier for a place
          example: geonames_5353
          title: ID
          type: string
        language:
          $ref: "#/components/schemas/Language"
        latitude:
          $ref: "#/components/schemas/Latitude"
        longitude:
          $ref: "#/components/schemas/Longitude"
        name:
          $ref: "#/components/schemas/place_name"
        native:
          description: Native representation of a place
          oneOf:
            - $ref: "#/components/schemas/GeonamesPlace"
      required:
        - id
        - dataset
        - name
        - descriptive_name
        - country_iso
        - language
        - longitude
        - latitude
      title: Place
    PlaceResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          properties:
            hits:
              description: |
                List of up to 10 matching places
              items:
                oneOf:
                  - $ref: "#/components/schemas/PlaceSuggestion"
              type: array
          required:
            - hits
          type: object
      required:
        - message
        - code
        - result
      title: Place Search Response
      type: object
    PlaceSuggestion:
      description: |
        Represents a possible place given an autocomplete query.
      properties:
        country_iso:
          $ref: "#/components/schemas/place_country_iso"
        descriptive_name:
          $ref: "#/components/schemas/place_descriptive_name"
        id:
          $ref: "#/components/schemas/place_id"
        name:
          $ref: "#/components/schemas/place_name"
      required:
        - name
        - descriptive_name
        - id
        - country_iso
      title: Place Description
    PostTownParam:
      description: "Filter by town. "
      example: London
      title: Post Town
      type: string
    PostcodeAreaParam:
      description: Filter by postcode. Can be combined with query to perform a postcode + building number/name search.
      example: SW
      title: Postcode Area
      type: string
    PostcodeNotFoundResponse:
      properties:
        code:
          enum:
            - 4040
          format: int32
          type: integer
        message:
          enum:
            - Postcode not found
          type: string
        suggestions:
          description: A list of alternate nearest matching postcodes you can try
          items:
            example: SN13 0SF
            type: string
          type: array
      required:
        - message
        - code
        - suggestions
      title: Postcode Not Found
      type: object
    PostcodeOutwardParam:
      description: Filter by outward code.
      example: 1AA
      title: Postcode Outward
      type: string
    PostcodeParam:
      description: Filter by postcode. Can be combined with query to perform a postcode + building number/name search.
      example: SW1A 2AA
      title: Postcode
      type: string
    PostcodeResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          description: |
            All addresses listed at the postcode.

            If Eircode is enabled, addreses for the Republic of Ireland will be returned in the English format.
          items:
            oneOf:
              - $ref: "#/components/schemas/PafAddress"
              - $ref: "#/components/schemas/MrAddress"
              - $ref: "#/components/schemas/NybAddress"
              - $ref: "#/components/schemas/PafAliasAddress"
              - $ref: "#/components/schemas/WelshPafAddress"
              - $ref: "#/components/schemas/AbAddress"
              - $ref: "#/components/schemas/GbrGlobalAddress"
          type: array
      required:
        - message
        - code
        - result
      title: Postcode Response
      type: object
    PostcodeSectorParam:
      description: "Filter by postcode sector, the outward code plus first numeric of the inward code. "
      example: SW1A 2
      title: Postcode Sector
      type: string
    PostcodeTypeParam:
      description: Filter by Postcode Type. Useful for separating organisational and residential addresses
      example: L
      title: Country
      type: string
    RateLimitedResponse:
      allOf:
        - $ref: "#/components/schemas/ErrorResponse"
        - properties:
            code:
              description: "`429X` type error response code"
              format: int32
              type: integer
            message:
              description: Request is being rate limited
              type: string
          required:
            - code
            - message
          type: object
      title: Unauthorized Request Error Response
    ResolvePlaceResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          oneOf:
            - $ref: "#/components/schemas/Place"
      required:
        - message
        - code
        - result
      title: Place Resolution Response
      type: object
    SmallUserParam:
      description: Filter by Organisation Indicator. Useful for separating organisational and residential addresses
      example: Y
      title: SU Organisation Indicator
      type: string
    StartParam:
      description: |
        A start date/time in the form of a UNIX Timestamp in milliseconds, e.g.  `1418556452651`.
      example: 1418556452651
      format: int32
      title: Start Time
      type: integer
    TagsParam:
      description: |
        A comma separated list of tags to query over. 

        Useful if you want to specify the circumstances in which the request was made.

        If multiple tags are specified, the response will only comprise of requests for which all the tags are satisfied - i.e. searching `"foo,bar"` will only query requests which tagged both `"foo"` and `"bar"`.
      example: foo,bar
      title: Tags
      type: string
    UDPRNResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          oneOf:
            - $ref: "#/components/schemas/PafAddress"
            - $ref: "#/components/schemas/NybAddress"
      required:
        - message
        - code
        - result
      title: UDPRN Response
      type: object
    UMPRNResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          oneOf:
            - $ref: "#/components/schemas/MrAddress"
      required:
        - message
        - code
        - result
      title: UDPRN Response
      type: object
    UPRNParam:
      description: Filters by UPRN. Does not accept comma separated terms. Only a single term is permitted
      example: "100023336956"
      title: UPRN
      type: integer
    UkAddressSuggestion:
      description: |
        Represents a possible address given an autocomplete query.

        UK Address Suggestions will return a UDPRN attribute if it references a deliverable endpoint found on Royal Mail's Postcode Address File dataset.

        UK Address Suggestion will return a UMPRN if it references a multiple occupancy premise found on Royal Mail's Multiple Residence dataset.
      properties:
        id:
          $ref: "#/components/schemas/ID"
        suggestion:
          description: Address suggestion for a given query.
          example: Flat 6, 12 Roskear, Camborne, TR14
          type: string
        udprn:
          $ref: "#/components/schemas/paf_udprn"
        umprn:
          description: Optionally returned field, representing the UMPRN of a Multiple Residence household
          example: 51103417
          format: int32
          type: number
        urls:
          properties:
            udprn:
              description: URL to retrieve the entire details for a given address suggestion by the UDPRN
              example: /v1/udprn/50985827
              type: string
            umprn:
              description: Optionally returned field, to retrieve the entire details for a suggested Multiple Residence household
              example: /v1/umprn/51103417
              type: string
          required:
            - udprn
          type: object
      required:
        - id
        - suggestion
        - udprn
        - urls
      title: UK Address Suggestion
      type: object
    UnauthorizedResponse:
      allOf:
        - $ref: "#/components/schemas/ErrorResponse"
        - properties:
            code:
              description: "`401X` type error response code"
              format: int32
              type: integer
            message:
              description: Unauthorized request error description
              type: string
          required:
            - code
            - message
          type: object
      title: Unauthorized Request Error Response
    UnknownEmail:
      properties:
        catchall:
          description: Catch-all status is not known
          enum:
            - null
          nullable: true
          type: boolean
        deliverable:
          description: Deliverability is not known
          enum:
            - null
          nullable: true
          type: boolean
        disposable:
          description: Disposability is not known
          enum:
            - null
          nullable: true
          type: boolean
        free:
          description: Free email provider is not known
          enum:
            - null
          nullable: true
          type: boolean
        result:
          enum:
            - unknown
          type: string
        role:
          description: Role is not known
          enum:
            - null
          nullable: true
          type: boolean
      required:
        - result
        - deliverable
        - role
        - free
        - disposable
        - catchall
      title: Unknown Email Object
      type: object
    UsaGlobalAddress:
      description: Global (non-US) Address in the US address format
      properties:
        address_secondary_abbreviation:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        base_alternate_code:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        building_or_firm_name:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        carrier_route_id:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        carrier_route_rate_sortation:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        city:
          description: City name
          type: string
        city_abbreviation:
          description: City name abbreviation (if available)
          type: string
        city_state_mailing_name_indicator:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        city_state_name_facility_code:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        congressional_district_number:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        country:
          $ref: "#/components/schemas/Country"
        country_iso:
          $ref: "#/components/schemas/CountryISO"
        country_iso_2:
          $ref: "#/components/schemas/CountryISO2"
        county:
          description: County name
          type: string
        county_number:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        dataset:
          $ref: "#/components/schemas/Dataset"
          enum:
            - paf
        finance_number:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        government_building_indicator:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        id:
          $ref: "#/components/schemas/ID"
        lacs_status_indicator:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        language:
          $ref: "#/components/schemas/Language"
        last_line:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        line_1:
          description: First line of address
          type: string
        line_2:
          description: Second line of address
          type: string
        municipality_city_state_key:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        native:
          description: The native representation of a non-US address
          oneOf:
            - $ref: "#/components/schemas/EcadAddress"
            - $ref: "#/components/schemas/EcafAddress"
            - $ref: "#/components/schemas/PafAddress"
            - $ref: "#/components/schemas/MrAddress"
            - $ref: "#/components/schemas/NybAddress"
            - $ref: "#/components/schemas/PafAliasAddress"
            - $ref: "#/components/schemas/WelshPafAddress"
            - $ref: "#/components/schemas/AbAddress"
        plus_4_code:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        preferred_city:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        preferred_last_line_city_state_key:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        primary_number:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        record_type_code:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        secondary_number:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        state:
          description: State or province
          type: string
        state_abbreviation:
          description: Code of state or province (if available)
          type: string
        street_name:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        street_post_directional_abbreviation:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        street_pre_directional_abbreviation:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        street_suffix_abbreviation:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        update_key_number:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        urbanization_city_state_key:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        zip_classification_code:
          description: Not available for non-US addresses
          enum:
            - ""
          type: string
        zip_code:
          description: Partial postcode of address
          type: string
        zip_plus_4_code:
          description: Full postal code of address
          type: string
      required:
        - id
        - dataset
        - country
        - country_iso
        - country_iso_2
        - language
        - primary_number
        - secondary_number
        - plus_4_code
        - line_1
        - line_2
        - last_line
        - zip_code
        - zip_plus_4_code
        - update_key_number
        - record_type_code
        - carrier_route_id
        - street_pre_directional_abbreviation
        - street_name
        - street_suffix_abbreviation
        - street_post_directional_abbreviation
        - building_or_firm_name
        - address_secondary_abbreviation
        - base_alternate_code
        - lacs_status_indicator
        - government_building_indicator
        - state_abbreviation
        - state
        - municipality_city_state_key
        - urbanization_city_state_key
        - preferred_last_line_city_state_key
        - county
        - city
        - city_abbreviation
        - preferred_city
        - city_state_name_facility_code
        - zip_classification_code
        - city_state_mailing_name_indicator
        - carrier_route_rate_sortation
        - finance_number
        - congressional_district_number
        - county_number
        - native
      title: Global Address
    UsaResolveAddressResponse:
      properties:
        code:
          enum:
            - 2000
          format: int32
          type: integer
        message:
          enum:
            - Success
          type: string
        result:
          oneOf:
            - $ref: "#/components/schemas/UspsAddress"
            - $ref: "#/components/schemas/UsaGlobalAddress"
      required:
        - message
        - code
        - result
      title: Address Resolution Response (USA)
      type: object
    UserTokenParam:
      description: |
        A secret key used for sensitive operations on your account and API Keys.

        Your user token can be retrieved and managed from your [accounts page](https://ideal-postcodes.co.uk/account).

        Typically beings `uk_...`
      example: uk_B59ScW1p1HHouf1VqclEPZUx
      title: User Token
      type: string
    UspsAddress:
      description: Standard USA Address
      properties:
        address_secondary_abbreviation:
          $ref: "#/components/schemas/address_secondary_abbreviation"
        base_alternate_code:
          $ref: "#/components/schemas/base_alternate_code"
        building_or_firm_name:
          $ref: "#/components/schemas/building_or_firm_name"
        carrier_route_id:
          $ref: "#/components/schemas/carrier_route_id"
        carrier_route_rate_sortation:
          $ref: "#/components/schemas/carrier_route_rate_sortation"
        city:
          $ref: "#/components/schemas/city"
        city_abbreviation:
          $ref: "#/components/schemas/city_abbreviation"
        city_state_mailing_name_indicator:
          $ref: "#/components/schemas/city_state_mailing_name_indicator"
        city_state_name_facility_code:
          $ref: "#/components/schemas/city_state_name_facility_code"
        congressional_district_number:
          $ref: "#/components/schemas/congressional_district_number"
        country:
          $ref: "#/components/schemas/usps_country"
        country_iso:
          $ref: "#/components/schemas/usps_country_iso"
        country_iso_2:
          $ref: "#/components/schemas/usps_country_iso_2"
        county:
          $ref: "#/components/schemas/county"
        county_number:
          $ref: "#/components/schemas/county_number"
        dataset:
          $ref: "#/components/schemas/usps_dataset"
        finance_number:
          $ref: "#/components/schemas/finance_number"
        government_building_indicator:
          $ref: "#/components/schemas/government_building_indicator"
        id:
          $ref: "#/components/schemas/ID"
        lacs_status_indicator:
          $ref: "#/components/schemas/lacs_status_indicator"
        language:
          $ref: "#/components/schemas/usps_language"
        last_line:
          $ref: "#/components/schemas/last_line"
        line_1:
          $ref: "#/components/schemas/line_1"
        line_2:
          $ref: "#/components/schemas/line_2"
        municipality_city_state_key:
          $ref: "#/components/schemas/municipality_city_state_key"
        plus_4_code:
          $ref: "#/components/schemas/plus_4_code"
        preferred_city:
          $ref: "#/components/schemas/preferred_city"
        preferred_last_line_city_state_key:
          $ref: "#/components/schemas/preferred_last_line_city_state_key"
        primary_number:
          $ref: "#/components/schemas/primary_number"
        record_type_code:
          $ref: "#/components/schemas/record_type_code"
        secondary_number:
          $ref: "#/components/schemas/secondary_number"
        state:
          $ref: "#/components/schemas/state"
        state_abbreviation:
          $ref: "#/components/schemas/state_abbreviation"
        street_name:
          $ref: "#/components/schemas/street_name"
        street_post_directional_abbreviation:
          $ref: "#/components/schemas/street_post_directional_abbreviation"
        street_pre_directional_abbreviation:
          $ref: "#/components/schemas/street_pre_directional_abbreviation"
        street_suffix_abbreviation:
          $ref: "#/components/schemas/street_suffix_abbreviation"
        update_key_number:
          $ref: "#/components/schemas/update_key_number"
        urbanization_city_state_key:
          $ref: "#/components/schemas/urbanization_city_state_key"
        zip_classification_code:
          $ref: "#/components/schemas/zip_classification_code"
        zip_code:
          $ref: "#/components/schemas/zip_code"
        zip_plus_4_code:
          $ref: "#/components/schemas/zip_plus_4_code"
      required:
        - id
        - dataset
        - country
        - country_iso
        - country_iso_2
        - language
        - primary_number
        - secondary_number
        - plus_4_code
        - line_1
        - line_2
        - last_line
        - zip_code
        - zip_plus_4_code
        - update_key_number
        - record_type_code
        - carrier_route_id
        - street_pre_directional_abbreviation
        - street_name
        - street_suffix_abbreviation
        - street_post_directional_abbreviation
        - building_or_firm_name
        - address_secondary_abbreviation
        - base_alternate_code
        - lacs_status_indicator
        - government_building_indicator
        - state_abbreviation
        - state
        - municipality_city_state_key
        - urbanization_city_state_key
        - preferred_last_line_city_state_key
        - county
        - city
        - city_abbreviation
        - preferred_city
        - city_state_name_facility_code
        - zip_classification_code
        - city_state_mailing_name_indicator
        - carrier_route_rate_sortation
        - finance_number
        - congressional_district_number
        - county_number
      title: United States Postal Service Address
    WelshPafAddress:
      allOf:
        - $ref: "#/components/schemas/PafBase"
        - properties:
            country:
              enum:
                - Wales
            country_iso:
              enum:
                - GBR
            country_iso_2:
              enum:
                - GB
            dataset:
              enum:
                - pafw
            language:
              enum:
                - cy
          type: object
      description: Welsh language alternative for a PAF Address
      title: Welsh PAF Address
    address_secondary_abbreviation:
      description: |-
        A descriptive code used to identify the type of address secondary range information in the Address Secondary Range field. 
        This code may be useful in address matching, e.g., the secondary address numbers may indicate apartment, suite, or trailer numbers.
      title: Address Secondary Abbreviation
      type: string
    base_alternate_code:
      description: |-
        Code that specifies whether a record is a base (preferred) or alternate record. 
        Base records (represented as "B") can represent a range of addresses or an individual address, such as a firm record, while alternate records (represented as "A") are individual delivery points. Base records are generally preferred over alternate records.
        Government deliveries will only be listed on alternate records with the appropriate government building indicator (federal, state, or city) set.
      enum:
        - A
        - B
        - ""
      title: Base Alternate Code
      type: string
    building_or_firm_name:
      description: |-
        The name of a company, building, apartment complex, shopping center, or other distinguishing secondary address information.
        This field is normally used with firm and highrise records but may also contain literals such as “Postmaster” or “United States Postal Service.”
      example: POSTMASTER
      title: Building or Firm Name
      type: string
    carrier_route_id:
      description: |-
        A 4 character ID identifying the postal route for the address.
        The first character indicates the route type. Specifically:
        - "B" indicates PO Box
        - "H" indicates highway
        - "C" indicates city
        - "G" indicates general
        - "R" indicates rural
      example: R012
      title: Carrier Route ID
      type: string
    carrier_route_rate_sortation:
      description: Identifies where automation Carrier Route rates are available and where the commingling of automation and non-automation mail, including Enhanced Carrier Routes and 5-digit presort, on the same pallet or in the same container is allowed.
      title: Carrier Route Rate Sortation and Merged 5-Digit Indicator
      type: string
    city:
      description: A valid city name for mailing purposes; appears in the last line of an address on a mail piece.
      example: HOLTSVILLE
      title: City Name
      type: string
    city_abbreviation:
      description: A standard 13-character abbreviation for a city/state name. This field is only used for names that are greater than 13 characters in length and have a city/state mailing name indicator of "Y." If the field is longer than 13 characters and the city/state mailing name indicator is "N," the field will be blank.
      example: W TOWNSHEND
      title: City State Name Abbreviation
      type: string
    city_state_mailing_name_indicator:
      description: |-
        Specifies whether or not the city state name can be used as a last line of address on a mail piece.
        - "Y = City/state name is a USPS-approved mailing name."
        - "N = City/state name is not approved for mailing purposes."
      title: City State Mailing Name Indicator
      type: string
    city_state_name_facility_code:
      description: |-
        The type of locale identified in the city/state name. The facility may be a USPS facility, such as a post office, station, or branch, or it may be a non-postal place name. City/state name facility codes include the following:
        - B = Branch
        - C = Community post office (CPO)
        - N = Non-postal community name, former USPS facility, or place name
        - P = Post Office
        - S = Station
        - U = Urbanization
      enum:
        - B
        - C
        - N
        - P
        - S
        - U
        - Y
        - ""
      title: City State Name Facility Code
      type: string
    congressional_district_number:
      description: A standard value identifying a geographic area within the United States served by a member of the U.S. House of Representatives. If Army/Air Force (APO), Fleet Post Office (FPO), or Diplomatic/Defense Post Office (DPO), this field will be blank. If there is only one member of Congress within a state, the code will be "AL" (at large).
      oneOf:
        - description: Empty string `""` if not available
          type: string
        - description: Congressional district number
          example: 6
          type: number
      title: Congressional District Number
    county:
      description: The name of the county or parish in which the 5-digit ZIP Code resides. If APO/FPO/DPO, then the county name will be blank.
      example: Suffolk
      title: County Name
      type: string
    county_number:
      description: The Federal Information Processing Standard (FIPS) code assigned to a given county or parish within a state. In Alaska, it identifies a region within the state. If APO/FPO/DPO, and the record type is “S,” “H,” or “F,” the county number will be blank.
      oneOf:
        - description: Empty string `""` if not available
          type: string
        - description: FIPS code
          example: 53
          type: number
      title: County Number
    ecad:
      $ref: "#/components/schemas/EcadAddress"
    ecaf:
      $ref: "#/components/schemas/EcafAddress"
    finance_number:
      description: A code assigned to Postal Service facilities (primarily Post Offices) to collect cost and statistical data and compile revenue and expense data.
      oneOf:
        - description: Empty string `""` if not available
          type: string
        - description: Finance Number
          example: 351560
          type: number
      title: Finance Number
    geonames:
      $ref: "#/components/schemas/GeonamesPlace"
    government_building_indicator:
      description: |-
        An alphabetic value that identifies the type of government agency at the delivery point and/or whether a firm is the only delivery at an address. For this purpose, "address" is defined as the complete delivery line (e.g., complete street address and, if included as part of the firm record, the secondary abbreviation and/or address secondary number).
        - A = City government building—alternates only
        - B = Federal government building—alternates only
        - C = State government building—alternates only
        - D = Firm only—base and alternates
        - E = City government building and firm only—alternates only
        - F = Federal government building and firm only—alternates only
        - G = State government building and firm only—alternates only
      enum:
        - ""
        - A
        - B
        - C
        - D
        - E
        - F
        - G
      title: Government Building Indicator
      type: string
    lacs_status_indicator:
      description: |-
        The Locatable Address Conversion Service (LACS) indicator describes records that have been converted to the LACS system (a product/system in a different USPS® product line that allows mailers to identify and convert a rural route address to a city-style address). Rural route and some city addresses are being modified to city-style addresses so that emergency services (e.g., ambulances, police) can find these addresses more efficiently.
        - L = LACS address: The old (usually rural-route) address that has been converted for the LACS system.
        - Blank = Not applicable
      enum:
        - ""
        - L
      title: LACS Status Indicator
      type: string
    last_line:
      description: Last line of the address comprising of city, state, zip code and zip+4
      example: Greenwich CT 06830-1234
      title: Last Line
      type: string
    line_1:
      description: The primary delivery line (usually the street address) of the address.
      example: 12 Armstrong Ct Apt 12
      title: First Address Line
      type: string
    line_2:
      description: Secondary delivery line of the address. Typically populated if the first line is the firm or building name.
      example: 9450 Pinecroft Dr
      title: Second Address Line
      type: string
    municipality_city_state_key:
      description: Municipality City State Key. Currently blank.
      title: Municipality City State Key
      type: string
    paf_administrative_county:
      description: |-
        The current administrative county to which the postcode has been assigned.

        A Unitary Authority name, where one is present. If there is no Unitary Authority, the County name is used. This information is not static, because County boundaries may change due to administrative changes. Data

        source: ONS
      example: ""
      title: Administrative County
      type: string
    paf_building_name:
      description: |-
        Name of residential or commercial premise. 

        Examples:
          - The Manor
          - 1-2
          - A
          - 12A
          - K
          - Victoria House
      example: ""
      maxLength: 50
      title: Building Name
      type: string
    paf_building_number:
      description: Number to identify premise on a thoroughfare or dependant thoroughfare.
      example: "10"
      maxLength: 4
      title: Building Number
      type: string
    paf_country:
      description: |2
          Full country names (ISO 3166)
      example: England
      title: Country
      type: string
    paf_country_iso:
      description: |2
          3 letter country code (ISO 3166-1)
      title: ISO Country Code (3)
      type: string
    paf_country_iso_2:
      description: |2
         2 letter country code (ISO 3166-1)
      title: ISO Country Code (2)
      type: string
    paf_county:
      description: Since postal, administrative or traditional counties may not apply to some addresses, the county field is designed to return whatever county data is available. Normally, the postal county is returned. If this is not present, the county field will fall back to the administrative county. If the administrative county is also not present, the county field will fall back to the traditional county. May be empty in cases where no administrative, postal or traditional county present.
      example: London
      title: County
      type: string
    paf_dataset:
      description: Indicates the provenance of an address
      title: Dataset
      type: string
    paf_delivery_point_suffix:
      description: A unique Royal Mail 2-character code (the first numeric & the second alphabetical), which, when added to the Postcode, enables each live Delivery Point to be uniquely identified. Once the Delivery Point is deleted from PAF the DPS may be reused (although they aren’t reused until all remaining Delivery Points in the range have been allocated). The DPS for a Large User is always '1A' as each Large User has its own Postcode.
      example: 1A
      title: Delivery Point Suffix
      type: string
    paf_department_name:
      description: Used to supplment Organisation Name to identify a deparment within the organisation.
      example: ""
      maxLength: 60
      title: Department Name
      type: string
    paf_dependant_locality:
      description: When the same thoroughfare name reoccurs in a Post town, it may not be possible to make it dependant on a dependant thoroughfare. In this case the thoroughfare is dependant on a locality. For example if we want to find 1 Back Lane in Huddersfield we see that there are three.
      example: ""
      maxLength: 35
      title: Dependant Locality
      type: string
    paf_dependant_thoroughfare:
      description: Used to supplement thoroughfare. When a thoroughfare name is used twice in the same Post Town, the dependant thoroughfare is added to uniquely indentify a delivery point.
      example: ""
      maxLength: 80
      title: Dependant Thoroughfare
      type: string
    paf_district:
      description: The current district/unitary authority to which the postcode has been assigned.
      example: Westminster
      title: District
      type: string
    paf_double_dependant_locality:
      description: Used to supplement Dependant Locality. A Double Dependant Locality supplied along with a Dependant Locality if the Dependant Locality exists twice in the same locality.
      example: ""
      maxLength: 35
      title: Double Dependant Locality
      type: string
    paf_language:
      description: |
        Language represented by 2 letter ISO Code (639-1)
      title: Language
      type: string
    paf_line1:
      description: First Address Line. Often contains premise and thoroughfare information. In the case of a commercial premise, the first line is always the full name of the registered organisation. Never empty.
      example: Prime Minister &amp; First Lord of Treasury
      title: Line 1
      type: string
    paf_line2:
      description: Second Address Line. Often contains thoroughfare and locality information. May be empty
      example: 10 Downing Street
      title: Line 2
      type: string
    paf_line3:
      description: Third address line. May be empty.
      example: ""
      title: Line 3
      type: string
    paf_organisation_name:
      description: Used to supplment Organisation Name to identify a deparment within the organisation
      example: Prime Minister &amp; First Lord Of The Treasury
      maxLength: 60
      title: Organisation Name
      type: string
    paf_pobox:
      description: When the PO Box Number field is populated it will contain PO BOX nnnnnn where n represents the PO Box number. Note that the PO Box details can occasionally consist of a combination of numbers and letters. PO Box Numbers are only allocated to Large Users.
      example: "100"
      maxLength: 6
      title: PO Box
      type: string
    paf_post_town:
      description: A Post Town is mandatory for delivery of mail to a Delivery Point. This is not necessarily the nearest town geographically, but a routing instruction to the Royal Mail delivery office sorting mail for that Delivery Point. A Post Town will always be present in every address, and for some Localities the Post Town will be the only locality element present.
      example: London
      maxLength: 30
      title: Post Town
      type: string
    paf_postal_county:
      description: Postal counties were used for the distribution of mail before the Postcode system was introduced in the 1970s. The Former Postal County was the Administrative County at the time. This data rarely changes. May be empty.
      example: London
      title: Postal County
      type: string
    paf_postcode:
      description: Correctly formatted postcode. Capitalised and spaced.
      example: SW1A 2AA
      maxLength: 8
      minLength: 6
      title: Postcode
      type: string
    paf_postcode_inward:
      description: |-
        The second part of a postcode is known as the inward code. e.g. The inward code of ID1 1QD is 1QD.

        The number identifies the sector in the postal district. The number is followed by 2 letters. The letters then define one or more properties in that sector.
      example: 2AA
      maxLength: 3
      minLength: 3
      title: Postcode Inward
      type: string
    paf_postcode_outward:
      description: The first part of a postcode is known as the outward code. e.g. The outward code of ID1 1QD is ID1. Enables mail to be sorted to the correct local area for delivery. This part of the code contains the area and the district to which the mail is to be delivered, e.g. ‘PO1’, ‘SW1A’ or ‘B23’.
      example: SW1A
      maxLength: 4
      minLength: 2
      title: Postcode Outward
      type: string
    paf_postcode_type:
      description: |-
        This indicates the type of user. It can only take the values 'S' or 'L' indicating small or large respectively. Large User Postcodes. These are assigned to one single address either due to the large volume of mail received at that address, or because a PO Box or Selectapost service has been set up. Small User Postcodes. These identify a group of Delivery Points.

        On average there are 19 Delivery Points per Postcode. However this can vary between 1 and, in some cases, 100. There will never be more than 100 Delivery Points on a Postcode.
      enum:
        - S
        - L
        - ""
      title: Postcode Type
      type: string
    paf_premise:
      description: A pre-computed string which sensibly combines building_number, building_name and sub_building_name. building_number, building_name and sub_building_name represent raw data from Royal Mail's and can be difficult to parse if you are unaware of how the Postcode Address File premise fields work together. For this reason, we also provide a pre-computed premise field which intelligently gathers these points into a single, simple premise string. This field is ideal if you want to pull premise information and thoroughfare information separately instead of using our address lines data.
      example: "10"
      maxLength: 84
      title: Premise
      type: string
    paf_su_organisation_indicator:
      description: Small User Organisation Indicator can have the values 'Y' or space. A value of 'Y' indicates that a Small User Organisation is present at this address.
      example: Y
      title: Small User Organisation Indicator
      type: string
    paf_sub_building_name:
      description: When a premise is split into individual units such as flats, apartments or business units. Cannot be present without either building_name or building_number. E.g. Flat 1, A, 10B
      example: Flat 1
      maxLength: 30
      title: Sub-Building Name
      type: string
    paf_thoroughfare:
      description: Also known as the street or road name. In general each Thoroughfare Name will have a separate Postcode. Longer Thoroughfares with high number ranges often have multiple Postcodes covering the entire length of the road, with breaks at suitable points e.g. junctions or natural breaks in the road.
      example: Downing Street
      maxLength: 80
      title: Thoroughfare
      type: string
    paf_traditional_county:
      description: Traditional counties are provided by the Association of British Counties. It is historical data, and can date from the 1800s. May be empty.
      example: Greater London
      title: Traditional County
      type: string
    paf_udprn:
      description: |-
        UDPRN stands for ‘Unique Delivery Point Reference Number’. Royal Mail assigns a unique UDPRN code for each premise on PAF. Simple, unique reference number for each Delivery Point. Unlikely to be reused when an address expires.

        Up to 8-digit numeric code.

        A new UDPRN is automatically assigned to each new Delivery Point added to PAF.
      example: 23747771
      format: int32
      title: Unique Delivery Point Reference Number (UDPRN)
      type: integer
    paf_umprn:
      description: |-
        A small minority of individual premises (as identified by a UDPRN) may have multiple occupants behind the same letterbox. These are known as Multiple Residence occupants and can be queried via the Multiple Residence dataset. Simple, unique reference number for each Multiple Residence occupant.

        Note: this will be an empty string `""` when not used.
      oneOf:
        - description: If premise is not multiple occupancy, this will be an empty string
          type: string
        - description: If premise is multiple occupancy, this will be an integer
          example: 983729
          maximum: 99999999
          minimum: 0
          type: number
      title: UMPRN
    paf_uprn:
      description: |-
        UPRN stands for Unique Property Reference Number and is maintained by the Ordnance Survey (OS). Local governments in the UK have allocated a unique number for each land or property.

        Up to 12 digits in length.

        Multiple Residence premises currently share the same UPRN as the parent premise.

        May not be available for a small number of Great Britain addresses due to longer update cycles for Ordnance Survey's AddressBase datasets. Returns empty string "" in these instances.

        Although UPRN takes an integer format, we encode and transmit this data as strings. As a 12 digit number, the UPRN can exceed the maximum safe integer `Number.MAX_SAFE_INTEGER` in most browsers causing this datapoint to be corrupted.

        Take special care when storing UPRN. As a 12 digit identifier, you will need 64 bits to encode every possible UPRN value. This means applications like Excel will corrupt cells containing UPRN values.
      title: Unique Property Reference Number
      type: string
    paf_ward:
      description: The current administrative/electoral area to which the postcode has been assigned. May be empty for a small number of addresses.
      example: St. James'
      title: Ward
      type: string
    place_country_iso:
      description: |2
          3 letter country code (ISO 3166-1)
      example: GBR
      title: Country
      type: string
    place_descriptive_name:
      description: |
        Longer form description of the place.
      example: London, United Kingdom
      title: Descriptive Place Name
      type: string
    place_id:
      description: |
        Unique identifier for place
      example: geonames_5324
      title: ID
      type: string
    place_name:
      description: |
        Place name
      example: London
      title: Place Name
      type: string
    plus_4_code:
      description: 4 digit ZIP add-on code.
      example: "1234"
      title: Plus 4 Code
      type: string
    preferred_city:
      description: Field that contains the default preferred or alternate preferred last-line name for a ZIP Code.
      example: AGUADA
      title: Preferred Last Line City State Name
      type: string
    preferred_last_line_city_state_key:
      description: In the Carrier Route, Five-Digit ZIP Code, Delivery Statistics, and ZIP + 4 products, an index to the City State product record that provides the preferred last-line name for this address range. In the City State product, the preferred last line city/state key contains the key value of a City State product record that has the default preferred or alternate preferred last-line key for a given ZIP Code.
      example: V13916
      title: Preferred Last Line City State Key
      type: string
    primary_number:
      description: A house, rural route, contract box, or Post Office Box number. The numeric or alphanumeric component of an address preceding the street name. Often referred to as house number.
      example: A298
      title: Primary Number
      type: string
    record_type_code:
      description: An alphabetic value that identifies the type of data in the record. - G = General delivery (5-Digit ZIP, ZIP + 4, and Carrier Route products) - H = High-rise (ZIP + 4 only) - F = Firm (ZIP + 4 only) - S = Street (5-Digit ZIP, ZIP + 4, and Carrier Route products) - P = PO Box (5-Digit ZIP, ZIP + 4, and Carrier Route products) - R = Rural route/contract (5-Digit ZIP, ZIP + 4, and Carrier Route products) - M = Multi-carrier (Carrier Route product only)
      enum:
        - G
        - H
        - F
        - S
        - P
        - R
        - M
        - ""
      title: Record Type Code
      type: string
    secondary_number:
      description: Number of the sub unit, apartment, suite etc
      example: 123A
      title: Secondary Number
      type: string
    state:
      description: Full name of a state, U.S. territory, or armed forces ZIP Code designation.
      example: New York
      title: State
      type: string
    state_abbreviation:
      description: A 2-character abbreviation for the name of a state, U.S. territory, or armed forces ZIP Code designation. If APO/FPO/DPO, then the state abbreviation will be “AA,” “AE,” or “AP.”
      example: NY
      title: State Abbreviation
      type: string
    street_name:
      description: The official name of a street as assigned by a local governing authority. The Street Name field contains only the street name and does not include directionals (EAST, WEST, etc.) or suffixes (ST, DR, BLVD, etc.). This element may also contain literals, such as PO BOX, GENERAL DELIVERY, USS, PSC, or UNIT.
      example: GOSHEN
      title: Street Name
      type: string
    street_post_directional_abbreviation:
      description: A geographic direction that follows the street name.
      title: Street Post Directional Abbreviation
      type: string
    street_pre_directional_abbreviation:
      description: A geographic direction that precedes the street name.
      title: Street Pre-Directional Abbreviation
      type: string
    street_suffix_abbreviation:
      description: "Code that is the standard USPS abbreviation for the trailing designator in a street address. "
      example: ST
      title: Street Suffix Abbreviation
      type: string
    update_key_number:
      description: Field that contains a number that uniquely identifies a record; used to identify the base record to which an add or delete transaction is being directed. The Update Key Number field is used only when applying transactions to the base file; it is not used in address matching and remains fixed for the life of the record. The field is alphanumeric and consists of the database segment code (V1, V2, W1, W2, X1, X2, Y1, Y2, Z1, or Z2) and eight characters containing an alphanumeric value ranging from 00000001 to AAAAAAAA.
      example: "00000001"
      title: Update Key Number
      type: string
    urbanization_city_state_key:
      description: An index to the City State file that provides the urbanization name for this delivery range.
      example: V18475
      title: Urbanization City State Key
      type: string
    usps_country:
      description: |2
          Full country names (ISO 3166)
      enum:
        - United States
        - Guam
        - Puerto Rico
      title: Country
      type: string
    usps_country_iso:
      description: |2
          3 letter country code (ISO 3166-1)
      enum:
        - USA
        - PRI
        - GUM
      title: ISO Country Code (3)
      type: string
    usps_country_iso_2:
      description: |2
         2 letter country code (ISO 3166-1)
      enum:
        - US
        - PR
        - GU
      title: ISO Country Code (2)
      type: string
    usps_dataset:
      description: Identifies the address as sourced from USPS
      enum:
        - usps
      title: USA Dataset
      type: string
    usps_language:
      description: |
        Language represented by 2 letter ISO Code (639-1)
      enum:
        - en
      title: Language
      type: string
    zip_classification_code:
      description: |-
        A field that describes the type of ZIP area that a 5-digit ZIP Code serves, e.g., a single educational institution, post office boxes only, or a single address that has unusually high mail volume or many different addresses.
         - M = Military ZIP Code
         - P = ZIP Code having only Post Office Boxes
         - U = Unique ZIP Code (ZIP assigned to a single organization)
         - Blank = Standard ZIP with many addresses assigned to it
      enum:
        - ""
        - M
        - P
        - U
      title: ZIP Classification Code
      type: string
    zip_code:
      description: "A 5-digit code that identifies a specific geographic delivery area. ZIP Codes can represent an area within a state, or a single building or company that has a very high mail volume. "
      example: "1234"
      title: ZIP Code
      type: string
    zip_plus_4_code:
      description: Nine-digit code that identifies a small geographic delivery area that is serviceable by a single carrier; appears in the last line of the address on a mail piece.
      example: 12345-6789
      title: ZIP + 4 Code
      type: string
x-tagGroups:
  - name: Address Search
    tags:
      - Address Search
      - UK
  - name: Place Search
    tags:
      - Place Search
  - name: Management
    tags:
      - Keys
      - Licensees
      - Configs
      - Emails
      - Phone Numbers
  - name: Models
    tags:
      - suggestion
      - usps_address
      - uk_address
      - ab_address
      - ecaf_address
      - ecad_address
      - geonames_place
