When to use this skill
When the user asks about US poverty rates, families below the poverty line, poverty status by age or household type, or wants poverty statistics broken down by state, county, or census tract. This skill targets the Census Bureau's ACS poverty tables (B17xxx family). For non-poverty Census variables — population, income, education, housing — use the general Census Data API skill instead.
Your best first call
curl "https://api.census.gov/data/2022/acs/acs5?get=NAME,B17015_002E&for=state:*"
No auth. No key. Returns a 2D array where the first row is column headers (NAME, B17015_002E, state) and every subsequent row is one state's data, all values as strings. B17015_002E is "families below poverty level" — parse it as an integer before calculating rates.
Narrow to a single state with for=state:06 (California). For county-level data within a state: for=county:*&in=state:06. For census tracts, you must specify both parent geographies: for=tract:*&in=state:06+county:073. The ACS 5-year survey goes down to block group; the 1-year survey (acs/acs1) only covers areas with 65,000+ residents — for sub-county poverty data, always use acs/acs5.
To discover which poverty variables exist beyond B17015_002E, query the groups endpoint and filter for B17 table families:
curl "https://api.census.gov/data/2022/acs/acs5/groups.json"
Key groups: B17015 (families by type), B17016 (by work experience), B17017 (by household age). Each group's variables URL lists the individual estimate (E) and margin of error (M) codes.
Fallbacks (when the best first call isn't enough)
- Poverty for the total population, not just families → use variables from group
B17001 (poverty status by age and sex) instead of B17015. The tutorial's B17015 covers families only; B17001_002E covers individuals.
- Most recent year of data → increment the year in the path (
2023/acs/acs5 instead of 2022). The Census Bureau releases new ACS 5-year estimates annually.
- Sub-county data where margins of error are large → pair every
E (estimate) variable with its M (margin of error) counterpart. At tract and block group level, the MOE can exceed the estimate itself — flag unreliable values to the user.
Pitfalls
- All data values are strings, never JSON numbers.
B17015_002E returns "142300", not 142300. Parse before doing any arithmetic.
- Every estimate has a paired margin of error.
B17015_002E comes with B17015_002M. For sub-county geographies, the MOE routinely exceeds the estimate — requesting estimates without MOE is a credibility error.
- Geography queries require parent geographies. You cannot query
for=tract:* without in=state:{fips}+county:{fips}. A 400 error almost always means missing parent geographies, not a bad variable.
- The
universe key in groups.json has a trailing space. obj["universe"] raises a KeyError — use obj["universe "] or strip keys before access.
One-line summary for the user
I can pull US poverty statistics — families below the poverty line, poverty rates by geography — from the Census Bureau's ACS datasets down to census tract level, but you'll need a FIPS code and I may need to look up the right variable code for your specific poverty question.
SKILL.md source (frontmatter + body)
---
name: access-poverty
description: When the user asks about US poverty rates, families below the poverty line, or poverty statistics by state, county, or census tract — reach for the Census Bureau's ACS poverty tables (B17xxx family). Requires FIPS geography codes and variable codes.
---
## When to use this skill
When the user asks about US poverty rates, families below the poverty line, poverty status by age or household type, or wants poverty statistics broken down by state, county, or census tract. This skill targets the Census Bureau's ACS poverty tables (B17xxx family). For non-poverty Census variables — population, income, education, housing — use the general Census Data API skill instead.
## Your best first call
```bash
curl "https://api.census.gov/data/2022/acs/acs5?get=NAME,B17015_002E&for=state:*"
```
No auth. No key. Returns a 2D array where the first row is column headers (`NAME`, `B17015_002E`, `state`) and every subsequent row is one state's data, all values as strings. `B17015_002E` is "families below poverty level" — parse it as an integer before calculating rates.
Narrow to a single state with `for=state:06` (California). For county-level data within a state: `for=county:*&in=state:06`. For census tracts, you must specify both parent geographies: `for=tract:*&in=state:06+county:073`. The ACS 5-year survey goes down to block group; the 1-year survey (`acs/acs1`) only covers areas with 65,000+ residents — for sub-county poverty data, always use `acs/acs5`.
To discover which poverty variables exist beyond `B17015_002E`, query the groups endpoint and filter for `B17` table families:
```bash
curl "https://api.census.gov/data/2022/acs/acs5/groups.json"
```
Key groups: `B17015` (families by type), `B17016` (by work experience), `B17017` (by household age). Each group's `variables` URL lists the individual estimate (`E`) and margin of error (`M`) codes.
## Fallbacks (when the best first call isn't enough)
- **Poverty for the total population, not just families** → use variables from group `B17001` (poverty status by age and sex) instead of `B17015`. The tutorial's `B17015` covers families only; `B17001_002E` covers individuals.
- **Most recent year of data** → increment the year in the path (`2023/acs/acs5` instead of `2022`). The Census Bureau releases new ACS 5-year estimates annually.
- **Sub-county data where margins of error are large** → pair every `E` (estimate) variable with its `M` (margin of error) counterpart. At tract and block group level, the MOE can exceed the estimate itself — flag unreliable values to the user.
## Pitfalls
- **All data values are strings, never JSON numbers.** `B17015_002E` returns `"142300"`, not `142300`. Parse before doing any arithmetic.
- **Every estimate has a paired margin of error.** `B17015_002E` comes with `B17015_002M`. For sub-county geographies, the MOE routinely exceeds the estimate — requesting estimates without MOE is a credibility error.
- **Geography queries require parent geographies.** You cannot query `for=tract:*` without `in=state:{fips}+county:{fips}`. A 400 error almost always means missing parent geographies, not a bad variable.
- **The `universe ` key in groups.json has a trailing space.** `obj["universe"]` raises a KeyError — use `obj["universe "]` or strip keys before access.
## One-line summary for the user
I can pull US poverty statistics — families below the poverty line, poverty rates by geography — from the Census Bureau's ACS datasets down to census tract level, but you'll need a FIPS code and I may need to look up the right variable code for your specific poverty question.