Election Candidate Reports
|
|
|
|
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
|
|
|
|
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. |
|
|
|
|
NoteThis 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.