City, State, ZIP

This page describes how to look up and verify city, state, and ZIP Code combinations. All requests on this page are at the same base URL:

api.smartystreets.com

Contents

  1. One lookup
  2. Multiple lookups
  3. Response
  4. Output fields

One lookup

GET /zipcode

Parameters

Each combination of city/state or ZIP is accepted, except for city alone.

Name Description
city The city name
state State name or abbreviation
zipcode The 5-digit ZIP Code
input_id A unique identifier for this address used in your application; this field will be copied into the output

Sample request

GET /zipcode?city=Los+Angeles&state=CA&zipcode=90023&input_id=hi+there&auth-id=example1234&auth-token=demo5678 HTTP/1.1
Host: api.smartystreets.com

Multiple lookups

POST /zipcode

You may submit up to 100 lookups per request.

Request body

This sample batch request uses five lookups on your subscription:

[
	{
		"zipcode": "20500"
	},
	{
		"city": "Cupertino",
		"state": "CA"
	},
	{
		"city": "Cupertino",
		"state": "CA",
		"zipcode": "95014"
	},
	{
		"city": "Does not exist",
		"state": "CA"
	},
	{
		"input_id": "Apple",
		"city": "Cupertino",
		"state": "ca",
		"zipcode": "90210"
	}
]

Any field described in the parameters above can be used in your POST requests.

Sample request

POST /zipcode?auth-id=example1234&auth-token=demo5678 HTTP/1.1
Host: api.smartystreets.com
Content-Type: application/json

[
	{
		"input_id": "zipcode-only",
		"zipcode": "20500"
	},
	{
		"input_id": "city/state",
		"city": "Cupertino",
		"state": "CA"
	}
]

Response

Every response is a JSON array containing one object for each lookup you submitted. For example, the sample request above yields this output:

[
	{
		"input_index": 0,
		"input_id": "zipcode-only",
		"city_states": [
			{
				"city": "Washington",
				"state_abbreviation": "DC",
				"state": "District of Columbia",
				"mailable_city": true
			}
		],
		"zipcodes": [
			{
				"zipcode": "20500",
				"zipcode_type": "S",
				"county_fips": "11001",
				"county_name": "District of Columbia",
				"latitude": 38.89769,
				"longitude": -77.03869
			}
		]
	},
	{
		"input_index": 1,
		"input_id": "city/state",
		"city_states": [
			{
				"city": "Cupertino",
				"state_abbreviation": "CA",
				"state": "California",
				"mailable_city": true
			}
		],
		"zipcodes": [
			{
				"zipcode": "95014",
				"zipcode_type": "S",
				"county_fips": "06085",
				"county_name": "Santa Clara",
				"latitude": 37.32056,
				"longitude": -122.03866
			},
			{
				"zipcode": "95015",
				"zipcode_type": "P",
				"county_fips": "06085",
				"county_name": "Santa Clara",
				"latitude": 37.32292,
				"longitude": -122.05415
			}
		]
	}
]

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

{
	"status": "invalid_zipcode",
	"reason": "Invalid ZIP Code."
}

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.

Output fields

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

city_states

Name Description
city The name of the city
mailable_city A boolean value indicating whether or not the city name is an approved USPS mailing name
default_city A boolean value indicating whether or not the city name is the default name for the corresponding ZIP Code
state_abbreviation The official, two-letter state abbreviation
state The state 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)
county_fips The county FIPS code
county_name The name of the county
latitude The approximate latitude geo-coordinate
longitude The approximate longitude geo-coordinate

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