# BenchmarkUSA - Data Application - LLM Context

> Financial transparency for America's local governments.

## About This Application

BenchmarkUSA is a civic-tech web application that collects, verifies, and benchmarks financial and operational data from local governments across multiple states. It ingests bulk data files (CSV and Excel) from state comptroller offices and the US Census Bureau to provide up to 30 years of fiscal trend analysis.

## Coverage

- **Entities:** 53,000+ local governments across 50 states + DC (cities, counties, towns, villages, school districts, CDPs)
- **Observations:** Millions of data points (1995-2025)
- **Data sources:**
  - NYS Office of the State Comptroller — Annual Financial Reports (CSV), Fiscal Stress Monitoring System (Excel)
  - NYC Comptroller — Annual Comprehensive Financial Report (Ten Year Trend tables, covering FY 2016-2025)
  - California State Controller's Office — City financial data via Socrata API (FY 2003-2024)
  - US Census Bureau — American Community Survey 5-year estimates (API)

## Key Pages

- Landing Page: https://benchmarkusa.org (state-level financial rankings)
- New York: https://benchmarkusa.org/ny (NY state landing)
- California: https://benchmarkusa.org/ca (CA state landing)
- Governments: https://benchmarkusa.org/ny/entities (browse all entities)
- Stress Analysis: https://benchmarkusa.org/stress-analysis (FSMS fiscal/socio-demographic stress scatter charts)
- Compliance: https://benchmarkusa.org/non-filers (filing compliance and FSMS participation)
- School Districts: https://benchmarkusa.org/school-districts/compare (spending and enrollment comparisons)
- Counties: https://benchmarkusa.org/counties/compare (political composition vs. fiscal health)
- Methodology: https://benchmarkusa.org/methodology (data sources and calculations)

## Related Sites

- Project Blog: https://benchmarkusa.org/blog
- MCP Server: https://mcp.benchmarkusa.org/mcp (Model Context Protocol API for querying data programmatically)
- MCP Documentation: https://benchmarkusa.org/blog/mcp

## Data Model

### Entity
A government body (city, town, village, county, or school district). Entities may have parent-child relationships representing fiscal dependency. Example: Yonkers Public Schools is fiscally dependent on the City of Yonkers. NYC is included with data from its own Comptroller's ACFR.

### Document
A source record tied to an entity and fiscal year. Sources include bulk data imports (CSV/Excel files from OSC and NYC Comptroller), PDF documents (ACFRs), and web sources (Census API).

### Metric
A standardized definition of a data point with label, value type, display format, and categorization (account_type, level_1_category, level_2_category).

### Observation
A single extracted fact linking an entity, document, metric, value, fiscal year, and verification status.

## Key Metrics

- **Fund Balance %** — Available Fund Balance / Total Revenue (fiscal cushion)
- **Debt Service %** — Total Debt Service / Total Revenue (debt burden)
- **Per-Capita Spending** — Total Expenditures / Population
- **FSMS Scores** — NYS Comptroller Fiscal Stress Monitoring System scores (fiscal and environmental, 0-100 scale)

## API Access

The MCP (Model Context Protocol) server at https://mcp.benchmarkusa.org/mcp provides programmatic access to all data. Compatible with Claude Desktop, Cursor, and other MCP clients.

## Technology

- Built with Ruby on Rails 8 and PostgreSQL
- Deployed on DigitalOcean via Kamal
- Document storage on DigitalOcean Spaces (S3-compatible)
- Charts rendered with Chart.js

## Contact

- Email: contact@benchmarkusa.org

## Data License

All financial and demographic data presented on this site is derived from public domain government sources (NYS Comptroller, NYC Comptroller, CA State Controller, US Census Bureau) and may be freely used with attribution to both the original source and BenchmarkUSA.