City State ZIP Lookup

The City State ZIP Lookup API allows you to verify if a given combination of city, state, and ZIP code is valid in the United States. This endpoint is particularly useful for validating address components individually or finding valid ZIP codes for a city/state combination.

The city state zip lookup model

The city/state/zip lookup model returns comprehensive information about the geographic location, including official and preferred city names, county information, and matching ZIP codes.

City State ZIP Lookup Properties

Name
original_request
Type
OriginalCityStateZipRequest
Description
The original lookup request parameters.
Name
lookup_status
Type
string
Description
Status of the lookup: ADDRESS_FOUND, ADDRESS_NOT_FOUND
Name
city_state_matches
Type
array
Description
Array of matching cites (CityStateMatch)
Name
zip_code_matches
Type
array
Description
Array of matching ZIP codes (ZipMatch)

OriginalCityStateZipRequest Properties

Name
city
Type
string
Description
City
Name
state
Type
string
Description
State
Name
zip_code
Type
string
Description
ZIP code

CityStateMatch Properties

Name
city_name
Type
string
Description
City
Name
state
Type
string
Description
State

ZipMatch Properties

Name
city_name
Type
string
Description
Official city name for this ZIP code
Name
preferred_city_name
Type
string
Description
Preferred city name for this ZIP code
Name
state
Type
string
Description
State abbreviation
Name
zip_code
Type
string
Description
The ZIP code
Name
zip_add_on_no
Type
string
Description
ZIP+4 add-on number (if available)
Name
county_name
Type
string
Description
County name for this ZIP code
Name
county_no
Type
string
Description
County number
Name
accuracy_level
Type
string
Description
Accuracy level of the match: ZIP_PLUS4, ZIP5

GET/v1/addresses/city-state-zip

Lookup city state zip

This endpoint verifies if a given combination of city, state, and ZIP code is valid in the US. You can provide any combination of these parameters to get matching results.

Optional parameters

Name
city
Type
string
Description
Name of the city to verify.
Name
state
Type
string
Description
The two-letter abbreviation or full name of US state.
Name
zip_code
Type
string
Description
The ZIP code to verify.

Request

GET

/v1/addresses/city-state-zip

curl https://us-address.addressfully.com/address-lookup/v1/addresses/city-state-zip \
    -H "Authorization: Bearer {api_key}" \
    -G \
    -d "city=San Francisco" \
    -d "state=CA" \
    -d "zip_code=94105"

Response

{
    "original_request": {
        "city": "San Francisco",
        "state": "CA",
        "zip_code": "94105"
    },
    "lookup_status": "ADDRESS_FOUND",
    "city_state_matches": [
        {
            "city_name": "SAN FRANCISCO",
            "state": "CA"
        }
    ],
    "zip_code_matches": [
        {
            "city_name": "SAN FRANCISCO",
            "preferred_city_name": "SAN FRANCISCO",
            "state": "CA",
            "zip_code": "94105",
            "zip_add_on_no": "",
            "county_name": "SAN FRANCISCO",
            "county_no": "075",
            "accuracy_level": "ZIP5"
        }
    ]
}