Free JSON API for postal codes, regions and places worldwide. The same data you see on ListPostCode, ready for your app.
Every country, with codes, currency and whether postcodes exist.
One country's details and how many places and postcodes it has.
Regions of a country by level, paginated.
One place with its postcode, coordinates and parents.
The places inside a region, paginated.
Turn a ListPostCode URL path into the place it shows.
Every place that uses a postcode in a country.
Search countries and places by name or postcode.
The nearest place with a postcode to a latitude and longitude.
Create a free ListPostCode developer account and copy your key from the dashboard.
curl -H "x-api-key: YOUR_API_KEY" \
"https://api.listpostcode.com/v1/countries/AU"Every response has the same envelope: statusCode, data and metadata.correlationId.
{
"statusCode": 200,
"data": {
"code": "KH",
"alpha3": "KHM",
"name": "Cambodia",
"slug": "cambodia",
"region": "AS",
"subRegion": null,
"currencyCode": "KHR",
"timezone": "Asia/Phnom_Penh",
"latitude": 12.565679,
"longitude": 104.990963,
"postalCodeFormat": "#####",
"hasPostcodes": true,
"url": "https://listpostcode.com/cambodia",
"stats": {
"totalPlaces": 16635,
"distinctPostcodes": 16634,
"levels": [
{
"level": 1,
"count": 25
},
{
"level": 2,
"count": 226
},
{
"level": 3,
"count": 1663
},
{
"level": 4,
"count": 14721
}
]
}
},
"metadata": {
"correlationId": "0199a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b"
}
}Send your key in the x-api-key header on every request.
Keep your key secret. Call the API from your server, or from a browser only with a key you are happy to expose.
https://api.listpostcode.comEvery key starts on the free plan: 10,000 requests per calendar month.
Over the limit, the API answers 429 until the next month. Without a key or with a wrong key, it answers 401. Your dashboard shows how much you have used.
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | A parameter is missing or invalid. |
| 401 | TOSKEY_API_KEY_MISSING | No API key was sent. |
| 401 | TOSKEY_API_KEY_INVALID | The key is wrong. |
| 401 | TOSKEY_API_KEY_REVOKED | The key was revoked or replaced. |
| 404 | COUNTRY_NOT_FOUND | No country with that code. |
| 404 | NO_POSTCODE_DATA | The country has no postcode data yet. |
| 404 | PLACE_NOT_FOUND | No place with that id or path. |
| 404 | POSTCODE_NOT_FOUND | No place uses that postcode. |
| 404 | NO_NEARBY_PLACE | Nothing within 80 km. |
| 429 | TOSKEY_QUOTA_EXCEEDED | Monthly free plan used up. |
Error bodies look like { statusCode, error: { message, code }, metadata: { correlationId } }. Quote the correlationId when you contact us.
List endpoints take page (from 1) and pageSize (1–100, default 50) and return items, pageNumber, pageSize, totalCount, totalPages, hasPreviousPage and hasNextPage.
Data comes from the ListPostCode dataset. Each place links back to its page on listpostcode.com in the url field. Please credit ListPostCode with a link when you show the data.
Place data includes GeoNames data (geonames.org, CC BY 4.0).
Yes. All endpoints listed here are on the free plan. You only need a free key.
Every country in the list endpoint where hasPostcodes is true.
Yes, CORS is open. Anyone can read a key shipped in front-end code, so prefer calling from your server.
With each dataset release. Responses can be cached for an hour.
In your developer dashboard, where you can reveal, replace or revoke it.
Free JSON API for postal codes, regions and places worldwide. The same data you see on ListPostCode, ready for your app.
Every country, with codes, currency and whether postcodes exist.
One country's details and how many places and postcodes it has.
Regions of a country by level, paginated.
One place with its postcode, coordinates and parents.
The places inside a region, paginated.
Turn a ListPostCode URL path into the place it shows.
Every place that uses a postcode in a country.
Search countries and places by name or postcode.
The nearest place with a postcode to a latitude and longitude.
Create a free ListPostCode developer account and copy your key from the dashboard.
curl -H "x-api-key: YOUR_API_KEY" \
"https://api.listpostcode.com/v1/countries/AU"Every response has the same envelope: statusCode, data and metadata.correlationId.
{
"statusCode": 200,
"data": {
"code": "KH",
"alpha3": "KHM",
"name": "Cambodia",
"slug": "cambodia",
"region": "AS",
"subRegion": null,
"currencyCode": "KHR",
"timezone": "Asia/Phnom_Penh",
"latitude": 12.565679,
"longitude": 104.990963,
"postalCodeFormat": "#####",
"hasPostcodes": true,
"url": "https://listpostcode.com/cambodia",
"stats": {
"totalPlaces": 16635,
"distinctPostcodes": 16634,
"levels": [
{
"level": 1,
"count": 25
},
{
"level": 2,
"count": 226
},
{
"level": 3,
"count": 1663
},
{
"level": 4,
"count": 14721
}
]
}
},
"metadata": {
"correlationId": "0199a1b2-3c4d-7e5f-8a9b-0c1d2e3f4a5b"
}
}Send your key in the x-api-key header on every request.
Keep your key secret. Call the API from your server, or from a browser only with a key you are happy to expose.
https://api.listpostcode.comEvery key starts on the free plan: 10,000 requests per calendar month.
Over the limit, the API answers 429 until the next month. Without a key or with a wrong key, it answers 401. Your dashboard shows how much you have used.
| Status | Code | Meaning |
|---|---|---|
| 400 | VALIDATION_FAILED | A parameter is missing or invalid. |
| 401 | TOSKEY_API_KEY_MISSING | No API key was sent. |
| 401 | TOSKEY_API_KEY_INVALID | The key is wrong. |
| 401 | TOSKEY_API_KEY_REVOKED | The key was revoked or replaced. |
| 404 | COUNTRY_NOT_FOUND | No country with that code. |
| 404 | NO_POSTCODE_DATA | The country has no postcode data yet. |
| 404 | PLACE_NOT_FOUND | No place with that id or path. |
| 404 | POSTCODE_NOT_FOUND | No place uses that postcode. |
| 404 | NO_NEARBY_PLACE | Nothing within 80 km. |
| 429 | TOSKEY_QUOTA_EXCEEDED | Monthly free plan used up. |
Error bodies look like { statusCode, error: { message, code }, metadata: { correlationId } }. Quote the correlationId when you contact us.
List endpoints take page (from 1) and pageSize (1–100, default 50) and return items, pageNumber, pageSize, totalCount, totalPages, hasPreviousPage and hasNextPage.
Data comes from the ListPostCode dataset. Each place links back to its page on listpostcode.com in the url field. Please credit ListPostCode with a link when you show the data.
Place data includes GeoNames data (geonames.org, CC BY 4.0).
Yes. All endpoints listed here are on the free plan. You only need a free key.
Every country in the list endpoint where hasPostcodes is true.
Yes, CORS is open. Anyone can read a key shipped in front-end code, so prefer calling from your server.
With each dataset release. Responses can be cached for an hour.
In your developer dashboard, where you can reveal, replace or revoke it.