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