Elections Response

XML Element

JSON Property

Description

Vote

@ApiVersion

"apiVersion"

The API version number; for example, 3.1.

@ApiBuild

"apiBuild"

The API build number; for example, 3.1.104.

@ElectionDate

"electionDate"

Date of the election day.

@Timestamp

"timestamp"

Timestamp when the file was created on the AP Elections system.

@IsTruncated

"isTruncated"

This field is returned only when you follow the next request link, and your request includes the minDateTime parameter. Possible values are:

• false. All available results are returned.

• true. More data is available. Repeat the request immediately using the next request link returned in the response to get the remaining results, and then continue repeating this step until isTruncated=false is returned.

Race

"races"

@EventID

"eventID"

The ID of an election event. An election event includes nominating event(s) and/or election(s) occurring in a state on a common date that share a similar set of tabulation characteristics, mainly reporting units and poll close time. An event may include a primary, general election, special election and/or and runoff. Special elections are only included if tabulated. In presidential years, events also include 1st tier caucus and party-run events for states and U.S. territories. In midterm years, events include all tabulated elections. In odd years, events include statewide elections, major municipal dates, special federal and legislative elections. A state may have two separate events on the same date, for example, in presidential years when state party-run nominating events may occur at different times with a different set of reporting units.

@StateID

"stateID"

AP-assigned state numbers. For more information, see State ID Values.

@ResultsType

"resultsType"

Indicates whether the elections data is test, live or certified:

• In XML: "t" (test), "l" (live) or "c" (certified)

• In JSON: "test", "live" or "certified"

@Test

(deprecated)

"test"

(deprecated)

Indicates whether the elections data is test or live:

• In XML: Test="1" (test data); Test="0" (live data)

• In JSON: "test": true (test data); "test": false (live data)

@ID

"raceID"

Unique race ID for a specific state.

@Type

"raceType"

Character string indicating the basic race type (for example, General, Primary). For more information, see Race Type IDs.

@TypeID

"raceTypeID"

Race type ID (up to three characters); for example, D (Dem Primary), R (GOP Primary), G (General), E (Dem Caucus), S (GOP Caucus), APP (All-Party Primary), CON (Conservative Party Primary), WF (Working Families Party Primary). For a full list of values, see Race Type IDs.

@TabulationStatus

"tabulationStatus"

AP Vote Tabulation Status; for example, "Active Tabulation." For more information, see Tabulation Status.

@RaceCallStatus

"raceCallStatus"

(When available) The Called Status (for any race; for example, "Called") or the AP Decision Status (for National Races only; for example, "Too Close to Call"). If the Called Status becomes available for a national race, it replaces the AP Decision Status. For more information, see Race Call Status.

@PartyRaceCall

"partyRaceCall"

For races where all candidates are from the same party, indicates that the race will be called for the party they belong to; for example, Dem.

@OfficeID

"officeID"

Office type ID (up to three characters); for example: P (President), S (U.S. Senate), H (U.S. House), G (Governor), I (ballot measures), SS (Secretary of State), SBE (State Board of Education). For a full list of values, see Office Type IDs.

@SuppOfficeID

"suppOfficeID"

(For ballot measures only) A supplemental three-letter office type ID starting with "I"; for example, IAM (Amendment). For a full list of values, see Supplemental Office Type IDs for Ballot Measures.

@OfficeName

"officeName"

Name of the office type (for example, President, U.S. House) or ballot measure type (for example, Amendment, Proposition). For more information, see Office Type IDs.

@SeatName

"seatName"

The name of the jurisdiction (such as district) or ballot measure; for example: District 25, 1 - Raise General Reserve Fund. Typically not applicable to statewide races.

@SeatNum

"seatNum"

The number of the jurisdiction (such as district). Typically not applicable to statewide races. For more information, see Seat Numbers for Nonstandard State Legislature Districts.

@FlippedSeat

"flippedSeat"

For President, U.S. Senate, U.S. House and Governor races, indicates whether the race winner flipped the seat by beating an incumbent from an opposing political party; for example, a Democrat flipped a Senate seat by beating an incumbent Republican.

• In XML: FlippedSeat="1" (flipped); FlippedSeat="0" (not flipped)

• In JSON: "flippedSeat": true (flipped); "flippedSeat": false (not flipped)

@Position

"position"

An alphanumeric position (for example, "1" or "A") used in addition to the district number in some states, such as Washington and Idaho. For more information, see State Legislature Districts with Position.

@Designation

"designation"

The state's numeric or alphanumeric identifier of a ballot measure (for example, "1" or "2A").

@Desc

"description"

Description of the office, ballot measure or other (if applicable).

@Category

"category"

The topic of the ballot measure assigned by the AP News Department. Possible values are Abortion, Courts and Justice, Drug Policy, Education, Gambling, Guns, Healthcare, Infrastructure, Labor, Other, Religion, Voting and Elections.

@Summary

"summary"

A concise description of the national ballot measure (200–300 words) created by the AP News Department.

@Party

"party"

Party code (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. For more information, see Party Codes.

@EEVP

"eevp"

Estimated Expected Vote Percentage.

@WinThreshold

"winThreshold"

The required percentage of votes a candidate must have to be declared a winner by the election authority (for example, state).

• For Ranked Choice Voting (RCV) races: If this field is not present, the candidate with the highest vote total can win.

• For ballot measures: The percentage of ballot measure votes necessary to approve the measure; if this field is not present, the threshold is 50%.

@RankedChoice

"rankedChoice"

Indicates that the race could proceed to Ranked Choice Voting (RCV). This field is not returned for races where RCV is not an option.

• In XML: RankedChoice="1"

• In JSON: "rankedChoice": true

@National

"national"

Indicates that the race is national:

• In XML: National="1"

• In JSON: "national": true

@State

"state"

Indicates that the race is statewide:

• In XML: State="1"

• In JSON: "state": true

@KeyRace

"keyRace"

Indicates that the race is a key race:

• In XML: KeyRace="true"

• In JSON: "keyRace": true

@Uncontested

"uncontested"

Indicates that the race is uncontested:

• In XML: Uncontested="1"

• In JSON: "uncontested": true

@NumWinners

"numWinners"

The maximum number of allowed winners (returned only if there is more than one).

@NumRunoff

"numRunoff"

The maximum number of candidates in a runoff race.

Incumbents

Candidate

"incumbents"

The incumbents for the President, Governor and U.S. Senate office types (office type IDs P, G and S).

@First

"first"            

Incumbent's first name.

@Last

"last"

Incumbent's last name.

@Party

"party"

The code of incumbent's party affiliation (for example, Dem, GOP). For more information, see Party Codes.

@CaucusWith

"caucusWith"

Indicates that the incumbent caucuses with Democrats or Republicans. Possible values are Dem and GOP.

@PolID

"polID"

Unique National Politician ID (NPID) across all states and races.

@PolNum

"polNum"

(Prior to 11/18/23) AP-assigned unique ID for this candidate in a specific state, regardless of race candidacy. Starting from 11/18/2023, this value is the same as the National Politician ID value.

@CandidateID

"candidateID"

(Prior to 11/18/23) AP-assigned unique ID for this candidate in a state's race. If a candidate was running in multiple races, this candidate had a different @CandidateID (or "candidateID") in each race. Starting from 11/18/2023, this value is the same as the National Politician ID value.

ReportingUnit

"reportingUnits"

@StatePostal

"statePostal"

Two-character state postal code.

@Name

"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).

"reportingunitName"

@ReportingUnitLevel

"reportingunitLevel"

A numerical indicator of the results level. Possible values are:

• 1. State-level results.

• 2. Results at the subunit (RU or FIPS) or district level.

• 3 or 4. May be used in special cases when a further breakout of results is available.

@ID

"reportingunitID"

Reporting unit ID or district ID for level=district (for example, AZ-CD-3 for Arizona Congressional District 3).

@Level

"level"

Region the vote results are reported from:

• national for presidential results and electoral count at the U.S. national rolled-up summary level (only for the general election in a presidential year)

• state for state-level results

• subunit for results at the RU or FIPS code level

• district for delegate results at the district level from the presidential primaries

@EEVP

"eevp"

Estimated Expected Vote Percentage for the race within the reporting unit.

@ElectTotal

"electTotal"

The state or U.S. national electoral count (only for presidential races in a general election in a presidential year).

@FipsCode

"fipsCode"

County FIPS code. For more information about FIPS codes, see American National Standards Institute (ANSI) Codes for States.

@TownFIPSCode

"townFIPSCode"

The New England township FIPS code.

@DistrictType

"districtType"

District type; for example, CD for Congressional District, AtLarge for At-Large (awarded based on statewide presidential vote), PLEO for Party Leaders and Elected Officials (awarded based on statewide presidential vote; for Dem only).

@LastUpdated

"lastUpdated"

Date and time when the results for this reporting unit were last updated.

@PollClosingTime

"pollClosingTime"

The time when the first polling location in this reporting unit closes.

Precincts   

@Reporting

"precinctsReporting"

The number of precincts reporting.

@Total

"precinctsTotal"

The total number of precincts.

@ReportingPct

"precinctsReportingPct"

The percentage of precincts reporting.

Candidate

"candidates"

@ID

"candidateID"

(Prior to 11/18/23) AP-assigned unique ID for this candidate in a state's race. If a candidate was running in multiple races, this candidate had a different Candidate/@ID (or "candidateID") in each race. Starting from 11/18/2023, this value is the same as the National Politician ID value.

@Party

"party"

Party affiliation code for a specific candidate (for example, Dem, GOP, Lib). For more information, see Party Codes.

@CaucusWith

"caucusWith"

Indicates that the candidate caucuses with Democrats or Republicans. Possible values are Dem and GOP.

@Incumbent

"incumbent"

Indicates that the candidate is an incumbent:

• In XML: Incumbent="1"

• In JSON: "incumbent": true

@First

"first"            

Candidate's first name.

@Middle

"middle"

Candidate's middle name.

@Last

"last"

Candidate's last name.

@Abbrv

"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.

@JR

"suffix"

Candidate's suffix.

@PolID

"polID"

Unique National Politician ID (NPID) across all states and races; available for ALL politicians. Prior to 11/18/23, NPIDs were only available for politicians who ran in a national race; for local politicians, this value was set to "0".

@BallotOrder

"ballotOrder"

Ballot order of this candidate. There may be gaps in sequence in this order field.

@PolNum

"polNum"

(Prior to 11/18/23) AP-assigned unique ID for this candidate in a specific state, regardless of race candidacy. Starting from 11/18/2023, this value is the same as the National Politician ID value.

@VoteCount

"voteCount"

Current number of votes for this candidate.

@AVotes

"avotes"

The A-report votes for this candidate as provided by the state, if requested and available.

@DelegateCount

"delegateCount"

Delegates won by this candidate in this state or in this district (for delegate results for presidential primaries, when level=district is specified in the request). For presidential races (officeID=P), the delegateCount is returned at the state level only when level=state, level=fipscode or level=ru is specified in the request.

@ElectWon

"electWon"

The candidate’s electoral votes (only for presidential races in a general election in a presidential year).

@ElectionDayInPerson

"electionDayInPerson"

Election Day In-Person votes for this candidate, if available and if vote by type was requested.

@Provisional

"provisional"

Provisional votes for this candidate, if available and if vote by type was requested.

@AdvanceTotal

"advanceTotal"

Advance vote total (votes cast prior to Election Day) for this candidate, if available and if vote by type was requested.

@EarlyInPerson

"earlyInPerson"

Early In-Person votes for this candidate, if applicable and if vote by type was requested.

@AbsenteeTotal

"absenteeTotal"

Absentee vote total for this candidate, if available and if vote by type was requested.

@AbsenteeInPerson

"absenteeInPerson"

Absentee In-Person votes for this candidate, if applicable and if vote by type was requested.

@AbsenteeMail

"absenteeMail"

Absentee Mail ballot votes for this candidate, if available and if vote by type was requested.

@InPersonTotal

"inPersonTotal"

Votes cast in person for this candidate, if applicable and if vote by type was requested. This category will be used primarily when a state merges results for Election Day In-Person and Early In-Person, and no further breakdown is available.

@AdvanceInPersonTotal

"advanceInPersonTotal"

Votes cast in person (not by mail) for this candidate prior to Election Day, which may include Early In-Person and/or Absentee In-Person votes, or populated when a further breakdown is not available. Currently, no states apply to this category.

@Winner

"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)

@WinnerDateTime

"winnerDateTime"

The date and time when the winner was declared.

@InfoUpdated

"infoUpdated"

Indicates that the candidate information has been updated:

• In XML: InfoUpdated="1"

• In JSON: "infoUpdated": true

RankedChoiceVotingRounds

For each candidate, contains the results of ranked choice voting (RCV) and appears only when ranked choice results are made available by the state, if applicable. The "voteCount" field in JSON ("VoteCount" in XML) contains the first-choice votes for each candidate. The AP starts receiving these on election night, same as for non-RCV races. 

RankedChoiceVotingRound

"rankedChoiceVoting"

@Eliminated

"eliminated"

Indicates if the candidate was eliminated during ranked choice processing:

• In XML: Eliminated="1"

• In JSON: "eliminated": true

@Votes

"votes"

Contains the number of votes allocated to the candidate AFTER the last round of ranked choice processing. 

• If "eliminated": true in JSON (Eliminated="1" in XML), this value may be 0.

• If "eliminated": false in JSON (Eliminated="0" in XML), this value indicates the number of votes allocated to the candidate when the other candidates were eliminated.

link

"nextrequest"

Indicates a link for the next request that must be used to request data newer than the data in the previously returned response.

@rel="next"

@href

The specific URL for the next request.

Header

Description

AP_SIGNATURE_SHA256

If includesignature=sha256 or includesignature=eddsa was specified in the request, contains the digital signature. For more information, see Requesting Digital Signatures.

AP_SIGNATURE_EDDSA