Introduction

The US Counties API provides you access to detailed and accurate information for all U.S. counties and county equivalents recognized by the U.S. Census Bureau. There are currently 3,143 counties recognized by the U.S. Census Bureau. In the United States, a county is an administrative or political subdivision of a state that consists of a geographic region with specific boundaries and usually some level of governmental authority. The term “county” is used in 48 U.S. states, while Louisiana and Alaska have functionally equivalent subdivisions called parishes and boroughs, respectively. The Census Bureau uses the term “county equivalent” to describe places that are comparable to counties, but called by different names. Louisiana parishes, the organized boroughs of Alaska, independent cities, and the District of Columbia are equivalent to counties for administrative purposes. Alaska’s Unorganized Borough is further divided into 11 census areas that are statistically equivalent to counties.
Note: Territories of the United States are not included in this API.

Data

The US Counties API provides a detailed data set for all U.S. Census Bureau “counties” and “county equivalents.” Data is continuously monitored for accuracy and updated accordingly.

Two distinct data sets are available in the US Counties API: State-level data and County-level data

State-level

Name
Abbreviation
Date
Capital
FIPS
Subdivisions
Population: Total, Density (km²), Density (mi²)
Area: mi², km²
Status

County-level

Name
Type
State
Abbreviation
Established
Seat
FIPS
Population: Total, Density (km²), Density (mi²)
Area: mi², km²
Etymology
Median Household Income

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 county data for occasional use.
Ultra - This plan provides full county 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 county details. Custom endpoints can be provided for customers on this plan. Access to metadata is also available.

Endpoints (all endpoints are GET methods)

State-level Data
/states -> returns a list of objects containing state-level data for all 50 states and Washington, D.C.
/state/XX -> returns an object of state level data for the state abbreviation provided in the path parameter ‘XX’

Sample Response for State-level Data

[
    {
        "name": "Ohio",
        "abbreviation": "OH",
        "date": "1816",
        "capital": "Columbus",
        "fips": "39",
        "subdivisions": "88",
        "population": "11,799,448",
        "area_mi": "44,826",
        "area_km": "116,098",
        "density_mi": "263.23",
        "density_km": "101.63",
        "status": "state"
    }
]

Basic County-level Data
/basic/XX -> returns a list of objects containing basic county-level data for the state abbreviation provided in the path parameter ‘XX’
/summary -> returns a list of objects containing basic county-level data for all counties and county equivalents (CAUTION: this is a large data set)

Sample Response for Basic County-level Data

[
    {
        "state": "Georgia",
        "abbreviation": "GA",
        "name": "Baldwin",
        "type": "county"
    }
]

Detailed County-level Data
/detail/XX -> returns a list of objects containing detailed county-level data for the state abbreviation provided in the path parameter ‘XX’
/full -> returns a list of objects containing detailed county-level data for all counties and county equivalents (CAUTION: this is a large data set)
/equivalents -> returns a list of objects containing detailed county-level data for all U.S. Census Bureau county equivalents

Sample Response for Detailed County-level Data

[
    {
        "name": "Beadle",
        "type": "county",
        "state": "South Dakota",
        "abbreviation": "SD",
        "established": "1879",
        "seat": "Huron",
        "fips": "005",
        "population": "19,149",
        "area_mi": "1,259",
        "area_km": "3,261",
        "density_mi": "15.21",
        "density_km": "5.87",
        "etymology": "William Henry Harrison Beadle, chief surveyor of Dakota Territory",
        "median_household_income": "$51,844 "
    }
]

Top 100 Lists
This endpoint can be used to get top 100 lists of several demographic categories. Response format will vary depending on list chosen.
Examples:
/top100?list=largest -> returns a list the largest counties by area in descending order
/top100?list=smallest -> returns a list the smallest counties by area in ascending order
/top100?list=most_populated -> returns a list the most populated counties in descending order
/top100?list=least_populated -> returns a list the least populated counties in ascending order
/top100?list=most_dense -> returns a list of the most densely populated counties in descending order
/top100?list=least_dense -> returns a list of the least densely populated counties in ascending order
/top100?list=richest -> returns a list of the richest counties by median household income in descending order
/top100?list=poorest -> returns a list of the poorest counties by median household income in ascending order

Demographic Overview
/stats/XX -> returns demographic county overview for the state abbreviation provided in the path parameter ‘XX’

Sample Response for Demographic Overview

[
    {
        "state": "Texas",
        "abbreviation": "TX",
        "subdivisions": "254",
        "average sq mi": "1,031.35",
        "average sq km": "2,671.16",
        "largest": {
            "name": "Brewster",
            "type": "county",
            "area sq mi": "6,193",
            "area sq km": "16,040"
        },
        "smallest": {
            "name": "Rockwall",
            "type": "county",
            "area sq mi": "149",
            "area sq km": "386"
        },
        "most populated": {
            "name": "Harris",
            "type": "county",
            "population": "4,731,145"
        },
        "least populated": {
            "name": "Loving",
            "type": "county",
            "population": "64"
        },
        "most dense": {
            "name": "Dallas",
            "type": "county",
            "density sq mi": "2,969.93",
            "density sq km": "1,146.79"
        },
        "least dense": {
            "name": "Loving",
            "type": "county",
            "density sq mi": "0.10",
            "density sq km": "0.04"
        },
        "highest median household income": {
            "name": "Rockwall",
            "type": "county",
            "median household income": "$105,763 "
        },
        "lowest median household income": {
            "name": "Brooks",
            "type": "county",
            "median household income": "$31,410 "
        }
    }
]

Value Lists
The /metadata endpoint will accept a ‘valueList’ query string parameter to build value lists from the state and county data sets. This endpoint can be useful for website or mobile app building.

Example: Get a list of state names
/metadata?valueList=states
Result:

[
    "Alabama",
    "Alaska",
    "Arizona",
    "Arkansas",
    "California",
    "Colorado",
    "Connecticut",
    "Delaware",
    "District of Columbia",
    "Florida",
    "Georgia",
    "Hawaii",
    "Idaho",
    ...
]

Example: Get a list of county names for Rhode Island
/metadata?valueList=name&state=RI
Result:

[
    "Bristol",
    "Kent",
    "Newport",
    "Providence",
    "Washington"
]

Example: Get a list of county seat names for Massachusetts
/metadata?valueList=seat&state=MA
Result:

[
    "Barnstable",
    "Boston",
    "Brockton, Plymouth",
    "Dedham",
    "Edgartown",
    "Greenfield",
    "Lowell, Cambridge",
    "Nantucket",
    "Northampton",
    "Pittsfield",
    "Salem, Lawrence",
    "Springfield",
    "Taunton",
    "Worcester"
]

You may get value lists for ‘states’, ‘capitals’, and ‘postal’ without the state parameter.
You may get value lists for ‘name’, ‘seat’, and ‘fips’ with the state parameter.
Please contact us if you have any difficulty using the metadata endpoint.

Query String Parameters

Query string parameters can be used to filter and sort results. Endpoints are listed below with query string parameters that can be used for each followed by usage and examples.
/states : sort, limit, fields, randomize parameters are available
/state/XX : fields parameter is available
/basic/XX : limit, sort, randomize parameters are available
/summary : limit, sort, randomize parameters are available
/detail/XX : sort, limit, fields, randomize parameters are available
/full : sort, limit, fields, randomize parameters are available
/equivalents : sort, limit, fields, randomize parameters are available
/top100 : limit parameter is available
/stats/XX : no parameters are available

sort=key:asc
Sort results based on the provided key field and direction indicator (‘asc’ or ‘desc’). If key field is provided without sort direction, default sort order is ascending.
Example:
/states?sort=name:asc (sort response by state name ascending)

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:
/full?limit=50 (return at most 50 records in response)

fields=field1,field2,field3
Return only the fields identified in the comma-separated list.
Example:
/detail/PA?fields=name,seat (return county name and county seat for all counties in Pennsylvania)

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

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 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.
In order to make our API data ever-evolving, new fields could be added at any time.

Related API

To compliment our US County data, we also have an API with much more US State detail. Check it out here: https://rapidapi.com/aptitudeapps/api/us-states

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