# BallotWatch

> The U.S. congressional record, source-linked: every member of Congress, every roll-call vote since the 119th Congress began, and every bill, drawn daily from Congress.gov, the House Clerk, and the Senate. Free to read, free to query, and every record carries its official source URL.

BallotWatch is a civic reference, not a campaign site. Pages read like an editorial broadsheet. Data is the record as ingested; the only derived field is a roll call's result, computed from the tally and the question. Bill explanations are grounded in the official CRS summary and are never generated on demand for anonymous requests.

## Canonical URLs

- Member: https://www.ballotwatch.io/politician/{bioguide_id} (example: /politician/P000197)
- Roll call: https://www.ballotwatch.io/vote/{congress}/{house|senate}/{session}/{roll} (example: /vote/119/house/2/295)
- Bill: https://www.ballotwatch.io/bill/{congress}/{type}/{number} (example: /bill/119/hr/1; types: hr, s, hjres, sjres, hconres, sconres, hres, sres)
- Members index: https://www.ballotwatch.io/all
- Bills index: https://www.ballotwatch.io/bills
- Methodology: https://www.ballotwatch.io/methodology

Every member and roll-call URL, and every bill with a recorded vote or an official summary, returns full HTML without JavaScript (other bills return the app shell). Send `Accept: text/markdown` to the same URL for a compact Markdown record (about a tenth of the tokens); the Markdown view works for every bill.

## API (no key required for GET)

- Base: https://www.ballotwatch.io/api/v1
- OpenAPI: https://www.ballotwatch.io/openapi.yaml
- Endpoints: /members, /members/{bioguide_id}, /members/{bioguide_id}/votes, /members/{bioguide_id}/stats, /bills, /bills/{id}, /votes, /votes/{roll_call_id}, /stats, /search?q=
- Ids: bioguide ids like P000197; bill ids like 119-hr-1; roll-call ids like house-119-2-295 (chamber-congress-session-roll)
- Limits: 60 requests per minute and 5,000 per day per IP without a key. A free key (sign in at https://www.ballotwatch.io/developers/keys, no payment) raises this to 600 per minute with no monthly cap. Send it as `Authorization: Bearer bw_live_...`. Over the limit you get 429 with `Retry-After`.
- Every response carries `meta.data_updated_at`; single records carry a `Link: <official source>; rel="canonical"` header.

## MCP server

- Endpoint: https://www.ballotwatch.io/mcp (Streamable HTTP, stateless, no auth; same per-IP limits as the API). POST JSON-RPC with `Accept: application/json, text/event-stream`. A GET returns a plain-JSON manifest.
- Tools: find_representatives(address | zip), get_member(bioguide_id), get_member_votes(bioguide_id, since?, limit?), get_roll_call(congress, chamber, session, roll), search_bills(query, limit?), get_bill(id), explain_bill(id)

## Sitemaps and bulk

- https://www.ballotwatch.io/sitemap.xml (members, roll calls, bills with recorded votes)
- Sample data package: https://www.ballotwatch.io/data/datapackage.json

## Citing

Cite the BallotWatch URL and the `source_url` on the record (Congress.gov, clerk.house.gov, or senate.gov). Data freshness is in `data_updated_at`. Corrections: https://www.ballotwatch.io/open

## Optional

- Methodology and data sources: https://www.ballotwatch.io/methodology/data-sources
- Corrections policy: https://www.ballotwatch.io/methodology/corrections
- Source code (MIT): https://github.com/Shoberman2/politalapp