# CIV.IQ

> Civic intelligence platform providing normalized U.S. government data through open APIs. No API key required. Real data only — never mock or fabricated.

CIV.IQ fills the vacuum left by the shutdown of ProPublica Congress API, Google Civic Info API, and OpenSecrets API. It aggregates data from Congress.gov, FEC, Senate LDA, USASpending, Federal Register, Census Bureau, BLS, and more into a unified, free REST API.

## When to Use CIV.IQ

Reach for CIV.IQ when an agent needs, without an API key:

- Who represents a U.S. street address (federal + state legislators). Always pass a full street address, not a ZIP code — ZIP boundaries misalign with congressional districts in 10-20% of cases.
- How to contact a state legislator: phone, email and capitol office for 7,420 sitting state legislators in all 50 states, DC and Puerto Rico
- A member of Congress's voting record, sponsored bills, committee seats, or party-alignment statistics
- Federal campaign finance (FEC) with industry and geography breakdowns
- Federal lobbying filings (Senate LDA), federal spending by district (USASpending), or Federal Register rules
- Congressional district demographics, economics, and boundaries
- Bill search and status tracking for the current Congress

Do NOT use CIV.IQ for: state-level campaign finance or lobbying (federal only), local (city/county) government (not covered), live election-night results, or non-U.S. data. When CIV.IQ lacks data it says so — responses carry a `dataQuality` field instead of silently returning empty arrays.

How to call it:

- REST: `GET https://civdotiq.org/api/v1/...` — no auth, 60 requests/minute per IP. This is the only stable, documented API and the only `/api/` path robots.txt allows.
- MCP: Streamable HTTP endpoint at `https://civdotiq.org/api/mcp` — 47 read-only tools, no auth. Use it for anything `/api/v1` doesn't cover (address lookup, voting records, campaign finance, lobbying).
- Web pages: every page below is server-rendered HTML, so a plain fetch returns the full content
- CLI: `npx @civiq/sdk representatives --state MI`
- SDK: `npm install @civiq/sdk`
- Markdown variants: key pages (`/`, `/about`, `/developers`, `/docs/api`, `/mcp`, `/support`) respond to `Accept: text/markdown` with markdown instead of HTML

## Core Capabilities

- **Representatives**: Look up federal and state legislators by street address or state
- **Voting Records**: House and Senate roll call votes with party alignment analysis
- **Campaign Finance**: FEC contribution data with industry/geographic breakdowns. **Federal only** — state campaign finance is not currently available
- **Legislation**: Bill search, details, sponsors, cosponsors, status tracking
- **Lobbying**: Senate LDA filings with spending and issue tracking. **Federal only**
- **Federal Spending**: USASpending contracts and grants by district
- **Intelligence Analysis**: ML-driven vote prediction, influence chain analysis, finance-jurisdiction overlap detection. **Federal data only** — state and local analyzer output is not produced because the underlying state-level cross-domain joins do not exist
- **Districts**: Demographics, economics, boundaries for all 435 congressional districts and 7,383 state legislative districts
- **Committees**: Membership, jurisdiction, activity tracking
- **Federal Register**: Rules, notices, executive orders search
- **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.

## Coverage Honesty

The canonical coverage matrix is published at https://github.com/civdotiq/civ.iq/blob/main/docs/COVERAGE.md (in repo at `docs/COVERAGE.md`). Every join-based API response carries a `dataQuality` field (`complete | partial | empty | unavailable`) so consumers can distinguish "no data exists" from "upstream source unavailable." Routes never return silent empty arrays in place of an error.

## API Access

- Base URL: `https://civdotiq.org/api`
- Versioned API: `https://civdotiq.org/api/v1`
- OpenAPI spec: `https://civdotiq.org/openapi.json`
- No authentication required
- Rate limited to 60 requests/minute per IP; responses carry standard `RateLimit-*` headers (plus legacy `X-RateLimit-*`), and a 429 includes `Retry-After`
- Errors are always structured JSON: `{ "error": { "code", "message", "details?" }, "meta": {...} }` — unknown API paths return this shape with status 404, never HTML
- Versioning: v1 in the URL path; breaking changes only ship as a new version with ≥6 months of `Deprecation`/`Sunset` (RFC 8594) header notice. Policy: https://civdotiq.org/docs/api#versioning

## Key Endpoints

REST (`/api/v1`, stable):

- `GET /api/v1` — machine-readable endpoint directory
- `GET /api/v1/representatives?state=MI&chamber=house` — list members of Congress
- `GET /api/v1/representatives/{bioguideId}` — member detail
- `GET /api/v1/bills?sort=updateDate+desc&limit=20` — recent bills
- `GET /api/v1/bills/{billId}` — bill detail (e.g. `119-hr-1`)
- `GET /api/v1/bills/{billId}/summary` — cached plain-language summary
- `GET /api/v1/votes/{voteId}` — roll-call vote detail (e.g. `house-119-116`)
- `GET /api/v1/districts/{districtId}` — congressional district and its member (e.g. `MI-12`)
- `GET /api/v1/committees` and `GET /api/v1/committees/{committeeId}` — committees and members
- `GET /api/v1/changelog` — API changelog

MCP tools for what `/api/v1` doesn't cover:

- `lookup_representatives` — everyone who represents a full street address (Congress + state legislature)
- `get_voting_history` — a member's recent votes
- `get_campaign_finance` — FEC totals, PAC money, industry breakdown
- `search_legislation` — full-text bill search
- `search_lobbying` — Senate LDA filings
- `analyze_vote_prediction` — ML vote prediction

Other paths under `/api/` (for example `/api/representative/{id}/votes`) are internal routes behind the site's own pages. They are unversioned, can change without notice, and robots.txt disallows them, so agents that respect robots.txt can't fetch them. Use `/api/v1` or MCP instead.

## Pages

Server-rendered HTML pages, listed in [sitemap.xml](/sitemap.xml) and [sitemap-state-legislators.xml](/sitemap-state-legislators.xml):

- `/your-reps` — find your members of Congress and state legislators by street address
- `/representative/{bioguideId}` — member of Congress profile: phone, DC office, contact form or website, votes, bills, campaign finance (e.g. `/representative/T000481`)
- `/state-legislature/{state}` — "Who is my state representative in [State]?": every state legislator by chamber with district, party and phone (e.g. `/state-legislature/mi`)
- `/state-legislature/{state}/legislator/{name}-{id}` — state legislator profile: phone, email, capitol office, district (e.g. `/state-legislature/mi/legislator/winnie-brinks-de38477b`)
- `/states/{state}` — state overview: governor, congressional delegation, legislature party split, Census demographics (e.g. `/states/mi`)
- `/districts/{ST-NN}` — congressional district: member, demographics, economy (e.g. `/districts/MI-12`; at-large seats use `AL`, e.g. `/districts/AK-AL`)
- `/state-districts/{state}/{upper|lower}/{district}` — state legislative district: members and population (e.g. `/state-districts/mi/upper/8`)
- `/bill/{congress}-{type}-{number}` — bill status, sponsors, actions and summary (e.g. `/bill/119-hr-1`)
- `/vote/{chamber}-{congress}-{session}-{rollNumber}` — roll-call vote (e.g. `/vote/senate-119-2-1`)

## Question Pages

CIV.IQ provides question-driven entry pages at `/ask/{question-slug}/{bioguideId}`. Each page answers a specific civic question with real data pods and structured FAQ schema.

Available question templates:
- `/ask/campaign-contributions/{bioguideId}` — Where do campaign contributions come from? (FEC data, industry breakdown, vote-finance correlation)
- `/ask/party-alignment/{bioguideId}` — How does this legislator vote compared to their party? (party-line rate, quarterly trends, notable shifts)
- `/ask/voting-record/{bioguideId}` — How does this legislator vote? (recent votes, sponsored bills, voting statistics)

Each page includes JSON-LD FAQPage schema, breadcrumb navigation, and related question links.

## MCP Server

CIV.IQ exposes a Model Context Protocol server for AI assistant integration:
- Endpoint: `https://civdotiq.org/api/mcp` (Streamable HTTP, no auth required; `https://civdotiq.org/mcp` accepts the same protocol traffic)
- Server manifest: `https://civdotiq.org/.well-known/mcp.json` (MCP registry server.json format)
- 47 read-only tools across 9 domains: representatives, legislation, finance, intelligence, civic, environment, safety, health, economy
- 7 resource templates (e.g. `civiq://legislators/{bioguideId}`) plus 3 static doc resources (`civiq://docs/when-to-use`, `civiq://docs/api-quickstart`, `civiq://docs/versioning-policy`)
- 6 prompt templates for common analysis patterns

## CLI

The `@civiq/sdk` npm package ships a `civiq` command-line tool for scripted lookups:
- `npx @civiq/sdk representatives --state MI --chamber house`
- `npx @civiq/sdk search healthcare`
- `npx @civiq/sdk representative P000197 votes`
All commands print JSON to stdout. Run `npx @civiq/sdk --help` for the full command list.

## Migration

- **Google Civic Info API users**: The Representatives API was shut down March 2025. CIV.IQ is a free drop-in replacement. See [migration guide](/migrate/google-civic).

## Documentation

- Developer portal: [https://civdotiq.org/developers](/developers)
- API reference (human-readable): [https://civdotiq.org/docs/api](/docs/api)
- Full API docs: [llms-full.txt](/llms-full.txt)
- OpenAPI 3.0 spec: [openapi.json](/openapi.json)
- API reference (repo): [docs/API_REFERENCE.md](https://github.com/civdotiq/civ.iq/blob/main/docs/API_REFERENCE.md)
- TypeScript SDK & CLI: [@civiq/sdk on npm](https://www.npmjs.com/package/@civiq/sdk)

## Data Sources

All data comes from official government sources:
- Congress.gov API v3 (bills, members, votes)
- FEC.gov API (campaign finance)
- Senate LDA API (lobbying disclosures)
- USASpending.gov API v2 (federal contracts/grants)
- Federal Register API (rules, executive orders)
- Census Bureau ACS (demographics)
- Bureau of Labor Statistics (employment)
- GovInfo.gov (hearing transcripts)

## License

MIT. Open source at github.com/civdotiq/civ.iq