NewConnect Claude, Gemini, ChatGPT, and other AI agents to API Ninjas via our MCP server →

Postal Code API

The Postal Code API looks up postal codes across more than 100 countries, returning the city, region and coordinates for a given code. Pass a two-letter country code alongside the postal code, or search in reverse by city or region.

The API covers 117 countries. A further 70 countries and territories operate no postal code system at all, and return has_postal_codes: false.

Popular countries: United Kingdom, India, Australia, Singapore, Indonesia, Germany, Netherlands, Malaysia, France, Japan, South Korea.

If you're looking for US zip codes, use the Zip Code API instead.

(4.2)

From 4,188 users

1,600+

Applications using this API

API Status

Online - All Systems Operational

API Response Times

Average
P50
P75
P90
P95
298ms319ms350ms731ms1187ms

Didn't find what you were looking for? Suggest an improvement

https://api.api-ninjas.com/v1/postalcode

Returns a list of postal code details matching the input parameters.

Formatting is flexible. Spaces, hyphens and country prefixes are normalized, so 1011AB and 1011 AB both resolve, as do L-4968 and 4968.

Parameters

At least one of postal_code, city or region must be set:

  • country  optional

    Two-letter ISO 3166-1 alpha-2 country code (e.g., GB, DE, IN, JP). Defaults to CA when omitted.

  • postal_code  optional

    The postal code to look up. Spaces, hyphens and country prefixes are normalized automatically, so both the local written form and the bare code will resolve.

  • city  optional Premium only

    Full name of the city or place to search (case-sensitive).

  • region  optional Premium only

    Name or code of the first-level region, such as a state, province or county (e.g., England, Bayern, ON). province is accepted as an alias.

Headers

  • X-Api-Key  required

    API Key associated with your account.

Response

A JSON array of objects, each containing the following fields, or an error if the request is unsuccessful.

  • country

    Two-letter ISO country code for the result.

  • postal_code

    The postal code in its normalized local form.

  • city

    The city or place name associated with the postal code.

  • region

    First-level region: state, province or county (e.g., England, Bayern).

  • region_code  Premium only

    Code for the first-level region, where the country publishes one.

  • county  Premium only

    Second-level region: county, district or municipality.

  • county_code  Premium only

    Code for the second-level region, where the country publishes one.

  • lat  Premium only

    The latitude coordinate of the postal code location.

  • lon  Premium only

    The longitude coordinate of the postal code location.

  • timezone

    The IANA timezone for the location (e.g., Europe/London).

  • area_code

    The telephone area code for the location. Available for Canada only; for United States ZIP codes, use the Zip Code API, which returns area_codes for every US ZIP. Telephone area codes follow exchange boundaries rather than postal ones, so no equivalent mapping exists for other countries.

Sample Request Live Demo!

country
postal_code
city Premium only
region Premium only

Try our APIs in the API playground

Sign up for a free API key to get started — no credit card required.

https://api.api-ninjas.com/v1/postalcode?country=GB&postal_code=SW1A1AA

Headers

X-Api-KeyLog in or sign up to get your API Key

Sample Response

JSON
[
    {
      country:"GB",
      postal_code:"SW1A 1AA",
      city:"London",
      region:"England",
      region_code:"ENG",
      county:"Greater London",
      county_code:"GLA",
      lat:"51.5010",
      lon:"-0.1416",
      timezone:"Europe/London"
    }
]

Code Examples

1 2 curl -X GET "https://api.api-ninjas.com/v1/postalcode?country=GB&postal_code=SW1A1AA" \ -H "X-Api-Key: YOUR_API_KEY"

If your programming language is not listed in the Code Example above, you can still make API calls by using a HTTP request library written in your programming language and following the above documentation.

Frequently Asked Questions

  • Yes, but you must have a premium subscription. Commercial use of the Postal Code API is not permitted on the free tier. See our pricing page to choose a plan that fits your needs.
  • Sign up for a free account to instantly get your API key, then pass it in the X-Api-Key header on every request. The documentation above includes ready-to-run examples in cURL, Python, JavaScript, Node.js, and more.
  • Your API requests will simply be denied once you hit your monthly quota — you will never be charged more than the plan you signed up for. To increase your quota, you can upgrade your plan any time on our pricing page.
  • The API responds with a standard HTTP status code and a JSON error message describing the problem. See our error codes reference for the full list of codes and how to resolve each one, or contact support if you need help.
  • The API covers over 100 countries. Pass a two-letter ISO 3166-1 country code to the country parameter along with a postal_code. Coverage varies by country, and we publish a per-country manifest showing the exact number of codes, the data source, and whether coverage is complete or partial, so you can check before you build. For US ZIP codes, use the Zip Code API.
  • Pass the country and postal_code parameters, for example country=GB&postal_code=SW1A1AA. Formatting is flexible: spaces, hyphens and country prefixes are normalized, so 1011AB and 1011 AB both resolve, as do L-4968 and 4968 for Luxembourg. Review possible error codes if a lookup returns no match.
  • Each object includes country, the normalized postal_code, city, region, and the IANA timezone. Paid plans additionally return region_code, county, county_code, lat and lon. The area_code field is available for Canada only; for US ZIP codes use the Zip Code API. To turn coordinates into a full address, pair this with the Geocoding API.
  • Yes. Supply the city or region parameter instead of a postal code to find every code in that area. These are premium-only inputs available on the paid plans listed on our pricing page.
  • Around 68 countries and territories, including the United Arab Emirates, Hong Kong, Macau, Qatar and Panama, operate no postal code system at all. Rather than returning an empty result, the API responds with has_postal_codes: false and a short explanation, so your address forms can skip the field instead of failing validation.
  • Canadian lookups remain the default when no country parameter is supplied, and the province parameter is still accepted as an alias for region, so existing integrations continue to work unchanged.