The ZIP Code API

How to look up cities, states, and ZIP Codes without street addresses

The ZIP Code API allows you to identify cities with ZIP Codes, and vice-versa. It also provides approximate geo-coordinates (latitude/longitude). This endpoint does not support street addresses as input.

Jump to:


City / State / ZIP Code lookups

The REST endpoint for this API is at

https://api.smartystreets.com/zipcode

Allowed Input

You may supply these values to the ZIP Code API:

Parameter name Required Definition
auth-id Y
(if using key pair)
Unique "auth-id" value, obtained from the Key Management page under "Security Keys." Do not use this field for an HTML key (use auth-token instead).
If used, this value must appear in the query string, not the request body.
auth-token Y Unique "auth-token" value, obtained from the Key Management page. If using security keys, this must be associated with an ID in the auth-id field.
This value must appear in the query string, not the request body.
city The city name
state The state name or abbreviation
zipcode The 5-digit ZIP Code
callback The name of the function in which to wrap the JSON response. Typically only used for cross-domain JSONP requests with Javascript.

Note: Any combination of city/state/zip is accepted, except for "city" alone.

Subscription notice: Each lookup to the ZIP Code API, including each entry in a bulk request, will deduct 1 lookup from the allotted amount on your subscription.

Examples: a single lookup

Method: GET https://api.smartystreets.com/zipcode?city=Los+Angeles&state=CA&zipcode=90023&auth-id=<id>&auth-token=<token>

Method: POST
URL: https://api.smartystreets.com/zipcode?auth-id=<id>&auth-token=<token>
JSON Payload: [ { "zipcode": "20500" } ] Notice how the request body is an array of address objects. The LiveAddress API is designed to receive an array of addresses because it can handle up to 100 city/state or ZIP Code entries per request. Even if you submit only one entry, it must be inside an array.

Example: batch request

Batch requests can only be sent via POST. You can submit up to 100 lookups per request.

Method: POST
URL: https://api.smartystreets.com/zipcode?auth-id=<id>&auth-token=<token>
JSON Payload: [ { "zipcode": "20500" }, { "city": "Cupertino", "state": "CA" }, { "city": "Cupertino", "state": "CA", "zipcode": "95014" }, { }, { "zipcode": "eibn3ei2nb" }, { "city": "Does not exist", "state": "CA" }, { "city": "Cupertino", "state": "ca", "zipcode": "90210" } ]


HTTP Status Codes

Responses come with one of the following status codes:

HTTP Code Definition
200 Success. See response body for result payload.
400 Bad input. Required fields missing from input, are malformed, or are too numerous.
401 Unauthorized. Authentication failure; invalid credentials.
402 Payment required. No active subscription found.
500 Internal server error. General service failure; retry request.

Output

This API responds with a JSON payload containing the results. Note: Every response is an array because, quite frequently, more than one set of data is returned. The exact number of items in the array depends on how many matches there are, and how many lookups were contained in the input request.

No results

When there is no match for the given input (city/state, or ZIP Code), the object returned in place of the input has a status and reason to tell you why. Example:

JSON Response: [ { "status": "invalid_zipcode", "reason": "Invalid ZIP Code." } ]

Following is a list of possible statuses and their reasons:

Status Reason
blank Blank lookup (you must provide a ZIP Code and/or City/State combination).
invalid_state Invalid State name or abbreviation.
invalid_city Invalid City for the given State.
invalid_zipcode Invalid ZIP Code.
conflict Conflicting ZIP Code/City/State information.

ZIP Code Types

The zipcode_type field has a code which indicates the type of ZIP code was matched:

Code Meaning
S Standard. This is a regular ZIP code.
M Military. APO/FPO military ZIP.
P PO Box. Only post office boxes are served in this ZIP code.
U Unique. This ZIP code belongs primarily to an organization.

ZIP Code → City+State

When submitting a valid ZIP Code as input (without a city or state) the output will be a listing of the valid city/state combinations as well as the approximate latitude/longitude coordinate.

Example Input:
ZIP Code: 10167
URL: https://api.smartystreets.com/zipcode?zipcode=10167&auth-id=<id>&auth-token=<token>
JSON Response: [ { "city_states": [ { "city": "New York", "state_abbreviation": "NY", "state": "New York" }, // ... CLIPPED FOR BREVITY (lots of results) ... { "city": "NYC", "state_abbreviation": "NY", "state": "New York" } ], "zipcodes": [ { "zipcode": "10167", "zipcode_type": "S", "county_fips": "36061", "county_name": "New York", "latitude": 40.75556, "longitude": -73.974469 } ] } ]


City+State → ZIP Codes

When submitting a valid city/state combination (without a ZIP Code) the output will be a listing of valid ZIP Codes (and their approximate latitude/longitude coordinates) as well as the confirmed city/state combination.

Example Input:
City: Los Angeles
State: California
URL: https://api.smartystreets.com/zipcode?city=los+angeles&state=california&auth-id=<id>&auth-token=<token>
JSON Response: [ { "city_states": [ { "city": "Los Angeles", "state_abbreviation": "CA", "state": "California" } ], "zipcodes": [ { "zipcode": "90001", "zipcode_type": "S", "county_fips": "06037", "county_name": "Los Angeles", "latitude": 33.973124, "longitude": -118.248502 }, // ... CLIPPED FOR BREVITY (lots of results) ... { "zipcode": "90230", "zipcode_type": "S", "county_fips": "06037", "county_name": "Los Angeles", "latitude": 33.996155, "longitude": -118.395494 } ] } ]

Validate city, state, and ZIP Code combinations

When a valid city/state/ZIP Code combination is submitted, the output will reflect the valid combination showing only the valid ZIP Code (with the approximate latitude/longitude coordinate) and the valid city/state combination.

Example Input:
City: Los Angeles
State: California
ZIP Code: 90230
URL: https://api.smartystreets.com/zipcode?city=los+angeles&state=california&zipcode=90230&auth-id=<id>&auth-token=<token>
JSON Response: [ { "input_index": 0, "city_states": [ { "city": "Los Angeles", "state_abbreviation": "CA", "state": "California" } ], "zipcodes": [ { "zipcode": "90230", "zipcode_type": "S", "county_fips": "06037", "county_name": "Los Angeles", "latitude": 33.996155, "longitude": -118.395494 } ] } ]

Verify a state

... quite frankly, we didn't find a "state" lookup to be particularly useful since there's only 50 of them (along with the territories and military designations), but we've provided one anyway. Try it! You'll see we had some fun.



Optimizations and enhancements

To increase throughput, we've trimmed all whitespace from values returned by the API. JSON will be compacted so as to use as few bytes as possible, and fields which contain an empty/null value (or false if it's default) will not be included in the result set. Make sure your code can handle empty/missing fields. Treat them as if they are 0, null, empty, or false as appropriate.

From time to time, we may introduce new properties into the result set to improve and enhance the service.


Sample code

We have lots of sample code on GitHub which you can peruse and learn from. You may use the files as starting points, but don't thrust it into your production code as-is. We don't officially support sample code, but have provided it as a courtesy. You are welcome to make pull requests and open issues on GitHub. We do actively maintain the repository.