A comprehensive skill for downloading US Census data and creating demographic maps showing population density, educational attainment, age distribution, race/ethnicity, income levels, and more.
- Comprehensive Demographic Data: Access population, age, race, education, income, housing, and employment statistics
- Multiple Geographic Levels: State, county, and census tract level data
- Beautiful Visualizations: Create choropleth maps with customizable color schemes
- Automatic Data Integration: Seamlessly combines Census API data with geographic boundaries
- Summary Statistics: Generate detailed statistical summaries of your data
- Export Capabilities: Save maps as high-resolution images and data as CSV files
This skill is available as a plugin in the baofeng-skills marketplace. To install it:
- Add the
baofeng-skillsmarketplace to Claude Code (if you haven't already):
claude plugin marketplace add baofeng-skills https://github.com/baofeng-dong/financial-dashboard-skill.git- Install the plugin:
claude plugin install census-demographics@baofeng-skills- Verify the plugin is enabled in
~/.claude/settings.json:
{
"enabledPlugins": {
"census-demographics@baofeng-skills": true
}
}- Restart Claude Code. The skill will automatically activate when you ask census or demographics-related questions — no slash command needed. Just ask naturally:
Show me a population density map of Texas counties
If you prefer to install the skill manually:
pip install -r requirements.txt- Visit https://api.census.gov/data/key_signup.html
- Sign up for a free API key
- Set your API key as an environment variable:
export CENSUS_API_KEY='your_api_key_here'Or add it to your .bashrc or .zshrc for persistence:
echo 'export CENSUS_API_KEY="your_api_key_here"' >> ~/.bashrc
source ~/.bashrcCopy the skill.md file to your Claude Code skills directory:
mkdir -p ~/.claude/skills/census-demographics
cp skill.md ~/.claude/skills/census-demographics/In Claude Code, the skill will be available automatically, or you can reference it directly in your conversation.
Show me a population density map of California counties
The skill will:
- Fetch population data for California counties
- Download county boundary geometries
- Calculate population density
- Create and save a choropleth map
Compare bachelor's degree attainment rates across all US states
The skill will:
- Fetch education data from ACS 5-year estimates
- Calculate percentage with bachelor's degrees
- Create state-level choropleth map
- Generate summary statistics
Map median age by county in Texas
The skill will:
- Fetch age data for Texas counties
- Create visualization showing median age
- Provide statistical summary
Show me maps of population, median income, and education levels for counties in the Northeast
The skill will:
- Fetch multiple demographic variables
- Create a multi-panel map showing all three metrics
- Export data to CSV for further analysis
Create a detailed map of racial diversity in Cook County, Illinois at the tract level
The skill will:
- Fetch race/ethnicity data at census tract level
- Create high-resolution tract-level map
- Calculate diversity indices
- Total population
- Population density
- Median age
- Under 18 population
- Over 65 population
- Age cohorts
- White alone
- Black or African American
- American Indian and Alaska Native
- Asian
- Native Hawaiian and Pacific Islander
- Hispanic or Latino
- Two or more races
- High school graduate
- Some college
- Associate's degree
- Bachelor's degree
- Master's degree
- Professional degree
- Doctorate degree
- Median household income
- Per capita income
- Mean household income
- Total housing units
- Median home value
- Median rent
- Owner-occupied vs. renter-occupied
- Labor force participation
- Employment rate
- Unemployment rate
Common Census variable codes used by this skill:
| Category | Variable | Code |
|---|---|---|
| Population | Total | B01003_001E |
| Age | Median | B01002_001E |
| Race | White | B02001_002E |
| Race | Black | B02001_003E |
| Race | Asian | B02001_005E |
| Ethnicity | Hispanic | B03003_003E |
| Education | Bachelor's | B15003_022E |
| Income | Median HH | B19013_001E |
| Housing | Median Value | B25077_001E |
For a complete list of variables, visit: https://api.census.gov/data/2021/acs/acs5/variables.html
- 50 states + DC + Puerto Rico
- Best for national comparisons
- Fast to process
- ~3,200 counties nationwide
- Good balance of detail and performance
- Most commonly used level
- ~84,000 tracts nationwide
- Neighborhood-level detail
- Requires state/county specification
- Slower to process for large areas
When you run the skill, it creates a timestamped output directory with:
- demographic_map.png - High-resolution map (300 DPI)
- summary_statistics.txt - Descriptive statistics
- census_data.csv - Raw data table
- README.txt - Explanation of the visualization
-
Start Broad, Then Narrow: Begin with state or county level, then drill down to tracts if needed
-
Specify Time Period: ACS 5-year estimates are most detailed but lag by 2-3 years
-
Use Appropriate Color Schemes:
- Sequential (YlOrRd, Blues) for single-variable continuous data
- Diverging (RdBu) for data with meaningful midpoint
- Categorical (Set3) for discrete categories
-
Consider Data Privacy: Block-level data may be suppressed for small populations
-
Combine Multiple Indicators: Create multi-panel maps to show relationships
- Ensure
CENSUS_API_KEYenvironment variable is set - Verify the key is valid at https://api.census.gov/data.html
- Check internet connection (downloads shapefiles from Census Bureau)
- Verify the year is valid (typically 2010-present)
- Check FIPS codes are correct
- Verify variable code exists for the specified year/dataset
- Some variables only available at certain geographic levels
- Try a higher-level geography (counties instead of tracts)
- Use classification schemes (quantiles, natural breaks)
- Filter to a specific region instead of entire US
You can specify custom Census variable codes:
Fetch variable B25064_001E (median rent) for all counties and create a map
Compare median household income between 2015 and 2021 for California counties
Calculate and map the percentage of population with graduate degrees for each state
Create a population map using the 'viridis' color scheme
You can also use the modules directly in Python scripts:
from census_fetch import CensusDataFetcher
from map_visualize import CensusMapVisualizer
# Fetch data
fetcher = CensusDataFetcher(api_key='your_key')
data = fetcher.fetch_county_data(
variables=['B01003_001E'], # Total population
state_fips='06', # California
year=2021
)
# Create visualization
viz = CensusMapVisualizer(output_dir='./my_maps')
counties = viz.load_geometries(level='county')
merged = viz.merge_data(counties, data)
fig, ax = viz.create_choropleth(
merged,
column='B01003_001E',
title='California County Population',
cmap='YlOrRd'
)
viz.save_map(fig, 'ca_population')All data comes from the US Census Bureau:
-
American Community Survey (ACS): Most detailed demographic data
- 5-Year Estimates: Most reliable, covers all geographies
- 1-Year Estimates: Most current, only for areas with 65k+ population
-
Decennial Census: Complete population count every 10 years (2010, 2020)
-
TIGER/Line Shapefiles: Geographic boundaries updated annually
- Census API Documentation: https://www.census.gov/data/developers/data-sets.html
- Variable Search: https://api.census.gov/data.html
- Geography Reference: https://www.census.gov/programs-surveys/geography.html
- ACS Handbook: https://www.census.gov/programs-surveys/acs/guidance.html
This skill uses publicly available US Census data. Census Bureau data are free from copyright restrictions.
For issues with this skill:
- Check the troubleshooting section above
- Verify your Census API key is valid
- Consult the Census Bureau's data documentation
- Ask Claude Code for help with specific error messages
Version: 1.0.0 Last Updated: 2025 Compatible with: Claude Code