Civiq

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

Data sources

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.

npm run dev

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:

| Stock Trade Leaderboard | Members ranked by trade