World Postal Codes API

Look up postal codes in 124 countries (place, state, county, coordinates), search by place or nearest point, validate formats of 180 countries.

GEThttps://apibox.io.vn/v1/world-postcodes

Data & JSON▶ Try it online

country + postcode (or /v1/world-postcodes/<CC>/<code>) returns the places that use the code with their first, second and third-level divisions and approximate coordinates; spaces, dashes and case do not matter (sw1a1aa = SW1A 1AA). A partial code (an outward code such as SW1A, the first digits of a ZIP) lists the codes that start with it. Every answer also says whether the code matches the official format of the country (format.valid, the pattern and examples); validate_only=true checks the format without a lookup, and works for about 180 countries – including those without a database, such as Vietnam.

q finds places by name in a country (accents optional) with their codes; lat + lon returns the nearest postal codes to a point. action=countries lists the countries covered and action=formats the format patterns.

Data: the GeoNames postal-code dump (CC BY 4.0, refreshed weekly) – about 4.1 million codes; the UK and the Netherlands have full codes (UK from Code-Point Open, Open Government Licence), Canada, Ireland, Malta, Chile and Argentina only the first part, Brazil only major codes, and some countries (Vietnam included) none. Coordinates are centroids, not delivery points. Formats come from Google's address metadata (libaddressinput, CC BY 4.0). Keep the attribution text when you display the data.

Parameters

Name	In	Type	Required	Default
`country`	query	string	yes		ISO 3166-1 alpha-2 code (`US`, `GB`, `DE`…). Not needed with `action`.
`postcode`	query	string	no		Postal code to look up (full or partial).
`q`	query	string	no		Place name to search in the country.
`lat`	query	number	no		Latitude for the nearest codes (with `lon`).
`lon`	query	number	no		Longitude.
`validate_only`	query	boolean	no	`false`	Only check the format of `postcode`.
`action`	query	string	no		`countries` (coverage) or `formats` (patterns of every country).
`limit`	query	number	no	`10`	Results for partial codes and place search (1–100; nearest: 1–20, default 5).

Example

curl "https://apibox.io.vn/v1/world-postcodes?country=GB&postcode=sw1a1aa" \
  -H "Authorization: Bearer YOUR_API_KEY"

const res = await fetch('https://apibox.io.vn/v1/world-postcodes?country=GB&postcode=sw1a1aa', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
  },
});
const data = await res.json();
console.log(data);

import requests

res = requests.get(
    "https://apibox.io.vn/v1/world-postcodes?country=GB&postcode=sw1a1aa",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    timeout=30,
)
print(res.json())

<?php
$ch = curl_init('https://apibox.io.vn/v1/world-postcodes?country=GB&postcode=sw1a1aa');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
]);
$response = curl_exec($ch);
print_r(json_decode($response, true));

Response

{
  "country": "GB",
  "postcode": "SW1A 1AA",
  "found": true,
  "format": {
    "checked": true,
    "valid": true,
    "pattern": "GIR ?0AA|(?:(?:AB|AL|B|…|ZE)(?:\\d[\\dA-Z]? ?\\d[ABD-HJLN-UW-Z]{2}))|BFPO ?\\d{1,4}",
    "examples": [
      "EC1Y 8SY",
      "GIR 0AA",
      "M2 5BQ",
      "…"
    ]
  },
  "count": 1,
  "places": [
    {
      "postcode": "SW1A 1AA",
      "place": "London",
      "admin1": "England",
      "admin1_code": "ENG",
      "admin2": "Greater London",
      "admin2_code": "GLA",
      "admin3": "City of Westminster",
      "admin3_code": "E09000033",
      "lat": 51.501,
      "lon": -0.1416,
      "accuracy": 6
    }
  ],
  "accuracy_note": "accuracy: 1 = estimated, 4 = from a GeoNames place, 6 = centroid of addresses or shape (null = unknown)",
  "data_version": "20261111",
  "attribution": [
    "Postal code data © GeoNames (geonames.org), CC BY 4.0. GB: contains Royal Mail data © Royal Mail copyright and database right; contains OS data © Crown copyright and database right (Open Government Licence v3.0).",
    "Postal code formats: Google libaddressinput address metadata, CC BY 4.0"
  ]
}

Use cases

Validate and autocomplete the postal code in an international checkout
Fill the city and state fields from a ZIP code
Find the postal code closest to a GPS position
Check that a list of addresses uses well-formed codes before shipping

FAQ

Which countries are covered?

124 countries have a database (action=countries lists them with their row counts); about 180 have a format check. Vietnam has format validation here and its own lookup at /v1/vn-postcode.

Why does a Canadian code only give the first three characters?

Full Canadian postal codes are Canada Post's property; the open data only has the forward sortation area (e.g. K1A). Use those three characters for the lookup.

Are the coordinates exact?

No. They are centroids of the code area or of the place; the accuracy field (1, 4 or 6) tells how they were obtained.

Related APIs

{✓}

World Postal Codes API

Parameters

Example

Response

Use cases

FAQ

Related APIs

JSON Validator

JSON Formatter

CSV to JSON