openapi: 3.0.3
info:
version: 4.11.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.
## OpenAPI Spec
Our OpenAPI specification is available at:
- [Github Repository](https://github.com/ideal-postcodes/openapi)
- [API Reference](https://openapi.ideal-postcodes.co.uk)
- [OpenAPI v3 JSON File](https://openapi.ideal-postcodes.co.uk/openapi.json)
- [OpenAPI v3 YAML File](https://openapi.ideal-postcodes.co.uk/openapi.yaml)
- [NPM Package](https://www.npmjs.com/package/@ideal-postcodes/openapi)
## 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.
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 the 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 identified 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 usable via the `available` property
- Determine available contexts for 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/UserTokenParam'
- $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/UserTokenParam'
- $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 organisation 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 ambiguous 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 thoroughfare or building name only? Are accurate organisation names an important feature?
operationId: AddressCleanse
parameters:
- $ref: '#/components/parameters/ApiKeyParam'
- $ref: '#/components/parameters/TagsParam'
- name: context
in: query
schema:
type: string
description: |
Identify the country of the address to cleanse. Defaults to UK (GBR)
example: usa
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"}'
/verify/addresses:
post:
tags:
- US
summary: Verify Address
description: |
The address verify API validates, corrects, and standardizes individual addresses based on USPS's Coding Accuracy Support System (CASS).
The address verify API accepts the 3 combination of inputs:
- Free-form address submitted as a single string in `query`
- Example: "123 Main St, Springfield, CO 81073-1119"
- Only free-form and zip code address components submitted as separate parameters:
- `query` for the first address line
- `zip_code` for the ZIP code
- Example:
- `query`: "123 Main St, Springfield CO"
- `zip_code`: "81073-1119"
- Only free-form, city and state address components submitted as separate parameters:
- `query` for the first address line
- `city` for the city
- `state` for the state
- Example:
- `query`: "123 Main St"
- `city`: "Springfield"
- `state`: "CO"
operationId: AddressVerify
parameters:
- $ref: '#/components/parameters/ApiKeyParam'
- $ref: '#/components/parameters/TagsParam'
- name: context
in: query
schema:
type: string
description: |
Identify the country of the address to verify. Defaults to United States (USA)
example: usa
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- query
properties:
query:
type: string
description: |
Address input to verify.
If submitting a freeform address verification query, enter the full address. E.g. `query=123 Main St, Springfield, CO, 81073`
Otherwise, query can be accompanied with the following address components:
- `zip_code`
- `city` and `state`
If zip_code or `city` and `state` or supplied, please omit this information from query by using it purely for the first address line. E.g. `query=123 Main St`
example: 123 Main St, Springfield, CO 81073
zip_code:
type: string
description: |
Specify the zip code of an address. The following formats are accepted: `81073-1119`, `810731119`, `81073`.
example: 81073-1119
city:
type: string
description: |
City of an address. For the US, this should be the city name.
example: Springfield
state:
type: string
description: |
State of an address. For the US, this should be in the 2 letter state abbreviation format.
example: CO
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/VerifyResponse'
'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/verify/addresses' \
-H 'Authorization: api_key="ak_test"'
-H 'Content-Type: application/json'
-d '{"query": "123 Main St, Springfield, IL 62701" }'
/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/DatasetParam'
- $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 identify 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
suggestions: []
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
- as
- 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
- ja
- ka
- kk
- km
- kn
- ko
- 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
- `usps` (USA) USPS Zip+4
- `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
- `herewe` (Western Europe) Western Europe Dataset
- `heret` (Taiwan) Taiwan Dataset
- `heresa` (South America) South America Dataset
- `hereo` (Oceania) Oceania Dataset
- `herena` (North America) North America Dataset
- `herei` (India) India Dataset
- `heremea` (Middle East and Africa) Middle East and Africa Dataset
- `herem` (Macau) Macau Dataset
- `herehk` (Hong Kong) Hong Kong Dataset
- `hereee` (Eastern Europe) Eastern Europe Dataset
- `hereap` (Asia Pacific) Asia Pacific Dataset
- `gnaf` (AUS) Geoscape Geocoded National Address File
- `kadaster` (NLD) Kadaster BAG 2.0 Address File
- `kartverket` (NOR) Norway Dataset
- `sdfi` (DNK) Denmark Dataset
- `cannar` (CAN) Canada National Address Register Dataset
- `fodbosa` (BEL) Belgium Dataset
- `mois` (KOR) South Korea Dataset
- `upujp` (JPN) Japan UPU Address File
- `bev` (AUT) Austria Dataset
enum:
- paf
- pafw
- pafa
- mr
- nyb
- usps
- ecaf
- ecad
- ab
- herewe
- heret
- heresa
- hereo
- herena
- heremeas
- heremea
- herem
- herei
- herehk
- hereee
- hereap
- gnaf
- kadaster
- kartverket
- sdfi
- cannar
- fodbosa
- mois
- upujp
- bev
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
- LTU
- LVA
- MDA
- MKD
- MNE
- POL
- ROU
- RUS
- SRB
- SVK
- SVN
- TUR
- UKR
- UZB
- XKX
- 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
nullable: true
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
- poi_name
- building_unit_name
- level_name
- unit_name
- suppl_address_info
- building_grp_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: ''
poi_name:
type: string
description: Name of the point of interest associated with the address.
example: Abbazia San Severo
building_unit_name:
type: string
description: Name of the Building associated with a Micro Point Address.
example: M193
level_name:
type: string
description: Name of floor or level within a building associated with a Micro Point Address.
example: '3'
unit_name:
type: string
description: Name of the unit (suite, etc) associated with a Micro Point Address.
example: 30A
suppl_address_info:
type: string
description: Additional address or building information.
example: Ballyboughal Post Office
building_grp_name:
type: string
description: Name of the group of buildings with which the address is associated.
example: Windgate Cottages
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
KadasterAddress:
required:
- id
- dataset
- country
- country_iso
- country_iso_2
- line_1
- language
- address
- identificatie
- latitude
- longitude
- gebruiksdoel
- oppervlakte
- status
- geconstateerd
- documentdatum
- documentnummer
- voorkomenidentificatie
- begin_geldigheid
- eind_geldigheid
- tijdstip_registratie
- eind_registratie
- tijdstip_registratie_lv
- tijdstip_eind_registratie_lv
- nummeraanduidingen_identificatie
- nummeraanduidingen_huisnummer
- nummeraanduidingen_huisnummertoevoeging
- nummeraanduidingen_huisletter
- nummeraanduidingen_postcode
- nummeraanduidingen_type_adresseerbaar_object
- nummeraanduidingen_status
- nummeraanduidingen_geconstateerd
- nummeraanduidingen_documentdatum
- nummeraanduidingen_documentnummer
- nummeraanduidingen_voorkomenidentificatie
- nummeraanduidingen_begin_geldigheid
- nummeraanduidingen_eind_geldigheid
- nummeraanduidingen_tijdstip_registratie
- nummeraanduidingen_eind_registratie
- nummeraanduidingen_tijdstip_registratie_lv
- nummeraanduidingen_tijdstip_eind_registratie_lv
- pand_identificatie
- pand_oorspronkelijk_bouwjaar
- pand_status
- pand_geconstateerd
- pand_documentdatum
- pand_documentnummer
- pand_voorkomenidentificatie
- pand_begin_geldigheid
- pand_eind_geldigheid
- pand_tijdstip_registratie
- pand_eind_registratie
- pand_tijdstip_registratie_lv
- pand_tijdstip_eind_registratie_lv
- openbare_ruimte_identificatie
- openbare_ruimte_naam
- openbare_ruimte_type
- openbare_ruimte_status
- openbare_ruimte_geconstateerd
- openbare_ruimte_documentdatum
- openbare_ruimte_documentnummer
- openbare_ruimte_voorkomenidentificatie
- openbare_ruimte_begin_geldigheid
- openbare_ruimte_eind_geldigheid
- openbare_ruimte_tijdstip_registratie
- openbare_ruimte_eind_registratie
- openbare_ruimte_tijdstip_registratie_lv
- openbare_ruimte_tijdstip_eind_registratie_lv
- openbare_ruimte_verkorte_naam
- woonplaats_identificatie
- woonplaats_naam
- woonplaats_status
- woonplaats_geconstateerd
- woonplaats_documentdatum
- woonplaats_documentnummer
- woonplaats_voorkomenidentificatie
- woonplaats_begin_geldigheid
- woonplaats_eind_geldigheid
- woonplaats_tijdstip_registratie
- woonplaats_eind_registratie
- woonplaats_tijdstip_registratie_lv
- woonplaats_tijdstip_eind_registratie_lv
- provincie
properties:
id:
$ref: '#/components/schemas/ID'
dataset:
type: string
enum:
- kadaster
country_iso:
description: |2
3 letter country code (ISO 3166-1)
enum:
- NLD
country_iso_2:
type: string
description: |2
2 letter country code (ISO 3166-1)
enum:
- NL
country:
type: string
description: |2
Full country names (ISO 3166)
enum:
- Netherlands
line_1:
type: string
description: |
First address line.
Can be empty string `""` if not present.
example: Herengracht 255
language:
enum:
- nl
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: '255'
longitude:
$ref: '#/components/schemas/Longitude'
latitude:
$ref: '#/components/schemas/Latitude'
identificatie:
type: string
description: |
The unique identifier of a BAG verblijfsobject.
gebruiksdoel:
type: string
description: |
The purpose of use of the verblijfsobject.
oppervlakte:
type: number
description: |
The area of the verblijfsobject in square metres.
status:
type: string
description: |
Verblijfsobject status.
geconstateerd:
type: boolean
description: |
Indicates that a verblijfsobject has been included in the registry as a result of an observation, without there being a regular source document for this inclusion at the time of registration.
documentdatum:
type: string
format: date
description: |
Date on which the verblijfsobject source document was created.
documentnummer:
type: string
description: |
The unique identifier of the verblijfsobject source document.
voorkomenidentificatie:
oneOf:
- type: string
description: Empty string `""` if not available
- type: number
description: |
The identifier of this instance of the verblijfsobject history.
begin_geldigheid:
type: string
format: date
description: |
The time at which a version of a verblijfsobject is valid in reality in accordance with the effective date in the source document.
eind_geldigheid:
type: string
format: date
description: |
The time at which a version of a verblijfsobject is no longer valid in reality. Empty string `""` if not applicable.
tijdstip_registratie:
type: string
format: date
description: |
The time at which a version of a verblijfsobject is registered by the bronhouder.
eind_registratie:
type: string
format: date
description: |
The time at which a version of a verblijfsobject is no longer valid according to the bronhouder. Empty string `""` if not applicable.
tijdstip_registratie_lv:
type: string
format: date
description: |
The time at which a version of a verblijfsobject is registered in the Landelijke Voorziening BAG.
tijdstip_eind_registratie_lv:
type: string
format: date
description: |
The time at which a version of a verblijfsobject is no longer valid in the Landelijke Voorziening BAG. Empty string `""` if not applicable.
nummeraanduidingen_identificatie:
type: string
description: |
The unique identifier of a BAG nummeraanduiding object.
nummeraanduidingen_huisnummer:
type: string
description: |
The house number assigned to a nummeraanduiding object by or on behalf of the municipal council.
nummeraanduidingen_huisnummertoevoeging:
type: string
description: |
A further addition to a house number or a combination of house number and house letter granted by or on behalf of the municipal council with regard to a nummeraanduiding object.
nummeraanduidingen_huisletter:
type: string
description: |
An addition to a house number in the form of an alphanumeric character assigned by or on behalf of the municipal council with regard to a nummeraanduiding object.
nummeraanduidingen_postcode:
type: string
description: |
A code determined by PostNL associated with a specific combination of a street name and a house number.
nummeraanduidingen_type_adresseerbaar_object:
type: string
description: |
The nature of the nummeraanduiding object.
nummeraanduidingen_status:
type: string
description: |
The status of the nummeraanduiding object.
nummeraanduidingen_geconstateerd:
type: boolean
description: |
Indicates that a nummeraanduidingen object has been included in the registry as a result of an observation, without there being a regular source document for this inclusion at the time of registration.
nummeraanduidingen_documentdatum:
type: string
format: date
description: |
Date on which the nummeraanduidingen object source document was created.
nummeraanduidingen_documentnummer:
type: string
description: |
The unique identifier of the nummeraanduidingen object source document.
nummeraanduidingen_voorkomenidentificatie:
oneOf:
- type: string
description: Empty string `""` if not available
- type: number
description: |
The identifier of this instance of the nummeraanduidingen object history.
nummeraanduidingen_begin_geldigheid:
type: string
format: date
description: |
The time at which a version of a nummeraanduidingen object is valid in reality in accordance with the effective date in the source document.
nummeraanduidingen_eind_geldigheid:
type: string
format: date
description: |
The time at which a version of a nummeraanduidingen object is no longer valid in reality. Empty string `""` if not applicable.
nummeraanduidingen_tijdstip_registratie:
type: string
format: date
description: |
The time at which a version of a nummeraanduidingen object is registered by the bronhouder.
nummeraanduidingen_eind_registratie:
type: string
format: date
description: |
The time at which a version of a nummeraanduidingen object is no longer valid according to the bronhouder. Empty string `""` if not applicable.
nummeraanduidingen_tijdstip_registratie_lv:
type: string
format: date
description: |
The time at which a version of a nummeraanduidingen object is registered in the Landelijke Voorziening BAG.
nummeraanduidingen_tijdstip_eind_registratie_lv:
type: string
format: date
description: |
The time at which a version of a nummeraanduidingen object is no longer valid in the Landelijke Voorziening BAG. Empty string `""` if not applicable.
pand_identificatie:
type: string
description: |
The unique identifier of a BAG pand object.
pand_oorspronkelijk_bouwjaar:
oneOf:
- type: string
description: Empty string `""` if not available
- type: number
description: |
The year in which a building was or will be originally completed.
pand_status:
type: string
description: |
The status of the pand object.
pand_geconstateerd:
type: boolean
description: |
Indicates that a pand object has been included in the registry as a result of an observation, without there being a regular source document for this inclusion at the time of registration.
pand_documentdatum:
type: string
format: date
description: |
Date on which the pand object source document was created.
pand_documentnummer:
type: string
description: |
The unique identifier of the pand object source document.
pand_voorkomenidentificatie:
oneOf:
- type: string
description: Empty string `""` if not available
- type: number
description: |
The identifier of this instance of the pand object history.
pand_begin_geldigheid:
type: string
format: date
description: |
The time at which a version of a pand object is valid in reality in accordance with the effective date in the source document.
pand_eind_geldigheid:
type: string
format: date
description: |
The time at which a version of a pand object is no longer valid in reality. Empty string `""` if not applicable.
pand_tijdstip_registratie:
type: string
format: date
description: |
The time at which a version of a pand object is registered by the bronhouder.
pand_eind_registratie:
type: string
format: date
description: |
The time at which a version of a pand object is no longer valid according to the bronhouder. Empty string `""` if not applicable.
pand_tijdstip_registratie_lv:
type: string
format: date
description: |
The time at which a version of a pand object is registered in the Landelijke Voorziening BAG.
pand_tijdstip_eind_registratie_lv:
type: string
format: date
description: |
The time at which a version of a pand object is no longer valid in the Landelijke Voorziening BAG. Empty string `""` if not applicable.
openbare_ruimte_identificatie:
type: string
description: |
The unique identifier of a BAG openbare ruimte object.
openbare_ruimte_naam:
type: string
description: |
The name assigned to an openbare ruimte object by or on behalf of the municipal council.
openbare_ruimte_type:
type: string
description: |
The nature of the openbare ruimte object.
openbare_ruimte_status:
type: string
description: |
The status of the openbare ruimte object.
openbare_ruimte_geconstateerd:
type: boolean
description: |
Indicates that an openbare ruimte object has been included in the registry as a result of an observation, without there being a regular source document for this inclusion at the time of registration.
openbare_ruimte_documentdatum:
type: string
format: date
description: |
Date on which the openbare ruimte object source document was created.
openbare_ruimte_documentnummer:
type: string
description: |
The unique identifier of the openbare ruimte object source document.
openbare_ruimte_voorkomenidentificatie:
oneOf:
- type: string
description: Empty string `""` if not available
- type: number
description: |
The identifier of this instance of the openbare ruimte object history.
openbare_ruimte_begin_geldigheid:
type: string
format: date
description: |
The time at which a version of an openbare ruimte object is valid in reality in accordance with the effective date in the source document.
openbare_ruimte_eind_geldigheid:
type: string
format: date
description: |
The time at which a version of an openbare ruimte object is no longer valid in reality. Empty string `""` if not applicable.
openbare_ruimte_tijdstip_registratie:
type: string
format: date
description: |
The time at which a version of an openbare ruimte object is registered by the bronhouder.
openbare_ruimte_eind_registratie:
type: string
format: date
description: |
The time at which a version of an openbare ruimte object is no longer valid according to the bronhouder. Empty string `""` if not applicable.
openbare_ruimte_tijdstip_registratie_lv:
type: string
format: date
description: |
The time at which a version of an openbare ruimte object is registered in the Landelijke Voorziening BAG.
openbare_ruimte_tijdstip_eind_registratie_lv:
type: string
format: date
description: |
The time at which a version of an openbare ruimte object is no longer valid in the Landelijke Voorziening BAG. Empty string `""` if not applicable.
openbare_ruimte_verkorte_naam:
type: string
description: |
An abbreviated name assigned to an openbare ruimte object if its name is longer than 24 characters.
woonplaats_identificatie:
type: string
description: |
The unique identifier of a BAG woonplaats object.
woonplaats_naam:
type: string
description: |
The name assigned to a woonplaats object by or on behalf of the municipal council.
woonplaats_status:
type: string
description: |
The status of the woonplaats object.
woonplaats_geconstateerd:
type: boolean
description: |
Indicates that a woonplaats object has been included in the registry as a result of an observation, without there being a regular source document for this inclusion at the time of registration.
woonplaats_documentdatum:
type: string
format: date
description: |
Date on which the woonplaats object source document was created.
woonplaats_documentnummer:
type: string
description: |
The unique identifier of the woonplaats object source document.
woonplaats_voorkomenidentificatie:
oneOf:
- type: string
description: Empty string `""` if not available
- type: number
description: |
The identifier of this instance of the woonplaats object history.
woonplaats_begin_geldigheid:
type: string
format: date
description: |
The time at which a version of a woonplaats object is valid in reality in accordance with the effective date in the source document.
woonplaats_eind_geldigheid:
type: string
format: date
description: |
The time at which a version of a woonplaats object is no longer valid in reality. Empty string `""` if not applicable.
woonplaats_tijdstip_registratie:
type: string
format: date
description: |
The time at which a version of a woonplaats object is registered by the bronhouder.
woonplaats_eind_registratie:
type: string
format: date
description: |
The time at which a version of a woonplaats object is no longer valid according to the bronhouder. Empty string `""` if not applicable.
woonplaats_tijdstip_registratie_lv:
type: string
format: date
description: |
The time at which a version of a woonplaats object is registered in the Landelijke Voorziening BAG.
woonplaats_tijdstip_eind_registratie_lv:
type: string
format: date
description: |
The time at which a version of a woonplaats object is no longer valid in the Landelijke Voorziening BAG. Empty string `""` if not applicable.
provincie:
type: string
description: |
The province name.
KartverketAddress:
required:
- id
- dataset
- country
- country_iso
- country_iso_2
- line_1
- line_2
- language
- address
- latitude
- longitude
- lokal_id
- kommunenummer
- kommunenavn
- adressetype
- adressetilleggsnavn
- adressetilleggsnavn_kilde
- adressekode
- adressenavn
- nummer
- bokstav
- gardsnummer
- bruksnummer
- festenummer
- seksjonsnummer
- undernummer
- adresse_tekst
- adresse_tekst_uten_adressetilleggsnavn
- bruksenhet_id
- bruksenhetsnummer_tekst
- offisiell_adresse_tekst
- offisiell_adresse_tekst_uten_adressetilleggsnavn
- epsg_kode
- nord
- oest
- postnummer
- poststed
- grunnkretsnummer
- grunnkretsnavn
- soknenummer
- soknenavn
- organisasjonsnummer
- tettstednummer
- tettstednavn
- valgkretsnummer
- valgkretsnavn
- oppdateringsdato
- datauttaksdato
- adresse_id
- uuid_adresse
- uuid_bruksenhet
- atkomst_id
- uuid_atkomst
- atkomst_nord
- atkomst_oest
- sommeratkomst_id
- uuid_sommeratkomst
- sommeratkomst_nord
- sommeratkomst_oest
- vinteratkomst_id
- uuid_vinteratkomst
- vinteratkomst_nord
- vinteratkomst_oest
- fylke
- landsdel
properties:
id:
$ref: '#/components/schemas/ID'
dataset:
type: string
enum:
- kartverket
country_iso:
description: |2
3 letter country code (ISO 3166-1)
enum:
- NOR
- SJM
country_iso_2:
type: string
description: |2
2 letter country code (ISO 3166-1)
enum:
- 'NO'
- SJ
country:
type: string
description: |2
Full country names (ISO 3166)
enum:
- Norway
- Svalbard and Jan Mayen
line_1:
type: string
description: |
First address line.
Can be empty string `""` if not present.
example: Lerkevegen 5
line_2:
type: string
description: |
Second address line.
Can be empty string `""` if not present.
example: ''
language:
enum:
- 'no'
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'
lokal_id:
type: string
description: |
Local identifier assigned by the data supplier.
Can be empty string `""` if not present.
kommunenummer:
type: string
description: |
Kommune (municipality) number.
kommunenavn:
type: string
description: |
Kommune (municipality) name.
adressetype:
type: string
description: |
`vegadresse` = street address, `matrikkeladresse` = land registry address
adressetilleggsnavn:
type: string
description: |
A local place name used in a road address.
Can be empty string `""` if not present.
adressetilleggsnavn_kilde:
type: string
description: |
Code for adressetilleggsnavn origin.
Can be empty string `""` if not present.
adressekode:
oneOf:
- type: string
description: Empty string `""` if not available
- type: number
description: |
A number that uniquely identifies addressable streets, roads, paths, places and areas that are entered in the land register.
adressenavn:
type: string
description: |
Name of street, road, path, place or area entered in the land register.
Can be empty string `""` if not present.
nummer:
oneOf:
- type: string
description: Empty string `""` if not available
- type: number
description: |
A number that uniquely identifies properties, facilities, buildings or entrances to buildings within an addressable street, road, path, place or area.
bokstav:
type: string
description: |
A subsequent letter that may be used in addition to a number.
Can be empty string `""` if not present.
gardsnummer:
type: number
description: |
The number of a farm unit in the land register, unique within each municipality.
bruksnummer:
type: number
description: |
A unique identification number automatically assigned to each individual unit within a farm.
festenummer:
oneOf:
- type: string
description: Empty string `""` if not available
- type: number
description: |
The number of a fixture within a gardsnummer/bruksnummer.
seksjonsnummer:
oneOf:
- type: string
description: Empty string `""` if not available
- type: number
description: |
The number of a section within a gardsnummer/bruksnummer and possibly a festenummer.
undernummer:
oneOf:
- type: string
description: Empty string `""` if not available
- type: number
description: |
A sub-number within a gardsnummer, bruksnummer and festenummer.
adresse_tekst:
type: string
description: |
Official address text without bruksenhetsnummer, unique within a kommune.
Can be empty string `""` if not present.
adresse_tekst_uten_adressetilleggsnavn:
type: string
description: |
Official address text without bruksenhetsnummer and adressetilleggsnavn, unique within a kommune.
Can be empty string `""` if not present.
bruksenhet_id:
type: string
description: |
Local identifier for a unit within a building.
Can be empty string `""` if not present.
bruksenhetsnummer_tekst:
type: string
description: |
Unit number, e.g. an apartment in a multi-dwelling building.
Can be empty string `""` if not present.
offisiell_adresse_tekst:
type: string
description: |
Official address text with bruksenhetsnummer, unique within a kommune.
Can be empty string `""` if not present.
offisiell_adresse_tekst_uten_adressetilleggsnavn:
type: string
description: |
Official address text with bruksenhetsnummer and without adressetilleggsnavn, unique within a kommune.
Can be empty string `""` if not present.
epsg_kode:
type: number
description: |
EPSG code = `25833`.
nord:
type: string
description: |
Northward coordinate of address.
oest:
type: string
description: |
Eastward coordinate of address.
postnummer:
type: string
description: |
Postal code.
poststed:
type: string
description: |
Name of postal town according to Posten.
grunnkretsnummer:
type: string
description: |
Identifier consisting of 8 digits, where the first four are the kommunenummer, the next two are the delområdenummer and the last two indicate the grunnkrets.
Can be empty string `""` if not present.
grunnkretsnavn:
type: string
description: |
Official grunnkrets name from Statistics Norway (SSB).
Can be empty string `""` if not present.
soknenummer:
type: string
description: |
Unique 8 digit identifier of a parish.
Can be empty string `""` if not present.
soknenavn:
type: string
description: |
Parish name.
Can be empty string `""` if not present.
organisasjonsnummer:
type: string
description: |
Unique identifier of organisation in the Brønnøysund Register.
Can be empty string `""` if not present.
tettstednummer:
type: string
description: |
4 digit code for tettsted (urban settlement).
Can be empty string `""` if not present.
tettstednavn:
type: string
description: |
Name of tettsted (urban settlement).
Can be empty string `""` if not present.
valgkretsnummer:
oneOf:
- type: string
description: Empty string `""` if not available
- type: number
description: |
Constituency code within a kommune.
valgkretsnavn:
type: string
description: |
Name of constituency.
Can be empty string `""` if not present.
oppdateringsdato:
type: string
description: |
Date of last change to the object data.
datauttaksdato:
type: string
description: |
Date of extraction from database.
adresse_id:
type: string
description: |
Address local identifier assigned by the data supplier.
uuid_adresse:
type: string
description: |
Address identifier realized as UUID managed by the cadastral system.
uuid_bruksenhet:
type: string
description: |
Unit of usage identifier realized as UUID managed by the cadastral system.
Can be empty string `""` if not present.
atkomst_id:
type: string
description: |
Local identifier for means of access to a property.
Can be empty string `""` if not present.
uuid_atkomst:
type: string
description: |
Identifier of the means of access to a property realized as UUID in the cadastral system.
Can be empty string `""` if not present.
atkomst_nord:
type: string
description: |
Northward coordinate of the means of access to a property.
Can be empty string `""` if not present.
atkomst_oest:
type: string
description: |
Eastward coordinate of the means of access to a property.
Can be empty string `""` if not present.
sommeratkomst_id:
type: string
description: |
Local identifier for means of access to a property in summer.
Can be empty string `""` if not present.
uuid_sommeratkomst:
type: string
description: |
Identifier of the means of access to a property in summer realized as UUID in the cadastral system.
Can be empty string `""` if not present.
sommeratkomst_nord:
type: string
description: |
Northward coordinate of the means of access to a property in summer.
Can be empty string `""` if not present.
sommeratkomst_oest:
type: string
description: |
Eastward coordinate of the means of access to a property in summer.
Can be empty string `""` if not present.
vinteratkomst_id:
type: string
description: |
Local identifier for means of access to a property in winter.
Can be empty string `""` if not present.
uuid_vinteratkomst:
type: string
description: |
Identifier of the means of access to a property in winter realized as UUID in the cadastral system.
Can be empty string `""` if not present.
vinteratkomst_nord:
type: string
description: |
Northward coordinate of the means of access to a property in winter.
Can be empty string `""` if not present.
vinteratkomst_oest:
type: string
description: |
Eastward coordinate of the means of access to a property in winter.
Can be empty string `""` if not present.
fylke:
type: string
description: |
Name of county.
landsdel:
type: string
description: |
Name of region.
SdfiAddress:
required:
- id
- dataset
- country
- country_iso
- country_iso_2
- line_1
- line_2
- language
- address
- latitude
- longitude
- adresse_id
- kvhx
- kvh
- adgangsadresse
- status
- darstatus
- oprettet
- ændret
- ikrafttrædelse
- nedlagt
- vejkode
- vejnavn
- adresseringsvejnavn
- husnr
- etage
- dør
- supplerendebynavn_dagi_id
- supplerendebynavn
- postnr
- postnrnavn
- stormodtagerpostnr
- stormodtagerpostnrnavn
- betegnelse
- adressepunktændringsdato
- etrs89koordinat_øst
- etrs89koordinat_nord
- wgs84koordinat_bredde
- wgs84koordinat_længde
- højde
- nøjagtighed
- kilde
- tekniskstandard
- tekstretning
- ddkn_m100
- ddkn_km1
- ddkn_km10
- kommunekode
- kommunenavn
- landsdelsnuts3
- landsdelsnavn
- regionskode
- regionsnavn
- afstemningsområdenummer
- afstemningsområdenavn
- menighedsrådsafstemningsområdenummer
- menighedsrådsafstemningsområdenavn
- opstillingskredskode
- opstillingskredsnavn
- storkredsnummer
- storkredsnavn
- valglandsdelsbogstav
- valglandsdelsnavn
- sognekode
- sognenavn
- politikredskode
- politikredsnavn
- retskredskode
- retskredsnavn
- jordstykke_ejerlavkode
- jordstykke_ejerlavnavn
- jordstykke_matrikelnr
- jordstykke_esrejendomsnr
- ejerlavkode
- ejerlavnavn
- matrikelnr
- esrejendomsnr
- zone
- brofast
- adgangsadresseid
- adgangspunktid
- navngivenvej_id
- adgangsadresse_status
- adgangsadresse_darstatus
- adgangsadresse_oprettet
- adgangsadresse_ændret
- adgangsadresse_ikrafttrædelse
- adgangsadresse_nedlagt
- vejpunkt_id
- vejpunkt_ændret
- vejpunkt_kilde
- vejpunkt_nøjagtighed
- vejpunkt_tekniskstandard
- vejpunkt_x
- vejpunkt_y
properties:
id:
$ref: '#/components/schemas/ID'
dataset:
type: string
enum:
- sdfi
country_iso:
description: |2
3 letter country code (ISO 3166-1)
enum:
- DNK
country_iso_2:
type: string
description: |2
2 letter country code (ISO 3166-1)
enum:
- DK
country:
type: string
description: |2
Full country names (ISO 3166)
enum:
- Denmark
line_1:
type: string
description: |
First address line.
Can be empty string `""` if not present.
example: Bakkevej 3
line_2:
type: string
description: |
Second address line.
Can be empty string `""` if not present.
example: Pindstrup
language:
enum:
- da
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'
adresse_id:
type: string
description: |
Unique address identifier assigned by the data supplier.
kvhx:
type: string
description: |
Unique composite key for the address, containing codes for the municipality, road section, house number, floor and door.
Can be empty string `""` if not present.
kvh:
type: string
description: |
Composite key for the address, containing codes for the municipality, road section and house number.
Can be empty string `""` if not present.
adgangsadresse:
type: boolean
description: |
Indicates whether the address is an access address.
status:
type: string
description: |
`1` = final address, `3` = provisional address.
darstatus:
type: string
description: |
Status of the address indicated by the status code in Danmarks Adresseregister (DAR): `2` = provisional, `3` = valid, `4` = retired, `5` = suspended.
oprettet:
type: string
description: |
Date and time of address creation in Danmarks Adresseregister (DAR).
Can be empty string `""` if not present.
ændret:
type: string
description: |
Date and time of the last change to the address in Danmarks Adresseregister (DAR).
Can be empty string `""` if not present.
ikrafttrædelse:
type: string
description: |
Date and time at which the address became valid.
Can be empty string `""` if not present.
nedlagt:
type: string
description: |
Date and time from which the address is retired or suspended (may be in the future).
Can be empty string `""` if not present.
vejkode:
type: string
description: |
Four digit street identifier.
vejnavn:
type: string
description: |
Street name.
adresseringsvejnavn:
type: string
description: |
A possibly shortened version of the street name of no more than 20 characters, used where there is no space for the full street name.
husnr:
type: string
description: |
House number.
etage:
type: string
description: |
Floor designation.
Can be empty string `""` if not present.
dør:
type: string
description: |
Door designation.
Can be empty string `""` if not present.
supplerendebynavn_dagi_id:
type: string
description: |
Unique identifier in Danmarks Administrative Geografiske Inddeling (DAGI) of the supplementary town or city name.
Can be empty string `""` if not present.
supplerendebynavn:
type: string
description: |
Supplementary city name.
Can be empty string `""` if not present.
postnr:
type: string
description: |
Postal code.
postnrnavn:
type: string
description: |
The city or district name associated with the postal code.
stormodtagerpostnr:
type: string
description: |
Bulk recipient postal code (company postal code) which is associated with the address.
Can be empty string `""` if not present.
stormodtagerpostnrnavn:
type: string
description: |
The city or district name associated with the bulk recipient postal code.
Can be empty string `""` if not present.
betegnelse:
type: string
description: |
Full text of postal address.
adressepunktændringsdato:
type: string
description: |
Date and time of the last change to the address point.
Can be empty string `""` if not present.
etrs89koordinat_øst:
type: string
description: |
Easting coordinate for the address in the ETRS89 system.
etrs89koordinat_nord:
type: string
description: |
Northing coordinate for the address in the ETRS89 system.
wgs84koordinat_bredde:
description: |
Latitude of the address in the WGS84 system.
Can be empty string `""` if not present.
oneOf:
- type: string
- type: number
minimum: -90
maximum: 90
example: 55.06428998
wgs84koordinat_længde:
description: |
Longitude of the address in the WGS84 system.
Can be empty string `""` if not present.
oneOf:
- type: string
- type: number
minimum: -180
maximum: 180
example: 15.13688626
højde:
type: string
description: |
Height in metres from the mean water level in the seas on Denmark's coasts to ground level at the address, calculated according to the Danish Vertical Reference 1990 (DVR90).
Can be empty string `""` if not present.
nøjagtighed:
type: string
description: |
Code indicating the accuracy of the address point. `A` = accurate to within 2 metres, `B` = accurate to within 100 metres, `U` = no address point.
kilde:
type: string
description: |
Code indicating the source of the address point.
Can be empty string `""` if not present.
tekniskstandard:
type: string
description: |
Technical classification code for the location of an address point.
tekstretning:
type: string
description: |
Orientation for an address in gons, where a full circle is divided into 400 gons.
ddkn_m100:
type: string
description: |
Identifier of the 100m cell in which the address is located in Det Danske Kvadratnet (DDKN).
ddkn_km1:
type: string
description: |
Identifier of the 1km cell in which the address is located in Det Danske Kvadratnet (DDKN).
ddkn_km10:
type: string
description: |
Identifier of the 10km cell in which the address is located in Det Danske Kvadratnet (DDKN).
kommunekode:
type: string
description: |
Four digit identifier of the municipality in which the address is located.
kommunenavn:
type: string
description: |
Name of the municipality in which the address is located.
landsdelsnuts3:
type: string
description: |
NUTS 3 code of the province in which the address is located.
landsdelsnavn:
type: string
description: |
Name of the province in which the address is located.
regionskode:
type: string
description: |
Four digit identifier of the region in which the address is located.
regionsnavn:
type: string
description: |
Name of the region in which the address is located.
afstemningsområdenummer:
type: string
description: |
Identifier of the polling district in which the address is located.
afstemningsområdenavn:
type: string
description: |
Unique name of the polling district in which the address is located.
menighedsrådsafstemningsområdenummer:
type: string
description: |
Identifier of the parish council polling district in which the address is located.
Can be empty string `""` if not present.
menighedsrådsafstemningsområdenavn:
type: string
description: |
Name of the parish council polling district in which the address is located.
Can be empty string `""` if not present.
opstillingskredskode:
type: string
description: |
Identifier of the local electoral district in which the address is located.
opstillingskredsnavn:
type: string
description: |
Name of the local electoral district in which the address is located.
storkredsnummer:
type: string
description: |
Identifier of the regional electoral district in which the address is located.
storkredsnavn:
type: string
description: |
Name of the regional electoral district in which the address is located.
valglandsdelsbogstav:
type: string
description: |
Letter identifier of the national electoral district in which the address is located: `A`, `B` or `C`.
valglandsdelsnavn:
type: string
description: |
Name of the national electoral district in which the address is located.
sognekode:
type: string
description: |
Identifier of the parish in which the address is located.
sognenavn:
type: string
description: |
Name of the parish in which the address is located.
politikredskode:
type: string
description: |
Identifier of the police district in which the address is located.
politikredsnavn:
type: string
description: |
Name of the police district in which the address is located.
retskredskode:
type: string
description: |
Four digit identifier of the judicial district in which the address is located.
retskredsnavn:
type: string
description: |
Name of the judicial district in which the address is located.
jordstykke_ejerlavkode:
type: string
description: |
Identifier of a cadastral unit with a single owner.
Can be empty string `""` if not present.
jordstykke_ejerlavnavn:
type: string
description: |
Name of a cadastral unit with a single owner.
Can be empty string `""` if not present.
jordstykke_matrikelnr:
type: string
description: |
Cadastre identifier for the plot of land on which the address is located, consisting of up to 7 characters.
Can be empty string `""` if not present.
jordstykke_esrejendomsnr:
type: string
description: |
Identifier for the property from the Ejendomsstamregisteret (ESR) property register, corresponding to the plot of land associated with the address, consisting of up to 7 characters.
Can be empty string `""` if not present.
ejerlavkode:
type: string
description: |
Identifier of a cadastral unit with a single owner (deprecated).
Can be empty string `""` if not present.
ejerlavnavn:
type: string
description: |
Name of a cadastral unit with a single owner (deprecated).
Can be empty string `""` if not present.
matrikelnr:
type: string
description: |
Cadastre identifier for the plot of land on which the address is located, consisting of up to 7 characters.
Can be empty string `""` if not present.
esrejendomsnr:
type: string
description: |
Identifier for the property from the Ejendomsstamregisteret (ESR) property register, corresponding to the plot of land associated with the address, consisting of up to 7 characters.
Can be empty string `""` if not present.
zone:
type: string
description: |
Status of the address zone: `Byzone`, `Sommerhusområde` or `Landzone`.
brofast:
type: boolean
description: |
Indicates whether the address is connected by a bridge.
adgangsadresseid:
type: string
description: |
Identifier of the access address associated with the address.
Can be empty string `""` if not present.
adgangspunktid:
type: string
description: |
Identifier of the access point for the address.
navngivenvej_id:
type: string
description: |
Identifier of the named road on which the access address is located.
adgangsadresse_status:
type: string
description: |
Status of the access address associated with the address: `1` = final address, `3` = provisional address.
adgangsadresse_darstatus:
type: string
description: |
Status of the access address indicated by the status code in Danmarks Adresseregister (DAR): `2` = provisional, `3` = valid, `4` = retired, `5` = suspended.
Can be empty string `""` if not present.
adgangsadresse_oprettet:
type: string
description: |
Date and time of the creation of the access address associated with the address.
Can be empty string `""` if not present.
adgangsadresse_ændret:
type: string
description: |
Date and time of the last change to the access address associated with the address.
Can be empty string `""` if not present.
adgangsadresse_ikrafttrædelse:
type: string
description: |
Date and time at which the access address became valid.
Can be empty string `""` if not present.
adgangsadresse_nedlagt:
type: string
description: |
Date and time from which the access address is retired or suspended (may be in the future).
Can be empty string `""` if not present.
vejpunkt_id:
type: string
description: |
Unique identifier of the geographic point on the road network that represents the starting point of the access route leading to the access point for the address.
vejpunkt_ændret:
type: string
description: |
Date and time of the last change in Danmarks Adresseregister (DAR) to the geographic point on the road network that represents the starting point of the access route leading to the access point for the address.
Can be empty string `""` if not present.
vejpunkt_kilde:
type: string
description: |
Source of the geographic point on the road network that represents the starting point of the access route leading to the access point for the address.
vejpunkt_nøjagtighed:
type: string
description: |
Accuracy of the geographic point on the road network that represents the starting point of the access route leading to the access point for the address: `A` = exact, `B` = approximate.
vejpunkt_tekniskstandard:
type: string
description: |
Technical classification code for the geographic point on the road network that represents the starting point of the access route leading to the access point for the address.
vejpunkt_x:
type: string
description: |
Longitude in the WGS84 system of the geographic point on the road network that represents the starting point of the access route leading to the access point for the address.
vejpunkt_y:
type: string
description: |
Latitude in the WGS84 system of the geographic point on the road network that represents the starting point of the access route leading to the access point for the address.
CannarAddress:
required:
- id
- dataset
- country
- country_iso
- country_iso_2
- language
- address
- line_1
- line_2
- latitude
- longitude
- loc_guid
- addr_guid
- apt_no_label
- civic_no
- civic_no_suffix
- official_street_name
- official_street_type
- official_street_dir
- prov_code
- csd_eng_name
- csd_fre_name
- csd_type_eng_code
- csd_type_fre_code
- mail_street_name
- mail_street_type
- mail_street_dir
- mail_mun_name
- mail_prov_abvn
- mail_postal_code
- bg_dls_lsd
- bg_dls_qtr
- bg_dls_sctn
- bg_dls_twnshp
- bg_dls_rng
- bg_dls_mrd
- bg_x
- bg_y
- bu_n_civic_add
- bu_use
- csd_code
- fed_code
- fed_eng_name
- fed_fre_name
- er_code
- er_eng_name
- er_fre_name
- reppoint_latitude
- reppoint_longitude
properties:
id:
$ref: '#/components/schemas/ID'
dataset:
type: string
enum:
- cannar
country_iso:
description: |2
3 letter country code (ISO 3166-1)
enum:
- CAN
country_iso_2:
type: string
description: |2
2 letter country code (ISO 3166-1)
enum:
- CA
country:
type: string
description: |2
Full country names (ISO 3166)
enum:
- Canada
line_1:
type: string
description: |
First address line.
Can be empty string `""` if not present.
example: 38 Deane St
line_2:
type: string
description: |
Second address line.
Can be empty string `""` if not present.
example: RR 4
language:
enum:
- en
- fr
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'
loc_guid:
type: string
description: |
Globally unique identifier for location.
addr_guid:
type: string
description: |
Globally unique identifier for address.
apt_no_label:
type: string
description: |
Apartment or suite number.
Can be empty string `""` if not present.
civic_no:
type: string
description: |
The building number assigned to the address.
Can be empty string `""` if not present.
civic_no_suffix:
type: string
description: |
A suffix attached to the civic number.
Can be empty string `""` if not present.
official_street_name:
type: string
description: |
Official street name.
Can be empty string `""` if not present.
official_street_type:
type: string
description: |
Official street designator.
Can be empty string `""` if not present.
official_street_dir:
type: string
description: |
Official street direction.
Can be empty string `""` if not present.
prov_code:
type: string
description: |
Province code.
csd_eng_name:
type: string
description: |
Census subdivision English name.
Can be empty string `""` if not present.
csd_fre_name:
type: string
description: |
Census subdivision French name.
Can be empty string `""` if not present.
csd_type_eng_code:
type: string
description: |
English code indicating the type of Census Subdivision.
Can be empty string `""` if not present.
csd_type_fre_code:
type: string
description: |
French code indicating the type of Census Subdivision.
Can be empty string `""` if not present.
mail_street_name:
type: string
description: |
Name of the street used in the mailing address.
Can be empty string `""` if not present.
mail_street_type:
type: string
description: |
Designator of the street used in the mailing address.
Can be empty string `""` if not present.
mail_street_dir:
type: string
description: |
Direction of the street used in the mailing address.
Can be empty string `""` if not present.
mail_mun_name:
type: string
description: |
Municipality name used in the mailing address.
Can be empty string `""` if not present.
mail_prov_abvn:
type: string
description: |
Province abbreviation used in the mailing address.
Can be empty string `""` if not present.
mail_postal_code:
type: string
description: |
Postal code used in the mailing address.
Can be empty string `""` if not present.
bg_dls_lsd:
type: string
description: |
Legal Subdivision number within the Dominion Land Survey system for the address location.
Can be empty string `""` if not present.
bg_dls_qtr:
type: string
description: |
Quarter section within a section of the Dominion Land Survey system for the address location.
Can be empty string `""` if not present.
bg_dls_sctn:
type: string
description: |
Section number within a township of the Dominion Land Survey system for the address location.
Can be empty string `""` if not present.
bg_dls_twnshp:
type: string
description: |
Township number within the Dominion Land Survey system for the address location.
Can be empty string `""` if not present.
bg_dls_rng:
type: string
description: |
Range number within a meridian of the Dominion Land Survey system for the address location.
Can be empty string `""` if not present.
bg_dls_mrd:
type: string
description: |
Meridian number within the Dominion Land Survey system for the address location.
Can be empty string `""` if not present.
bg_x:
type: string
description: |
Spatial X coordinate (GPS) of building. (ESPG 3347)
Can be empty string `""` if not present.
bg_y:
type: string
description: |
Spatial Y coordinate (GPS) of building. (ESPG 3347)
Can be empty string `""` if not present.
bu_n_civic_add:
type: string
description: |
Additional delivery information for mailing address.
Can be empty string `""` if not present.
example: PO Box 377
bu_use:
type: string
description: |
Building usage codes.
Can be empty string `""` if not present.
csd_code:
type: string
description: |
Unique identifier code for a Census Subdivision (CSD).
Can be empty string `""` if not present.
fed_code:
type: string
description: |
Unique identifier code for a federal electoral district.
Can be empty string `""` if not present.
fed_eng_name:
type: string
description: |
Name of the federal electoral district in English.
Can be empty string `""` if not present.
fed_fre_name:
type: string
description: |
Name of the federal electoral district in French.
Can be empty string `""` if not present.
er_code:
type: string
description: |
Unique identifier code for an economic region.
Can be empty string `""` if not present.
er_eng_name:
type: string
description: |
Name of the economic region in English.
Can be empty string `""` if not present.
er_fre_name:
type: string
description: |
Name of the economic region in French.
Can be empty string `""` if not present.
reppoint_latitude:
$ref: '#/components/schemas/Latitude'
reppoint_longitude:
$ref: '#/components/schemas/Longitude'
FodbosaAddress:
required:
- id
- dataset
- country
- country_iso
- country_iso_2
- line_1
- language
- address
- latitude
- longitude
- epsg_31370_x
- epsg_31370_y
- epsg_4326_lat
- epsg_4326_lon
- address_id
- box_number
- house_number
- municipality_id
- municipality_name_de
- municipality_name_fr
- municipality_name_nl
- postcode
- postname_fr
- postname_nl
- street_id
- streetname_de
- streetname_fr
- streetname_nl
- region_code
- status
properties:
id:
$ref: '#/components/schemas/ID'
dataset:
type: string
enum:
- fodbosa
country_iso:
description: |2
3 letter country code (ISO 3166-1)
enum:
- BEL
country_iso_2:
type: string
description: |2
2 letter country code (ISO 3166-1)
enum:
- BE
country:
type: string
description: |2
Full country names (ISO 3166)
enum:
- Belgium
line_1:
type: string
description: |
First address line.
Can be empty string `""` if not present.
example: Kapellestraat 3
language:
enum:
- de
- fr
- nl
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: '3'
longitude:
$ref: '#/components/schemas/Longitude'
latitude:
$ref: '#/components/schemas/Latitude'
epsg_31370_x:
type: string
description: |
X coordinate of the address in the BD72 / Belgian Lambert 72 (EPSG:31370) coordinate system.
epsg_31370_y:
type: string
description: |
Y coordinate of the address in the BD72 / Belgian Lambert 72 (EPSG:31370) coordinate system.
epsg_4326_lat:
type: string
description: |
Latitude of the address in the WGS84 (EPSG:4326) coordinate system.
epsg_4326_lon:
type: string
description: |
Longitude of the address in the WGS84 (EPSG:4326) coordinate system.
address_id:
type: string
description: |
Address local identifier assigned by the data supplier.
box_number:
type: string
description: |
PO Box number.
Can be empty string `""` if not present.
house_number:
type: string
description: |
House number.
Can be empty string `""` if not present.
municipality_id:
type: string
description: |
Municipality local identifier assigned by the data supplier.
municipality_name_de:
type: string
description: |
Municipality name in German.
Can be empty string `""` if not present.
municipality_name_fr:
type: string
description: |
Municipality name in French.
Can be empty string `""` if not present.
municipality_name_nl:
type: string
description: |
Municipality name in Dutch.
Can be empty string `""` if not present.
postcode:
type: string
description: |
Postal code.
postname_fr:
type: string
description: |
Name of postal area in French.
Can be empty string `""` if not present.
postname_nl:
type: string
description: |
Name of postal area in Dutch.
Can be empty string `""` if not present.
street_id:
type: string
description: |
Street local identifier assigned by the data supplier.
streetname_de:
type: string
description: |
Street name in German.
Can be empty string `""` if not present.
streetname_fr:
type: string
description: |
Street name in French.
Can be empty string `""` if not present.
streetname_nl:
type: string
description: |
Street name in Dutch.
Can be empty string `""` if not present.
region_code:
type: string
description: |
ISO 3166-2 code of the region in which the address is located.
status:
type: string
description: |
Status of the address: `current`, `proposed` or `retired`.
MoisAddress:
required:
- id
- dataset
- country
- country_iso
- country_iso_2
- language
- address
- line_1
- line_2
- city
- province
- 법정읍면동명
- 법정동코드
- 법정리명
- 비고1
- 비고2
- 변동전도로명주소
- 변경이력정보
- 변경이력사유
- 변경전_도로명주소
- 변경사유
- 변경사유코드
- 층일련번호
- 층명칭
- 대표지번여부
- 대표여부
- 다량배달처명
- 동일련번호
- 동명칭
- 도로명
- 도로명_로마자
- 도로명번호
- 도로명코드
- 도로명코드_고시일자
- 도로명코드_말소일자
- 읍면동구분
- 읍면동일련번호
- 읍면동코드
- 읍면동명
- 읍면동명_로마자
- 건축물대장_건물명
- 건물본번
- 건물부번
- 건물관리번호
- 기초구역번호
- 공동주택여부
- 고시일자
- 관리번호
- 행정동코드
- 행정동명
- 호일련번호
- 호명칭
- 호접미사일련번호
- 호접미사명칭
- 이동사유코드
- 일련번호
- 지번일련번호
- 지번본번_번지
- 지번부번_호
- 지하구분
- 지하여부
- 산여부
- 상위도로명
- 상위도로명번호
- 상세건물명
- 상세주소_부여여부
- 상세주소여부
- 사용여부
- 시도명
- 시도명_로마자
- 시군구_건물명
- 시군구코드
- 시군구명
- 시군구명_로마자
- 시군구용_건물명
- 우편일련번호
- 우편번호
- 우편번호_일련번호
- 영문_법정리명
- 영문읍면동명
- 영문_법정읍면동명
- 영문도로명
- 영문시도명
- 영문시군구명
properties:
id:
$ref: '#/components/schemas/ID'
dataset:
type: string
enum:
- mois
country:
type: string
description: |2
Full country names (ISO 3166)
enum:
- South Korea
country_iso:
description: |2
3 letter country code (ISO 3166-1)
enum:
- KOR
country_iso_2:
type: string
description: |2
2 letter country code (ISO 3166-1)
enum:
- KR
language:
enum:
- ko
description: |
Language represented by 2 letter ISO Code (639-1)
address:
type: string
description: |
Address / House Number identifying the address along the specified street.
Can be empty string `""` if not present.
example: '16'
line_1:
type: string
description: |
First address line.
Can be empty string `""` if not present.
example: 배방읍 북수리 배방산길 197-1
line_2:
type: string
description: |
Second address line.
Can be empty string `""` if not present.
example: ''
city:
type: string
description: |
Preferred city name.
Can be empty string `""` if not present.
example: ''
province:
type: string
description: |
Preferred province name.
Can be empty string `""` if not present.
example: ''
법정읍면동명:
type: string
description: |
Legal town name.
Can be empty string `""` if not present.
법정동코드:
type: string
description: |
Legal district code.
법정리명:
type: string
description: |
Legal name.
Can be empty string `""` if not present.
비고1:
type: string
description: |
Note 1.
Can be empty string `""` if not present.
비고2:
type: string
description: |
Note 2.
Can be empty string `""` if not present.
변동전도로명주소:
type: string
description: |
Changed street name address.
Can be empty string `""` if not present.
변경이력정보:
type: string
description: |
Change history information.
Can be empty string `""` if not present.
변경이력사유:
type: string
description: |
Change history reason.
Can be empty string `""` if not present.
변경전_도로명주소:
type: string
description: |
Previous road name address.
Can be empty string `""` if not present.
변경사유:
type: string
description: |
Change reason.
Can be empty string `""` if not present.
변경사유코드:
type: string
description: |
Change reason code.
Can be empty string `""` if not present.
층일련번호:
type: string
description: |
Floor serial number.
Can be empty string `""` if not present.
층명칭:
type: string
description: |
Floor name.
Can be empty string `""` if not present.
대표지번여부:
type: string
description: |
Is representative address.
Can be empty string `""` if not present.
대표여부:
type: string
description: |
Is representative.
Can be empty string `""` if not present.
다량배달처명:
type: string
description: |
Bulk delivery location name.
Can be empty string `""` if not present.
동일련번호:
type: string
description: |
Building serial number.
Can be empty string `""` if not present.
동명칭:
type: string
description: |
Building name.
Can be empty string `""` if not present.
도로명:
type: string
description: |
Road name.
Can be empty string `""` if not present.
도로명_로마자:
type: string
description: |
Romanized road name.
Can be empty string `""` if not present.
도로명번호:
type: string
description: |
Road name number.
Can be empty string `""` if not present.
도로명코드:
type: string
description: |
Road name code.
도로명코드_고시일자:
type: string
description: |
Road name code creation date.
Can be empty string `""` if not present.
도로명코드_말소일자:
type: string
description: |
Road name code deletion date.
Can be empty string `""` if not present.
읍면동구분:
type: string
description: |
Town classification.
Can be empty string `""` if not present.
읍면동일련번호:
type: string
description: |
Town serial number.
Can be empty string `""` if not present.
읍면동코드:
type: string
description: |
Town code.
Can be empty string `""` if not present.
읍면동명:
type: string
description: |
Town name.
Can be empty string `""` if not present.
읍면동명_로마자:
type: string
description: |
Romanized town name.
Can be empty string `""` if not present.
건축물대장_건물명:
type: string
description: |
Building name in building register.
Can be empty string `""` if not present.
건물본번:
type: string
description: |
Building number.
건물부번:
type: string
description: |
Building sub-number.
Can be empty string `""` if not present.
건물관리번호:
type: string
description: |
Building management number.
Can be empty string `""` if not present.
기초구역번호:
type: string
description: |
Basic area number.
Can be empty string `""` if not present.
공동주택여부:
type: string
description: |
Is apartment.
Can be empty string `""` if not present.
고시일자:
type: string
description: |
Creation date.
Can be empty string `""` if not present.
관리번호:
type: string
description: |
Management number.
Can be empty string `""` if not present.
행정동코드:
type: string
description: |
Administrative district code.
Can be empty string `""` if not present.
행정동명:
type: string
description: |
Administrative district name.
Can be empty string `""` if not present.
호일련번호:
type: string
description: |
Unit serial number.
Can be empty string `""` if not present.
호명칭:
type: string
description: |
Unit name.
Can be empty string `""` if not present.
호접미사일련번호:
type: string
description: |
Unit suffix serial number.
Can be empty string `""` if not present.
호접미사명칭:
type: string
description: |
Unit suffix name.
Can be empty string `""` if not present.
이동사유코드:
type: string
description: |
Movement reason code.
Can be empty string `""` if not present.
일련번호:
type: string
description: |
Serial number.
Can be empty string `""` if not present.
지번일련번호:
type: string
description: |
Address serial number.
Can be empty string `""` if not present.
지번본번_번지:
type: string
description: |
Address building number.
Can be empty string `""` if not present.
지번부번_호:
type: string
description: |
Address unit number.
Can be empty string `""` if not present.
지하구분:
type: string
description: |
Is basement.
Can be empty string `""` if not present.
지하여부:
type: string
description: |
Level (ground level, underground, aerial).
산여부:
type: string
description: |
Is mountain.
Can be empty string `""` if not present.
상위도로명:
type: string
description: |
Upper road name.
Can be empty string `""` if not present.
상위도로명번호:
type: string
description: |
Upper road name number.
Can be empty string `""` if not present.
상세건물명:
type: string
description: |
Detailed building name.
Can be empty string `""` if not present.
상세주소_부여여부:
type: string
description: |
Whether detailed address assigned.
Can be empty string `""` if not present.
상세주소여부:
type: string
description: |
Whether detailed address exists.
Can be empty string `""` if not present.
사용여부:
type: string
description: |
In use.
Can be empty string `""` if not present.
시도명:
type: string
description: |
City name.
시도명_로마자:
type: string
description: |
Romanized city name.
Can be empty string `""` if not present.
시군구_건물명:
type: string
description: |
District building name.
Can be empty string `""` if not present.
시군구코드:
type: string
description: |
District code.
Can be empty string `""` if not present.
시군구명:
type: string
description: |
District name.
Can be empty string `""` if not present.
시군구명_로마자:
type: string
description: |
Romanized district name.
Can be empty string `""` if not present.
시군구용_건물명:
type: string
description: |
District building name.
Can be empty string `""` if not present.
우편일련번호:
type: string
description: |
Postal sequence number.
Can be empty string `""` if not present.
우편번호:
type: string
description: |
Postal code.
Can be empty string `""` if not present.
우편번호_일련번호:
type: string
description: |
Postal code serial number.
Can be empty string `""` if not present.
영문_법정리명:
type: string
description: |
English legal name.
Can be empty string `""` if not present.
영문읍면동명:
type: string
description: |
English town name.
Can be empty string `""` if not present.
영문_법정읍면동명:
type: string
description: |
English legal town name.
Can be empty string `""` if not present.
영문도로명:
type: string
description: |
English road name.
Can be empty string `""` if not present.
영문시도명:
type: string
description: |
English city name.
Can be empty string `""` if not present.
영문시군구명:
type: string
description: |
English district name.
Can be empty string `""` if not present.
UpujpAddress:
required:
- id
- dataset
- country
- country_iso
- country_iso_2
- language
- script
- address
- line_1
- building_name
- neighbourhood
- district
- city
- prefecture
- postcode
- latitude
- longitude
- org_id
- org_type_ind
- org_sub_type_ind
- org_loc_id
- org_dis_id
- org_nei_id
- org_org_id
- org_name
- org_name_trans
- org_loc_sfx
- org_loc_sfx_trans
- org_adr
- org_adr_trans
- org_po_ind
- org_po_start
- org_po_end
- org_dsc
- org_dsc_trans
- org_pcode
- org_pcode_fin
- org_script
- org_language
- str_id
- str_key
- str_loc_id
- str_dis_id
- str_nei_id
- str_org_id
- str_pfx
- str_pfx_trans
- str_qlf_pre
- str_qlf_pre_trans
- str_qlf_suc
- str_qlf_suc_trans
- str_name
- str_name_trans
- str_loc_sfx
- str_loc_sfx_trans
- str_type
- str_type_trans
- str_type_abv
- str_type_abv_trans
- str_adr_num_key
- str_from_num
- str_from_unit
- str_from_alph
- str_to_num
- str_to_unit
- str_to_alph
- str_evenodd
- str_dsc
- str_dsc_trans
- str_blg_id
- str_blg_name
- str_blg_name_trans
- str_blg_type
- str_blg_type_trans
- str_blg_dsc
- str_blg_dsc_trans
- str_ref_str_id
- str_pcode
- str_script
- str_language
- sub_dis_id
- sub_dis_key
- sub_loc_id
- sub_loc_sfx
- sub_loc_sfx_trans
- sub_dis_name
- sub_dis_name_trans
- sub_dis_sfx
- sub_dis_sfx_trans
- sub_dis_dsc
- sub_dis_dsc_trans
- sub_dis_pcode
- sub_dis_pcode_fin
- sub_nei_id
- sub_nei_key
- sub_nei_name
- sub_nei_name_trans
- sub_nei_sfx
- sub_nei_sfx_trans
- sub_nei_zone_from
- sub_nei_zone_to
- sub_nei_dsc
- sub_nei_dsc_trans
- sub_nei_pcode
- sub_script
- sub_language
- loc_id
- loc_key
- loc_adm1_id
- loc_adm1_key
- loc_adm1_name
- loc_adm1_name_trans
- loc_adm1_sfx
- loc_adm1_sfx_trans
- loc_adm1_abv
- loc_adm1_abv_trans
- loc_adm2_id
- loc_adm2_key
- loc_adm2_name
- loc_adm2_name_trans
- loc_adm2_sfx
- loc_adm2_sfx_trans
- loc_adm2_abv
- loc_adm2_abv_trans
- loc_adm3_id
- loc_adm3_key
- loc_adm3_name
- loc_adm3_name_trans
- loc_adm3_sfx
- loc_adm3_sfx_trans
- loc_adm3_abv
- loc_adm3_abv_trans
- loc_name
- loc_name_trans
- loc_sfx
- loc_sfx_trans
- loc_pcode
- loc_pcode_fin
- loc_dsc
- loc_dsc_trans
- loc_script
- loc_language
properties:
id:
$ref: '#/components/schemas/ID'
dataset:
type: string
enum:
- upujp
country:
type: string
description: |2
Full country names (ISO 3166)
enum:
- Japan
country_iso:
description: |2
3 letter country code (ISO 3166-1)
enum:
- JPN
country_iso_2:
type: string
description: |2
2 letter country code (ISO 3166-1)
enum:
- JP
language:
enum:
- ja
- en
description: |
Language represented by 2 letter ISO Code (639-1)
line_1:
type: string
description: |
First address line.
Can be empty string `""` if not present.
example: 2-4
address:
type: string
description: |
Address / House Number uniquely identifying the address along the specified street.
Can be empty string `""` if not present.
example: 2-4
building_name:
type: string
description: |
Preferred building name.
Can be empty string `""` if not present.
example: 電通本社ビル
neighbourhood:
type: string
description: |
Preferred neighbourhood name.
Can be empty string `""` if not present.
example: あいの里一条七丁目
district:
type: string
description: |
Preferred district name.
Can be empty string `""` if not present.
example: 上富良野町
city:
type: string
description: |
Preferred city name.
Can be empty string `""` if not present.
example: 下関市
prefecture:
type: string
description: |
Preferred prefecture name.
Can be empty string `""` if not present.
example: 和歌山県
postcode:
type: string
description: |
Preferred postal code.
Can be empty string `""` if not present.
example: 259-1100
longitude:
$ref: '#/components/schemas/Longitude'
latitude:
$ref: '#/components/schemas/Latitude'
org_id:
type: string
description: |
The unique identifier of an organisation.
Can be empty string `""` if not present.
org_type_ind:
oneOf:
- type: string
- type: number
description: |
Indicates the type of organisation.
Can be empty string `""` if not present.
org_sub_type_ind:
oneOf:
- type: string
- type: number
description: |
Indicates the sub-type of the organisation.
Can be empty string `""` if not present.
org_loc_id:
type: string
description: |
Locality identifier for the organisation.
Can be empty string `""` if not present.
org_dis_id:
type: string
description: |
District identifier for the organisation.
Can be empty string `""` if not present.
org_nei_id:
type: string
description: |
Neighbourhood identifier for the organisation.
Can be empty string `""` if not present.
org_org_id:
type: string
description: |
Associated organisation identifier for the organisation.
Can be empty string `""` if not present.
org_name:
type: string
description: |
Name of the organisation.
Can be empty string `""` if not present.
org_name_trans:
type: string
description: |
Translated name of the organisation in Latin script.
Can be empty string `""` if not present.
org_loc_sfx:
type: string
description: |
Suffix of the locality for the organisation.
Can be empty string `""` if not present.
org_loc_sfx_trans:
type: string
description: |
Translated suffix of the locality for the organisation in Latin script.
Can be empty string `""` if not present.
org_adr:
type: string
description: |
Address of the organisation.
Can be empty string `""` if not present.
org_adr_trans:
type: string
description: |
Translated address of the organisation in Latin script.
Can be empty string `""` if not present.
org_po_ind:
oneOf:
- type: string
- type: number
description: |
Indicates whether the organisation has a post office box.
Can be empty string `""` if not present.
org_po_start:
type: string
description: |
Post office box number or start of the post office box range associated with the organisation.
Can be empty string `""` if not present.
org_po_end:
type: string
description: |
End of the post office box range associated with the organisation.
Can be empty string `""` if not present.
org_dsc:
type: string
description: |
Additional information about the organisation.
Can be empty string `""` if not present.
org_dsc_trans:
type: string
description: |
Translated additional information about the organisation in Latin script.
Can be empty string `""` if not present.
org_pcode:
type: string
description: |
Postal code for the organisation.
Can be empty string `""` if not present.
org_pcode_fin:
type: string
description: |
Final postal code for the organisation.
Can be empty string `""` if not present.
org_script:
type: string
description: |
Script used for the organisation name.
`Hani` = Kanji, `Hira` = Hiragana, `Latn` = Latin.
Can be empty string `""` if not present.
org_language:
type: string
description: |
Language used for the organisation name.
Can be empty string `""` if not present.
str_id:
type: string
description: |
Identifier of the street (not unique).
Can be empty string `""` if not present.
str_key:
type: string
description: |
Permanent identifier of the street.
Can be empty string `""` if not present.
str_loc_id:
type: string
description: |
Locality identifier for the street.
Can be empty string `""` if not present.
str_dis_id:
type: string
description: |
District identifier for the street.
Can be empty string `""` if not present.
str_nei_id:
type: string
description: |
Neighbourhood identifier for the street.
Can be empty string `""` if not present.
str_org_id:
type: string
description: |
Associated organisation identifier for the street.
Can be empty string `""` if not present.
str_pfx:
type: string
description: |
Prefix of the street name.
Can be empty string `""` if not present.
str_pfx_trans:
type: string
description: |
Translated prefix of the street name in Latin script.
Can be empty string `""` if not present.
str_qlf_pre:
type: string
description: |
Preceding qualifier of the street name.
Can be empty string `""` if not present.
str_qlf_pre_trans:
type: string
description: |
Translated preceding qualifier of the street name in Latin script.
Can be empty string `""` if not present.
str_qlf_suc:
type: string
description: |
Succeeding qualifier of the street name.
Can be empty string `""` if not present.
str_qlf_suc_trans:
type: string
description: |
Translated succeeding qualifier of the street name in Latin script.
Can be empty string `""` if not present.
str_name:
type: string
description: |
Name of the street.
Can be empty string `""` if not present.
str_name_trans:
type: string
description: |
Translated name of the street in Latin script.
Can be empty string `""` if not present.
str_loc_sfx:
type: string
description: |
Suffix of the locality for the street.
Can be empty string `""` if not present.
str_loc_sfx_trans:
type: string
description: |
Translated suffix of the locality for the street in Latin script.
Can be empty string `""` if not present.
str_type:
type: string
description: |
Type of the street.
Can be empty string `""` if not present.
str_type_trans:
type: string
description: |
Translated type of the street in Latin script.
Can be empty string `""` if not present.
str_type_abv:
type: string
description: |
Abbreviation of the street type.
Can be empty string `""` if not present.
str_type_abv_trans:
type: string
description: |
Translated abbreviation of the street type in Latin script.
Can be empty string `""` if not present.
str_adr_num_key:
type: string
description: |
Permanent identifier of the address.
Can be empty string `""` if not present.
str_from_num:
oneOf:
- type: string
- type: number
description: |
Lowest address number on the street.
Can be empty string `""` if not present.
str_from_unit:
type: string
description: |
Lowest unit number on the street.
Can be empty string `""` if not present.
str_from_alph:
type: string
description: |
Extension of the lowest address number on the street.
Can be empty string `""` if not present.
str_to_num:
oneOf:
- type: string
- type: number
description: |
Highest address number on the street.
Can be empty string `""` if not present.
str_to_unit:
type: string
description: |
Highest unit number on the street.
Can be empty string `""` if not present.
str_to_alph:
type: string
description: |
Extension of the highest address number on the street.
Can be empty string `""` if not present.
str_evenodd:
oneOf:
- type: string
- type: number
description: |
Indicates whether the address range for this street contains even numbers, odd numbers, or both.
Can be empty string `""` if not present.
str_dsc:
type: string
description: |
Additional information about the street.
Can be empty string `""` if not present.
str_dsc_trans:
type: string
description: |
Translated additional information about the street in Latin script.
Can be empty string `""` if not present.
str_blg_id:
type: string
description: |
Identifier of the building for the street.
Can be empty string `""` if not present.
str_blg_name:
type: string
description: |
Name of the building for the street.
Can be empty string `""` if not present.
str_blg_name_trans:
type: string
description: |
Translated name of the building for the street in Latin script.
Can be empty string `""` if not present.
str_blg_type:
type: string
description: |
Type of the building for the street.
Can be empty string `""` if not present.
str_blg_type_trans:
type: string
description: |
Translated type of the building for the street in Latin script.
Can be empty string `""` if not present.
str_blg_dsc:
type: string
description: |
Additional information about the building for the street.
Can be empty string `""` if not present.
str_blg_dsc_trans:
type: string
description: |
Translated additional information about the building for the street in Latin script.
Can be empty string `""` if not present.
str_ref_str_id:
type: string
description: |
Identifier of the associated street.
Can be empty string `""` if not present.
str_pcode:
type: string
description: |
Postal code for the street.
Can be empty string `""` if not present.
str_script:
type: string
description: |
Script used for the street name.
`Hani` = Kanji, `Hira` = Hiragana, `Latn` = Latin.
Can be empty string `""` if not present.
str_language:
type: string
description: |
Language used for the street name.
Can be empty string `""` if not present.
sub_dis_id:
type: string
description: |
Unique identifier of the district.
Can be empty string `""` if not present.
sub_dis_key:
type: string
description: |
Permanent identifier of the district.
Can be empty string `""` if not present.
sub_loc_id:
type: string
description: |
Locality identifier for the subdivision.
Can be empty string `""` if not present.
sub_loc_sfx:
type: string
description: |
Suffix of the locality for the subdivision.
Can be empty string `""` if not present.
sub_loc_sfx_trans:
type: string
description: |
Translated suffix of the locality for the subdivision in Latin script.
Can be empty string `""` if not present.
sub_dis_name:
type: string
description: |
Name of the district.
Can be empty string `""` if not present.
sub_dis_name_trans:
type: string
description: |
Translated name of the district in Latin script.
Can be empty string `""` if not present.
sub_dis_sfx:
type: string
description: |
Suffix of the district.
Can be empty string `""` if not present.
sub_dis_sfx_trans:
type: string
description: |
Translated suffix of the district in Latin script.
Can be empty string `""` if not present.
sub_dis_dsc:
type: string
description: |
Additional information about the district.
Can be empty string `""` if not present.
sub_dis_dsc_trans:
type: string
description: |
Translated additional information about the district in Latin script.
Can be empty string `""` if not present.
sub_dis_pcode:
type: string
description: |
Postal code for the district.
Can be empty string `""` if not present.
sub_dis_pcode_fin:
type: string
description: |
Final postal code for the district.
Can be empty string `""` if not present.
sub_nei_id:
type: string
description: |
Identifier of the neighbourhood.
Can be empty string `""` if not present.
sub_nei_key:
type: string
description: |
Permanent identifier of the neighbourhood.
Can be empty string `""` if not present.
sub_nei_name:
type: string
description: |
Name of the neighbourhood.
Can be empty string `""` if not present.
sub_nei_name_trans:
type: string
description: |
Translated name of the neighbourhood in Latin script.
Can be empty string `""` if not present.
sub_nei_sfx:
type: string
description: |
Suffix of the neighbourhood.
Can be empty string `""` if not present.
sub_nei_sfx_trans:
type: string
description: |
Translated suffix of the neighbourhood in Latin script.
Can be empty string `""` if not present.
sub_nei_zone_from:
type: string
description: |
Start of the range of zone numbers to which the neighbourhood postal code corresponds.
Can be empty string `""` if not present.
sub_nei_zone_to:
type: string
description: |
End of the range of zone numbers to which the neighbourhood postal code corresponds.
Can be empty string `""` if not present.
sub_nei_dsc:
type: string
description: |
Additional information about the neighbourhood.
Can be empty string `""` if not present.
sub_nei_dsc_trans:
type: string
description: |
Translated additional information about the neighbourhood in Latin script.
Can be empty string `""` if not present.
sub_nei_pcode:
type: string
description: |
Postal code for the neighbourhood.
Can be empty string `""` if not present.
sub_script:
type: string
description: |
Script used for the subdivision names.
`Hani` = Kanji, `Hira` = Hiragana, `Latn` = Latin.
Can be empty string `""` if not present.
sub_language:
type: string
description: |
Language used for the subdivision names.
Can be empty string `""` if not present.
loc_id:
type: string
description: |
Unique identifier of the locality.
Can be empty string `""` if not present.
loc_key:
type: string
description: |
Permanent identifier of the locality.
Can be empty string `""` if not present.
loc_adm1_id:
type: string
description: |
Identifier of administrative division 1.
Can be empty string `""` if not present.
loc_adm1_key:
type: string
description: |
Permanent identifier of administrative division 1.
Can be empty string `""` if not present.
loc_adm1_name:
type: string
description: |
Name of administrative division 1.
Can be empty string `""` if not present.
loc_adm1_name_trans:
type: string
description: |
Translated name of administrative division 1 in Latin script.
Can be empty string `""` if not present.
loc_adm1_sfx:
type: string
description: |
Suffix of administrative division 1.
Can be empty string `""` if not present.
loc_adm1_sfx_trans:
type: string
description: |
Translated suffix of administrative division 1 in Latin script.
Can be empty string `""` if not present.
loc_adm1_abv:
type: string
description: |
Abbreviation of administrative division 1.
Can be empty string `""` if not present.
loc_adm1_abv_trans:
type: string
description: |
Translated abbreviation of administrative division 1 in Latin script.
Can be empty string `""` if not present.
loc_adm2_id:
type: string
description: |
Identifier of administrative division 2.
Can be empty string `""` if not present.
loc_adm2_key:
type: string
description: |
Permanent identifier of administrative division 2.
Can be empty string `""` if not present.
loc_adm2_name:
type: string
description: |
Name of administrative division 2.
Can be empty string `""` if not present.
loc_adm2_name_trans:
type: string
description: |
Translated name of administrative division 2 in Latin script.
Can be empty string `""` if not present.
loc_adm2_sfx:
type: string
description: |
Suffix of administrative division 2.
Can be empty string `""` if not present.
loc_adm2_sfx_trans:
type: string
description: |
Translated suffix of administrative division 2 in Latin script.
Can be empty string `""` if not present.
loc_adm2_abv:
type: string
description: |
Abbreviation of administrative division 2.
Can be empty string `""` if not present.
loc_adm2_abv_trans:
type: string
description: |
Translated abbreviation of administrative division 2 in Latin script.
Can be empty string `""` if not present.
loc_adm3_id:
type: string
description: |
Identifier of administrative division 3.
Can be empty string `""` if not present.
loc_adm3_key:
type: string
description: |
Permanent identifier of administrative division 3.
Can be empty string `""` if not present.
loc_adm3_name:
type: string
description: |
Name of administrative division 3.
Can be empty string `""` if not present.
loc_adm3_name_trans:
type: string
description: |
Translated name of administrative division 3 in Latin script.
Can be empty string `""` if not present.
loc_adm3_sfx:
type: string
description: |
Suffix of administrative division 3.
Can be empty string `""` if not present.
loc_adm3_sfx_trans:
type: string
description: |
Translated suffix of administrative division 3 in Latin script.
Can be empty string `""` if not present.
loc_adm3_abv:
type: string
description: |
Abbreviation of administrative division 3.
Can be empty string `""` if not present.
loc_adm3_abv_trans:
type: string
description: |
Translated abbreviation of administrative division 3 in Latin script.
Can be empty string `""` if not present.
loc_name:
type: string
description: |
Name of the locality.
Can be empty string `""` if not present.
loc_name_trans:
type: string
description: |
Translated name of the locality in Latin script.
Can be empty string `""` if not present.
loc_sfx:
type: string
description: |
Suffix of the locality.
Can be empty string `""` if not present.
loc_sfx_trans:
type: string
description: |
Translated suffix of the locality in Latin script.
Can be empty string `""` if not present.
loc_pcode:
type: string
description: |
Postal code of the locality.
Can be empty string `""` if not present.
loc_pcode_fin:
type: string
description: |
Final postal code of the locality.
Can be empty string `""` if not present.
loc_dsc:
type: string
description: |
Additional information about the locality.
Can be empty string `""` if not present.
loc_dsc_trans:
type: string
description: |
Translated additional information about the locality in Latin script.
Can be empty string `""` if not present.
loc_script:
type: string
description: |
Script used for the locality names.
`Hani` = Kanji, `Hira` = Hiragana, `Latn` = Latin.
Can be empty string `""` if not present.
loc_language:
type: string
description: |
Language used for the locality names.
Can be empty string `""` if not present.
BevAddress:
required:
- id
- dataset
- country
- country_iso
- country_iso_2
- language
- address
- line_1
- line_2
- latitude
- longitude
- adrcd
- kgnr
- gkz
- okz
- plz
- skz
- zaehlsprengel
- hausnrtext
- hausnrzahl1
- hausnrbuchstabe1
- hausnrverbindung1
- hausnrzahl2
- hausnrbuchstabe2
- hausnrbereich
- hnr_adr_zusammen
- gnradresse
- hofname
- rw
- hw
- epsg
- quelladresse
- bestimmungsart
- subcd
- objektnummer
- objfunktkennziffer
- hauptadresse
- hausnrverbindung2
- hausnrzahl3
- hausnrbuchstabe3
- hausnrverbindung3
- hausnrzahl4
- hausnrbuchstabe4
- hausnrgebaeudebez
- hnr_geb_zusammen
- eigenschaft
- gemeindename
- ortsname
- strassenname
- strassennamenzusatz
- szusadrbest
- zustellort
- zustellort_id
- zaehlsprengelname
properties:
id:
$ref: '#/components/schemas/ID'
dataset:
type: string
enum:
- bev
country_iso:
description: |2
3 letter country code (ISO 3166-1)
enum:
- AUT
country_iso_2:
type: string
description: |2
2 letter country code (ISO 3166-1)
enum:
- AT
country:
type: string
description: |2
Full country names (ISO 3166)
enum:
- Austria
language:
enum:
- de
description: |
Language represented by 2 letter ISO Code (639-1)
address:
type: string
description: |
Combination of hnr_adr_zusammen and hnr_geb_zusammen - the full house number and building designation.
Can be empty string `""` if not present.
example: '40'
line_1:
type: string
description: |
First address line.
Can be empty string `""` if not present.
example: Villa Kranzmayer
line_2:
type: string
description: |
Second address line.
Can be empty string `""` if not present.
example: Römerweg 48
longitude:
$ref: '#/components/schemas/Longitude'
latitude:
$ref: '#/components/schemas/Latitude'
adrcd:
type: string
description: |
Unique identifier of the address
kgnr:
type: string
description: |
Cadastral number of the municipality of the land parcel associated with the address
gkz:
type: string
description: |
Municipality unique identifier
okz:
type: string
description: |
Locality unique identifier
plz:
type: string
description: |
Postal code
skz:
type: string
description: |
Street unique identifier
zaehlsprengel:
type: string
description: |
Census district unique identifier
hausnrtext:
type: string
description: |
Text before house number
hausnrzahl1:
oneOf:
- type: string
description: |
Empty string `""` if not available
- type: number
description: |
House number part 1
hausnrbuchstabe1:
type: string
description: |
House letter part 1
hausnrverbindung1:
type: string
description: |
House number connector 1
hausnrzahl2:
oneOf:
- type: string
description: |
Empty string `""` if not available
- type: number
description: |
House number part 2
hausnrbuchstabe2:
type: string
description: |
House letter part 2
hausnrbereich:
type: string
description: |
House number range scheme (even, odd, all or not specified)
hnr_adr_zusammen:
type: string
description: |
Complete house number (combination of house number parts and letters)
gnradresse:
type: number
description: |
Parcel number used as an address when no house number is present
hofname:
type: string
description: |
Name of building or building complex (e.g. farmstead)
rw:
type: string
description: |
Easting / X coordinate
hw:
type: string
description: |
Northing / Y coordinate
epsg:
type: number
description: |
Coordinate reference system identifier
quelladresse:
type: string
description: |
Coordinate accuracy level (building level, parcel level, etc.)
bestimmungsart:
type: string
description: |
Coordinate determination method (DKM, surveying office, municipality, etc.)
subcd:
type: string
description: |
Subcode to distinguish multiple buildings at the same address
objektnummer:
type: string
description: |
Object number of the building
objfunktkennziffer:
type: string
description: |
All building function codes related to the address
Can be empty string `""` if not present.
hauptadresse:
oneOf:
- type: string
description: |
Empty string `""` if not available
- type: number
description: |
Indicates whether this address is the primary address for the associated building.
hausnrverbindung2:
type: string
description: |
House number connector 2
hausnrzahl3:
oneOf:
- type: string
description: |
Empty string `""` if not available
- type: number
description: |
House number part 3
hausnrbuchstabe3:
type: string
description: |
House letter part 3
hausnrverbindung3:
type: string
description: |
House number connector 3
hausnrzahl4:
oneOf:
- type: string
description: |
Empty string `""` if not available
- type: number
description: |
House number part 4
hausnrbuchstabe4:
type: string
description: |
House letter part 4
hausnrgebaeudebez:
type: string
description: |
Building description
hnr_geb_zusammen:
type: string
description: |
Combination of house number and building designation
eigenschaft:
type: string
description: |
Code indicating the primary use or function of the building associated with the address
gemeindename:
type: string
description: |
Name of the municipality
ortsname:
type: string
description: |
Name of the locality
strassenname:
type: string
description: |
Name of the street
strassennamenzusatz:
type: string
description: |
Street type (e.g., "Allee", "Strasse", etc.)
szusadrbest:
type: number
description: |
Indicates whether the street type is included in the street name
zustellort:
type: string
description: |
Postal town name
zustellort_id:
type: string
description: |
Postal town identifier
zaehlsprengelname:
type: string
description: |
Name of the census district
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'
- $ref: '#/components/schemas/KadasterAddress'
- $ref: '#/components/schemas/KartverketAddress'
- $ref: '#/components/schemas/SdfiAddress'
- $ref: '#/components/schemas/CannarAddress'
- $ref: '#/components/schemas/FodbosaAddress'
- $ref: '#/components/schemas/MoisAddress'
- $ref: '#/components/schemas/UpujpAddress'
- $ref: '#/components/schemas/BevAddress'
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: Street name
example: Georgia Ave
dependant_thoroughfare:
type: string
description: Not available for non-UK addresses
enum:
- ''
building_number:
type: string
description: Address or house number
example: '2'
building_name:
type: string
description: Name of the building associated with the address
example: Holland House
sub_building_name:
type: string
description: Name of the sub-building associated with the address
example: Kingscourt Post Office
premise:
type: string
description: Not available for non-UK addresses
enum:
- ''
po_box:
type: string
description: PO Box number
example: '100'
department_name:
type: string
description: Not available for non-UK addresses
enum:
- ''
organisation_name:
type: string
description: Name of the company or organisation associated with the address
example: Farrell's Gift Shop
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
ApiKeyMonthlyLimit:
title: API Key Monthly Limit
type: object
required:
- limit
- consumed
properties:
limit:
x-nullable: true
nullable: true
minimum: 0
example: 10000
type: integer
description: |-
`number` or `null`. The monthly lookup limit currently set on your key.
`null` means the limit is currently disabled.
format: int32
consumed:
minimum: 0
example: 2500
type: integer
description: Number of lookups performed this month which count towards your monthly 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
- balance_threshold
- no_balance
- limit_reached
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
balance_threshold:
type: integer
format: int32
minimum: 0
x-nullable: true
nullable: true
description: Balance threshold that triggers a reminder email. null means disabled.
example: 500
no_balance:
type: boolean
description: Send notice when balance hits zero.
limit_reached:
type: boolean
description: Send notice when rate limit is reached.
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
- kadaster
- kartverket
- sdfi
- cannar
- fodbosa
- mois
- upujp
- bev
- gbrcleanse
- uspscleanse
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: 'Republic of Ireland: Eircode Address Database'
example: false
ecaf:
type: boolean
description: 'Republic of Ireland: 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
kadaster:
type: boolean
description: 'Netherlands: Kadaster BAG 2.0 Address File'
kartverket:
type: boolean
description: 'Norway: Kartverket Address File'
example: true
mois:
type: boolean
description: 'South Korea: MOIS Address File'
example: true
sdfi:
type: boolean
description: 'Denmark: Danmarks Adresseregister (DAR)'
example: true
cannar:
type: boolean
description: 'Canada: Statistics Canada National Address Register'
example: true
fodbosa:
type: boolean
description: 'Belgium: FOD BOSA Address File'
example: true
upujp:
type: boolean
description: 'Japan: UPU Address File'
example: true
bev:
type: boolean
description: 'Austria: BEV Address File'
example: true
gbrcleanse:
type: boolean
description: UK GBR Cleanse
example: true
uspscleanse:
type: boolean
description: US CASS Cleanse
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:
- name
- contexts
- lookups_remaining
- daily_limit
- monthly_limit
- individual_limit
- allowed_urls
- redact_days
- notifications
- automated_topups
- current_purchases
- ip_forwarding
- datasets
properties:
name:
type: string
description: A name for the key
example: My API Key
contexts:
$ref: '#/components/schemas/AvailableContexts'
lookups_remaining:
minimum: 0
example: 19889
type: integer
format: int32
daily_limit:
$ref: '#/components/schemas/ApiKeyDailyLimit'
monthly_limit:
$ref: '#/components/schemas/ApiKeyMonthlyLimit'
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:
name:
type: string
maxLength: 32
pattern: ^(\w|\s){0,32}$
description: A name for the key
example: My API Key
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
monthly_limit:
title: Monthly Rate Limit
type: object
properties:
limit:
x-nullable: true
nullable: true
minimum: 0
example: 10000
type: integer
description: |-
`number` or `null`. The monthly 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
balance_threshold:
type: integer
format: int32
minimum: 0
x-nullable: true
nullable: true
description: Balance threshold that triggers a reminder email. null to disable.
example: 500
no_balance:
type: boolean
description: Send notice when balance hits zero.
limit_reached:
type: boolean
description: Send notice when rate limit is reached.
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
kadaster:
type: boolean
description: 'Netherlands: Kadaster BAG 2.0 Address File'
example: true
kartverket:
type: boolean
description: 'Norway: Kartverket Address File'
example: true
sdfi:
type: boolean
description: 'Denmark: SDFI Address File'
example: true
cannar:
type: boolean
description: 'Canada: Statistics Canada National Address Register'
example: true
fodbosa:
type: boolean
description: 'Belgium: FOD BOSA Address File'
example: true
mois:
type: boolean
description: 'South Korea: MOIS Address File'
example: true
upujp:
type: boolean
description: 'Japan: UPU Address File'
example: true
bev:
type: boolean
description: 'Austria: BEV Address File'
example: true
ab:
type: boolean
description: UK AddressBase dataset
example: false
nip:
type: boolean
description: Northern Ireland Pointer Dataset
example: false
gbrcleanse:
type: boolean
description: UK GBR Cleanse
example: true
uspscleanse:
type: boolean
description: US CASS Cleanse
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_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
- state
- suite_link_footnote
- time_zone
- urbanization
- zip_code
properties:
address1:
type: string
description: |
Primary delivery address
example: 101 Cauther Ln
address2:
type: string
description: |
Secondary address information
example: ''
address3:
type: string
description: |
Additional secondary address information
example: ''
area_code:
type: string
description: |
Area code. Also known as Numbering Plan Area (NPA) https://en.wikipedia.org/wiki/List_of_North_American_Numbering_Plan_area_codes
example: 575
carrier_route:
type: string
description: |
Data required to perform a Carrier Route sort
example: C019
check_digit:
type: string
description: |
Character following the 5 or 9 digit ZIP Code. Part of the 11-digit barcode
example: '4'
city:
type: string
description: |
City name
example: "Alamogordo"
city_abbreviation:
type: string
description: |
City Abbreviation. Empty string if not present
example: ''
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
example: US
county:
type: string
description: |
Name of the county
example: Otero
day_light_savings:
type: boolean
description: |
Daylight saving time indicator
example: true
delivery_point:
type: string
description: |
Last 2 digits of the primary street address number or Post Office box
example: '10'
dpv:
type: string
description: |
Delivery Point Validation (DPV) Confirmation code.
Possible values:
- 'Y' Primary and secondary address information was validated
- 'S' Extraneous or incorrect secondary address present
- 'D' Secondary address information missing
- 'N' Primary and secondary address information was not validated
- '' Address was not submitted to DPV lookup. Address was not ZIP+4 matched.
enum:
- 'Y'
- S
- D
- 'N'
- ''
dpv_cmra:
type: string
description: |
Delivery Point Validation (DPV) CMRA code.
Indicates if the address is linked to a Commercial Mail Receiving Agency (CMRA), such as the UPS Store or Mailboxes Etc., where USPS mail can be sent or received.
Possible values:
- 'Y' Address is associated with a CMRA
- 'N' Address is not associated with a CMRA
- '' Empty string if address is not DPV validated.
enum:
- 'Y'
- 'N'
- ''
dpv_footnotes:
type: string
description: |
Delivery Point Validation (DPV) Footnotes. Empty string if not present
Possible values:
- 'AA' ZIP+4 matched.
- 'A1' ZIP+4 did not match.
- 'BB' Primary and secondary address information was DPV validated.
- 'CC' Primary address information was DPV validated. Input secondary address information dropped.
- 'F1' Military address.
- 'G1' General delivery address.
- 'N1' Primary address information was DPV validated. Highrise address with missing secondary address information.
- 'M1' Primary number missing from address.
- 'M3' Primary number invalid.
- 'P1' Box number missing.
- 'P3' Box number invalid.
- 'RR' Validated CMRA address with PMB information.
- 'R1' Validated CMRA address without PMB information.
- 'U1' Unique 5-digit ZIP code.
example: AABB
dpv_no_stat:
type: string
description: "Delivery Point Validation (DPV) NoStat code.\n\nIndicates whether the address is a vacant property, it receives mail as a part of a drop, or it does not have an established delivery yet.\n\nPossible values:\n- 'Y'\tConfirmed\n- 'N'\tNot confirmed\n- '' Empty string if address is not DPV validated.\n"
enum:
- 'Y'
- 'N'
- ''
dpv_vacant:
type: string
description: |
Delivery Point Validation (DPV) Vacant code.
USPS records indicate that although this may be a valid address, the residence or business is vacant.
Possible values:
- 'Y' Confirmed vacant
- 'N' Not confirmed vacant
- '' Empty string if address is not DPV validated.
enum:
- 'Y'
- 'N'
- ''
elot:
type: string
description: |
Enhanced Line of Travel. For arranging records in the order that a route is served by a carrier. eLOT sequencing, when combined with Carrier Route codes, may allow Enhanced Carrier Route (ECR) discounts to be claimed.
example: 0133A
finance_number:
oneOf:
- type: string
- type: number
description: |
Internal accounting number used by the USPS® when Post Offices or ZIP Codes are discontinued and reassigned. The finance number reflects the geographic grouping of ZIP + 4 areas in which these changes can be made.
Empty string if not present
example: 340105
fips_county_code:
type: string
description: |
Federal Information Processing Standard code for a county. Empty string if not present
example: '035'
firm:
type: string
description: |
Company name in a business address
example: ''
footnotes:
type: string
description: |
Letter codes returned by ZIP+4 encoding. Empty string if not present
geo_coded:
type: boolean
description: |
Indicates whether the address was geo-coded
lacs_indicator:
type: string
description: |
Indicates whether a record may benefit from LACS processing.
Possible values:
- 'L' Yes
- '' No
enum:
- L
- ''
lacs_link_footnote:
type: string
description: |
LACSLink Footnote. Return Code returned by the LACSLink process when an accurate address match could not be made. These codes help identify the type of move and the type of deficiency in the record which prevents a match.
Possible values:
- 'A' Address matched
- '00' No match
- '09' The input record matched to a record in the master file, but the old address is a highrise default
- '14' The input record matched to a record in the master file. The new address could not be converted to a deliverable address
- '92' LACSLink Record: Secondary Number Dropped from Input Address - The input record matched to a master file record, but the input address had a secondary number and the master file record did not. The record is a ZIP + 4 street level or high-rise match
- '' Address not submitted to LACSLink lookup
enum:
- A
- '00'
- '09'
- '14'
- '92'
- ''
lacs_link_indicator:
type: string
description: |
LACSLink Indicator. Indicates whether the input address matched a record in the LACSLink database.
Possible values:
- 'Y' Matched a record in the master file
- 'S' The input record matched a master file record, but the input address included a secondary number that the master file record lacked
- 'N' No match
- '' Empty string if not prese
enum:
- 'Y'
- S
- 'N'
- ''
latitude:
oneOf:
- type: string
- type: number
description: |
Latitude of the encoded address. Empty string if not present
example: 32.91278
longitude:
oneOf:
- type: string
- type: number
description: |
Longitude of the encoded address. Empty string if not present
example: -105.94904
parsed_pmb_designator:
type: string
description: |
Information if a Private Mail Box (PMB) is found in an address. Empty string if not present
example: ''
parsed_pmb_number:
oneOf:
- type: string
- type: number
description: |
Information if a Private Mail Box (PMB) is found in an address. Empty string if not present
example: ''
parsed_post_directional:
oneOf:
- type: string
- type: number
description: |
Notation following the street name indicating street direction. Empty string if not present
example: ''
parsed_pre_directional:
type: string
description: |
Notation preceding the street name indicating street direction. Empty string if not present
example: ''
parsed_primary_number:
oneOf:
- type: string
- type: number
description: |
Number preceding the street name. Empty string if not present
example: ''
parsed_street_name:
type: string
description: |
Street name. Empty string if not present
example: ''
parsed_suffix:
type: string
description: |
Part of the delivery address line following the street name. Empty string if not present
example: ''
parsed_unit_designator:
type: string
description: |
Identification of the secondary address unit. Empty string if not present
example: ''
parsed_unit_number:
type: string
description: |
Apartment or suite number. Empty string if not present
example: ''
rdi:
type: string
description: |
Reserved for future use. Empty string if not present
example: 'Y'
record_type:
type: string
description: "Type of address record.\n\nPossible values:\n- 'C'\tMulti-Carrier\n- 'F'\tFirm\n- 'G'\tGeneral Delivery\n- 'H'\tHigh-rise or Apartment Building\n- 'M'\tMilitary\n- 'P'\tPO Box\n- 'R'\tRoute (Rural Route/Highway Contract)\n- 'S'\tStreet\n- 'U'\tUnique 5-Digit\n"
enum:
- C
- F
- G
- H
- M
- P
- R
- S
- U
- ''
state:
type: string
description: |
Standard two-letter state abbreviation
example: NM
suite_link_footnote:
type: string
description: |
Results of the SuiteLink lookup.
Possible values: ' ' (Space), '00' (Double Zero), 'A' (A). Empty string if not present
enum:
- ''
- '00'
- A
time_zone:
type: string
description: |
Time zone. Empty string if not present
example: MST
urbanization:
type: string
description: |
Urban name required in the address of all mail being delivered to Puerto Rico. Empty string if not present
example: ''
zip_code:
type: string
description: |
5-digit ZIP Code and the four additional digits
example: 88310-5631
country_iso_2:
type: string
description: |
2 letter country ISO code
example: US
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
UsaVerifyMatch:
title: Address Match
type: object
required:
- query
- query_city
- query_state
- query_zip_code
- match
- count
- fit
- confidence
- match_information
- address_line_one
- address_line_two
- city
- state
- zip_code
- country_iso_2
properties:
query:
type: string
description: Submitted query
query_city:
type: string
description: Submitted city
query_state:
type: string
description: Submitted state
query_zip_code:
type: string
description: Submitted zip_code
match:
description: Nearest matching address
oneOf:
- $ref: '#/components/schemas/UsaCassVerifiedAddress'
- $ref: '#/components/schemas/PafAddress'
- $ref: '#/components/schemas/MrAddress'
- $ref: '#/components/schemas/NybAddress'
- $ref: '#/components/schemas/PafAliasAddress'
- $ref: '#/components/schemas/WelshPafAddress'
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.
match_information:
type: string
description: |
Additional information about the match.
This information is for human consumption and may not be present in all responses.
example: Single Response - The delivery address was found in the National Database and no further information was required.
address_line_one:
type: string
description: |
Primary delivery address
example: 123 Main St
address_line_two:
type: string
description: |
Secondary address information
example: ''
city:
type: string
description: |
City name
example: Springfield
state:
type: string
description: |
State name
example: CO
zip_code:
type: string
description: |
Zip code
example: 81073-1119
country_iso_2:
type: string
description: |
2 letter ISO country code
example: US
UsaVerifyNoMatch:
type: object
title: No Address Match
required:
- query
- query_city
- query_state
- query_zip_code
- match
- count
- fit
- confidence
- address_line_one
- address_line_two
- city
- state
- zip_code
- country_iso_2
properties:
query:
type: string
description: Originally submitted query
query_city:
type: string
description: Originally submitted city
query_state:
type: string
description: Originally submitted state
query_zip_code:
type: string
description: Originally submitted zip_code
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
address_line_one:
type: string
description: |
Empty if no match
enum:
- ''
address_line_two:
type: string
description: |
Empty if no match
enum:
- ''
city:
type: string
description: |
Empty if no match
enum:
- ''
state:
type: string
description: |
Empty if no match
enum:
- ''
zip_code:
type: string
description: |
Empty if no match
enum:
- ''
country_iso_2:
type: string
description: |
Empty if no match
enum:
- ''
VerifyResponse:
title: Address Verify 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/UsaVerifyMatch'
- $ref: '#/components/schemas/UsaVerifyNoMatch'
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: House number or PO Box number
example: '10'
secondary_number:
type: string
description: Unit or apartment number
example: '4'
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: Street name
example: Harvey St
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: Name of the company or building associated with the address
example: Cooper Ltd
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'
- $ref: '#/components/schemas/KadasterAddress'
- $ref: '#/components/schemas/KartverketAddress'
- $ref: '#/components/schemas/SdfiAddress'
- $ref: '#/components/schemas/CannarAddress'
- $ref: '#/components/schemas/FodbosaAddress'
- $ref: '#/components/schemas/MoisAddress'
- $ref: '#/components/schemas/UpujpAddress'
- $ref: '#/components/schemas/BevAddress'
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
- suggestions
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
suggestions:
type: array
items:
type: string
description: Returns an array of suggested email addresses if the email address is not deliverable. The suggested emails are not validated.
example:
- corrected_email@example.com
UnknownEmail:
title: Unknown Email Object
type: object
required:
- result
- deliverable
- role
- free
- disposable
- catchall
- suggestions
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
suggestions:
type: array
items:
type: string
description: Suggestions will be empty
EmailResponse:
title: Email Verification Response
type: object
example:
result:
result: deliverable
deliverable: true
catchall: false
free: false
role: true
disposable: false
suggestions: []
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: |
** Tags **
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
style: form
in: query
schema:
type: integer
format: int64
minimum: 0
description: |
**Start Timestamp**
A start date/time in the form of a UNIX Timestamp in milliseconds. E.g. `1418556452651`
example: 1418556452651
EndParam:
name: end
style: form
in: query
schema:
type: integer
format: int64
minimum: 0
description: |
**End Timestamp**
An end date/time in the form of a UNIX Timestamp in milliseconds. E.g. `1418556477882`
example: 1418556492651
LicenseeParam:
example: sl_hk71kco54zGSGvF9eXXrvvnMOLLNh
description: |
**Licensee Key**
Uniquely identifies a licensee.
explode: false
in: query
name: licensee
schema:
type: string
style: form
DatasetParam:
name: dataset
in: query
style: form
explode: false
schema:
type: array
items:
$ref: '#/components/schemas/Dataset'
description: |
**Filter by Dataset**
Comma-separated list of datasets to search within.
Filters autocomplete results to only include addresses from the specified datasets.
example: paf,nyb
ContextParam:
name: context
in: query
style: form
explode: false
example: GBR
description: |
**Context**
Limits search results, typically within a 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