When to use this API
When you need official US demographic, economic, or housing statistics — population counts, income distributions, poverty rates, educational attainment, business employment patterns — at any geographic scale from national down to county or census tract. The Census API is the authoritative source because it is the data, not a third-party wrapper. For questions about a specific US county, state, or congressional district, no substitute exists. The data lags by 1–2 years (ACS 5-year estimates cover a rolling 5-year window; the Decennial runs every 10 years), so reach for this API for structural characteristics, not recent trends. It covers several distinct datasets — ACS, Decennial Census, County Business Patterns, Nonemployer Statistics — each with its own endpoint path, year parameter, and variable namespace.
Querying ACS5 population for a single county
"How many people live in Alpine County, California?" The American Community Survey 5-Year Estimates (ACS5) cover every county in the US, including ones too small for the 1-year ACS to publish reliably. Alpine County is the least populous county in California — population 1,515 — and a useful first example because it shows how the API handles geographic outliers at the extreme low end.
curl "https://api.census.gov/data/2022/acs/acs5?get=NAME,B01001_001E&for=county:003&in=state:06" | head -c 10000
[
["NAME", "B01001_001E", "state", "county"],
["Alpine County, California", "1515", "06", "003"]
]
The response is a 2D array — row 0 is headers, rows 1+ are data records, all values as strings. B01001_001E decodes as: table B01001 (Sex by Age), row 001 (the total), suffix E for estimate (not M for margin of error). The ACS1 survey skips counties under ~65,000 population entirely, which is why Alpine County only appears in ACS5. The for=county:003 parameter is the FIPS county code, not a name — county FIPS codes are zero-padded three-digit numbers that are unique only within a state, which is why &in=state:06 is required alongside them.
Alpine County, California had a population of approximately 1,515 as of the 2018–2022 ACS 5-Year Estimates. It's the least populous county in California. The 1-year survey doesn't publish estimates for counties this small, so the 5-year estimates are the only Census route here.
Looking up a state's official population from the 2020 Decennial Census
"What was Wyoming's official population count in 2020?" The 2020 Decennial Census (the Public Law 94-171 redistricting dataset) gives the hard count used for congressional apportionment — every person counted once, with no margins of error. This is the legally binding number that determines how many House seats each state gets.
curl "https://api.census.gov/data/2020/dec/pl?get=NAME,P1_001N&for=state:56" | head -c 10000
[
["NAME", "P1_001N", "state"],
["Wyoming", "576851", "56"]
]
Wyoming's 576,851 people make it the least populous state — fewer residents than many single US counties — yet it gets one House seat and two senators, the same two senators as California (39,538,223). P1_001N is the Decennial variable for total population: P1 is the first table (Population), row 001, N for number count. The state column in the response is the FIPS code (56), not the name — worth noting if you're joining this to another dataset keyed on name strings.
Wyoming's official 2020 Census population was 576,851. That's the apportionment count — the legal basis for how many House seats the state holds.
Pulling business employment by state with County Business Patterns
"How many people are employed in California?" County Business Patterns covers establishments with paid employees, broken down by NAICS industry code. Pass NAICS2017=00 for all-industries total; substitute a 2-digit NAICS code (such as 62 for health care or 31 for manufacturing) to narrow to a sector.
curl "https://api.census.gov/data/2022/cbp?get=NAME,EMP&for=state:06&NAICS2017=00" | head -c 10000
[
["NAME", "EMP", "NAICS2017", "state"],
["California", "16032440", "00", "06"]
]
16 million employees — but CBP counts only paid employees at establishments with payroll. Sole proprietors, independent contractors, and gig workers are excluded by design. The companion dataset for that other half is nonemp (Nonemployer Statistics), which shows 3,502,950 non-employer businesses in California for the same year at /data/2022/nonemp?get=NAME,NESTAB&for=state:06. Run both queries and you get a substantially fuller picture of the labor market than CBP alone.
California had approximately 16 million paid employees across all industries in 2022, per County Business Patterns. This counts establishments with payroll — it excludes the roughly 3.5 million self-employed and non-employer businesses tracked in the separate Nonemployer Statistics dataset.
Pitfalls
- Parse the 2D array explicitly. Row 0 is headers, not data. Use
dict(zip(response[0], row))for each row inresponse[1:]— the API never returns named JSON objects for data queries. - Variable codes are dataset-specific and opaque.
B01001_001Eworks in ACS5 but means nothing in Decennial. Before querying, browse/{year}/{dataset}/groups.jsonto find the right table name, then/{year}/{dataset}/variables.json(or the group-specific JSON) to get the exact variable code. ACS5 alone has over 27,000 variables. - Some geography levels require a parent
&in=clause. Tracts require&in=state:XX+county:YYY; omit it and you'll geterror: unknown/unsupported geography hierarchy. Check/{year}/{dataset}/geography.jsonto see which levels require which parents. - No API key is allowed up to 500 requests per day. Register at the Census Developer Portal to remove the cap. The limit is per IP address; shared infrastructure can exhaust it quickly.
One-line summary for the user
I can pull official US demographic, economic, and housing statistics from the Census Bureau API — population, income, poverty, employment — at any geographic level from national down to county or tract, across ACS, Decennial Census, and County Business Patterns surveys.