The /format endpoint is used to retrieve a fully formatted address by the Autocomplete, Singleline, Typedown, and Lookup search types.
Name | Type | Description |
---|---|---|
Auth-Token | string | Input your unique token here. This is required to submit an API request. |
x-app-key (Optional) |
string | Alternative authentication header. Auth-Token takes precedence. |
Reference-Id (Optional) |
string | Identifier that will be returned to the response to help you track the request. |
Timeout-Seconds (Optional) |
integer | Maximum time you are prepared to wait for a response, expressed in seconds. Acceptable values: 2-15. If a timeout occurs, an HTTP status code of 408 - Request Timeout will be returned. The default value of this setting is 15. |
Add-Components (Optional) |
boolean | Specifies if the response should contain the address broken down into its components. The default value of this setting is false. |
Add-Metadata (Optional) |
boolean | Specify whether the response should return all fields and values, in addition to the main core information. The default value of this setting is false. |
Name | Type | Description |
---|---|---|
global_address_key | string | Global address key of the address you want to retrieve. |
In the request body you can specify the layout and format you want to get the address returned in. If you do not require a custom layout, you can use the /format
GET request as well.
Name | Type | Description | |
---|---|---|---|
layouts (Optional) |
collection | Collection of layout names. The default value of this setting is default which will return a predefined 7 line layout. |
|
layout_format (Optional) |
string | The format of the customized address layout. The available values are:
|
Name | Type | Description |
---|---|---|
Reference-Id (Optional) |
String | Identifier that was supplied by you in the request header to help you track the request. |
The response from the API returns the below fields within a result
object. Should an error occur, an error
object is returned instead.
Name | Type | Description | |
---|---|---|---|
global_address_key | string | The ID of the address matched as part of an address validation. | |
confidence | string | The confidence level of the validation result.
|
|
address | object | The Address object comprises seven address lines representing the formatted address for a given country, each containing up to 256 characters. The first three address lines will be composed of a number of specific components relating to the premises and street. The next four lines contain the locality, province, postal code and country. | |
addresses_formatted | collection | Customized address layouts. | |
components | object | The Components object consists of all available address components. Each individual component can be added to relevant fields in your database. Components that do not contain any values for the selected address will not be returned by the API. This object is only returned when the Add-Components header is set to True on the request. |
The Address object comprises seven address lines representing the formatted address for a given country, each containing up to 256 characters. The first three address lines will be composed of a number of specific components relating to the premises and street. The next four lines contain the locality, province, postal code and country. Country specific information for our most popular countries is shown below:
Address lines | |||||||
---|---|---|---|---|---|---|---|
address_line_1 | Auto Line | Auto Line | Auto Line | Auto Line | Auto Line | Auto Line | Auto Line |
address_line_2 | Auto Line | Auto Line | Auto Line | Auto Line | Auto Line | Auto Line | Auto Line |
address_line_3 | Auto Line | Auto Line | Auto Line | Auto Line | Auto Line | Auto Line | Auto Line |
locality | Town | City Name | Municipality | Locality | Suburb Lobby Name Rural Delivery |
Town | Locality |
region | State Code | Province Code | State Code | City | Province | ||
postal_code | Postcode | ZIP+4 | Postal Code | Postcode | Postal Code | Postcode | Postal Code |
country | Country | Country | Country | Country | Country | Country | Country |
The addresses_formatted
collection is only returned if a custom layout has been supplied.
Name | Type | Description | |
---|---|---|---|
addresses_formatted | collection | Collection of formatted addresses. | |
layout_name | string | Name of the layout. | |
address | object | This object is returned if layout_format is set to default or omitted from the request. |
|
address_lines | collection | This object is returned if layout_format is set to address_lines. |
|
not_enough_lines | boolean | There are not enough address lines configured to display the whole address. This object can only be returned if layout_format is set to address_lines. |
|
has_truncated_lines | boolean | Truncation has occurred on one or more address lines. This object can only be returned if layout_format is set to address_lines. |
|
has_missing_sub_premises | boolean | The missing subpremise attribute specifies if the address is missing a subpremise when using the validate search type. It can be ignored when using all other engines. This object can only be returned if layout_format is set to address_lines. |
The Components object comprises seven address lines representing the formatted address for a given country, each containing up to 256 characters. The first three address lines will be composed of a number of specific components relating to the premises and street. The next four lines contain the locality, province, postal code and country. The full list of components with details for our most popular countries plus a rest of world column for all other supported countries can be found below.
Only returned if
Name | |||||||
---|---|---|---|---|---|---|---|
language | Language | Language | Language | Language | Language | Language | Language |
country_name | Country name | Country name | Country name | Country name | Country | Country | Country name |
country_iso_3 | ISO 3166-1 alpha-3 country code | ISO 3166-1 alpha-3 country code | ISO 3166-1 alpha-3 country code | ISO 3166-1 alpha-3 country code | ISO 3166-1 alpha-3 country code | ISO 3166-1 alpha-3 country code | ISO 3166-1 alpha-3 country code |
country_iso_2 | ISO 3166-2 code* | ISO 3166-2 code* | ISO 3166-2 code* | ISO 3166-2 code* | ISO 3166-2 code* | ISO 3166-2 code* | ISO 3166-2 code* |
/* ISO 3166-2 standard consists of two parts: the first part is the ISO 3166-1 alpha-2 country code, the second part (when present) is a string of up to three alphanumeric characters indicating country subdivision.
Name | |||||||
---|---|---|---|---|---|---|---|
full_name | Postcode | Zip code | Postal code | Postal code | Postcode | Postcode | Postcode |
primary | ZIP | Postal code | Postcode | Postcode | |||
secondary | Plus4 |
Name | |||||||
---|---|---|---|---|---|---|---|
full_name | Delivery service | Delivery service | Delivery service | All postal delivery types | All postal delivery types | All PO Box types | |
service_type | Delivery Service type | Delivery Service type | Delivery Service type | ||||
service_number | Delivery Service value | Delivery Service value | Delivery Service value | ||||
post_centre_name |
Name | |||||||
---|---|---|---|---|---|---|---|
full_name | Delivery Service | Delivery Service | |||||
service_type | Delivery Service type | Delivery Service type | |||||
service_number | Delivery Service value | Delivery Service value | |||||
post_centre_name |
Name | |||||||||
---|---|---|---|---|---|---|---|---|---|
name | Building name / Flat / Unit name (GNAF) | AFNOR line 3 | |||||||
entrance | |||||||||
full_name | Subbuilding number | ||||||||
type | |||||||||
value | |||||||||
floor | |||||||||
full_name | Building Level | ||||||||
type | Building Level type | ||||||||
value | Building Level number | ||||||||
door | |||||||||
full_name | Extension designation | Secondary number | Suite name / number | Flat / Unit name | Unit textual + Unit AlphaNum | Secondary address unit | |||
type | Extension designation type | Secondary address identifier | Suite Name | Flat / Unit type | |||||
value | Extension designation value | Secondary address number | Suite number | Flat / Unit number |
Name | |||||||
---|---|---|---|---|---|---|---|
building_name | Building name | Building name | Building name | Additional geographic data | Building name | ||
secondary_name | Group building name (Ireland only) | ||||||
building_number | Street number | Primary number | Street number + Suffix | Building number | Street number | Number and Number extension | Address/ house number |
secondary_number | Secondary number and Secondary number extension | ||||||
allotment_number | Allotment number |
Name | |||||||
---|---|---|---|---|---|---|---|
department_name | Department | Department | Department | ||||
secondary _department_name |
|||||||
company_name | Organization name | Company name |
Name | |||||||
---|---|---|---|---|---|---|---|
full_name | Primary thoroughfare name & type | Full street name | Full street name | Street | Street | Street | Full street name |
prefix | Street prefix | Street prefix | |||||
name | Primary thoroughfare name | Street name | Street name | Street name | Primary street name | ||
type | Primary thoroughfare type | Street type | Street type | Street type | Street type | Primary street type | |
suffix | Street suffix | Street suffix | Street type suffix |
Name | |||||||
---|---|---|---|---|---|---|---|
full_name | Secondary Thoroughfare Name & Type | ||||||
prefix | |||||||
name | Secondary thoroughfare name | ||||||
type | Secondary thoroughfare type | ||||||
suffix |
Name | ||||||||
---|---|---|---|---|---|---|---|---|
region | ||||||||
name | Département | Region | ||||||
code | State Code | Province Code | INSEE code | |||||
description | ||||||||
sub_region | ||||||||
name | County name |
Subregion | ||||||
code | ||||||||
description | ||||||||
town | ||||||||
name | Town | City name | Municipality | Locality | Suburb | Town / CEDEX office | Town | |
code | ||||||||
description | ||||||||
district | ||||||||
name | Dependent locality | Delivery area installation | Lobby name | Geographic town | Settlement | |||
code | ||||||||
description | ||||||||
sub_district | ||||||||
name | Double-dependent locality | PNR Lobby name |
Postal locality / Geographic town | |||||
code | ||||||||
description |
The Metadata object contains additional information about the returned address, such as deliverability indicators. The metadata can be stored in your database or used to decide if the address should be rejected.
Metadata is only supported for certain countries (see table below). For all other countries, an empty metadata object will be returned.
Only returned if
The following metadata elements are currently available:
Name | Country | Description | ||
---|---|---|---|---|
address_info | ||||
sources | Indicates the source of address information:
|
|||
number_of_households | Number of households present at the address for Royal Mail's Multiple Residence and Not Yet Built addresses. | |||
just_built_date | Construction date of a property, if activated within the past six months. | |||
identifier | ||||
udprn | Royal Mail's Unique Delivery Point Reference Number, an eight-digit code assigned to every delivery point in the Postcode Address File (PAF). | |||
umrrn | Royal Mail's Unique Multiple Residence Reference Number, an eight-digit code linked to UDPRNs in Royal Mail's Multiple Residence dataset. | |||
dpid | Delivery Point Identifier that uniquely identifies an address:
|
|||
gnafPid | Geoscape Australia's Geocoded National Address File Persistent Identifier (G-NAF ID). | |||
hin | Household Identification Number (HIN), unique reference ID for each household. | |||
paf_address_key | Royal Mail's PAF Address Key. | |||
route_classification | ||||
id | New Zealand Post's unique numeric identifier for a street, for example 1324. | |||
carrier_route | Code assigned by the USPS to a group of addresses to aid mail delivery within a ZIP code. Consists of a carrier route type and carrier route code (length: 4 bytes). For example, C001. | |||
barcode | ||||
sort_plan_number | Three-digit Barcode Sort Plan (BSP) number for each full address to facilitate pre-sorting of mail items. | |||
delivery_point_barcode |
|
|||
address_classification | ||||
delivery_type | The type of mail delivery at the address:
|
|||
address_type | ||||
code | Record type code indicating the type of address. | |||
description | Description of the address type code. | |||
is_deliverable | Indicates whether the address can receive mail. | |||
dpv | ||||
cmra_indicator | Indicates whether selected address is a Commercial Mail Receiving Agency.
|
|||
seed_indicator | Indicates whether selected address is a seed address. Seed records are control records placed by the USPS to prevent unauthorized tampering (e.g., creation of lists containing every single delivery point in a geographical region).
|
|||
dpv_indicator | Indicates whether selected address is confirmed as deliverable via Delivery Point Validation process.
|
|||
footnotes | Array containing zero or more of the following elements:
|
|||
vacancy_indicator | Indicates whether selected address is known to be vacant and not receiving mail deliveries:
|
|||
no_stats_indicator | Indicates whether selected address is not receiving mail deliveries. These addresses are not receiving delivery because a) delivery has not been established; b) customer receives mail as a part of a drop; or c) the address is no longer a possible delivery because the carrier destroys or returns all of the mail. Addresses for delivery points in gated communities may also be identified as No-Stats.
|
|||
pbsa_indicator | Indicates whether selected address is a Post Office Box Street Address, a USPS alternative to traditional PO BOX addresses for customers who require a formal street address for delivery (as opposed to a PO BOX number).
|
The following response codes can be returned by the API:
Status Code | Reason phrase | Description |
---|---|---|
200 | Success | Request processed successfully. |
400 | Bad Request | Request failed due to malformed syntax. |
401 | Unauthorized | Auth-Token provided is incorrect. |
403 | Forbidden | Request is not authorized to use this service. |
406 | Not Acceptable | Request is not in an acceptable format. |
408 | Request Timeout | Response was not returned within the timeout allowance. |
415 | Unsupported Media Type | Request is not using a Media type that is recognized by the server. |
429 | Too many requests | Too many requests were sent. To protect all customers, your account has been temporarily throttled. Check our rate limiting for more details. |
500 | Internal Server Error | The server has encountered an error. |
503 | Service Unavailable | Service unavailable. Check service status for up-to-date information. |
GET /address/format/v1/UdSdlkyc0FBQUFBQUEtLX4yNX43 HTTP/1.1
Add-Metadata: true
Add-Components: true
{
"result": {
"global_address_key": "UdSdlkyc0FBQUFBQUEtLX4yNX43",
"confidence": "Verified match",
"address": {
"address_line_1": "U 55 49-51 Queens Rd",
"address_line_2": "",
"address_line_3": "",
"locality": "FIVE DOCK",
"region": "NSW",
"postal_code": "2046",
"country": "AUSTRALIA"
},
"components": {
"language": "en-GB",
"country_name": "AUSTRALIA",
"country_iso_3": "AUS",
"country_iso_2": "AU-NSW",
"postal_code": {
"full_name": "2046",
"primary": "2046"
},
"sub_building": {
"door": {
"full_name": "U 55",
"type": "U",
"value": "55"
}
},
"building": {
"building_number": "49-51"
},
"street": {
"full_name": "Queens Rd",
"name": "Queens",
"type": "Rd"
},
"locality": {
"town": {
"name": "FIVE DOCK"
}
}
}
},
"metadata": {
"address_info": {
"identifier": {
"hin": "1001307350"
}
},
"barcode": {
"delivery_point_barcode": "1301012030001212203021330300311323213",
"sort_plan_number": "006"
},
"address_classification": {
"delivery_type": "residential"
}
}
}
POST /address/format/v1/UdSdlkyc0FBQUFBQUEtLX4yNX43 HTTP/1.1
Add-Metadata: false
Add-Components: false
{
"layouts": [ "your layout name" ],
"layout_format": "default" // ("default" or "address_lines")
}
{
"result": {
"global_address_key": "UdSdlkyc0FBQUFBQUEtLX4yNX43",
"confidence": "Verified match",
"addresses_formatted": [
{
"layout_name": "your layout name",
"address": {
"StreetAddress1": "U 55 49-51 Queens Rd",
"StreetAddress2": "",
"Suburb": "FIVE DOCK",
"City": "FIVE DOCK",
"StateCode": "NSW",
"PostCode": "2046",
"CountryCode": "AU"
}
}
]
}
}
POST /address/format/v1/UdSdlkyc0FBQUFBQUEtLX4yNX43 HTTP/1.1
Add-Metadata: false
Add-Components: false
{
"layouts": [ "your layout name" ],
"layout_format": "address_lines" // ("default" or "address_lines")
}
{
"result": {
"global_address_key": "UdSdlkyc0FBQUFBQUEtLX4yNX43",
"confidence": "Verified match",
"addresses_formatted": [
{
"layout_name": "your layout name",
"address_lines": [
{
"label": "StreetAddress1",
"line": "U 55 49-51 Queens Rd",
"line_content": "address"
},
{
"label": "StreetAddress2",
"line": "",
"line_content": "address"
},
{
"label": "Suburb",
"line": "FIVE DOCK",
"line_content": "address"
},
{
"label": "City",
"line": "FIVE DOCK",
"line_content": "address"
},
{
"label": "StateCode",
"line": "NSW",
"line_content": "address"
},
{
"label": "PostCode",
"line": "2046",
"line_content": "address"
},
{
"label": "CountryCode",
"line": "AU",
"line_content": "address"
}
]
}
]
}
}
GET /address/format/v1/R1g2fjcuNzMwQU9HWDZDZ3ps HTTP/1.1
Add-Metadata: true
Add-Components: true
{
"result": {
"global_address_key": "R1g2fjcuNzMwQU9HWDZDZ3ps",
"confidence": "Verified match",
"address": {
"address_line_1": "Experian Data Quality",
"address_line_2": "160 Blackfriars Road",
"address_line_3": "",
"locality": "LONDON",
"region": "",
"postal_code": "SE1 8EZ",
"country": "UNITED KINGDOM"
},
"components": {
"country_name": "UNITED KINGDOM",
"country_iso_3": "GBR",
"country_iso_2": "GB",
"postal_code": {
"full_name": "SE1 8EZ",
"primary": "SE1 8EZ"
},
"building": {
"building_number": "160"
},
"street": {
"full_name": "Blackfriars Road",
"name": "Blackfriars",
"type": "Road"
},
"locality": {
"town": {
"name": "LONDON"
}
}
}
},
"metadata": {
"address_info": {
"identifier": {
"udprn": "55244256",
"paf_address_key": "3796984103990845S"
}
},
"barcode": {
"delivery_point_barcode": "(SE18EZ1P7)"
}
}
}
POST /address/format/v1/R1g2fjcuNzMwQU9HWDZDZ3ps HTTP/1.1
Add-Metadata: false
Add-Components: false
{
"layouts": [ "your layout name" ],
"layout_format": "default" // ("default" or "address_lines")
}
{
"result": {
"global_address_key": "R1g2fjcuNzMwQU9HWDZDZ3ps",
"confidence": "Verified match",
"addresses_formatted": [
{
"layout_name": "your layout name",
"address": {
"LINE_1": "Experian Data Quality",
"LINE_2": "160 Blackfriars Road",
"Town": "LONDON",
"County": "",
"Postcode": "SE1 8EZ"
}
}
]
}
}
POST /address/format/v1/R1g2fjcuNzMwQU9HWDZDZ3ps HTTP/1.1
Add-Metadata: false
Add-Components: false
{
"layouts": [ "your layout name" ],
"layout_format": "address_lines" // ("default" or "address_lines")
}
{
"result": {
"global_address_key": "R1g2fjcuNzMwQU9HWDZDZ3ps",
"confidence": "Verified match",
"addresses_formatted": [
{
"layout_name": "TestGBR Staging",
"address_lines": [
{
"label": "",
"line": "Experian Data Quality",
"line_content": "none"
},
{
"label": "",
"line": "160 Blackfriars Road",
"line_content": "none"
},
{
"label": "Town",
"line": "LONDON",
"line_content": "address"
},
{
"label": "County",
"line": "",
"line_content": "address"
},
{
"label": "Postcode",
"line": "SE1 8EZ",
"line_content": "address"
}
]
}
]
}
}
GET /address/format/v1/eE5ESXpBQUFBQUFBLX4yNn43 HTTP/1.1
Add-Metadata: true
Add-Components: true
{
"result": {
"confidence": "Verified match",
"address": {
"address_line_1": "77 Massachusetts Ave",
"address_line_2": "",
"address_line_3": "",
"locality": "Cambridge",
"region": "MA",
"postal_code": "02139-4307",
"country": "UNITED STATES OF AMERICA"
},
"components": {
"country_name": "UNITED STATES OF AMERICA",
"country_iso_3": "USA",
"country_iso_2": "US",
"postal_code": {
"full_name": "11423-1826",
"primary": "11423",
"secondary": "1826"
},
"building": {
"building_number": "8800"
},
"street": {
"full_name": "187th St",
"name": "187th",
"type": "St"
},
"locality": {
"region": {
"code": "NY"
},
"sub_region": {
"name": "Queens"
},
"town": {
"name": "Hollis"
}
}
}
},
"metadata": {
"barcode": {
"delivery_point_barcode": "11423182600",
"check_digit": "2"
},
"route_classification": {
"carrier_route": "C052"
},
"address_classification": {
"address_type": {
"code": "S",
"description": "Street"
},
"delivery_type": "Residential"
}
}
}
POST /address/format/v1/eE5ESXpBQUFBQUFBLX4yNn43 HTTP/1.1
Add-Metadata: false
Add-Components: false
{
"layouts": [ "your layout name" ],
"layout_format": "default" // ("default" or "address_lines")
}
{
"result": {
"global_address_key": "eE5ESXpBQUFBQUFBLX4yNn43",
"confidence": "Verified match",
"addresses_formatted": [
{
"layout_name": "your layout name",
"address": {
"Organisation": "",
"Street 1": "8801 187th St",
"Street 2": "",
"Street 3": "",
"City": "Hollis",
"State/Province": "NY",
"ZIP/Postal Code": "11423",
"Country/Region": "UNITED STATES OF AMERICA"
}
}
]
}
}
POST /address/format/v1/eE5ESXpBQUFBQUFBLX4yNn43 HTTP/1.1
Add-Metadata: false
Add-Components: false
{
"layouts": [ "your layout name" ],
"layout_format": "address_lines" // ("default" or "address_lines")
}
{
"result": {
"global_address_key": "eE5ESXpBQUFBQUFBLX4yNn43-MzB-Nw",
"confidence": "Verified match",
"addresses_formatted": [
{
"layout_name": "your layout name",
"address_lines": [
{
"label": "Organisation",
"line": "",
"line_content": "address"
},
{
"label": "Street 1",
"line": "8800 187th St",
"line_content": "address"
},
{
"label": "Street 2",
"line": "",
"line_content": "none"
},
{
"label": "Street 3",
"line": "",
"line_content": "none"
},
{
"label": "City",
"line": "Hollis",
"line_content": "address"
},
{
"label": "State/Province",
"line": "NY",
"line_content": "address"
},
{
"label": "ZIP/Postal Code",
"line": "11423",
"line_content": "address"
},
{
"label": "Country/Region",
"line": "UNITED STATES OF AMERICA",
"line_content": "address"
}
]
}
]
}
}