openapi: 3.0.3 info: version: 4.0.0 license: name: AGPLv3 url: https://opensource.org/licenses/AGPL-3.0 title: API Reference termsOfService: https://terms.ideal-postcodes.co.uk description: | ## Getting Started 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. ## 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. ## 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. | contact: email: support@ideal-postcodes.co.uk name: Support url: https://ideal-postcodes.co.uk/support servers: - url: https://api.ideal-postcodes.co.uk/v1 description: API Server variables: {} tags: - name: Address Search description: Global address autocomplete, for search-as-you-type - name: Place Search description: Global places search to identify geographical names and places - name: UK description: UK Address and Postcode Search - name: Keys description: Monitor and manage API Keys - name: Licensees 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: Configs 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: suggestion x-displayName: Address Suggestion 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. - name: usps_address x-displayName: US Address description: | Standard US Address format as reported by USPS. - name: uk_address x-displayName: UK 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. - name: ecaf_address x-displayName: IE Address description: | Standard Republic of Ireland Address format as reported by the Eircode ECAF file. - name: ecad_address x-displayName: IE Address (ECAD) description: | ECAF file including additional data for each address. - name: ab_address x-displayName: AddressBase Core description: | AddressBase Core Address. An alternative to UK PAF dataset from Ordnance Survey. Please contact us to have this enabled on your account. - name: geonames_place x-displayName: GeoNames Place description: | GeoNames place record externalDocs: description: More on our APIs, libraries with guides and examples url: https://docs.ideal-postcodes.co.uk paths: /postcodes/{postcode}: get: tags: - UK summary: Lookup Postcode operationId: Postcodes 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. parameters: - name: postcode in: path description: Postcode to retrieve required: true style: simple explode: false example: SW1A 2AA schema: type: string - $ref: '#/components/parameters/ApiKeyParam' - $ref: '#/components/parameters/FilterParam' - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/TagsParam' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PostcodeResponse' examples: Postcode Found: value: result: - postcode: SW1A 2AA postcode_inward: 2AA postcode_outward: SW1A post_town: London dependant_locality: '' double_dependant_locality: '' thoroughfare: Downing Street dependant_thoroughfare: '' building_number: '10' building_name: '' sub_building_name: '' po_box: '' department_name: '' organisation_name: Prime Minister & First Lord Of The Treasury udprn: 23747771 postcode_type: L su_organisation_indicator: '' delivery_point_suffix: 1A line_1: Prime Minister & First Lord Of The Treasury line_2: 10 Downing Street line_3: '' premise: '10' longitude: -0.12767 latitude: 51.503541 eastings: 530047 northings: 179951 country: England traditional_county: Greater London administrative_county: '' postal_county: London county: London district: Westminster ward: St. James's uprn: '100023336956' id: paf_23747771 country_iso: GBR country_iso_2: GB county_code: '' language: en umprn: '' dataset: paf code: 2000 message: Success limit: 100 page: 0 total: 1 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '404': description: Postcode Not Found content: application/json: schema: $ref: '#/components/schemas/PostcodeNotFoundResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/postcodes/SW1A2AA?api_key=iddqd - lang: cURL label: CLI source: | curl -G -k \ --url 'https://api.ideal-postcodes.co.uk/v1/postcodes/SW1A2AA' \ --d "api_key=iddqd" /udprn/{udprn}: get: tags: - UK summary: Retrieve by UDPRN operationId: UDPRN 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. parameters: - name: udprn in: path description: UDPRN to be retrieved required: true style: simple explode: false schema: type: string - $ref: '#/components/parameters/ApiKeyParam' - $ref: '#/components/parameters/FilterParam' responses: '200': description: Success headers: {} content: application/json: schema: $ref: '#/components/schemas/UDPRNResponse' examples: Valid UDPRN: value: result: postcode: SW1A 2AA postcode_inward: 2AA postcode_outward: SW1A post_town: London dependant_locality: '' double_dependant_locality: '' thoroughfare: Downing Street dependant_thoroughfare: '' building_number: '10' building_name: '' sub_building_name: '' po_box: '' department_name: '' organisation_name: Prime Minister & First Lord Of The Treasury udprn: 23747771 postcode_type: L su_organisation_indicator: '' delivery_point_suffix: 1A line_1: Prime Minister & First Lord Of The Treasury line_2: 10 Downing Street line_3: '' premise: '10' longitude: -0.12767 latitude: 51.503541 eastings: 530047 northings: 179951 country: England traditional_county: Greater London administrative_county: '' postal_county: London county: London district: Westminster ward: St. James's uprn: '100023336956' id: paf_23747771 country_iso: GBR country_iso_2: GB county_code: '' language: en umprn: '' dataset: paf code: 2000 message: Success '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/udprn/0?api_key=iddqd - lang: cURL label: CLI source: | curl -k -G https://api.ideal-postcodes.co.uk/v1/udprn/0 \ -d "api_key=iddqd" /umprn/{umprn}: get: tags: - UK summary: Retrieve by UMPRN operationId: UMPRN 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. parameters: - name: umprn in: path description: UMPRN to be retrieved required: true style: simple explode: false schema: type: string - $ref: '#/components/parameters/ApiKeyParam' - $ref: '#/components/parameters/FilterParam' responses: '200': description: Success headers: {} content: application/json: schema: $ref: '#/components/schemas/UMPRNResponse' examples: Valid UMPRN: value: result: postcode: CV4 7AL postcode_inward: 7AL postcode_outward: CV4 post_town: Coventry dependant_locality: '' double_dependant_locality: '' thoroughfare: Gibbet Hill Road dependant_thoroughfare: '' building_number: '' building_name: Block 1 Arthur Vick sub_building_name: Room 249a po_box: '' department_name: '' organisation_name: '' udprn: 5770157 postcode_type: S su_organisation_indicator: '' delivery_point_suffix: 1A line_1: Room 249a, Block 1 Arthur Vick line_2: Gibbet Hill Road line_3: '' premise: Room 249a, Block 1 Arthur Vick longitude: -1.5648072 latitude: 52.3858227 eastings: 429716 northings: 276509 country: England traditional_county: Warwickshire administrative_county: '' postal_county: West Midlands county: West Midlands district: Coventry ward: Wainbody uprn: '200001572050' id: mr_50906058 country_iso: GBR country_iso_2: GB county_code: '' language: en umprn: 50906058 dataset: mr code: 2000 message: Success '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/umprn/0?api_key=iddqdmr - lang: cURL label: CLI source: | curl -k -G https://api.ideal-postcodes.co.uk/v1/umprn/0 \ -d "api_key=iddqdmr" /keys/{key}: get: tags: - Keys summary: Availability operationId: KeyAvailability description: | Returns public information on your API Key. This endpoint can be used for the following: - Determine if the key is currently useable via the `available` property - Determine available contexts for a an API Key - Identify the currently likely context of a user given their location You may pass both API Keys (beginning `ak_`) and Sub-licensed Keys (beginning `sl_`). parameters: - $ref: '#/components/parameters/ApiKeyPathParam' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ApiKeyResponse' '404': description: Invalid Key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /keys/{key}/details: get: tags: - Keys summary: Details operationId: KeyDetails description: | Returns private data on the key including remaining lookups, available datasets and usage limits. parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/UserTokenParam' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ApiKeyDetailsResponse' '401': description: Unauthorised content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' deprecated: false put: tags: - Keys summary: Update Details description: Update API Key Details operationId: UpdateKeyDetails parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/UserTokenParam' requestBody: content: application/json: schema: $ref: '#/components/schemas/ApiKeyDetailsEditable' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ApiKeyDetailsResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorised content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' /keys/{key}/usage: get: tags: - Keys summary: Usage Stats operationId: KeyUsage 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. If no `start` time is provided, the start time will be set to 21 days prior to the current time. If no `end` time is provided, the current time will be used. Append `tags` to scope the number of lookups to those with matching tag values. E.g. `tags=foo,bar` will only count transactions that match `foo` and `bar`. parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/StartParam' - $ref: '#/components/parameters/EndParam' - $ref: '#/components/parameters/TagsParam' - $ref: '#/components/parameters/LicenseeParam' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ApiKeyUsageResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/keys/iddqd/usage?user_token=my_secret_token - lang: cURL label: CLI source: | curl -k -G https://api.ideal-postcodes.co.uk/v1/keys/iddqd/usage \ -d "user_token=my_secret_token" /keys/{key}/lookups: get: tags: - Keys summary: Logs (CSV) operationId: KeyLogs 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. parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/StartParam' - $ref: '#/components/parameters/EndParam' - $ref: '#/components/parameters/LicenseeParam' responses: '200': description: Success 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: type: string description: Success '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/keys/iddqd/lookups?user_token=my_secret_token - lang: cURL label: CLI source: | curl -k -G https://api.ideal-postcodes.co.uk/v1/keys/iddqd/lookups \ -d "user_token=my_secret_token" /cleanse/addresses: post: tags: - UK summary: Cleanse Address 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: - $ref: '#/components/parameters/ApiKeyParam' - $ref: '#/components/parameters/TagsParam' requestBody: required: true content: application/json: schema: type: object required: - query properties: query: type: string description: | Freeform address input to cleanse example: 10 Downing Street, London, SW2A 2BN postcode: type: string description: | Optionally specify postal code for the address. example: SW1A 2BN post_town: type: string description: | Optionally specify the city or town of the address. For UK verifications, this should be the "post town" of the address. For USA verifications, this should be the city of the address. example: London county: type: string description: | Optionally specify the county or state of the address. For UK verifications, we recommend omitting this field as county data is unreliable. For USA verifications, this should be the state of the address. example: Kent responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CleanseResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '429': description: Rate Limited content: application/json: schema: $ref: '#/components/schemas/RateLimitedResponse' x-codeSamples: - lang: cURL label: CLI 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"}' /autocomplete/addresses: get: tags: - Address Search summary: Find Address description: | The Address Autocomplete API delivers address suggestions in order of relevance based on a provided query. It aids real-time address autofill implementations. Consider using our Address Autocomplete JavaScript libraries to add address lookup to a form in moments rather than interacting with this API directly. ## API Usage Implementing our Address Autocomplete API involves: 1. Fetch address suggestions with `/autocomplete/addresses` 2. Acquire the complete address using the ID from the suggestion Step 2 will decrement your lookup balance. Note that step 1 is not a free standalone resource. Integrations that consistently make autocomplete requests without a paid Step 2 request will be rate limited and then suspended. ## Query Filters Refine results by appending filters to your querystring, e.g., `postcode=sw1a2aa` for postcode `SW1A 2AA`. Invalid filters return an empty set without affecting your lookup count. To apply multiple filter terms, use a comma-separated list, e.g., `postcode_outward=e1,e2,e3` combines result sets for E1, E2, and E3. Unless otherwise specified, all filters support multiple terms. Combine filters by `AND` logic, for instance, `su_organisation_indicator=Y&postcode_area=n`. The maximum allowed filter terms is **10**. ## Address Bias Preface bias searches with `bias_` to boost certain address results. Unlike filters, biasing allows unmatched addresses to appear with lower priority. For example, use `bias_postcode_area=SW,SE` to favor addresses in the `SW` and `SE` postcode areas. Invalid bias terms have no effect. Multiple bias terms are allowed unless stated otherwise, with a combined maximum of **5**. ## Suggestion Format The suggestion format is subject to change. We recommend using the suggestion as-is to prevent potential integration issues. ## Rate Limiting and Cost The rate limit for the Autocomplete API is 3000 requests per 5 minutes. HTTP Headers inform about the current rate limit. Autocomplete API usage does not impact your balance, but resolving a suggestion to a full address requires a paid request. Autocomplete requests without subsequent paid requests may result in rate limitation or suspension. operationId: FindAddress parameters: - $ref: '#/components/parameters/ApiKeyParam' - name: query description: | **Address Query** The partial address string entered by the user to autocomplete. example: 10 downing street lo explode: false in: query schema: type: string maxLength: 150 style: form - $ref: '#/components/parameters/ContextParam' - $ref: '#/components/parameters/LimitParam' - $ref: '#/components/parameters/BiasLonLatParam' - $ref: '#/components/parameters/BiasIpParam' - $ref: '#/components/parameters/BoxParam' - $ref: '#/components/parameters/PostcodeOutwardParam' - $ref: '#/components/parameters/PostcodeParam' - $ref: '#/components/parameters/PostcodeAreaParam' - $ref: '#/components/parameters/PostcodeSectorParam' - $ref: '#/components/parameters/PostTownParam' - $ref: '#/components/parameters/UPRNParam' - $ref: '#/components/parameters/CountryParam' - $ref: '#/components/parameters/PostcodeTypeParam' - $ref: '#/components/parameters/SmallUserParam' - $ref: '#/components/parameters/BiasPostcodeOutwardParam' - $ref: '#/components/parameters/BiasPostcodeParam' - $ref: '#/components/parameters/BiasPostcodeAreaParam' - $ref: '#/components/parameters/BiasPostcodeSectorParam' - $ref: '#/components/parameters/BiasPosttownParam' - $ref: '#/components/parameters/BiasThoroughfareParam' - $ref: '#/components/parameters/BiasCountryParam' responses: '200': description: Success headers: X-RateLimit-Limit: description: The maximum number of requests that can be made in 5 minutes schema: type: number format: int32 X-RateLimit-Remaining: description: The remaining requests within the current rate limit window schema: type: number format: int32 X-RateLimit-Reset: description: | The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds. schema: type: number format: int32 content: application/json: schema: $ref: '#/components/schemas/AutocompleteResponse' examples: GBR: summary: Example response for GBR context value: result: hits: - id: paf_23747771 suggestion: Prime Minister & First Lord Of The Treasury, 10 Downing Street, London, SW1A udprn: 23747771 urls: udprn: /v1/udprn/23747771 - id: paf_26245117 suggestion: Flat 10, Downing Court, Grenville Street, London, WC1N udprn: 26245117 urls: udprn: /v1/udprn/26245117 code: 2000 message: Success USA: summary: Example response for USA context value: result: hits: - suggestion: 10 Downing St, Montpelier, VT, 05602 urls: {} id: usps_V210079628|10||3797 - suggestion: 10 Ten Downing St, Fountain Inn, SC, 29644 urls: {} id: usps_X219061579|10||5031 - suggestion: 10 Downing St Apt 1, Montpelier, VT, 05602 urls: {} id: usps_V210079629|10|1|3798 - suggestion: 2100 N Downing St Unit 10, Denver, CO, 80205 urls: {} id: usps_Z125260298|2100|10|5272 - suggestion: 10 S Downing St, Denver, CO, 80209 urls: {} id: usps_Z105732754|10||2411 - suggestion: 10 Downing St, Hollister, MO, 65672 urls: {} id: usps_W112200302|10||5568 - suggestion: 10 Downing St, Greensboro, NC, 27410 urls: {} id: usps_Y127860601|10||2448 - suggestion: 1 S Downing St Apt 10, Denver, CO, 80209 urls: {} id: usps_Z105731302|1|10|2440 - suggestion: 1560 N Downing St Apt 10, Denver, CO, 80218 urls: {} id: usps_Z122881416|1560|10|1538 - suggestion: 2202 N Downing St Apt 10, Denver, CO, 80205 urls: {} id: usps_Z122964113|2202|10|5264 code: 2000 message: Success '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses?api_key=iddqd&q=10%20downing - lang: cURL label: CLI 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: tags: - Address Search summary: Resolve Address operationId: ResolveAddress 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). parameters: - name: address in: path description: | **ID of address suggestion** ID of address suggestion provided by the API to fully resolve. required: true style: simple explode: false example: paf_23747771 schema: type: string - $ref: '#/components/parameters/ApiKeyParam' - $ref: '#/components/parameters/TagsParam' responses: '200': description: Success headers: {} content: application/json: schema: $ref: '#/components/schemas/GbrResolveAddressResponse' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses/paf_23747771/gbr?api_key=iddqd - lang: cURL label: CLI 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: tags: - Address Search summary: Retrieve Address operationId: RetrieveAddress 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). parameters: - name: address in: path description: | **ID of address suggestion** ID of address suggestion provided by the API to fully retrieve. required: true style: simple explode: false example: usps_V118834572|310||3191 schema: type: string - $ref: '#/components/parameters/ApiKeyParam' - $ref: '#/components/parameters/TagsParam' responses: '200': description: Success headers: {} content: application/json: schema: $ref: '#/components/schemas/UsaResolveAddressResponse' '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/autocomplete/addresses/usps_Z222446599|1||1101/usa?api_key=iddqd - lang: cURL label: CLI 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" /addresses: get: tags: - UK summary: Extract Addresses 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: - $ref: '#/components/parameters/ApiKeyParam' - name: query in: query description: Specifies the address you wish to query. style: form explode: false schema: type: string - $ref: '#/components/parameters/LimitParam' - $ref: '#/components/parameters/PageParam' - $ref: '#/components/parameters/FilterParam' - $ref: '#/components/parameters/AddressLongitudeParam' - $ref: '#/components/parameters/AddressLatitudeParam' - $ref: '#/components/parameters/PostcodeOutwardParam' - $ref: '#/components/parameters/PostcodeParam' - $ref: '#/components/parameters/PostcodeAreaParam' - $ref: '#/components/parameters/PostcodeSectorParam' - $ref: '#/components/parameters/PostTownParam' - $ref: '#/components/parameters/UPRNParam' - $ref: '#/components/parameters/CountryParam' - $ref: '#/components/parameters/PostcodeTypeParam' - $ref: '#/components/parameters/SmallUserParam' - $ref: '#/components/parameters/BoxParam' - $ref: '#/components/parameters/BiasPostcodeOutwardParam' - $ref: '#/components/parameters/BiasPostcodeParam' - $ref: '#/components/parameters/BiasPostcodeAreaParam' - $ref: '#/components/parameters/BiasPostcodeSectorParam' - $ref: '#/components/parameters/BiasPosttownParam' - $ref: '#/components/parameters/BiasThoroughfareParam' - $ref: '#/components/parameters/BiasCountryParam' - $ref: '#/components/parameters/BiasLonLatParam' - $ref: '#/components/parameters/TagsParam' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/AddressResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '404': description: Postcode Not Found content: application/json: schema: $ref: '#/components/schemas/PostcodeNotFoundResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/addresses?api_key=iddqd&query=10%20downing%20street%20london - lang: cURL label: CLI source: | curl -k -G 'https://api.ideal-postcodes.co.uk/v1/addresses' \ -d 'api_key=iddqd' \ --data-urlencode 'query=10 downing street london' /places: get: tags: - Place Search summary: Find Place 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 and Cost The rate limit for the Autocomplete API is 3000 requests per 5 minutes. HTTP Headers inform about the current rate limit. Autocomplete API usage does not impact your balance, but resolving a suggestion to a full address requires a paid request. Autocomplete requests without subsequent paid requests may result in rate limitation or suspension. operationId: FindPlace parameters: - $ref: '#/components/parameters/ApiKeyParam' - name: query in: query description: Specifies the place you wish to query. Query can be shortened to `q=` style: form explode: false schema: type: string allowReserved: true - $ref: '#/components/parameters/CountryIsoParam' - $ref: '#/components/parameters/BiasCountryIsoParam' - $ref: '#/components/parameters/BiasLonLatParam' - $ref: '#/components/parameters/BiasIpParam' responses: '200': description: Success headers: X-RateLimit-Limit: description: The maximum number of requests that can be made in 5 minutes schema: type: number format: int32 X-RateLimit-Remaining: description: The remaining requests within the current rate limit window schema: type: number format: int32 X-RateLimit-Reset: description: | The time when the rate limit window resets in Unix Time (seconds) or UTC Epoch seconds. schema: type: number format: int32 content: application/json: schema: $ref: '#/components/schemas/PlaceResponse' examples: Result: value: result: hits: - id: geonames_2643743 name: London descriptive_name: London, Greater London, England country_iso: GBR - id: geonames_4517009 name: London descriptive_name: London, Madison County, Ohio country_iso: USA - id: geonames_4298960 name: London descriptive_name: London, Laurel County, Kentucky country_iso: USA code: 2000 message: Success '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/places?api_key=ak_test&query=london - lang: cURL label: CLI source: | curl -k -G 'https://api.ideal-postcodes.co.uk/v1/places' \ -d 'api_key=ak_test' \ --data-urlencode 'query=london' /places/{place}: get: tags: - Place Search summary: Resolve Place operationId: ResolvePlace description: | Resolves a place autocompletion by its place ID. parameters: - name: place in: path description: ID of place suggestion required: true style: simple explode: false schema: type: string - $ref: '#/components/parameters/ApiKeyParam' - $ref: '#/components/parameters/TagsParam' responses: '200': description: Success headers: {} content: application/json: schema: $ref: '#/components/schemas/ResolvePlaceResponse' examples: Valid Place: value: result: id: geonames_2643743 dataset: geonames name: London descriptive_name: London, Greater London, England language: en longitude: -0.12574 latitude: 51.50853 country_iso: GBR native: admin1_code: ENG admin2_name: Greater London geonameid: 2643743 timezone: Europe/London latitude: 51.50853 language: en dem: 25 admin4_code: '' admin1_geonameid: 6269131 alternatenames: - ILondon - LON - Lakana - Landan - Landen - Ljondan - Llundain - Lodoni - Londain - Londan - Londar - Londe - Londen - Londin - Londinium - Londino - Londn - London - London osh - Londona - Londonas - Londoni - Londono - Londons - Londonu - Londra - Londres - Londrez - Londri - Londro - Londye - Londyn - Londýn - Lonn - Lontoo - Loundres - Luan GJon - Lun-tun - Lunden - Lundra - Lundun - Lundunir - Lundúnir - Lung-dung - Lunnainn - Lunnin - Lunnon - Luân Đôn - Lùn-tûn - Lùng-dŭng - Lûn-tun - Lākana - Lůndůn - Lọndọnu - Ranana - Rānana - ilantan - ladana - landan - landana - leondeon - lndn - london - londoni - lun dui - lun dun - lwndwn - lxndxn - rondon - Łondra - Λονδίνο - Лондан - Лондон - Лондон ош - Лондонъ - Лёндан - Լոնդոն - לאנדאן - לונדון - لأندأن - لندن - لوندون - لەندەن - ܠܘܢܕܘܢ - लंडन - लंदन - लण्डन - लन्डन् - लन्दन - লন্ডন - ਲੰਡਨ - લંડન - ଲ୍ଡନ - இலண்டன் - లండన్ - ಲಂಡನ್ - ലണ്ടൻ - ලන්ඩන් - ลอนดอน - ລອນດອນ - ལོན་ཊོན། - လန်ဒန်မြို့ - ლონდონი - ለንደን - ᎫᎴ ᏗᏍᎪᏂᎯᏱ - ロンドン - 伦敦 - 倫敦 - 런던 cc2: [] admin2_code: GLA modification_date: '2022-03-09T00:00:00.000Z' asciiname: London id: geonames_2643743 feature_code: PPLC country_iso: GBR longitude: -0.12574 elevation: null admin2_geonameid: 2648110 admin1_name: England population: '8961989' country_code: GB feature_class: P name: London admin3_code: '' dataset: geonames code: 2000 message: Success '404': description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/places/geonames_5353?api_key=ak_test - lang: cURL label: CLI source: | curl -k -G https://api.ideal-postcodes.co.uk/v1/places/geonames_5355?api_key=ak_test \ -d "api_key=ak_test" /keys/{key}/licensees: get: tags: - Licensees summary: List description: Returns a list of licensees for a key. operationId: ListLicensees parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - name: starting_after in: query description: Specify ID of the licensee after which you would like to list results style: form explode: false schema: type: integer format: int32 - $ref: '#/components/parameters/UserTokenParam' - $ref: '#/components/parameters/LimitParam' - name: query in: query description: Filter result by licensee name. Query can be shortened to `q=` style: form explode: false schema: type: string responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/LicenseesResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' post: tags: - Licensees summary: Create description: Create a licensee for the specified API Key. operationId: CreateLicensee parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/UserTokenParam' requestBody: content: application/json: schema: $ref: '#/components/schemas/LicenseeEditable' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/LicenseeResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' /keys/{key}/licensees/{licensee}: get: tags: - Licensees summary: Retrieve description: Returns licensee information as identified by the licensee key. operationId: RetrieveLicensee parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/LicenseePathParam' - $ref: '#/components/parameters/UserTokenParam' responses: '200': description: Success headers: {} content: application/json: schema: $ref: '#/components/schemas/LicenseeResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' delete: tags: - Licensees summary: Cancel 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: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/LicenseePathParam' - $ref: '#/components/parameters/UserTokenParam' responses: '200': description: Success content: application/json: schema: required: - result - code - message title: Licensee Delete Response type: object properties: result: type: object required: - deleted properties: deleted: type: number format: int32 example: 1 minimum: 0 code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' put: tags: - Licensees summary: Update description: Update Licensee operationId: UpdateLicensee parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/LicenseePathParam' - $ref: '#/components/parameters/UserTokenParam' requestBody: content: application/json: schema: $ref: '#/components/schemas/LicenseeEditable' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/LicenseeResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' /keys/{key}/configs: get: tags: - Configurations summary: List description: Lists configurations associated with a key operationId: ListConfigs parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/UserTokenParam' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ConfigsResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorized Request content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' post: tags: - Configurations summary: Create description: Create a configuration operationId: CreateConfig parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/UserTokenParam' requestBody: content: application/json: schema: $ref: '#/components/schemas/ConfigNewParam' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ConfigResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorized Request content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' /keys/{key}/configs/{config}: get: tags: - Configurations summary: Retrieve description: Retrieve configuration object by name operationId: RetrieveConfig parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/ConfigParam' responses: '200': description: Success headers: {} content: application/json: schema: $ref: '#/components/schemas/ConfigResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' delete: tags: - Configurations summary: Delete description: Permanently deletes a configuration object. operationId: DeleteConfig parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/ConfigParam' - $ref: '#/components/parameters/UserTokenParam' responses: '200': description: Success content: application/json: schema: title: Config Delete Response type: object required: - result - code - message properties: result: type: object required: - deleted properties: deleted: type: number format: int32 example: 1 minimum: 0 code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorized Request content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' post: tags: - Configurations summary: Update description: Updates configuration object operationId: UpdateConfig parameters: - $ref: '#/components/parameters/ApiKeyPathParam' - $ref: '#/components/parameters/ConfigParam' - $ref: '#/components/parameters/UserTokenParam' requestBody: content: application/json: schema: $ref: '#/components/schemas/ConfigUpdateParam' required: true responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/ConfigResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorized Request content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/NotFoundResponse' /emails: get: tags: - Emails summary: Email Validation description: | Query for and validate email addresses. operationId: EmailValidation parameters: - $ref: '#/components/parameters/ApiKeyParam' - name: query in: query description: Specifies the email address to validate required: true explode: false style: form schema: type: string allowReserved: true - $ref: '#/components/parameters/TagsParam' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/EmailResponse' examples: Valid Email: value: result: result: deliverable deliverable: true catchall: false free: false role: true disposable: false code: 2000 message: Success '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/emails?api_key=ak_test&query=foo@domain.com - lang: cURL label: CLI source: | curl -k -G 'https://api.ideal-postcodes.co.uk/v1/emails' \ -d 'api_key=iddqd' \ --data-urlencode 'query=foo@domain.com' /phone_numbers: get: tags: - Phone Numbers summary: Phone Number Validation description: | Query for and validate phone numbers. operationId: PhoneNumberValidation parameters: - $ref: '#/components/parameters/ApiKeyParam' - name: query in: query 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`. required: true explode: false style: form schema: type: string allowReserved: true - name: current_carrier in: query required: false description: | When set to `true` the current network of the phone number will be retrieved and populated. Note that this operation is potentially slow depending on the network and local conditions. explode: false style: form schema: type: string enum: - 'true' - $ref: '#/components/parameters/TagsParam' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/PhoneNumberResponse' examples: Valid Phone Number: value: result: valid: true national_format: 020 7112 8019 international_format: +44 20 7112 8019 iso_country: GBR iso_country_2: GB country: United Kingdom current_carrier: network_code: null name: Invomo Ltd country: GB network_type: landline original_carrier: network_code: null name: Invomo Ltd country: GB network_type: landline code: 2000 message: Success '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/UnauthorizedResponse' '429': description: Rate Limit Timeout content: application/json: schema: $ref: '#/components/schemas/BadRequestResponse' x-codeSamples: - lang: http label: URL source: | https://api.ideal-postcodes.co.uk/v1/phone_numbers?api_key=ak_test&query=02071128019 - lang: cURL label: CLI source: | curl -k -G 'https://api.ideal-postcodes.co.uk/v1/phone_numbers' \ -d 'api_key=iddqd' \ --data-urlencode 'query=02071128019' components: schemas: ecaf: $ref: '#/components/schemas/EcafAddress' ecad: $ref: '#/components/schemas/EcadAddress' geonames: $ref: '#/components/schemas/GeonamesPlace' here: $ref: '#/components/schemas/HereAddress' ID: title: ID type: string description: Global unique internally generated identifier for an address example: paf_8387729 paf_dataset: title: Dataset type: string description: Indicates the provenance of an address paf_country_iso: title: ISO Country Code (3) type: string description: |2 3 letter country code (ISO 3166-1) paf_country_iso_2: title: ISO Country Code (2) type: string description: |2 2 letter country code (ISO 3166-1) paf_country: title: Country type: string description: |2 Full country names (ISO 3166) example: England paf_language: title: Language type: string description: | Language represented by 2 letter ISO Code (639-1) paf_line1: title: Line 1 type: string 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 & First Lord of Treasury paf_line2: title: Line 2 type: string description: Second Address Line. Often contains thoroughfare and locality information. May be empty example: 10 Downing Street paf_line3: title: Line 3 type: string description: Third address line. May be empty. example: '' paf_post_town: maxLength: 30 type: string description: | **Filter by Town or City" 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 paf_postcode: title: Postcode type: string description: Correctly formatted postcode. Capitalised and spaced. maxLength: 8 minLength: 6 example: SW1A 2AA paf_county: title: County type: string 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 paf_uprn: title: Unique Property Reference Number type: string 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. paf_udprn: title: Unique Delivery Point Reference Number (UDPRN) type: integer format: int32 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 paf_umprn: title: 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: - type: string description: If premise is not multiple occupancy, this will be an empty string - type: number description: If premise is multiple occupancy, this will be an integer example: 983729 minimum: 0 maximum: 99999999 paf_postcode_outward: title: Postcode Outward type: string 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’. maxLength: 4 minLength: 2 example: SW1A paf_postcode_inward: title: Postcode Inward type: string 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. maxLength: 3 minLength: 3 example: 2AA paf_dependant_locality: title: Dependant Locality type: string 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. maxLength: 35 example: '' paf_double_dependant_locality: title: Double Dependant Locality type: string 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. maxLength: 35 example: '' paf_thoroughfare: title: Thoroughfare type: string 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. maxLength: 80 example: Downing Street paf_dependant_thoroughfare: title: Dependant Thoroughfare type: string 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. maxLength: 80 example: '' paf_building_number: title: Building Number type: string description: Number to identify premise on a thoroughfare or dependant thoroughfare. maxLength: 4 example: '10' paf_building_name: title: Building Name type: string description: |- Name of residential or commercial premise. Examples: - The Manor - 1-2 - A - 12A - K - Victoria House maxLength: 50 example: '' paf_sub_building_name: title: Sub-Building Name type: string 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 maxLength: 30 example: Flat 1 paf_pobox: title: PO Box type: string 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. maxLength: 6 example: '100' paf_department_name: title: Department Name type: string description: Used to supplment Organisation Name to identify a deparment within the organisation. maxLength: 60 example: '' paf_organisation_name: title: Organisation Name type: string description: Used to supplment Organisation Name to identify a deparment within the organisation maxLength: 60 example: Prime Minister & First Lord Of The Treasury paf_postcode_type: enum: - S - L - '' title: 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. paf_su_organisation_indicator: title: Small User Organisation Indicator type: string 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' paf_delivery_point_suffix: title: Delivery Point Suffix type: string 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 paf_premise: title: Premise type: string 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. maxLength: 84 example: '10' paf_administrative_county: title: Administrative County type: string 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: '' paf_postal_county: title: Postal County type: string 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 paf_traditional_county: title: Traditional County type: string 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 paf_district: title: District type: string description: The current district/unitary authority to which the postcode has been assigned. example: Westminster paf_ward: title: Ward type: string 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' Longitude: title: 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: - type: string description: Empty string `""` if not available - type: number description: Represents longitude example: 0.002823 minimum: -180 maximum: 180 Latitude: title: Longitude 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: - type: string description: Empty string `""` if not available - type: number description: Represents latitude example: 52.938278 minimum: -90 maximum: 90 Eastings: title: 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: - type: string description: Empty string `""` if not available - type: number description: Metres offset east from origin example: 9382 minimum: 0 maximum: 999999 Northings: title: 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: - type: string description: Empty string `""` if not available - type: number description: Metres offset north from origin example: 123932 minimum: 0 maximum: 999999 PafBase: 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 properties: id: $ref: '#/components/schemas/ID' dataset: $ref: '#/components/schemas/paf_dataset' country_iso: $ref: '#/components/schemas/paf_country_iso' country_iso_2: $ref: '#/components/schemas/paf_country_iso_2' country: $ref: '#/components/schemas/paf_country' language: $ref: '#/components/schemas/paf_language' line_1: $ref: '#/components/schemas/paf_line1' line_2: $ref: '#/components/schemas/paf_line2' line_3: $ref: '#/components/schemas/paf_line3' post_town: $ref: '#/components/schemas/paf_post_town' postcode: $ref: '#/components/schemas/paf_postcode' county: $ref: '#/components/schemas/paf_county' county_code: title: County Code type: string description: Short code representing the county or province. May be empty (`""`) example: '' uprn: $ref: '#/components/schemas/paf_uprn' udprn: $ref: '#/components/schemas/paf_udprn' umprn: $ref: '#/components/schemas/paf_umprn' postcode_outward: $ref: '#/components/schemas/paf_postcode_outward' postcode_inward: $ref: '#/components/schemas/paf_postcode_inward' dependant_locality: $ref: '#/components/schemas/paf_dependant_locality' double_dependant_locality: $ref: '#/components/schemas/paf_double_dependant_locality' thoroughfare: $ref: '#/components/schemas/paf_thoroughfare' dependant_thoroughfare: $ref: '#/components/schemas/paf_dependant_thoroughfare' building_number: $ref: '#/components/schemas/paf_building_number' building_name: $ref: '#/components/schemas/paf_building_name' sub_building_name: $ref: '#/components/schemas/paf_sub_building_name' po_box: $ref: '#/components/schemas/paf_pobox' department_name: $ref: '#/components/schemas/paf_department_name' organisation_name: $ref: '#/components/schemas/paf_organisation_name' postcode_type: $ref: '#/components/schemas/paf_postcode_type' su_organisation_indicator: $ref: '#/components/schemas/paf_su_organisation_indicator' delivery_point_suffix: $ref: '#/components/schemas/paf_delivery_point_suffix' premise: $ref: '#/components/schemas/paf_premise' administrative_county: $ref: '#/components/schemas/paf_administrative_county' postal_county: $ref: '#/components/schemas/paf_postal_county' traditional_county: $ref: '#/components/schemas/paf_traditional_county' district: $ref: '#/components/schemas/paf_district' ward: $ref: '#/components/schemas/paf_ward' longitude: $ref: '#/components/schemas/Longitude' latitude: $ref: '#/components/schemas/Latitude' eastings: $ref: '#/components/schemas/Eastings' northings: $ref: '#/components/schemas/Northings' PafAddress: title: Postcode Address File Address 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. allOf: - $ref: '#/components/schemas/PafBase' - type: object properties: country_iso: enum: - GBR - IMN - JEY - GGY dataset: type: string enum: - paf country_iso_2: enum: - GB - IM - JE - GG language: enum: - en country: enum: - England - Scotland - Wales - Northern Ireland - Jersey - Guernsey - Isle of Man MrAddress: title: Multiple Residence Address 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. allOf: - $ref: '#/components/schemas/PafBase' - type: object properties: dataset: enum: - mr country_iso: enum: - GBR - IMN - JEY - GGY country_iso_2: enum: - GB - IM - JE - GG language: enum: - en country: enum: - England - Scotland - Wales - Northern Ireland - Jersey - Guernsey - Isle of Man NybAddress: title: Not Yet Built Address description: |- A UK premise under construction and currently not occupied. This dataset is updated by Royal Mail on a monthly cadence. allOf: - $ref: '#/components/schemas/PafBase' - type: object properties: dataset: enum: - nyb country_iso: enum: - GBR - IMN - JEY - GGY country_iso_2: enum: - GB - IM - JE - GG language: enum: - en country: enum: - England - Scotland - Wales - Northern Ireland - Jersey - Guernsey - Isle of Man PafAliasAddress: title: PAF Alias Address 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. allOf: - $ref: '#/components/schemas/PafBase' - type: object properties: dataset: enum: - pafa country_iso: enum: - GBR - IMN - JEY - GGY country_iso_2: enum: - GB - IM - JE - GG language: enum: - en country: enum: - England - Scotland - Wales - Northern Ireland - Jersey - Guernsey - Isle of Man WelshPafAddress: title: Welsh PAF Address description: Welsh language alternative for a PAF Address allOf: - $ref: '#/components/schemas/PafBase' - type: object properties: dataset: enum: - pafw country_iso: enum: - GBR country_iso_2: enum: - GB language: enum: - cy country: enum: - Wales Language: title: Language type: string description: | Language represented by 2 letter ISO Code (639-1) enum: - en - ar - az - be - bg - bn - bs - ca - cs - cy - da - de - el - es - et - eu - fi - fo - fr - ga - gl - gn - he - hi - hr - hu - hy - id - is - it - ka - kk - km - kn - lt - lv - mk - mn - ms - mt - my - nl - 'no' - pl - pt - ro - ru - sk - sl - sq - sr - sv - ta - th - tr - uk - uz - vi - wa - zh AddressBaseCore: title: AddressBase Core description: Represents a GB address in Ordnance Survey's AddressBase Core dataset 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 properties: id: $ref: '#/components/schemas/ID' dataset: title: Dataset type: string description: Indicates the provenance of an address enum: - ab language: $ref: '#/components/schemas/Language' line_1: $ref: '#/components/schemas/paf_line1' line_2: $ref: '#/components/schemas/paf_line2' line_3: $ref: '#/components/schemas/paf_line3' premise: $ref: '#/components/schemas/paf_premise' uprn: title: UPRN type: string maxLength: 12 description: Unique Property Reference Number (UPRN) assigned by the LLPG Custodian or Ordnance Survey. udprn: title: UDPRN type: number maxLength: 8 description: Royal Mail's Unique Delivery Point Reference Number (UDPRN). parent_uprn: title: PARENT_UPRN type: string maxLength: 12 description: UPRN of the parent Record if a parent-child relationship exists. usrn: title: USRN type: number maxLength: 8 description: |- Unique Street Reference Number assigned by the Street Name and Numbering Custodian OR Ordnance Survey depending on the address record. toid: title: TOID type: string maxLength: 20 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. classification_code: title: Classification Code type: string maxLength: 4 description: A code that describes the classification of the address record to a maximum of a secondary level. eastings: title: Easting type: number maxLength: 8 multipleOf: 0.01 description: A value in metres defining the x location in accordance with the British National Grid. northings: title: Northing type: number maxLength: 9 multipleOf: 0.01 description: A value in metres defining the y location in accordance with the British National Grid. latitude: title: Latitude type: number description: A value in metres defining the y location in accordance with the British National Grid. longitude: title: Longitude type: number description: A value defining the Longitude location in accordance with the ETRS89 coordinate reference system. single_address_line: title: Single Line Address type: string maxLength: 500 description: A single attribute containing text concatenation of the address elements separated by a comma. street_name: title: Single Line Address type: string maxLength: 100 description: Street / Road name for the address record. locality: title: Locality type: string maxLength: 35 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. town_name: title: Town Name type: string maxLength: 35 description: Geographical town name assigned by the Local Authority. Please note this can be different from the Post Town value assigned by Royal Mail. delivery_point_suffix: title: Delivery Point Suffix type: string maxLength: 2 description: A two-character code uniquely identifying an individual delivery point within a postcode, assigned by Royal Mail. post_town: title: Town Name type: string maxLength: 30 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. gss_code: title: Governmental Statistical Service type: string maxLength: 9 description: The Office for National Statistics Governmental Statistical Service (GSS) code representing the contributing Local Authority. rpc: title: Representative Point Code type: number maxLength: 1 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. last_update_date: title: Last Update Date type: string format: date description: The latest date on which any of the attributes on this record were last changed. island: title: Island type: string maxLength: 50 description: Third level of geographic area name to record island names where appropriate. change_code: title: Change Code type: string maxLength: 50 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 building_name: title: Building Name type: string maxLength: 110 description: The building name is a description applied to a single address or a group of addresses. building_number: title: Building Number type: string maxLength: 13 description: The building number is a number or range of numbers given to a single address or a group of addresses. sub_building: title: Sub-building type: string maxLength: 110 description: The sub-building name and/or number for the address record. postcode: title: Postcode type: string maxLength: 8 description: A postcode assigned by Royal Mail for the address record. po_box: title: PO Box type: string maxLength: 13 description: Text concatenation of 'PO BOX' and the Post Office Box (PO Box) number or 'BFPO' and the British Forces Post Office number. organisation: title: Organisation type: string maxLength: 100 description: The organisation name is the business name given, when appropriate, to an address record. country: $ref: '#/components/schemas/paf_country' country_iso: $ref: '#/components/schemas/paf_country_iso' county: $ref: '#/components/schemas/paf_county' district: $ref: '#/components/schemas/paf_district' ward: $ref: '#/components/schemas/paf_ward' traditional_county: $ref: '#/components/schemas/paf_traditional_county' administrative_county: $ref: '#/components/schemas/paf_administrative_county' postal_county: $ref: '#/components/schemas/paf_postal_county' AbAddress: title: AddressBase Core description: |- Address from Ordnance Survey AddressBase Core 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. allOf: - $ref: '#/components/schemas/PafBase' - type: object required: - native properties: country_iso: enum: - GBR dataset: type: string enum: - ab country_iso_2: enum: - GB language: enum: - en postcode_type: title: Postcode Type enum: - '' type: string country: enum: - England - Scotland - Wales native: $ref: '#/components/schemas/AddressBaseCore' Dataset: title: Dataset type: string 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 - `herewe` (Western Europe) Western Europe Dataset - `gnaf` (Australia) Geoscape Geocoded National Address File enum: - paf - pafw - pafa - mr - nyb - usps - ecaf - ecad - ab - herewe - heret - heresa - hereo - herena - heremeas - heremea - herem - herei - herehk - hereee - hereap - gnaf CountryISO: title: ISO Country Code (3) type: string description: |2 3 letter country code (ISO 3166-1) enum: - GBR - IMN - JEY - GGY - USA - PRI - GUM - IRL - VAT - FRA - GRL - NLD - LUX - AUT - GIB - LIE - FIN - UNI - ISL - CHE - PRT - BEL - MCO - ITA - FRO - NOR - DNK - SMR - MLT - AND - SWE - DEU - ESP - SJM - BRN - IDN - KHM - MMR - MYS - PHL - SGP - THA - TLS - VNM - ALB - ARM - AZE - BGR - BIH - BLR - CYP - CZE - EST - GEO - GRC - HRV - HUN - KAZ - KGZ - KOS - LTU - LVA - MDA - MKD - MNE - POL - ROU - RUS - SRB - SVK - SVN - TUR - UKR - UZB - HKG - BGD - IND - LKA - MAC - AGO - ARE - BFA - BHR - BWA - CMR - EGY - GHA - ISR - JOR - KEN - KWT - LBN - LSO - MAR - MOZ - MUS - MYT - NAM - NGA - OMN - QAT - REU - SAU - SEN - SWZ - TUN - ZAF - ZMB - ZWE - BHS - BLZ - BMU - CAN - CRI - CYM - DOM - GTM - HND - HTI - JAM - MEX - NIC - PAN - SLV - VGB - AUS - CCK - CXR - FJI - NCL - NFK - NZL - PYF - TON - VUT - ABW - ARG - BLM - BOL - BRA - BRB - CHL - COL - CUW - DMA - ECU - GLP - GUF - GUY - MAF - MTQ - PER - PRY - SUR - TTO - URY - VEN - TWN - CHN - JPN - KOR - LAO - MNG - PNG - PRK - SLB - TJK - TKM - BTN - IOT - LKA - MDV - NPL - PAK - AFG - BDI - BEN - CAF - CIV - COD - COG - COM - CPV - DJI - DZA - ERI - ESH - ETH - GAB - GIN - GMB - GNB - GNQ - IRN - IRQ - LBR - LBY - MDG - MLI - MRT - MWI - NER - RWA - SHN - SLE - SOM - SSD - STP - SYC - TCD - TGO - TZA - UGA - SDN - SYR - YEM - CUB - SPM - TCA - COK - KIR - NIU - NRU - PCN - TKL - TUV - WLF - WSM - AIA - ATG - BES - FLK - GRD - KNA - LCA - MSR - SGS - SXM - VCT - ASM - FSM - MHL - MNP - PLW - VIR CountryISO2: title: ISO Country Code (2) type: string description: |2 2 letter country code (ISO 3166-1) enum: - GB - IM - JE - GG - US - PR - GU - IE - VA - FR - GL - NL - LU - AT - GI - LI - FI - GB - IS - CH - PT - BE - MC - IT - FO - 'NO' - DK - SM - MT - AD - SE - DE - ES - SJ - BS - BZ - BM - CA - CR - KY - DO - GT - HN - HT - JM - MX - NI - PA - SV - VG - AU - CC - CX - FJ - NC - NF - NZ - PF - TO - VU - AW - AR - BL - BO - BR - BB - CL - CO - CW - DM - EC - GP - GD - GF - GY - MF - MQ - PE - PY - SR - TT - UY - VE - TW - BN - ID - KH - MM - MY - PH - SG - TH - TL - VN - AL - AM - AZ - BG - BA - BY - CY - CZ - EE - GE - GR - HR - HU - KZ - KG - XK - LT - LV - MD - MK - ME - PL - RO - RU - RS - SK - SI - TR - UA - UZ - HK - BD - IN - LK - MO - AO - AE - BF - BH - BW - CM - EG - GH - IL - JO - KE - KW - LB - LS - MA - MZ - MU - YT - NA - NG - OM - QA - RE - SA - SN - SZ - TN - ZA - ZM - ZW - CN - JP - KR - LA - MN - PG - KP - SB - TJ - TM - BT - IO - LK - MV - NP - PK - AF - BI - BJ - CF - CI - CD - CG - KM - CV - DJ - DZ - ER - EH - ET - GA - GN - GM - GW - GQ - IR - IQ - LR - LY - MG - ML - MR - MW - NE - RW - SH - SL - SO - SS - ST - SC - TD - TG - TZ - UG - SD - SY - YE - CU - PM - TC - CK - KI - NU - NR - PN - TK - TV - WF - WS - AI - AG - BQ - FK - KN - LC - MS - GS - SX - VC - AS - FM - MH - MP - PW - VI Country: title: Country type: string description: |2 Full country names (ISO 3166) enum: - United Kingdom - England - Scotland - Wales - Northern Ireland - Isle of Man - Jersey - Guernsey - Guam - United States - Puerto Rico - Ireland - Vatican City - France - Greenland - Netherlands - Luxembourg - Austria - Gibraltar - Liechtenstein - Finland - United Kingdom - Iceland - Switzerland - Portugal - Belgium - Monaco - Italy - Faroe Islands - Norway - Denmark - San Marino - Malta - Andorra - Sweden - Germany - Spain - Svalbard and Jan Mayen - Bahamas - Belize - Bermuda - Canada - Costa Rica - Cayman Islands - Dominican Republic - Guatemala - Honduras - Haiti - Jamaica - Mexico - Nicaragua - Panama - El Salvador - British Virgin Islands - Australia - Cocos (Keeling) Islands - Christmas Island - Fiji - New Caledonia - Norfolk Island - New Zealand - French Polynesia - Tonga - Vanuatu - Aruba - Argentina - Saint Barthélemy - Bolivia - Brazil - Barbados - Chile - Colombia - Curaçao - Dominica - Ecuador - Guadeloupe - Grenada - French Guiana - Guyana - Saint Martin (French part) - Martinique - Peru - Paraguay - Suriname - Trinidad and Tobago - Uruguay - Venezuela - Taiwan - Brunei Darussalam - Indonesia - Cambodia - Myanmar - Malaysia - Philippines - Singapore - Thailand - Timor-Leste - Vietnam - Albania - Armenia - Azerbaijan - Bulgaria - Bosnia and Herzegovina - Belarus - Cyprus - Czech Republic - Estonia - Georgia - Greece - Croatia - Hungary - Kazakhstan - Kyrgyzstan - Kosovo - Lithuania - Latvia - Moldova - North Macedonia - Montenegro - Poland - Romania - Russia - Serbia - Slovakia - Slovenia - Turkey - Ukraine - Uzbekistan - Hong Kong - Bangladesh - India - Sri Lanka - Macau - Angola - United Arab Emirates - Burkina Faso - Bahrain - Botswana - Cameroon - Egypt - Ghana - Israel - Jordan - Kenya - Kuwait - Lebanon - Lesotho - Morocco - Mozambique - Mauritius - Mayotte - Namibia - Nigeria - Oman - Qatar - Réunion - Saudi Arabia - Senegal - Eswatini - Tunisia - South Africa - Zambia - Zimbabwe - China - Japan - South Korea - Laos - Mongolia - Papua New Guinea - North Korea - Solomon Islands - Tajikistan - Turkmenistan - Bhutan - British Indian Ocean Territory - Sri Lanka - Maldives - Nepal - Pakistan - Afghanistan - Burundi - Benin - Central African Republic - Côte d'Ivoire - Democratic Republic of the Congo - Republic of the Congo - Comoros - Cape Verde - Djibouti - Algeria - Eritrea - Western Sahara - Ethiopia - Gabon - Guinea - Gambia - Guinea-Bissau - Equatorial Guinea - Iran - Iraq - Liberia - Libya - Madagascar - Mali - Mauritania - Malawi - Niger - Rwanda - Saint Helena - Sierra Leone - Somalia - South Sudan - São Tomé and Príncipe - Seychelles - Chad - Togo - Tanzania - Uganda - Sudan - Syria - Yemen - Cuba - Saint Pierre and Miquelon - Turks and Caicos Islands - Cook Islands - Kiribati - Niue - Nauru - Pitcairn Islands - Tokelau - Tuvalu - Vanuatu - Wallis and Futuna - Samoa - Anguilla - Antigua and Barbuda - Bonaire, Sint Eustatius and Saba - Falkland Islands (Malvinas) - Saint Kitts and Nevis - Saint Lucia - Montserrat - South Georgia and the South Sandwich Islands - Sint Maarten (Dutch part) - Saint Vincent and the Grenadines - American Samoa - Federated States of Micronesia - Marshall Islands - Northern Mariana Islands - Palau - United States Virgin Islands EircBase: 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 properties: id: $ref: '#/components/schemas/ID' dataset: type: string description: Source of address country_iso: description: |2 3 letter country code (ISO 3166-1) enum: - IRL country_iso_2: type: string description: |2 2 letter country code (ISO 3166-1) enum: - IE country: type: string description: |2 Full country names (ISO 3166) enum: - Ireland language: enum: - en - ga description: | Language represented by 2 letter ISO Code (639-1) line_1: description: Address Line 1 type: string maxLength: 200 minLength: 0 line_2: description: Address Line 2 type: string maxLength: 200 minLength: 0 line_3: description: Address Line 3 type: string maxLength: 200 minLength: 0 line_4: description: Address Line 4 type: string maxLength: 200 minLength: 0 line_5: description: Address Line 5 type: string maxLength: 200 minLength: 0 line_6: description: Address Line 6 type: string maxLength: 200 minLength: 0 line_7: description: Address Line 7 type: string maxLength: 200 minLength: 0 line_8: description: Address Line 8 type: string maxLength: 200 minLength: 0 line_9: description: Address Line 9 type: string maxLength: 200 minLength: 0 department: type: string maxLength: 60 minLength: 0 description: The department or division within an organisation. If the department element exists, then the organisation must also exist. example: Accounts Department organisation: type: string description: Organisation name maxLength: 60 minLength: 0 example: Oak Tree Limited sub_building_name: type: string example: Flat 1 maxLength: 60 minLength: 0 description: The sub-building refers to an apartment, flat or unit within a building. building_name: type: string example: Rose Cottage maxLength: 60 minLength: 0 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. building_number: type: string example: 22 maxLength: 40 minLength: 0 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. building_group: type: string maxLength: 60 minLength: 0 description: A building group is a collection of buildings with a collective name, located on or near the same thoroughfare. example: Marrian Terrace primary_thoroughfare: type: string maxLength: 40 minLength: 0 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 secondary_thoroughfare: type: string maxLength: 40 minLength: 0 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 primary_locality: type: string maxLength: 40 minLength: 0 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 secondary_locality: type: string maxLength: 40 minLength: 0 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 tertiary_locality: type: string maxLength: 40 minLength: 0 example: Dublin 14 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." post_county: type: string maxLength: 30 minLength: 0 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 eircode: type: string maxLength: 60 minLength: 0 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 address_reference: type: string maxLength: 16 minLength: 0 description: The address reference is the An Post GeoDirectory address reference identifier used by the Universal Service Provider. longitude: $ref: '#/components/schemas/Longitude' latitude: $ref: '#/components/schemas/Latitude' EcadAddress: title: Ireland ECAD Address 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 allOf: - $ref: '#/components/schemas/EircBase' - type: object properties: dataset: type: string enum: - ecad ecad_id: type: string description: Unique 10 digit ECAD ID example: '17000000' minLength: 1 maxLength: 10 organisation_id: type: string description: Organisation ID example: '10098783' maxLength: 10 minLength: 1 address_point_id: type: string description: Address Point ID example: '10098783' maxLength: 10 minLength: 1 building_id: type: string description: Building ID example: '10098783' maxLength: 10 minLength: 1 building_group_id: type: string description: Building Group ID example: '10098783' primary_thoroughfare_id: type: string description: Primary Thoroughfare ID example: '10098783' maxLength: 10 minLength: 1 secondary_thoroughfare_id: type: string description: Secondary Thoroughfare ID example: '10098783' primary_locality_id: type: string description: Primary Locality ID example: '10098783' maxLength: 10 minLength: 1 secondary_locality_id: type: string description: Secondary Locality ID example: '10098783' post_town: type: string minLength: 0 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." post_town_id: type: string description: Post Town ID example: '10098783' maxLength: 10 minLength: 1 post_county_id: type: string description: Post County ID example: '10098783' maxLength: 10 minLength: 1 nua: type: boolean 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. gaeltacht: type: boolean 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. address_type: type: string minLength: 0 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. 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. type: string minLength: 0 building_group_address_type: type: string minLength: 0 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. primary_locality_address_type: type: string minLength: 0 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 secondary_locality_address_type: type: string minLength: 0 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 building_type: type: string minLength: 0 description: Describes the type of building, e.g. detached, semi-detached, bungalow. holiday_home: enum: - 'N' - 'Y' - '' description: A Yes/No field, indicating whether or not the building is a holiday home. under_construction: enum: - 'N' - 'Y' - '' description: A Yes/No field, indicating whether or not the building is under construction. building_use: enum: - R - C - B - U description: |- Can be one of: - `R` Residential - `C` Commercial - `B` Both - `U` Unknown vacant: description: A Yes/No field, indicating whether the building is vacant. enum: - 'Y' - 'N' - '' org_vacant: description: A Yes/No field, indicating whether the organisation is vacant. enum: - 'Y' - 'N' - '' nace_code: description: The NACE Code for the Category. type: string minLength: 0 nace_category: description: Name of the NACE Category type: string minLength: 0 local_authority: description: Name of local authority type: string minLength: 0 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. type: string minLength: 0 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. type: string minLength: 0 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. type: string minLength: 0 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. type: string minLength: 0 postaim_presort_61: description: An Post sorting information. type: string minLength: 0 postaim_presort_152: description: An Post sorting information. type: string minLength: 0 publicity_post_zone: description: An Post publicity post zone information. type: string minLength: 0 EcafAddress: title: Ireland ECAF Address 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 allOf: - $ref: '#/components/schemas/EircBase' - type: object properties: dataset: type: string enum: - ecaf ecaf_id: type: string maxLength: 10 minLength: 0 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. usps_dataset: title: USA Dataset type: string description: Identifies the address as sourced from USPS enum: - usps usps_country: title: Country type: string description: |2 Full country names (ISO 3166) enum: - American Samoa - Federated States of Micronesia - Guam - Marshall Islands - Northern Mariana Islands - Palau - Puerto Rico - United States - United States Virgin Islands usps_country_iso: title: ISO Country Code (3) type: string description: |2 3 letter country code (ISO 3166-1) enum: - ASM - FSM - GUM - MHL - MNP - PLW - PRI - USA - VIR usps_country_iso_2: title: ISO Country Code (2) type: string description: |2 2 letter country code (ISO 3166-1) enum: - AS - FM - GU - MH - MP - PR - PW - US - VI usps_language: title: Language type: string description: | Language represented by 2 letter ISO Code (639-1) enum: - en primary_number: title: Primary Number type: string 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 secondary_number: title: Secondary Number type: string description: Number of the sub unit, apartment, suite etc example: 123A plus_4_code: title: Plus 4 Code type: string description: 4 digit ZIP add-on code. example: '1234' line_1: title: First Address Line type: string description: The primary delivery line (usually the street address) of the address. example: 12 Armstrong Ct Apt 12 line_2: title: Second Address Line type: string description: Secondary delivery line of the address. Typically populated if the first line is the firm or building name. example: 9450 Pinecroft Dr last_line: title: Last Line type: string description: Last line of the address comprising of city, state, zip code and zip+4 example: Greenwich CT 06830-1234 zip_code: title: ZIP Code type: string maxLength: 5 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' zip_plus_4_code: title: ZIP + 4 Code type: string maxLength: 9 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 update_key_number: title: Update Key Number type: string maxLength: 10 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' record_type_code: title: Record Type Code type: string maxLength: 1 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 - '' carrier_route_id: title: Carrier Route ID type: string maxLength: 4 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 street_pre_directional_abbreviation: title: Street Pre-Directional Abbreviation type: string maxLength: 2 description: A geographic direction that precedes the street name. street_name: title: Street Name type: string maxLength: 28 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 street_suffix_abbreviation: title: Street Suffix Abbreviation type: string maxLength: 4 description: 'Code that is the standard USPS abbreviation for the trailing designator in a street address. ' example: ST street_post_directional_abbreviation: title: Street Post Directional Abbreviation type: string maxLength: 2 description: A geographic direction that follows the street name. building_or_firm_name: title: Building or Firm Name type: string maxLength: 40 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 address_secondary_abbreviation: title: Address Secondary Abbreviation type: string maxLength: 4 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. base_alternate_code: title: Base Alternate Code type: string maxLength: 1 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 - '' lacs_status_indicator: title: LACS Status Indicator type: string maxLength: 1 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 government_building_indicator: title: Government Building Indicator type: string maxLength: 1 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 state_abbreviation: title: State Abbreviation type: string maxLength: 2 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 state: title: State type: string description: Full name of a state, U.S. territory, or armed forces ZIP Code designation. example: New York municipality_city_state_key: title: Municipality City State Key type: string maxLength: 6 description: Municipality City State Key. Currently blank. urbanization_city_state_key: title: Urbanization City State Key type: string maxLength: 6 description: An index to the City State file that provides the urbanization name for this delivery range. example: V18475 preferred_last_line_city_state_key: title: Preferred Last Line City State Key type: string maxLength: 6 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 county: title: County Name type: string 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 city: title: City Name type: string description: A valid city name for mailing purposes; appears in the last line of an address on a mail piece. example: HOLTSVILLE city_abbreviation: title: City State Name Abbreviation type: string 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 preferred_city: title: Preferred Last Line City State Name type: string description: Field that contains the default preferred or alternate preferred last-line name for a ZIP Code. example: AGUADA city_state_name_facility_code: title: City State Name Facility Code type: string maxLength: 1 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' - '' zip_classification_code: title: ZIP Classification Code type: string maxLength: 1 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 city_state_mailing_name_indicator: title: City State Mailing Name Indicator type: string maxLength: 1 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." carrier_route_rate_sortation: title: Carrier Route Rate Sortation and Merged 5-Digit Indicator type: string maxLength: 1 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. finance_number: title: Finance Number oneOf: - type: string description: Empty string `""` if not available - type: number description: Finance Number example: 351560 description: A code assigned to Postal Service facilities (primarily Post Offices) to collect cost and statistical data and compile revenue and expense data. congressional_district_number: title: Congressional District Number oneOf: - type: string description: Empty string `""` if not available - type: number description: Congressional district number example: 6 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). county_number: title: County Number oneOf: - type: string description: Empty string `""` if not available - type: number description: FIPS code example: 53 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. UspsAddress: title: United States Postal Service Address description: Standard USA Address 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 properties: id: $ref: '#/components/schemas/ID' dataset: $ref: '#/components/schemas/usps_dataset' country: $ref: '#/components/schemas/usps_country' country_iso: $ref: '#/components/schemas/usps_country_iso' country_iso_2: $ref: '#/components/schemas/usps_country_iso_2' language: $ref: '#/components/schemas/usps_language' primary_number: $ref: '#/components/schemas/primary_number' secondary_number: $ref: '#/components/schemas/secondary_number' plus_4_code: $ref: '#/components/schemas/plus_4_code' line_1: $ref: '#/components/schemas/line_1' line_2: $ref: '#/components/schemas/line_2' last_line: $ref: '#/components/schemas/last_line' zip_code: $ref: '#/components/schemas/zip_code' zip_plus_4_code: $ref: '#/components/schemas/zip_plus_4_code' update_key_number: $ref: '#/components/schemas/update_key_number' record_type_code: $ref: '#/components/schemas/record_type_code' carrier_route_id: $ref: '#/components/schemas/carrier_route_id' street_pre_directional_abbreviation: $ref: '#/components/schemas/street_pre_directional_abbreviation' street_name: $ref: '#/components/schemas/street_name' street_suffix_abbreviation: $ref: '#/components/schemas/street_suffix_abbreviation' street_post_directional_abbreviation: $ref: '#/components/schemas/street_post_directional_abbreviation' building_or_firm_name: $ref: '#/components/schemas/building_or_firm_name' address_secondary_abbreviation: $ref: '#/components/schemas/address_secondary_abbreviation' base_alternate_code: $ref: '#/components/schemas/base_alternate_code' lacs_status_indicator: $ref: '#/components/schemas/lacs_status_indicator' government_building_indicator: $ref: '#/components/schemas/government_building_indicator' state_abbreviation: $ref: '#/components/schemas/state_abbreviation' state: $ref: '#/components/schemas/state' municipality_city_state_key: $ref: '#/components/schemas/municipality_city_state_key' urbanization_city_state_key: $ref: '#/components/schemas/urbanization_city_state_key' preferred_last_line_city_state_key: $ref: '#/components/schemas/preferred_last_line_city_state_key' county: $ref: '#/components/schemas/county' city: $ref: '#/components/schemas/city' city_abbreviation: $ref: '#/components/schemas/city_abbreviation' preferred_city: $ref: '#/components/schemas/preferred_city' city_state_name_facility_code: $ref: '#/components/schemas/city_state_name_facility_code' zip_classification_code: $ref: '#/components/schemas/zip_classification_code' city_state_mailing_name_indicator: $ref: '#/components/schemas/city_state_mailing_name_indicator' carrier_route_rate_sortation: $ref: '#/components/schemas/carrier_route_rate_sortation' finance_number: $ref: '#/components/schemas/finance_number' congressional_district_number: $ref: '#/components/schemas/congressional_district_number' county_number: $ref: '#/components/schemas/county_number' HereAddress: title: HERE Address description: Address from the global HERE dataset allOf: - type: object required: - id - dataset - country_iso - line_1 - line_2 - line_3 - line_4 - line_5 - language - address - latitude - longitude - building_name - delivery_longitude - delivery_latitude - street_name - postal_code - order1_name - order2_name - order8_name - builtup_name properties: id: $ref: '#/components/schemas/ID' country_iso: type: string description: |- Three character country code based on ISO Standard 3166. Can be empty string `""` if not present. example: ITA dataset: type: string enum: - herewe - heret - heresa - hereo - herena - heremeas - heremea - herem - herei - herehk - hereee - hereap language: type: string description: Language Code of Address and Building Name for the Point Address. example: it minLength: 2 maxLength: 2 line_1: type: string description: | First address line. Can be empty string `""` if not present. example: 16 Via Giuseppe Garibaldi minLength: 1 maxLength: 150 line_2: type: string description: | Second address line. Can be empty string `""` if not present. example: '' minLength: 0 maxLength: 150 line_3: type: string description: | Third address line. Can be empty string `""` if not present. example: '' minLength: 0 maxLength: 150 line_4: type: string description: | Fourth address line. Can be empty string `""` if not present. example: '' minLength: 0 maxLength: 150 line_5: type: string description: | Fifth address line. Can be empty string `""` if not present. example: '' minLength: 0 maxLength: 150 address: type: string description: | Address / House Number uniquely identifying the address along the specified road link. Can be empty string `""` if not present. example: '16' minLength: 0 maxLength: 150 address_type: type: string description: | Address Type defines the type of address represented by the Point Address (e.g., Base, Commercial). Can be empty string `""` if not present. example: '1' delivery_latitude: oneOf: - type: string description: Empty string `""` if not available - type: number minimum: -90 maximum: 90 description: Latitude defining the arrival position of the Point Address. example: 45.28441 delivery_longitude: oneOf: - type: string description: Empty string `""` if not available - type: number minimum: -180 maximum: 180 description: Longitude defining the arrival position of the Point Address. example: 12.00825 building_name: type: string description: | Name of the Building to which the Point Address is associated. Can be empty string `""` if not present. example: '' minLength: 0 maxLength: 150 latitude: oneOf: - type: string description: Empty string `""` if not available - type: number minimum: -90 maximum: 90 description: Latitude of the display position for the Point Address. example: 45.28441 longitude: oneOf: - type: string description: Empty string `""` if not available - type: number minimum: -180 maximum: 180 description: Longitude of the display position for the Point Address. example: 12.00825 street_name: type: string description: The full spelling of the street name, including Prefix, Base Name, Suffix, Street Type, and Direction on Sign. minLength: 1 maxLength: 100 example: Via Giuseppe Garibaldi postal_code: type: string description: |- Full postal code; could be numeric or alphanumeric postal code. Can be empty string `""` if not present. minLength: 0 maxLength: 15 example: '35020' order1_name: type: string description: Identifies the highest administrative level in which a country can be subdivided. example: Veneto order2_name: type: string description: Identifies an intermediate administrative level of a country and is a sub-division of an Order-1 area. Only countries with a five (or more) level administrative hierarchy have Order-2 administrative levels defined. This feature can be used for destination selection and map display. example: Padova order8_name: type: string description: Identifies the lowest level of the country's administrative hierarchy that is present country- wide. (No gaps exist in the coverage.) example: Brugine builtup_name: type: string description: Identifies the lowest administrative level for a country. This level does not cover the entire country, (as opposed to the Order-8 Area level which does cover the entire country). This feature should be used in conjunction with Zone and Order-8 Area for destination selection. The Built-up Area polygon, as published in RDF_CARTO, can also be used for map display. example: '' GnafAddress: required: - id - dataset - country - country_iso - country_iso_2 - line_1 - line_2 - language - address - longitude - latitude - address_detail_pid - date_created - date_last_modified - date_retired - building_name - lot_number_prefix - lot_number - lot_number_suffix - flat_type_code - flat_number_prefix - flat_number - flat_number_suffix - level_type_code - level_number_prefix - level_number - level_number_suffix - number_first_prefix - number_first - number_first_suffix - number_last_prefix - number_last - number_last_suffix - street_locality_pid - alias_principal - postcode - private_street - legal_parcel_id - confidence - level_geocoded_code - primary_secondary - alias_type_code - geocode_type_code - default_latitude - default_longitude - address_change_type_code - mb_2016_match_code - mb_2021_match_code - address_type - address_site_name - geocode_site_name - site_geocode_type_code - reliability_code - site_boundary_extent - site_planimetric_accuracy - elevation - site_longitude - site_latitude - geocode_type_priority_order - site_geocode_priority_order - locality_name - primary_postcode - locality_class_code - locality_gnaf_reliability_code - locality_alias_name - locality_alias_postcode - locality_alias_type_code - locality_planimetric_accuracy - locality_latitude - locality_longitude - mb_2016_code - mb_2021_code - ps_join_type_code - state_name - state_abbreviation - street_class_code - street_name - street_type_code - street_suffix_code - gnaf_street_confidence - street_locality_gnaf_reliability_code - street_locality_alias_street_name - street_locality_alias_street_type_code - street_locality_alias_street_suffix_code - street_locality_alias_type_code - street_locality_boundary_extent - street_locality_planimetric_accuracy - street_locality_latitude - street_locality_longitude - street_type_name - street_locality_alias_street_type_name properties: id: $ref: '#/components/schemas/ID' dataset: type: string enum: - gnaf country_iso: description: |2 3 letter country code (ISO 3166-1) enum: - AUS - CCK - CXR - NFK country_iso_2: type: string description: |2 2 letter country code (ISO 3166-1) enum: - AU - CC - CX - NF country: type: string description: |2 Full country names (ISO 3166) enum: - Australia - Cocos (Keeling) Islands - Christmas Island - Norfolk Island line_1: type: string description: | First address line. Can be empty string `""` if not present. example: 30 Hampton Cct line_2: type: string description: | Second address line. Can be empty string `""` if not present. example: '' language: enum: - en description: | Language represented by 2 letter ISO Code (639-1) address: type: string description: | Address / House Number uniquely identifying the address along the specified street. Can be empty string `""` if not present. example: '16' longitude: $ref: '#/components/schemas/Longitude' latitude: $ref: '#/components/schemas/Latitude' address_detail_pid: type: string description: | The Persistent Identifier is unique to the real world feature this record represents. date_created: type: string format: date description: | Date this record was created. date_last_modified: type: string format: date description: | Date this record was last modified (not retired/recreated in line with ICSM standard). date_retired: type: string format: date description: | Date this record was retired. building_name: type: string description: | Combines both building/property name fields. Field length: up to 200 alphanumeric characters (AS4590:2006 5.7). lot_number_prefix: type: string description: | Lot number prefix. Field length: up to two alphanumeric characters (AS4590:2006 5.8.1). lot_number: type: string description: | Lot number. Field length: up to five alphanumeric characters (AS4590:2006 5.8.1). lot_number_suffix: type: string description: | Lot number suffix. Field length: up to two alphanumeric characters (AS4590:2006 5.8.1). flat_type_code: type: string description: | Specification of the type of a separately identifiable portion within a building/complex. Field Length: up to seven upper case alpha characters (AS4590:2006 5.5.1.1). flat_number_prefix: type: string description: | Level number prefix. Field length: up to two alphanumeric characters (AS4590:2006 5.5.2.2). flat_number: oneOf: - type: string description: Empty string `""` if not available - type: number description: | Flat/unit number. Field length: up to five numeric characters (AS4590:2006 5.5.1.2). flat_number_suffix: type: string description: | Flat/unit number suffix Field length: up to two alphanumeric characters (AS4590:2006 5.5.1.2). level_type_code: type: string description: | Level type. Field length: up to four alphanumeric characters (AS4590:2006 5.5.2.1). level_number_prefix: type: string description: | Level number prefix. Field length: up to two alphanumeric characters (AS4590:2006 5.5.2.2). level_number: oneOf: - type: string description: Empty string `""` if not available - type: number description: | Level number. Field length: up to three numeric characters (AS4590:2006 5.5.2.2). level_number_suffix: type: string description: | Level number suffix. Field length: up to two alphanumeric characters (AS4590:2006 5.5.2.2). number_first_prefix: type: string description: | Prefix for the first (or only) number in range. Field length: up to three uppercase alphanumeric characters (AS4590:2006 5.5.3.1). number_first: oneOf: - type: string description: Empty string `""` if not available - type: number description: | Identifies first (or only) street number in range. Field length: up to six numeric characters (AS4590:2006 5.5.3.1). number_first_suffix: type: string description: | Suffix for the first (or only) number in range. Field length: up to two uppercase alphanumeric characters (AS4590:2006 5.5.3.1). number_last_prefix: type: string description: | Prefix for the last number in range. Field length: up to three uppercase alphanumeric characters (AS4590:2006 5.5.3.2). number_last: oneOf: - type: string description: Empty string `""` if not available - type: number description: | Identifies last number in range. Field length: up to six numeric characters (AS4590:2006 5.5.3.2). number_last_suffix: type: string description: | Suffix for the last number in range. Field length: up to two uppercase alphanumeric characters (AS4590:2006 5.5.3.2). street_locality_pid: type: string description: | Street/Locality of this address - not mandatory N as some records in G-F may not require street (e.g. remote rural property). alias_principal: type: string description: | A = Alias record, P = Principal record. postcode: type: string description: | Postcodes are optional as prescribed by AS4819 and AS4590:2006 5.13. private_street: type: string description: | Private street information. This is not broken up into name/type/suffix. Field length: up to 75 alphanumeric characters. This is not currently populated. legal_parcel_id: type: string description: | Generic parcel id field derived from the Geoscape Australia’s Cadastre parcel where available. confidence: oneOf: - type: string description: Empty string `""` if not available - type: number description: | Reflects how many contributor databases this address appears in (0 = 1 database, 1 = 2 database etc.). level_geocoded_code: type: number description: | Binary indicator of the level of geocoding this address has. e.g. 0 = 000 = (No geocode), 1 = 001 = (No Locality geocode, No Street geocode, Address geocode), etc. primary_secondary: type: string description: | Indicator that identifies if the address is P (Primary) or S (secondary). alias_type_code: type: string description: | Alias type (e.g. "Synonym"). geocode_type_code: type: string description: | Unique abbreviation for the geocode type. default_latitude: oneOf: - type: string description: Empty string `""` if not available - type: number description: | Latitude default_longitude: oneOf: - type: string description: Empty string `""` if not available - type: number description: | Longitude address_change_type_code: type: string description: | The code indicating the type of change, for example, LOC-STN for locality name and street name change. mb_2016_match_code: type: string description: | Code for mesh block match e.g. 1. mb_2021_match_code: type: string description: | Code for mesh block match e.g. 1. address_type: type: string description: | Address type (e.g. "Postal", Physical"). address_site_name: type: string description: | Address site name. Field length: 200 alphanumeric characters. geocode_site_name: type: string description: | An identifier that relates to this specific geocoded site (e.g. "Transformer 75658"). site_geocode_type_code: type: string description: | Unique abbreviation for geocode feature. (e.g. "PRCL") (SAWG 7.4.1). reliability_code: type: string description: | Spatial precision of the geocode expressed N as number in the range, 1 (unique identification of feature) to 6 (feature associated to region i.e. postcode). site_boundary_extent: type: string description: | Measurement (metres) of a geocode from other geocodes associated with the same address persistent identifier. site_planimetric_accuracy: type: string description: | Planimetric accuracy. elevation: type: string description: | Elevation. This field is not currently populated. site_longitude: type: string description: | Site longitude site_latitude: type: string description: | Site latitude geocode_type_priority_order: oneOf: - type: string description: Empty string `""` if not available - type: number description: | The priority order enables a default geocode to be assigned to each address which represents the geocode of the highest precision currently assigned to an address. site_geocode_priority_order: oneOf: - type: string description: Empty string `""` if not available - type: number description: | The priority order enables a default geocode to be assigned to each address which represents the geocode of the highest precision currently assigned to an address. locality_name: type: string description: | The name of the locality or suburb. primary_postcode: type: string description: | Required to differentiate localities of the same name within a state. locality_class_code: type: string description: | Describes the class of locality (e.g. Gazetted, topographic feature etc.). Lookup to locality class. locality_gnaf_reliability_code: oneOf: - type: string description: Empty string `""` if not available - type: number description: | = 5 if suburb locality, else = 6. Spatial precision of the geocode expressed as number in the range, 1 (unique identification of feature) to 6 (feature associated to region i.e. postcode). locality_alias_name: type: string description: | The alias name for the locality or suburb. locality_alias_postcode: type: string description: | Postcode. locality_alias_type_code: type: string description: | Alias type code for the locality. locality_planimetric_accuracy: oneOf: - type: string description: Empty string `""` if not available - type: number description: | Planimetric accuracy of geocode (if known). locality_latitude: oneOf: - type: string description: Empty string `""` if not available - type: number description: | Locality latitude locality_longitude: oneOf: - type: string description: Empty string `""` if not available - type: number description: | Locality longitude mb_2016_code: type: string description: | The 2016 mesh block code. mb_2021_code: type: string description: | The 2021 mesh block code. ps_join_type_code: type: string description: | Code of 1 OR 2 when the root address:- Code 1: Automatically generated when the primary and secondary addresses share the same street number, street name (and type) and locality name components. Code 2: Manually generated where the primary and secondary addresses MAY or MAY NOT share the same street number, street name (and type) and locality name components state_name: type: string description: | The state or territory name. All in uppercase. E.g. TASMANIA. state_abbreviation: type: string description: | The state or territory abbreviation. street_class_code: type: string description: | Defines whether this street represents a confirmed or unconfirmed street. street_name: type: string description: | Street name. e.g. "POPLAR". street_type_code: type: string description: | The street type code. e.g. "PLACE". street_suffix_code: type: string description: | The street suffix code. e.g. "WEST". gnaf_street_confidence: oneOf: - type: string description: Empty string `""` if not available - type: number description: | The street confidence level. street_locality_gnaf_reliability_code: oneOf: - type: string description: Empty string `""` if not available - type: number description: | Always = 4. Spatial precision of the geocode expressed as number in the range, 1 (unique identification of feature) to 6 (feature associated to region i.e. postcode). street_locality_alias_street_name: type: string description: | The street alias name. e.g. "POPLAR". street_locality_alias_street_type_code: type: string description: | The street type code. e.g. "PLACE". street_locality_alias_street_suffix_code: type: string description: | The street suffix code. e.g. "WEST". street_locality_alias_type_code: type: string description: | The alias type code. street_locality_boundary_extent: oneOf: - type: string description: Empty string `""` if not available - type: number description: | Measurement (metres) of a geocode from other geocodes associated with the same address persistent identifier. street_locality_planimetric_accuracy: oneOf: - type: string description: Empty string `""` if not available - type: number description: | Planimetric accuracy of geocode (if known). street_locality_latitude: oneOf: - type: string description: Empty string `""` if not available - type: number description: | Street locality latitude street_locality_longitude: oneOf: - type: string description: Empty string `""` if not available - type: number description: | Street locality longitude street_type_name: type: string description: | Abbreviation of street type street_locality_alias_street_type_name: type: string description: | Abbreviation of street type GbrGlobalAddress: title: Global Address description: Global (non-UK) address in the UK address format 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 properties: id: $ref: '#/components/schemas/ID' dataset: $ref: '#/components/schemas/Dataset' country_iso: $ref: '#/components/schemas/CountryISO' country_iso_2: $ref: '#/components/schemas/CountryISO2' language: $ref: '#/components/schemas/Language' line_1: title: Address First Line type: string description: First line of the address. Typically the building number and street name example: 10 Georgia Ave line_2: title: Address Second Line type: string description: Second line of the address. Can be blank example: '' line_3: title: Address Third Line type: string description: Third line of the address. Can also be blank example: '' postcode: title: Postal Code type: string description: Represents the postal or zip code example: 30529-2320 post_town: type: string description: | The city, town or other primary locality example: Commerce county: type: string description: State or county name example: Georgia county_code: type: string description: Code abbreviation for state or county used in some countries. example: GA longitude: $ref: '#/components/schemas/Longitude' latitude: $ref: '#/components/schemas/Latitude' country: $ref: '#/components/schemas/Country' 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/HereAddress' - $ref: '#/components/schemas/GnafAddress' postcode_outward: type: string description: Not available for non-UK addresses enum: - '' postcode_inward: type: string description: Not available for non-UK addresses enum: - '' dependant_locality: type: string description: Not available for non-UK addresses enum: - '' double_dependant_locality: type: string description: Not available for non-UK addresses enum: - '' thoroughfare: type: string description: Not available for non-UK addresses enum: - '' dependant_thoroughfare: type: string description: Not available for non-UK addresses enum: - '' building_number: type: string description: Not available for non-UK addresses enum: - '' building_name: type: string description: Not available for non-UK addresses enum: - '' sub_building_name: type: string description: Not available for non-UK addresses enum: - '' premise: type: string description: Not available for non-UK addresses enum: - '' po_box: type: string description: Not available for non-UK addresses enum: - '' department_name: type: string description: Not available for non-UK addresses enum: - '' organisation_name: type: string description: Not available for non-UK addresses enum: - '' udprn: type: string description: Not available for non-UK addresses. See `id` for address identifier umprn: type: string description: Not available for non-UK addresses. See `id` for address identifier enum: - '' postcode_type: type: string description: Not available for non-UK addresses enum: - '' su_organisation_indicator: type: string description: Not available for non-UK addresses enum: - '' delivery_point_suffix: type: string description: Not available for non-UK addresses enum: - '' administrative_county: type: string description: Not available for non-UK addresses enum: - '' postal_county: type: string description: Not available for non-UK addresses enum: - '' traditional_county: type: string description: Not available for non-UK addresses enum: - '' district: type: string description: Not available for non-UK addresses enum: - '' ward: type: string description: Not available for non-UK addresses enum: - '' eastings: type: string description: Not available for non-UK addresses enum: - '' northings: type: string description: Not available for non-UK addresses enum: - '' uprn: type: string description: Not available for non-UK addresses. See `id` for address identifier enum: - '' PostcodeResponse: title: Postcode Response type: object example: result: - postcode: SW1A 2AA postcode_inward: 2AA postcode_outward: SW1A post_town: London dependant_locality: '' double_dependant_locality: '' thoroughfare: Downing Street dependant_thoroughfare: '' building_number: '10' building_name: '' sub_building_name: '' po_box: '' department_name: '' organisation_name: Prime Minister & First Lord Of The Treasury udprn: 23747771 postcode_type: L su_organisation_indicator: '' delivery_point_suffix: 1A line_1: Prime Minister & First Lord Of The Treasury line_2: 10 Downing Street line_3: '' premise: '10' longitude: -0.12767 latitude: 51.503541 eastings: 530047 northings: 179951 country: England traditional_county: Greater London administrative_county: '' postal_county: London county: London district: Westminster ward: St. James's uprn: '100023336956' id: paf_23747771 country_iso: GBR country_iso_2: GB county_code: '' language: en umprn: '' dataset: paf code: 2000 message: Success limit: 100 page: 0 total: 1 required: - message - code - result - limit - page - total properties: result: type: array 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' description: | All addresses listed at the postcode. If Eircode is enabled, addreses for the Republic of Ireland will be returned in the English format. code: type: integer enum: - 2000 message: type: string enum: - Success page: type: integer minimum: 0 maximum: 10 default: 0 limit: type: integer minimum: 1 maximum: 100 default: 100 total: type: integer ErrorResponse: title: Basic Error Response type: object required: - code - message properties: code: type: integer 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 message: type: string description: Human readable error message supplied with every error response. BadRequestResponse: title: Bad Request Error Response allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object required: - code - message properties: code: type: integer description: '`400X` type error response code' format: int32 message: type: string description: Bad request error description errors: type: array items: type: object required: - path - message properties: message: type: string example: should have required property 'type' description: Indicates location of error in request query or URL parameter path: type: string example: .query.type description: Indicates location of error in request query or URL parameter errorCode: type: string example: required.openapi.validation PostcodeNotFoundResponse: title: Postcode Not Found type: object required: - message - code - suggestions properties: code: type: integer format: int32 enum: - 4040 message: type: string enum: - Postcode not found suggestions: description: A list of alternate nearest matching postcodes you can try type: array items: type: string example: SN13 0SF UDPRNResponse: title: UDPRN Response type: object example: result: postcode: SW1A 2AA postcode_inward: 2AA postcode_outward: SW1A post_town: London dependant_locality: '' double_dependant_locality: '' thoroughfare: Downing Street dependant_thoroughfare: '' building_number: '10' building_name: '' sub_building_name: '' po_box: '' department_name: '' organisation_name: Prime Minister & First Lord Of The Treasury udprn: 23747771 postcode_type: L su_organisation_indicator: '' delivery_point_suffix: 1A line_1: Prime Minister & First Lord Of The Treasury line_2: 10 Downing Street line_3: '' premise: '10' longitude: -0.12767 latitude: 51.503541 eastings: 530047 northings: 179951 country: England traditional_county: Greater London administrative_county: '' postal_county: London county: London district: Westminster ward: St. James's uprn: '100023336956' id: paf_23747771 country_iso: GBR country_iso_2: GB county_code: '' language: en umprn: '' dataset: paf code: 2000 message: Success required: - message - code - result properties: result: oneOf: - $ref: '#/components/schemas/PafAddress' - $ref: '#/components/schemas/NybAddress' code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success UMPRNResponse: title: Multiple Residence (UMPRN) Address Response type: object example: result: postcode: CV4 7AL postcode_inward: 7AL postcode_outward: CV4 post_town: Coventry dependant_locality: '' double_dependant_locality: '' thoroughfare: Gibbet Hill Road dependant_thoroughfare: '' building_number: '' building_name: Block 1 Arthur Vick sub_building_name: Room 249a po_box: '' department_name: '' organisation_name: '' udprn: 5770157 postcode_type: S su_organisation_indicator: '' delivery_point_suffix: 1A line_1: Room 249a, Block 1 Arthur Vick line_2: Gibbet Hill Road line_3: '' premise: Room 249a, Block 1 Arthur Vick longitude: -1.5648072 latitude: 52.3858227 eastings: 429716 northings: 276509 country: England traditional_county: Warwickshire administrative_county: '' postal_county: West Midlands county: West Midlands district: Coventry ward: Wainbody uprn: '200001572050' id: mr_50906058 country_iso: GBR country_iso_2: GB county_code: '' language: en umprn: 50906058 dataset: mr code: 2000 message: Success required: - message - code - result properties: result: $ref: '#/components/schemas/MrAddress' code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success AvailableContexts: title: Available Contexts type: array description: A list of available contexts for a key items: type: object required: - iso_3 - iso_2 - description - emoji - rgeo properties: iso_3: type: string example: USA description: 3 letter ISO code iso_2: type: string example: US description: 2 letter ISO code description: type: string example: United States description: | Country descriptor to show in Address Finder emoji: type: string description: Emoji text icon example: 🇺🇸 rgeo: type: boolean example: true description: | Indicates availability of reverse geolocation search Context: title: Context type: string description: Limits search results within a geographical boundary or country. NoContext: title: No Context Provided type: string enum: - '' description: Empty string if no context is provided or key check has failed ApiKey: title: Key type: object required: - available - context - contexts properties: contexts: $ref: '#/components/schemas/AvailableContexts' 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' 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 type: boolean example: true ApiKeyResponse: title: API Key Response type: object required: - message - code - result properties: result: $ref: '#/components/schemas/ApiKey' message: type: string enum: - Success code: type: integer format: int32 enum: - 2000 ApiKeyDailyLimit: title: API Key Daily Limit type: object required: - limit - consumed properties: limit: x-nullable: true nullable: true minimum: 0 example: 1000 type: integer description: |- `number` or `null`. The daily lookup limit currently set on your key. `null` means the limit is currently disabled. format: int32 consumed: minimum: 0 example: 288 type: integer description: Number of lookups performed today which count towards your daily limit. format: int32 ApiKeyIndividualLimit: title: API Key Individual Limit type: object required: - limit properties: limit: minimum: 0 example: 30 x-nullable: true nullable: true type: integer 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. format: int32 ApiKeyNotifications: title: API Key Notifications type: object required: - emails - enabled properties: emails: type: array description: A list of email addresses designated by you to receive notifications about this key. items: type: string example: person@example.com enabled: description: Indicates whether email notifications are enabled. type: boolean ApiKeyDatasets: title: API Key Dataset Availability description: Indicates which datasets are available and added by default to the address responses type: object required: - paf - mr - nyb - pafa - pafw - ab - nip - ecad - ecaf - usps - herewe - hereap - hereee - herehk - herei - herem - heremea - heremeas - herena - hereo - heresa - heret - email - phone - gnaf properties: paf: type: boolean description: UK Main Address File (Postcode Address File) example: true pafa: type: boolean description: UK Property Alias dataset example: false pafw: type: boolean description: UK Welsh Language Dataset example: false mr: type: boolean description: UK Multiple Residence Dataset example: true nyb: type: boolean description: UK Not Yet Built Dataset example: false ab: type: boolean description: UK AddressBase dataset example: false nip: type: boolean description: Northern Ireland Pointer Dataset example: false usps: type: boolean description: US Address Dataset example: true ecad: type: boolean description: IE Address File. Eircode Address Database example: false ecaf: type: boolean description: IE Base Address File. Eircode Address File example: false gnaf: type: boolean description: Australia Geocoded National Address File example: true hereap: type: boolean description: Asia Pacific Address File example: true herehk: type: boolean description: Hong Kong Address File example: true herei: type: boolean description: India Address File example: true herem: type: boolean description: Macau Address File example: true heremea: type: boolean description: Middle East and Africa Address File example: true heremeas: type: boolean description: Middle East and Africa Standalone Intermediate Maps Address File example: true herena: type: boolean description: North America Address File example: true hereo: type: boolean description: Oceania Address File example: true heresa: type: boolean description: South America Address File example: true heret: type: boolean description: Taiwan Address File example: true hereee: type: boolean description: Eastern Europe Address File example: true herewe: type: boolean description: Western Europe Address File example: true phone: type: boolean description: Phone validation is enabled example: true email: type: boolean description: Email validation is enabled example: true ApiKeyAutomatedTopup: title: API Key Automated Topup description: Automated topup status type: object required: - enabled properties: enabled: type: boolean description: Indicates whether automated top-ups are enabled example: true ApiKeyCurrentPurchase: title: API Key Batch Purchase type: object required: - expires - purchased - consumed properties: expires: x-nullable: true nullable: true type: string example: '2022-01-06T11:41:27.092Z' 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. purchased: minimum: 0 type: integer description: Number of procured lookups from this purchase. example: 20000 format: int32 consumed: minimum: 0 type: integer description: Number of consumed lookups off this purchase. format: int32 example: 121 ApiKeyDetails: title: API Key Details type: object required: - lookups_remaining - daily_limit - individual_limit - allowed_urls - redact_days - notifications - automated_topups - current_purchases - ip_forwarding - datasets properties: lookups_remaining: minimum: 0 example: 19889 type: integer format: int32 daily_limit: $ref: '#/components/schemas/ApiKeyDailyLimit' individual_limit: $ref: '#/components/schemas/ApiKeyIndividualLimit' allowed_urls: type: array items: type: string description: A list of allowed URLs. An empty list means that allowed URLs are disabled. redact_days: type: integer default: 28 description: Number of days to preserve personal data stored in your key usage history. Set to 0 to prevent personal data storage notifications: $ref: '#/components/schemas/ApiKeyNotifications' datasets: $ref: '#/components/schemas/ApiKeyDatasets' automated_topups: $ref: '#/components/schemas/ApiKeyAutomatedTopup' current_purchases: type: array items: $ref: '#/components/schemas/ApiKeyCurrentPurchase' description: Current balance purchases attached to key. ip_forwarding: type: boolean default: false description: Accept IP addresses forwarded in the `IDPC-Source-IP` header ApiKeyDetailsResponse: title: API Key Details Response type: object required: - message - code - result properties: result: $ref: '#/components/schemas/ApiKeyDetails' code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success ApiKeyDetailsEditable: title: API Key Details Update type: object properties: daily_limit: title: Daily Rate Limit type: object properties: limit: x-nullable: true nullable: true minimum: 0 example: 1000 type: integer description: |- `number` or `null`. The daily lookup limit currently set on your key. `null` means the limit is currently disabled. format: int32 individual_limit: title: API Key Individual Limit type: object properties: limit: minimum: 0 example: 30 x-nullable: true nullable: true type: integer 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. format: int32 allowed_urls: type: array items: type: string maxLength: 256 pattern: ^[^\s]+$ description: A list of allowed URLs. An empty list means that allowed URLs are disabled. Up to 10 allowed. redact_days: type: integer default: 28 minimum: 0 maximum: 1095 description: Number of days to preserve personal data stored in your key usage history. Set to 0 to prevent personal data storage notifications: title: API Key Notifications type: object properties: emails: type: array description: A list of email addresses designated by you to receive notifications about this key. Up to 5 allowed. items: type: string pattern: ^\S{1,100}@\S{1,100}$ example: person@example.com enabled: description: Indicates whether email notifications are enabled. type: boolean ip_forwarding: type: boolean default: false description: Accept IP addresses forwarded in the `IDPC-Source-IP` header datasets: title: API Key Dataset Availability description: Indicates which datasets are available and added by default to the address responses type: object properties: pafa: type: boolean description: UK Property Alias dataset example: false pafw: type: boolean description: UK Welsh Language Dataset example: false usps: type: boolean description: US Address Dataset example: true hereap: type: boolean description: Asia Pacific Address File example: true herehk: type: boolean description: Hong Kong Address File example: true herei: type: boolean description: India Address File example: true herem: type: boolean description: Macau Address File example: true heremea: type: boolean description: Middle East and Africa Address File example: true heremeas: type: boolean description: Middle East and Africa Extended File example: true herena: type: boolean description: North America Address File example: true hereo: type: boolean description: Oceania Address File example: true heresa: type: boolean description: South America Address File example: true heret: type: boolean description: Taiwan Address File example: true hereee: type: boolean description: Eastern Europe Address File example: true herewe: type: boolean description: Western Europe Address File example: true phone: type: boolean description: Phone validation is enabled example: true email: type: boolean description: Email validation is enabled example: true gnaf: type: boolean description: Australia Geoscape Geocoded National Address File example: true KeyUsageResult: title: Key Usage type: object required: - start - end - total - dailyCount properties: start: type: string description: Start date in ISO 8601 format. example: '2015-01-22T15:08:06.609Z' end: type: string description: End date in ISO 8601 format. example: '2015-01-23T15:08:06.609Z' total: type: integer description: Total of paid lookups performed in specified period. format: int32 example: 132 dailyCount: type: array 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: type: object required: - date - count properties: date: type: string example: '2015-01-22T00:00:00.000Z' count: type: integer format: int32 example: 132 ApiKeyUsageResponse: title: Key Usage Response type: object required: - message - code - result properties: result: $ref: '#/components/schemas/KeyUsageResult' code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success UsaCassVerifiedAddress: title: United States CASS Verified Address type: object description: | Address retrieved using CASS compliant address verification process required: - address1 - address2 - address3 - area_code - carrier_route - check_digit - city - city_abbreviation - congressional_district - country_code - county - day_light_savings - delivery_point - dpv - dpv_cmra - dpv_footnotes - dpv_fp - dpv_no_stat - dpv_vacant - elot - finance_number - fips_county_code - firm - footnotes - geo_coded - lacs_indicator - lacs_link_footnote - lacs_link_indicator - latitude - longitude - parsed_pmb_designator - parsed_pmb_number - parsed_post_directional - parsed_pre_directional - parsed_primary_number - parsed_street_name - parsed_suffix - parsed_unit_designator - parsed_unit_number - rdi - record_type - secondary_address_info - state - suite_link_footnote - time_zone - urbanization - zip_code properties: address1: type: string description: | Primary delivery address address2: type: string description: | Secondary address information address3: type: string description: | Additional secondary address information area_code: type: string description: | Area code carrier_route: type: string description: | Data required to perform a Carrier Route sort check_digit: type: string description: | Character following the 5- or 9-digit ZIP Code city: type: string description: | City name city_abbreviation: type: string description: | City Abbreviation. Empty string if not present congressional_district: type: string description: | Identifies the Congressional District. Empty string if not present country_code: type: string description: | ISO3166 country code. Empty string if not present county: type: string description: | Name of the county day_light_savings: type: string description: | Daylight saving time indicator delivery_point: type: string description: | Last 2 digits of the primary street address number or Post Office™ box dpv: type: string description: | DPV Confirmation code. Possible values: 'Y' (Yes), 'S' (Suspicious), 'D' (No). dpv_cmra: type: string description: | DPV CMRA code. Possible values: 'Y' (Yes), 'N' (No). dpv_footnotes: type: string description: | DPV Footnotes. Empty string if not present dpv_fp: type: string description: | False Positive Indicator from the DPV lookup. Possible values: 'Y' (Yes), 'N' (No), ' ' (Space). Empty string if not present dpv_no_stat: type: string description: | DPV NoStat code. Empty string if not present dpv_vacant: type: string description: | DPV Vacant code. Empty string if not present elot: type: string description: | Enhanced Line of Travel finance_number: oneOf: - type: string - type: number description: | Internal accounting number used by the USPS. Empty string if not present fips_county_code: type: string description: | Federal Information Processing Standard code for a county. Empty string if not present firm: type: string description: | Company name in a business address footnotes: type: string description: | Letter codes returned by ZIP + 4® encoding. Empty string if not present geo_coded: type: string description: | Indicates whether the address was geo-coded. Possible values: 'Y' (Yes), 'N' (No). lacs_indicator: type: string description: | Indicates whether a record may benefit from LACS processing. Possible values: 'L' (Yes), ' ' (No). lacs_link_footnote: type: string description: | LACSLink Footnote. Empty string if not present lacs_link_indicator: type: string description: | LACSLink Indicator. Empty string if not present latitude: oneOf: - type: string - type: number description: | Latitude of the encoded address. Empty string if not present longitude: oneOf: - type: string - type: number description: | Longitude of the encoded address. Empty string if not present parsed_pmb_designator: type: string description: | Information if a PMB is found in an address. Empty string if not present parsed_pmb_number: oneOf: - type: string - type: number description: | Information if a PMB is found in an address. Empty string if not present parsed_post_directional: oneOf: - type: string - type: number description: | Notation following the street name indicating street direction. Empty string if not present parsed_pre_directional: type: string description: | Notation preceding the street name indicating street direction. Empty string if not present parsed_primary_number: oneOf: - type: string - type: number description: | Number preceding the street name. Empty string if not present parsed_street_name: type: string description: | Street name. Empty string if not present parsed_suffix: type: string description: | Part of the delivery address line following the street name. Empty string if not present parsed_unit_designator: type: string description: | Identification of the secondary address unit. Empty string if not present parsed_unit_number: type: string description: | Apartment or suite number. Empty string if not present rdi: type: string description: | Reserved for future use. Empty string if not present record_type: type: string description: | Type of address record (Street, PO Box, High-rise, etc.) secondary_address_info: type: string description: | Additional secondary address information. Empty string if not present state: type: string description: | Standard two-letter state abbreviation suite_link_footnote: type: string description: | Results of the SuiteLink lookup. Possible values: ' ' (Space), '00' (Double Zero), 'A' (A). Empty string if not present time_zone: type: string description: | Time zone. Empty string if not present urbanization: type: string description: | Urban name required in the address of all mail being delivered to Puerto Rico. Empty string if not present zip_code: type: string description: | 5-digit ZIP Code™ and the four additional digits GbrCleanseMatch: title: Address Match type: object required: - query - match - count - fit - confidence - organisation_match - premise_match - thoroughfare_match - postcode_match - locality_match - post_town_match properties: query: type: string description: Originally submitted query 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' - $ref: '#/components/schemas/UsaCassVerifiedAddress' count: type: number description: | The number of addresses we matched to the input. We return the closest match by default. maximum: 10 minimum: 0 fit: type: number 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 confidence: type: number maximum: 1 minimum: 0 description: | A confidence score represented as number between 1 and 0. 1 indicates a full match. 0 indicates no complete matching elements. organisation_match: type: string description: Match indicator for the organisation enum: - FULL - PARTIAL - INCORRECT - MISSING - NA premise_match: type: string description: Match indicator for the premise enum: - FULL - PARTIAL - INCORRECT - MISSING - NA postcode_match: type: string description: Match indicator for the postcode enum: - FULL - PARTIAL - INCORRECT - MISSING - NA thoroughfare_match: type: string description: Match indicator for the street enum: - FULL - PARTIAL - INCORRECT - MISSING - NA locality_match: type: string description: Match indicator for the locality enum: - FULL - PARTIAL - INCORRECT - MISSING - NA post_town_match: type: string description: Match indicator for the post_town enum: - FULL - PARTIAL - INCORRECT - MISSING - NA GbrCleanseNoMatch: type: object title: No Address Match required: - query - match - count - fit - confidence - organisation_match - premise_match - thoroughfare_match - postcode_match - locality_match - post_town_match properties: query: type: string description: Originally submitted query match: description: Nearest matching address type: object nullable: true enum: - null count: type: number description: '' enum: - 0 fit: type: number format: float description: '' enum: - 0 confidence: type: number format: float description: '' enum: - 0 organisation_match: type: string description: '' enum: - NO_MATCH premise_match: type: string description: '' enum: - NO_MATCH postcode_match: type: string description: '' enum: - NO_MATCH thoroughfare_match: type: string description: '' enum: - NO_MATCH locality_match: type: string description: '' enum: - NO_MATCH post_town_match: type: string description: '' enum: - NO_MATCH CleanseResponse: title: Address Cleanse Response type: object required: - message - code - result properties: code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success result: oneOf: - $ref: '#/components/schemas/GbrCleanseMatch' - $ref: '#/components/schemas/GbrCleanseNoMatch' UnauthorizedResponse: title: Unauthorized Request Error Response allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object required: - code - message properties: code: type: integer description: '`401X` type error response code' format: int32 message: type: string description: Unauthorized request error description RateLimitedResponse: title: Unauthorized Request Error Response allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object required: - code - message properties: code: type: integer description: '`429X` type error response code' format: int32 message: type: string description: Request is being rate limited AddressSuggestion: title: Address Suggestion description: Represents an address suggestion for any address in the world type: object required: - id - suggestion - urls example: id: usps_V210079628|10||3797 suggestion: 10 Downing St, Montpelier, VT, 05602 urls: null properties: id: $ref: '#/components/schemas/ID' suggestion: type: string description: Address Suggestion to be displayed to the user example: 10 Downing St, Montpelier, VT, 05602 urls: type: object UkAddressSuggestion: title: UK Address Suggestion 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. type: object example: id: paf_23747771 suggestion: Prime Minister & First Lord Of The Treasury, 10 Downing Street, London, SW1A udprn: 23747771, urls: udprn: /v1/udprn/23747771 required: - id - suggestion - udprn - urls properties: id: $ref: '#/components/schemas/ID' suggestion: type: string description: Address suggestion for a given query. example: Flat 6, 12 Roskear, Camborne, TR14 udprn: $ref: '#/components/schemas/paf_udprn' umprn: type: number format: int32 description: Optionally returned field, representing the UMPRN of a Multiple Residence household example: 51103417 urls: required: - udprn type: object properties: udprn: type: string description: URL to retrieve the entire details for a given address suggestion by the UDPRN example: /v1/udprn/50985827 umprn: type: string description: Optionally returned field, to retrieve the entire details for a suggested Multiple Residence household example: /v1/umprn/51103417 AutocompleteResponse: title: Address Autocomplete Response type: object required: - message - code - result properties: result: type: object required: - hits example: - id: paf_23747771 suggestion: Prime Minister & First Lord Of The Treasury, 10 Downing Street, London, SW1A udprn: 23747771 urls: udprn: /v1/udprn/23747771 - id: paf_26245117 suggestion: Flat 10, Downing Court, Grenville Street, London, WC1N udprn: 26245117 urls: udprn: /v1/udprn/26245117 properties: hits: type: array items: oneOf: - $ref: '#/components/schemas/AddressSuggestion' - $ref: '#/components/schemas/UkAddressSuggestion' code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success GbrResolveAddressResponse: title: Address Resolution Response (GBR) type: object required: - message - code - result properties: code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success 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' UsaGlobalAddress: title: Global Address description: Global (non-US) Address in the US address format 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 properties: id: $ref: '#/components/schemas/ID' dataset: $ref: '#/components/schemas/Dataset' enum: - paf country: $ref: '#/components/schemas/Country' country_iso: $ref: '#/components/schemas/CountryISO' country_iso_2: $ref: '#/components/schemas/CountryISO2' language: $ref: '#/components/schemas/Language' primary_number: type: string description: Not available for non-US addresses enum: - '' secondary_number: type: string description: Not available for non-US addresses enum: - '' plus_4_code: type: string description: Not available for non-US addresses enum: - '' line_1: type: string description: First line of address line_2: type: string description: Second line of address last_line: type: string description: Not available for non-US addresses enum: - '' zip_code: type: string description: Partial postcode of address zip_plus_4_code: type: string description: Full postal code of address update_key_number: type: string description: Not available for non-US addresses enum: - '' record_type_code: type: string description: Not available for non-US addresses enum: - '' carrier_route_id: type: string description: Not available for non-US addresses enum: - '' street_pre_directional_abbreviation: type: string description: Not available for non-US addresses enum: - '' street_name: type: string description: Not available for non-US addresses enum: - '' street_suffix_abbreviation: type: string description: Not available for non-US addresses enum: - '' street_post_directional_abbreviation: type: string description: Not available for non-US addresses enum: - '' building_or_firm_name: type: string description: Not available for non-US addresses enum: - '' address_secondary_abbreviation: type: string description: Not available for non-US addresses enum: - '' base_alternate_code: type: string description: Not available for non-US addresses enum: - '' lacs_status_indicator: type: string description: Not available for non-US addresses enum: - '' government_building_indicator: type: string description: Not available for non-US addresses enum: - '' state: type: string description: State or province state_abbreviation: type: string description: Code of state or province (if available) municipality_city_state_key: type: string description: Not available for non-US addresses enum: - '' urbanization_city_state_key: type: string description: Not available for non-US addresses enum: - '' preferred_last_line_city_state_key: type: string description: Not available for non-US addresses enum: - '' county: type: string description: County name city: type: string description: City name city_abbreviation: type: string description: City name abbreviation (if available) preferred_city: type: string description: Not available for non-US addresses enum: - '' city_state_name_facility_code: type: string description: Not available for non-US addresses enum: - '' zip_classification_code: type: string description: Not available for non-US addresses enum: - '' city_state_mailing_name_indicator: type: string description: Not available for non-US addresses enum: - '' carrier_route_rate_sortation: type: string description: Not available for non-US addresses enum: - '' finance_number: type: string description: Not available for non-US addresses enum: - '' congressional_district_number: type: string description: Not available for non-US addresses enum: - '' county_number: type: string description: Not available for non-US addresses enum: - '' 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' - $ref: '#/components/schemas/HereAddress' - $ref: '#/components/schemas/GnafAddress' UsaResolveAddressResponse: title: Address Retrieve Response (USA) type: object required: - message - code - result properties: code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success result: oneOf: - $ref: '#/components/schemas/UspsAddress' - $ref: '#/components/schemas/UsaGlobalAddress' AddressResponse: title: Address Search Response type: object required: - message - code - result properties: code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success result: type: object required: - hits - total - limit - page properties: hits: type: array 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' total: minimum: 0 maximum: 10000 type: integer format: int32 limit: maximum: 100 minimum: 0 default: 10 example: 10 type: integer format: int32 page: minimum: 0 default: 0 example: 0 maximum: 10 type: integer format: int32 place_name: title: Place Name type: string description: | Place name example: London place_descriptive_name: title: Descriptive Place Name type: string description: | Longer form description of the place. example: London, United Kingdom place_country_iso: title: Country type: string description: |2 3 letter country code (ISO 3166-1) example: GBR place_id: title: ID type: string description: | Unique identifier for place example: geonames_5324 PlaceSuggestion: title: Place Description description: | Represents a possible place given an autocomplete query. required: - name - descriptive_name - id - country_iso properties: name: $ref: '#/components/schemas/place_name' descriptive_name: $ref: '#/components/schemas/place_descriptive_name' country_iso: $ref: '#/components/schemas/place_country_iso' id: $ref: '#/components/schemas/place_id' PlaceResponse: title: Place Search Response type: object example: result: hits: - id: geonames_2643743 name: London descriptive_name: London, Greater London, England country_iso: GBR - id: geonames_4517009 name: London descriptive_name: London, Madison County, Ohio country_iso: USA - id: geonames_4298960 name: London descriptive_name: London, Laurel County, Kentucky country_iso: USA code: 2000 message: Success required: - message - code - result properties: code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success result: type: object required: - hits properties: hits: type: array description: | List of up to 10 matching places items: oneOf: - $ref: '#/components/schemas/PlaceSuggestion' GeonamesPlace: title: GeoNames Place 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 allOf: - type: object properties: geonameid: type: integer format: int32 description: Unique identifier for GeoNames place example: 5353 name: type: string description: Place name (UTF8) minLength: 0 maxLength: 200 example: London asciiname: type: string description: Place Name (ASCII) minLength: 0 maxLength: 200 example: London alternatenames: type: array description: List of alternate ASCII names items: oneOf: - type: string description: Alternate name for place minLength: 0 maxLength: 40 example: London latitude: $ref: '#/components/schemas/Latitude' longitude: $ref: '#/components/schemas/Longitude' feature_class: type: string description: GeoNames single letter feature code enum: - A - H - L - P - R - S - T - U - V feature_code: type: string description: Full GeoNames feature code (http://www.geonames.org/export/codes.html) minLength: 0 maxLength: 7 example: ADM1 country_code: type: string description: 2 Letter ISO country code minLength: 2 maxLength: 2 example: GB cc2: type: array description: List of other countries codes mapping to this place items: oneOf: - type: string description: Alternate name for place minLength: 2 maxLength: 2 example: IE admin1_name: type: string description: Name of first administrative area example: England admin1_geonameid: type: integer format: int32 nullable: true description: GeoName ID for first administrative area example: 5353 admin1_code: type: string description: Fipscode (subject to change to iso code) minLength: 0 maxLength: 20 example: ENG admin2_name: type: string description: Name of second administrative area example: England admin2_geonameid: type: integer format: int32 nullable: true description: GeoName ID for second administrative area example: 5353 admin2_code: type: string description: Code for the second administrative division minLength: 0 maxLength: 20 example: '06' admin3_code: type: string description: Code for third level administrative division minLength: 0 maxLength: 20 example: '08' admin4_code: type: string description: Code for fourth level administrative division minLength: 0 maxLength: 20 example: '07' population: type: string description: Population at place. Represented as string as it could be a larger than a 32bit integer example: '7392832' elevation: type: integer nullable: true format: int32 description: Elevation in meters dem: type: integer nullable: true format: int32 description: Digital elevation model example: 32 timezone: type: string description: The IANA timezone ID minLength: 0 maxLength: 40 example: Europe/London modification_date: type: string description: Datetime format example: '2015-03-09' dataset: type: string enum: - geonames id: type: string description: Unique place ID example: geonames_5353 Place: title: Place description: Represents a geographical place required: - id - dataset - name - descriptive_name - country_iso - language - longitude - latitude properties: id: title: ID type: string description: Global unique internally generated identifier for a place example: geonames_5353 dataset: title: Dataset type: string description: |- Indicates the provenance of a place. - `geonames` GeoNames place enum: - geonames name: $ref: '#/components/schemas/place_name' descriptive_name: $ref: '#/components/schemas/place_descriptive_name' country_iso: $ref: '#/components/schemas/place_country_iso' language: $ref: '#/components/schemas/Language' longitude: $ref: '#/components/schemas/Longitude' latitude: $ref: '#/components/schemas/Latitude' native: description: Native representation of a place oneOf: - $ref: '#/components/schemas/GeonamesPlace' ResolvePlaceResponse: title: Place Resolution Response type: object example: result: id: geonames_2643743 dataset: geonames name: London descriptive_name: London, Greater London, England language: en longitude: -0.12574 latitude: 51.50853 country_iso: GBR native: admin1_code: ENG admin2_name: Greater London geonameid: 2643743 timezone: Europe/London latitude: 51.50853 language: en dem: 25 admin4_code: '' admin1_geonameid: 6269131 alternatenames: - ILondon - LON - Lakana - Landan - Landen - Ljondan - Llundain - Lodoni - Londain - Londan - Londar - Londe - Londen - Londin - Londinium - Londino - Londn - London - London osh - Londona - Londonas - Londoni - Londono - Londons - Londonu - Londra - Londres - Londrez - Londri - Londro - Londye - Londyn - Londýn - Lonn - Lontoo - Loundres - Luan GJon - Lun-tun - Lunden - Lundra - Lundun - Lundunir - Lundúnir - Lung-dung - Lunnainn - Lunnin - Lunnon - Luân Đôn - Lùn-tûn - Lùng-dŭng - Lûn-tun - Lākana - Lůndůn - Lọndọnu - Ranana - Rānana - ilantan - ladana - landan - landana - leondeon - lndn - london - londoni - lun dui - lun dun - lwndwn - lxndxn - rondon - Łondra - Λονδίνο - Лондан - Лондон - Лондон ош - Лондонъ - Лёндан - Լոնդոն - לאנדאן - לונדון - لأندأن - لندن - لوندون - لەندەن - ܠܘܢܕܘܢ - लंडन - लंदन - लण्डन - लन्डन् - लन्दन - লন্ডন - ਲੰਡਨ - લંડન - ଲ୍ଡନ - இலண்டன் - లండన్ - ಲಂಡನ್ - ലണ്ടൻ - ලන්ඩන් - ลอนดอน - ລອນດອນ - ལོན་ཊོན། - လန်ဒန်မြို့ - ლონდონი - ለንደን - ᎫᎴ ᏗᏍᎪᏂᎯᏱ - ロンドン - 伦敦 - 倫敦 - 런던 cc2: [] admin2_code: GLA modification_date: '2022-03-09T00:00:00.000Z' asciiname: London id: geonames_2643743 feature_code: PPLC country_iso: GBR longitude: -0.12574 elevation: null admin2_geonameid: 2648110 admin1_name: England population: '8961989' country_code: GB feature_class: P name: London admin3_code: '' dataset: geonames code: 2000 message: Success required: - message - code - result properties: code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success result: $ref: '#/components/schemas/Place' LicenseeEditable: title: Licensee description: Licensee object which can be defined by user type: object properties: name: type: string example: Qwerty Widgets Limited description: Licensee individual or organisation name address: example: 12 High Street, Manchester type: string description: Licensee's first, second and third line address as well as post town concatenated by commas postcode: example: ID1 1QD type: string description: Licensee's postcode whitelist: type: array items: type: string example: https://www.example.com description: A list of allowed URLs. An empty list means that whitelisting is disabled daily: type: object properties: limit: example: 10000 x-nullable: true nullable: true minimum: 0 format: int32 type: number description: The maximum number of lookups this licensee can perform in a day. `null` indicates the limit is not active Licensee: title: Licensee allOf: - $ref: '#/components/schemas/LicenseeEditable' - type: object required: - id - key - createdAt - name - address - postcode - whitelist - daily properties: id: type: string example: 56a11209ebe230380bf104c3 description: | An immutable ID provided for every licensee. Primarily used for paginated list requests. key: type: string example: sl_ijoiqsxeQgXW2gkiE0X94 description: | Uniquely identifies a licensee for a key. Required to perform paid lookups for a specific licensee. Typically begins `sk_`. createdAt: type: string example: '2016-01-21T17:14:49.971Z' description: Timestamp for when the licensee was created daily: required: - count - updatedAt type: object properties: count: example: 232 minimum: 0 type: number format: int32 description: The number lookups performed by the licensee on the day represented b `licesees.daily.updatedAt` updatedAt: type: string example: '2016-08-05T16:43:28.865Z' description: The timestamp when the limit was last used. LicenseesResponse: title: Licensee List Response type: object required: - message - code - result properties: result: description: List of licensees type: object properties: licensees: type: array items: $ref: '#/components/schemas/Licensee' hasMore: type: boolean description: Returns true if there are more licensees listed after the maximum number of results as implied by `limit` message: type: string enum: - Success code: type: integer format: int32 enum: - 2000 LicenseeResponse: title: Licensee Response type: object required: - message - code - result properties: result: $ref: '#/components/schemas/Licensee' code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success Config: title: Config Object type: object required: - updatedAt - createdAt - name - payload properties: updatedAt: type: string example: '2016-01-21T17:14:49.971Z' description: Timestamp for when the config was created createdAt: type: string example: '2016-01-21T17:14:49.971Z' description: Timestamp for when the config was updated name: type: string example: woocommerce description: A unique name to identify the configuration payload minimum: 0 maximum: 32 payload: example: | { "removeOrganisation": false } type: string minimum: 0 maximum: 4096 description: A serialised payload of up to `4096` characters ConfigsResponse: title: Config List Response type: object required: - message - code - result properties: result: description: List of configurations type: object required: - configs properties: configs: type: array items: $ref: '#/components/schemas/Config' message: type: string enum: - Success code: type: integer format: int32 enum: - 2000 ConfigNewParam: title: New Config Object description: Required configuration object parameters type: object required: - name - payload properties: name: type: string example: woocommerce description: A unique name to identify the configuration payload minimum: 0 maximum: 32 payload: example: | { "removeOrganisation": false } type: string minimum: 0 maximum: 4096 description: A serialised payload of up to `4096` characters ConfigResponse: title: Config Response type: object required: - result - code - message properties: result: $ref: '#/components/schemas/Config' code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success NotFoundResponse: title: Not Found Response allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object required: - code - message properties: code: type: integer description: '`404X` type error response code' format: int32 message: type: string description: Resource not found error description ConfigUpdateParam: title: Update Config Object description: Config object update parameters type: object properties: payload: example: | { "removeOrganisation": false } type: string minimum: 0 maximum: 4096 description: A serialised payload of up to `4096` characters Email: title: Email Object type: object required: - result - deliverable - role - free - disposable - catchall properties: result: type: string enum: - deliverable - not_deliverable deliverable: type: boolean description: Returns `true` if the email can be delivered disposable: type: boolean description: Returns `true` if email comes from a disposable email service like temp-mail free: type: boolean description: Returns `true` if the email originates from a free service like Outlook or Gmail. role: type: boolean description: Returns `true` if email address represents an organisational role like `admin`, `support`, `postmaster` etc catchall: type: boolean description: Returns `true` if this domain accepts all emails regardless of username UnknownEmail: title: Unknown Email Object type: object required: - result - deliverable - role - free - disposable - catchall properties: result: type: string enum: - unknown deliverable: type: boolean x-nullable: true nullable: true description: Deliverability is not known enum: - null disposable: type: boolean x-nullable: true nullable: true description: Disposability is not known enum: - null free: type: boolean x-nullable: true nullable: true description: Free email provider is not known enum: - null role: type: boolean x-nullable: true nullable: true description: Role is not known enum: - null catchall: type: boolean x-nullable: true nullable: true description: Catch-all status is not known enum: - null EmailResponse: title: Email Verification Response type: object example: result: result: deliverable deliverable: true catchall: false free: false role: true disposable: false code: 2000 message: Success required: - message - code - result properties: code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success result: oneOf: - $ref: '#/components/schemas/Email' - $ref: '#/components/schemas/UnknownEmail' Carrier: title: Carrier Object type: object x-nullable: true nullable: true required: - network_code - name - country - network_type properties: network_code: title: Network Code type: string x-nullable: true nullable: true description: The [Mobile Country Code](https://en.wikipedia.org/wiki/Mobile_country_code) for the carrier. example: '234' name: title: Name type: string x-nullable: true nullable: true description: The full name of the carrier that number is associated with. example: BT Group country: title: Country ISO Alpha-2 Code type: string x-nullable: true nullable: true description: Country that number is associated with. In ISO 3166-1 alpha-2 format. example: GB network_type: title: Network Type type: string x-nullable: true nullable: true description: Type of network that number is associated with. enum: - mobile - landline - landline_premium - landline_tollfree - virtual - unknown - pager - mobile_or_landline - shared_cost - uan - voicemail PhoneNumber: title: Phone Number Object type: object required: - valid - national_format - international_format - iso_country - iso_country_2 - country - current_carrier - original_carrier properties: valid: type: boolean enum: - true national_format: description: Phone number formatted to local standard type: string example: 020 7112 8019 international_format: description: Phone number formatted to international standard type: string example: '442071128019' iso_country: description: Country code in 3 letter ISO format type: string example: GBR iso_country_2: description: Country code in 2 letter ISO format type: string example: GB country: description: Full country name type: string example: United Kingdom current_carrier: description: Representation of current phone carrier information like network code, name, country, network type $ref: '#/components/schemas/Carrier' original_carrier: description: Representation of original phone carrier information like network code, name, country, network type $ref: '#/components/schemas/Carrier' InvalidPhoneNumber: title: Invalid Phone Number Object type: object required: - valid - national_format - international_format - iso_country - iso_country_2 - country properties: valid: type: boolean enum: - false national_format: description: Phone number formatted to local standard x-nullable: true nullable: true type: string enum: - null international_format: description: Phone number formatted to international standard x-nullable: true nullable: true type: string enum: - null iso_country: description: Country code in 3 letter ISO format x-nullable: true nullable: true type: string enum: - null iso_country_2: description: Country code in 2 letter ISO format x-nullable: true nullable: true type: string enum: - null country: description: Full country name x-nullable: true nullable: true type: string enum: - null current_carrier: description: Representation of current phone carrier information like network code, name, country, network type x-nullable: true nullable: true type: string enum: - null original_carrier: description: Representation of original phone carrier information like network code, name, country, network type x-nullable: true nullable: true type: string enum: - null PhoneNumberResponse: title: Phone Number Verification Response type: object example: result: valid: true national_format: 020 7112 8019 international_format: +44 20 7112 8019 iso_country: GBR iso_country_2: GB country: United Kingdom current_carrier: network_code: null name: Invomo Ltd country: GB network_type: landline original_carrier: network_code: null name: Invomo Ltd country: GB network_type: landline code: 2000 message: Success required: - message - code - result properties: code: type: integer format: int32 enum: - 2000 message: type: string enum: - Success result: oneOf: - $ref: '#/components/schemas/PhoneNumber' - $ref: '#/components/schemas/InvalidPhoneNumber' parameters: ApiKeyParam: description: | **API Key** Your unique identifier that allows access to our APIs. Begins `ak_`. Available from your dashboard example: ak_test explode: false in: query name: api_key schema: type: string style: form FilterParam: name: filter in: query style: form explode: false schema: type: string description: | **Restrict Result Fields** 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 PageParam: name: page in: query style: form explode: false schema: type: integer minimum: 0 maximum: 100 default: 0 format: int32 description: | **Page** 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: 1 TagsParam: name: Tags in: query style: form explode: false required: false schema: type: string 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 ApiKeyPathParam: name: key in: path required: true style: simple explode: false schema: type: string example: ak_test description: | **API Key** The API Key to retrieve. Begins `ak_`. UserTokenParam: in: query style: form explode: false schema: type: string name: user_token description: | **Private User Token** 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 StartParam: name: Start Time style: form in: query schema: type: integer format: int64 minimum: 0 description: | A start date/time in the form of a UNIX Timestamp in milliseconds, e.g. `1418556452651`. example: 1418556452651 EndParam: name: End Time style: form in: query schema: type: integer format: int64 minimum: 0 description: | An start date/time in the form of a UNIX Timestamp in milliseconds, e.g. `1418556477882`. example: 1418556477882 LicenseeParam: example: sl_hk71kco54zGSGvF9eXXrvvnMOLLNh description: | **Licensee Key** Uniquely identifies a licensee. explode: false in: query name: licensee schema: type: string style: form ContextParam: name: context in: query style: form explode: false example: GBR description: | **Context** Limits search results, typically within g country. schema: type: string LimitParam: name: limit in: query style: form explode: false schema: minimum: 1 maximum: 100 default: 10 type: integer format: int32 example: 5 description: | **Limit** Specifies the maximum number of records to retrieve. By default the limit is 10. Requesting a larger result set will result in more latency BiasLonLatParam: name: bias_lonlat in: query style: form explode: false schema: type: string description: | **Bias by Geolocation** 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' BiasIpParam: name: bias_ip in: query style: form explode: false required: false description: | **Bias by Geolocation of IP** Biases search based on approximate geolocation of IP address. Set `bias_ip=true` to enable. schema: type: string enum: - 'true' BoxParam: name: box in: query style: form explode: false schema: type: string description: | **Filter by Bounding Box** 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 PostcodeOutwardParam: name: postcode_outward in: query style: form explode: false schema: type: string description: | **Filter by Outward Code** Restrict result set to addresses with a matching outward code. The outward code is the first half of a postcode. E.g. the outward code for `SW1A 2AA` is `SW1A`. example: SW1A PostcodeParam: name: postcode in: query style: form explode: false schema: type: string description: |- **Filter by postcode** Restrict result set to matching postcodes only. Can be combined with query to perform a postcode and building number or name search. example: SW1A 2AA PostcodeAreaParam: name: postcode_area in: query style: form explode: false schema: type: string description: | **Filter by Postcode Area** Postcode area represents the first one or two non-numeric characters of a postcode. E.g. the postcode area of `SW1A 2AA` is `SW`. Can be combined with query to perform a postcode and building search. example: SW PostcodeSectorParam: name: postcode_sector in: query style: form explode: false schema: type: string description: | **Filter by Postcode Sector** Postcode sector is the outward code plus first numeric of the inward code. E.g. postcode sector of `SW1A 2AA` is `SW1A 2` example: SW1A 2 PostTownParam: name: post_town in: query style: form explode: false schema: type: string description: | **Filter by Town or City** Restrict addresses to matching town, city or other locality identifier. example: London UPRNParam: name: uprn in: query style: form explode: false schema: type: integer description: | **Filter by UPRN** Does not accept comma separated terms. Only a single term is permitted example: '100023336956' CountryParam: name: country in: query style: form explode: false schema: type: string description: | **Filter by country** Filters by country name. In the context of GBR, country values are not United Kingdom. Instead they are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man. example: England PostcodeTypeParam: name: postcode_type in: query style: form explode: false schema: type: string description: | **Filter by Postcode Type** Filter by Postcode Type. Useful for separating organisational and residential addresses SmallUserParam: name: su_organisation_indicator in: query style: form explode: false schema: type: string description: | **Filter by Organisation Indicator** Useful for separating organisational and residential addresses example: 'Y' BiasPostcodeOutwardParam: name: bias_postcode_outward in: query style: form explode: false schema: type: string description: |- **Bias by Outward Code** Boosts addresses with a matching outward code. Outward code is the first have of a postcode. For instance, the outward code of `SW1A 2AA` is `SW1A` example: SW1A BiasPostcodeParam: name: bias_postcode in: query style: form explode: false schema: type: string description: |- **Bias by postcode** Boost addresses which match postcode. Can be combined with query to perform a postcode and building number or name search. example: SW1A2AA BiasPostcodeAreaParam: name: bias_postcode_area in: query style: form explode: false schema: type: string description: | **Bias by Postcode Area** Boosts if the first one or two non-numeric characters of a postcode match The postcode area of SW1A 2AA and N1 6RT are SW and N respectively example: SW BiasPostcodeSectorParam: name: bias_postcode_sector in: query style: form explode: false schema: type: string description: | **Bias by Postcode Sector** Boost postcode sector matches. The postcode sector comprises the outward code plus first numeric of the inward code. example: SW1A 2 BiasPosttownParam: name: bias_post_town in: query style: form explode: false schema: type: string description: | **Bias by Town or City** Biases results to matching town, city or other locality name. BiasThoroughfareParam: name: bias_thoroughfare in: query style: form explode: false schema: type: string description: | **Bias by Street** Bias by street or thoroughfare name. BiasCountryParam: name: bias_country in: query style: form explode: false schema: type: string description: | **Bias by Country** Possible values are England, Scotland, Wales, Northern Ireland, Jersey, Guernsey and Isle of Man. AddressLongitudeParam: name: lon in: query style: form explode: false schema: type: number format: float minimum: -180 maximum: 180 description: | **Longitude** Longitude query for reverse geocoding. An accompanying latitude (lat=) query must be submitted for a valid reverse geocode query. example: -0.12767 AddressLatitudeParam: name: lat in: query style: form explode: false schema: type: number format: float minimum: -90 maximum: 90 description: | **Latitude** Latitude query for reverse geocoding. An accompanying longitude (lon=) query must be submitted for a valid reverse geocode query. example: 51.503541 CountryIsoParam: name: country_iso in: query style: form explode: false schema: type: string description: | **Filter by Country** 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 BiasCountryIsoParam: name: bias_country_iso in: query style: form explode: false description: |- **Bias by Country** 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 schema: type: string LicenseePathParam: name: licensee in: path required: true style: simple explode: false schema: type: string example: sl_hk71kco54zGSGvF9eXXrvvnMOLLNh description: | **Licensee Key** Uniquely identifies a licensee. ConfigParam: name: config in: path required: true style: simple explode: false schema: type: string description: | **Configuration Name** User provided configuration object name. example: idpc-be 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