The /format endpoint is used to retrieve a fully formatted address by the Autocomplete, Singleline, Typedown, and Lookup search types.

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.
Add-Enrichment
(Optional)
boolean Specifies if the response should contain additional enrichment attributes.

The default value of this setting is false.

Path

Name Type Description
global_address_key string Global address key of the address you want to retrieve.

Body

In the request body you can specify the layout and format you want to get the address returned in. If you do not require a custom layout, you can use the /format GET request as well.

Name Type Description
layouts
(Optional)
collection Collection of layout names.

The default value of this setting is default which will return a predefined 7 line layout.
layout_format
(Optional)
string The format of the customized address layout. The available values are:
  • default: Address line label and content is presented as key value pairs.
  • address_lines: Address format to ease migration from other address validation services. The separate address lines follow the same structure as in Address Validate SOAP and Pro Web.
The default value of this setting is default.
attributes
(Optional)
collection Specifies the required attributes. There are specific attributes for each dataset - they can be found in the attribute Request Body parameter for the different datasets:
Global Location Insights (geocodes)
Premium Location Insights (premium_location_insight)
What3words (what3words)
Regional Geocodes for Australia (aus_regional_geocodes)
Regional Geocodes for New Zealand (nzl_regional_geocodes)
Regional Geocodes for United Kingdom - Essential (uk_location_essential)
Regional Geocodes for United Kingdom - Complete (uk_location_complete)
Regional Geocodes for United States (usa_regional_geocodes)
Health (gbr_health)
Government (gbr_government)
Australia - ConsumerView Household (AUS_CV_Household)
New Zealand - ConsumerView Household (nzl_cv_household)

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
global_address_key string The ID of the address matched as part of an address validation.
confidence string The confidence level of the validation 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.
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.

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

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 MPAN trading status
trading_status_efd MPAN trading status effective from date
profile_class Profile Class
profile_class_efd Profile Class effective from date
meter_timeswitch_class Meter Time-switch Class
meter_timeswitch_class_efd Meter Time-switch Class effective from date
line_loss_factor Line Loss Factor Class
line_loss_factor_efd Line Loss Factor Class effective from date
standard_settlement_configuration Standard Settlement Configuration
standard_settlement_configuration_efd Standard Settlement Configuration effective from date
energisation_status Energisation status
energisation_status_efd Energisation status effective from date
gsp_group_id Grid Supply Point Group Id
gsp_group_efd Grid Supply Point Group effective from date
data_aggregator_mpid Data Aggregator MPID
data_aggregator_efd Data Aggregator appointment effective from date
data_collector_mpid Data Collector MPID
data_collector_efd Data Collector appointment effective from date
supplier_mpid Supplier MPID
supplier_efd Effective from date of the current supplier
meter_operator_mpid Meter Operator MPID
meter_operator_efd Meter Operator appointment effective from date
measurement_class Measurement Class
measurement_class_efd Measurement Class effective from date
green_deal_in_effect An indicator 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 Data Communications Company Service Flag
dcc_service_flag_efd Data Communications Company Service Flag effective from date.
ihd_status In Home Display Install status.
ihd_status_efd In Home Display Install status effective from date.
smets_version Smart Metering Equipment Technical Specification version.
distributor_mpid Distributor MPID.
metered_indicator Metered Indicator.
metered_indicator_efd Metered Indicator effective from date.
metered_indicator_etd Metered Indicator effective to date
consumer_type Consumer Type.
relationship_status_indicator Relationship Status Indicator.
rmp_state RMP State
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 Current supply start date as supplier via CSS messages
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 Installing Supplier MPID
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.
rel_address_language The language of the address (ISO 639-2 Code).
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.
rel_address_classification Classification code of the property as per the AddressBase Premium classification scheme.
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.
rel_address_language The language of the address (ISO 639-2 Code).
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.
rel_address_classification Classification code of the property as per the AddressBase Premium classification scheme.
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
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 Département Region
code State code Province 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

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

Enrichment

The Enrichment object contains enriched data for the given specified attributes in the request body.

The available enrichment elements can be found in the response body for each dataset:

Global Location Insights (geocodes)

Premium Location Insights (premium_location_insight)

What3words (what3words)

Regional Geocodes for Australia (aus_regional_geocodes)

Regional Geocodes for New Zealand (nzl_regional_geocodes)

Regional Geocodes for United Kingdom - Essential (uk_location_essential)

Regional Geocodes for United Kingdom - Complete (uk_location_complete)

Regional Geocodes for United States (usa_regional_geocodes)

Health (gbr_health)

Government (gbr_government)

Australia - ConsumerView Household (AUS_CV_Household)

New Zealand - ConsumerView Household (nzl_cv_household)

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

GET /address/format/v1/UdSdlkyc0FBQUFBQUEtLX4yNX43 HTTP/1.1
Add-Metadata: true
Add-Components: true

Response

{
  "result": {
    "global_address_key": "UdSdlkyc0FBQUFBQUEtLX4yNX43",
    "confidence": "Verified match",
    "address": {
      "address_line_1": "U 55  49-51 Queens Rd",
      "address_line_2": "",
      "address_line_3": "",
      "locality": "FIVE DOCK",
      "region": "NSW",
      "postal_code": "2046",
      "country": "AUSTRALIA"
    },
    "components": {
      "language": "en-GB",
      "country_name": "AUSTRALIA",
      "country_iso_3": "AUS",
      "country_iso_2": "AU-NSW",
      "postal_code": {
        "full_name": "2046",
        "primary": "2046"
      },
      "sub_building": {
        "door": {
          "full_name": "U 55",
          "type": "U",
          "value": "55"
        }
      },
      "building": {
        "building_number": "49-51"
      },
      "street": {
        "full_name": "Queens Rd",
        "name": "Queens",
        "type": "Rd"
      },
      "locality": {
        "town": {
          "name": "FIVE DOCK"
        }
      }
    }
  },
  "metadata": {
    "address_info": {
      "identifier": {
        "hin": "1001307350"
      }
    },
    "barcode": {
      "delivery_point_barcode": "1301012030001212203021330300311323213",
      "sort_plan_number": "006"
    },
    "address_classification": {
      "delivery_type": "residential"
    }
  }
}

Request

POST /address/format/v1/UdSdlkyc0FBQUFBQUEtLX4yNX43 HTTP/1.1
Add-Metadata: false
Add-Components: false

{
  "layouts": [ "your layout name" ],
  "layout_format": "default"                // ("default" or "address_lines")
}

Response

{
  "result": {
    "global_address_key": "UdSdlkyc0FBQUFBQUEtLX4yNX43",
    "confidence": "Verified match",
    "addresses_formatted": [
      {
        "layout_name": "your layout name",
        "address": {
          "StreetAddress1": "U 55  49-51 Queens Rd",
          "StreetAddress2": "",
          "Suburb": "FIVE DOCK",
          "City": "FIVE DOCK",
          "StateCode": "NSW",
          "PostCode": "2046",
          "CountryCode": "AU"
        }
      }
    ]
  }
}

Request

POST /address/format/v1/UdSdlkyc0FBQUFBQUEtLX4yNX43 HTTP/1.1
Add-Metadata: false
Add-Components: false

{
  "layouts": [ "your layout name" ],
  "layout_format": "address_lines"              // ("default" or "address_lines")
}

Response

{
  "result": {
    "global_address_key": "UdSdlkyc0FBQUFBQUEtLX4yNX43",
    "confidence": "Verified match",
    "addresses_formatted": [
      {
        "layout_name": "your layout name",
        "address_lines": [
          {
            "label": "StreetAddress1",
            "line": "U 55  49-51 Queens Rd",
            "line_content": "address"
          },
          {
            "label": "StreetAddress2",
            "line": "",
            "line_content": "address"
          },
          {
            "label": "Suburb",
            "line": "FIVE DOCK",
            "line_content": "address"
          },
          {
            "label": "City",
            "line": "FIVE DOCK",
            "line_content": "address"
          },
          {
            "label": "StateCode",
            "line": "NSW",
            "line_content": "address"
          },
          {
            "label": "PostCode",
            "line": "2046",
            "line_content": "address"
          },
          {
            "label": "CountryCode",
            "line": "AU",
            "line_content": "address"
          }
        ]
      }
    ]
  }
}

Request

POST /address/format/v1/aWQ9TGV2ZWwgNiAgNTQ5IFN0IEtpbGRhIFJvYWQsIE1FTEJPVVJORSAgVklDIDMwMDQsIEF1c3RyYWxpYX5hbHRfa2V5PTYyMTQ3NzEyfmRhdGFzZXQ9QVVTX1BBRn5mb3JtYXRfa2V5PUFVUyRhdS1hZGRyZXNzJDcuNzMwMU9BVVNIQXZtQndBQUFBQUlBZ0VBQUFBQlBlTlNFQWdoQUFJQUFBQUFBQUFBTmdBQS4uOWRBQUFBQVAuLi4uOEFBQUFBQUFBQUFBQUFBQUFBQUFCTUlEWWdJRFUwT1NCVGRDQkxhV3hrWVNCU1pBQUFBQUFBJCQk HTTP/1.1
Add-Metadata: true
Add-Components: true
Add-Enrichment: true

Response

{
  "result": {
    "global_address_key": "aWQ9TGV2ZWwgNiAgNTQ5IFN0IEtpbGRhIFJvYWQsIE1FTEJPVVJORSAgVklDIDMwMDQsIEF1c3RyYWxpYX5hbHRfa2V5PTYyMTQ3NzEyfmRhdGFzZXQ9QVVTX1BBRn5mb3JtYXRfa2V5PUFVUyRhdS1hZGRyZXNzJDcuNzMwMU9BVVNIQXZtQndBQUFBQUlBZ0VBQUFBQlBlTlNFQWdoQUFJQUFBQUFBQUFBTmdBQS4uOWRBQUFBQVAuLi4uOEFBQUFBQUFBQUFBQUFBQUFBQUFCTUlEWWdJRFUwT1NCVGRDQkxhV3hrWVNCU1pBQUFBQUFBJCQk",
    "confidence": "Verified match",
    "address": {
      "address_line_1": "L 6  549 St Kilda Rd",
      "address_line_2": "",
      "address_line_3": "",
      "locality": "MELBOURNE",
      "region": "VIC",
      "postal_code": "3004",
      "country": "AUSTRALIA"
    },
    "components": {
      "country_name": "AUSTRALIA",
      "country_iso_3": "AUS",
      "country_iso_2": "AU",
      "postal_code": {
        "full_name": "3004",
        "primary": "3004"
      },
      "sub_building": {
        "floor": {
          "full_name": "L 6",
          "type": "L",
          "value": "6"
        }
      },
      "building": {
        "building_number": "549"
      },
      "street": {
        "full_name": "St Kilda Rd",
        "name": "St Kilda",
        "type": "Rd"
      },
      "locality": {
        "town": {
          "name": "MELBOURNE"
        }
      }
    }
  },
  "metadata": {
    "address_info": {
      "identifier": {
        "dpid": "62147712",
        "hin": "203060068"
      }
    },
    "barcode": {
      "delivery_point_barcode": "1301012002011121210102312002130231113",
      "sort_plan_number": "022"
    },
    "address_classification": {
      "delivery_type": "Business"
    }
  },
  "enrichment": {
    "transaction_id": "23918140-4df9-4862-aaca-db81dd757c52",
    "result": {
      "geocodes": {
        "latitude": -37.84659,
        "longitude": 144.98028,
        "match_level": "building"
      }
    },
    "metadata": {
      "code": "S200",
      "message": "Success",
      "detail": "All requested attribute(s) retrieved.",
      "datasets": {
        "geocodes": {
          "latitude": {
            "code": "S200",
            "message": "Match",
            "value": "-37.84659"
          },
          "longitude": {
            "code": "S200",
            "message": "Match",
            "value": "144.98028"
          },
          "match_level": {
            "code": "S200",
            "message": "Match",
            "value": "building"
          }
        }
      }
    }
  }
}

United Kingdom

Request

GET /address/format/v1/R1g2fjcuNzMwQU9HWDZDZ3ps HTTP/1.1
Add-Metadata: true
Add-Components: true

Response

{
  "result": {
    "global_address_key": "R1g2fjcuNzMwQU9HWDZDZ3ps",
    "confidence": "Verified match",
    "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"
    },
    "components": {
      "country_name": "UNITED KINGDOM",
      "country_iso_3": "GBR",
      "country_iso_2": "GB",
      "postal_code": {
        "full_name": "SE1 8EZ",
        "primary": "SE1 8EZ"
      },
      "building": {
        "building_number": "160"
      },
      "street": {
        "full_name": "Blackfriars Road",
        "name": "Blackfriars",
        "type": "Road"
      },
      "locality": {
        "town": {
          "name": "LONDON"
        }
      }
    }
  },
  "metadata": {
    "address_info": {
      "identifier": {
        "udprn": "55244256",
        "paf_address_key": "3796984103990845S"
      }
    },
    "barcode": {
      "delivery_point_barcode": "(SE18EZ1P7)"
    }
  }
}

Request

POST /address/format/v1/R1g2fjcuNzMwQU9HWDZDZ3ps HTTP/1.1
Add-Metadata: false
Add-Components: false

{
  "layouts": [ "your layout name" ],
  "layout_format": "default"                // ("default" or "address_lines")
}

Response

{
  "result": {
    "global_address_key": "R1g2fjcuNzMwQU9HWDZDZ3ps",
    "confidence": "Verified match",
    "addresses_formatted": [
      {
        "layout_name": "your layout name",
        "address": {
          "LINE_1": "Experian Data Quality",
          "LINE_2": "160 Blackfriars Road",
          "Town": "LONDON",
          "County": "",
          "Postcode": "SE1 8EZ"
        }
      }
    ]
  }
}

Request

POST /address/format/v1/R1g2fjcuNzMwQU9HWDZDZ3ps HTTP/1.1
Add-Metadata: false
Add-Components: false

{
  "layouts": [ "your layout name" ],
  "layout_format": "address_lines"              // ("default" or "address_lines")
}

Response

{
  "result": {
    "global_address_key": "R1g2fjcuNzMwQU9HWDZDZ3ps",
    "confidence": "Verified match",
    "addresses_formatted": [
      {
        "layout_name": "TestGBR Staging",
        "address_lines": [
          {
            "label": "",
            "line": "Experian Data Quality",
            "line_content": "none"
          },
          {
            "label": "",
            "line": "160 Blackfriars Road",
            "line_content": "none"
          },
          {
            "label": "Town",
            "line": "LONDON",
            "line_content": "address"
          },
          {
            "label": "County",
            "line": "",
            "line_content": "address"
          },
          {
            "label": "Postcode",
            "line": "SE1 8EZ",
            "line_content": "address"
          }
        ]
      }
    ]
  }
}

Request

{
  "layouts": [
    "electricityutility" 
  ]
}

Response

{
    "result": {
      "global_address_key":
"R0JFfjcuNzMwb09HQlJGQUhuQndBQUFBQUJBd0VBQUFBQnBNNHJFWWdoR0FJVENDRWdBZ0FBQUFBQUFBQXhBQUQuLjJRQUFBQUEuLi4uLndBQUFBQUFBQUFBQUFBQUFBQUFBRk4xYzNObGVDQkRiRzl6WlN4VGRYTnpaWGdnVjJGNUxFeHZibVJ2YmdBQUFBQUF-MzB-MX5lbGVjPXRydWU", 
      "confidence": "Verified match", 
      "addresses_formatted": [ 
      {
        "layout_name": "ElectricityUtility",
        "address": {
          "address_line_1": "1 Sussex Close",
          "address_line_2": "Sussex Way", 
          "address_line_3": "", 
          "locality": "London", 
          "region": "", 
          "postal_code": "N19 4LL",
          "country": "United Kingdom", 
          "electricity_meters": [
            { 
              "mpan": "1200022602050", 
              "uprn": "5300088831", 
              "address_line_1": "", 
              "address_line_2": "", 
              "address_line_3": "1", 
              "address_line_4": "SUSSEX CLOSE", 
              "address_line_5": "SUSSEX WAY", 
              "address_line_6": "", 
              "address_line_7": "", 
              "address_line_8": "LONDON", 
              "address_line_9": "", 
              "address_postal_code": "N19 4LL", 
              "trading_status": "T", 
              "trading_status_efd": "19960401", 
              "profile_class": "01", 
              "profile_class_efd": "20090616",
              "meter_timeswitch_class": "801", 
              "meter_timeswitch_class_efd": "20160105", 
              "line_loss_factor": "902", 
              "line_loss_factor_efd": "20050727", 
              "standard_settlement_configuration": "0393", 
              "standard_settlement_configuration_efd": "20090616", 
              "energisation_status": "E", 
              "energisation_status_efd": "20130110", 
              "gsp_group_id": "_C", 
              "gsp_group_efd": "19960401", 
              "data_aggregator_mpid": "SOUT", 
              "data_aggregator_efd": "20090616", 
              "data_collector_mpid": "SOUT", 
              "data_collector_efd": "20090616", 
              "supplier_mpid": "SOUT", 
              "supplier_efd": "20090616", 
              "meter_operator_mpid": "SOUT", 
              "meter_operator_efd": "20100215", 
              "measurement_class": "A", 
              "measurement_class_efd": "20090616", 
              "green_deal_in_effect": "0", 
              "smso_mpid": "LCMG", 
              "smso_efd": "20180329", 
              "dcc_service_flag": "", 
              "dcc_service_flag_efd": "", 
              "ihd_status": "I", 
              "ihd_status_efd": "20180329", 
              "smets_version": "SMETS1", 
              "distributor_mpid": "LOND", 
              "metered_indicator": "T", 
              "metered_indicator_efd": "20090616", 
              "metered_indicator_etd": "", 
              "consumer_type": "Domestic", 
              "relationship_status_indicator": "None", 
              "rmp_state": "O", 
              "rmp_efd": "19960401", 
              "domestic_consumer_indicator": "T", 
              "css_supplier_mpid": "", 
              "css_supply_start_date": "", 
              "meter_serial_number": "17K0497365", 
              "meter_install_date": "20180329", 
              "meter_type": "S1", 
              "map_mpid": "SGNS", 
              "map_mpid_efd": "20180329", 
              "installing_supplier_mpid": "SOUT", 
              "rel_address_primary_name": "1", 
              "rel_address_secondary_name": "", 
              "rel_address_street1": "SUSSEX WAY",
              "rel_address_street2": "SUSSEX CLOSE", 
              "rel_address_locality1": "", 
              "rel_address_locality2": "", 
              "rel_address_town": "LONDON", 
              "rel_address_postcode": "N19 4LL", 
              "rel_address_logical_status": "1", 
              "rel_address_language": "ENG", 
              "rel_address_organisation": "", 
              "rel_address_address_type": "DPA", 
              "rel_address_confidence_score": "92", 
              "rel_address_classification": "RD06", 
              "rel_address_latitude": "51.564362", 
              "rel_address_longitude": "-0.122257" 
            } 
          ] 
        } 
      } 
    ] 
  } 
}

Request

{
  "layouts": [
    "electricityutility" 
  ]
}

Response

{ 
    "result": {
      "global_address_key":
"R0JHfjcuNzMwb09HQlJGQUhuQndBQUFBQUJBd0VBQUFBQnBNNHJFWWdoR0FJVENDRWdBZ0FBQUFBQUFBQXhBQUQuLjJRQUFBQUEuLi4uLndBQUFBQUFBQUFBQUFBQUFBQUFBRk4xYzNObGVDQkRiRzl6WlN4VGRYTnpaWGdnVjJGNUxFeHZibVJ2YmdBQUFBQUF-MzB-MX5nYXM9dHJ1ZQ", 
      "confidence": "Verified match", 
      "addresses_formatted": [
      { 
        "layout_name": "GasUtility",
        "address": { 
          "address_line_1": "1 Sussex Close",
          "address_line_2": "Sussex Way", 
          "address_line_3": "", 
          "locality": "London", 
          "region": "", 
          "postal_code": "N19 4LL", 
          "country": "United Kingdom", 
          "gas_meters": [ 
            { 
              "mprn": "3407732400", 
              "uprn": "5300088831", 
              "rel_address_primary_name": "1", 
              "rel_address_secondary_name": "", 
              "rel_address_street1": "SUSSEX WAY", 
              "rel_address_street2": "SUSSEX CLOSE", 
              "rel_address_locality1": "", 
              "rel_address_locality2": "", 
              "rel_address_town": "LONDON", 
              "rel_address_postcode": "N19 4LL", 
              "rel_address_logical_status": "1", 
              "rel_address_language": "ENG", 
              "rel_address_organisation": "", 
              "rel_address_address_type": "DPA", 
              "rel_address_confidence_score": "100", 
              "rel_address_classification": "RD06", 
              "rel_address_latitude": "51.564362", 
              "rel_address_longitude": "-0.122257", 
              "meter_serial": "G4K00034171808", 
              "offtake_quantity_annual": "2723", 
              "meter_point_status": "LI", 
              "installer_id": "STH", 
              "network_name": "Cadent Gas Limited", 
              "supplier_name": "OVO Gas Ltd", 
              "last_meter_read_date": "20230312", 
              "last_meter_read_type": "E", 
              "last_meter_read_value": "01144" 
            } 
          ] 
        } 
      } 
    ] 
  } 
}

Request

POST /address/format/v1/aWQ9RmxhdCAxLCAyMSBBYmVyZGVlbiBXYWxrLCBTY2FyYm9yb3VnaCwgWU8xMSAxQkEsIFVuaXRlZCBLaW5nZG9tfmFsdF9rZXk9NTQ0Nzc3OTh-ZGF0YXNldD1HQlJfUEFGfmZvcm1hdF9rZXk9R0JSJGdiLWFkZHJlc3MkNmFmZWFhMWMtNTZkYS00YzA4LThmZTQtYTNkOTlhYWI5MTI0JDIxJCQ HTTP/1.1
Add-Metadata: true
Add-Components: true
Add-Enrichment: true

Response

{
  "result": {
    "global_address_key": "aWQ9RmxhdCAxLCAyMSBBYmVyZGVlbiBXYWxrLCBTY2FyYm9yb3VnaCwgWU8xMSAxQkEsIFVuaXRlZCBLaW5nZG9tfmFsdF9rZXk9NTQ0Nzc3OTh-ZGF0YXNldD1HQlJfUEFGfmZvcm1hdF9rZXk9R0JSJGdiLWFkZHJlc3MkNmFmZWFhMWMtNTZkYS00YzA4LThmZTQtYTNkOTlhYWI5MTI0JDIxJCQ",
    "confidence": "Verified match",
    "address": {
      "address_line_1": "Flat 1",
      "address_line_2": "21 Aberdeen Walk",
      "address_line_3": "",
      "locality": "SCARBOROUGH",
      "region": "",
      "postal_code": "YO11 1BA",
      "country": "UNITED KINGDOM"
    },
    "components": {
      "country_name": "UNITED KINGDOM",
      "country_iso_3": "GBR",
      "country_iso_2": "GB",
      "postal_code": {
        "full_name": "YO11 1BA",
        "primary": "YO11 1BA"
      },
      "sub_building": {
        "door": {
          "full_name": "Flat 1"
        }
      },
      "building": {
        "building_number": "21"
      },
      "street": {
        "full_name": "Aberdeen Walk",
        "name": "Aberdeen",
        "type": "Walk"
      },
      "locality": {
        "region": {
          "name": "Scotland",
          "code": "SCT",
          "description": "Constituent country"
        },
        "sub_region": {
          "name": "Fife",
          "description": "Geographic county"
        },
        "town": {
          "name": "Scarborough"
        }
      },
      "additional_elements": {
        "locality": {
          "sub_region": {
            "administrative_county": "North Yorkshire",
            "former_postal_county": "North Yorkshire",
            "traditional_county": "Yorkshire"
          }
        }
      }
    }
  },
  "metadata": {
    "address_info": {
      "identifier": {
        "udprn": "54477798",
        "paf_address_key": "3890873300000000S"
      }
    },
    "address_classification": {
      "delivery_type": "residential"
    }
  },
  "enrichment": {
    "transaction_id": "70ac71c8-bad1-4d7e-9e21-f1405d0647a4",
    "result": {
      "geocodes": {
        "latitude": 54.2828,
        "longitude": -0.40269,
        "match_level": "building"
      }
    },
    "metadata": {
      "code": "S200",
      "message": "Success",
      "detail": "All requested attribute(s) retrieved.",
      "datasets": {
        "geocodes": {
          "latitude": {
            "code": "S200",
            "message": "Match",
            "value": "54.2828"
          },
          "longitude": {
            "code": "S200",
            "message": "Match",
            "value": "-0.40269"
          },
          "match_level": {
            "code": "S200",
            "message": "Match",
            "value": "building"
          }
        }
      }
    }
  }
}

United States

Request

GET /address/format/v1/eE5ESXpBQUFBQUFBLX4yNn43 HTTP/1.1
Add-Metadata: true
Add-Components: true

Response

{
  "result": {
    "confidence": "Verified match",
    "address": {
      "address_line_1": "77 Massachusetts Ave",
      "address_line_2": "",
      "address_line_3": "",
      "locality": "Cambridge",
      "region": "MA",
      "postal_code": "02139-4307",
      "country": "UNITED STATES OF AMERICA"
    },
    "components": {
      "country_name": "UNITED STATES OF AMERICA",
      "country_iso_3": "USA",
      "country_iso_2": "US",
      "postal_code": {
        "full_name": "11423-1826",
        "primary": "11423",
        "secondary": "1826"
      },
      "building": {
        "building_number": "8800"
      },
      "street": {
        "full_name": "187th St",
        "name": "187th",
        "type": "St"
      },
      "locality": {
        "region": {
          "code": "NY"
        },
        "sub_region": {
          "name": "Queens"
        },
        "town": {
          "name": "Hollis"
        }
      }
    }
  },
  "metadata": {
    "barcode": {
      "delivery_point_barcode": "11423182600",
      "check_digit": "2"
    },
    "route_classification": {
      "carrier_route": "C052"
    },
    "address_classification": {
      "address_type": {
        "code": "S",
        "description": "Street"
      },
      "delivery_type": "Residential"
    }
  }
}

Request

POST /address/format/v1/eE5ESXpBQUFBQUFBLX4yNn43 HTTP/1.1
Add-Metadata: false
Add-Components: false

{
  "layouts": [ "your layout name" ],
  "layout_format": "default"                // ("default" or "address_lines")
}

Response

{
  "result": {
    "global_address_key": "eE5ESXpBQUFBQUFBLX4yNn43",
    "confidence": "Verified match",
    "addresses_formatted": [
      {
        "layout_name": "your layout name",
        "address": {
          "Organisation": "",
          "Street 1": "8801 187th St",
          "Street 2": "",
          "Street 3": "",
          "City": "Hollis",
          "State/Province": "NY",
          "ZIP/Postal Code": "11423",
          "Country/Region": "UNITED STATES OF AMERICA"
        }
      }
    ]
  }
}

Request

POST /address/format/v1/eE5ESXpBQUFBQUFBLX4yNn43 HTTP/1.1
Add-Metadata: false
Add-Components: false

{
  "layouts": [ "your layout name" ],
  "layout_format": "address_lines"              // ("default" or "address_lines")
}

Response

{
  "result": {
    "global_address_key": "eE5ESXpBQUFBQUFBLX4yNn43-MzB-Nw",
    "confidence": "Verified match",
    "addresses_formatted": [
      {
        "layout_name": "your layout name",
        "address_lines": [
          {
            "label": "Organisation",
            "line": "",
            "line_content": "address"
          },
          {
            "label": "Street 1",
            "line": "8800 187th St",
            "line_content": "address"
          },
          {
            "label": "Street 2",
            "line": "",
            "line_content": "none"
          },
          {
            "label": "Street 3",
            "line": "",
            "line_content": "none"
          },
          {
            "label": "City",
            "line": "Hollis",
            "line_content": "address"
          },
          {
            "label": "State/Province",
            "line": "NY",
            "line_content": "address"
          },
          {
            "label": "ZIP/Postal Code",
            "line": "11423",
            "line_content": "address"
          },
          {
            "label": "Country/Region",
            "line": "UNITED STATES OF AMERICA",
            "line_content": "address"
          }
        ]
      }
    ]
  }
}

Request

POST /address/format/v1/aWQ9NzcgTWFzc2FjaHVzZXR0cyBBdmUsIENhbWJyaWRnZSBNQSAwMjEzOSwgVW5pdGVkIFN0YXRlcyBPZiBBbWVyaWNhfmFsdF9rZXk9fDc3IE1hc3NhY2h1c2V0dHMgQXZlfHxDYW1icmlkZ2UsTUEsMDIxMzktNDMwN35kYXRhc2V0PVVTQV9QQUZ-Zm9ybWF0X2tleT1VU0EkdXMtYWRkcmVzcyRkZTZhMDQ2Mi1iYTE0LTQxYTMtOWQ2Ny01YjBhZjRmNGZmZmUkNzckJA HTTP/1.1
Add-Metadata: true
Add-Components: true
Add-Enrichment: true

Response

{
  "result": {
    "global_address_key": "aWQ9NzcgTWFzc2FjaHVzZXR0cyBBdmUsIENhbWJyaWRnZSBNQSAwMjEzOSwgVW5pdGVkIFN0YXRlcyBPZiBBbWVyaWNhfmFsdF9rZXk9fDc3IE1hc3NhY2h1c2V0dHMgQXZlfHxDYW1icmlkZ2UsTUEsMDIxMzktNDMwN35kYXRhc2V0PVVTQV9QQUZ-Zm9ybWF0X2tleT1VU0EkdXMtYWRkcmVzcyRkZTZhMDQ2Mi1iYTE0LTQxYTMtOWQ2Ny01YjBhZjRmNGZmZmUkNzckJA",
    "confidence": "Verified match",
    "address": {
      "address_line_1": "77 Massachusetts Ave",
      "address_line_2": "",
      "address_line_3": "",
      "locality": "Cambridge",
      "region": "MA",
      "postal_code": "02139-4301",
      "country": "UNITED STATES OF AMERICA"
    },
    "components": {
      "country_name": "UNITED STATES OF AMERICA",
      "country_iso_3": "USA",
      "country_iso_2": "US",
      "postal_code": {
        "full_name": "02139-4301",
        "primary": "02139",
        "secondary": "4301"
      },
      "building": {
        "building_number": "77"
      },
      "street": {
        "full_name": "Massachusetts Ave",
        "name": "Massachusetts",
        "type": "Ave"
      },
      "locality": {
        "region": {
          "code": "MA"
        },
        "sub_region": {
          "name": "Middlesex"
        },
        "town": {
          "name": "Cambridge"
        }
      }
    }
  },
  "metadata": {
    "barcode": {
      "delivery_point_barcode": "02139430177",
      "check_digit": "3"
    },
    "route_classification": {
      "carrier_route": "C077",
      "elot": "0184A"
    },
    "address_classification": {
      "address_type": {
        "code": "S",
        "description": "Street"
      },
      "delivery_type": "Business",
      "is_deliverable": "Y"
    }
  },
  "enrichment": {
    "transaction_id": "6d2963bd-f53f-4674-a908-5463cd4ecacc",
    "result": {
      "geocodes": {
        "latitude": 42.36,
        "longitude": -71.09221,
        "match_level": "building"
      }
    },
    "metadata": {
      "code": "S200",
      "message": "Success",
      "detail": "All requested attribute(s) retrieved.",
      "datasets": {
        "geocodes": {
          "latitude": {
            "code": "S200",
            "message": "Match",
            "value": "42.36"
          },
          "longitude": {
            "code": "S200",
            "message": "Match",
            "value": "-71.09221"
          },
          "match_level": {
            "code": "S200",
            "message": "Match",
            "value": "building"
          }
        }
      }
    }
  }
}