Validate Address

The Validate Address resource permits a user to validate and retrieve the most likely matches of provided postal addresses. Each successful validation costs $0.03 (USD). US address validations are free of charge.

Scope: validate

Actions

POST /validate-address Get validated possible matches of provided postal addresses

Properties

addresses 

{
    "addresses": [
        {
            "street1": "113 INTL BROADWAY",
            "street2": "",
            "city": "LOS ANGELES",
            "province": "CALIFORNIA",
            "postal_code": "91013",
            "country": "US"
        }
    ]
}

Array - List of addresses. Minimum: 1. Maximum: 10. Required

street1: String(40) - The street address. Required.
street2: String(40) - Additional space for the street address. Optional.
city: String(40) - The city. Required.
province: String(40) - The province or the state. Optional. Required for US.
postal_code: String(10) - The postal code or ZIP Code. Optional.
country: String(2) - The country in ISO 3166-1 alpha-2 format. Required.
  • Allowed Values: AU, AT, BE, BR, CA, CL, CO, CZ, DK, EE, FI, FR, DE, HU, IE, IT, LV, LT, LU, MY, MX, NL, NO, NZ, PL, PR, SG, SK, SI, ES, SE, CH, GB, US
original 

{
    "original": {
        "street1": "113 INTL",
        "street2": "BROADWAY",
        "city": "LAS ANGELES",
        "province": "CALIFORNIA",
        "postal_code": "91014",
        "country": "US"
    }
}

Object - The provided original address.
error

{"error": true}

Boolean - Whether or not there has been an error while validating the address.
message

{"message": "[US.state] is not in the correct format"}

String|null - A message which explains the error occurred. It can be null if there's no error.
matches 

{
    "matches": [
        {
            "street1": "113 INTL BROADWAY",
            "street2": "",
            "city": "LOS ANGELES",
            "province": "CA",
            "postal_code": "91013",
            "country": "US",
            "confidence": "HIGH"
        }
    ]
}

Array - List of postal address matches for the provided original address.
matches[].confidence

  • LOW
    LOW confidence means that the address is most probably does not exist thus, it should not be provided as an address input to any of our endpoints.

  • MEDIUM
    MEDIUM confidence means that the address is missing some components or some parts are unconfirmed but plausible. It is usually acceptable as an address input but whether it can be used or not depends on its completeness thus, caution is advised.

  • HIGH
    HIGH confidence means that there's an exact match thus, it is recommended and can be used as an address input.
String - Confidence value inside each match describes how accurate the match is. You can increase the confidence of an existing match by providing additional or more accurate information.

POST
/validate-address
Get validated possible matches of provided postal addresses.
request
POST /validate-address 
{
    "addresses": [
        {
            "street1": "1600 Amphitheatre Parkway",
            "street2": "",
            "city": "Montan View",
            "province": "CALIFORNIA",
            "postal_code": "94043",
            "country": "US"
        },
        {
            "street1": "113 Intl Broadway",
            "street2": "",
            "city": "Los Angeles",
            "province": "",
            "postal_code": "91013",
            "country": "US"
        },
        {
            "street1": "Via Piano dell'Ucciardone",
            "street2": "2",
            "city": "Palermo",
            "province": "PA",
            "postal_code": "90140",
            "country": "IT"
        },
        {
            "street1": "Steinsdorfstraße",
            "street2": "14",
            "city": "Munich",
            "province": "",
            "postal_code": "80538",
            "country": "DE"
        }
    ]
}
response

HTTP/1.1 200 OK

{
    "addresses": [
        {
            "original": {
                "street1": "1600 Amphitheatre Parkway",
                "street2": "",
                "city": "Montan View",
                "province": "CA",
                "postal_code": "94043",
                "country": "US"
            },
            "error": false,
            "message": null,
            "matches": [
                {
                    "street1": "1600 AMPHITHEATRE PKWY",
                    "street2": "",
                    "city": "MOUNTAIN VIEW",
                    "province": "CA",
                    "postal_code": "94043-1351",
                    "country": "US",
                    "confidence": "HIGH"
                }
            ]
        },
        {
            "original": {
                "street1": "113 Intl Broadway",
                "street2": "",
                "city": "Los Angeles",
                "province": "",
                "postal_code": "91013",
                "country": "US"
            },
            "error": true,
            "message": "[US.state] is not in the correct format",
            "matches": []
        },
        {
            "original": {
                "street1": "Via Piano dell'Ucciardone",
                "street2": "2",
                "city": "Palermo",
                "province": "PA",
                "postal_code": "90140",
                "country": "IT"
            },
            "error": false,
            "message": null,
            "matches": [
                {
                    "street1": "Via Piano dell'Ucciardone, 2",
                    "street2": "",
                    "city": "Palermo",
                    "province": "PA",
                    "postal_code": "90139",
                    "country": "IT",
                    "confidence": "MEDIUM"
                }
            ]
        },
        {
            "original": {
                "street1": "Steinsdorfstraße",
                "street2": "14",
                "city": "Munich",
                "province": "",
                "postal_code": "80538",
                "country": "DE"
            },
            "error": false,
            "message": null,
            "matches": [
                {
                    "street1": "Steinsdorfstraße 14",
                    "street2": "",
                    "city": "München",
                    "province": "",
                    "postal_code": "80538",
                    "country": "DE",
                    "confidence": "LOW"
                }
            ]
        }
    ]
}