API Documentation

Start using our easy to use API today, follow the examples to learn how to use it.




GET Get postal codes within a distance

With this easy to use endpoint you will get a list of Postal codes that are within a given distance. The request example will return a list of unique postal codes, a complete list of postal codes and the details of each postal code.

GET https://postalcodes.app/api/v1/?key=YOUR-APIKEY&distance=25&zipcode=10005&country=us

Our API accepts distance measurements in kilometers (Default) or miles.

To change measurement to kilometers you must put the ms parameter in your request:

GET https://postalcodes.app/api/v1/?key=YOUR-APIKEY&ms=km&distance=25&zipcode=10005&country=us

The response will look like this:

{
   "query":{
      "code": "10005",
      "country": "US",
      "range": "25",
      "measure": ""
   },
   "results":{
       "range_codes_unique": ["07010", "07020", "07022", "07024", "07026", ...],
       "range_codes": ["07010", "07020", "07022", "07024", "07026", ...],
       "range_codes_details": [
          {
              "postal_code":"07010",
              "country_code":"US",
              "city":"Cliffside Park",
              "state":"New Jersey",
              "state_code":"NJ",
              "province":"Bergen",
              "province_code":"003"
          },
          {
              "postal_code":"07020",
              "country_code":"US",
              "city":"Edgewater",
              "state":"New Jersey",
              "state_code":"NJ",
              "province":"Bergen",
              "province_code":"003"
          },
          {
              "postal_code":"07022",
              "country_code":"US",
              "city":"Fairview",
              "state":"New Jersey",
              "state_code":"NJ",
              "province":"Bergen",
              "province_code":"003"
          },
          {
              "postal_code":"07024",
              "country_code":"US",
              "city":"Fort Lee",
              "state":"New Jersey",
              "state_code":"NJ",
              "province":"Bergen",
              "province_code":"003"
          },
          {
              "postal_code":"07026",
              "country_code":"US",
              "city":"Garfield",
              "state":"New Jersey",
              "state_code":"NJ",
              "province":"Bergen",
              "province_code":"003"
          },
           ...
       ],
   }
}

GET Get postal codes details

The following example will return the details of the postal codes that match with the search query.

GET https://postalcodes.app/api/v1/?key=YOUR-APIKEY&zipcode=10005&country=us

The response will look like this:

{
   "query":{
      "code": "10005",
      "country": "us",
      "range": "",
      "measure": ""
   },
   "results":{
       "range_codes_unique": ["10005"],
       "range_codes": ["10005"],
       "range_codes_details": [
          {
              "postal_code":"10005",
              "country_code":"US",
              "city":"New York",
              "state":"New York",
              "state_code":"NY",
              "province":"New York",
              "province_code":"061"
          }
       ],
   }
}

GET Get custom data

You can pass extra params to get only what you need in the results, just add the value fields in your request.

GET https://postalcodes.app/api/v1/?key=YOUR-APIKEY&fields=["range_codes_unique"]&distance=25&zipcode=10005&country=us

The response will look like this:

{
   "query":{
      "code": "10005",
      "country": "US",
      "range": "25",
      "measure": ""
   },
   "results":{
       "range_codes_unique": ["07010", "07020", "07022", "07024", "07026", ...]
   }
}



Start using our API for free today!

Get 240 daily free requests

+94 Supported countries

AD (Andorra)
AR (Argentina)
AS (American Samoa)
AT (Austria)
AU (Australia)
AX (Aland Islands)
AZ (Azerbaijan)
BD (Bangladesh)
BE (Belgium)
BG (Bulgaria)
BM (Bermuda)
BR (Brazil)
Flag of Belarus
BY (Belarus)
CA (Canada)
CH (Switzerland)
CL (Chile)
CO (Colombia)
CR (Costa Rica)
CY (Cyprus)
CZ (Czech Republic)
Flag of Germany
DE (Germany)
DK (Denmark)
DO (Dominican Republic)
DZ (Algeria)
EE (Estonia)
ES (Spain)
FI (Finland)
FM (Micronesia)
FO (Faroe Islands)
FR (France)
GB (United Kingdom)
GF (French Guiana)
GG (Guernsey and Alderney)
GL (Greenland)
GP (Guadeloupe)
GT (Guatemala)
GU (Guam)
HR (Croatia (Hrvatska))
HU (Hungary)
IE (Ireland)
IM (Man (Isle of))
IN (India)
IS (Iceland)
IT (Italy)
JE (Jersey)
JP (Japan)
Flag of South Korea
KR (Korea South)
LI (Liechtenstein)
LK (Sri Lanka)
LT (Lithuania)
LU (Luxembourg)
LV (Latvia)
MC (Monaco)
MD (Moldova)
Flag of the Marshall Islands
MH (Marshall Islands)
MK (Macedonia)
MP (Northern Mariana Islands)
MQ (Martinique)