Names, abbreviations, FIPS codes, capitals, regions, timezones, admission dates, and population for every US state. Search the list or look up by code.
This calls the live States API. Pull the full list, search by name, or fetch a single state by abbreviation.
Any two-letter abbreviation works in production.
| state | abbr | fips | capital | region | population |
|---|---|---|---|---|---|
| Loading live response... | |||||
Why States API
Complete state reference
All 50 US states with name, abbreviation, FIPS code, capital, region, timezones, admission date, and population.
FIPS code lookups
Resolve census and government datasets with GET /fips/:code. Single-digit codes are auto-padded, so 6 and 06 both return California.
Name search
Filter the list with a q parameter: /us-states?q=new returns New Hampshire, New Jersey, New Mexico, and New York in one call.
Region and timezone data
Group states by census region or map users to timezones without maintaining your own lookup table.
Population figures
Census population values ready for per-capita math, market sizing, and choropleth maps.
Read-only and stable
Reference data that changes rarely and an API surface that never mutates. Cache aggressively; responses are consistent between calls.
/api/v1/us-states
List and search states
Returns all 50 states, or a filtered list with the optional q search parameter.
Lookup by abbreviation
Single state by two-letter code, e.g. /us-states/CA returns California.
Lookup by FIPS code
Single state by FIPS code. Codes are auto-padded to two digits, so 6 resolves to 06.
Service health
Status, version, timestamp, and uptime for monitoring.
Prometheus metrics
Request counts and latency histograms in Prometheus exposition format.
| Parameter | Type | Required | Description |
|---|---|---|---|
| q | string | no | Search term for the list endpoint. Matches state names, e.g. ?q=new. |
| abbr | path | for /us-states/:abbr | Two-letter state abbreviation, case-insensitive. |
| fipscode | path | for /fips/:fipscode | One- or two-digit FIPS code; auto-padded to two digits. |
Error reference
Failed lookups return a plain error message and a correlationId for tracing.
No state matches the requested abbreviation, e.g. /us-states/ZZ. Check the two-letter code.
No state matches the requested FIPS code, e.g. /fips/99. Valid codes run from 01 to 56.
The path is not one of /us-states, /us-states/:abbr, or /us-states/fips/:fipscode.
Missing or invalid API key at the gateway. Send x-api-key or api_key with every request.
Unexpected runtime failure. The response includes details and a correlationId for tracing.
Example error response
{
"error": "FIPS code 99 not found",
"correlationId": "1780011610881-z0qs7cw52"
}FAQ
Eight fields per state: stateName, abbreviation, fipsCode, capital, region, timezones, admittedOn (admission date), and population. The same shape is returned by list, search, abbreviation, and FIPS lookups.
GET /fips/:fipscode accepts one- or two-digit codes and auto-pads them, so /fips/6 and /fips/06 both return California. Unknown codes return a 404 with an explanatory error.
Yes. Add q to the list endpoint: /us-states?q=new returns every state whose name matches, such as New Hampshire, New Jersey, New Mexico, and New York.
Yes. The API is read-only reference data that changes rarely (population updates with census revisions), so aggressive client-side caching is appropriate.
Send your Datpaq API key as an x-api-key header or an api_key query parameter. Keys are created in the Datpaq dashboard and a free tier is included.
Abbreviations, FIPS codes, capitals, regions, timezones, and population from one read-only endpoint. No CSV to import, no table to maintain.