Introduction

The US States API provides you access to detailed and accurate information for all 50 US states, 5 territories and 1 federal district.

Data

The US States API provides an extremely detailed data. Data is continuously monitored for accuracy and updated accordingly.
Available information:

Name
Postal Abbreviation
Capital (includes name and lat/lon)
Date of Statehood
Population
Nickname
FIPS code
Demonym
Top 5 Cities (by population)
Lowest Geographic Point
Highest Geographic Point
Elevation: Max (m), Max (ft), Min (m), Min (ft), Span (m), Span (ft), Mean (m), Mean (ft), Mean Rank, Max Rank
Area: Total, Land, and Water Area in sq mi and sq km. Total, Land, and Water Area Rank. Water Percent.
Websiter
Per Capita Income
Median Household Income
Status
Other Nicknames
OMB Federal Region
Census Bureau Region and Division
AP Abbreviation
GPO Abbreviation
Number of Representatives
Time Zones
Koppen Climate Regions
Motto
Symbols
Subdivisions

Sample Response

[
    {
        "name": "Connecticut",
        "postal": "CT",
        "capital": {
            "name": "Hartford",
            "latitude": "41.764046",
            "longitude": "-72.682198"
        },
        "date": "Jan 9, 1788",
        "population": {
            "density_km": "286",
            "total": "3605944",
            "density_mi": "741"
        },
        "nickname": "Constitution State",
        "fips": "09",
        "demonym": "Connecticuter",
        "cities": [
            {
                "name": "Bridgeport",
                "population": "144900"
            },
            {
                "name": "New Haven",
                "population": "130418"
            },
            {
                "name": "Stamford",
                "population": "129775"
            },
            {
                "name": "Hartford",
                "population": "122587"
            },
            {
                "name": "Waterbury",
                "population": "108093"
            }
        ],
        "lowest_point": "Long Island Sound",
        "highest_point": "Massachusetts border on the southern slope of Mount Frissell",
        "elevation": {
            "min_ft": "sea level",
            "min_m": "sea level",
            "mean_ft": "500",
            "max_rank": "39",
            "max_ft": "2379",
            "span_ft": "2379",
            "mean_rank": "43",
            "span_m": "725",
            "mean_m": "150",
            "max_m": "725"
        },
        "area": {
            "total_mi": "5543.41",
            "land_rank": "48",
            "land_km": "12542",
            "water_rank": "40",
            "total_rank": "48",
            "land_mi": "4842.36",
            "water_km": "1816",
            "total_km": "14357",
            "land_percent": "87.35",
            "water_mi": "701.06",
            "water_percent": "12.65"
        },
        "website": "https://portal.ct.gov/",
        "per_capita_income": "$39,373 ",
        "median_household_income": "$76,348 ",
        "status": "state",
        "other_nicknames": [
            "Arsenal of the Nation",
            "Land of Steady Habits",
            "Nutmeg State",
            "Provisions State"
        ],
        "standard_federal_region": "Region I",
        "census_bureau": {
            "region": "Northeast",
            "division": "New England"
        },
        "ap_abbreviation": "Conn.",
        "gpo_abbreviation": "Conn.",
        "representatives": "5",
        "time_zones": [
            "EST"
        ],
        "koppen_climate": [
            "Dfb",
            "Dba",
            "Cfb",
            "Cfa"
        ],
        "motto": "Qui transtulit sustinet",
        "symbols": {
            "song": "Yankee Doodle",
            "tartan": "Connecticut State Tartan",
            "tree": "Charter Oak",
            "folk dance": "Square Dance",
            "hero": "Nathan Hale",
            "fossil": "Eubrontes Giganteus",
            "flower": "Mountain Laurel",
            "shellfish": "Eastern Oyster",
            "children's flower": "Michaela Petit's Four-O'Clocks",
            "bird": "American Robin",
            "fish": "American Shad",
            "insect": "European Mantis",
            "heroine": "Prudence Crandall",
            "dinosaur": "Dilophosaurus",
            "mineral": "Garnet",
            "polka": "Ballroom Polka"
        },
        "subdivisions": [
            "Fairfield",
            "Hartford",
            "Litchfield",
            "Middlesex",
            "New Haven",
            "New London",
            "Tolland",
            "Windham"
        ]
    }
]

Pricing Plans and Usage

Basic - This plan is suited for developers who want to try out the API for building apps or websites.
Pro - This plan is suited for small, personal apps or websites needing basic state data for occasional use.
Ultra - This plan provides full state details suited for heavier commercial usage. Quicker support is provided with this plan.
Mega - This is an enterprise-level plan suited for heavy usage of full state details. Custom endpoints can be provided for customers on this plan. Access to metadata is also available.

Endpoints (all endpoints are GET methods)

/basic
/all
/name
/capital
/abbreviation
/fips
/region
/division
/subdivisions
/symbols
/timezone
/metadata

Path Parameters

The following endpoints allow path parameters to directly access a specific state or a subset of states: /abbreviation /fips /region /division /timezone
Multiple parameters can be sent together separated by commas.
Examples:
/abbreviation/CA -> returns state data for California
/abbreviation/FL,GU -> returns state data for Florida and Guam
/fips/04,32 -> returns state data for Arizona and Nevada
/region/South -> returns data for all states in the census bureau South region
/division/Mountain,Pacific -> returns data for all states in the census bureau Mountain and Pacific divisions
/timezone/EST,PST -> returns all states found in Eastern Standard Time and Pacific Standard Time Zones

The following endpoints allow a single path parameter to directly access a subset of state /symbols /subdivisions
Examples:
/symbols/WV -> returns all state symbols for West Virginia
/subdivisions/LA-> returns all subdivisions for Louisiana

The following endpoints allow path parameters in the form of search strings (either full or partial): /name /capital
Examples:
/name/south -> returns data for South Carolina and South Dakota
/capital/char -> returns all states with substring ‘char’ in the capital name: Charlotte Amalie (U.S. Virgin Islands), Charleston (West Virginia)

Query String Parameters

Query string parameters can be used to filter and sort results (limited to /all endpoint).

sort=key:asc
Sort results based on the provided key field and direction indicator (‘asc’ or ‘desc’). Only root-level keys can be used for sorting.
Example:
/all?sort=name:desc (sort response by name descending)

limit=limit_value
Indicate the (maximum) number of records to return in the response. If no limit is provided, all records matching the request will be returned. (Note: sort parameter is evaluated before limit parameter.)
Example:
/all?limit=5 (return at most 5 records in response)

fields=field1,field2,field3,field4
Return only the fields identified in the comma-separated list.
Example:
/all?fields=name,postal,capital (return only Name, Postal Abbreviation, and Capital fields in response)

randomize=true
Return the result set in random order. This feature can be useful for quiz or game apps.
Example:
/all?limit=1&fields=name&randomize=true (this example returns a single, random state name and nothing more)

Metadata

In some cases it can be very beneficial to access information about the data contained in our API. For the MEGA plan, we provide an endpoint that provides such information.

valueList
During website or mobile app development, you may require values for drop down boxes or filtering. Rather than store these items yourself and risk having outdated data, you can access the /metadata endpoint with the valueList parameter to retrieve value lists. Fields linked to this parameter include:
Name (parameter=‘name’)
Capital (parameter=‘capital’)
USPS Abbreviation (parameter=‘abbreviation’)
AP Abbreviation (parameter=‘ap_abbreviation’)
Census Bureau Region (parameter=‘region’)
Census Bureau Division (parameter=‘division’)
Time Zone (parameter=‘timezone’)

Example:
/metadata?valueList=division
Result:

[
    "East North Central",
    "East South Central",
    "Mid-Atlantic",
    "Mountain",
    "New England",
    "Pacific",
    "South Atlantic",
    "West North Central",
    "West South Central"
]

Example:
/metadata?valueList=abbreviation
Result:

[
    "AK",
    "AL",
    "AR",
    "AS",
    "AZ",
    "CA",
    "CO",
    "CT",
    "DC",
    "DE",
    "FL",
    "GA",
    "GU",
    "HI",
    "IA",
    "ID",
    "IL",
    "IN",
    "KS",
	...
]

Errors

400 - Invalid Request (you have specified an invalid resource or not supplied appropriate path parameters)
401 - Unauthorized (you are not authorized to use the specified endpoint)
404 - Value Not Found (the path parameter(s) provided could not be found)

Please Note

All response data is provided in string format for easy and consistent usage.
Field order in response is not guaranteed or preserved.
By default, response items are sorted by state name ascending unless other sort criteria is provided.
In order to make our API data ever-evolving, new fields could be added at any time.

Related API

If you’re looking for detailed US County data, we have an API dedicated to that. Check it out here: https://rapidapi.com/aptitudeapps/api/us-counties

Thank you

We strive to provide the most up-to-date data available. If for any reason you notice data discrepancies, please contact us immediately so we can resolve them.
https://aptitudeapps.com/index.php/statesv1/