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.
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 |
