Postal code validation
Address validation API for postal codes
Catch the typo before the parcel goes out. The /v1/validate endpoint checks the postal code of an address against its country: it tells you whether the code exists, whether it has the country's format and which city, state and county it belongs to. It does not verify street names or house numbers.
Example request and response
The /v1/validate endpoint, with the example from the documentation. Compare the returned city and state with what the customer entered to catch a code that exists but belongs to another town.
curl -G https://api.zipcodestack.com/v1/validate \
-d code=1010 \
-d country=at \
-H "apikey: YOUR-API-KEY"
{
"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",
"state_code": "09",
"province": "Wien Stadt",
"community": "Wien, Innere Stadt",
"accuracy": 4
}
]
}
}
Response fields
| Field | What it contains |
|---|---|
| valid | Whether the code exists in our data for that country. |
| format_valid | Whether the code matches the country's postal code format, for example four digits in Austria or A1A 1A1 in Canada. null when no format is known for the country. |
| uses_postal_codes | false for countries without postal codes, such as Hong Kong: hide the field for them. |
| normalized | The code as stored, in upper case with the canonical spacing. Save this instead of the raw input. |
| matches | Every place the code belongs to, with city, state, county or district, coordinates and their accuracy. |
Use cases
Checkout and shipping forms
Reject a postal code that does not exist before the order is placed, and suggest the city and state for the code the customer typed.
Sign-up and CRM data
Store the normalized code and the matching city, so reports and territories group addresses correctly.
Hide the field where it is not used
Countries without postal codes return uses_postal_codes: false, so international forms stop asking for one.
Start on the free plan
Every call to /v1/validate costs 1 credit. The free plan includes 300 credits a month with 10 requests a minute; paid plans start at $34.99 a month for 70,000 credits.
Frequently asked questions
Does this verify street addresses?
What is the difference between valid and format_valid?
valid: false with format_valid: true means the code looks right but is not assigned, usually a typo in one digit. Both false means the input does not even have the country's format.