US ZIP Code API

This page describes how to look up and verify city, state, and ZIP Code combinations using the SmartyStreets APIs. We also provide a simple, non-technical 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. Input Field Combination --> Output Schema
    2. SSL/TLS Information
    3. Try the demo

HTTP Request: URL Composition

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

https://us-zipcode.api.smartystreets.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.smartystreets.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 "Website 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.smartystreets.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.smartystreets.com/lookup?
			auth-id=YOUR+AUTH-ID+HERE&
			auth-token=YOUR+AUTH-TOKEN+HERE'
	-H "Content-Type: application/json"
	--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.

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
input_id 36 A unique identifier for this address used in your application; this field will be copied into the output.

HTTP Request: Headers

You must include the following required HTTP headers in POST 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
Host The Host request header field specifies the internet host and port number of the resource being requested Host: api.smartystreets.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 "website key" authentication, we restrict the number of requests coming from a given source over too short of a time. If you use "website key" authentication, you can avoid this error by adding your IP address as an authorized host for the website 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.

Example Output

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

{
	"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

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)
  • 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
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.

Unknown — Coordinates not known, possibly because input is invalid
None — Coordinates are not provided for the input. Military ZIP Codes do not provide coordinates.
State — Reserved for future use
SolutionArea — Reserved for future use
City — Reserved for future use
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)
Structure — Reserved for future use

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"
	}
]

Input Field Combinations --> Output Schemas

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:

  • A listing of corresponding City + State combinations.
  • Metadata for the input ZIP Code (including latitude and longitude coordinates).

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"
			}
		]
	}
]
Input Combination Output Explanation
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"
			}
		]
	}
]
Input Combination Output Explanation
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
Certificate Authority:
	AddTrust External CA Root
	Fingerprint: 02faf3e291435468607857694df5e45b68851868

Supported Protocols:
	TLS 1.2
	TLS 1.1
	TLS 1.0

Cipher Suites:
	TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256
	TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
	TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
	TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
	TLS_RSA_WITH_AES_128_GCM_SHA256
	TLS_RSA_WITH_AES_256_GCM_SHA384
	TLS_RSA_WITH_AES_128_CBC_SHA256
	TLS_RSA_WITH_AES_128_CBC_SHA
	TLS_RSA_WITH_AES_256_CBC_SHA256
	TLS_RSA_WITH_AES_256_CBC_SHA


Product Features Demo Pricing Help Company Documentation Articles Contact Customers Legal Stuff