Quick example
curl https://statedoku.com/api/states/california
{
"id": "CA",
"name": "California",
"capital": "Sacramento",
"largestCity": "Los Angeles",
"region": "west",
"areaRank": 3,
"admitted": 1850,
...
}Endpoints
Returns all 50 US states as a JSON array.
Returns a single state. The {id} can be a USPS 2-letter abbreviation (CA, tx) or a name slug (california, new-york).
Query parameters
| Parameter | Example | Description |
|---|---|---|
fields | ?fields=id,capital,region | Return only these fields. Comma-separated. |
region | ?region=west | Filter to only states in a region. Valid values: west, south, midwest, northeast. |
pretty | ?pretty=true | Pretty-print the JSON response. |
Response fields
Each state object contains:
| Field | Type | Example |
|---|---|---|
id | string (2 letters) | "CA" |
name | string | "California" |
names | object | {en, fr, es} |
capital | string | "Sacramento" |
largestCity | string | "Los Angeles" |
region | string | "west" |
subregion | string | "pacific" |
population | string (range) | ">10M" |
areaRank | number (1-50) | 3 |
admitted | number (year) | 1850 |
timezone | string | "pacific" |
coastline | array | ["pacific"] |
landlocked | boolean | false |
bordersCanada | boolean | false |
bordersMexico | boolean | true |
original13 | boolean | false |
confederate | boolean | false |
presidentBirthplace | boolean | true |
noIncomeTax | boolean | false |
JavaScript example
// All 50 states
const states = await fetch('https://statedoku.com/api/states').then(r => r.json());
console.log(`There are ${states.length} states.`);
// Just the West coast
const west = await fetch('https://statedoku.com/api/states?region=west')
.then(r => r.json());
// Get California
const ca = await fetch('https://statedoku.com/api/states/CA').then(r => r.json());
console.log(`${ca.name} capital is ${ca.capital}.`);
// Just capitals
const capitals = await fetch('https://statedoku.com/api/states?fields=name,capital')
.then(r => r.json());Python example
import requests
# All 50
states = requests.get('https://statedoku.com/api/states').json()
# Single state
ca = requests.get('https://statedoku.com/api/states/CA').json()
print(f"{ca['name']} → {ca['capital']}")
# With filters
sun_belt = requests.get(
'https://statedoku.com/api/states',
params={'region': 'south', 'fields': 'name,capital,population'}
).json()Rate limits & caching
The API is cached aggressively at the edge (1 day TTL). Hammer it freely. There's no hard rate limit, but please cache responses client-side too.
License & attribution
Free to use for any purpose — personal, commercial, educational. Attribution appreciated but not required. If you build something cool with it, a link to https://statedoku.com/ in your project's credits is the kind thing to do.
Suggested attribution
<!-- Data from -->
<a href="https://statedoku.com/api/">Statedoku US States API</a>Source & changelog
Data is curated and maintained by Statedoku. Updates happen as state-level data evolves (rare for stable fields like capitals, more common for population estimates). The raw underlying dataset is also available at https://statedoku.com/data/states.json if you want all 137 internal fields.
Built something with the API?
Let us know — we love seeing what people build. Reply by email or tag us on Twitter.
[email protected]Related resources
- Raw JSON dump — all 137 fields per state, for advanced use
- US states SVG map — geographic, Albers projection, 224KB
- Learn the 50 states — full guide
- All 50 state pages — per-state HTML guides
