US ZIP Code API

This page describes how to look up and verify city, state, and ZIP Code combinations using the Smarty 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 live API

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:

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:

• GET (for sending a single input)
• POST (for sending multiple inputs)
• OPTIONS (for "pre-flight" cross-domain requests)

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.

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:

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.

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

The following table has possible statuses and their reasons:

city_states

zipcodes

"alternate_counties": [
	{
		"county_fips":"21047",
		"county_name":"Christian",
		"state_abbreviation":"KY",
		"state":"Kentucky"
	},
	{
		"county_fips":"47125",
		"county_name":"Montgomery",
		"state_abbreviation":"TN",
		"state":"Tennessee"
	}
]

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.

[
	{
		"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_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_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.