Neighborhood Report Generator

Overview

A Python backend service that generates detailed neighborhood intelligence reports on demand. Given a ZIP code, city, county, or census tract, it fetches demographic data from the US Census Bureau (ACS 5-year estimates) and institution counts from OpenStreetMap, then produces both a web-viewable report and a downloadable PDF.

Designed for community organizations, nonprofits, and researchers who need actionable neighborhood data without a data science background.

What It Reports

Demographics (from Census ACS)

Total population, median age, household size
Poverty rate, median household income
Educational attainment (HS diploma, bachelor’s, graduate)
Foreign-born population, non-English speaking households
Race/ethnicity breakdown, single-parent households, elderly households

Community Institutions (from OpenStreetMap)

Churches and religious organizations
Elementary, middle, and high schools; colleges and universities
Libraries, community centers, hospitals and clinics
Fire stations, social service facilities

AI-Generated Overview A single prose paragraph contextualizing the numbers for a non-technical audience — generated by Claude Haiku and cached per geography.

Architecture

Two report tiers:
├── Executive Summary: Demographic cards + Community Needs + AI overview
└── In-Depth: Full charts + trend breakdowns (future)

Caching:
└── SQLModel (SQLite) stores reports by geography + ACS vintage year
    Reports are never re-fetched until Census releases new data

Output:
├── Web view: Rendered HTML in browser
└── PDF: WeasyPrint converts same HTML → styled PDF

Technology Stack

Category	Tools
Backend	Python, FastAPI
Census Data	censusdis library (ACS REST API)
Map Data	overpy (OpenStreetMap Overpass API)
PDF Generation	WeasyPrint
Database	SQLModel, SQLite
AI Prose	Claude Haiku (claude-haiku-4-5)
Charts	matplotlib

Design Philosophy

Hybrid AI: Only the Overview paragraph uses Claude — everything else is deterministic. Community Needs flags (e.g., “high poverty rate”) use rule-based thresholds so the report is reproducible and auditable. The AI call is cached so each geography only pays the cost once.

Lay-person readability: Every stat includes a plain-language label. The Overview contextualizes numbers in terms of what they mean for a community organization, not just what they are.

← Back to Projects