Methodology

Data sources (tiered)

• Tier 1 — Official state sources. State legislature APIs, bulk data, and websites, used directly where technically and legally feasible.
• Tier 2 — Open States. The Open States v3 API and bulk CSV exports, our primary bootstrap source for all 51 jurisdictions. Open States data is public domain; we preserve their attribution and source links on every record.
• Tier 3 — LegiScan (optional). Used only via LegiScan’s authorized API/datasets under CC BY 4.0 attribution. The platform is fully functional without it.
• Tier 4 — Compliant direct extraction. Used only where robots.txt, terms of service, and rate limits are respected, with an honest user agent and no CAPTCHA or authentication bypass. If a source blocks us, we document the blocker and fall back to Tier 2.

Attribution

Every bill record on Bill Commons carries a source name, source URL, and retrieval timestamp. Where data originates from Open States, we preserve their public-domain notice; where LegiScan data is used, we preserve CC BY 4.0 attribution. See each bill page’s “Attribution” section for record-level sourcing.

Coverage state machine

Each jurisdiction moves through a tracked pipeline:

NOT_STARTED → SOURCE_IDENTIFIED → BOOTSTRAPPED → METADATA_SEARCHABLE → FULL_TEXT_SEARCHABLE → VALIDATING → GREEN | DEGRADED | BLOCKED

A jurisdiction reaches GREEN only when all of the following hold: its current session is identified from an authoritative source; all discoverable bills for that session are imported; bills are searchable by number and title; description, subjects, sponsors, and actions are searchable wherever supplied; full text is searchable wherever technically available from the source; official source URLs are retained on every record; incremental refresh succeeds; validation samples pass; the search index count matches the database count; and there are no unexplained zero counts. For states without a 2026 regular session, GREEN requires the current legislative cycle to be explicitly verified with no new session pending.

Live status for every jurisdiction is public on the coverage page, including bill counts, full-text percentage, last update time, validation sample size and pass rate, and any known gaps.

Refresh policy

• Active regular/special sessions: every 15–30 minutes
• Year-round legislatures: hourly
• Recently adjourned sessions: daily
• Dormant sessions: weekly status check
• Calendars and special-session notices: daily

Refreshes use conditional requests, exponential backoff, circuit breakers, and per-source concurrency limits. Unexpected bill-count drops or schema changes trigger alerts rather than silent data loss.

Version diffing

Bill text is normalized from HTML, XML, plain text, and text-layer PDFs; original source files are preserved. Scanned PDFs that require OCR are flagged with a confidence indicator and are never presented as authoritative without that warning. Version-to-version diffs are computed deterministically (line anchors, adds, deletes, moves, and section headings) — never by a language model.

Quality assurance

Each jurisdiction is spot-checked against at least five random bills compared to the official source (number, title, session, sponsor, latest action), at least one full bill-text document verified, and bill-number and keyword search verified against known official text. Results are recorded and summarized on the coverage page.

Known limitations

• Coverage depth varies by jurisdiction and by how quickly each reaches GREEN status — check the coverage page before relying on completeness for a given state.
• Full text may be unavailable for some documents at the source (e.g. scanned-only historical filings).
• Member-level vote detail depends on what the underlying source publishes; some jurisdictions report only aggregate counts.
• AI-generated summaries, if ever introduced, will always be labeled as generated analysis with linked sources — never presented as an official record.