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 docid\ ddif6z6lr1 lmr6ov4exm , districts docid\ kdauezki9ijql2gz9 l3z , elections docid\ dv5oz2oghgw71mecmtge9 , and voters docid 3oen1vuistn6yqclc0u9u tables overview 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 data structure 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 https //www census gov/library/reference/code lists/mt feature class codes html# text=the%20maf%2ftiger%20feature%20class,in%20the%20tiger%2fline%20products 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 https //www census gov/programs surveys/geography/guidance/geo identifiers html 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 https //support ballotready org/ballotready data tiers position and candidate research 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 email 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