📁 officials

Federally elected and federally appointed officeholders. members covers every person who has served in the House or Senate (Congress.gov API, the modernized successor to the Biographical Directory of the U.S. Congress). nominations covers PAS nominations — the live pipeline of Senate-confirmed appointed officials, from receipt through committee action to confirmation/withdrawal. federal_judges covers every Article III judge ever commissioned, including appointing president and confirmation history, from the Federal Judicial Center's own biographical database. committees and committee_membership cover House/Senate/Joint committee structure, jurisdiction, and current rosters — the one table pair in this schema sourced from a community-maintained aggregator (unitedstates/congress-legislators) rather than a government system of record directly, because no official source exposes committee membership or jurisdiction in structured form; see the header comment above. house_election_results (1976-2018 from the MIT Election Data + Science Lab, 2020 and 2022 from the FEC; 2024 missing) and senate_election_results (1976-2024, MIT) hold candidate-level election returns, with the views house_race_results, senate_race_results and election_seats_won giving winner, two-party margin and seats won per cycle.

14 datasets · 178 columns

members · table

Every House/Senate member per Congress they served, from the Congress.gov API per-Congress member list endpoint (the modernized Biographical Directory of the U.S. Congress). One row per (bioguide_id, congress) pair — a member serving multiple congresses has multiple rows. terms_json is the member's full chamber service history (all congresses, not just this row's), as a JSON array of {chamber, start_year, end_year}. party_name is the party held in this row's Congress (from the detail endpoint's partyHistory; a mid-Congress switch resolves to the party held when that Congress ended), so a party switcher's rows differ by Congress. Chamber is not a column: district is null for senators and non-null (0 = at-large) for House members. A Congress holds more rows than seats because mid-Congress replacements each get a row, so party control is not a plain COUNT. state_name and district are as reported by the per-Congress list endpoint. Coverage is bounded by congress_range (see dimension_values comment) — not full 1789-present history by default. Cross-references geo.state_ref via state_name (full name; geo.states is a year-vintaged boundary snapshot and not a valid FK target — see constraints below). Territorial delegates (Puerto Rico, Guam, etc.) won't resolve against state_ref, which covers 50 states + DC only.

Column	Type	Null	Description
bioguide_id	string	no	Bioguide identifier (Biographical Directory of the U.S. Congress), e.g. L000174
congress	INTEGER	yes
name_last_first	string	yes	Member name in "Last, First Middle" order as returned by the API
state_name	string	yes	Full state name represented in this row's Congress (join key into geo.state_ref.state_name, not FIPS/abbr; geo.states is a year-vintaged boundary snapshot and not a valid FK target)
party_name	string	yes	Party the member held in this row's Congress (Congress.gov partyHistory span in effect when the Congress ended), e.g. Democratic, Republican, Independent, Independent Democrat, Libertarian. Null when the detail call for the row failed.
district	integer	yes	House district (0 = at-large/single-district state or territory); null for senators
current_member	boolean	yes	Whether the member currently holds office, per Congress.gov's /v3/member/{bioguideId} detail endpoint (currentMember is not present on the list endpoint this table otherwise fetches from — see CongressMemberCurrentEnricher). Populated by an N+1 detail call per row; null means the enrichment call failed for that row (network/parse error), not that the member's status is unknown by design — see CongressMemberTransformer/CongressMemberCurrentEnricher javadoc.
terms_json	string	yes	JSON array of {chamber, start_year, end_year} — this member's FULL chamber service history across all congresses (not scoped to this row's congress column), in chronological order. Kept as JSON rather than a flattened table (per one-source-one-table) pending confirmation that Calcite UNNEST works cleanly over it.
image_url	string	yes	Official portrait URL (depiction.imageUrl)
member_url	string	yes	Referrer URL to the member's Congress.gov API detail record

nominations · table

Presidential nominations requiring Senate confirmation (PAS), from the Congress.gov API nomination endpoint — this IS the appointed-officials pipeline: received -> committee referral -> confirmed/withdrawn/returned. Verified against a live keyed response (2026-08-01): organization is a real top-level field, not an N+1-only one as originally assumed. description is populated for individually -named nominees but is empty for isList=true batch nominations (e.g. Foreign Service class promotions covering many officers at once) — the detail endpoint's isList flag itself is not fetched here, so an empty description is the only MVP signal that a row is a class nomination rather than a named appointee. latest_action_text is the best single field for current status (e.g. "Confirmed by the Senate by Voice Vote", "Nomination Withdrawn").

Column	Type	Null	Description
citation	string	no	Nomination citation, e.g. PN1064 or PN78-4 for a partitioned nomination
congress	INTEGER	yes
number	integer	no	Assigned nomination number within the Congress
part_number	string	yes	Partition suffix when a multi-nominee nomination is split by confirmation path
organization	string	yes	Organization the position sits in, e.g. "Department of State", "Foreign Service"
description	string	yes	Free-text nominee name and position, e.g. "Jane Doe, of Ohio, to be...". Empty for isList=true batch/class nominations — see table comment.
is_civilian	boolean	yes	nominationType.isCivilian. Live responses only ever showed isCivilian=true (isMilitary appears to be omitted rather than sent as false) — unverified against an actual military nomination.
is_privileged	boolean	yes	Whether entitled to expedited Senate procedure. Never observed populated at list level in live samples; kept nullable pending a confirmed-present example.
received_date	string	yes	Date received from the President (YYYY-MM-DD)
latest_action_date	string	yes	Date of the latest Senate/President action (YYYY-MM-DD)
latest_action_text	string	yes	Text of the latest action — the primary status signal (confirmed/withdrawn/ returned/pending committee action)
update_date	string	yes	Last update timestamp on Congress.gov

federal_judges · table

Every Article III federal judge ever commissioned, from the Federal Judicial Center's own Biographical Directory of Article III Federal Judges export. Verified against a live download (2026-08-01): the real CSV is 201 columns wide — up to 6 repeating groups of ~33 court/appointment columns each (a judge elevated District -> Circuit -> retired-then-recalled etc. gets multiple groups), plus separate "Other Federal Judicial Service", "School"/"Degree", and free-text career columns. This table maps a curated 12-of-33 fields per group (the appointment-identity and confirmation-timeline columns) and drops the education/career/committee-vote detail for MVP scope — not a parsing limitation, a deliberate cut. Ingested as one row per judge (one source, minimal reshape); a future federal_judgeships view could UNION ALL the 6 groups into one row per appointment if downstream queries need that grain.

Column	Type	Null	Description
nid	string	no	FJC judge name ID
jid	string	no	FJC judge ID (stable identifier, one per judge)
last_name	string	yes
first_name	string	yes
middle_name	string	yes
suffix	string	yes
birth_year	integer	yes
gender	string	yes
race_or_ethnicity	string	yes
court_type_1	string	yes	Court Type
court_name_1	string	yes	Court Name
appointment_title_1	string	yes	Appointment Title (e.g. Judge, Chief Judge)
appointing_president_1	string	yes	Appointing President
party_of_appointing_president_1	string	yes	Party of Appointing President
aba_rating_1	string	yes	American Bar Association rating at nomination
nomination_date_1	string	yes	Nomination Date (YYYY-MM-DD)
confirmation_date_1	string	yes	Confirmation Date (YYYY-MM-DD)
commission_date_1	string	yes	Commission Date (YYYY-MM-DD)
senior_status_date_1	string	yes	Senior Status Date (YYYY-MM-DD), if applicable
termination_date_1	string	yes	Termination Date (YYYY-MM-DD), if applicable
termination_reason_1	string	yes	Termination reason (e.g. Resignation, Death, Elevation)
court_type_2	string	yes
court_name_2	string	yes
appointment_title_2	string	yes
appointing_president_2	string	yes
party_of_appointing_president_2	string	yes
aba_rating_2	string	yes
nomination_date_2	string	yes
confirmation_date_2	string	yes
commission_date_2	string	yes
senior_status_date_2	string	yes
termination_date_2	string	yes
termination_reason_2	string	yes
court_type_3	string	yes
court_name_3	string	yes
appointment_title_3	string	yes
appointing_president_3	string	yes
party_of_appointing_president_3	string	yes
aba_rating_3	string	yes
nomination_date_3	string	yes
confirmation_date_3	string	yes
commission_date_3	string	yes
senior_status_date_3	string	yes
termination_date_3	string	yes
termination_reason_3	string	yes
court_type_4	string	yes
court_name_4	string	yes
appointment_title_4	string	yes
appointing_president_4	string	yes
party_of_appointing_president_4	string	yes
aba_rating_4	string	yes
nomination_date_4	string	yes
confirmation_date_4	string	yes
commission_date_4	string	yes
senior_status_date_4	string	yes
termination_date_4	string	yes
termination_reason_4	string	yes
court_type_5	string	yes
court_name_5	string	yes
appointment_title_5	string	yes
appointing_president_5	string	yes
party_of_appointing_president_5	string	yes
aba_rating_5	string	yes
nomination_date_5	string	yes
confirmation_date_5	string	yes
commission_date_5	string	yes
senior_status_date_5	string	yes
termination_date_5	string	yes
termination_reason_5	string	yes
court_type_6	string	yes
court_name_6	string	yes
appointment_title_6	string	yes
appointing_president_6	string	yes
party_of_appointing_president_6	string	yes
aba_rating_6	string	yes
nomination_date_6	string	yes
confirmation_date_6	string	yes
commission_date_6	string	yes
senior_status_date_6	string	yes
termination_date_6	string	yes
termination_reason_6	string	yes

committees · table

House, Senate, and Joint standing/select committees and their subcommittees, from the unitedstates/congress-legislators project's committees-current.yaml — a CC0-licensed, near-continuously-updated mirror of official House/Senate committee pages. The one community-aggregator source in this schema: verified live that the Congress.gov API's /v3/committee endpoint carries no jurisdiction text and no member roster (see the schema header). One row per full committee and one row per subcommittee, linked via parent_committee_id; committee_id is the join key into committee_membership.

Column	Type	Null	Description
committee_id	string	no	thomas_id (full committee) or parent thomas_id + subcommittee thomas_id (subcommittee, e.g. HSAG + 15 = HSAG15) — PK, and the join key into committee_membership.
chamber	string	yes	house, senate, or joint
name	string	yes
parent_committee_id	string	yes	NULL for a full committee; the parent's committee_id for a subcommittee
is_subcommittee	boolean	yes
url	string	yes
minority_url	string	yes
jurisdiction	string	yes	Legislative jurisdiction, free text (populated for most House committees; sparse elsewhere)
jurisdiction_source	string	yes
address	string	yes
phone	string	yes
rss_url	string	yes

committee_membership · table

Current committee/subcommittee rosters, from the unitedstates/congress-legislators project's committee-membership-current.yaml. One row per (committee, member) assignment for the sitting Congress. committee_id joins to committees.committee_id; bioguide_id joins to members.bioguide_id — this file has no congress number of its own (it is always the current roster), so join against the member's most recent congress rather than a specific one (see current_members).

Column	Type	Null	Description
committee_id	string	no
bioguide_id	string	yes
member_name	string	yes
party	string	yes	majority or minority
rank	integer	yes	Seniority rank within the committee for this party (1 = chair/ranking member)
title	string	yes	e.g. Chairman, Ranking Member; null for other members

electoral_college_votes · table

Electoral College vote allocation by state, for President and Vice President, from the National Archives (NARA) official per-election results page (archives.gov/electoral-college/{year}) — the government's own record of the Electoral College outcome, not a poll or projection. One row per (year, state, office, candidate). Verified stable across 200 years of live pages (1824, 1876, 1960, 1980, 2000, 2020, 2024): each page has a state-by-state table whose "For President"/"For Vice-President" header groups carry a colspan equal to however many candidates received at least one elector that year — parsed dynamically, not a fixed column count. candidate_party is populated only for the winner and the top losing candidate (the only two NARA names on the page's own summary block); other candidates' party is null — NARA's per-election page does not state it for anyone else, including write-in/faithless-elector recipients. Coverage defaults to 1976-2024 (presidential_year_range) — see that dimension's comment for why 1789 isn't the floor. Cross-references geo.state_ref via state_name (same caveat as members: DC has 3 electoral votes since the 23rd Amendment but is not itself a state, so 3-elector DC rows will not resolve against a strict state_ref join in years before 1961 if the range is widened).

Column	Type	Null	Description
year	INTEGER	yes
state_name	string	no	Full state name as published by NARA (e.g. "California"); join key into geo.state_ref.state_name
state_electoral_votes	integer	yes	Total electoral votes allocated to this state for this election
office	string	no	PRESIDENT or VICE_PRESIDENT
candidate_name	string	no	Candidate name as published by NARA (format varies by era, e.g. "Kamala D. Harris")
candidate_home_state	string	yes	Candidate's home state as published ("... of California"); null when NARA's text doesn't follow that pattern
candidate_party	string	yes	Party abbreviation, populated ONLY for the page's designated winner and main opponent (the only two candidates NARA's summary block names with a party) — null for every other candidate on the page, including anyone who received faithless-elector or write-in votes.
electoral_votes_won	integer	yes	Electoral votes this candidate won in this state ("-" in the source becomes 0, not null)

presidential_election_results · table

Popular vote totals by state and candidate for the presidential general election, from the FEC's official post-election results workbook (fec.gov, "{year} Presidential General Election Results", published as XLSX). Richer than electoral_college_votes for the years it covers — actual vote counts, not just elector allocation — but coverage is NOT full-history: FEC only publishes this specific XLSX format for recent cycles (confirmed: 2024; unconfirmed further back — the source page lists only PDF, not XLSX, for cycles further back at the time this table was built, 2026-08-02). No predictable per-year URL exists (each year's file lives behind an opaque numeric document ID), so this transformer discovers the URL per year by scraping FEC's static results-and-voting-information listing page rather than templating a URL directly — a year with no matching link on that page yields zero rows for this table, not an error; check the ETL log for "no results link found" to distinguish "not published this way" from a real failure. One row per (year, state, candidate). Cross-references geo.state_ref via state_name.

Column	Type	Null	Description
year	INTEGER	yes
state_name	string	no	Full state name (converted from the source's 2-letter postal code); join key into geo.state_ref.state_name
state_electoral_votes	integer	yes	Total electoral votes allocated to this state (also carried on electoral_college_votes)
candidate_name	string	no	Candidate surname/label as published in the workbook's column header (format varies by year)
popular_votes	long	yes	Popular votes received by this candidate in this state
state_total_votes	long	yes	Total votes cast for President in this state, all candidates + write-ins

house_election_results · table

U.S. House general-election returns by district and candidate for 24 cycles: 1976 to 2018 from the MIT Election Data + Science Lab (CC0), as the Lab's GitHub repository MEDSL/constituency-returns publishes them (release dated 2019, commit cca36bc159), and 2020 and 2022 from the Federal Election Commission's official results workbooks (source 'FEC' against 'MEDSL' in the source column). 2024 IS MISSING: the Lab's 1976-2024 release (Harvard Dataverse doi:10.7910/DVN/IG0UN2) sits behind a Dataverse guestbook that requires a name, e-mail, institution and position, so an automated job cannot fetch it, and the FEC has not published a 2024 House results workbook (fec.gov lists only the 2024 candidate list and presidential results); 2024 is to be added when the FEC publishes it. One row per candidate per party line per district election round: year, state, district, whether it is a special election or a runoff, the stage (gen general election, pri primary, null when the Lab gave none), the candidate, the party label as published and a normalised major-party field, votes and the published total. Fusion tickets: in states that let a candidate appear on several party lines (mostly New York and Connecticut, also Maryland and South Carolina) each line is its own row with its own votes and the same candidate name, so a candidate's vote is the SUM over rows, never one row; party_major is D or R per line only when that line is the Democratic or Republican party itself (the Conservative or Working Families line of a Republican or Democrat is OTHER on its own row), which is why the views house_race_results and house_seats_won assign a candidate to D or R when any of the candidate's lines is a D or R line. Nothing is merged in this table. Other quirks kept as published: district 0 is an at-large state (at_large=true, cd_fips ends 00); write-ins are lumped in rows with candidate null (candidate_kind write_in_aggregate) and vote buckets (Blank Vote, Scatter, Over Vote, Other) are candidate_kind residual; uncontested races carry candidate_votes 1 and total_votes 1 (uncontested=true), which is a placeholder, not a count; 39 2018 rows are marked unofficial; the file is not a Congress roster, so a candidate who won a special election appears under special=true. Redistricting: results are by the district map in force that year (new maps in 1982, 1992, 2002, 2012, and the court-ordered mid-decade Texas redraws of 1996 and 2006, which appear as extra special, runoff and null-stage rounds; 2022 uses the 2020-census maps), so a (state, district) pair is a different place before and after a redistricting year and is not comparable across them without a crosswalk. Louisiana 2002 district 5 is a runoff round after an open first round (Louisiana 2020 district 5 likewise, FEC). FEC ROWS (2020, 2022), read from the workbook's 'US House Results by State' sheet with strict parsing (an unknown header, state, party label or subtotal fails the fetch; every district's rows must sum to the sheet's own district total and the winner flag must name the leader): only the 50 states' general elections are loaded, stage gen, from the General Votes and General Runoff columns; primaries, primary runoffs and the per-party and combined subtotal rows are not. The delegates (DC, AS, GU, MP, PR, VI) are not loaded, as the Lab's series has none. Vacancy-filling special elections are not loaded (the Lab's series has none either; they sit on the FEC 'Special Elections' appendix), except Indiana 2 in 2022, whose unexpired-term election is on the main sheet beside the full-term one and is special=true. Fusion tickets (New York, Connecticut, Oregon, South Carolina, Alaska): each party line of a candidate is its own row with its own votes, as in the Lab's data; the FEC 'Combined Parties' rows and combined-total columns are not read. Oregon and a few other states publish one combined total under a combined label (D/WF, D/IP/WF), which is one row whose party_published joins the lines with '/'. A combined label is credited to the major party only when it contains exactly one of D or R and the candidate has a primary or convention entry; otherwise it is OTHER (Connecticut 4 2020 Brian Merlen, labelled D/IP, is OTHER). Write-ins: the FEC's 'Scattered', 'All Others' and 'Anyone Else' lines are write-in aggregates (candidate null, candidate_kind write_in_aggregate, writein true); named write-in candidates (party W) are kept as candidate rows with writein true and party null, which is more granular than the Lab's 2018 rows (one named write-in in all of 2018). Party labels are the workbook's own codes resolved through its 'Party Labels' sheet and lower-cased (party_published 'democratic', not the Lab's 'democrat'); party_major D covers D, DFL and DNL (Democratic-Nonpartisan League), R covers R, everything else is OTHER; the star after a code (R, D) marks a convention nominee and is dropped; W(x)/x (a primary write-in who is on the general ballot as x) is x; two codes are aliased to the label the sheet defines (AVP to APV, Approval Voting Party, in 2020; GS to GSA, God Save America, in 2022). A candidate taken off the ballot by a court (the '#' result of a Montana 2020 Green) has no row. Uncontested races: the FEC prints 'Unopposed' for Florida 25 (2020) and Florida 5 and Louisiana 4 (2022), which become the Lab's marker, candidate_votes 1 and total_votes 1 (uncontested true, a placeholder); other races whose opponents did not appear carry the FEC's real counts. At-large districts are district 0 (FEC 00), as the Lab. Runoffs: a General Runoff value makes a second round, runoff true, beside the first round (runoff false), as the Lab does for Louisiana. Ranked-choice contests (Maine 2 and Alaska at-large in 2022): candidate_votes and total_votes are the LAST round's counts of the instant runoff tabulation, as the Lab's Maine 2 in 2018 is, with ranked_choice true and the first-choice count in first_choice_votes; eliminated candidates carry 0 in the last round, and write-ins that the tabulation excludes (the Scattered line) have no row, so the round total is the tabulation's. Rows from the Lab have ranked_choice null (its 2018 Maine 2 rows are last-round counts, unflagged). A candidate who appears in two districts (a redistricted incumbent) is two unrelated rows; nothing is merged across districts or years, and the FEC file carries no stable candidate key that the table keeps. total_votes is, in both sources, the sum of every row of the round including write-ins. DISCONTINUITY at 2018/2020: party_published vocabulary changes (the Lab's 'democrat' to the FEC's 'democratic'; use party_major across the boundary); candidate names are the FEC's first and last name columns joined as 'first last' (a suffix the FEC puts in the first-name column stays there: 'Martin, Jr. Lemelle'), not the Lab's spellings, so names do not join across the boundary; version_date is null on FEC rows (the workbooks carry only a month, October 2022 for 2020 and February 2025 for 2022, named in source_release); unofficial is false on FEC rows (an official-results publication); the Lab's per-year set of vote buckets (Blank Vote, Scatter, Over Vote) does not exist in the FEC data; the FEC rows are the states' certified results while the Lab's may carry unofficial flags. Joins: state_fips to geo.state_ref.state_fips; state_name to officials.members.state_name; members.district equals district and the Congress seated after the election is (year - 1786) / 2 (year 2018 is Congress 116); cd_fips (state FIPS + 2-digit district, 00 at large) matches geo.congressional_districts cd_fips for the same map vintage, which geo carries from 2021 only. Candidate-level joins to members would be name matching and are not attempted (the Lab carries no bioguide id). Sources: https://github.com/MEDSL/constituency-returns (1976-2018-house.csv; codebook and license on the Dataverse record doi:10.7910/DVN/IG0UN2) and the FEC workbooks federalelections2020.xlsx and federalelections2022.xlsx under https://www.fec.gov/introduction-campaign-finance/election-and-voting-information/.

Column	Type	Null	Description
year	integer	no	Election year (even years 1976 to 2018 from MIT, 2020 and 2022 from the FEC; 2024 missing); PK component
state_fips	string	no	2-digit state FIPS code (FK to geo.state_ref.state_fips); PK component
state_name	string	no	State name in title case (join key to officials.members.state_name and geo.state_ref.state_name)
state_postal	string	no	2-letter postal abbreviation
district	integer	no	Congressional district number as published; 0 for an at-large state; PK component
at_large	boolean	no	True when district is 0 (the state elects one member at large)
cd_fips	string	no	4-character district code: state FIPS + 2-digit district, 00 for at-large
special	boolean	no	True for a special election (to fill a vacancy or after a court-ordered redraw); PK component
runoff	boolean	yes	True for a runoff round; null when the Lab published NA (2006 Texas special rounds); PK component
stage	string	yes	'gen' general election, 'pri' primary (1996 Texas special primaries); null when published NA; PK component
line_no	integer	no	Position of the row within its (year, state, district, special, runoff, stage) round in the published file, 1-based; makes the key unique where a candidate appears on several party lines; PK component
candidate	string	yes	Candidate name as published; null for the write-in aggregate rows
candidate_kind	string	no	'candidate' a named candidate, 'write_in_aggregate' write-ins lumped together, 'residual' a vote bucket (Blank Vote, Scatter, Over Vote, Other)
party_published	string	yes	Party label as published, lower case. MIT rows: democrat, republican, conservative, working families, democratic-farmer-labor, ...; FEC rows: the workbook's party-label name, democratic, republican, conservative, working families, ..., combined labels joined with '/' (democratic/working families). Null when published NA, and for FEC write-in rows
party_major	string	yes	D for the labels democrat and democratic-farmer-labor (MIT) and the codes D, DFL and DNL (FEC), R for republican and independent-republican (Minnesota's Republican Party until 1995; MIT) and the code R (FEC), OTHER for any other label, null when party_published is null; see the table comment for combined FEC labels
writein	boolean	no	True for write-in votes
candidate_votes	long	no	Votes this candidate received on this party line (1 when uncontested)
total_votes	long	no	Total votes cast in the district round as published (1 when uncontested)
uncontested	boolean	no	True when the Lab published candidate_votes = 1 and total_votes = 1, its marker for an unopposed race; the vote count is not real
unofficial	boolean	no	True where the Lab flagged the result as unofficial pending later update (39 rows, 2018); always false on FEC rows (an official-results publication)
version_date	string	yes	Date the Lab finalised the row (ISO date from the published yyyyMMdd version); null on FEC rows, whose workbook carries only a month (named in source_release)
source_release	string	no	Dataset, repository and commit (MIT rows) or workbook, publication month and URL (FEC rows) the row was read from
source	string	no	'MEDSL' for MIT Election Data + Science Lab rows (1976-2018), 'FEC' for Federal Election Commission rows (2020, 2022); tells the two series apart across the 2018/2020 boundary
ranked_choice	boolean	yes	True on FEC rows of a ranked-choice contest (Maine 2 and Alaska at-large, 2022), where candidate_votes and total_votes are the last-round counts; false on other FEC rows; null on MIT rows (the Lab does not flag it; Maine 2 in 2018 is a last-round count)
first_choice_votes	long	yes	First-choice votes as published (General Votes column) for a ranked-choice contest row; null otherwise

senate_election_results · table

U.S. Senate statewide returns by candidate, every election 1976 to 2024 (25 even years plus the 2021 Georgia runoffs, 3,945 rows), from the MIT Election Data + Science Lab (CC0; Harvard Dataverse doi:10.7910/DVN/PEJ5QU, file 1976-2024-senate-state, found through the Dataverse API at each fetch so a new release is picked up; the dataset has no guestbook). One row per candidate per party line per election round: year, state, whether it is a special election, the stage, the candidate, the party label as published and a normalised major-party field, votes and the published total. Each cycle elects one class (33 to 35 seats) and special elections for vacated seats add rows with special=true in the same year (Georgia 2020 carries two Senate races, the regular Perdue-Ossoff one and the special Loeffler-Warnock-Collins one). Stages as published: gen general election; runoff a runoff (the 2022 file's GEN RUNOFF is stored as runoff); pre appears only for Georgia 1992 and 2008, where pre is the first-round general election and the same year's gen rows are the decisive runoff; the Georgia 5 January 2021 runoffs (Ossoff, Warnock) are stage runoff with year 2021, although they decide the 2020 cycle's two Georgia seats, so the 2020 gen rows of Georgia are first rounds. Fusion tickets: before 2024 a candidate on several party lines (New York, Connecticut) has a row per line and the vote is the SUM over rows; the 2024 New York rows carry one combined label such as DEMOCRATIC/WORKING FAMILIES. The views senate_race_results and senate_seats_won sum a candidate's lines and assign D or R when any line is a D or R line. Quirks kept as published: write-ins lumped in rows with candidate null (write_in_aggregate); vote buckets (Over Votes, Undervotes, Blank Vote, Scatter, Void, Other, None of these candidates) are candidate_kind residual; uncontested races (Louisiana 1978 to 1992 and a few others) carry candidate_votes 1 and total_votes 1 (uncontested=true), a placeholder; the unofficial flag is true for some 2018, 2020, 2021, 2022 and 2024 rows the Lab had not yet updated; version_date is the Lab's finalisation date and differs by row (2021-01-14 for 1976 to 2020, 2023-09-20 for 2022, 2024-12-12 and 2025-11-20 for parts of 2024); total_votes counts the ballots the state reports for the race and, where a state includes undervotes, can exceed the sum of candidate votes. Joins: state_fips to geo.state_ref.state_fips; state_name to officials.members.state_name (senators have district null there); candidate-level joins to members would be name matching and are not attempted (the Lab carries no bioguide id). The Congress that a class elected in year Y joins is (Y - 1786) / 2 (2024 is Congress 119). Source: https://dataverse.harvard.edu/dataset.xhtml?persistentId=doi:10.7910/DVN/PEJ5QU.

Column	Type	Null	Description
year	integer	no	Calendar year of the election round (even years; 2021 for the Georgia January runoffs); PK component
state_fips	string	no	2-digit state FIPS code (FK to geo.state_ref.state_fips); PK component
state_name	string	no	State name in title case (join key to officials.members.state_name and geo.state_ref.state_name)
state_postal	string	no	2-letter postal abbreviation
special	boolean	no	True for a special election to fill a vacated seat; PK component
stage	string	no	'gen' general election, 'runoff', or 'pre' (Georgia 1992 and 2008 first round); PK component
line_no	integer	no	Position of the row within its (year, state, special, stage) round in the published file, 1-based; makes the key unique where a candidate appears on several party lines; PK component
candidate	string	yes	Candidate name as published, upper case; null for the write-in aggregate rows
candidate_kind	string	no	'candidate' a named candidate, 'write_in_aggregate' write-ins lumped together, 'residual' a vote bucket (Over Votes, Undervotes, Blank Vote, Scatter, Void, Other)
party_published	string	yes	party_detailed as published, upper case (DEMOCRAT, REPUBLICAN, LIBERTARIAN, INDEPENDENT, DEMOCRATIC/WORKING FAMILIES, ...); null for write-in and residual rows
party_major	string	yes	D or R when party_published is a Democratic or Republican label (DEMOCRAT, DEMOCRATIC, DEMOCRATIC-FARMER-LABOR, DEMOCRATIC-NPL, DEMOCRATIC/WORKING FAMILIES; REPUBLICAN, GOP, REPUBLICAN/CONSERVATIVE), which overrides the Lab's party_simplified where it is wrong (2022 Illinois and Maryland DEMOCRATIC are OTHER there); with no label, D or R from party_simplified when it says so; OTHER for any other published label; null when the party is not published (Murkowski 2010 and 2022 and Lummis 2020, who are Republicans in officials.members, and the write-in and residual rows). A label that contradicts party_simplified fails the fetch
writein	boolean	no	True for write-in votes
candidate_votes	long	no	Votes this candidate received on this party line (1 when uncontested)
total_votes	long	no	Total votes cast in the race round as published (1 when uncontested)
uncontested	boolean	no	True when the Lab published candidate_votes = 1 and total_votes = 1, its marker for an unopposed race; the vote count is not real
unofficial	boolean	no	True where the Lab flagged the result as unofficial pending later update
version_date	string	no	Date the Lab finalised the row (ISO date; from yyyyMMdd or the 2024 partial rows MM/dd/yy)
source_release	string	no	Dataverse dataset, version number and release date the row was read from

current_members · view

Members Congress.gov's per-member detail endpoint reports as currently holding office (members.current_member = true, populated by CongressMemberCurrentEnricher's N+1 detail call — see that column's comment). Restricted to the latest congress present in members (bounded by GOVDATA_START_CONGRESS/GOVDATA_END_CONGRESS — not necessarily the literal current Congress if those knobs haven't been bumped for a new session) so a member's row from an older congress they also served doesn't duplicate their current one. voting_member is a structural derivation, not a Congress.gov field: the House's 6 territorial/DC seats (American Samoa, DC, Guam, N. Mariana Islands, Puerto Rico's Resident Commissioner, Virgin Islands) are non-voting delegate seats, and no territory or DC has Senate representation at all — so state_name being one of the 50 states is both necessary and sufficient for floor voting rights, for House and Senate rows alike. The 6-name exclusion list is fixed by the Constitution/statute, not annually vintaged data, so it is inlined here rather than sourced from geo (whose state_ref is a 50-states+DC list that would still need this same non-DC-state test, and members' territorial state_names don't resolve against it at all — see the members table comment).

View — columns are resolved by the query engine at runtime.

state_political_index · view

Composite Political Index (CPI) per state PER CONGRESS: 0.50I_Pres + 0.30I_Senate + 0.20I_House, on a -100 (max Republican) to +100 (max Democratic) scale. One row per (congress, state) — a full historical time series, not just the latest congress. congress/congress_start_year identify which congress each row describes; join congress_start_year to any other schema's year for a same-period comparison (House/Senate composition is constant across both years of a congress, so a caller wanting an exact calendar year should pick whichever congress covers it, not assume a 1:1 congress-to-year mapping). Converted from a single "current only" snapshot to this per-congress series 2026-08-23: the prior version hardcoded congress = (SELECT MAX(congress) FROM members) for House/Senate and always used the two most recent presidential cycles globally. Both members (bounded by its own congress_range, not full 1789-present — see that table's own comment) and electoral_college_votes (1976-2024) already carried everything needed for a real series over that bounded range — the only change is computing every congress's index using the data available AS OF that congress's start year, instead of collapsing to "now". This view's own coverage is therefore no wider than members' configured range: a congress older than members' floor produces no row here either. The presidential component for congress N is resolved via congress_start_year = 1787 + 2congress (inverse of OfficialsSchemaFactory.deriveCongressRange's N = (year-1789)/2 + 1), then taking the two most recent electoral_college_votes years <= that start year — the same 2-cycle blend as before, just anchored per-congress instead of to today. DEVIATION FROM THE ORIGINAL SPEC (deliberate, decided 2026-08-02): I_Pres was specified as a two-party POPULAR vote share margin, blended 2:1 across the two most recent presidential cycles. presidential_election_results only has 2024 (FEC hasn't published this XLSX format further back yet) and carries no party column, so that could not be computed for two cycles today. Substituted a two-party ELECTORAL vote share margin from electoral_college_votes instead — it has full 1976-2024 history AND a real candidate_party column, so both cycles resolve with no fuzzy join. This is a different statistic (EV share, not popular-vote share) — do not treat i_pres as a popular-vote number. Known caveats, not silently absorbed: (1) candidate_party on electoral_college_votes is populated only for the page's winner/main-opponent — reliable as 'D'/'R' in modern two-party-dominant elections, but a state whose top-2 was NOT the two major parties would be excluded from the margin calc for that year, not misattributed. (2) party_name on members reflects Congress.gov's literal reported affiliation, NOT caucus alignment — an independent who caucuses with a party (e.g. a Sanders/King-style seat) is counted as neither s_d nor s_r, understating that state's I_Senate versus its practical governing-coalition lean. (3) i_pres degrades gracefully to M_t alone (via COALESCE) for a state with only one presidential cycle on record instead of two — verified against a synthetic single-cycle case, not just the two-cycle case. (4) H_D/H_R (and S_D/S_R) denominators are exactly as the original formula specified — vacant seats and non-D/R members are excluded from the denominator entirely, not counted as a third bucket. (5) I_Senate's /2 denominator assumes exactly 2 senators per state per congress; a mid-congress death/resignation plus appointed/special-election replacement (both rows present in members for that congress, e.g. California's 118th: Feinstein died in office, Butler was appointed to finish her term, alongside the two full-term senators) inflates s_d+s_r past 2 for that congress, which can push cpi/i_senate past the documented +-100 scale. Real turnover, not a bug — a single "current" snapshot could land on either side of a mid-congress swap and never surface this; a full series makes every such congress visible.

View — columns are resolved by the query engine at runtime.

house_race_results · view

One row per U.S. House district election round (year, state, district, special, runoff, stage) built from house_election_results, general-election rounds and special elections only (regular primaries are left out): the leader and the leader's party, the leader's and runner-up's votes, D and R votes and the two-party margin (D - R) / (D + R) in [-1, 1] (positive favours the Democratic candidate), and is_decisive marking the round that decides the district for that cycle. Votes are summed per candidate across party lines (fusion tickets), then each candidate is put in a party group: D when the candidate's Democratic lines carry more votes than the Republican lines (or only Democratic lines exist), R likewise, OTHER when the candidate has only other known lines, and null when no line has a published party (the Lab left the party blank for a few winners, for example Alabama 5, New Jersey 4 and Wisconsin 8 in 2018, all Republicans in officials.members). cross_endorsed_candidates counts candidates that have both a D line and an R line (New York 1976 to 1990 Democrats who also got the Republican line, for example); their whole vote goes to the party group with the larger line. two_party_margin is null for uncontested races (the Lab's placeholder vote of 1) and when neither major party has a candidate. is_decisive: within a (year, state, district) the round with the highest precedence, a runoff round, then the regular general election, then a special election published without a stage, then a special election published as a primary (Texas 1996, where the court-ordered redistricting elections are published as special primaries with runoffs in districts 8, 9 and 25); this gives exactly one decisive round for each of the 435 districts in every cycle 1976 to 2022 and puts the Texas 2006 redistricting special elections (published with a null stage) in the decisive round for the four districts that have no regular general round. Rounds that are not decisive (a first round that went to a runoff, a special election held beside the regular one) are kept with is_decisive false. tied is true when two candidates share the lead, in which case the leader columns are null.

View — columns are resolved by the query engine at runtime.

senate_race_results · view

One row per U.S. Senate election round (year, state, special, stage) built from senate_election_results: the leader and the leader's party, the leader's and runner-up's votes, D and R votes, the two-party margin (D - R) / (D + R) (positive favours the Democratic candidate), cycle_year (the even election year: 2020 for the Georgia runoffs of January 2021) and is_decisive. Candidate and party grouping rules are those of house_race_results (a candidate's party lines are summed, the party group follows the larger of the D and R lines, null when no line has a published party: Murkowski 2010 and 2022 and Lummis 2020, whose party the Lab left blank, are Republicans in officials.members). is_decisive: the round with the highest stage rank within (year, state, special), runoff over gen over pre, except that a first round whose state and seat have a runoff in the following year is not decisive (the Georgia 2020 general elections, decided by the 5 January 2021 runoffs). Known gaps inherited from the Lab's file (verified against the file, not filled in): no Connecticut 2022 and no North Dakota 1980 race; the regular North Carolina 1986 and Illinois 2010 elections are published with special=true; so regular-class counts are 33 or 34 per cycle except those years.

View — columns are resolved by the query engine at runtime.

election_seats_won · view

Seats won per cycle by party: for each chamber, cycle year and special-election flag, the count of decisive election rounds won by the Democratic candidate (D), the Republican (R), another party (OTHER) or a candidate whose party the Lab left blank (null). House rows are one per district: 435 seats with special=false in every cycle 1976 to 2022 (the Texas 1996 and 2006 redistricting special elections that decide a district are counted there as special=true rows, 10 and 4 seats). Senate rows are the 33 or 34 regular seats of the class up that year (with the gaps documented on senate_race_results) plus special elections; the Georgia January 2021 runoffs count in cycle_year 2020. These are election winners, not Congress rosters: a member who switches party, dies or resigns, or a seat filled by appointment, is not reflected (see officials.members for who held the seat; for Congresses 111 to 116 the winner's party is among the party names of the seat's members in every district except four party switches, one misfiled chamber and three blank parties, and for the Senate in every race except three blank parties). Independents who caucus with a party count as OTHER.

View — columns are resolved by the query engine at runtime.