Setup

• Log into your rapidapi.com account
• Check the details for subscription plans and click subscribe
• Go to the endpoint page and click Test Endpoint
• Click the panel on the left to change the request snippet to the technology you are familiar with.
• Copy the example and run it in your favorite programming environment.

First API call

After completing the setup guide, you should verify that you are able to make a successful request.

curl --get --include 'https://us-zipcodes.p.rapidapi.com/codes/5033' \
       -H 'X-RapidAPI-Key: SIGN-UP-FOR-KEY' \
       -H 'X-RapidAPI-Host: us-zipcodes.p.rapidapi.com'

A success request would return a HTTP Status code of 200 and response looking similar to:

{
  "zip_code": "05033",
  "state": "Vermont",
  "state_code": "VT",
  "city": "Bradford",
  "population": 2572,
  "timezone": "America/New_York",
  "latitude": 44.00888,
  "longitude": -72.15799
}

Search City

Search using city name and return all macthed zip codes. It returns first 20 result.

curl --get --include 'https://us-zipcodes.p.rapidapi.com/codes?q=abc' \
       -H 'X-RapidAPI-Key: SIGN-UP-FOR-KEY' \
       -H 'X-RapidAPI-Host: us-zipcodes.p.rapidapi.com'

A success request would return a HTTP Status code of 200 and response looking similar to:

[
  {
    "zip_code": "54413",
    "state": "Wisconsin",
    "state_code": "WI",
    "city": "Babcock",
    "population": 149,
    "timezone": "America/Chicago",
    "latitude": 44.28432,
    "longitude": -90.13183
  }
]

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of a request. In case of an error, the response will include an error message with additional details.

Common error status codes:

400 Bad Request: Indicates that the request was malformed, missing required parameters or zip code not found in our system.

401 Unauthorized: Indicates that the API key is missing or invalid.

429 Too Many Requests: Indicates that you have exceeded the rate limit for your tier.

Example Error Response:

{
  "message":"zip code not found"
  "query":"123456"
  "status":false
}

A sample postman collection can be found here