The /suggestions/format endpoint is used to retrieve fully formatted address versions of all full addresses in a list of suggestions.

Headers

Name Type Description
Auth-Token string Input your unique token here. This is required to submit an API request.
x-app-key
(Optional)
string Alternative authentication header. Auth-Token takes precedence.
Reference-Id
(Optional)
string Identifier that will be returned to the response to help you track the request.
Timeout-Seconds
(Optional)
integer Maximum time you are prepared to wait for a response, expressed in seconds.
Acceptable values: 2-15. If a timeout occurs, an HTTP status code of 408 - Request Timeout will be returned.

The default value of this setting is 15.
Add-Components
(Optional)
boolean Specifies if the response should contain the address broken down into its components.

The default value of this setting is false.
Add-Metadata
(Optional)
boolean Specify whether the response should return all fields and values, in addition to the main core information.

The default value of this setting is false.

Body parameters

In the request body you can specify:

Name Type Description
country_iso string The ISO3 code of the country you want to search against.
datasets collection The collection of datasets you want to search against (multiple datasets are currently only supported for UK).
max_suggestions
(Optional)
integer The maximum number of suggestions you want to get returned.
Acceptable values: 1-100

The default value of this setting is 7.
components object Object defining the input components.
unspecified collection Collection of unspecified text inputs.
layouts
(Optional)
collection Collection of layout names.

The default value of this setting is default which will return a predefined 7 line layout.

Headers

Name Type Description
Reference-Id
(Optional)
string Identifier that was supplied by you in the request header to help you track the request.

Body

The response from the API returns the below fields within a result object. Should an error occur, an error object is returned instead.

Name Type Description
more_results_available boolean To indicate that there are more suggestions available than returned in this request.
confidence string The confidence level of the result.
  • Verified match: The input was matched to a single deliverable address in our data. This result may be slightly different from the provided address because we corrected formatting/spelling errors and added any missing address elements.
  • Multiple matches: The input was matched to more than one deliverable address in our data. This can happen when the provided address doesn't contain enough information to return just one match. As a result, the returned addresses may or may not be deliverable addresses. Therefore, a list of suggestions containing all the matches will be returned and the user has to select the required address.
  • Too many matches: The input was too broad and matched too many addresses in our data. The user should be further prompted to provide additional information.
  • Interaction required: The input was matched to a single deliverable address in our data. However, user interaction is recommended as the confidence in the validity of this address is not high enough for it to be classed as a Verified match.
  • Premises partial: The input was partially matched to a deliverable address in our data. For example, a search on "Flat A, 63 Southerton Road, London" could be matched to "63 Southerton Road, London" only. Therefore, a list of suggestions containing all the partial matches will be returned and the user has to select the required address.
  • Street partial: The input was partially matched to a deliverable address in our data. For example, a search on "63 Southerton Road, London" could be matched to "Southerton Road, London" only. Therefore, a list of suggestions containing all the partial matches will be returned and the user has to select the required address.
  • Verified place: The input was matched to a single deliverable address in our data but the street information is missing. This result may be slightly different from the provided address because we corrected formatting/spelling errors and added any missing address elements.
  • Verified street: The input was matched to a single deliverable address in our data but the building information is missing. This result may be slightly different from the provided address because we corrected formatting/spelling errors and added any missing address elements.
  • Incomplete address: The input was matched to an address in our data, but is not deliverable. This is commonly returned when searching within data that does not contain building level information. If the user selects a suggestion with this attribute set, then they should be further prompted to provide additional building level information so that the address is deliverable.
  • Insufficient search terms: The input did not contain enough characters to provide a meaningful result.
  • No matches: The input could not be matched to any deliverable results in our data. Therefore, address validation is not possible and the address provided by the user should be used.
suggestions collection The collection of the suggestions that match the address search input.
global_address_key string The ID of the address matched as part of a search.
address object The Address object comprises seven address lines representing the formatted address for a given country, each containing up to 256 characters. The first three address lines will be composed of a number of specific components relating to the premises and street. The next four lines contain the locality, province, postal code and country.
addresses_formatted collection Customized address layouts.
components object The Components object consists of all available address components. Each individual component can be added to relevant fields in your database. Components that do not contain any values for the selected address will not be returned by the API.
This object is only returned when the Add-Components header is set to True on the request.
metadata object 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.
This object is only returned when the Add-Metadata header is set to True on the request.

Address object

The Address object comprises seven address lines representing the formatted address for a given country, each containing up to 256 characters. The first three address lines will be composed 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 the World
address_line_1 Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line
address_line_2 Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line Auto Line
address_line_3 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+4 Postal code Postcode Postal code Postcode Postal code*
country Country Country Country Country Country Country Country

* This element may not be applicable to every supported country and territory.

Addresses_formatted collection

The addresses_formatted collection is only returned if a custom layout has been supplied. To use our Utilities Enrichment, use the electricityutility and/or gasutility layout to return the relevant enrichment fields.

Name Type Description
addresses_formatted collection Collection of formatted addresses.
layout_name string Name of the layout.
address object This object is returned if layout_format is set to default or omitted from the request. This is where the electricity_meters and gas_meters fields will be returned.
address_lines collection This object is returned if layout_format is set to address_lines.
not_enough_lines boolean There are not enough address lines configured to display the whole address.
This object can only be returned if layout_format is set to address_lines.
has_truncated_lines boolean Truncation has occurred on one or more address lines.
This object can only be returned if layout_format is set to address_lines.
has_missing_sub_premises boolean The missing subpremise attribute specifies if the address is missing a subpremise when using the validate search type. It can be ignored when using all other engines.
This object can only be returned if layout_format is set to address_lines.
Name Description
mpan Meter Point Administration Number
uprn Unique Property Reference Number
address_line_1 – 9 Metering Point address line 1 – 9
address_postal_code Metering Point postcode
trading_status A status assigned to an MPAN that indicates whether the MPAN is currently being supplied with electricity or not:
  • T: for Traded.
  • C: for Closed.
  • X: for Disconnected.
  • S: for Standing.
  • P: for Pending.
  • D: for De-energised.
  • R: for Rejected.
  • U: for Unknown.
  • M: for Metered.
  • F: for Unmetered.
  • E: for Energised.
  • N: for Non-energised.
  • A: for Abandoned.
  • B: for Blocked.
  • Z: for Inactive.
  • Q: for Queried.
  • V: for Void.
  • W: for Withdrawn.
  • Y: for Pending Closure.
  • G: for Pending Disconnection.
  • H: for Pending Reconnection.
  • I: for Pending Energisation.
  • J: for Pending De-energisation.
  • K: for Pending Metering.
  • L: for Pending Non-Energisation.
  • O: for Pending Abandonment.
  • X1: for Disconnected - No Meter.
  • X2: for Disconnected - No Supply.
  • X3: for Disconnected - No Connection.
  • X4: for Disconnected - No MPAN.
  • X5: for Disconnected - No MPRN.
  • X6: for Disconnected - No Connection and No Meter.
  • X7: for Disconnected - No Connection and No Supply.
  • X8: for Disconnected - No Connection and No MPAN.
  • X9: for Disconnected - No Connection and No MPRN.

trading_status_efd MPAN trading status effective from date.
profile_class Identifies the type of electricity metering system installed at a premises. It is used to determine the number of registers on the meter and the time.
  • 1: domestic unregistered
  • 2: domestic economy 7
  • 3: non-domestic unrestricted
  • 4: non-domestic economy 7
  • 5: non domestic load factor 0-20%
  • 6: non domestic load factor 20-30%
  • 7: non domestic load factor 30-40%
  • 8: non domestic load factor +40%

profile_class_efd Profile class effective from date.
meter_timeswitch_class A code that identifies the type of metering equipment installed at a Metering Point.
meter_timeswitch_class_efd Meter time-switch class effective from date.
line_loss_factor A measure of the energy lost in the distribution of electricity from the point of generation to the point of consumption.
line_loss_factor_efd Line loss factor class effective from date.
standard_settlement_configuration A term used in the UK electricity industry to describe the set of parameters that define how energy consumption is measured and billed for a particular metering point.
standard_settlement_configuration_efd Standard Settlement Configuration effective from date.
energisation_status Energisation status:
  • E: Energised
  • D De-energised

energisation_status_efd Energisation status effective from date.
gsp_group_id A unique identifier used to identify the location of the GSP (Grid Supply Point) Group, and used in the MPAN to identify the distribution network operator that supplies the electricity to the premises:
  • A:Eastern
  • B: East Midlands
  • C: London
  • D: Merseyside and North Wales
  • E: Midlands
  • F: Northern
  • G: North Western
  • H: Southern
  • J:South Eastern
  • K: South Wales
  • L: South Western
  • M: Yorkshire
  • N: South Scotland
  • P: North Scotland

gsp_group_efd Grid Supply Point Group effective from date
data_aggregator_mpid A unique identifier assigned to a Data Aggregator by the Code Manager. It is used to identify the Data Aggregator in the ECOES system.
data_aggregator_efd Data Aggregator appointment effective from date
data_collector_mpid A unique identifier assigned to a Data Collector by the Registration Authority. It is used to identify the Data Collector in communications with other market participants.
data_collector_efd Data Collector appointment effective from date
supplier_mpid A unique identifier assigned to each Supplier by the REC. It is used to identify the Supplier in the Central Switching System (CSS) and other industry systems.
supplier_efd Effective From date of the current supplier
meter_operator_mpid A unique identifier assigned to a Meter Operator (MOP) by ELEXON. The MOP MPID is used to identify the MOP in the BSC Central Systems and is used in the BSC processes to identify the MOP responsible for a Metering System.
meter_operator_efd Meter Operator appointment effective from date.
measurement_class Measurement class:
  • A: Non-Half Hourly Metered
  • B: Non-Half Hourly Unmetered
  • C: HH metered in 100kW premises
  • D: Half Hourly Unmetered
  • E: HH metered sub 100kw CT
  • F: Half Hourly Metering Equipment at sub 100kW premises with current transformer or whole current and at Domestic Premises
  • G: Half Hourly Metering Equipment at sub 100kW premises with whole current and not at Domestic Premises

measurement_class_efd Measurement Class effective from date.
green_deal_in_effect An indicator (True/False) whether Green Deal is currently active for this MPAN.
smso_mpid Smart Metering System Operator MPID.
smso_efd Smart Metering System Operator effective from date.
dcc_service_flag A Data Communications Company service flag that indicates whether a smart meter is SMETS comiant or not.
  • A: Active
  • N: Inactive
  • I: Installed not commissioned

dcc_service_flag_efd Data Communications Company Service Flag effective from date.
ihd_status In Home Display Install status. This refers to the status of the IHD following a Smart or Dumb Meter exchange.
  • Declined: Customer has chosen not to have an in home display from the supplier.
  • Existing: Customer has an in home display when changing supplier.
  • Installed: Customer has accpeted offer of in-home display from the supplier and ths has been installed.

ihd_status_efd In Home Display Install status effective from date.
smets_version Smart Metering Equipment Technical Specification version.
distributor_mpid A unique identifier assigned to each Distribution Network Operator (DNO) and Independent Distribution Network Operator (IDNO) in the UK. It is used to identify the DNO or IDNO responsible for a particular electricity supply point.
metered_indicator Identifies whether a supply is metered or unmetered (F).
metered_indicator_efd Metered Indicator effective from date.
metered_indicator_etd Metered Indicator effective to date
consumer_type The classification of consumer based on their usage of energy, e.g. Domestic Consumer or Non-domenstic Consumer.
relationship_status_indicator A flag that indicates whether a Meter Point is in a relationship with another Meter Point. It is used to identify the Meter Points that are in a relationship for the purposes of Data Cleanse Reports.
rmp_state RMP State: Created, Registerd, Traded or Disconnected.
rmp_efd RMP State effective from date
domestic_consumer_indicator Domestic Consumer Indicator as supplied via CSS messages
css_supplier_mpid Current supplier as supplied via CSS messages
css_supply_start_date The date on which the CSS Provider has confirmed that the Gaining Supplier is the registered Supplier for the MPAN(s) and the supply of electricity to the MPAN(s) is to commence.
meter_serial_number Meter Serial Number
meter_install_date Meter Install Date
meter_type Meter Type
map_mpid Meter Asset Provider MPID
map_mpid_efd Meter Asset Provider effective from date
installing_supplier_mpid A unique identifier assigned to the energy supplier who installed the metering equipment at the premises.
rel_address_primary_name The Primary Addressable Object description. This is normally the name and or number of the property.
rel_address_secondary_name The Secondary Addressable Object description, e.g. the “Flat 2” in the address “Flat 2, London House, Exeter”. This is only relevant for a child property. “London House” in this case will the Primary Name of the parent property.
rel_address_street1 DPA – thoroughfare
LPI – derived from street
rel_address_street2 DPA – dependent thoroughfare
LPI – blank
rel_address_locality1 DPA – dependent locality
LPI – derived from street
rel_address_locality2 DPA – double dependent locality
LPI – blank
rel_address_town DPA – post town
LPI – derived from street
rel_address_postcode Postcode associated with the address
rel_address_logical_status The status of the address.
  • 0: no logical status
  • 1: approved (official version)
  • 3: alternative (alias address e.g. house name added)
  • 6: provisional (temporary for eg new builds)
  • 8: historic

rel_address_language The language of the address (ISO 639-2 Code). For example 'eng' stands for English and 'cym' stands for Welsh.
rel_address_organisation Current organisation name of the property if one exists.
rel_address_address_type The type of address of this entry:
DPA – Delivery Point Address
LPI – Local Property Identifier
rel_address_confidence_score A relative confidence score on the match from MPL to REL. Scored 0-100.
rel_address_classification Classification code of the property as per the AddressBase Premium classification scheme.
  • Matched: an address is matched to the GB Standardised Address List
  • Manual: a consumer insists the initial address is incorrect and the address is manually entered.
  • MPL: the Gold Standard required to match the source address to Ordnance Survey AddressBase Premium has not been matched. The MPL address will be used until a Gold Standard match is made or it is manually updated in the enduring solution. Local UPRN is assigned.

rel_address_latitude Latitude of the associated property, usually either the centroid of the building polygon or a general internal point within the building polygon.
rel_address_longitude Longitude of the associated property, usually either the centroid of the building polygon or a general internal point within the building polygon.
Name Description
mprn Meter Point Reference Number.
uprn Unique Property Reference Number.
rel_address_primary_name The Primary Addressable Object description. This is normally the name and or number of the property.
rel_address_secondary_name The Secondary Addressable Object description, e.g. the “Flat 2” in the address “Flat 2, London House, Exeter”. This is only relevant for a child property. “London House” in this case will the Primary Name of the parent property.
rel_address_street1 DPA – thoroughfare
LPI – derived from street
rel_address_street2 DPA – dependent thoroughfare
LPI – blank
rel_address_locality1 DPA – dependent locality
LPI – derived from street
rel_address_locality2 DPA – double dependent locality
LPI – blank
rel_address_town DPA – post town
LPI – derived from street
rel_address_postcode Postcode associated with the address
rel_address_logical_status The status of the address.
  • 0: no logical status
  • 1: approved (official version)
  • 3: alternative (alias address e.g. house name added)
  • 6: provisional (temporary for eg new builds)
  • 8: historic

rel_address_language The language of the address (ISO 639-2 Code). For example 'eng' stands for English and 'cym' stands for Welsh.
rel_address_organisation Current organisation name of the property if one exists.
rel_address_address_type The type of address of this entry:
DPA – Delivery Point Address
LPI – Local Property Identifier
rel_address_confidence_score A relative confidence score on the match from MPL to REL. Scored 0-100.
rel_address_classification Classification code of the property as per the AddressBase Premium classification scheme.
  • Matched: an address is matched to the GB Standardised Address List
  • Manual: a consumer insists the initial address is incorrect and the address is manually entered.
  • MPL: the Gold Standard required to match the source address to Ordnance Survey AddressBase Premium has not been matched. The MPL address will be used until a Gold Standard match is made or it is manually updated in the enduring solution. Local UPRN is assigned.

rel_address_latitude Latitude of the associated property, usually either the centroid of the building polygon or a general internal point within the building polygon.
rel_address_longitude Longitude of the associated property, usually either the centroid of the building polygon or a general internal point within the building polygon.
meter_serial The manufacturer's meter serial number as held on the physical meter currently installed on the supply point.
offtake_quantity_annual The current annual offtake quantity (AQ) of a Supply Meter Point. Value in kWh.
meter_point_status The current status of the operability of the supply meter point. LI = Live; DE = Dead; CA = Capped; CL = Clamped; PL = Planned.
installer_id The smart meter Supplier ID.
network_name Gas Distribution Network Name.
supplier_name The name of the current Supplier.
last_meter_read_date The date on which the last meter read recorded at the site.
last_meter_read_type Latest meter read type.
last_meter_read_value The last meter read value.

Components object

The Components object comprises seven address lines representing the formatted address for a given country, each containing up to 256 characters. The first three address lines will be composed of a number of specific components relating to the premises and street. The next four lines contain the locality, province, postal code and country. 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.

Name United Kingdom United States Canada Australia New Zealand France Rest of the world
language Language Language Language Language Language Language Language
country_name Country Country Country Country Country Country Country
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.

Name 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 ZIP Postal code Postcode Postcode
secondary Plus4
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Delivery service Delivery service Delivery service All postal delivery types All postal delivery types All PO Box types
service_type Delivery service type Delivery service type Delivery service type
service_number Delivery service value Delivery service value Delivery service value
post_centre_name
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Station information Delivery service
service_type Station information type Delivery service type
service_number Station information value Delivery service value
post_centre_name
Name 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 Subbuilding 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 alphanumeric Secondary address unit
type Extension designation type Secondary address identifier Suite name Flat / Unit type
value Extension designation value Secondary address number Suite number Flat / Unit number
Name 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 and suffix Building number Street number Number and number extension Address/ house number
secondary_number Secondary number and Secondary number extension
allotment_number Allotment number
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
department_name Department Department Department
secondary
_department_name
company_name Organization name Company name
business
company_name Business organization name
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Primary thoroughfare Street Street Street Street Street Street
prefix Street prefix Street prefix
name Primary thoroughfare name Street name Street name Street name Street name
type Primary thoroughfare type Street type Street type Street type Street type Street type
suffix Street suffix Street suffix Street suffix
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Secondary thoroughfare
prefix
name Secondary thoroughfare name
type Secondary thoroughfare type
suffix
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
full_name Rural route / General delivery Route service type / number
service_type
service_number
delivery_name
qualifier
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
region
name Constituent country State name Region Département Region
code State code Province code State code INSEE code
description
sub_region
name Geographic county County Subregion
code
description
town
name Town City Municipality Locality Suburb Town / CEDEX office Town
code
description
district
name Dependent locality Urbanization Delivery area installation Lobby Geographic town Settlement
code
description
sub_district
name Double-dependent locality PNR lobby Postal locality / Geographic town
code
description
Name United Kingdom United States Canada Australia New Zealand France Rest of the world
town
name Town / City
code
description
district
name Suburb
code
description

Metadata object

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:

Name 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
If the address appears in both sources, 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
Delivery Point Identifier that uniquely identifies an address:
  • Australia Post's Delivery Point Identifier, an eight-digit number that uniquely identifies a physical location to which Australia Post delivers mail.
  • 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.
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 Australia
United States
  • Australia: Customer barcode is a 37-digit string generated from the DPID.
  • 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.
address_classification
delivery_type Australia
United Kingdom
United States
The type of mail delivery at the address:
  • business
  • residential
  • mixed
  • P (PO Box)
address_type
code Australia
New Zealand
United States
Record type code indicating the type of address.
USA:
  • F: Firm
  • G: General Delivery
  • H: High-rise
  • P: PO Box
  • R: Rural Route / Contract
  • S: Street
description Australia
New Zealand
United States
Description of the address type code.
is_deliverable New Zealand Indicates whether the address can receive mail.
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).
  • 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.
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.
lacs_indicator United States Indicates whether selected address is present in the Locatable Address Conversion System table (LACSLink). LACSlink allows addresses that have been converted due to various USPS changes to be linked with their new addresses. This affects many of rural-style U.S. addresses that have been assigned city-style street names for 911 emergency response systems. Additionally, LACSLink covers street names that have been modified by municipalities in recognition of an individual or an event.
  • Y: Address listed in the LACS record table
  • N: Address not listed in the LACS record table
  • Blank: Address not presented to hash table.
lacs_code United States Informational codes to go along with lacs_indicator (see above)
  • A: New address could be furnished
  • 09: Cannot Match LACS Record: Highrise Default – The input record matched to a record in the master file, but the old address is a highrise default.
  • 14: New Address Would Not Convert at Run Time – The input record matched to a record in the master file. The new address could not be converted to a deliverable address
  • Blank: Address not presented to hash table.
urbanization United States Urbanization (Puerto Rico specific)
delivery_line_1 United States Primary address line that would appear on a piece of mail
delivery_line_2 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
last_line United States Last address line, containing city, state and ZIP Code information
no_stat_reason_code United States Informational codes to go along with no_stats_indicator (see above)
  • 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.
non_delivery_days_indicator 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.
non_delivery_days_value United States Seven bytes representing the delivery days included for each address on the table
no_secure_location 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.
door_not_accessible 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.
enhanced_dpv_codes 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.

The following response codes can be returned by the API:

Status Code Reason phrase Description
200 Success Request processed successfully.
204 No Content Request processed successfully, but there is no content to be returned.
400 Bad Request Request failed due to malformed syntax.
401 Unauthorized Auth-Token provided is incorrect. Sign in to the Self Service Portal to find the right token.
403 Forbidden Request is not authorized to use this service.
404 Not Found Request is not found.
406 Not Acceptable Request is not in an acceptable format.
408 Request Timeout Your request has timed out (the web server failed to respond in the specified time frame). Try submitting another request. If the issue persists, contact us.
415 Unsupported Media Type You've specified an invalid Content-Type header. Try submitting another call and make sure you specify a valid Content-Type value.
429 Too many requests Too many requests were sent. To protect all customers, your account has been temporarily throttled. Check our rate limiting for more details.
500 Internal Server Error An unexpected server error was encountered. Try submitting another request. If the issue persists, contact us.
503 Service Unavailable Service unavailable. Check service status for up-to-date information.

Australia

Request

{
  "country_iso": "aus",
  "max_suggestions": 3,
  "components": {
    "unspecified": [
      "49 Queens Road, five dock"
    ]
  },
  "datasets":["au-address"]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions": [
      {
        "global_address_key": "QVVTfjcuNzMwaE9BVVNI",
        "address": {
          "address_line_1": "U 1  49-51 Queens Rd",
          "address_line_2": "",
          "address_line_3": "",
          "locality": "FIVE DOCK",
          "region": "NSW",
          "postal_code": "2046",
          "country": "AUSTRALIA"
        }
      },
      {
        "global_address_key": "JBaEFJSUFBQUFBQUFBRElBQVAuLlpBQUFBQU",
        "address": {
          "address_line_1": "U 2  49-51 Queens Rd",
          "address_line_2": "",
          "address_line_3": "",
          "locality": "FIVE DOCK",
          "region": "NSW",
          "postal_code": "2046",
          "country": "AUSTRALIA"
        }
      },
      {
        "global_address_key": "OWphd0FBQUFBQX4yNX4z",
        "address": {
          "address_line_1": "U 3  49-51 Queens Rd",
          "address_line_2": "",
          "address_line_3": "",
          "locality": "FIVE DOCK",
          "region": "NSW",
          "postal_code": "2046",
          "country": "AUSTRALIA"
        }
      }
    ]
  }
}

Request

{
  "country_iso": "aus",
  "max_suggestions": 3,
  "components": {
    "unspecified": [
      "49 Queens Road, five dock"
    ]
  },
  "datasets":[ "au-address" ],
  "layouts":[ "your layout name" ]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions": [
      {
        "global_address_key": "QVVTfjcuNzMwaE9BVVNI",
        "addresses_formatted": [
          {
            "layout_name": "your layout name",
            "address": {
              "StreetAddress1": "U 1  49-51 Queens Rd",
              "Suburb": "FIVE DOCK",
              "City": "FIVE DOCK",
              "StateCode": "NSW",
              "PostCode": "2046",
              "CountryCode": "AU"
            }
          }
        ]
      },
      {
        "global_address_key": "JBaEFJSUFBQUFBQUFBRElBQVAuLlpBQUFBQU",
        "addresses_formatted": [
          {
            "layout_name": "your layout name",
            "address": {
              "StreetAddress1": "U 2  49-51 Queens Rd",
              "Suburb": "FIVE DOCK",
              "City": "FIVE DOCK",
              "StateCode": "NSW",
              "PostCode": "2046",
              "CountryCode": "AU"
            }
          }
        ]
      },
      {
        "global_address_key": "OWphd0FBQUFBQX4yNX4z",
        "addresses_formatted": [
          {
            "layout_name": "your layout name",
            "address": {
              "StreetAddress1": "U 3  49-51 Queens Rd",
              "Suburb": "FIVE DOCK",
              "City": "FIVE DOCK",
              "StateCode": "NSW",
              "PostCode": "2046",
              "CountryCode": "AU"
            }
          }
        ]
      }
    ]
  }
}

United Kingdom

Request

{
  "country_iso": "gbr",
  "max_suggestions": 3,
  "components": {
    "unspecified": [
      "160, SE1 8EZ"
    ]
  },
  "datasets":[ "gb-address" ]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions": [
      {
        "global_address_key": "R0JSfjcuNzMwcE9HQlJFZ0xtQndBQUFBQUJBd0VBQUFBQm5a",
        "address": {
          "address_line_1": "Axon Communications",
          "address_line_2": "160 Blackfriars Road",
          "address_line_3": "",
          "locality": "LONDON",
          "region": "",
          "postal_code": "SE1 8EZ",
          "country": "UNITED KINGDOM"
        }
      },
      {
        "global_address_key": "FJQUFBQUFBQUFBQUFELi4yUUFBQUFBLi4uLi53QUFBQUFBQU",
        "address": {
          "address_line_1": "C Q G UK Ltd",
          "address_line_2": "160 Blackfriars Road",
          "address_line_3": "",
          "locality": "LONDON",
          "region": "",
          "postal_code": "SE1 8EZ",
          "country": "UNITED KINGDOM"
        }
      },
      {
        "global_address_key": "oRldnQUFBQUFBfjEyfjM",
        "address": {
          "address_line_1": "Experian Data Quality",
          "address_line_2": "160 Blackfriars Road",
          "address_line_3": "",
          "locality": "LONDON",
          "region": "",
          "postal_code": "SE1 8EZ",
          "country": "UNITED KINGDOM"
        }
      }
    ]
  }
}

Request

{
  "country_iso": "gbr",
  "max_suggestions": 3,
  "components": {
    "unspecified": [
      "160, SE1 8EZ"
    ]
  },
  "datasets":[ "gb-address" ],
  "layouts":[ "your layout name" ]
}

Response

{
  "result": {
    "more_results_available": true,
    "confidence": "Multiple matches",
    "suggestions": [
      {
        "global_address_key": "R0JSfjcuNzMwcE9HQlJFZ0xtQndBQUFBQUJBd0VBQUFBQm5a",
        "addresses_formatted": [
          {
            "layout_name": "your layout name",
            "address": {
              "Organisation": "Axon Communications",
              "Street": "160 Blackfriars Road",
              "Town": "LONDON",
              "County": "",
              "Postcode": "SE1 8EZ"
            }
          }
        ]
      },
      {
        "global_address_key": "FJQUFBQUFBQUFBQUFELi4yUUFBQUFBLi4uLi53QUFBQUFBQU",
        "addresses_formatted": [
          {
            "layout_name": "your layout name",
            "address": {
              "Organisation": "C Q G UK Ltd",
              "Street": "160 Blackfriars Road",
              "Town": "LONDON",
              "County": "",
              "Postcode": "SE1 8EZ"
            }
          }
        ]
      },
      {
        "global_address_key": "oRldnQUFBQUFBfjEyfjM",
        "addresses_formatted": [
          {
            "layout_name": "your layout name",
            "address": {
              "Organisation": "Experian Data Quality",
              "Street": "160 Blackfriars Road",
              "Town": "LONDON",
              "County": "",
              "Postcode": "SE1 8EZ"
            }
          }
        ]
      }
    ]
  }
}

United States

Request

{
  "country_iso": "usa",
  "max_suggestions": 3,
  "components": {
    "unspecified": [
      "Main St, Ste 125, Vista"
    ]
  },
  "datasets":[ "us-address" ]
}

Response

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions": [
      {
        "global_address_key": "VVNBfjcuNzMwR09VU0FEd1BtQndBQUFBQUJBd0VBQUFBQkYuNjUwQWdoR0FJVEVDQUFBQUFBQUFBQUFQLi5aQUFBQUFELi4uLi5BQUFBQUFBQUFBQUFBQUFBQUFBQVRXRnBiaUJUZEN3Z1UzUmxJREV5TlN3Z1ZtbHpkR0VBQUFBQUFBLS1-MjN-NQ",
        "address": {
          "address_line_1": "20 Main St",
          "address_line_2": "Ste 125",
          "address_line_3": "",
          "locality": "Vista",
          "region": "CA",
          "postal_code": "92083-5847",
          "country": "UNITED STATES OF AMERICA"
        }
      },
      {
        "global_address_key": "VVNBfjcuNzMwbU9VU0FEd1BtQndBQUFBQUJBd0VBQUFBQkdDbjZrWUFoTVFJQUFBQUFBQUFBTVRJMUFBRC4uMlFBQUFBQS4uLi4ud0FBQUFBQUFBQUFBQUFBQUFBQUFFMWhhVzRnVTNRc0lGTjBaU0F4TWpVc0lGWnBjM1JoQUFBQUFBQS1-MjN-NQ",
        "address": {
          "address_line_1": "221 Main St",
          "address_line_2": "Ste 125",
          "address_line_3": "",
          "locality": "Vista",
          "region": "CA",
          "postal_code": "92084-6054",
          "country": "UNITED STATES OF AMERICA"
        }
      }
    ]
  }
}

Request

{
  "country_iso": "usa",
  "max_suggestions": 3,
  "components": {
    "unspecified": [
      "Main St, Ste 125, Vista"
    ]
  },
  "datasets":[ "us-address" ],
  "layouts":[ "your layout name" ]
}

Response

{
  "result": {
    "more_results_available": false,
    "confidence": "Multiple matches",
    "suggestions": [
      {
        "global_address_key": "VVNBfjcuNzMwR09VU0FEd1Bt",
        "addresses_formatted": [
          {
            "layout_name": "your layout name",
            "address": {
              "Organisation": "",
              "Street 1": "20 Main St",
              "Street 2": "Ste 125",
              "City": "Vista",
              "State/Province": "CA",
              "ZIP/Postal Code": "92083-5847"
            }
          }
        ]
      },
      {
        "global_address_key": "GWnBjM1JoQUFBQUFBQS1-MjN-NQ",
        "addresses_formatted": [
          {
            "layout_name": "your layout name",
            "address": {
              "Organisation": "",
              "Street 1": "221 Main St",
              "Street 2": "Ste 125",
              "City": "Vista",
              "State/Province": "CA",
              "ZIP/Postal Code": "92084-6054"
            }
          }
        ]
      }
    ]
  }
}