When a successful Format request is made, Result and Metadata objects will be returned.

Result

The Result object returned on the format call contains the following collections:

global_address_key - Global Address Key corresponding to the input address.

confidence - Confidence level associated with validation of this address.

address – Collection comprising of seven address lines representing the formatted address for a given country.

components – Collection comprising of all available address components.

If the HTTP status code of the response is 200, among other fields, the response body will contain a confidence level.

Confidence Description
Verified match Only 1 address match has been returned.
Multiple matches 2 or more address matches have been returned.
No matches No address matches have been returned.
Insufficient search terms Not enough characters were entered to provide a result.

The Address collection comprises of seven address lines representing the formatted address for a given country, each containing up to 256 characters. The first three address lines will be comprised 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 United Kingdom United States Canada Australia New Zealand France Rest of World
addressLine1 Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line
addressLine2 Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line
addressLine3 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 - ZIP+4 Code Postal Code Postcode Postal Code Postcode Postal Code
country Country Country Country Country Country Country Country

The Components collection comprises of all available address components. Each individual component can be added to relevant fields in your database. Note that components vary slightly from country to country. Components that do not contain any values for the selected address will not be returned by the API. 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.

Main components

Component United Kingdom United States Canada Australia New Zealand France Rest of the World
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.

postal_code component

Sub-component level 1 United Kingdom United States Canada Australia New Zealand France Rest of the World
full_name Postcode Zip code Postal code Postal code Postcode Postcode Postcode
primary Postal code Postcode Postcode
secondary ZIP+4

delivery_service component

Sub-component level 1 United Kingdom United States Canada Australia New Zealand France Rest of the World
full_name Delivery service Delivery service (PO Box xxx) Delivery service (PO Box xxx) All postal delivery types All postal delivery types All PO Box types
service_type Delivery service type Delivery service type e.g. PO Box Delivery service type e.g. PO Box
service_number Delivery service value Delivery service value e.g. 5020 Delivery service value e.g. 5020
post_centre_name

secondary_delivery_service component

Sub-component level 1 United Kingdom United States Canada Australia New Zealand France Rest of the World
full_name Delivery service (Box xxx) Delivery Service
service_type Delivery service type e.g. Box Delivery Service Type
service_number Delivery service value e.g. 5020 Delivery Service Value
post_centre_name

sub_building component

           
Sub-component
level 1
Sub-component
level 2
United
Kingdom
United
States
Canada Australia New
Zealand
France Rest
of the
World
name Building
name/
Flat/
unit
name
(GNAF)
AFNOR
line 3
entrance full_name Sub-
building
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
e.g.
Apartment
or
Suite
type Extension
designation
type
Secondary
address
identifier
Suite
Name
Flat/
unit
type
value Extension
designation
value
Secondary
address
number
Suite
number
Flat/
unit
number

building component

Sub-component level 1 United Kingdom United States Canada Australia New Zealand France Rest of the World
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

organization component

Sub-component
slevel 1
United Kingdom United States Canada Australia New Zealand France Rest of the World
department_name Department Department Department
secondary_
department_name
company_name Organisation name Company name

street component

Sub-component level 1 United Kingdom United States Canada Australia New Zealand France Rest of the World
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

secondary_street component

Sub-component level 1 United Kingdom United States Canada Australia New Zealand France Rest of the World
full_name Secondary Thoroughfare Name & Type
prefix
name Secondary thoroughfare name
type Secondary thoroughfare type
suffix

route_service component

Sub-component level 1 United Kingdom United States Canada Australia New Zealand France Rest of the World
full_name Route service type/number
service_type
service_number
delivery_name
qualifier

locality component

Sub-component
level 1
Sub-component
level 2
United
Kingdom
United
States
Canada Australia New Zealand France Rest
of the
World
region name Départ-
ement
Region
code State
Code
Province
Code
INSEE
code
description
sub_region name County
name
Subregion
code
description
town name Town City
name
Muni-
cipality
Locality Suburb Town/
CEDEX
office
Town
code
description
district name Dependent
locality
Delivery
area
install-
ation
Lobby
name
Geo-
graphic
town
Settlement
code
description
sub_district name Double-
dependent
locality
PNR
Lobby
name
Postal
locality/
Geo-
graphic
town
code
description

physical_locality component

Sub-component
level 1
United
Kingdom
United
States
Canada Australia New Zealand France Rest
of the
World
town town/city
district suburb

Metadata

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.

The following metadata elements are currently available:

Property Sub-property level 1 Sub-property level 2 Country Description
address_info sources Australia Indicates the source of address information:
PAF – Australia Post’s Postal Address File

GNAF – Geoscape Australia’s Geocoded National Address File

(Note: If address appears in both databases, both PAF and GNAF indicators will be returned.)
number_of_households United Kingdom Number of households present at the address for Royal Mail’s Multiple Residence and Not Yet Built addresses
just_built_date United Kingdom Construction date of a property (if activated within the past six months)
identifier udprn United Kingdom Royal Mail’s Unique Delivery Point Reference Number, an eight-digit code assigned to every delivery point in the Postcode Address File (PAF).
umrrn United Kingdom Royal Mail’s Unique Multiple Residence Reference Number, an eight-digit code linked to UDPRNs in Royal Mail's Multiple Residence dataset.
dpid Australia/ New Zealand (AUS) Australia Post’s Delivery Point Identifier, an eight- digit number that uniquely identifies a physical location to which Australia Post delivers mail.
(NZL) New Zealand Post's Delivery Point Identifier, a unique reference number of up to seven digits which is assigned to each delivery point address in the postal address file
gnafPid Australia Geoscape Australia’s Geocoded National Address File Persistent Identifier (G-NAF ID)
hin Australia Household Identification Number (HIN), unique reference ID for each household
paf_address_key United Kingdom Royal Mail’s PAF Address Key
route_classification id New Zealand New Zealand Post’s unique numeric identifier for a street, for example 1324.
carrier_route United States 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.
address_classification delivery_type United States / United Kingdom / Australia delivery_type: type of mail delivery at the address. Value can be either business, residential or mixed.
address_type code Australia / New Zealand / United States Record type code indicating the type of address.
description Australia / New Zealand / United States Description of the address type code.
is_deliverable New Zealand Yes/No indicator of whether the address can receive mail.
barcode sort_plan_number Australia Three-digit Barcode Sort Plan (BSP) number for each full address to facilitate pre-sorting of mail items
delivery_point_barcode United States/ Australia USA: Delivery point barcode (DPBC) consists of ZIP+4 followed by the last two digits of the house/box number, or if the match is made to a highrise record, the secondary unit number representing the delivery point information.
Australia: Customer barcode is a 37- digit string generated from the DPID.
dpv cmra_indicator United States Indicates whether selected address is a Commercial Mail Receiving Agency.
Y – Address listed in the table of CMRA addresses

N – Address not listed in the table of CMRA addresses

Blank – Address not presented to hash table
seed_indicator United States 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).
Y – Address matched to a seed record

N – Address did not match to a seed record

Blank – Address not presented to hash table.
dpv_indicator United States Indicates whether selected address is confirmed as deliverable via Delivery Point Validation process.
Y – Address DPV confirmed for both primary and (if present) secondary numbers

D – Address DPV confirmed for the primary number only, and secondary number information was missing

S – Address DPV confirmed for the primary number only, and secondary number information was present but unconfirmed

N – Both Primary and (if present) Secondary number information failed to DPV Confirm.
footnotes United States Array containing zero or more of the following elements:
AA – Input Address Matched to the ZIP+4 file

A1 – Input Address Not Matched to the ZIP+4 file

BB – Input Address Matched to DPV (all components)

CC – Input Address Primary Number Matched to DPV but Secondary Number not Matched (present but invalid)

N1 – Input Address Primary Number Matched to DPV but Address Missing Secondary Number

M1 – Input Address Primary Number Missing

M3 – Input Address Primary Number Invalid

P1 – Input Address RR or HC Box number Missing

P3 – Input Address PO, RR, or HC Box number Invalid

RR – Input Address Matched to CMRA and PMB designator present (PMB 123 or #123)

R1 – Input Address Matched to CMRA but PMB designator not present (PMB 123 or #123)

F1 – Input Address Matched to a Military Address

G1 – Input Address Matched to a General Delivery Address

U1 – Input Address Matched to a Unique ZIP Code
vacancy_indicator United States Indicates whether selected address is known to be vacant and not receiving mail deliveries
Y – Address listed in the table of vacant addresses

N – Address not listed in the table of vacant addresses

Blank – Address not presented to hash table.
no_stats_indicator United States 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.
Y – Address listed in the table of no-stats addresses

N – Address not listed in the table of no-stats addresses

Blank – Address not presented to hash table.
pbsa_indicator United States 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).
Y – Address listed in the table of PBSA addresses

N – Address not listed in the table of PBSA addresses

Blank – Address not presented to hash table.