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