102 lines
3.6 KiB
Markdown
102 lines
3.6 KiB
Markdown
# US Common Metrics
|
|
|
|
**A comprehensive catalog of the most important U.S. economic and social indicators.**
|
|
|
|
## Purpose
|
|
|
|
This dataset provides a single source of truth for understanding the current state of the U.S. economy and society. Instead of navigating dozens of government websites with different update schedules and formats, you get:
|
|
|
|
- **One master document** with 60+ metrics and their current values
|
|
- **Full provenance** - every number traced back to its authoritative source
|
|
- **Update automation** - TypeScript scripts keep metrics current
|
|
- **Transparency** - complete methodology documentation per Substrate philosophy
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
# View current metrics
|
|
cat US-Common-Metrics.md
|
|
|
|
# Get parseable data
|
|
cat us-metrics-current.csv
|
|
|
|
# Update all metrics (requires API keys)
|
|
bun run update.ts
|
|
```
|
|
|
|
## Contents
|
|
|
|
| File | Description |
|
|
|------|-------------|
|
|
| `US-Common-Metrics.md` | Master document with all metrics, values, sources |
|
|
| `us-metrics-current.csv` | Current values in parseable format |
|
|
| `us-metrics-historical.csv` | Historical time series |
|
|
| `source.md` | Methodology, data lineage, source links |
|
|
| `update.ts` | Automation script to refresh all metrics |
|
|
|
|
## Metric Categories
|
|
|
|
1. **Economic Output & Growth** - GDP, industrial production, retail sales
|
|
2. **Inflation & Prices** - CPI, PCE, gas prices, oil prices
|
|
3. **Employment & Labor** - Unemployment, payrolls, jobless claims, quit rate
|
|
4. **Housing** - Home prices, mortgage rates, housing starts
|
|
5. **Consumer & Personal Finance** - Sentiment, saving rate, credit
|
|
6. **Financial Markets** - Interest rates, stock indices, volatility
|
|
7. **Trade & International** - Trade balance, USD index
|
|
8. **Government & Fiscal** - Federal debt, budget, spending
|
|
9. **Demographics & Social** - Population, inequality, poverty
|
|
10. **Health & Crisis** - Deaths of despair, air quality, life expectancy
|
|
|
|
## Data Sources
|
|
|
|
All data comes from authoritative government and institutional sources:
|
|
|
|
| Source | Metrics | API |
|
|
|--------|---------|-----|
|
|
| FRED (Federal Reserve) | Most economic indicators | Free API |
|
|
| EIA (Energy Information Admin) | Gas prices, oil, energy | Free API |
|
|
| Treasury FiscalData | Federal debt, budget, spending | Free API |
|
|
| BLS (Bureau of Labor Statistics) | Employment, wages | Free API |
|
|
| Census Bureau | Demographics, housing starts | Free API |
|
|
| CDC WONDER | Mortality data | Free access |
|
|
| EPA AQS | Air quality | Free API |
|
|
|
|
See `source.md` for full documentation of each data source.
|
|
|
|
## Update Schedule
|
|
|
|
| Frequency | Metrics |
|
|
|-----------|---------|
|
|
| Daily | Treasury yields, oil prices, stock indices |
|
|
| Weekly | Jobless claims, gas prices, mortgage rates |
|
|
| Monthly | CPI, employment, retail sales, housing data |
|
|
| Quarterly | GDP, home prices, debt service ratio |
|
|
| Annual | Population, GINI, poverty rate, mortality |
|
|
|
|
## Requirements
|
|
|
|
- [Bun](https://bun.sh) runtime for automation scripts
|
|
- API keys (all free):
|
|
- `FRED_API_KEY` - https://fred.stlouisfed.org/docs/api/api_key.html
|
|
- `EIA_API_KEY` - https://www.eia.gov/opendata/register.php
|
|
- `CENSUS_API_KEY` - https://api.census.gov/data/key_signup.html
|
|
|
|
## Integration with Substrate
|
|
|
|
This dataset supports other Substrate components:
|
|
|
|
- **Claims** - Back assertions with authoritative data
|
|
- **Arguments** - Reference specific metrics and trends
|
|
- **Problems** - Quantify the scale of issues (e.g., debt, inequality)
|
|
- **Solutions** - Track progress using ground-truth indicators
|
|
|
|
## Credits
|
|
|
|
**Created:** 2025-12-01
|
|
**Maintainer:** Daniel Miessler
|
|
**Sources:** Federal Reserve, BLS, Census Bureau, EIA, Treasury, CDC, EPA
|
|
|
|
---
|
|
|
|
**Mission**: Build a trusted foundation of ground-truth data to support human understanding and progress.
|