Format response

When a successful Format request is made, three collections will be returned.

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

Components – Collection comprising of all available address components.

Metadata – Collection comprising of all available metadata components.

Collections

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
province State Code Province Code State Code City Province
postalCode Postcode Zip - Zip+4 Code Postal Code Postcode PostalCode 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.

Address components United Kingdom United States Canada Australia New Zealand France Rest of World
deliveryService1 Delivery Service Identifier PO Box Route Service Type / Number All Postal Delivery Types All Postal Delivery Types All PO Box Types
deliveryService2 PO Box
deliveryService3 Delivery Service Type / Name
deliveryService4 Box Number
deliveryPointID1 Delivery Point Identifier
subBuilding1 Extension Designation Secondary Number Suite Name / Number Flat / Unit Name Unit Textual + Unit alpha-num Secondary Number + Secondary Number Ext Secondary Address Units e.g. Apartments, Suites, Units etc.
subBuilding2 Building Level Floor Number
subBuilding3 Sub-Building Number Sub-Building Number
subBuilding4 Building Name 2
building1 Building Building Name Building Name Building Name
building2 Group Building Name (Ireland only)
organisation1 Organisation Name Company Name
organisation2 Department Department Name
organisation3
organisation4
streetNumber1 Street Number Primary Number Street Number + Suffix Building Number Street Number Number + Number Extension Address / House Number
streetNumber2 Allotment Number
street1 Primary Thoroughfare Name & Type Street Street Street Street Street Street
street2 Secondary Thoroughfare Name & Type
locality1 Town City Name Municipality Locality Suburb Town Town/City
locality2 Dependent locality Delivery Installation Lobby Name Cedex Office Settlement
locality3 Double-dependent locality PNR Lobby Name Additional Geographic Data
locality4 Rural Delivery Submitted Postal Locality / Geographic Town
locality5 Town / City
locality6 Suburb
county1 County Name County
province1 State Name City Départment Province / State
provinceCode1 State Code Province Code State Code INSEE code
postalCode1 Postcode Zip - Zip+4 Code Postal Code Postal Code Postcode Postcode Postal Code
country1 Country Name Country Name Country Name Country Name Country Name Country Name Country Name
countryISO1 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
countryISO2 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.

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
addressSource code Australia Indicates the source of address information:
P – Australia Post’s Postal Address File (PAF)

G – Geoscape Australia’s Geocoded National Address File (GNAF)

PG - Address appears in both PAF and GNAF
description Australia Description of the address source (e.g., Address exists on both PAF and G-NAF)
justBuiltDate United Kingdom Construction date of a property (if activated within the past six months)
numberOfHouseholds United Kingdom Number of households present at the address for Royal Mail’s Multiple Residence and Not Yet Built addresses
addressIds 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.
pafAddressKey United Kingdom Royal Mail’s PAF Address Key
routeClassification id New Zealand New Zealand Post’s unique numeric identifier for a street, for example 1324.
carrierRoute 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.
addressClassification deliveryType United States / United Kingdom / Australia deliveryType: type of mail delivery at the address. Value can be either business, residential or mixed.
addressType code United States / United Kingdom / Australia Record type code indicating the type of address.
description United States Description of the address type code.
isDeliverable New Zealand Yes/No indicator of whether the address can receive mail.
barcode sortPlanNumber Australia Three-digit Barcode Sort Plan (BSP) number for each full address to facilitate pre-sorting of mail items
deliveryPointBarcode 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 (Delivery Point Validation) cmraIndicator 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
seedIndicator 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.
dpvIndicator 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
vacancyIndicator 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
noStatsIndicator 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
pbsaIndicator 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