International Batch Cleanse

Cleanses a batch of international addresses (and can also be used for single addresses). To enable the best customer experience, the recommendation is to send batches of less than 100 records which are homogenous in terms of the location. Grouping the requests into countries enables the Verify engine to manage its resources more effectively.

Request parameters
Response fields
Errors
Examples

Base URL

https://api.addressy.com/Cleansing/International/Batch/v1.00/

Note: we don't support API connections using HTTP - all calls should use HTTPS.

JSON

https://api.addressy.com/Cleansing/International/Batch/v1.00/json4.ws

Note: A REST endpoint with a JSON payload is the only call style supported.

Request parameters

Each request to the web service requires a number of parameters, all of which are listed below. All requests require a key which can be generated in your account.

* = required field

Name	Description
Key*	The key you want to use to authenticate with the service (you can request we create one for you or create one in your account section)
Geocode Boolean	Whether you want geo-coordinates to be appended to your results (if available). There is an additional cost associated with enabling this option.
Addresses*	An array of addresses that you want to verify. The country field must contain a valid ISO2 or ISO3 country code. We recommend that you use the structured fields (i.e. building/thoroughfare etc) over the address line input fields if the data you are cleansing is already structured. To enable the best customer experience, the recommendation is to send batches of less than 100 records which are homogenous in terms of the location. Grouping the requests into countries enables the Verify engine to manage its resources more effectively. The list of available input address fields are the "Primary Address Fields" listed here.
Options Object	Used to specify various options and override processes. Comprised of the following: Process (string) - Loqate Process to run. Valid Values: Verify \| ReverseGeocode Verify is the default and will be run if "Process" is not specified. Version (boolean) - Return Loqate engine version with request. You can cross-reference versions to releases. Certify (boolean) - Use certified data set. AMAS (AU), CASS (US) or SERP (CA). The country of the input address will determine which certification product is used. You can find output field definitions at AMAS Field Descriptions, CASS Field Descriptions or SERP Field Descriptions Enhance (boolean) - Use enhanced datasets. Returns enhance fields (defined here) if applicable. ServerOptions (object) - Properties are OptionName and value is OptionValue. More info can be found here. If status fields are required, you can set FieldStatus: true in the ServerOptions object to return them. FieldStatus codes are defined here.

Response Fields

Name	Description
Input	A copy of the address that you input in the request "Addresses" array.
Matches	An array of matched records including: AVC - See Address Verification Code. AQI - See Address Quality Index. Address elements - The cleansed address elements (ordered address lines and each structured address element returned for each match) - defined here. Sequence - If present on output, indicates the order of the address was in the request. If Geocode was requested, the output will include the Latitude/Longitude, GeoAccuracy and GeoDistance fields (if available) – defined here. The GeoAccuracy code is defined here. Process fields – non-address generated fields are defined here.

Name

Description

Input

A copy of the address that you input in the request "Addresses" array.

Matches

An array of matched records including:

AVC - See Address Verification Code.
AQI - See Address Quality Index.
Address elements - The cleansed address elements (ordered address lines and each structured address element returned for each match) - defined here.
Sequence - If present on output, indicates the order of the address was in the request.
If Geocode was requested, the output will include the Latitude/Longitude, GeoAccuracy and GeoDistance fields (if available) – defined here.
- The GeoAccuracy code is defined here.
Process fields – non-address generated fields are defined here.

Errors

Below are the errors which are specific to this web service. If an error occurs, an error table like the one below will be returned. To check for an error response, test for a 4 column table with columns "Number", "Description", "Cause" and "Resolution" containing a single row.

For a list of errors applicable to all APIs, have a look at the list of common errors.

Number	Description	Cause	Resolution
1000	Invalid JSON object	The JSON object in the POST body was invalid.	Try again sending a valid JSON request object in the POST body.
1001	No address supplied	No addresses supplied.	Ensure you send at least one address in the request for cleansing.
1002	Batch processing failed	Error cleansing your records.	There was a server error whilst processing your batch. Please try again shortly.
1003	Batch processing timeout	Your batch took too long to process and timed out.	Please reduce the batch size or increase the quality of the input in order to ensure your requests don't time out.
1004	Too many addresses supplied	Address input limit reached.	Please limit input length to 100 records or less.