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

GREEN is a stored local coverage assessment for a session. The validation process samples indexed bills, checks search retrieval and available source links, and applies a threshold for obtainable full text. Some source checks can be unavailable or blocked by robots policy. A GREEN row does not establish that every bill has been found, that its official source is current, or that the session has no unresolved operational warnings.

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 and recency vary by jurisdiction. Check both the coverage matrix and data-health report before relying on a result.
• 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.