FIPS API Documentation

Your guide to using the FIPS County Code API.

Base URL

All API endpoints are relative to the following base URL:

https://api.fips.codes/

Data Shapes

The API returns data in two main shapes depending on the endpoint.

1. County-Specific Data (for /counties routes)

When querying for specific states or counties using the /counties endpoint, the response for a single county record (or an array of these records) will be in the following JSON format:

{
  "stateAbbrev": "AL",
  "state": "ALABAMA",
  "stateFips": "01",
  "county": "BIBB COUNTY",
  "fips": "01007"
}
  • stateAbbrev: The 2-letter abbreviation for the state.
  • state: The full name of the state.
  • stateFips: The 2-digit FIPS code for the state.
  • county: The full name of the county.
  • fips: The 5-digit FIPS code for the county (combining state and county codes).

2. All States Data (for /index route)

The /index route returns a single JSON object. Each key in this object is a state abbreviation. The value for each state key is an object containing state metadata (_name, _fips, _abbrev) and then a series of key-value pairs where the key is the county name and the value is its FIPS code.

{
  "AL": {
    "_name": "Alabama",
    "_fips": "01",
    "_abbrev": "AL",
    "Autauga County": "01001",
    "Baldwin County": "01003",
    "Bibb County": "01007",
    "Chambers County": "01017",
    "Cherokee County": "01019"
    // ... other counties in Alabama
  },
  "AK": {
    "_name": "Alaska",
    "_fips": "02",
    "_abbrev": "AK",
    "Aleutians East Borough": "02013",
    // ... other boroughs/census areas in Alaska
  }
  // ... other states
}

API Endpoints

Retrieve All FIPS County Codes (Grouped by State)

Provides a single JSON object containing all FIPS county codes, grouped by state. Each state entry includes state metadata and a list of its counties with their respective FIPS codes. Refer to "Data Shapes - All States Data" for the response structure.

GET/index

Parameters:

None.

Example Response (Success 200):

{
  "AL": {
    "_name": "Alabama",
    "_fips": "01",
    "_abbrev": "AL",
    "Autauga County": "01001",
    "Baldwin County": "01003",
    "Barbour County": "01005",
    "Bibb County": "01007",
    "Blount County": "01009",
    "Bullock County": "01011",
    "Butler County": "01013",
    "Calhoun County": "01015",
    "Chambers County": "01017",
    "Cherokee County": "01019",
    "Chilton County": "01021",
    "Choctaw County": "01023",
    "Clarke County": "01025",
    "Clay County": "01027",
    "Cleburne County": "01029",
    "Coffee County": "01031"
    // ... etc. for all counties in Alabama
  },
  "AK": {
    // ... Alaska data
  }
  // ... other states
}

Retrieve FIPS Codes for a Specific State

Fetches all FIPS county codes for a given state name. The response is an array of county objects. Refer to "Data Shapes - County-Specific Data" for the response structure of each item in the array.

GET/counties?state=STATE_NAME

Query Parameters:

ParameterTypeRequiredDescription
stateStringYesThe full name of the state (e.g., ALABAMA, California). Case-insensitive matching is recommended.

Example Request:

GET https://api.fips.codes/counties?state=ALABAMA

Example Response (Success 200):

[
  {
    "stateAbbrev": "AL",
    "state": "ALABAMA",
    "stateFips": "01",
    "county": "AUTAUGA COUNTY",
    "fips": "01001"
  },
  {
    "stateAbbrev": "AL",
    "state": "ALABAMA",
    "stateFips": "01",
    "county": "BALDWIN COUNTY",
    "fips": "01003"
  }
  // ... other counties in Alabama
]

Example Response (Error 404 - State Not Found):

{
  "error": "State not found: NONEXISTENTSTATE"
}

Retrieve a Specific FIPS Code

Retrieves the FIPS code for a specific county within a specific state. The response is a single county object. Refer to "Data Shapes - County-Specific Data" for the response structure.

GET/counties?state=STATE_NAME&county=COUNTY_NAME

Query Parameters:

ParameterTypeRequiredDescription
stateStringYesThe full name of the state (e.g., ALABAMA, California). Case-insensitive matching is recommended.
countyStringYesThe name of the county (e.g., BIBB COUNTY, Los Angeles County). Case-insensitive matching is recommended.

Example Request:

GET https://api.fips.codes/counties?state=ALABAMA&county=BIBB COUNTY

Example Response (Success 200):

{
  "stateAbbrev": "AL",
  "state": "ALABAMA",
  "stateFips": "01",
  "county": "BIBB COUNTY",
  "fips": "01007"
}

Example Response (Error 404 - County Not Found):

{
  "error": "County not found: NONEXISTENT COUNTY in ALABAMA"
}

Example Response (Error 404 - State Not Found):

{
  "error": "State not found: NONEXISTENTSTATE"
}

Error Handling

The API uses standard HTTP status codes to indicate the success or failure of an API request.

  • 200 OK: The request was successful.
  • 400 Bad Request: The request was malformed (e.g., missing required parameters).
  • 404 Not Found: The requested resource (e.g., state or county) could not be found.
  • 500 Internal Server Error: Something went wrong on our end. (Please contact support if this persists)

Error responses will typically include a JSON object with an error key describing the issue.

// Example Error Response
{
  "error": "Specific error message here"
}