Skip to contents

North Carolina elections

Source: vignettes/articles/north-carolina.Rmd
north-carolina.Rmd

What it covers

The NC scraper returns precinct-level local election results from the NC State Board of Elections, filtered by year range.

Note: Only the 2025 election file layout is currently supported. Elections before 2025 use an older format that has not yet been implemented; they are automatically skipped with an informational message.

Arguments

Argument Default Description
state "NC" (any NC alias) "NC", "north_carolina", or "north carolina"
year_from NULL Start year, inclusive; NULL = no lower bound
year_to NULL End year, inclusive; NULL = no upper bound

Examples

Precinct + county + state results for a single year 

res <- scrape_elections(state = "NC", year_from = 2025, year_to = 2025)

# Precinct-level results
res$precinct %>%
  filter(county == "Wake") %>%
  select(election_date, contest_name, precinct, candidate, party, votes) %>%
  arrange(contest_name, desc(votes))

# County-level aggregates
res$county %>%
  filter(office_level == "State") %>%
  select(county, election_date, contest_name, candidate, party, votes) %>%
  arrange(contest_name, county, desc(votes))

# Statewide totals
res$state %>%
  filter(winner == TRUE) %>%
  select(election_date, contest_name, candidate, party, votes, vote_pct)

Statewide totals only (faster — skips precinct/county detail) 

state_df <- scrape_elections(state = "NC", year_from = 2025, year_to = 2025,
                              level = "state")

state_df %>%
  select(election_date, contest_name, candidate, party, votes, vote_pct, winner)

Filter to a specific county 

res <- scrape_elections(state = "NC", year_from = 2025, year_to = 2025)

res$county %>%
  filter(county == "Wake") %>%
  select(election_date, contest_name, candidate, party, votes) %>%
  arrange(contest_name, desc(votes))

Columns returned

$precinct (when level = "all" or "precinct")

Column Description
state Always "NC"
election_date Date of the election
election_year Calendar year of the election
election_type Election type (e.g. "General", "Primary")
county County name
precinct Precinct name or identifier
contest_name Full contest name as reported by NCSBE
contest_type Contest type code
contest_group_id Internal contest group identifier
jurisdiction Jurisdiction extracted from contest name
office_level "Federal", "State", or "Local"
district District identifier (when applicable)
candidate Candidate name
party Party abbreviation
vote_for Number of seats to fill
election_day Election day votes
early_voting Early voting votes
absentee_by_mail Absentee by mail votes
absentee_or_early Combined absentee/early votes (older files)
provisional Provisional votes
votes Total votes
winner_status Raw winner status string from NCSBE source
runoff_status Runoff indicator from source
recount_status Recount indicator from source
real_precinct Whether the row represents a real precinct
precinct_abbrv Precinct abbreviation
ftp_date File date from NCSBE

$county (when level = "all" or "county")

Column Description
state Always "NC"
county County name
election_date Date of the election
contest_name Full contest name
jurisdiction Jurisdiction extracted from contest name
office_level "Federal", "State", or "Local"
district District identifier (when applicable)
candidate Candidate name
party Party abbreviation
election_day Election day votes aggregated to county
early_voting Early voting votes aggregated to county
absentee_by_mail Absentee by mail votes aggregated to county
absentee_or_early Combined absentee/early votes (older files)
provisional Provisional votes aggregated to county
votes Total votes aggregated to county

$state (when level = "all" or "state")

Same columns as $county, minus county, plus:

Column Description
vote_pct Percentage of votes within the contest
winner TRUE for the highest-voted candidate(s) per contest