Data dictionary: Candidates

The tables below define each of the attributes you may receive in your dataset -- column name and description.

Basic information

column name	description
election_year	The year the race is occuring
state	The state in which the office has jurisdiction (postal abbreviation)

Office, District (Geography)

column name	description
office_id	Ballotpedia unique identifier (stable across election years)
office_name	Name of the office
office_level	Level of government: -Federal -State -Local
office_branch	Branch of government: -Executive -Legislative -Judicial
district_id	Ballotpedia unique identifier
district_ocdid	The Open Civic Data Division Identifiers project seeks to assign somewhat predictable and globally unique identifiers to political divisions. This field is not uniformly filled due to data availability.
district_name	Name of district (geographical area) that elects the office.
district_type	Type of district that elects the office: -Country -State -Congress -State Legislative (Upper) -State Legislative (Lower) -County -School District -City-town -Judicial District -Special District -State subdivision -County subdivision -Judicial district subdivision -Special district subdivision -City-town subdivision -School district subdivision
parent_district_id	Ballotpedia unique identifier used to associate a "subdivision" district with its parent (not comprehensive). Example: "X City Council, District 1" and "X City Council, District 2" have a parent district of "X City".
parent_district_name	Name of parent district

Race

column name	description
race_id	Ballotpedia unique identifier
race_type	One of the following: -Regular -Special -Recall -Retention
seats_up_for_election	The number of positions this race will fill in the office.
race_url	Link to the Ballotpedia overview page about this race/election.

Stage, Election Date

column name	description
election_date_id	Ballotpedia unique identifier
election_date	The date that the stage contest is scheduled to appear before voters.
election_date_district_type	Often linked to the State, provides additional detail about which geographical area might be having an election at this time.
stage_id	Ballotpedia unique identifier (stable across ranked-choice voting rounds, if applicable).
stage	One of the following: -Convention -Primary -Primary Runoff -General -General Runoff
stage_party	For partisan primaries, provides a political party name. Each partisan primary or primary runoff will have its own stage.
is_partisan_primary	true / false for Primary or Primary Runoff stages, where applicable. Otherwise NULL. This indicates whether candidates in the primary were limited by party (such as a traditional Republican or Democratic Party primary) or not (such as an open primary in California). More information here: https://ballotpedia.org/Primary_election
stage_is_canceled	true / false to indicate if the stage has been canceled
stage_is_ranked_choice	true / false to indicate if the stage is conducted by ranked-choice voting
stage_write_in_other_votes	Includes additional write-in votes for the stage (votes that are not associated with a particular candidate, but relevant to vote totals).

Candidate

column name
candidate_id	Ballotpedia unique identifier
person_id	Ballotpedia unique identifier
name	Full name of the candidate
first_name	First name of the candidate
last_name	Last name of the candidate
ballotpedia_url	Link to the Ballotpedia profile about this candidate
gender	One of the following, or NULL: -Male -Female -Neither/Both (if the person explicitly identifies as neither or both of the above)
party_affiliation	The political party affiliation that the candidate is running under (one or more). If the candidate is cross-filed in a primary, they will have a row for their participation in each party’s primary they are running in and this field will indicate that party. If they advanced to a general under more than one party, all those parties will be listed in this field. Party affiliation for candidates in nonpartisan elections is listed as "Nonpartisan".
is_incumbent	true / false to indicate whether the candidate held the office they are seeking at the time of announcing their candidacy. See further details for how Ballotpedia handles appointees and redistricting situations here: https://ballotpedia.org/Incumbent
candidate_status	-Candidacy Declared: announced a run for the office but has not yet qualified for the ballot -On the Ballot: filing with election office is complete, and the election office has published the person as an official candidate -Advanced: The candidate received the most votes (or was one of the top vote recipients in a race with more than one seat up for election) in this stage of the election (such as a primary) and is going on to further rounds (such as a general). Effectively, this indicates the winner of a stage when the full race is not yet complete. This also applies to RCV stages, where a candidate may advance from multiple rounds within a single stage. -Won: The candidate received the most votes (or was one of the top vote recipients in a race with more than one seat up for election) and will assume office. -Lost: The candidate did not advance to another stage (or RCV round) and/or did not garner enough votes to win the seat. -Withdrew: The candidate withdrew from the election and will not appear on the ballot. -Disqualified: The candidate was disqualified from the election and will not appear on the ballot.
is_write_in	true / false to indicate if the candidate’s name was or will be printed on the ballot. Note that in some cases write-ins do file official paperwork and can thus have candidate_status=On the ballot while is_write_in=true.
is_withdrawn_still_on_ballot	true / false to capture scenarios where a candidate misses the official withdrawal deadline and will appear on the ballot despite announcing publicly their intent to withdraw
votes_for	Number of votes received in favor of the candidate in this stage (and RCV round, if applicable)
votes_against	Number of votes against the candidate. Only applicable to Recalls, Retentions, and RCVs.
delegates_pledged	Applicable to the general election for U.S. President
ranked_choice_voting_round	RCV results are reported in “rounds” of calculations. Ballotpedia reports each round of these results, so a candidate in an RCV stage will have a row for each round of calculation in that stage. The first round of results reported will be round "1". Rounds will count up by 1 until the final round.

Contact information (add-on)

Contact information is optional, available for an additional charge.

Values are listed below. The "campaign" contact is the one used by the candidate's campaign. All other contacts were identified as belonging to the candidate for non-campaign purposes.

Values:

• campaign_email

• other_email

• campaign_website

• personal_website

• campaign_facebook

• personal_facebook

• campaign_x

• personal_x

• campaign_tiktok

• personal_tiktok

• campaign_instagram

• personal_instagram

• campaign_youtube

• personal_youtube

• campaign_mailing_address

• campaign_phone

• linkedin