CIV.IQ

Civic intelligence from government sources, organized for public use.

civdotiq.org • API Reference • Contribute • License

What this is

A civic intelligence platform. Enter an address to find your federal and state representatives, with voting records, federal campaign finance, committee assignments, legislative activity, and machine-learning-powered analysis of money-in-politics patterns. Local-government coverage is limited to a pilot list of 10 cities.

All data comes from government APIs. All analysis is statistical, with confidence scores and methodology disclosed. If data is unavailable, the interface and the response payload say so explicitly. Nothing is fabricated.

Honest coverage matrix: docs/COVERAGE.md. It is the canonical answer to "what does CIV.IQ actually cover?" — every other claim in this README defers to that page.

What it does

Representatives: Federal and state legislators with photos, contact info, committee assignments, and voting records.

Campaign Finance: Federal only — FEC contributions, PAC spending, expenditure tracking, and donor sector analysis. State campaign finance is not currently available (FollowTheMoney.org is in maintenance mode during the OpenSecrets merger).

Intelligence Layer: Statistical analyzers that cross-reference voting records with campaign finance, lobbying filings, stock trades, and committee jurisdictions to surface patterns of potential influence. Every insight carries a confidence score, methodology note, and correlation-not-causation disclaimer.

Vote Prediction: An XGBoost model (trained on historical roll call data, exported to ONNX) predicts how representatives are likely to vote on upcoming legislation, with an independence score measuring deviation from party line.

Money Report: Address-based lookup that traces the path from campaign contributions through committee assignments to legislative outcomes for your specific representatives.

Sector Leaderboard: Rankings of legislators by industry sector, showing which members receive the most from a given industry relative to their peers.

Regulations & Comment Periods: Federal Register integration for proposed rules, final rules, executive orders, and open public comment periods.

State Legislatures: All 50 states via OpenStates — legislators, bills, committees, votes, and calendars. Interactive district boundary maps for all 7,383 state legislative districts. State-level campaign finance, lobbying, and stock-trade data are not part of state coverage.

Local Government: City council data for 10 pilot cities via Legistar (Austin, Boston, Chicago, Denver, Detroit, Minneapolis, Oakland, Philadelphia, Portland, Seattle). Outside this list, local-government routes return dataQuality: 'unavailable' rather than empty arrays. There is no national local-government API; coverage expands one city at a time.

District Intelligence: Demographics, economic indicators (BLS employment data), federal spending (USASpending), infrastructure metrics, and bills ranked by relevance to each congressional district.

Nostr Publishing: Civic events (new bills, votes, hearings) are signed and published to the Nostr network for decentralized, verifiable distribution.

Developer integrations

Data sources

The table lists the primary sources. Additional federal agency datasets — CDC PLACES, CMS, Medicaid, FEMA, FBI UCR, FDIC, VA, Treasury, CFPB, NHTSA, College Scorecard, and more — power district and intelligence features, for 26 live government data sources in total. The canonical, continuously verified list is docs/COVERAGE.md.

No data is fabricated, scraped, or generated.

Setup

git clone https://github.com/civdotiq/civ.iq.git
cd civ.iq
npm install
cp .env.example .env.local

Add API keys to .env.local. All are free:

# Required
CONGRESS_API_KEY=       # api.congress.gov/sign-up
FEC_API_KEY=            # api.open.fec.gov/developers
CENSUS_API_KEY=         # api.census.gov/data/key_signup.html
OPENSTATES_API_KEY=     # openstates.org/accounts/profile

# Recommended
UPSTASH_REDIS_REST_URL= # upstash.com (caching)
UPSTASH_REDIS_REST_TOKEN=
GOOGLE_GENERATIVE_AI_API_KEY= # aistudio.google.com/apikey (AI summaries)

# Optional (enhanced features)
FRED_API_KEY=           # fredaccount.stlouisfed.org/apikeys
DATA_GOV_API_KEY=       # api.data.gov/signup (Regulations.gov)
GOVINFO_API_KEY=        # api.govinfo.gov/docs

See .env.example for the full list, including Nostr publishing and ActivityPub federation.

npm run dev

Verify at localhost:3000/api/health.

Structure

src/
├── app/
│   ├── api/                  # 181 API routes
│   └── (civic)/              # Pages (representatives, districts, legislation, etc.)
├── components/
│   ├── intelligence/         # Insight cards, leaderboards, influence chains
│   └── ...                   # Shared UI, search, visualizations
├── features/                 # Feature modules
│   ├── campaign-finance/
│   ├── legislation/
│   ├── representatives/
│   └── state-legislature/
├── lib/
│   ├── intelligence/         # Analyzers, ML models, embeddings, entity resolution
│   ├── nostr/                # Nostr event signing and relay publishing
│   ├── data-sources/         # Federal Register, FRED, SEC, lobbying services
│   └── ...                   # API clients, services, utilities
├── hooks/                    # Custom React hooks
└── types/                    # TypeScript definitions
packages/
├── sdk/                      # @civiq/sdk (TypeScript API client)
├── civic-statistics/         # @civiq/civic-statistics (confidence scoring, correlation)
└── entity-resolution/        # @civiq/entity-resolution (entity matching, deduplication)

Stack

Next.js 16, React 18, TypeScript (strict), Tailwind CSS, SWR, Zustand, MapLibre GL, D3.js, Recharts, Redis (Upstash + ioredis), Zod, simple-statistics, HuggingFace Transformers (small models), Google Gemini AI, nostr-tools.

Intelligence layer

12 statistical analyzers cross-reference government data domains: