census-lookup

A Python library for mapping US addresses to Census data locally, without relying on rate-limited APIs. Supports Census 2020 (PL 94-171) and American Community Survey (ACS) 5-Year Estimates.

Features

• Fully offline geocoding using TIGER Address Range files (~95% match rate)
• Lazy per-state data downloading - only download data for states you need
• Census data at ALL geographic levels - block, block group, tract, county, and state in a single lookup
• Two Census data sources:
  • PL 94-171 (Redistricting Data): Population, race, housing counts at block level
  • ACS 5-Year Estimates: Income, education, employment, housing characteristics at tract level
• Efficient batch processing for large address lists
• CLI and Python API - use from command line or in your code

Installation

# Using uv (recommended)
uv add census-lookup

# Using pip
pip install census-lookup

Quick Start

CLI (no install required)

# Look up a single address (auto-downloads data as needed)
uvx census-lookup lookup "123 Main St, Los Angeles, CA 90012"

# Include specific census variables
uvx census-lookup lookup "123 Main St, Los Angeles, CA 90012" -v P1_001N -v H1_001N

# Process a batch file (use -l to set output level for CSV columns)
uvx census-lookup batch input.csv output.csv --address-column addr -l tract

# Pre-download data for states (optional - data downloads automatically)
uvx census-lookup download CA TX NY

# List available census variables
uvx census-lookup variables

# Show cache info
uvx census-lookup info

Example Output

$ uvx census-lookup lookup "1600 Pennsylvania Avenue NW, Washington, DC 20500" -v P1_001N

{
  "input_address": "1600 Pennsylvania Avenue NW, Washington, DC 20500",
  "matched_address": "Pennsylvania Ave NW",
  "latitude": 38.898761,
  "longitude": -77.035117,
  "match_type": "interpolated",
  "match_score": 0.9,
  "state_fips": "11",
  "county_fips": "11001",
  "tract": "11001010100",
  "block_group": "110010101003",
  "block": "110010101003014",
  "P1_001N": {
    "block": 19.0,
    "block_group": 963.0,
    "tract": 2699.0,
    "county": 689545.0,
    "state": 689545.0
  }
}

Census data is returned at all geographic levels in a single lookup. Each variable contains values aggregated at block, block group, tract, county, and state levels.

With ACS variables (median income, home value):

$ uvx census-lookup lookup "1600 Pennsylvania Avenue NW, Washington, DC 20500" \
    -v B19013_001E -v B25077_001E

{
  "...": "...",
  "B19013_001E": {
    "tract": 72500.0
  },
  "B25077_001E": {
    "tract": 485000.0
  }
}

ACS variables are available at tract level and above.

Python API

from census_lookup import CensusLookup

# Initialize (first use will download data for the state)
lookup = CensusLookup(
    variables=["P1_001N", "H1_001N"],  # Population, Housing units
)

# Single address lookup
result = await lookup.geocode("123 Main St, Los Angeles, CA 90012")
print(f"Block GEOID: {result.block}")
print(f"Block Population: {result.census_data['P1_001N']['block']}")
print(f"Tract Population: {result.census_data['P1_001N']['tract']}")

# Batch processing
import pandas as pd
df = pd.read_csv("addresses.csv")
results = await lookup.geocode_batch(df["address"], progress=True)

Geographic Levels

Census Variables

PL 94-171 (Redistricting Data)

Available at block level and above. Includes:

• P1: Race (total population, by race categories)
• P2: Hispanic/Latino by Race
• P3: Race for Population 18+ (voting age)
• P4: Hispanic/Latino 18+
• H1: Housing Units (total, occupied, vacant)

# Use variable groups
lookup = CensusLookup(variable_groups=["population", "housing"])

# Or specify individual variables
lookup = CensusLookup(variables=["P1_001N", "P1_003N", "H1_001N"])

ACS 5-Year Estimates (American Community Survey)

Available at tract level and above. Includes richer demographic data:

Over 100+ ACS variables available. Run uvx census-lookup variables --acs for the full list

from census_lookup import CensusLookup, list_acs_variable_groups

# See available ACS variable groups
print(list_acs_variable_groups())

# Use ACS variables with your lookup
lookup = CensusLookup(
    variables=["P1_001N"],  # PL 94-171 population
    acs_variables=["B19013_001E", "B25077_001E"],  # Median income, home value
    # Or use variable groups:
    # acs_variable_groups=["income", "housing"],
)

result = await lookup.geocode("123 Main St, Los Angeles, CA 90012")
# PL 94-171 data available at all levels
print(f"Block Population: {result.census_data['P1_001N']['block']}")
# ACS data available at tract level
print(f"Median Income: ${result.census_data['B19013_001E']['tract']:,}")

Note: ACS data is available at tract level and above. When you request ACS variables, they will appear in the nested output with tract (and higher) levels populated.

Data Storage

Data is cached in ~/.census-lookup/:

~/.census-lookup/
├── catalog.json           # Tracks downloaded data
├── tiger/
│   ├── addrfeat/         # Address range features
│   └── blocks/           # Block polygons
└── census/
    ├── pl94171/          # PL 94-171 data
    └── acs5/             # ACS 5-Year data
        └── tract/        # ACS at tract level

Typical storage per state: 100-300MB (TIGER + PL 94-171), plus ~10-50MB for ACS

How It Works

1. Parse address using the usaddress library
2. Normalize street name for TIGER matching
3. Match to TIGER Address Range segment
4. Interpolate coordinates along the street segment
5. Spatial lookup using rtree index to find containing census block
6. Join census data using DuckDB for efficient queries

Data Sources

All data is downloaded from official US Census Bureau sources:

• TIGER/Line Shapefiles: Geographic boundaries and address ranges

  • https://www.census.gov/geographies/mapping-files/time-series/geo/tiger-line-file.html
  • Address Range Feature files (ADDRFEAT) for geocoding
  • Block shapefiles for spatial lookups

• PL 94-171 Redistricting Data: Population and housing counts

  • https://www.census.gov/programs-surveys/decennial-census/about/rdo/summary-files.html
  • Available at block level and above

• American Community Survey (ACS) 5-Year Estimates: Socioeconomic data

  • https://www.census.gov/programs-surveys/acs
  • Available at tract level and above
  • Accessed via Census API: https://api.census.gov

Development

# Clone and install with uv
git clone https://github.com/yolodex-ai/census-lookup.git
cd census-lookup
uv sync --all-extras

# Run unit tests (fast, no network required)
uv run pytest tests/unit -v

# Run functional tests (downloads real data, slower)
uv run pytest tests/functional -v -s

# Run all tests
uv run pytest tests/ -v

# Run linting
uv run ruff check src/

License

MIT