Skip to content

Instantly share code, notes, and snippets.

What would you like to do?
AP Election Result Specification

AP Election Result Specification

Taken from

Part of a comparison of election result specifications such as


Field Description
test "Indicates whether the elections data is live or for test purposes only:
  • In XML: Test=""1""(test data);Test=""0""(live data)
  • In JSON: ""test"": true(test data); ""test"": false(live data)"
raceID Unique race ID for a specific state.
raceType Character string indicating the type of race (for example, GOP Primary, General, Democratic Caucus).
raceTypeID Single-character race type ID: D(Dem Primary), R(GOP Primary), G(General), E(Dem Caucus), S(GOP Caucus).
officeID Office type ID, usually a single character; for example: P(President), G(Governor), S(U.S. Senate) and H(U.S. House).
officeName Name of the office, ballot initiative or other race.
description Description of the office, ballot initiative or other (if applicable).
party Party abbreviation (for example, Dem, GOP, Lib). This field is not applicable to a general election race. It is applicable to closed primaries where there is more than one race for the same office; for example, Dem Governor race and GOP Governor race.
seatName The district or ballot initiative name; for example: District 1, 1A-Abortion). Typically not applicable to statewide races.
seatNum The district or ballot initiative number. Typically not applicable to statewide races.
uncontested "Indicates that the race is uncontested:
  • In XML: Uncontested=""1""
  • In JSON: ""uncontested"": true
    • Note: All the uncontested races are called at the same time, at poll close. If a state has two time zones, the uncontested races are called after the second poll close."
national "Indicates that the race is national:
  • In XML:National=""1"
  • In JSON:""national"": true"
numWinners The maximum number of allowed winners (returned only if there is more than one).
numRunoff The maximum number of candidates in a runoff race.
statePostal Two-character state postal code.
stateName Full state name (for example, Delaware, New York), the reporting unit name (city/town name for the New England states and county name for the other states) or the district name (for example, At-Large, District 1, PLEO).
reportingunitID Reporting unit ID or district number (for example, 4for Congressional District 4)
level "Region the vote results are reported from:
  • nationalfor presidential results and electoral count at the U.S. national rolled-up summary level (only for the general election in a presidential year)
  • statefor state-level results
  • subunitfor results at the RU or FIPS code level
  • districtfor delegate results at the district level from the presidential primariesOR presidential results and electoral counts by district (currently, in Maine and Nebraska) for the general election in a presidential year"
electTotal The state or U.S. national electoral count (only for the general election in a presidential year).
fipsCode County FIPS code.
districtType District type; for example, CDfor Congressional District, AtLargefor At-Large (awarded based on statewide presidential vote), PLEOfor Party Leaders and Elected Officials (awarded based on statewide presidential vote; for Dem only).
lastUpdated Date and time when the results for this reporting unit were last updated.
precinctsReporting The number of precincts reporting.
precinctsTotal The total number of precincts.
precinctsReportingPct The percentage of precincts reporting.
candidateID AP-assigned unique ID for this candidate in a state's race. If a candidate is running in multiple races, this candidate has a different Candidate/@ID(or "candidateID") in each race.
party Party affiliation for a specific candidate, abbreviation (for example, Dem, GOP, Lib).
incumbent "Indicates that the candidate is an incumbent:
  • In XML:Incumbent=""1""
  • In JSON:""incumbent"": true"
first Candidate's first name.
middle Candidate's middle name.
last Candidate's last name.
abbrv Candidate's abbreviated name, usually last name with some vowels removed if too long. This attribute is omitted if its value is identical to the candidate's last name.
suffix Candidate's suffix.
polID Unique National Politician ID across all states and races (only for politicians who have run in a national race). For local politicians, this value is set to "0".
ballotOrder Ballot order of this candidate. There may be gaps in sequence in this order field.
polNum AP-assigned unique ID for this candidate in a specific state, regardless of race candidacy.
voteCount Current number of votes for a particular candidate.
delegateCount Delegates won by this candidate in this district (only for delegate results for presidential primaries).
electWon The candidate’s electoral votes (only for the general election in a presidential year).
winner "Single character indicating whether the candidate is a winner:
  • X(the candidate is a winner)
  • R(the candidate is advancing to a runoff)
  • N(the candidate is no longer considered the winner due to a race call reversal)
infoUpdated "Indicates that the candidate information has been updated:
  • In XML:InfoUpdated=""1"
  • In JSON:""infoUpdated"": true"
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment