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 ComponentsValuesNotes
SchemehttpsNOTE: non-secure http requests are not supported
Hostnameus-zipcode.api.smartystreets.com
Path/lookupNOTE: There is no trailing slash!
Query String?auth-id=123&auth-token=abcAuthentication 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.

NameMax CharactersDescription
city64The city name
state32State name or two-letter abbreviation
zipcode16The ZIP Code
input_id36A 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 all requests:

HeaderDescriptionExample
Content-TypeThe 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
HostThe Host request header field specifies the internet host and port number of the resource being requestedHost: us-zipcode.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 CodeResponse and Explanation
401Unauthorized: The credentials were provided incorrectly or did not match any existing, active credentials.
402Payment Required: There is no active subscription for the account associated with the credentials submitted with the request.
413Request Entity Too Large: The maximum size for a request body to this API is 16K (16,384 bytes).
400Bad Request (Malformed Payload): The request body of a POST request contained no lookups or contained malformed JSON.
429Too 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.
200OK (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

NameDescription
input_indexThe positional index, or ordering, of the input that is associated with this result
input_idAny unique identifier that you used to reference the input address. The output will be identical to the input.
city_statesA list of cities and their states that match the input
zipcodesA list of ZIP Codes that match the input
statusFor a lookup with no matches, status classifies the kind of failure and always comes with a reason
reasonFor a lookup with no matches, reason explains why the lookup failed

The following table has possible statuses and their reasons:

StatusReason
blankBlank lookup (you must provide a ZIP Code and/or City/State combination).
invalid_stateInvalid State name or abbreviation.
invalid_cityInvalid City for the given State.
invalid_zipcodeInvalid ZIP Code.
conflictConflicting ZIP Code/City/State information.

city_states

NameDescription
cityThe name of the city
state_abbreviationThe official, two-letter state abbreviation
stateThe state name
mailable_cityA boolean value indicating whether or not the city name is an approved USPS mailing name

zipcodes

NameDescription
zipcodeThe 5-digit ZIP Code
zipcode_typeThe 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_cityA string containing the default city name for this ZIP Code
county_fipsThe county FIPS code
county_nameThe name of the county
state_abbreviationThe official, two-letter state abbreviation
stateThe state name
latitudeThe approximate latitude geo-coordinate
longitudeThe approximate longitude geo-coordinate
precisionIndicates 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_countiesThe 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 CombinationOutput 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 CombinationOutput 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 CombinationOutput 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