Data Quality user documentation | Suggestions/Format

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

Credit usage

If you have a per-click license, each successful request will deduct one or more credits. Please contact your account manager or contact support for more information. You can also log in to Experian's Self Service Portal to review your product usage.

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

Only returned if

This object is only returned when the Add-Components header is set to True on the request.

Name
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
full_name	Postcode	Zip code	Postal code	Postal code	Postcode	Postcode	Postcode
primary		ZIP		Postal code	Postcode	Postcode
secondary		Plus4

Name
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
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
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
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
department_name		Department	Department	Department
secondary _department_name
company_name		Organization name	Company name
business
	company_name	Business organization name

Name
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
full_name	Secondary thoroughfare
prefix
name	Secondary thoroughfare name
type	Secondary thoroughfare type
suffix

Name
full_name	Rural route / General delivery	Route service type / number
service_type
service_number
delivery_name
qualifier

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

Only returned if

This object is only returned when the Add-Metadata header is set to True on the request.

The following metadata elements are currently available:

Name			Description
address_info
	sources		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		Number of households present at the address for Royal Mail's Multiple Residence and Not Yet Built addresses.
	just_built_date		Construction date of a property, if activated within the past six months.
	identifier
		udprn	Royal Mail's Unique Delivery Point Reference Number, an eight-digit code assigned to every delivery point in the Postcode Address File (PAF).
		umrrn	Royal Mail's Unique Multiple Residence Reference Number, an eight-digit code linked to UDPRNs in Royal Mail's Multiple Residence dataset.
		dpid	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	Geoscape Australia's Geocoded National Address File Persistent Identifier (G-NAF ID).
		hin	Household Identification Number (HIN), unique reference ID for each household.
		paf_address_key	Royal Mail's PAF Address Key.
route_classification
	id		New Zealand Post's unique numeric identifier for a street, for example 1324.
	carrier_route		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		Three-digit Barcode Sort Plan (BSP) number for each full address to facilitate pre-sorting of mail items.
	delivery_point_barcode		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		The type of mail delivery at the address: business residential mixed P (PO Box)
	address_type
		code	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	Description of the address type code.
	is_deliverable		Indicates whether the address can receive mail.
dpv
	cmra_indicator		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		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		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		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		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		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		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		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		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		Urbanization (Puerto Rico specific)
	delivery_line_1		Primary address line that would appear on a piece of mail
	delivery_line_2		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		Last address line, containing city, state and ZIP Code information
	no_stat_reason_code		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		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		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		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		Seven bytes representing the delivery days included for each address on the table
	no_secure_location		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		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		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"
            }
          }
        ]
      }
    ]
  }
}

Was this helpful?

Previous: Suggestions/Refine

Next: Layouts

Experian Address Validation

Address API reference

Next topic:
API specification
Previous topic:
Prerequisites