City, State, ZIP

This page describes how to look up and verify city, state, and ZIP Code combinations.

Contents

  1. Input fields
  2. Single lookup
  3. Multiple lookups
  4. Response
  5. Output fields

Input fields

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

Single lookup

To submit one lookup at a time, a simple HTTPS GET request is all you need.

curl -v 'https://api.smartystreets.com/zipcode?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE&
	city=Los+Angeles&
	state=CA&
	zipcode=90023'

Multiple lookups

In order to submit multiple addresses at a time (MAX: 100 addresses per request) you can use an HTTPS POST request.

curl -v 'https://api.smartystreets.com/zipcode?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE' --data-binary '
[
	{
		"zipcode":"20500"
	},
	{
		"city":"cupertino",
		"state":"CA"
	},
	{
		"input_id":"228",
		"city":"cupertino",
		"state":"CA",
		"zipcode":"90210"
	}		
]'

Response

Every response is a JSON array containing zero or more objects for each lookup you submitted. If none of the submitted lookups validate, the array is empty []. The structure is the same whether you use GET or POST requests.

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

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

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

Output fields

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