How to process a batch file via the API

Before you start, make sure you have a Loqate account. If you don’t already have one, you will need to sign up here.

Prepare Your File For Uploading

Before you upload your file, check the following:

Make sure the file is UTF-8 encoded.
Make sure the file contains the word input in the name, for example, "address-input.txt".
The file should have a .csv or .txt extension.
The first line should contain headers describing the field for each column, for example, Address1, Address2, Country etc.
The format must be comma or tab delimited.
Line endings must be LF (Linux/Unix).

If you are unsure, you can use our base template for an idea of what the file should look like. You will still need to rename this to include "input" in the filename.

Upload the File

Use the following to upload your file.

POST https://api.addressy.com/Folders/Files/Upload/v1.00/json4.ws
form-data
File: filecontents
Filename: filename-input.txt
Key: yourlqtkey

Process the File

Once your file has been uploaded, use the following body to start the processing.

POST https://api.addressy.com/Cleansing/International/Batch/v1.00/json4.ws
Content-Type: application/json
{
"BatchFile": true,
"BatchFileName": "filenameusedinuploadrequest-input.txt",
"Key": "yourlqtkey",
"Delimiter": "tab"
}

Note: Valid values for the Delimiter parameter are "tab" or "comma". ServerOptions can also be set as outlined here.

Check the Job Status

As soon as your file is uploaded, you can check the status of the job.

POST https://api.addressy.com/Folders/Files/Status/v1.00/json4.ws
{
"Filename": "filenameusedinuploadrequest-input.txt",
"Key": "yourlqtkey"
}

Example status response

{
"AccountName": "GBG",
"Status": "uploaded || processing || complete",
"Progress": 0.0,
"Lines": 0,
"Usage": { 
  iso2: count,
}
}

Downloading The Results

You can poll the status endpoint until it returns complete, at which point the output file will be ready to download. Billing occurs once after the first download request, if applicable. All output files are simply the input filename with "input" replaced with "output". For example, "address-input.txt" becomes "address-output.txt".

POST https://api.addressy.com/Folders/Files/Download/v1.00/json4.ws
Content-Type: application/json
{
"Key": "yourlqtkey",
"Filename": "address-output.txt"
}

The response will be returned as plain-text.

Example raw response

InputID,InputOrganization,InputAddress1,InputAddress2,InputAddress3,InputAddress4,InputAddress5,InputAddress6,InputAddress7,InputAddress8,InputLocality,InputAdministrativeArea,InputPostalCode,InputCountry,AVC,AQI,Address,Address1,Address2,Address3,Address4,Address5,Address6,Address7,Address8,DeliveryAddress,DeliveryAddress1,DeliveryAddress2,DeliveryAddress3,DeliveryAddress4,DeliveryAddress5,DeliveryAddress6,DeliveryAddress7,DeliveryAddress8,CountryName,ISO3166-2,ISO3166-3,ISO3166-N,SuperAdministrativeArea,AdministrativeArea,SubAdministrativeArea,Locality,DependentLocality,DoubleDependentLocality,Thoroughfare,DependentThoroughfare,Building,Premise,SubBuilding,PostalCode,PostalCodePrimary,PostalCodeSecondary,Organization,PostBox,Unmatched
1000,,999 baker way ste 320,,,,,,,,san mateo,,94404,USA,V55-I55-P7-100,A,999 Baker Way Ste 320
San Mateo CA 94404-1566,999 Baker Way Ste 320,San Mateo CA 94404-1566,,,,,,,999 Baker Way Ste 320,999 Baker Way Ste 320,,,,,,,,United States,Us,Us,Usa,840,,CA,San Mateo,San Mateo,,,Baker Way,,,999,Ste 320,94404-1566,94404,1566,,,
1001,,1111 bayhill drive ste 290,san bruno,,,,,,,,ca,,USA,V55-I55-P3-100,A,1111 Bayhill Dr Ste 290
San Bruno CA 94066-3053,1111 Bayhill Dr Ste 290,San Bruno CA 94066-3053,,,,,,,1111 Bayhill Dr Ste 290,1111 Bayhill Dr Ste 290,,,,,,,,United States,Us,Us,Usa,840,,CA,San Mateo,San Bruno,,,Bayhill Dr,,,1111,Ste 290,94066-3053,94066,3053,,,

If you prefer to use the UI instead, take a look at this guide.