Postal Code Validation Endpoint

Checks a postal code against a country: does it exist, and does it have the country’s format?

Use it in checkout and sign-up forms to catch typos before an order ships to an address that does not exist.

This endpoint costs 1 credit per request.

GET/v1/validate

Validate A Postal Code

Required attributes

Name
code
Type
string
Description
The postal code to check, as the user typed it. Surrounding spaces and lower case are fine.
Name
country
Type
string
Description
Two letter country code. Example: at

Response Properties

The fields below are returned inside result; query echoes the code and country you sent.

Name
valid
Type
boolean
Description
Whether the code exists in our data for that country.
Name
format_valid
Type
boolean | null
Description
Whether the code matches the country’s postal code format (for example four digits in Austria, A1A 1A1 in Canada). null when we know no format for the country, e.g. for countries without postal codes.
Name
uses_postal_codes
Type
boolean
Description
false for countries that do not use postal codes, such as Hong Kong. Hide the postal code field for them.
Name
normalized
Type
string | null
Description
The code as stored, e.g. upper case with the canonical spacing. Save this instead of the user’s input.
Name
matches
Type
array
Description
The location data of every match, with the same fields as /v1/search.

valid and format_valid answer different questions. {"valid": false, "format_valid": true} means the code looks right but is not assigned, which usually is a typo in one digit. {"valid": false, "format_valid": false} means the input is not a postal code of that country at all.

Request

GET

/v1/validate

curl -G https://api.zipcodestack.com/v1/validate \
    -d code=1010 \
    -d country=at \
    -H "apikey: YOUR-API-KEY"

Response

{
    "query": {
        "code": "1010",
        "country": "AT"
    },
    "result": {
        "valid": true,
        "format_valid": true,
        "uses_postal_codes": true,
        "normalized": "1010",
        "matches": [
            {
                "postal_code": "1010",
                "country_code": "AT",
                "latitude": 48.2077,
                "longitude": 16.3705,
                "city": "Wien, Innere Stadt",
                "state": "Wien",
                "city_en": "Wien, Innere Stadt",
                "state_en": "Wien",
                "state_code": "09",
                "province": "Wien Stadt",
                "province_code": "900",
                "community": "Wien, Innere Stadt",
                "community_code": "90101",
                "accuracy": 4
            }
        ]
    }
}

Well-formed but not assigned (code=1999)

{
    "query": {
        "code": "1999",
        "country": "AT"
    },
    "result": {
        "valid": false,
        "format_valid": true,
        "uses_postal_codes": true,
        "normalized": null,
        "matches": []
    }
}