Tutorial 2: ACS 5-Year Aggregate Data¶

This tutorial covers the most common use case: fetching aggregate statistics from the ACS 5-Year estimates.

Goal: Get poverty statistics for all places (cities, towns, CDPs) in a state.

Setup¶

In [1]:

Copied!





import os
from cendat import CenDatHelper
from dotenv import load_dotenv

load_dotenv()
cdh = CenDatHelper(key=os.getenv("CENSUS_API_KEY"))
import os
from cendat import CenDatHelper
from dotenv import load_dotenv

load_dotenv()
cdh = CenDatHelper(key=os.getenv("CENSUS_API_KEY"))

✅ API key loaded successfully.

Step 1: Find the ACS 5-Year Product¶

In [2]:

Copied!





# The \) at the end matches products ending with a closing paren,
# which filters out sub-products like /profile, /subject, etc.
cdh.list_products(years=[2023], patterns=r"acs/acs5\)")
cdh.set_products()
# The \) at the end matches products ending with a closing paren,
# which filters out sub-products like /profile, /subject, etc.
cdh.list_products(years=[2023], patterns=r"acs/acs5\)")
cdh.set_products()

✅ Product set: 'ACS 5-Year Detailed Tables (2023/acs/acs5)' (Vintage: [2023])

Step 2: Explore Variable Groups¶

For products like ACS with thousands of variables, groups are essential:

In [3]:

Copied!

# Search for poverty-related groups
cdh.list_groups(patterns="poverty")
# Search for poverty-related groups
cdh.list_groups(patterns="poverty")

Out[3]:

[{'name': 'B17015',
  'description': 'Poverty Status in the Past 12 Months of Families by Family Type by Social Security Income by Supplemental Security Income (SSI) and Cash Public Assistance Income',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17016',
  'description': 'Poverty Status in the Past 12 Months of Families by Family Type by Work Experience of Householder and Spouse',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17017',
  'description': 'Poverty Status in the Past 12 Months by Household Type by Age of Householder',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17018',
  'description': 'Poverty Status in the Past 12 Months of Families by Household Type by Educational Attainment of Householder',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17012',
  'description': 'Poverty Status in the Past 12 Months of Families by Household Type by Number of Related Children Under 18 Years',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17013',
  'description': 'Poverty Status in the Past 12 Months of Families by Household Type by Number of Persons in Family',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17014',
  'description': 'Poverty Status in the Past 12 Months of Families by Household Type by Number of Workers in Family',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17010',
  'description': 'Poverty Status in the Past 12 Months of Families by Family Type by Presence of Related Children Under 18 Years by Age of Related Children',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17019',
  'description': 'Poverty Status in the Past 12 Months of Families by Household Type by Tenure',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17004',
  'description': 'Poverty Status in the Past 12 Months of Individuals by Sex by Work Experience',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17005',
  'description': 'Poverty Status in the Past 12 Months of Individuals by Sex by Employment Status',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17006',
  'description': 'Poverty Status in the Past 12 Months of Related Children Under 18 Years by Family Type by Age of Related Children Under 18 Years',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17007',
  'description': 'Poverty Status in the Past 12 Months of Unrelated Individuals 15 Years and Over by Sex by Age',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B07012PR',
  'description': 'Geographical Mobility in the Past Year by Poverty Status in the Past 12 Months for Current Residence in Puerto Rico',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17001',
  'description': 'Poverty Status in the Past 12 Months by Sex by Age',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17003',
  'description': 'Poverty Status in the Past 12 Months of Individuals by Sex by Educational Attainment',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17009',
  'description': 'Poverty Status by Work Experience of Unrelated Individuals by Householder Status',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B05010',
  'description': 'Ratio of Income to Poverty Level in the Past 12 Months by Nativity of Children Under 18 Years in Families and Subfamilies by Living Arrangements and Nativity of Parents',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B08522',
  'description': 'Means of Transportation to Work by Poverty Status in the Past 12 Months for Workplace Geography',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B07012',
  'description': 'Geographical Mobility in the Past Year by Poverty Status in the Past 12 Months for Current Residence in the United States',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17026',
  'description': 'Ratio of Income to Poverty Level of Families in the Past 12 Months',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17022',
  'description': 'Ratio of Income to Poverty Level in the Past 12 Months of Families by Family Type by Presence of Related Children Under 18 Years by Age of Related Children',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17023',
  'description': 'Poverty Status in the Past 12 Months of Families by Household Type by Number of Own Children Under 18 Years',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17024',
  'description': 'Age by Ratio of Income to Poverty Level in the Past 12 Months',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17025',
  'description': 'Poverty Status in the Past 12 Months by Nativity',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17020',
  'description': 'Poverty Status in the Past 12 Months by Age',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17021',
  'description': 'Poverty Status of Individuals in the Past 12 Months by Living Arrangement',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B29003',
  'description': 'Citizen, Voting-Age Population by Poverty Status',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'C18131',
  'description': 'Ratio of Income to Poverty Level in the Past 12 Months by Disability Status',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'C18130',
  'description': 'Age by Disability Status by Poverty Status',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B06012PR',
  'description': 'Place of Birth by Poverty Status in the Past 12 Months in Puerto Rico',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B07412',
  'description': 'Geographical Mobility in the Past Year by Poverty Status in the Past 12 Months for Residence 1 Year Ago in the United States',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B13010',
  'description': 'Women 15 to 50 Years Who Had a Birth in the Past 12 Months by Marital Status and Poverty Status in the Past 12 Months',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B23024',
  'description': 'Poverty Status in the Past 12 Months by Disability Status by Employment Status for the Population 20 to 64 Years',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17010E',
  'description': 'Poverty Status in the Past 12 Months of Families by Family Type by Presence of Related Children Under 18 Years by Age of Related Children (Native Hawaiian and Other Pacific Islander Alone Householder)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17010F',
  'description': 'Poverty Status in the Past 12 Months of Families by Family Type by Presence of Related Children Under 18 Years by Age of Related Children (Some Other Race Alone Householder)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17010C',
  'description': 'Poverty Status in the Past 12 Months of Families by Family Type by Presence of Related Children Under 18 Years by Age of Related Children (American Indian and Alaska Native Alone)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17010D',
  'description': 'Poverty Status in the Past 12 Months of Families by Family Type by Presence of Related Children Under 18 Years by Age of Related Children (Asian Alone Householder)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17010A',
  'description': 'Poverty Status in the Past 12 Months of Families by Family Type by Presence of Related Children Under 18 Years by Age of Related Children (White Alone Householder)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17010B',
  'description': 'Poverty Status in the Past 12 Months of Families by Family Type by Presence of Related Children Under 18 Years by Age of Related Children (Black or African American Alone Householder)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17010I',
  'description': 'Poverty Status in the Past 12 Months of Families by Family Type by Presence of Related Children Under 18 Years by Age of Related Children (Hispanic or Latino)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17010G',
  'description': 'Poverty Status in the Past 12 Months of Families by Family Type by Presence of Related Children Under 18 Years by Age of Related Children (Two or More Races Householder)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17010H',
  'description': 'Poverty Status in the Past 12 Months of Families by Family Type by Presence of Related Children Under 18 Years by Age of Related Children (White Alone, Not Hispanic or Latino Householder)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17001G',
  'description': 'Poverty Status in the Past 12 Months by Sex by Age (Two or More Races)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17001H',
  'description': 'Poverty Status in the Past 12 Months by Sex by Age (White Alone, Not Hispanic or Latino)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17001E',
  'description': 'Poverty Status in the Past 12 Months by Sex by Age (Native Hawaiian and Other Pacific Islander Alone)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17001F',
  'description': 'Poverty Status in the Past 12 Months by Sex by Age (Some Other Race Alone)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17001C',
  'description': 'Poverty Status in the Past 12 Months by Sex by Age (American Indian and Alaska Native Alone)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17001D',
  'description': 'Poverty Status in the Past 12 Months by Sex by Age (Asian Alone)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17001A',
  'description': 'Poverty Status in the Past 12 Months by Sex by Age (White Alone)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17001B',
  'description': 'Poverty Status in the Past 12 Months by Sex by Age (Black or African American Alone)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'C21007',
  'description': 'Age by Veteran Status by Poverty Status in the Past 12 Months by Disability Status for the Civilian Population 18 Years and Over',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17001I',
  'description': 'Poverty Status in the Past 12 Months by Sex by Age (Hispanic or Latino)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17101',
  'description': 'Poverty Status in the Past 12 Months of People in Housing Units',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B06012',
  'description': 'Place of Birth by Poverty Status in the Past 12 Months in the United States',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B14006',
  'description': 'Poverty Status in the Past 12 Months by School Enrollment by Level of School for the Population 3 Years and Over',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B16009',
  'description': 'Poverty Status in the Past 12 Months by Age by Language Spoken at Home for the Population 5 Years and Over',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B07412PR',
  'description': 'Geographical Mobility in the Past Year by Poverty Status in the Past 12 Months for Residence 1 Year Ago in Puerto Rico',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B10059',
  'description': 'Poverty Status in the Past 12 Months of Grandparents Living With Own Grandchildren Under 18 Years by Responsibility for Own Grandchildren and Age of Grandparent',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'C27018',
  'description': 'Public Health Insurance by Ratio of Income to Poverty Level in the Past 12 Months by Age',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'C27017',
  'description': 'Private Health Insurance by Ratio of Income to Poverty Level in the Past 12 Months by Age',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'C27016',
  'description': 'Health Insurance Coverage Status by Ratio of Income to Poverty Level in the Past 12 Months by Age',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'C17002',
  'description': 'Ratio of Income to Poverty Level in the Past 12 Months',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17020D',
  'description': 'Poverty Status in the Past 12 Months by Age (Asian Alone)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17020E',
  'description': 'Poverty Status in the Past 12 Months by Age (Native Hawaiian and Other Pacific Islander Alone)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17020B',
  'description': 'Poverty Status in the Past 12 Months by Age (Black or African American Alone)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17020C',
  'description': 'Poverty Status in the Past 12 Months by Age (American Indian and Alaska Native Alone)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17020A',
  'description': 'Poverty Status in the Past 12 Months by Age (White Alone)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B99171',
  'description': 'Allocation of Poverty Status in the Past 12 Months for Unrelated Individuals',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B99172',
  'description': 'Allocation of Poverty Status in the Past 12 Months for Families',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B08122',
  'description': 'Means of Transportation to Work by Poverty Status in the Past 12 Months',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B22003',
  'description': 'Receipt of Food Stamps/SNAP in the Past 12 Months by Poverty Status in the Past 12 Months for Households',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17020H',
  'description': 'Poverty Status in the Past 12 Months by Age (White Alone, Not Hispanic or Latino)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17020I',
  'description': 'Poverty Status in the Past 12 Months by Age (Hispanic or Latino)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17020F',
  'description': 'Poverty Status in the Past 12 Months by Age (Some Other Race Alone)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'},
 {'name': 'B17020G',
  'description': 'Poverty Status in the Past 12 Months by Age (Two or More Races)',
  'product': 'ACS 5-Year Detailed Tables (2023/acs/acs5)',
  'vintage': [2023],
  'url': 'http://api.census.gov/data/2023/acs/acs5'}]

In [4]:

Copied!

# Let's use B17001 (Poverty Status by Sex by Age)
cdh.set_groups("B17001")

# See what variables are in this group
cdh.describe_groups()
# Let's use B17001 (Poverty Status by Sex by Age)
cdh.set_groups("B17001")

# See what variables are in this group
cdh.describe_groups()

✅ Groups set: B17001

--- Group: B17001 (Poverty Status in the Past 12 Months by Sex by Age) ---

  Product: ACS 5-Year Detailed Tables (2023/acs/acs5) (Vintage: 2023)
      B17001_001E: Total:
        B17001_002E: Income in the past 12 months below poverty level:
          B17001_003E: Male:
            B17001_004E: Under 5 years
            B17001_005E: 5 years
            B17001_006E: 6 to 11 years
            B17001_007E: 12 to 14 years
            B17001_008E: 15 years
            B17001_009E: 16 and 17 years
            B17001_010E: 18 to 24 years
            B17001_011E: 25 to 34 years
            B17001_012E: 35 to 44 years
            B17001_013E: 45 to 54 years
            B17001_014E: 55 to 64 years
            B17001_015E: 65 to 74 years
            B17001_016E: 75 years and over
          B17001_017E: Female:
            B17001_018E: Under 5 years
            B17001_019E: 5 years
            B17001_020E: 6 to 11 years
            B17001_021E: 12 to 14 years
            B17001_022E: 15 years
            B17001_023E: 16 and 17 years
            B17001_024E: 18 to 24 years
            B17001_025E: 25 to 34 years
            B17001_026E: 35 to 44 years
            B17001_027E: 45 to 54 years
            B17001_028E: 55 to 64 years
            B17001_029E: 65 to 74 years
            B17001_030E: 75 years and over
        B17001_031E: Income in the past 12 months at or above poverty level:
          B17001_032E: Male:
            B17001_033E: Under 5 years
            B17001_034E: 5 years
            B17001_035E: 6 to 11 years
            B17001_036E: 12 to 14 years
            B17001_037E: 15 years
            B17001_038E: 16 and 17 years
            B17001_039E: 18 to 24 years
            B17001_040E: 25 to 34 years
            B17001_041E: 35 to 44 years
            B17001_042E: 45 to 54 years
            B17001_043E: 55 to 64 years
            B17001_044E: 65 to 74 years
            B17001_045E: 75 years and over
          B17001_046E: Female:
            B17001_047E: Under 5 years
            B17001_048E: 5 years
            B17001_049E: 6 to 11 years
            B17001_050E: 12 to 14 years
            B17001_051E: 15 years
            B17001_052E: 16 and 17 years
            B17001_053E: 18 to 24 years
            B17001_054E: 25 to 34 years
            B17001_055E: 35 to 44 years
            B17001_056E: 45 to 54 years
            B17001_057E: 55 to 64 years
            B17001_058E: 65 to 74 years
            B17001_059E: 75 years and over

Step 3: Select Variables and Geography¶

In [5]:

Copied!





# B17001_001E = Total population for poverty calculation
# B17001_002E = Population below poverty level
cdh.set_variables(["B17001_001E", "B17001_002E"])

# 160 = Places (cities, towns, CDPs)
cdh.set_geos(["160"])
# B17001_001E = Total population for poverty calculation
# B17001_002E = Population below poverty level
cdh.set_variables(["B17001_001E", "B17001_002E"])

# 160 = Places (cities, towns, CDPs)
cdh.set_geos(["160"])

✅ Variables set:
  - Product: ACS 5-Year Detailed Tables (2023/acs/acs5) (Vintage: [2023])
    Variables: B17001_001E, B17001_002E
✅ Geographies set: 'place' (requires `within` for: state)

Step 4: Get Data with Names¶

In [6]:

Copied!





response = cdh.get_data(
    include_names=True,      # Include place names
    include_attributes=True  # Include margins of error
)
response = cdh.get_data(
    include_names=True,      # Include place names
    include_attributes=True  # Include margins of error
)

✅ Parameters created for 1 geo-variable/group combinations.

✅ Data fetching complete. Stacking results.

Step 5: Analyze¶

In [7]:

Copied!

# Convert to DataFrame
df = response.to_polars(concat=True, destring=True)
df.glimpse()
# Convert to DataFrame
df = response.to_polars(concat=True, destring=True)
df.glimpse()

Rows: 32325
Columns: 15
$ NAME          <str> 'Abanda CDP, Alabama', 'Abbeville city, Alabama', 'Adamsville city, Alabama', 'Addison town, Alabama', 'Akron town, Alabama', 'Alabaster city, Alabama', 'Albertville city, Alabama', 'Alexander City city, Alabama', 'Alexandria CDP, Alabama', 'Aliceville city, Alabama'
$ B17001_001E   <i64> 48, 2306, 4235, 651, 354, 33224, 22180, 14240, 3420, 2338
$ B17001_002E   <i64> 0, 508, 798, 76, 38, 1768, 3795, 3102, 182, 1037
$ B17001_001MA <null> null, null, null, null, null, null, null, null, null, null
$ B17001_002MA <null> null, null, null, null, null, null, null, null, null, null
$ B17001_002EA <null> null, null, null, null, null, null, null, null, null, null
$ B17001_001EA <null> null, null, null, null, null, null, null, null, null, null
$ B17001_001M   <i64> 71, 300, 69, 176, 227, 90, 158, 46, 639, 459
$ B17001_002M   <i64> 13, 170, 435, 53, 40, 465, 994, 554, 139, 369
$ state         <str> '01', '01', '01', '01', '01', '01', '01', '01', '01', '01'
$ place         <str> '00100', '00124', '00460', '00484', '00676', '00820', '00988', '01132', '01180', '01228'
$ product       <str> 'ACS 5-Year Detailed Tables (2023/acs/acs5)', 'ACS 5-Year Detailed Tables (2023/acs/acs5)', 'ACS 5-Year Detailed Tables (2023/acs/acs5)', 'ACS 5-Year Detailed Tables (2023/acs/acs5)', 'ACS 5-Year Detailed Tables (2023/acs/acs5)', 'ACS 5-Year Detailed Tables (2023/acs/acs5)', 'ACS 5-Year Detailed Tables (2023/acs/acs5)', 'ACS 5-Year Detailed Tables (2023/acs/acs5)', 'ACS 5-Year Detailed Tables (2023/acs/acs5)', 'ACS 5-Year Detailed Tables (2023/acs/acs5)'
$ vintage       <str> '2023', '2023', '2023', '2023', '2023', '2023', '2023', '2023', '2023', '2023'
$ sumlev        <str> '160', '160', '160', '160', '160', '160', '160', '160', '160', '160'
$ desc          <str> 'place', 'place', 'place', 'place', 'place', 'place', 'place', 'place', 'place', 'place'

In [8]:

Copied!

# Quick tabulation: how many places have >10,000 population?
response.tabulate("state", where="B17001_001E > 10_000")
# Quick tabulation: how many places have >10,000 population?
response.tabulate("state", where="B17001_001E > 10_000")

shape: (52, 5)
┌───────┬─────┬──────┬───────┬────────┐
│ state ┆   n ┆  pct ┆  cumn ┆ cumpct │
╞═══════╪═════╪══════╪═══════╪════════╡
│    01 ┆  70 ┆  1.7 ┆    70 ┆    1.7 │
│    02 ┆   7 ┆  0.2 ┆    77 ┆    1.9 │
│    04 ┆  68 ┆  1.7 ┆   145 ┆    3.5 │
│    05 ┆  35 ┆  0.8 ┆   180 ┆    4.4 │
│    06 ┆ 494 ┆ 12.0 ┆   674 ┆   16.4 │
│    08 ┆  69 ┆  1.7 ┆   743 ┆   18.0 │
│    09 ┆  34 ┆  0.8 ┆   777 ┆   18.9 │
│    10 ┆  11 ┆  0.3 ┆   788 ┆   19.1 │
│    11 ┆   1 ┆  0.0 ┆   789 ┆   19.2 │
│    12 ┆ 342 ┆  8.3 ┆ 1,131 ┆   27.5 │
│    13 ┆ 108 ┆  2.6 ┆ 1,239 ┆   30.1 │
│    15 ┆  33 ┆  0.8 ┆ 1,272 ┆   30.9 │
│    16 ┆  25 ┆  0.6 ┆ 1,297 ┆   31.5 │
│    17 ┆ 223 ┆  5.4 ┆ 1,520 ┆   36.9 │
│    18 ┆  83 ┆  2.0 ┆ 1,603 ┆   38.9 │
│    19 ┆  38 ┆  0.9 ┆ 1,641 ┆   39.8 │
│    20 ┆  34 ┆  0.8 ┆ 1,675 ┆   40.7 │
│    21 ┆  41 ┆  1.0 ┆ 1,716 ┆   41.7 │
│    22 ┆  57 ┆  1.4 ┆ 1,773 ┆   43.0 │
│    23 ┆  12 ┆  0.3 ┆ 1,785 ┆   43.3 │
│    24 ┆ 135 ┆  3.3 ┆ 1,920 ┆   46.6 │
│    25 ┆  89 ┆  2.2 ┆ 2,009 ┆   48.8 │
│    26 ┆  98 ┆  2.4 ┆ 2,107 ┆   51.1 │
│    27 ┆  98 ┆  2.4 ┆ 2,205 ┆   53.5 │
│    28 ┆  39 ┆  0.9 ┆ 2,244 ┆   54.5 │
│    29 ┆  81 ┆  2.0 ┆ 2,325 ┆   56.4 │
│    30 ┆   8 ┆  0.2 ┆ 2,333 ┆   56.6 │
│    31 ┆  17 ┆  0.4 ┆ 2,350 ┆   57.0 │
│    32 ┆  24 ┆  0.6 ┆ 2,374 ┆   57.6 │
│    33 ┆  14 ┆  0.3 ┆ 2,388 ┆   58.0 │
│    34 ┆ 155 ┆  3.8 ┆ 2,543 ┆   61.7 │
│    35 ┆  23 ┆  0.6 ┆ 2,566 ┆   62.3 │
│    36 ┆ 196 ┆  4.8 ┆ 2,762 ┆   67.0 │
│    37 ┆  95 ┆  2.3 ┆ 2,857 ┆   69.3 │
│    38 ┆   9 ┆  0.2 ┆ 2,866 ┆   69.6 │
│    39 ┆ 185 ┆  4.5 ┆ 3,051 ┆   74.1 │
│    40 ┆  44 ┆  1.1 ┆ 3,095 ┆   75.1 │
│    41 ┆  66 ┆  1.6 ┆ 3,161 ┆   76.7 │
│    42 ┆  84 ┆  2.0 ┆ 3,245 ┆   78.8 │
│    44 ┆  11 ┆  0.3 ┆ 3,256 ┆   79.0 │
│    45 ┆  61 ┆  1.5 ┆ 3,317 ┆   80.5 │
│    46 ┆  12 ┆  0.3 ┆ 3,329 ┆   80.8 │
│    47 ┆  61 ┆  1.5 ┆ 3,390 ┆   82.3 │
│    48 ┆ 262 ┆  6.4 ┆ 3,652 ┆   88.6 │
│    49 ┆  64 ┆  1.6 ┆ 3,716 ┆   90.2 │
│    50 ┆   4 ┆  0.1 ┆ 3,720 ┆   90.3 │
│    51 ┆ 127 ┆  3.1 ┆ 3,847 ┆   93.4 │
│    53 ┆ 128 ┆  3.1 ┆ 3,975 ┆   96.5 │
│    54 ┆  16 ┆  0.4 ┆ 3,991 ┆   96.9 │
│    55 ┆  90 ┆  2.2 ┆ 4,081 ┆   99.1 │
│    56 ┆  11 ┆  0.3 ┆ 4,092 ┆   99.3 │
│    72 ┆  28 ┆  0.7 ┆ 4,120 ┆  100.0 │
└───────┴─────┴──────┴───────┴────────┘

In [9]:

Copied!





# Weighted by population
response.tabulate(
    "state",
    weight_var="B17001_001E",
    where="B17001_001E > 10_000"
)
# Weighted by population
response.tabulate(
    "state",
    weight_var="B17001_001E",
    where="B17001_001E > 10_000"
)

shape: (52, 5)
┌───────┬────────────┬──────┬─────────────┬────────┐
│ state ┆          n ┆  pct ┆        cumn ┆ cumpct │
╞═══════╪════════════╪══════╪═════════════╪════════╡
│    01 ┆  2,355,550 ┆  1.2 ┆   2,355,550 ┆    1.2 │
│    02 ┆    403,280 ┆  0.2 ┆   2,758,830 ┆    1.4 │
│    04 ┆  6,119,211 ┆  3.0 ┆   8,878,041 ┆    4.4 │
│    05 ┆  1,359,339 ┆  0.7 ┆  10,237,380 ┆    5.1 │
│    06 ┆ 34,506,198 ┆ 17.1 ┆  44,743,578 ┆   22.2 │
│    08 ┆  4,280,170 ┆  2.1 ┆  49,023,748 ┆   24.3 │
│    09 ┆  1,698,368 ┆  0.8 ┆  50,722,116 ┆   25.2 │
│    10 ┆    253,946 ┆  0.1 ┆  50,976,062 ┆   25.3 │
│    11 ┆    647,874 ┆  0.3 ┆  51,623,936 ┆   25.6 │
│    12 ┆ 14,801,907 ┆  7.3 ┆  66,425,843 ┆   33.0 │
│    13 ┆  4,135,032 ┆  2.1 ┆  70,560,875 ┆   35.0 │
│    15 ┆  1,016,957 ┆  0.5 ┆  71,577,832 ┆   35.5 │
│    16 ┆  1,075,551 ┆  0.5 ┆  72,653,383 ┆   36.1 │
│    17 ┆  9,076,740 ┆  4.5 ┆  81,730,123 ┆   40.6 │
│    18 ┆  3,681,396 ┆  1.8 ┆  85,411,519 ┆   42.4 │
│    19 ┆  1,556,593 ┆  0.8 ┆  86,968,112 ┆   43.2 │
│    20 ┆  1,778,954 ┆  0.9 ┆  88,747,066 ┆   44.1 │
│    21 ┆  1,795,677 ┆  0.9 ┆  90,542,743 ┆   44.9 │
│    22 ┆  2,090,938 ┆  1.0 ┆  92,633,681 ┆   46.0 │
│    23 ┆    311,963 ┆  0.2 ┆  92,945,644 ┆   46.1 │
│    24 ┆  4,217,822 ┆  2.1 ┆  97,163,466 ┆   48.2 │
│    25 ┆  4,343,845 ┆  2.2 ┆ 101,507,311 ┆   50.4 │
│    26 ┆  4,138,955 ┆  2.1 ┆ 105,646,266 ┆   52.4 │
│    27 ┆  3,616,611 ┆  1.8 ┆ 109,262,877 ┆   54.2 │
│    28 ┆  1,033,697 ┆  0.5 ┆ 110,296,574 ┆   54.7 │
│    29 ┆  3,057,142 ┆  1.5 ┆ 113,353,716 ┆   56.3 │
│    30 ┆    401,363 ┆  0.2 ┆ 113,755,079 ┆   56.5 │
│    31 ┆  1,127,077 ┆  0.6 ┆ 114,882,156 ┆   57.0 │
│    32 ┆  2,826,147 ┆  1.4 ┆ 117,708,303 ┆   58.4 │
│    33 ┆    450,713 ┆  0.2 ┆ 118,159,016 ┆   58.7 │
│    34 ┆  4,230,820 ┆  2.1 ┆ 122,389,836 ┆   60.8 │
│    35 ┆  1,294,092 ┆  0.6 ┆ 123,683,928 ┆   61.4 │
│    36 ┆ 13,493,510 ┆  6.7 ┆ 137,177,438 ┆   68.1 │
│    37 ┆  5,035,190 ┆  2.5 ┆ 142,212,628 ┆   70.6 │
│    38 ┆    425,518 ┆  0.2 ┆ 142,638,146 ┆   70.8 │
│    39 ┆  6,215,141 ┆  3.1 ┆ 148,853,287 ┆   73.9 │
│    40 ┆  2,353,232 ┆  1.2 ┆ 151,206,519 ┆   75.1 │
│    41 ┆  2,763,329 ┆  1.4 ┆ 153,969,848 ┆   76.4 │
│    42 ┆  3,711,999 ┆  1.8 ┆ 157,681,847 ┆   78.3 │
│    44 ┆    585,058 ┆  0.3 ┆ 158,266,905 ┆   78.6 │
│    45 ┆  1,751,610 ┆  0.9 ┆ 160,018,515 ┆   79.4 │
│    46 ┆    428,240 ┆  0.2 ┆ 160,446,755 ┆   79.6 │
│    47 ┆  3,476,446 ┆  1.7 ┆ 163,923,201 ┆   81.4 │
│    48 ┆ 19,673,491 ┆  9.8 ┆ 183,596,692 ┆   91.1 │
│    49 ┆  2,679,413 ┆  1.3 ┆ 186,276,105 ┆   92.5 │
│    50 ┆     83,205 ┆  0.0 ┆ 186,359,310 ┆   92.5 │
│    51 ┆  4,802,864 ┆  2.4 ┆ 191,162,174 ┆   94.9 │
│    53 ┆  5,278,869 ┆  2.6 ┆ 196,441,043 ┆   97.5 │
│    54 ┆    323,917 ┆  0.2 ┆ 196,764,960 ┆   97.7 │
│    55 ┆  3,118,085 ┆  1.5 ┆ 199,883,045 ┆   99.2 │
│    56 ┆    279,046 ┆  0.1 ┆ 200,162,091 ┆   99.4 │
│    72 ┆  1,298,264 ┆  0.6 ┆ 201,460,355 ┆  100.0 │
└───────┴────────────┴──────┴─────────────┴────────┘