Table · senate-results
US Senate election results, 1976-2024
Statewide returns for every US Senate election from 1976 to 2024, including special elections and runoffs: one row per candidate per ballot line, from the MIT Election Data + Science Lab.
- Updates
- Every 2 years
- Coverage
- —
- Current version
- —
- Last published
- —
- Validation
- —
- License
- CC0 1.0
- Commercial use
- Allowed
Preview
Use the API
The examples follow the rows picked above. See the docs for versions, caching and errors.
curl
# All rows (.json or .csv)
curl -s "https://api.electiondata.dev/v1/senate-results/table/all.json"
# The whole table in one file
curl -sO "https://api.electiondata.dev/v1/senate-results/download/senate-results.csv"Python (polars)
import polars as pl
# All rows
df = pl.read_csv("https://api.electiondata.dev/v1/senate-results/table/all.csv")
# The whole table
everything = pl.read_parquet("https://api.electiondata.dev/v1/senate-results/download/senate-results.parquet")JavaScript
const res = await fetch("https://api.electiondata.dev/v1/senate-results/table/all.json");
if (!res.ok) throw new Error((await res.json()).detail); // errors are problem+json
const { meta, rows } = await res.json();
console.log(meta.rows, rows[0]);Downloads
The whole dataset in one file. Parquet keeps the column types and is much smaller.
- senate-results.csv CSV
- senate-results.parquet Parquet
Schema
Rows are identified by year, state_po, special, stage, race_row.
The rows are also split into one file per value of year.
Tables up to 50,000 rows also have a single table/all file.
| Column | Type | Unit | Can be empty | Description |
|---|---|---|---|---|
| year key partition | year (YYYY) | — | no | Year of the election |
| state | text | — | no | State name in upper case |
| state_po key | text | — | no | USPS state code |
| state_fips | integer | — | no | State FIPS code |
| state_cen | integer | — | no | Census Bureau state code |
| state_ic | integer | — | no | ICPSR state code |
| state_id | text | — | no | Location id in the shared registry (us-<usps>) |
| office | text | — | no | Always US SENATE |
| district | text | — | no | Always STATEWIDE |
| stage key | text | — | no | GEN (general), RUNOFF, or PRE (a general that went to a runoff) |
| special key | true / false | — | no | True for a special election to fill a vacancy |
| race_row key | integer | — | no | Position of the row within its race in MEDSL's file |
| candidate | text | — | yes | Candidate as MEDSL spells it, upper case; null for unnamed write-ins |
| party_detailed | text | — | yes | Ballot line (party) as reported |
| party_simplified | text | — | yes | DEMOCRAT, REPUBLICAN, LIBERTARIAN or OTHER |
| writein | true / false | — | no | True for write-in votes |
| mode | text | — | no | Vote mode; always TOTAL in this file |
| candidatevotes | integer | votes | yes | Votes on this ballot line; null where MEDSL marks a race with no reported count |
| totalvotes | integer | votes | yes | Total votes in the race as MEDSL reports it |
| candidate_total_votes | integer | votes | yes | The candidate's votes on all ballot lines in the race (fusion voting); null for unnamed write-ins |
| unofficial | true / false | — | no | True where MEDSL took the figures from unofficial results |
| version | date (YYYY-MM-DD) | — | no | Date MEDSL finalized the row |
Source and license
- Source
- MIT Election Data and Science Lab, U.S. Senate statewide 1976-2024
- Publisher
- MIT Election Data and Science Lab (MEDSL)
- License
- CC0 1.0 (public domain dedication) (
CC0-1.0) - Commercial use
- Allowed
Credit the source with this exact text:
MIT Election Data and Science Lab, 2017, "U.S. Senate statewide 1976–2024", https://doi.org/10.7910/DVN/PEJ5QU, Harvard Dataverse, V8, UNF:6:jRgjMTzXKaB+psjQ9tTqMQ== [fileUNF]
Checked every 7 days. If the source hasn't changed in 3 years, the status page flags it as stale.
Endpoints
Every URL for this dataset. To pin the current version, put it after the id:
/v1/senate-results@<version>.
The API reference describes each response.
| What | URL |
|---|---|
| Metadata: version, coverage, downloads, validation | /v1/senate-results |
| Versions and monthly snapshots | /v1/senate-results/versions |
| Partitions | /v1/senate-results/locations |
| Rows for one year (JSON) | /v1/senate-results/table/{year}.json |
| Rows for one year (CSV) | /v1/senate-results/table/{year}.csv |
| All rows in one file (tables up to 50,000 rows) | /v1/senate-results/table/all.json |
| Whole dataset (CSV) | /v1/senate-results/download/senate-results.csv |
| Whole dataset (Parquet) | /v1/senate-results/download/senate-results.parquet |