candidacies
To help users get the best information about past and future elections, we've worked with BallotReady to build a crosswalk between our datasets. This table includes proprietary data on past and current candidacies from BallotReady, which we've linked to our campaigns, districts, elections, and voters tables.
The Candidacies Dataset, one of the many datasets available through BallotReady’s Data Packages, is used to explore candidates who have run for election at all levels of government across the country, from congress to local school boards. You can easily filter this dataset to focus on positions and races of interest by location, government level, position types, and candidate party. Our dataset includes candidate contact information, websites and social media links, and the win/loss status of the candidacy.
Whether you are looking to contact candidates who previously ran for election and are likely to run again; identify candidates with specific backgrounds, such as teachers, engineers, or military veterans; or decide which candidates your organization wants to support this election year, the Candidacies Dataset is a perfect starting point for your programming.
As with all of our datasets, the Candidacies Dataset can be combined with other datasets to build a Data Package that meets all of your needs. Our candidate education, work experience, issue stances, and endorsements datasets can seamlessly combine with our Candidacies Dataset to provide you with a holistic picture of each individual's background and campaign.
This dataset includes one row per candidacy. We define a candidacy as the combination of a candidate, position, election day, and race type. If a candidate participates in both a primary and general election for the same position in a given year, they will have two candidacy records in our dataset. Similarly, if a candidate runs for both a regular and unexpired term race for the same position on the same day, they will have two candidacy records in our dataset.
Various ID fields can be used to track people and positions across races.
- Candidate_id is used to identify a person’s electoral history across pimary/general races and election years
- Election_id can be used to identify all of the candidates and races on the ballot on a given date within a state
- Race_id can be used to identify all of the candidates that will be on the ballot for a specific position
- Position_id can be used to track the races and candidacies across the position’s primary, general, and runoff elections.
- Normalized_position_id can be used to identify positions of the same type, such as State Senators, City Mayors, or Local School Boards.
Other fields in the dataset serve as attributes about the candidacy, but can also be used to filter down the races that are most applicable for your needs. For example, you could choose to filter on level to take a deeper look at city level positions, or filter on election_result and is_primary to find the candidates that lost their primary election.
Field | Type | Description |
|---|---|---|
candidacy id | integer | A unique identifier for each instance of a candidate running for a position for a certain election in the BallotReady database |
election id | integer | A unique identifier for each election in the BallotReady database, where an election is the combination of a state and a date |
election name | character varying | A descriptive name for the election according to BallotReady's naming conventions. This name may not always match the precise name used by state or local election officials. |
election day | date | The date of the election |
position id | integer | A unique identifier for each position on a ballot in the BallotReady database |
mtfcc | character varying | Tabulation area defined by the Census Bureau. Values starting with X are from BallotReady's custom research. MAF/TIGER Feature Class Code (MTFCC) is a 5-digit code assigned by the Census Bureau intended to classify and describe geographic objects or features. |
geo id | character varying | Geographic identifier defined by the Census Bureau. GEO_ID/FIPS code describing the type of place the body is associated with, according to the census specification. |
position name | character varying | The name of the position that encompasses both official ballot and BallotReady position naming conventions |
sub area name | character varying | A parsed portion of the position name, used to help identify the specific area the position represents. Sub_area_name is used to identify the type of sub area (e.g., "District" or "Region"). |
sub area value | character varying | A parsed portion of the position name, used to help identify the specific area the position represents. Sub_area_value is used to identify the number or office of the subarea (e.g., "1" or "West"). |
sub area name secondary | character varying | A second parsed portion of the position name, used to help identify the specific area the position represents when there are two levels of sub area. For example, a position with the name "Smith County Council - Region 1, Seat 2" would have sub_area_name = 'Region', sub_area_value = '1', sub_area_name_secondary = 'Seat' and sub_area_value_secondary = '2'. |
sub area value secondary | character varying | A second parsed portion of the position name, used to help identify the specific area the position represents when there are two levels of sub area. For example, a position with the name "Smith County Council - Region 1, Seat 2" would have sub_area_name = 'Region', sub_area_value = '1', sub_area_name_secondary = 'Seat' and sub_area_value_secondary = '2'. |
state | character varying | The state in which the position is elected |
level | character varying | An identifier for the level of the position: federal, state, regional, county, city, or local |
tier | integer | BallotReady-defined Tiers of coverage (1-5), as described here. |
is judicial | boolean | A boolean marked as true if the position is for electing a judge |
is retention | boolean | A boolean marked as true if the position is for a retention election (i.e., a yes/no vote) |
number of seats | integer | The maximum number of people who will be elected to that position during a given race. Note that staggered term positions will have seats on a board split over multiple positions. For example, a 5 member board that elects 2 members in 2024 and 3 members in 2026 will have two separate position records, one with 2 seats and one with 3 seats. |
normalized position id | integer | A unique identifier for each generic position type (e.g., County Clerk, City Legislative, etc.). |
normalized position name | character varying | Describes the generic position type (e.g., County Clerk, City Legislative, etc.). Double slash symbols "//" represent an "OR", typically when the same type of position can go by different terms. A single slash accompanied by "(Joint)" represents a position that is responsible for functions typically performed by multiple positions. |
race id | integer | A unique identifier for each race, which is the combination of a position, an election, and a race type (primary, general, unexpired, etc.) |
geofence id | bigint | A unique identifier for each geofence which encapsulates the geographic region related to the candidacy in the BallotReady database |
geofence is not exact | boolean | True if the geospatial data tied to the position is an estimation of who votes for the position rather than an exact boundary. This field can be true if the position is elected by subdistrict but we only have the boundaries of the overall jurisdiction (city council districts but we only have the city boundaries). It can also be true if we do not have the boundaries for the position but we've estimated the boundaries to a larger known jurisdiction (a special district that we know is within a specific county). |
is primary | boolean | A boolean marked as true if the race is primary and false if the race is a general |
is runoff | boolean | A boolean marked as true if the race is a runoff |
is unexpired | boolean | A boolean marked as true if the race is to fill an unexpired term |
candidate id | integer | A unique identifier for the person in the BallotReady database |
first name | character varying | The first name of the person as it appears on the ballot or an official government website |
middle name | character varying | The middle name of the person as it appears on the ballot or an official government website |
nickname | character varying | The nickname of the person as it appears on the ballot or an official government website |
last name | character varying | The last name of the person as it appears on the ballot or an official government website |
suffix | character varying | The suffix of the person as it appears on the ballot or an official government website |
phone | character varying | The candidate's phone number, sourced from a campaign website or official filing materials. |
character varying | The candidate's email address, sourced from a campaign website or official filing materials | |
image url | character varying | A URL to a candidate photo as it appears on a campaign social media account or website, with a preference for candidate photos that resemble those used for driver's licenses or state issued ids, as opposed to candid or informal photos. BallotReady tries to crop photos to center the candidate's face wherever possible |
parties | json | Identifies the name of the party or parties the candidate is listed under on a ballot. BallotReady does not provide party affiliations for candidates in nonpartisan races. This field is in a json format to account for candidates who run under multiple parties for the same race. |
urls | json | Identifies the candidate's campaign website or social media link and the type of url. This field is in a json format to account for a candidate having multiple urls of various types. |
election_result | character varying | Provides the election result for the given candidacy, which can be LOSS, PRIMARY_WIN, RUNOFF, or GENERAL_WIN. Where election results have not been researched, the value will be null. |
candidacy_created_at | timestamp | A timestamp of when the candidacy record was created |
candidacy_updated_at | timestamp | A timestamp of when the candidacy record was most recently updated |