Address Cleanse
Verifies, corrects and enriches address data to the highest level of precision and confidence, globally and at scale
Validate 1 to 100 addresses per requests.
Our flexible service allows:
Up to 100 addresses per request
Each Address can be from any country.
Each Address can have its own schema. Reducing effort and improving results.
Resource URL
POST https://hosted.mastersoftgroup.com/harmony/rest/v2/address/cleanseRequest
Upto 100 addresses can be validated per request from any country with many input schemas.
This flexibility in our service enables you to call our service using your list schema to achieve optimal results.
{
"payload":
[
{
"buildingName": "string",
"country": "string",
"eid": "string",
"flatUnitNumber": "string",
"flatUnitType": "string",
"floorLevelNumber": "string",
"floorLevelType": "string",
"fullAddress": "string",
"id": "string",
"lotNumber": "string",
"postal": "string",
"postalNumber": "string",
"postalType": "string",
"postcode": "string",
"street": "string",
"street2": "string",
"streetName": "string",
"streetNumber": "string",
"streetSuffix": "string",
"streetType": "string",
"subLocality": "string",
"subdwelling": "string",
"city": "string",
"line1": "string",
"line2": "string",
"line3": "string",
"province": "string",
"sourceOfTruth": "string"
}
],
"featureOptions":
{
"additionalProp1": "string",
"additionalProp2": "string",
"additionalProp3": "string"
}
}Example payload schemas
We've designed our API with flexible payload schemas. Meaning you can match the way you have stored the data into the optimal schema for our service.
Reducing your overall integration effort whilst improving performance of the service.
We recommend choosing the below schemas for each address you need cleansed.
Please ensure the information is not duplicated in any of the address lines to achieve better validation results.
Line 1: is a representation of address fields usually house sub-dwellings, street numbers, street names, buildingName etc. This is usually determined by how you have data stored.
Line 2: is a representation of address fields usually additional information not contained in Line 1 such as suite numbers or floor information or subdwellings (not contained in Line 1). This is usually determined by how you have data stored.
Line 3: is a representation of address fields usually around city, province, suburbs/locality for example "suburb postcode region".
Note: Please ensure the information populated in city/province/postcode is not duplicated in any of the address lines to achieve better validation results.
Service Options
Address Cleanse V2 API leverages both Standard and Premium Address Cleanse services.
Standard Cleanse Service:
The validation data set for standard cleanse service is using our default datasets (AU: GNAF, NZ: NZPAF, INTL: INTL Standard. By default the API is set to Standard services meaning you do not need to specify within the API requests.
"featureOptions":
{
"cleanseEnhance":0,
"cleanseGeocode":0,
"cleanseCertify":0
}Premium Cleanse Service:
This service provides access to advanced cleanse functions.
This allows the input request to pass on specific sourceOfTruth for AU, NZ addresses and allows to enhance the international data by setting the featureOptions to 1.
To get INTL geocodes requires "cleanseGeocode":1.
Utilizing cleanse featureOptions requires access. To get access contact a member of the team.
// Enabling Premium Cleanse Service
"featureOptions":
{
"cleanseEnhance":1,
"cleanseGeocode":1,
"cleanseCertify":1
}Configurations
sourceOfTruth
string
defaults
AU: GNAF
NZ: NZPAF
INTL: INTL
Premium service only.
Defines selection of premium datasets being used to Cleanse the data.
caseType
string
TITLE, default empty
caseType for returned address components and attributes. LOW = lowercase, UP = UPPERCASE, TITLE = Title Case
exposeAttributes
Integer
("0"|"1"|"7") default 1
AU only.
Enriches the data with address related attributes depending on value. Options 0,1,7
exposeChanges
Integer
("0"|"1") default 0
AU NZ only.
Determines whether to include PDP change items in response.
cleanseEnhance
boolean
("0"|"1") default 0
Premium service only.
This option when set to 1 enhances AU NZ data with additional data attributes based on sourceOfTruth set in the input.
AU: AUPAF, AUSOTS
NZ: NZAD
For International addresses this option will determine the Enhanced data pack to be used based on the country input in the request.
cleanseCertify
boolean
("0"|"1") default 0
Premium service only.
International only.
This option when set to 1 uses the country input to determine which certification data set to be used for international address validation.
cleanseGeocode
boolean
("0"|"1") default 0
Premium service only.
International only.
This option when set to 1 returns geocode information for international addresses.
Response
See Address Field Mapping Guide for integration best practices.
Response of Basic Cleanse Service
The response body is an AddressRestResponse object:
Response of Premium Cleanse Service
The response body is an AddressRestResponse object:
Attributes for Australia and NewZealand address samples may vary based on the input sourceOfTruth chosen.
Attributes for International addresses may vary based on the cleanseXXX feature options chosen.
Exception Message
Failed to Parse:
Exception message for AU NZ "failed to parse record" looks like the following.
"Exception": "H112 : No pattern matched for this input - VRI BUILDING BLDG 403 30 FLEMINGTON ROAD, PARKVILLE VIC 3052. Check for punctuation errors, duplicate fields, incorrect input format and incorrect input data."Failed to Validate
For AU ad NZ: ChangedItems in the response will indicate the records not validated. "affectedElement": "ParsedWithoutMatchInPaf"
For International address: AVC code indicates the address match level. Records with AVC codes prefixed with "U" are unverified matches.
Last updated