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 Urbanization 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)

C1 – Input address primary number matched, secondary number Not matched, secondary number required

CC – Input address primary number matched, secondary number Not matched, secondary number not required

F1 – Input address matched to a military address

G1 – Input address matched to a general delivery address

IA – Informed address identified

N1 – Input address primary number matched, secondary number missing, secondary number required

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

PB – Identified PO Box street address

R1 – Input address matched to CMRA but PMB designator not present (PMB 123 or #123)

R7 – Addresses that are assigned to a phantom route of R777 or R779

RR – Input address matched to CMRA and PMB designator present (PMB 123 or #123)

TA – Input address primary number matched to DPV by dropping trailing alpha

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
urbanization United States Urbanization (Puerto Rico specific)
deliveryLine1 United States Primary address line that would appear on a piece of mail
deliveryLine2 United States Secondary address line, typically only present in the case of dual addressing where a street address and a PO Box or Rural Route both appear on a piece of mail
lastLine United States Last address line, containing city, state and ZIP code information
noStatReasonCode United States Indicates whether selected address is confirmed as deliverable via Delivery Point Validation process.
1 – IDA (Internal Drop Address) – Addresses that do not receive mail directly from the USPS, but are delivered to a drop address that services them.

2 – CDS No-Stat – Addresses that have not yet become deliverable. For example, a new subdivision where lots and primary numbers have been determined, but no structure exists yet for occupancy.

3 – Collision – Addresses that do not actually DPV confirm. In this case, the ‘Y’ should be set to ‘N’ on the DPV ‘A’ table and all other table values should be blank.

4 – CMZ (College, Military and Other Types) – ZIP + 4 records USPS has incorporated into the data

5 – Regular No-Stat – Indicates addresses not receiving delivery and the addresses are not counted as possible deliveries.

6 – Secondary Required - The address requires secondary information.
drop United States Indicates whether mail is delivered to a single receptacle at a site.
Y – Address listed in the table of drop addresses

N – Address not listed in the table of drop addresses

Blank – Address not presented to hash table
throwback United States Indicates whether mail is not delivered to the street address.
Y – Address listed in the table of throwback addresses

N – Address not listed in the table of throwback addresses

Blank – Address not presented to hash table
nonDeliveryDaysIndicator United States Indicates whether mail delivery is not performed every day of the week.
Y – Address listed in the table of non-delivery-days addresses

N – Address not listed in the table of non-delivery-days addresses

Blank – Address not presented to hash table
noSecureLocation United States Indicates whether door is accessible, but package will not be left due to security concerns
Y – Address listed in the table of no-secure-location addresses

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

Blank – Address not presented to hash table
doorNotAccessible United States Indicates addresses where USPS cannot knock on a door to deliver mail.
Y – Address listed in the table of door-not-accessible addresses

N – Address not listed in the table of door-not-accessible addresses

Blank – Address not presented to hash table
enhancedDpvCode United States Indicates whether selected address is confirmed as deliverable via Delivery Point Validation process.
Y – Address was DPV confirmed for primary/secondary components necessary to determine a valid delivery point

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

S – Address was DPV confirmed for the primary number only, the secondary number information was present but not confirmed or a single trailing alpha on a primary number was dropped to make a DPV match and secondary information required

N – Primary number failed to DPV confirm

R – Address confirmed but assigned to phantom route R777 or R779 and USPS delivery is not provided

Blank – Address not presented to hash table