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.
https://api.addressy.com/Cleansing/International/Batch/v1.00/
Note: we don't support API connections using HTTP - all calls should use HTTPS.
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.
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:
|
| Name | Description |
|---|---|
| Input | A copy of the address that you input in the request "Addresses" array. |
| Matches | An array of matched records including:
|
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. |
Below are a selection of requests and responses to the API.
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":""
}
]
}[
{
"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."
}
]
}
]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": 2
}
},
"Addresses": [
{
"Latitude": "37.491400",
"Longitude": "-122.228800",
"Country": "US"
},
{
"Latitude": "43.713384",
"Longitude": "-79.398706",
"Country": "CA"
}
]
}
[
{
"input": {
"latitude": "37.491400",
"longitude": "-122.228800",
"country": "us"
},
"matches": [
{
"address": "805 veterans blvd,redwood city ca 94063",
"address1": "805 veterans blvd",
"address2": "redwood city ca 94063",
"administrativearea": "ca",
"countryname": "united states",
"deliveryaddress": "805 veterans blvd",
"deliveryaddress1": "805 veterans blvd",
"geodistance": "0.000000",
"iso3166-2": "us",
"country": "us",
"iso3166-3": "usa",
"iso3166-n": "840",
"latitude": "37.491400",
"locality": "redwood city",
"longitude": "-122.228800",
"postalcode": "94063",
"postalcodeprimary": "94063",
"premise": "805",
"premisenumber": "805",
"premisenumberrangefield": "805",
"subadministrativearea": "san mateo",
"thoroughfare": "veterans blvd"
},
{
"address": "409 brewster ave,redwood city ca 94063",
"address1": "409 brewster ave",
"address2": "redwood city ca 94063",
"administrativearea": "ca",
"countryname": "united states",
"deliveryaddress": "409 brewster ave",
"deliveryaddress1": "409 brewster ave",
"geodistance": "40.314589",
"iso3166-2": "us",
"country": "us",
"iso3166-3": "usa",
"iso3166-n": "840",
"latitude": "37.491750",
"locality": "redwood city",
"longitude": "-122.229490",
"postalcode": "94063",
"postalcodeprimary": "94063",
"premise": "409",
"premisenumber": "409",
"premisenumberrangefield": "409",
"subadministrativearea": "san mateo",
"thoroughfare": "brewster ave"
}
]
},
{
"input": {
"latitude": "43.713384",
"longitude": "-79.398706",
"country": "ca"
},
"matches": [
{
"address": "11 sherwood ave,toronto on m4p 2a6",
"address1": "11 sherwood ave",
"address2": "toronto on m4p 2a6",
"administrativearea": "on",
"countryname": "canada",
"deliveryaddress": "11 sherwood ave",
"deliveryaddress1": "11 sherwood ave",
"geodistance": "12.817361",
"iso3166-2": "ca",
"country": "ca",
"iso3166-3": "can",
"iso3166-n": "124",
"latitude": "43.713360",
"locality": "toronto",
"longitude": "-79.398830",
"postalcode": "m4p 2a6",
"postalcodeprimary": "m4p 2a6",
"premise": "11",
"premisenumber": "11",
"premisenumberrangefield": "11",
"subadministrativearea": "toronto",
"thoroughfare": "sherwood ave"
},
{
"address": "15 sherwood ave,toronto on m4p 2a6",
"address1": "15 sherwood ave",
"address2": "toronto on m4p 2a6",
"administrativearea": "on",
"countryname": "canada",
"deliveryaddress": "15 sherwood ave",
"deliveryaddress1": "15 sherwood ave",
"geodistance": "17.655316",
"iso3166-2": "ca",
"country": "ca",
"iso3166-3": "can",
"iso3166-n": "124",
"latitude": "43.713420",
"locality": "toronto",
"longitude": "-79.398540",
"postalcode": "m4p 2a6",
"postalcodeprimary": "m4p 2a6",
"premise": "15",
"premisenumber": "15",
"premisenumberrangefield": "15",
"subadministrativearea": "toronto",
"thoroughfare": "sherwood ave"
}
]
}
]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"
}
]
}
[
{
"input": {
"address1": "805 veterans street",
"address2": "#305",
"locality": "redwoodcity",
"administrativearea": "california",
"postalcode": "",
"country": "usa"
},
"matches": [
{
"aqi": "d",
"avc": "v55-i55-p3-083",
"address": "805 veterans blvd ste 305,redwood city ca 94063-1737",
"address1": "805 veterans blvd ste 305",
"address2": "redwood city ca 94063-1737",
"administrativearea": "ca",
"autozoneindicator": "d",
"businessindicator": " ",
"cmraindicator": "n",
"carrierroute": "c018",
"centralizedindicator": "",
"checkdigit": "2",
"congressionaldistrict": "15",
"countryname": "united states",
"curbindicator": "",
"dpvconfirmedindicator": "y",
"dpvfootnotes": "aabb",
"dpvlacsindicator": " ",
"defaultflag": " ",
"deliveryaddress": "805 veterans blvd ste 305",
"deliveryaddress1": "805 veterans blvd ste 305",
"deliverypointbarcode": "802",
"dependentlocality": "",
"dropcount": "",
"dropsiteindicator": " ",
"educationalindicator": " ",
"fipscountycode": "081",
"falsepositiveindicator": " ",
"finance": "056378",
"footnotes": "b#l#",
"iso3166-2": "us",
"country": "us",
"iso3166-3": "usa",
"iso3166-n": "840",
"lacslinkcode": "",
"lacslinkindicator": " ",
"locality": "redwood city",
"ndcbuindicator": "",
"nostatindicator": "n",
"organization": "",
"otherindicator": "",
"pmbnumber": "",
"pmbtype": "",
"postboxnumber": "",
"postboxtype": "",
"postalcode": "94063-1737",
"postalcodeprimary": "94063",
"postalcodesecondary": "1737",
"postalcodesecondaryrangehigh": "1737",
"postalcodesecondaryrangelow": "1737",
"premise": "805",
"premisenumber": "805",
"primaryaddressline": "805 veterans blvd ste 305",
"primarynumrangecode": "o",
"primarynumrangehigh": "0000000805",
"primarynumrangelow": "0000000805",
"recordtype": "h",
"residentialdelivery": "n",
"returncode": "31",
"suitelinkfootnote": "",
"seasonalindicator": " ",
"secondaryaddressline": "redwood city ca 94063-1737",
"secondarynumrangecode": "b",
"secondarynumrangehigh": "00000322",
"secondarynumrangelow": "00000228",
"subadministrativearea": "san mateo",
"subbuilding": "ste 305",
"subbuildingleadingtype": "ste",
"subbuildingnumber": "305",
"thoroughfare": "veterans blvd",
"thoroughfarename": "veterans",
"thoroughfarepostdirection": "",
"thoroughfarepredirection": "",
"thoroughfaretrailingtype": "blvd",
"throwbackindicator": "n",
"vacantindicator": "n",
"elotcode": "",
"elotnumber": ""
}
]
},
{
"input": {
"address1": "8 charlotte st #8, toronto, ontario m5v 0k4",
"country": "canada"
},
"matches": [
{
"aqi": "c",
"avc": "v55-i55-p6-091",
"addinfo": "",
"address": "8-8 charlotte st,toronto on m5v 0k4",
"address1": "8-8 charlotte st",
"address2": "toronto on m5v 0k4",
"administrativearea": "on",
"countryname": "canada",
"deliveryaddress": "8-8 charlotte st",
"deliveryaddress1": "8-8 charlotte st",
"endexpirydate": "2023-03-16",
"iso3166-2": "ca",
"country": "ca",
"iso3166-3": "can",
"iso3166-n": "124",
"locality": "toronto",
"postalcode": "m5v 0k4",
"postalcodeprimary": "m5v 0k4",
"premise": "8",
"premisenumber": "8",
"result": "valid",
"serpstatusex": "v",
"startexpirydate": "2023-02-17",
"subbuilding": "8",
"subbuildingnumber": "8",
"subbuildingtype": "-",
"thoroughfare": "charlotte st",
"thoroughfarename": "charlotte",
"thoroughfaretrailingtype": "st",
"thoroughfaretype": "st"
}
]
},
{
"input": {
"address1": "6/19 brittain crescent hillsdale nsw 2036 aus",
"country": "australia"
},
"matches": [
{
"aqi": "a",
"avc": "v55-i55-p6-100",
"address": "6,19 brittain cres,hillsdale nsw 2036",
"address1": "6",
"address2": "19 brittain cres",
"address3": "hillsdale nsw 2036",
"administrativearea": "nsw",
"barcode": "1301012202101110210212322302233112213",
"building": "",
"countryname": "australia",
"dpid": "82343725",
"deliveryaddress": "6,19 brittain cres",
"deliveryaddress1": "6",
"deliveryaddress2": "19 brittain cres",
"errorcode": "4",
"floornumber": "",
"floortype": "",
"iso3166-2": "au",
"country": "au",
"iso3166-3": "aus",
"iso3166-n": "036",
"locality": "hillsdale",
"lotnumber": "",
"postalcode": "2036",
"presortzone": "10",
"premise": "19",
"primaryaddressline": "u 6 19 brittain cres",
"primarypremise": "19",
"primarypremisesuffix": "",
"printpostzone": "10",
"secondaryaddressline": "",
"secondarypremise": "",
"secondarypremisesuffix": "",
"subbuilding": "6",
"subbuildingfloor": "",
"subbuildingleadingtype": "u",
"subbuildingnumber": "6",
"thoroughfare": "brittain cres",
"thoroughfarename": "brittain",
"thoroughfarepostdirection": "",
"thoroughfaretrailingtype": "cres"
}
]
}
]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": ""
}
]
}
[
{
"input": {
"address1": "805 veterans street redwoodcity california usa ",
"address2": "",
"country": "",
"locality": "",
"postalcode": ""
},
"matches": [
{
"aqi": "c",
"avc": "v42-i44-p3-092",
"address": "805 veterans blvd,redwood city ca 94063-1734",
"address1": "805 veterans blvd",
"address2": "redwood city ca 94063-1734",
"administrativearea": "ca",
"administrativeareaiso2": "us-ca",
"cbsametropolitanstatisticalarea": "san francisco-oakland-berkeley, ca=41860",
"censusclasscode": "c1",
"censuscode": "60102",
"censusindicator": "locality",
"countryname": "united states",
"deliveryaddress": "805 veterans blvd",
"deliveryaddress1": "805 veterans blvd",
"gnisfeatureid": "2410919",
"hyphenclass": "c",
"iso3166-2": "us",
"country": "us",
"iso3166-3": "usa",
"iso3166-n": "840",
"locality": "redwood city",
"matchrulelabel": "c2 d1 d1 d1",
"metropolitandivision": "san francisco-san mateo-redwood city, ca=41884",
"postalcode": "94063-1734",
"postalcodeprimary": "94063",
"postalcodesecondary": "1734",
"premise": "805",
"premisenumber": "805",
"subadministrativearea": "san mateo",
"thoroughfare": "veterans blvd",
"thoroughfarename": "veterans",
"thoroughfaretrailingtype": "st",
"thoroughfaretype": "st",
"timezone_dst": "-07:00",
"timezone_name": "pacific standard time",
"timezone_utc": "-08:00"
}
]
}
]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"
}
]
}
[
{
"input": {
"address": "つきみ野 618 大和市 神奈川県 242-0002 jpn"
},
"matches": [
{
"aqi": "a",
"avc": "v44-i44-p6-100",
"address": "6-1-8 tsukimino,yamato-shi kanagawa 242-0002",
"address1": "6-1-8 tsukimino",
"address2": "yamato-shi kanagawa 242-0002",
"administrativearea": "kanagawa",
"countryname": "japan",
"deliveryaddress": "6-1-8 tsukimino",
"deliveryaddress1": "6-1-8 tsukimino",
"geoaccuracy": "p4",
"geodistance": "0.0",
"hyphenclass": "c",
"iso3166-2": "jp",
"country": "jp",
"iso3166-3": "jpn",
"iso3166-n": "392",
"latitude": "35.512035",
"locality": "yamato-shi",
"localityname": "taiwashi",
"localitytrailingtype": "shi",
"localitytype": "shi",
"longitude": "139.453619",
"matchrulelabel": "v1a",
"postalcode": "242-0002",
"postalcodeprimary": "242-0002",
"premise": "6-1-8",
"premisenumber": "6-1-8",
"thoroughfare": "tsukimino",
"thoroughfarename": "tukimi",
"thoroughfaretrailingtype": "ya",
"thoroughfaretype": "ya"
}
]
}
]