US ZIP Code API

This page describes how to look up and verify city, state, and ZIP Code combinations using the Smarty (formerly SmartyStreets) APIs. We also provide a simple, non-technical validation tool to verify addresses.

Contents

  1. HTTP Request
    1. URL Composition
    2. Request Methods
    3. Input Fields
    4. Headers
  2. HTTP Response
    1. Status Codes and Results
    2. Output field definitions
  3. Supplementary Materials
    1. SSL/TLS Information
    2. Try the ZIP Code API demo

HTTP Request: URL Composition

Proper URL construction is required for all API requests. Here is an example URL:

https://us-zipcode.api.smarty.com/lookup?auth-id=123&auth-token=abc

Here is a more granular examination of the example above:

URL Components Values Notes
Scheme https NOTE: non-secure http requests are not supported
Hostname us-zipcode.api.smarty.com
Path /lookup NOTE: There is no trailing slash!
Query String ?auth-id=123&auth-token=abc Authentication information, inputs, etc. Additional query string parameters are introduced in the next section.

For additional information about URLs, please read our article about URL components.

HTTP Request: Supported Methods/Verbs

HTTP requests can be categorized according to their HTTP method. Most HTTP requests are defined using the GET method. We call these "get requests." Other common methods are PUT, POST, and DELETE.

The following methods are supported by this API:

Note: When calling any of our APIs using "embedded key" authentication, only the HTTP GET method is allowed. With "secret key" authentication, both HTTP GET and POST methods are allowed.

HTTP GET: Single Input

To send one (and only one) input to the API, simply encode the field names from the table below along with their corresponding values as query string parameters in the URL of your request. Here's an example that uses the city, state, and zipcode fields:

curl -v 'https://us-zipcode.api.smarty.com/lookup?
	auth-id=YOUR+AUTH-ID+HERE&
	auth-token=YOUR+AUTH-TOKEN+HERE&
	city=mountain+view&
	state=CA&
	zipcode=94035'

Please note that all query string parameter values must be url-encoded (spaces become + or %20, for example) to ensure that the data is transferred correctly. A common mistake we see is a non-encoded pound sign (#) like in an apartment number (# 409). This character, when properly encoded in a URL, becomes %23. When not encoded this character functions as the fragment identifier, which is ignored by our API servers.

HTTP POST: Multiple Inputs

A POST request allows a larger volume of data (MAX: 100 inputs or 16K per request) to be sent in the HTTP request body. In this case, the data should be encoded as a JSON array where each element in the array is a JSON object with field names identical to those in the field listing below. Here's a sample request with three inputs being sent:

curl -v 'https://us-zipcode.api.smarty.com/lookup?
			auth-id=YOUR+AUTH-ID+HERE&
			auth-token=YOUR+AUTH-TOKEN+HERE'
	-H "Content-Type: application/json; charset=utf-8"
	--data-binary '
	[
		{
			"city":"North Pole",
			"state":"AK"
		},
		{
			"zipcode":"12345"
		},
		{
			"city":"cupertino",
			"state":"CA",
			"zipcode":"95014"
		}
	]'

Note: When POSTing JSON, always make sure to add a Content-Type of application/json; charset=utf-8.

HTTP Request: Input Fields

All fields listed below are strings. The default value for each field (if not submitted) is an empty string.

Name Max Characters Description
city 64 The city name
state 32 State name or two-letter abbreviation
zipcode 16 The ZIP Code. See the paragraphs below this table for a few relevant details.
input_id 36 A unique identifier for this address used in your application; this field will be copied into the output.

ZIP Code Inputs

Keep in mind that a ZIP Code is not a number; it is simply a series of digits representing a delivery area. For instance, many ZIP Codes contain leading zeros (ie. 00501), but spreadsheet programs often interpret a series of digits as a number, causing leading zeros to be erroneously dropped. This API attempts to compensate for this behavior thereby increasing the chances of a match.

Another consequence of erroneous handling of ZIP Code data within spreadsheets and databases is that variations of 0 in the ZIP Code input field will be dropped when provided in combination with non-blank City and State inputs. Otherwise, a zero-value ZIP Code will be treated literally if no other data (city/state) is submitted, resulting in the status of the response being invalid_zipcode. Obviously, this could change in the future should the USPS address database provision an actual ZIP Code with a value of 00000.

HTTP Request: Headers

You must include the following required HTTP headers in all requests:

Header Description Example
Content-Type The purpose of the Content-Type field is to describe the data contained in the body fully enough that the receiving user agent can pick an appropriate agent or mechanism to present the data to the user, or otherwise deal with the data in an appropriate manner. Content-Type: application/json; charset=utf-8
Host The Host request header field specifies the internet host and port number of the resource being requested Host: us-zipcode.api.smarty.com

HTTP Response: Status Codes and Results

Responses will have a status header with a numeric value. This value is what you should check for when writing code to parse the response. The only response body that should be read and parsed is a 200 response.

Status Code Response and Explanation
401 Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.
402 Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.
413 Request Entity Too Large: The maximum size for a request body to this API is 16K (16,384 bytes).
400 Bad Request (Malformed Payload): The request body of a POST request contained no lookups or contained malformed JSON.
429 Too Many Requests: When using public embedded key authentication, we restrict the number of requests coming from a given source over too short of a time. If you use embedded key authentication, you can avoid this error by adding your IP address as an authorized host for the embedded key in question.
200 OK (success!): The response body will be a JSON array containing zero or more matches for the input provided with the request. The structure of the response is the same for both GET and POST requests.

JSON Response

Rather than writing your own code to parse the JSON response, we recommend using a tried and tested JSON parser that is specific for your programming language. There is a very comprehensive list of such tools (as well as the complete JSON specification) at json.org. Only non-blank fields will be returned.

Example Output

Input that doesn't yield a match is returned with a status and reason:

[
	{
		"input_index": 0,
		"status": "invalid_zipcode",
		"reason": "Invalid ZIP Code."
	}
]

Here is an example of the result of submitting valid input:

[
	{
		"input_index": 0,
		"city_states": [
			{
				"city": "Washington",
				"state_abbreviation": "DC",
				"state": "District of Columbia",
				"mailable_city": true
			}
		],
		"zipcodes": [
			{
				"zipcode": "20500",
				"zipcode_type": "S",
				"default_city": "Washington",
				"county_fips": "11001",
				"county_name": "District of Columbia",
				"state_abbreviation": "DC",
				"state": "District of Columbia",
				"latitude": 38.89769,
				"longitude": -77.03869,
				"precision": "Zip5"
			}
		]
	}
]

HTTP Response: Output Field Definitions

NOTE: Any returned fields that are not defined within this document should be considered experimental and may be changed or discontinued at any time without notice.

Root | city_states | zipcodes

Root

Name Description
input_index The positional index, or ordering, of the input that is associated with this result
input_id Any unique identifier that you used to reference the input address. The output will be identical to the input.
city_states A list of cities and their states that match the input
zipcodes A list of ZIP Codes that match the input
status For a lookup with no matches, status classifies the kind of failure and always comes with a reason
reason For a lookup with no matches, reason explains why the lookup failed

The following table has 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.

city_states

Name Description
city The name of the city
state_abbreviation The official, two-letter state abbreviation
state The state name
mailable_city A boolean value indicating whether or not the city name is an approved USPS mailing name

zipcodes

Name Description
zipcode The 5-digit ZIP Code
zipcode_type The type of ZIP Code. Possible values:
  • S - Standard (regular ZIP Code)
  • M - Military (APO/FPO military ZIP Code. Also includes DPO - Diplomatic addresses)
  • P - P.O. Box (serves only post-office boxes)
  • U - Unique (belongs primarily to a firm)
default_city A string containing the default city name for this ZIP Code
county_fips The county FIPS Code
county_name The name of the county in which the ZIP Code is located

Note: The county name listed here pertains to the 5-digit ZIP Code, not necessarily the city.
state_abbreviation The official, two-letter state abbreviation
state The state name
latitude The approximate latitude geo-coordinate
longitude The approximate longitude geo-coordinate
precision Indicates the precision of the latitude and longitude values.

None — Coordinates not known. Reasons could include: address is invalid, military address (APO or FPO), lat/lon coordinates not available.
Zip5 — Accurate to a 5-digit ZIP Code level (least precise)
Zip6 — Accurate to a 6-digit ZIP Code level
Zip7 — Accurate to a 7-digit ZIP Code level
Zip8 — Accurate to an 8-digit ZIP Code level
Zip9 — Accurate to a 9-digit ZIP Code level (most precise but NOT rooftop level)

alternate_counties The county FIPS codes, county names, state abbreviations, and states, that share the same ZIP Code.

Example Input: zipcode=42223
Example Output:
"alternate_counties": [
	{
		"county_fips":"21047",
		"county_name":"Christian",
		"state_abbreviation":"KY",
		"state":"Kentucky"
	},
	{
		"county_fips":"47125",
		"county_name":"Montgomery",
		"state_abbreviation":"TN",
		"state":"Tennessee"
	}
]

Note: The county names listed here pertain to the 5-digit ZIP Code, not necessarily the city.

The results returned by the ZIP Code API vary greatly depending on the combination of input fields that are submitted. (The input_id field is an exception; it is simply a pass-through value and never meaningfully changes the output.)

There are three valid input field combinations (not including the optional input_id field):

  1. zipcode
  2. city + state
  3. city + state + zipcode

In the case of valid ZIP Code input, the result will include metadata about the ZIP Code (including latitude and longitude coordinates) along with a listing of City + State combinations that belong with that ZIP Code. In the case of City + State inputs, the result will be the inverse (metadata for the City + State input and a listing of ZIP Codes that belong with that City + State). When a valid combination of all three fields is submitted the result will consist of separate metadata for the City + State and the ZIP Code as confirmation of all three input fields.

Allowed inputs, along with the corresponding results for valid input values, are enumerated in the table below.

Input Combination Output Explanation
ZIP Code Schema:
Example Input: zipcode=90023
Example Output:
[
	{
		"city_states": [
			{
				"city": "Los Angeles",
				"state_abbreviation": "CA",
				"state": "California",
				"mailable_city": true
			},
			{
				"city": "Commerce",
				"state_abbreviation": "CA",
				"state": "California",
				"mailable_city": true
			},
			{
				"city": "Lugo",
				"state_abbreviation": "CA",
				"state": "California",
				"mailable_city": false
			}
		],
		"zipcodes": [
			{
				"zipcode": "90023",
				"zipcode_type": "S",
				"default_city": "Los Angeles",
				"county_fips": "06037",
				"county_name": "Los Angeles",
				"state_abbreviation": "CA",
				"state": "California",
				"latitude": 34.02425,
				"longitude": -118.20399,
				"precision": "Zip5"
			}
		]
	}
]
City + State Schema:
  • Metadata for the input City + State combination.
  • A listing of corresponding ZIP Code combinations.
Example Input: city=commerce&state=CA
Example Output:
[
	{
		"city_states": [
			{
				"city": "Commerce",
				"state_abbreviation": "CA",
				"state": "California",
				"mailable_city": true
			}
		],
		"zipcodes": [
			{
				"zipcode": "90022",
				"zipcode_type": "S",
				"default_city": "Los Angeles",
				"county_fips": "06037",
				"county_name": "Los Angeles",
				"state_abbreviation": "CA",
				"state": "California",
				"latitude": 34.02335,
				"longitude": -118.15579,
				"precision": "Zip5"
			},
			{
				"zipcode": "90023",
				"zipcode_type": "S",
				"default_city": "Los Angeles",
				"county_fips": "06037",
				"county_name": "Los Angeles",
				"state_abbreviation": "CA",
				"state": "California",
				"latitude": 34.02425,
				"longitude": -118.20399,
				"precision": "Zip5"
			},
			{
				"zipcode": "90040",
				"zipcode_type": "S",
				"default_city": "Los Angeles",
				"county_fips": "06037",
				"county_name": "Los Angeles",
				"state_abbreviation": "CA",
				"state": "California",
				"latitude": 33.99506,
				"longitude": -118.15206,
				"precision": "Zip5"
			},
			{
				"zipcode": "90091",
				"zipcode_type": "P",
				"default_city": "Los Angeles",
				"county_fips": "06037",
				"county_name": "Los Angeles",
				"state_abbreviation": "CA",
				"state": "California",
				"latitude": 33.99917,
				"longitude": -118.15672,
				"precision": "Zip5"
			}
		]
	}
]
City + State + ZIP Code Schema:
  • Metadata for the input City + State combination.
  • Metadata for the input ZIP Code (including latitude and longitude).
Example Input: city=commerce&state=CA&zipcode=90023
Example Output:
[
	{
		"city_states":[
			{
				"city":"Commerce",
				"state_abbreviation":"CA",
				"state":"California",
				"mailable_city":true
			}
		],
		"zipcodes":[
			{
				"zipcode":"90023",
				"zipcode_type":"S",
				"default_city":"Los Angeles",
				"county_fips":"06037",
				"county_name":"Los Angeles",
				"state_abbreviation":"CA",
				"state":"California",
				"latitude":34.02425,
				"longitude":-118.20399,
				"precision":"Zip5"
			}
		]
	}
]

SSL/TLS Information

Use modern security software and cipher suites.

Ready to get started?