API access: endpoints, plans and how to get a key – POSTCODEZIP US

Besides the downloadable files, we offer a REST API that answers in JSON. It is meant for applications that need live lookups rather than a static file: address validation, autocomplete, postal code and street search, and integration into an ERP or CRM such as Microsoft Dynamics 365 Business Central.

Plans and price

The API is not sold from the online shop and it has no public price list. It is quoted on request, on the basis of the request volume you expect per month and of the countries you need. Tell us roughly how many calls a month you plan to make and what you want to do with them, and we come back with a proposal.

A free test key is provided beforehand, so you can validate the integration before committing to anything.

Endpoints

Endpoint	What it returns	Main parameters
`/api/v1/countries`	Covered countries	country_code, page, size
`/api/v1/localities`	Cities and towns	country_code (required), name, page, size
`/api/v1/postal-codes`	Postal codes	country_code (required), postal_code, page, size
`/api/v1/zip-codes`	Same as postal-codes	country_code (required), postal_code, page, size
`/api/v1/streets`	Streets	country_code (required), name, locality, postal_code, page, size
`/api/v1/autocomplete`	Suggestions as the user types	query (required), country_code, contains, size

Authentication

Every call carries your key in the X-API-KEY header. Without it the API answers 401. With an unknown or revoked key it answers 403.

curl -H "X-API-KEY: YOUR_KEY" "https://api.YOURSITE.com/api/v1/countries?country_code=DE&size=5"

Replace YOURSITE with the site you deal with. The API is served on api.listreet.com, api.postalcodezip.com and api.postcodezip.com, and the three hosts expose exactly the same service.

Documentation

The interactive documentation is the Swagger page of the API host, at /swagger-ui/index.html, and the machine readable specification is at /v3/api-docs.

Troubleshooting

401: the X-API-KEY header is missing.
403 with ApiKey is not found: the key is wrong, expired, or truncated. Keys are long and e-mail clients often cut them across lines. Copy the key as a single unbroken string.
500: send us the exact URL you called and the time of the call, and we investigate.
There is no house number endpoint today. Address level data is delivered as a file. Tell us what you need and we will look at it.

Address validation

The current endpoints are lookup and autocomplete endpoints: they let you check whether a street, a city or a postal code exists and return the matching records. There is no endpoint yet that takes a full address and returns a corrected version. If that is what your project needs, tell us: parameters and results can be adapted on request.