product-fpol/docs/data-coverage.md

# Data feasibility — checked 2026-10-04

**Real-league launch is blocked on national candidate coverage, frozen ratings, and verified automatic results/calls.** The prototype is usable with synthetic data. No live provider adapter or polling service is enabled, and no historical scoring backtest is claimed.

## Scope and evidence

The [USPS election calendar](https://about.usps.com/postal-bulletin/2026/pb22694/html/cover_004.htm) lists November 3, 2026, with 435 House seats, 35 Senate seats and 36 state governorships. This milestone assumes the 50 states, including safe and uncontested races. Territories, nonvoting delegates and separate special House contests need an explicit scope decision before a national catalog is frozen. The [150-row matrix](../data/coverage_2026.csv) distinguishes offices without a scheduled election from missing or unverified data. It is an office/state checklist, not a verified seat-by-seat national manifest.

The [Michigan official general-election list](https://mi-boe.entellitrak.com/etk-mi-boe-prod/page.request.do?electionType=GEN&electionYear=2026&page=page.miboePublicReport) was readable. Its 13 House races, Senate race and governor race were manually transcribed into [a 73-candidate snapshot](../data/real/mi-2026-10-04.json). Entries marked DISQ were excluded. Governor tickets use the gubernatorial candidate. Provenance dates have day precision; midnight UTC is a storage convention. The source can change: independently reconcile the transcription, ballot qualification and replacements before a draft. Empty provider mappings mean they have not been matched to any results feed. This catalog is deliberately `complete: false`.

[FEC information](https://www.fec.gov/introduction-campaign-finance/election-results-and-voting-information/) is useful for retrospective federal results; campaign filings are not proof of general-election ballot qualification. State election offices remain the catalog authority.

## Provider findings

| Source | Verified evidence | Still unverified / missing |
| --- | --- | --- |
| [civicAPI documentation](https://civicapi.org/api-documentation) | Advertises free, unauthenticated real-time results and calls; documents a v2 API base | Concrete race endpoint, response schema, 2026 office/state coverage, stable candidate IDs, call provenance, timestamp and correction behavior |
| [Open America API contract](https://openamerica.io/elections/api/) | Documents a free results endpoint, 2024 replay and 22-state coverage | Live payload retrieval, individual office/seat coverage and identity reconciliation; no calls or pre-election candidate catalog |
| State election offices | Michigan catalog retrieved | National catalog and automatic feed coverage |
| Commissioner ratings import | Versioned, sourced snapshots supported | No real pre-draft ratings imported; no dated historical rating dataset verified |

Open America documents `https://openamerica.io/elections/results.json?year=2026&office=House`; substitute Senate/Governor or year 2024. Its `final` flag concerns precinct reporting, not certification. Candidate names and parties require explicit internal-ID matching. Follow its 60-second polling guidance, conditional requests, gzip, attribution and backoff. State inclusion does not guarantee every office or uncontested race. Outside the documented 22 states, coverage is missing. Calls are missing everywhere.

Attempts to open provider JSON endpoints through the available research tools returned no usable payload. civicAPI `/api/v2/status`, `/api/v2/races`, and the API root were exploratory guesses, **not verified endpoint contracts**. This is not evidence of a provider outage. Shell networking is restricted here. No provider's transport, election-night reliability or correction behavior has been validated end to end.

## Capacity findings

The C++ capacity endpoint checks 2–12 players. For **each office**, twelve teams need at least 12 Democrats, 12 Republicans, 12 Others and 48 distinct candidates overall. The total requirement reserves enough candidates for Flex after the affiliation slots are filled. These conditions are sufficient for these disjoint office/affiliation constraints; they say nothing about data coverage.

| Imported catalog | House D / R / Other / total | Senate | Governor |
| --- | --- | --- | --- |
| Synthetic | 12 / 12 / 24 / 48 | 12 / 12 / 24 / 48 | 12 / 12 / 24 / 48 |
| Michigan partial | 13 / 13 / 36 / 62 | 1 / 1 / 4 / 6 | 1 / 1 / 3 / 5 |

The fictional catalog supports every allowed league size. Michigan alone cannot fill two complete rosters because Senate and Governor each have only one D and one R. **Nationwide feasibility is unknown**, not disproven. Obtain the remaining qualified candidates before deciding whether the Other slots work for twelve players. Do not silently relax the roster rules.

## Gates before multiplayer launch

1. Reconcile every in-scope seat and qualified candidate, including fusion lines, independents, uncontested seats and replacements. Use one candidacy ID per candidate/race; preserve the original ballot labels and commissioner-assigned roster affiliation. Never draft aggregate write-in buckets.
2. Capture actual provider responses and retain their URL, retrieval time and payload. Confirm candidate-level IDs or reviewed mappings, vote denominators, timestamps, rounds, calls/retractions and corrections. A party leader or 100% precincts is never a call.
3. Obtain sourced, dated ratings for every race; freeze the selected immutable snapshot before drafting. Unrated races block that gate; they do not default to Safe.
4. Verify real capacity for the selected player count, then rehearse automatic polling and replay with outage/staleness handling. Free automatic coverage is a launch requirement. Resolve unsupported states and calls before promising a complete election-night experience.
5. Settle runoff and ranked-choice scoring policy. The current importer rejects a different round for the same catalog race and `pending_round` remains unscored. A later round must not be added to an earlier count. Do not launch affected races until provider semantics and final-round handling are specified and tested.

Commissioner JSON imports make the foundation reviewable; they are not the planned election-night automation. If free sources cannot meet these gates, bring that concrete limitation back for a product decision rather than introducing a paid dependency or silently narrowing the game.

## League milestone update — October 4, 2026

The combined `data/real/us-2026-10-04-partial.json` now includes **115 candidates / 30 contests**: Michigan's existing 73/15 plus North Carolina's 42 candidates across 14 House districts and one Senate contest. NC facts were reviewed from [the official state-only November candidate list](https://s3.amazonaws.com/dl.ncsbe.gov/Elections/2026/Candidate%20Filing/2026_general_candidate_list_by_contest_federal_and_state.pdf), pages 1–3, report dated September 21. No residential/contact details were copied. Retrieval timestamps have day precision; midnight is a date placeholder. The remaining 48 states still need candidate imports; real ratings and live coverage remain incomplete.

A national inventory now records 506 scheduled November contests (435 House, 35 Senate including the FL/OH specials, 36 governor). It supplements the 150-row state/office matrix and guards draft readiness. Candidate source watches, Open America normalization, and a reviewed official JSON integration contract are implemented, but **no provider capture is verified**. civicAPI remains capture-only pending an actual response contract. See [ingestion](ingestion.md) for activation requirements and the settled November first-choice share policy.