Election Candidate Reports

 

ON THIS PAGE      Show

 

 

 

 

Description

Four separate candidate reports are provided, including U.S. House candidates, U.S. Senate candidates, candidates for Governor and candidates running for President in each state. Candidates are listed by state in each of the reports. In the Presidential report, a candidate may be listed multiple times since their ballot status may be different for each state.

Data Elements

 

  Note

 

These reports are also available in JSON, with the XML version of the report returned by default when you follow the direct link to the report from the report list (for more information, see Election Reports). For brevity, report examples in the online documentation are provided in XML. JSON property names match the names of the XML elements.

 

 

 

This table describes the XML elements used in the Candidate reports.

 

XML Element

Description

OfficeCandidates[ByState]year

The tag for this report; for example, PresidentialCandidatesByState2024, HouseCandidates2024, SenateCandidates2024, GubernatorialCandidates2024.

lastupdated

The date when the report was last updated.

CandidateInformation

Contains information about the candidate.

State

Two-character state postal code.

Seat

(For U.S. House candidates only) The district number.

Primary_Caucus_Date

(For Presidential candidates only) The date of the state primary or caucus event.

State_Primary_Date

(For other candidates) The date of the state primary event.

Runoff_Date

(For U.S. House/Senate runoff and potential runoff candidates only) The date of the runoff race.

Candidate_Name

Candidate's full name including any special nicknames or suffixes; for example, Charles "Wally" Coppock or Joe Edwards Collins, III.

First_Name

Candidate's first name.

Last_Name

Candidate's last name.

Party

Party affiliation for a specific candidate, abbreviation (for example, Dem, GOP, Lib).

NPID

Unique National Politician ID across all states and races.

Senate_Class

(For current U.S. Senators only) The Senate class (for example, Class II) to which the senator belongs.

Status

Indicates the candidate’s status; for example, confirms if the candidate is on the ballot, is qualified for the GE, lost the primary or is in a runoff.

Incumbent

Indicates that the candidate is an incumbent. Possible value is yes.

Incumbent_Running

(For incumbents only) Indicates whether the incumbent is running again. Possible values are yes and no.

Dropout_Date

(For Presidential candidates only) The date when the candidate drops out of the race or suspends their campaign.

Notes

Any special notes about the candidate, if provided.

Examples

Example: U.S. House Candidate Report

This XML example shows a partial 2024 U.S. House Candidate report.