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.
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 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 "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 InputTo 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 InputsA 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 POST
ing JSON, always make sure to add a Content-Type
of application/json
.
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. |
You must include the following required HTTP headers in all 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: us-zipcode.api.smartystreets.com |
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. |
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.
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"
}
]
}
]
Root | city_states | zipcodes
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. |
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 |
Name | Description |
---|---|
zipcode | The 5-digit ZIP Code |
zipcode_type | The type of ZIP Code. Possible values:
|
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:
|
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):
zipcode
city
+ state
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:
Example Input: zipcode=90023 Example Output:
|
City + State | Schema:
city=commerce&state=CA Example Output:
|
City + State + ZIP Code | Schema:
city=commerce&state=CA&zipcode=90023 Example Output:
|
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