Access us census statistics

When the user asks for US demographic, economic, or housing statistics — population, income, poverty, employment, educational attainment — at state, county, or tract level, reach for the US Census Bureau API. Authoritative federal data via unauthenticated GET.

access-us-census-statistics · v1 · updated 2026-04-16

Agents: This page is a SKILL.md-style capability guide. For JSON, call GET /api/skills/access-us-census-statistics. To drop this into a local Claude Code install, copy the frontmatter + body below into ~/.claude/skills/access-us-census-statistics/SKILL.md.

When to use this skill

When the user asks for official US demographic, economic, or housing statistics — population counts, income, poverty rates, educational attainment, employment by industry — at any geographic scale from national down to state, county, or census tract. This is the authoritative source: it is the data, not a wrapper. For questions about a specific US county, state, or congressional district, no substitute exists. For recent trends (last few months), this is the wrong skill — Census data lags 1–2 years (ACS 5-year estimates cover a rolling window; the Decennial runs every 10 years). For non-US statistics, this is also the wrong skill.

Your best first call

curl "https://api.census.gov/data/2022/acs/acs5?get=NAME,B01001_001E&for=county:003&in=state:06"

No auth required for up to 500 requests/day per IP. Register at the Census Developer Portal to remove the cap.

This fetches the total population of Alpine County, California — the least populous county in CA (population 1,515) — from the ACS 5-Year Estimates. The URL pattern is https://api.census.gov/data/{year}/{dataset}?get={variables}&for={geography}&in={parent_geography}.

The response is a 2D array: row 0 is headers, rows 1+ are data, all values as strings:

[
  ["NAME", "B01001_001E", "state", "county"],
  ["Alpine County, California", "1515", "06", "003"]
]

Key fields an agent uses: - NAME — human-readable geographic label (e.g. "Alpine County, California") - Variable columns like B01001_001E — the requested estimates. E suffix means estimate; M means margin of error. Variable codes are dataset-specific and opaque (ACS5 has 27,000+ of them). - state, county, tract — FIPS geography codes, always zero-padded strings, not names.

Fallbacks (when the best call isn't enough)

Decennial Census hard counts → /data/2020/dec/pl with P1_001N for the legally binding apportionment population. Use when the user wants the official 2020 count, not an estimate.
Employment by industry → /data/2022/cbp with EMP and NAICS2017=00 for all-industries total, or a 2-digit NAICS code like 62 for health care. CBP counts paid employees only — sole proprietors and gig workers are in the separate nonemp dataset at /data/2022/nonemp.
Variable discovery → /{year}/{dataset}/groups.json lists table names; /{year}/{dataset}/variables.json lists every variable. Use these when you don't know the right variable code yet.

Pitfalls

Parse the 2D array explicitly. Row 0 is headers, not data. Map each data row with dict(zip(response[0], row)) — the API never returns named JSON objects for data queries.
Variable codes are opaque and dataset-specific. B01001_001E works in ACS5 but means nothing in Decennial. Browse groups.json to find the table, then variables.json to get the exact code. Guessing codes produces either errors or the wrong statistic.
Some geography levels require a parent &in= clause. County requires &in=state:XX; tract requires &in=state:XX+county:YYY. Omit it and you'll get error: unknown/unsupported geography hierarchy. Check /{year}/{dataset}/geography.json for required hierarchies.
ACS5 and ACS1 cover different populations. ACS1 only publishes for areas with 65,000+ residents. Small counties like Alpine (pop 1,515) exist only in ACS5. If a user asks about a small place and you query ACS1, you'll get no results — switch to ACS5.

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.

APIs this skill uses

US Census Bureau API · primary · verified

The Census Data API provides access to a wide range of Census Bureau datasets including the American Community Survey (ACS), Decennial Census, Economic Census, and more. Users can query demographic, economic, and housing data at various geo…

Generated from

US Census Bureau API tutorial Getting Started with the US Census Bureau API

SKILL.md source (frontmatter + body)

---
name: access-us-census-statistics
description: When the user asks for US demographic, economic, or housing statistics — population, income, poverty, employment, educational attainment — at state, county, or tract level, reach for the US Census Bureau API. Authoritative federal data via unauthenticated GET.
---

## When to use this skill

When the user asks for official US demographic, economic, or housing statistics — population counts, income, poverty rates, educational attainment, employment by industry — at any geographic scale from national down to state, county, or census tract. This is the authoritative source: it *is* the data, not a wrapper. For questions about a specific US county, state, or congressional district, no substitute exists. For recent trends (last few months), this is the wrong skill — Census data lags 1–2 years (ACS 5-year estimates cover a rolling window; the Decennial runs every 10 years). For non-US statistics, this is also the wrong skill.

## Your best first call

```bash
curl "https://api.census.gov/data/2022/acs/acs5?get=NAME,B01001_001E&for=county:003&in=state:06"
```

No auth required for up to 500 requests/day per IP. Register at the Census Developer Portal to remove the cap.

This fetches the total population of Alpine County, California — the least populous county in CA (population 1,515) — from the ACS 5-Year Estimates. The URL pattern is `https://api.census.gov/data/{year}/{dataset}?get={variables}&for={geography}&in={parent_geography}`.

The response is a 2D array: row 0 is headers, rows 1+ are data, all values as strings:

```json
[
  ["NAME", "B01001_001E", "state", "county"],
  ["Alpine County, California", "1515", "06", "003"]
]
```

Key fields an agent uses:
- `NAME` — human-readable geographic label (e.g. "Alpine County, California")
- Variable columns like `B01001_001E` — the requested estimates. `E` suffix means estimate; `M` means margin of error. Variable codes are dataset-specific and opaque (ACS5 has 27,000+ of them).
- `state`, `county`, `tract` — FIPS geography codes, always zero-padded strings, not names.

## Fallbacks (when the best call isn't enough)

- **Decennial Census hard counts** → `/data/2020/dec/pl` with `P1_001N` for the legally binding apportionment population. Use when the user wants the official 2020 count, not an estimate.
- **Employment by industry** → `/data/2022/cbp` with `EMP` and `NAICS2017=00` for all-industries total, or a 2-digit NAICS code like `62` for health care. CBP counts paid employees only — sole proprietors and gig workers are in the separate `nonemp` dataset at `/data/2022/nonemp`.
- **Variable discovery** → `/{year}/{dataset}/groups.json` lists table names; `/{year}/{dataset}/variables.json` lists every variable. Use these when you don't know the right variable code yet.

## Pitfalls

- **Parse the 2D array explicitly.** Row 0 is headers, not data. Map each data row with `dict(zip(response[0], row))` — the API never returns named JSON objects for data queries.
- **Variable codes are opaque and dataset-specific.** `B01001_001E` works in ACS5 but means nothing in Decennial. Browse `groups.json` to find the table, then `variables.json` to get the exact code. Guessing codes produces either errors or the wrong statistic.
- **Some geography levels require a parent `&in=` clause.** County requires `&in=state:XX`; tract requires `&in=state:XX+county:YYY`. Omit it and you'll get `error: unknown/unsupported geography hierarchy`. Check `/{year}/{dataset}/geography.json` for required hierarchies.
- **ACS5 and ACS1 cover different populations.** ACS1 only publishes for areas with 65,000+ residents. Small counties like Alpine (pop 1,515) exist only in ACS5. If a user asks about a small place and you query ACS1, you'll get no results — switch to ACS5.

## 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.

« Back to all skills