Data Dictionary

This vignette describes every column returned by scrape_elections() for each supported state and level. Not every column is present for every state — the schema depends on the underlying source. Each section below covers one source, with a table per output level.

For worked examples of using these columns in analysis (filtering by office, counting party wins, computing margins, cross-state comparisons), see the Example analyses vignette.

Data Sources

State(s)	Source	URL
Connecticut	CT Election Management System (CTEMS)	https://ctemspublic.tgstg.net/#/home
Georgia	Georgia Secretary of State	https://results.sos.ga.gov/results/public/Georgia
Indiana	Indiana Election Division	https://www.in.gov/sos/elections/election-commission/election-results/
Louisiana	Louisiana Secretary of State	https://voterportal.sos.la.gov/Graphical
North Carolina	NC State Board of Elections	https://www.ncsbe.gov/results-data/election-results/historical-election-results-data
Utah	Utah Elections Portal	https://electionresults.utah.gov/results/public/Utah
Colorado (see ElectionStats)	Colorado Secretary of State	https://co.elstats2.civera.com/eng/contests
Idaho (see ElectionStats)	Idaho Secretary of State	https://canvass.sos.idaho.gov/eng/contests
Massachusetts (see ElectionStats)	Massachusetts Secretary of the Commonwealth	https://electionstats.state.ma.us/elections
New Hampshire (see ElectionStats)	New Hampshire Secretary of State	https://nh.electionstats.com/elections
New Mexico (see ElectionStats)	New Mexico Secretary of State	https://electionstats.sos.nm.gov
New York (see ElectionStats)	New York State Board of Elections	https://results.elections.ny.gov
South Carolina (see ElectionStats)	South Carolina Election Commission	https://electionhistory.scvotes.gov
Vermont (see ElectionStats)	Vermont Secretary of State	https://electionarchive.vermont.gov/elections
Virginia (see ElectionStats)	Virginia Department of Elections	https://historical.elections.virginia.gov

---

Connecticut

Source: CT Election Management System (CTEMS). Results available 2016–present.

$state

Column	Type	Description
state	character	State abbreviation ("CT")
election_name	character	Human-readable election name (e.g. "11/05/2024 -- November General Election")
election_year	integer	Calendar year of the election
election_date	character	Date of the election
election_type	character	Election type extracted from election_name (e.g. "General Election", "August Primary")
office_level	character	"Federal", "State", or "Local"
office	character	Office name
district	character	County name for Local races; NA for statewide (Federal/State) races
town	character	Town name for Local races; NA for statewide (Federal/State) races
candidate	character	Candidate name
party	character	Party name (e.g. "Democratic", "Republican")
votes	integer	Total votes
vote_pct	numeric	Percentage of votes within the contest; write-ins are excluded, so may not sum to 100%
winner	logical	TRUE if the candidate won the statewide contest

$town

Column	Type	Description
state	character	State abbreviation ("CT")
election_name	character	Human-readable election name
election_year	integer	Calendar year of the election
election_date	character	Date of the election
election_type	character	Election type extracted from election_name (e.g. "General Election", "August Primary")
office_level	character	"Federal", "State", or "Local"
office	character	Office name
district	character	County name
town	character	Town name
candidate	character	Candidate name
party	character	Party name
votes	integer	Votes cast in this town
vote_pct	numeric	Percentage of votes within this town; write-ins are excluded, so may not sum to 100%
town_winner	logical	TRUE if the candidate won within this town

---

Georgia

Source: Georgia Secretary of State. Results available 2000–present.

$state

Column	Type	Description
state	character	State abbreviation ("GA")
election_name	character	Human-readable election name (e.g. "November General Election")
election_type	character	Election type (e.g. "General", "Primary")
election_year	integer	Calendar year of the election
election_date	character	Date string from the page header
office_level	character	"Federal", "State", or "Local"
office	character	Office name
district	character	District identifier; NA when not applicable
candidate	character	Candidate name
party	character	Party abbreviation
votes	integer	Total votes
vote_pct	numeric	Percentage of votes within the contest; write-ins are excluded, so may not sum to 100%
winner	logical	TRUE if the candidate won the statewide contest
url	character	URL of the election results page scraped

$county

Column	Type	Description
state	character	State abbreviation ("GA")
election_name	character	Human-readable election name
election_type	character	Election type (e.g. "General", "Primary")
election_year	integer	Calendar year of the election
election_date	character	Date string from the page header
office_level	character	"Federal", "State", or "Local"
office	character	Office name
district	character	District identifier; NA when not applicable
county	character	County name
candidate	character	Candidate name
party	character	Party abbreviation
votes	integer	County-level vote total
vote_pct	numeric	Percentage of votes within the contest for this county; write-ins are excluded, so may not sum to 100%
county_winner	logical	TRUE if the candidate won within this county
url	character	URL of the election results page scraped

$precinct

Column	Type	Description
state	character	State abbreviation ("GA")
election_name	character	Human-readable election name
election_type	character	Election type (e.g. "General", "Primary")
election_year	integer	Calendar year of the election
election_date	character	Date string from the page header
office_level	character	"Federal", "State", or "Local"
office	character	Office name
district	character	District identifier; NA when not applicable
county	character	County name
precinct	character	Precinct name
candidate	character	Candidate name
party	character	Party abbreviation
votes	integer	Precinct-level vote total
vote_pct	numeric	Percentage of votes within the contest for this precinct; write-ins are excluded, so may not sum to 100%
precinct_winner	logical	TRUE if the candidate won within this precinct
url	character	URL of the precinct results page scraped

---

Indiana

Source: Indiana Election Division. General Elections only, 2019–present.

$state

Column	Type	Description
state	character	State abbreviation ("IN")
election_year	integer	Calendar year of the election
election_date	character	Date of the election
election_type	character	Always "General"
office_level	character	"Federal", "State", or "Local"
office	character	Office name (e.g. "County Offices")
district	character	District identifier; NA when not applicable
candidate	character	Candidate name as printed on the ballot
party	character	Full party name (e.g. "Republican", "Democrat")
votes	integer	Statewide vote total
vote_pct	numeric	Percentage of votes within the contest; write-ins are excluded, so may not sum to 100%
winner	logical	TRUE if the candidate won
num_seats	integer	Number of seats available in the contest

$county

Column	Type	Description
state	character	State abbreviation ("IN")
election_year	integer	Calendar year of the election
election_date	character	Date of the election
election_type	character	Always "General"
office_level	character	"Federal", "State", or "Local"
office	character	Office name
district	character	District identifier; NA when not applicable
county_name	character	County name
candidate	character	Candidate name as printed on the ballot
party	character	Full party name
votes	integer	County-level vote total
vote_pct	numeric	Percentage of votes within the contest for this county; write-ins are excluded, so may not sum to 100%
county_winner	logical	TRUE if the candidate won within this county
num_seats	integer	Number of seats available in the contest

---

Louisiana

Source: Louisiana Secretary of State. Results available 1982–present.

$state

Column	Type	Description
state	character	State abbreviation ("LA")
election_name	character	Human-readable election name (e.g. "November 5, 2024 General Election")
election_year	integer	Calendar year of the election
election_date	character	Date of the election
office_level	character	"Federal", "State", or "Local"
office	character	Office title
district	character	Court, district, or seat qualifier; NA when not present
candidate	character	Candidate name
party	character	Full party name (e.g. "Republican", "Democratic")
votes	integer	Vote total
vote_pct	numeric	Percentage of votes within the contest; write-ins are excluded, so may not sum to 100%
winner	logical	TRUE if the candidate won
voter_turnout_pct	numeric	Statewide voter turnout percentage; NA when not published

$parish

Column	Type	Description
state	character	State abbreviation ("LA")
election_name	character	Human-readable election name
election_year	integer	Calendar year of the election
election_date	character	Date of the election
office_level	character	"Federal", "State", or "Local"
office	character	Office title
district	character	Court, district, or seat qualifier; NA when not present
parish	character	Parish name (e.g. "Orleans Parish")
candidate	character	Candidate name
party	character	Full party name
votes	integer	Parish-level vote total
vote_pct	numeric	Percentage of votes within the contest for this parish; write-ins are excluded, so may not sum to 100%
parish_winner	logical	TRUE if the candidate won within this parish
parish_voter_turnout_pct	numeric	Parish-level voter turnout percentage; NA when not published

---

North Carolina

Source: NC State Board of Elections. Results available 2000–present.

$precinct

Column	Type	Description
state	character	Always "NC"
county	character	County name
election_date	character	Date of the election
election_type	character	Election type (e.g. "General", "Primary")
election_year	integer	Calendar year of the election
precinct	character	Precinct name or identifier
contest_group_id	character	Internal contest group identifier from NCSBE
contest_type	character	Contest type code from NCSBE
contest_name	character	Full contest name as reported by NCSBE
jurisdiction	character	Jurisdiction extracted from the contest name
office_level	character	"Federal", "State", or "Local"
district	character	District identifier; NA when not applicable
candidate	character	Candidate name
party	character	Party abbreviation
vote_for	integer	Number of seats to fill in the contest
election_day	integer	Election Day votes
early_voting	integer	Early voting votes
absentee_by_mail	integer	Absentee by mail votes
absentee_or_early	integer	Combined absentee/early votes; populated in older files before the fields were separated
provisional	integer	Provisional votes
votes	integer	Total votes
winner_status	character	Raw winner status string from NCSBE
real_precinct	logical	FALSE for pseudo-rows (e.g. absentee-only counters) included in NCSBE files
precinct_abbrv	character	Precinct abbreviation

$county

Column	Type	Description
state	character	Always "NC"
county	character	County name
election_date	character	Date of the election
election_year	integer	Calendar year of the election
office	character	Office name derived from contest name
jurisdiction	character	Jurisdiction extracted from the contest name
office_level	character	"Federal", "State", or "Local"
district	character	District identifier; NA when not applicable
candidate	character	Candidate name
party	character	Party abbreviation
election_day	integer	Election Day votes aggregated to county
early_voting	integer	Early voting votes aggregated to county
absentee_by_mail	integer	Absentee by mail votes aggregated to county
absentee_or_early	integer	Combined absentee/early votes (older files)
provisional	integer	Provisional votes aggregated to county
votes	integer	Total votes aggregated to county

$state

Column	Type	Description
state	character	Always "NC"
election_date	character	Date of the election
election_year	integer	Calendar year of the election
office	character	Office name derived from contest name
jurisdiction	character	Jurisdiction extracted from the contest name
office_level	character	"Federal", "State", or "Local"
district	character	District identifier; NA when not applicable
candidate	character	Candidate name
party	character	Party abbreviation
election_day	integer	Election Day votes aggregated statewide
early_voting	integer	Early voting votes aggregated statewide
absentee_by_mail	integer	Absentee by mail votes aggregated statewide
absentee_or_early	integer	Combined absentee/early votes (older files)
provisional	integer	Provisional votes aggregated statewide
votes	integer	Total votes
vote_pct	numeric	Percentage of votes within the contest; write-ins are excluded, so may not sum to 100%
winner	logical	TRUE for the highest-voted candidate(s) per contest

---

Utah

Source: Utah elections portal. Results available 2023–present.

$state

Column	Type	Description
state	character	State abbreviation ("UT")
election_name	character	Human-readable election name
election_type	character	Election type (e.g. "General", "Primary")
election_year	integer	Calendar year of the election
election_date	character	Date string from the page header
office_level	character	"Federal", "State", or "Local"
office	character	Office name
district	character	District identifier; NA when not applicable
candidate	character	Candidate name
party	character	Party abbreviation
votes	integer	Total votes
vote_pct	numeric	Percentage of votes within the contest; write-ins are excluded, so may not sum to 100%
winner	logical	TRUE if the candidate won the statewide contest
url	character	URL of the election results page scraped

$county

Column	Type	Description
state	character	State abbreviation ("UT")
election_name	character	Human-readable election name
election_type	character	Election type (e.g. "General", "Primary")
election_year	integer	Calendar year of the election
election_date	character	Date string from the page header
office_level	character	"Federal", "State", or "Local"
office	character	Office name
district	character	District identifier; NA when not applicable
county	character	County name
candidate	character	Candidate name
party	character	Party abbreviation
votes	integer	County-level vote total
vote_pct	numeric	Percentage of votes within the contest for this county; write-ins are excluded, so may not sum to 100%
county_winner	logical	TRUE if the candidate won within this county
url	character	URL of the election results page scraped

$precinct

Column	Type	Description
state	character	State abbreviation ("UT")
election_name	character	Human-readable election name
election_type	character	Election type (e.g. "General", "Primary")
election_year	integer	Calendar year of the election
election_date	character	Date string from the page header
office_level	character	"Federal", "State", or "Local"
office	character	Office name
district	character	District identifier; NA when not applicable
county	character	County name
precinct	character	Precinct name
candidate	character	Candidate name
party	character	Party abbreviation
votes	integer	Precinct-level vote total
vote_pct	numeric	Percentage of votes within the contest for this precinct; write-ins are excluded, so may not sum to 100%
precinct_winner	logical	TRUE if the candidate won within this precinct
url	character	URL of the precinct results page scraped

---

ElectionStats

Source: ElectionStats. Covers CO, ID, MA, NH, NM, NY, SC, VT, VA. Year coverage varies by state. Precinct-level data available for ID, NM, SC, and VA.

$state

Column	Type	Description
state	character	State abbreviation (e.g. "CO", "VA")
election_year	integer	Calendar year of the election
election_id	integer	Internal ElectionStats election identifier
election_type	character	Election stage (e.g. "General", "Primary")
office_level	character	"Federal", "State", or "Local"
office	character	Office name
district	character	District identifier; NA when not applicable
candidate_id	integer	Internal ElectionStats candidate identifier
candidate	character	Candidate name
party	character	Party name as returned by ElectionStats
votes	integer	Total votes
vote_pct	numeric	Percentage of votes within the contest; write-ins are excluded, so may not sum to 100%
winner	logical	TRUE if the candidate won
url	character	URL for the candidate detail page on ElectionStats

$county

Column	Type	Description
state	character	State abbreviation
election_year	integer	Calendar year of the election
election_id	integer	Internal ElectionStats election identifier
election_type	character	Election stage (e.g. "General", "Primary")
office_level	character	"Federal", "State", or "Local"
office	character	Office name
district	character	District identifier; NA when not applicable
county_or_city	character	County or independent city name
candidate_id	integer	Internal ElectionStats candidate identifier
candidate	character	Candidate name
party	character	Party name
votes	integer	Vote total for this county or city
vote_pct	numeric	Percentage of votes within the contest for this county/city; write-ins are excluded, so may not sum to 100%
county_winner	logical	TRUE for the top vote-getter within each county/city
url	character	URL for the candidate detail page on ElectionStats

$precinct (ID, NM, SC, VA only)

Column	Type	Description
state	character	State abbreviation
election_year	integer	Calendar year of the election
election_id	integer	Internal ElectionStats election identifier
election_type	character	Election stage (e.g. "General", "Primary")
office_level	character	"Federal", "State", or "Local"
office	character	Office name
district	character	District identifier; NA when not applicable
county	character	County name
precinct	character	Precinct name or identifier
candidate_id	integer	Internal ElectionStats candidate identifier
candidate	character	Candidate name
party	character	Party name
votes	integer	Vote total for this precinct
vote_pct	numeric	Percentage of votes within the contest for this precinct; write-ins are excluded, so may not sum to 100%
precinct_winner	logical	TRUE for the top vote-getter within each precinct
url	character	URL for the candidate detail page on ElectionStats

---

Further reading

Each source has its own vignette with argument reference, worked examples, and performance notes:

• Connecticut
• Georgia
• Indiana
• Louisiana
• North Carolina
• Utah
• ElectionStats states (VA, MA, CO, NH, ID, SC, NM, NY, VT)