Loqate, a GBG solution
Loqate

Developers  |  APIs  |  Data Cleanse  |  International Batch Cleanse

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.

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

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.

Name Description
Key
Required
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
Required
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.
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.
  • Certify (boolean) - Use certified data set. AMAS (AU), CASS (US) or SERP (CA).
  • 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.

Back to top

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:

Back to top

Example Verify and Geocode Request

POST https://api.addressy.com/Cleansing/International/Batch/v1.00/json4.ws
Content-Type: application/json

{
    "Key": “AA11-AA11-AA11-AA11",
    "Geocode":true,
    "Addresses": [  
       {  
          "Address":"",
          "Address1":"Sageweg 27",
          "Address2":"Neuenburg",
          "Address3":"",
          "Address4":"",
          "Address5":"",
          "Address6":"",
          "Address7":"",
          "Address8":"",
          "Country":"DEU",
          "SuperAdministrativeArea":"",
          "AdministrativeArea":"",
          "SubAdministrativeArea":"",
          "Locality":"",
          "DependentLocality":"",
          "DoubleDependentLocality":"",
          "Thoroughfare":"",
          "DependentThoroughfare":"",
          "Building":"",
          "Premise":"",
          "SubBuilding":"",
          "PostalCode":"79395",
          "Organization":"",
          "PostBox":""
       },
       {  
          "Address":"",
          "Address1":"Schubartstr. 111",
          "Address2":"Bietigheim-Bissingen",
          "Address3":"74321",
          "Address4":"",
          "Address5":"",
          "Address6":"",
          "Address7":"",
          "Address8":"",
          "Country":"DEU",
          "SuperAdministrativeArea":"",
          "AdministrativeArea":"",
          "SubAdministrativeArea":"",
          "Locality":"",
          "DependentLocality":"",
          "DoubleDependentLocality":"",
          "Thoroughfare":"",
          "DependentThoroughfare":"",
          "Building":"",
          "Premise":"",
          "SubBuilding":"",
          "PostalCode":"",
          "Organization":"",
          "PostBox":""
       }
    ]
}

    

 

Example Response

[
    {
        "Input": {
            "Address": "",
            "Address1": "Sageweg 27",
            "Address2": "Neuenburg",
            "Address3": "",
            "Address4": "",
            "Address5": "",
            "Address6": "",
            "Address7": "",
            "Address8": "",
            "Country": "DEU",
            "SuperAdministrativeArea": "",
            "AdministrativeArea": "",
            "SubAdministrativeArea": "",
            "Locality": "",
            "DependentLocality": "",
            "DoubleDependentLocality": "",
            "Thoroughfare": "",
            "DependentThoroughfare": "",
            "Building": "",
            "Premise": "",
            "SubBuilding": "",
            "PostalCode": "79395",
            "Organization": "",
            "PostBox": ""
        },
        "Matches": [
            {
                "AQI": "A",
                "AVC": "V44-I44-P6-100",
                "Address": "Sägeweg 27,79395 Neuenburg Am Rhein",
                "Address1": "Sägeweg 27",
                "Address2": "79395 Neuenburg Am Rhein",
                "AdministrativeArea": "Baden-Württemberg",
                "CountryName": "Germany",
                "DeliveryAddress": "Sägeweg 27",
                "DeliveryAddress1": "Sägeweg 27",
                "GeoAccuracy": "P4",
                "GeoDistance": "0.0",
                "HyphenClass": "C",
                "ISO3166-2": "DE",
                "Country": "DE",
                "ISO3166-3": "DEU",
                "ISO3166-N": "276",
                "Latitude": "47.807820",
                "Locality": "Neuenburg Am Rhein",
                "Longitude": "7.569160",
                "MatchRuleLabel": "Rlfnp",
                "PostalCode": "79395",
                "PostalCodePrimary": "79395",
                "Premise": "27",
                "PremiseNumber": "27",
                "SubAdministrativeArea": "Reg.-Bez. Freiburg",
                "Thoroughfare": "Sägeweg"
            }
        ]
    },
    {
        "Input": {
            "Address": "",
            "Address1": "Schubartstr. 111",
            "Address2": "Bietigheim-Bissingen",
            "Address3": "74321",
            "Address4": "",
            "Address5": "",
            "Address6": "",
            "Address7": "",
            "Address8": "",
            "Country": "DEU",
            "SuperAdministrativeArea": "",
            "AdministrativeArea": "",
            "SubAdministrativeArea": "",
            "Locality": "",
            "DependentLocality": "",
            "DoubleDependentLocality": "",
            "Thoroughfare": "",
            "DependentThoroughfare": "",
            "Building": "",
            "Premise": "",
            "SubBuilding": "",
            "PostalCode": "",
            "Organization": "",
            "PostBox": ""
        },
        "Matches": [
            {
                "AQI": "A",
                "AVC": "V44-I44-P6-100",
                "Address": "Schubartstr. 111,74321 Bietigheim-Bissingen",
                "Address1": "Schubartstr. 111",
                "Address2": "74321 Bietigheim-Bissingen",
                "AdministrativeArea": "Baden-Württemberg",
                "CountryName": "Germany",
                "DeliveryAddress": "Schubartstr. 111",
                "DeliveryAddress1": "Schubartstr. 111",
                "DependentLocality": "Bissingen",
                "GeoAccuracy": "P4",
                "GeoDistance": "0.0",
                "HyphenClass": "C",
                "ISO3166-2": "DE",
                "Country": "DE",
                "ISO3166-3": "DEU",
                "ISO3166-N": "276",
                "Latitude": "48.942220",
                "Locality": "Bietigheim-Bissingen",
                "Longitude": "9.106600",
                "MatchRuleLabel": "Rlfnp",
                "PostalCode": "74321",
                "PostalCodePrimary": "74321",
                "Premise": "111",
                "PremiseNumber": "111",
                "SubAdministrativeArea": "Reg.-Bez. Stuttgart",
                "Thoroughfare": "Schubartstr."
            }
        ]
    }
]
    

Back to top

Example ReverseGeocode Request

POST https://api.addressy.com/Cleansing/International/Batch/v1.00/json4.ws
Content-Type: application/json

{
    "Key": "AA11-AA11-AA11-AA11",
    "Options": {
        "Process": "ReverseGeocode",
        "ServerOptions": {
            "MaxResults": 10
        }
    },
    "Addresses": [
        {
            "Latitude": "37.491400",
            "Longitude": "-122.228800",
            "Country": "US"
        },
        {
            "Latitude": "43.713384",
            "Longitude": "-79.398706",
            "Country": "CA"
        }
    ]
}
    

Back to top

Example Multi-Country Certify Request

POST https://api.addressy.com/Cleansing/International/Batch/v1.00/json4.ws
Content-Type: application/json

{
    "Key": "AA11-AA11-AA11-AA11",
    "Options": {
        "Certify": true
    },
    "Addresses": [
        {
            "Address1": "805 Veterans Street",
            "Address2": "#305",
            "Locality": "redwoodcity",
            "AdministrativeArea": "california",
            "PostalCode": "",
            "Country": "USA"
        },
        {
            "Address1": "8 Charlotte St #8, Toronto, Ontario M5V 0K4",
            "Country": "Canada"
        },
        {
            "Address1": "6/19 Brittain Crescent Hillsdale NSW 2036 AUS",
            "Country": "Australia"
        }
    ]
}

    

Back to top

Example Enhance (for a US address) request

POST https://api.addressy.com/Cleansing/International/Batch/v1.00/json4.ws
Content-Type: application/json

{
    "Key": "AA11-AA11-AA11-AA11",
    "Options": {
        "Enhance": true
    },
    "Addresses": [
        {
            "Address1": "805 Veterans Street RedwoodCity california USA ",
            "Address2": "",
            "Country": "",
            "Locality": "",
            "PostalCode": ""
        }
    ]
}


    

Back to top

Example Verify, Geocode, and Transliteration Request (output Japanese address in Latin)

POST https://api.addressy.com/Cleansing/International/Batch/v1.00/json4.ws
Content-Type: application/json

{
    "Key": "AA11-AA11-AA11-AA11",
    "Geocode": true,
    "Options": {
        "Process": "Verify",
        "ServerOptions": {
            "OutputScript": "Latn"
        }
    },
    "Addresses": [
        {
            "Address": "つきみ野 618    大和市 神奈川県 242-0002 JPN"
        }
    ]
}

    

Back to top

Sign up for a free trial or book a demo Get started