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 (city/county) government: not covered. Local records lack a shared standard or central source; CIV.IQ intends to add them only once a verified public source exists.
Data comes from official government records. Most are read straight from the agency's API or bulk files; some are read through named open datasets, such as OpenStates for state legislatures and the Congress Trading Monitor for parsed STOCK Act filings. 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.
Money Report: Address-based lookup that traces the path from campaign contributions through committee assignments to legislative outcomes for your specific representatives.
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, and calendars. Per-legislator vote history is in progress. 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: Not covered (city/county). Local records lack a shared standard or central source; CIV.IQ intends to add them only once a verified public source exists.
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
| Integration | What it provides |
|---|
| OpenAPI spec | 39 endpoints, 38 schemas — generate clients in any language |
| @civiq/sdk | Zero-dependency TypeScript client (npm install @civiq/sdk) |
| MCP server | 46 tools for AI assistants (Claude, Cursor, etc.) |
| Atom feeds | RSS-compatible feeds for bills, members, districts, committees |
| Embeddable widgets | Drop-in HTML for legislator cards, district lookup, bill status |
| llms.txt | AI-discoverable documentation |
Data sources
| Source | What it provides |
|---|
| Congress.gov v3 | Bills, members, committees, hearings |
| FEC.gov | Campaign contributions, expenditures, PAC filings |
| U.S. Census Bureau | Geocoding, demographics, district boundaries (TIGER) |
| Senate.gov XML | Senate floor votes, roll calls |
| House Clerk XML | House voting records |
| GovInfo | Hearing transcripts, legislative documents |
| Federal Register | Executive orders, proposed rules, comment periods |
| USASpending.gov v2 | Federal contracts, grants, awards by district |
| LDA (lda.gov) | Lobbying disclosure filings |
| Bureau of Labor Statistics | Employment, wages, labor force data |
| SEC EDGAR | Company filings |
| FRED | Federal Reserve economic indicators |
| Regulations.gov | Public comments on proposed rules |
| OpenStates (open dataset) | State legislators, bills, committees (all 50 states) |
| Congress Trading Monitor (open dataset) | STOCK Act trades for both chambers, parsed from the official House and Senate filings |
| Wikidata (open dataset) | State executives, state judiciary |
The table lists the primary sources. Other federal agency datasets (CDC PLACES, CMS, FEMA, FBI, FDIC, VA, Treasury, CFPB, NHTSA, EPA, College Scorecard, and more) power district and intelligence features. In total CIV.IQ reads 40 data sources: 29 government and 11 open datasets. The full list and the counting rule are in docs/COVERAGE.md.
No data is fabricated or generated. When a source is unavailable, the response says so.
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.
Verify at localhost:3000/api/health.
Structure
src/
├── app/
│ ├── api/ # API routes (public contract: /api/v1 + openapi.json)
│ └── (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
17 statistical analyzers cross-reference the federal data domains:
| Analyzer | What it computes |
|---|
| Finance-Jurisdiction Overlap | How far a member's donor industries overlap with their committees' jurisdictions |
| Vote-Finance Alignment | Share of a member's votes cast on bills in their top donor sectors |
| Party-Line Alignment | How often a member votes with their party's majority, from real roll calls |
| Temporal Vote Shifts | Quarter-by-quarter party-line alignment, alongside committee, contribution, and election events |
| Chamber Baselines | Chamber and party medians for votes cast, missed votes, and party alignment (peer baselines) |
| Lobbying Pipeline | Lobbying filings aimed at a committee, grouped by issue and matched to bills |
| PAC-to-Vote Tracing | A PAC's recipients and how they voted on the PAC's issue areas |
| Stock-Committee Overlap | STOCK Act trades in sectors a member's committees oversee |
| Stock Trade Leaderboard | Members ranked by trade count, trade value, or late filings |
| Sector Leaderboard | Each member's yes-vote rate on bills in one donor sector |
| Influence Chain | Lobbying → contribution → committee → matching bill → vote pathways |
| Influence Graph | Influence chains extended with related regulations, enforcement actions, and court cases |
| Temporal Proximity | Timing patterns, such as a contribution within 90 days of a related vote |
| Bill Intelligence | Sponsors' funding sources against a bill's policy sectors, plus bill-to-lobbying text similarity |
| Enforcement | EPA and OSHA enforcement actions and CFPB complaints, by sector, state, or organization |
| Federal Register Extraction | Industries, costs, and timelines extracted from rule preambles |
| Civic Brief | A one-page representative brief: statistics and pattern detection first, then an AI summary |
One more analyzer, the regulation analyzer, is in the code but not listed because nothing calls it.
Every insight carries: confidence score (0–1), data-as-of timestamp, methodology description, and a disclaimer that correlation does not imply causation.
ML pipeline
All models are small and run server-side through HuggingFace Transformers. Setting CIVIQ_ML_PIPELINES=off disables them.
- Text similarity: all-MiniLM-L6-v2 embeddings for bill-to-lobbying matching and bill sector classification
- Classification: nli-deberta-v3-xsmall for zero-shot bill sector classification
- Named entity recognition: distilbert-NER (ONNX) for extracting entities from Federal Register preambles
- Influence clusters: Offline Python computation (
scripts/compute-influence-clusters.py) served as JSON
Open-source packages
Three packages are extracted as standalone npm workspace packages:
- @civiq/sdk — TypeScript API client with 33 typed methods across 9 resources, error hierarchy, custom fetch injection
- @civiq/civic-statistics — Confidence scoring, peer comparison, correlation (Spearman/Pearson), anomaly detection, sample size enforcement
- @civiq/entity-resolution — Committee alias resolution, ticker-to-industry mapping, FEC recipient deduplication
Commands
npm run dev
npm run build
npm run lint
npm run type-check
npm test
npm run test:e2e
npm run validate:all
npm run diagnose:apis
Additional scripts for performance benchmarking, data/ML processing, and security scanning are defined in package.json.
Contributing
See CONTRIBUTING.md.
License
Apache License 2.0. Copyright 2019-2026 Mark Sandford.
Use it, modify it, distribute it. Include the copyright, license, and NOTICE file per Apache 2.0 Section 4. Credit is appreciated but not required: "Powered by CIV.IQ." The government data the API serves is in the public domain. The @civiq/* npm packages are MIT. The CIV.IQ name and logo are trademarks and require written permission to use. See LICENSE and NOTICE.
Mark Sandford - contact@civdotiq.org