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

Postal Code API

See More

The Postal Code API enables you to look up detailed information for postal codes in Canada. You can input postal codes directly, or search for postal codes using city and province parameters.

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

/v1/postalcode GET

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

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

Parameters

At least one of the following parameters must be set:

  • postal_code  optional

    The postal code to look up. Accepts Canadian postal codes in 6 characters (A1A1A1) or 7 characters with a space (A1A 1A1). The space will be automatically normalized if not provided.

  • city  optional premium only

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

  • province  optional premium only

    2-letter abbreviation of the province (e.g., ON, BC, QC).

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.

  • city

    The city name associated with the postal code.

  • province

    The 2-letter province abbreviation (e.g., ON, BC, QC).

  • postal_code

    The postal code in normalized format (A1A 1A1).

  • area_code

    The area code associated with the postal code.

  • timezone

    The timezone for the location (e.g., America/Toronto).

  • lat

    The latitude coordinate of the postal code location.

  • lon

    The longitude coordinate of the postal code location.

Sample Request Live Demo!

postal_code
city premium
province premium

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?postal_code=K1A0B1

Headers

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

Sample Response

JSON
[
    {
      city:"Ottawa",
      province:"ON",
      postal_code:"K1A 0B1",
      area_code:"613",
      timezone:"America/Toronto",
      lat:"45.4168",
      lon:"-75.7002"
    }
]

Code Examples

1 2 curl -X GET "https://api.api-ninjas.com/v1/postalcode?postal_code=K1A0B1" \ -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 Postal Code API covers Canadian postal codes only, returning the city, province, area_code, timezone, and lat/lon coordinates for a given code. If you need US ZIP codes instead, use the Zip Code API.
  • Pass the postal code to the postal_code parameter, accepting either the 6-character form (A1A1A1) or the 7-character form with a space (A1A 1A1); the space is normalized automatically if omitted. Review possible error codes if a lookup returns no match.
  • Yes, you can supply the city (full name, case-sensitive) and province (2-letter abbreviation such as ON, BC, or QC) parameters instead of a postal code, but these are premium-only inputs available on paid plans listed on our pricing page.
  • Each object in the JSON array includes city, province, normalized postal_code, area_code, timezone (e.g., America/Toronto), and the lat and lon coordinates. To convert those coordinates into a full address or vice versa, pair this with the Geocoding API.