What's New in Elections API v3

Certified Results for 2020 GE and Prior

Any Elections API calls requesting certified results for 2020 GE and prior must be directed to v2.

Requests to v3 for certified results for GE 2020 and prior will return an empty response because v3 has only Live data and will NOT be updated with the certified results until after 2024 GE.

Presidential Results and Electoral Counts

Electoral Votes

2020 GE and Prior

For a candidate's electoral votes, Elections API returned "electWon": 0 in JSON and  ElectWon="0" in XML for all candidates before a race call and for the non-winning candidates after the race call.

Effective 2024 GE

A candidate’s electoral vote count (electWon in JSON, ElectWon in XML) is returned only for one or more electoral votes won by a candidate; "electWon": 0 in JSON (ElectWon="0" in XML) is NOT returned before or after a race call.

Presidential Results and Electoral Counts by District

Maine and Nebraska award presidential electoral votes using a district-based method instead of the "Winner-Take-All" method used by the other states. Maine awards two electoral votes based on the statewide vote, and one vote for each congressional district. Nebraska awards two electoral votes based on the statewide vote, and one vote for each of the three congressional districts.

2020 GE and Prior

• Elections request. The level=district parameter in the Elections request was used to receive presidential results and electoral votes by district in Maine and Nebraska, for example:

https://api.ap.org/v2/elections/2012-11-06?statepostal=ME&level=district

• Elections response. Presidential popular votes and electoral counts by district were returned as one statewide presidential race with a number of district-level RUs (for more information, see the Maine example, which shows test data for illustration purposes only).

Effective 2024 GE

• Elections request. You no longer need to specify the level=district parameter to receive the presidential results and electoral counts by district in Maine and Nebraska. These results are now returned by default (level=state), or when you specify level=ru or level=fipscode in the request, for example:

https://api.ap.org/v3/elections/2024-11-05?statepostal=ME&officeID=P

• Elections response. The presidential results and electoral counts by district are returned in races separate from the statewide presidential race. For example, three separate presidential races are returned in Maine:

1. The statewide race where two electoral votes (ElectTotal="2") are allocated based on the statewide presidential popular vote.

2. The District 1 race where one electoral vote (ElectTotal="1") is awarded in CD1 (SeatName="District 1")

3. The District 2 race where one electoral vote (ElectTotal="1") is awarded in CD2 (SeatName="District 2")

API Security Requirements

Field Value Updates

For information about the updates to Office Type IDs, Race Type IDs, ballot measures, Seat Numbers, Politician IDs and Connecticut FIPS Codes, see Field Value Updates.

AP VoteCast Data

AP VoteCast result files for live elections and test events are now available to AP VoteCast subscribers via Elections API. For more information, see AP VoteCast.

New Elections Response Fields

The Elections API method now delivers the following response fields where applicable.

Race Details

Flipped Seat

For President, U.S. Senate, U.S. House and Governor races, the new flippedSeat field in JSON (FlippedSeat in XML) 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)

Party Race Call

For races where all candidates are from the same party, the new partyRaceCall field in JSON (PartyRaceCall in XML) indicates that the race will be called for the party they belong to; for example, "partyRaceCall": "Dem".

Ballot Measure Details

Category

The new category field in JSON (Category in XML) indicates the topic of the ballot measure, as 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

The new summary field in JSON (Summary in XML) delivers a concise description of the national ballot measure (200–300 words) created by the AP News Department.

Threshold

The winThreshold field in JSON (WinThreshold in XML) returns the percentage of ballot measure votes necessary to approve the measure. If this field is not present, the threshold is 50%.

Example

New England Reporting Unit Details

Township FIPS Code

For New England states, the new townFIPSCode field in JSON (TownFIPSCode in XML) indicates the township FIPS code of a reporting unit.

Candidate and Incumbent Details

Caucus With

The new caucusWith field in JSON (CaucusWith in XML), which is available for a very limited number of active candidates, indicates that the candidate or incumbent caucuses with Democrats or Republicans. Possible values are Dem and GOP.

Election Report Upgrades

Trend Reports

Addition of "Caucus with" to the U.S. Senate and U.S. House National Trend Reports

Effective 2024 GE, the reports that show the national party breakdown specify third-party and independent candidates that caucus with Democrats or Republicans, where that information is available. The format of the report remains the same as in 2022 and years prior, with the addition of the "caucus with" sections along with the previously existing "Dem", "GOP" and "Others" sections. The "Others" section continues to track all third-party and independent candidates who are NOT listed in the "caucus with" sections as holdovers, leaders and winners. For information about the data elements, see Party Balance of Power/Trend Reports.

Example: 2024 U.S. Senate National Trend Report

New State-by-State Trend Report for U.S. House

The new U.S. House state-by-state trend report is in the format similar to the existing U.S. House national trend report, but tracks the changes to the U.S. House seats at the state level.

Permalinks for Election Reports

The latest version of each election report in v3 is always available at the same URL. In v2, there are different direct links to each version of the report, so you have to request a specific URL to the latest version of an election report, and then access that URL.

In v3, once you have requested the list of reports and accessed the URL for a specific report for the first time, you can keep checking that URL for newer versions of the report. For example, you can now access the latest version of the 2020-08-11 Cumulative Delegates Report ("DelSum") from the live election at this URL:

https://api.ap.org/v3/reports/Delegates-delsum-20200811-US-Live

Report Filters

Filtering by Subtype

In v3, you can filter reports by subtype only, without specifying the type of the report in the request. For example, if you are interested only in the Cumulative Delegate Report ("DelSum"), you can now specify subtype=delsum, but not type=Delegates:

https://api.ap.org/v3/reports?format=json&subtype=delsum  

Filtering by Geo Code

You can now use the statePostal parameter to filter reports by the geo code, such as a two-character state postal code or "US" for national reports ("US" is the only valid value for delegate, presidential and trends reports). Multiple values must be separated by commas; for example:

https://api.ap.org/v3/reports?statePostal=VT,US

Streamlined List of Reports

The data returned in the report list in the Election Reports response in v3 is the same as in v2; however, the format of the report list has changed in both XML and JSON. For details, see Election Reports Response.

JSON Example

XML Example

New Reports

Primary Runoff and Majority Vote Rules Report

The Primary Runoff and Majority Vote Rules report tracks state-by-state rules regarding minimum vote requirements related to runoffs, ranked choice voting, etc., where applicable. For more information, see Primary Runoff and Majority Vote Rules Report.

Voter Registration Requirements

The Voter Registration Requirements report tracks state-by-state voter registration requirements for primaries and presidential nominating events. Current registration numbers by state are provided where available. For more information, see Voter Registration Requirements Report.

Write-In Rules Report

The Write-In Rules report confirms state-by-state rules, where applicable, for submitting a vote for a write-in candidate. For more information, see Write-in Rules Report.

Recount Rules Report

The Recount Rules report confirms rules for mandatory and non-mandatory recounts state-by-state. For more information, see Recount Rules Report.

Deadlines and Milestones Report

The Deadlines and Milestones report captures deadlines and milestones for each state throughout the year. This report encompasses important dates for voters, candidate filings and county canvasses. For more information, see Deadlines and Milestones Report.

Delegate Breakout Report

The Delegate Breakout report shows the AP-estimated Democratic and Republican delegate totals by state and type. For more information, see Delegate Breakout Report.

Political Party Report

The Political Party report lists the codes and names for political parties that have been active from 2020 to present. For more information, see Political Party Report.

Poll Hours Report

The Poll Hours report lists poll hours in each state, in local time and Eastern Time (ET). For more information, see Poll Hours Report.

Available Vote Types Report

Not all vote types are available in any particular state or RU. The available data may also change from one election date to another depending on the rules and regulations for a particular election. The "Available Vote Types" report (also known as "What's Available Where" report) provides state-by-state availability of each vote type for each election date starting from March 1, 2022. For more information, see Available Vote Types Report.

Updated Reports

Candidate Reports

• The removed fields are gender, incumbentLastElectionPercentage and tabulatedByAP.

• The format of the field names in the Candidate Reports has changed slightly. For more information, see the updated list of data elements in Candidate Reports.

• In a previous release, a new field, dropoutDate (now called Dropout_Date) was added to the U.S. presidential candidate report to capture the date when the candidate drops out of the race or suspends their campaign.

National Presidential Delegate Tracking Reports

New fields in the National Presidential Delegate Tracking Reports and the Delegates API method response (in both XML and JSON) include:

• dropoutDate. The date when the candidate drops out of the race or suspends their campaign.

• presumptiveNominee="X" is assigned to one Democratic candidate and one GOP candidate when enough delegates have been allocated to them according to party rules based on presidential nominating events.

• conventionWinner="X" is assigned to one Democratic candidate after being elected during the Democratic National Convention and one GOP candidate after being elected during the Republican National Convention. This may or may not be the same as the presumptiveNominee.

Election Calendar Report

New fields in the Election Calendar report include:

• statePostal. The state postal code (for example, IA).

• presPrimary. Indicates that the event includes a presidential nominating event. Possible values are "Dem", "GOP" and "Dem, GOP".

• delegateEvent. Indicates that the event includes delegate allocation for presidential candidates. Possible values are "Dem", "GOP" and "Dem, GOP". In most cases, the value of this field will match the presPrimary field value; however, some states have additional events where some or all delegates are allocated on a separate day than the presidential primary (usually through a state convention).

• govOrSenIncl. Indicates that the primary event includes a race for Governor and/or U.S. Senate. Possible values are "Gov", "Sen" and "Gov, Sen".

For more information, see Election Calendar Report.

Availability of New v3 Features in v2

With the exception of the Delegates methods, the new v3 features described below in these Release Notes are also available in v2 starting from the 03-01-2022 election date. If you are planning to get election data for 03-01-2022 and future election dates, you do not need to change v2 to v3 in the request URL.

New API Methods

Delegates

For presidential primaries, the new Delegates API method returns the delegate allocation data of a specific type for Democrats, Republicans or both. The types represent the National Presidential Delegate Tracking Reports, and the returned data elements are the same as in those reports. However, the reports reflect the delegate allocation as of a specific date (for example, two days after Super Tuesday) while the Delegates method returns the delegate allocation at the time of request. For more information, see Delegates.

Delegates - DNC 2024

Following the announcement of President Joe Biden’s decision to exit the race for President, the Elections API tracked the updated delegate allocation for a new presidential nominee. All rounds of voting during the delegate selection process were captured.

For more information, see Delegates - DNC 2024.

Advance Turnout

For presidential and midterm general elections, you can use the new Advance Turnout API method to request state-by-state data on advance voting, including how many absentee ballots have been requested, sent and returned, demographic data and in-person voting data. Also included is a comparison to the historical data, such as 2020 presidential primaries, 2018 midterm general election and 2016 general election.

Try it out:

https://api.ap.org/v3/elections/2020-11-03/advance?statepostal=nc&format=json

To learn more, see Advance Turnout.

Ranked Choice Voting (RCV) Races

Updated RCV Race Structure

Previously, there were two race IDs for a ranked choice race, one to capture first-choice preference results and a separate one to capture final results. Starting in 2023, races with ranked choice results will be consolidated into one race ID, which will include both first choice results and final results made available after ranked choice processing.

Retired RCV Race Type IDs

The Race Type IDs previously used for RCV ('V' for general elections, 'Y' for DEM primaries, and 'Z' for GOP primaries) will no longer be used to specify ranked choice voting moving forward.

New Elections Response Fields

Race Details

• If a race could proceed to ranked choice voting, it is indicated by "rankedChoice": true in JSON and RankedChoice="1" in XML. This field is not returned for races where RCV is not an option.

• The new "winThreshold" field in JSON ("WinThreshold" in XML), which may also be returned for non-RCV races, indicates the required percentage of votes a candidate must have to be declared a winner by the election authority (for example, state). If this field is not present, the candidate with the highest vote total can win.

Candidate Details

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

• For each candidate, the new "rankedChoiceVoting" array in JSON (the "RankedChoiceVotingRounds" element in XML) appears only when ranked choice results are made available by the state, if applicable.

"rankedChoiceVoting" in JSON ("RankedChoiceVotingRounds/RankedChoiceVotingRound" in XML) includes the following properties/attributes:

• "eliminated": true or "eliminated": false in JSON (Eliminated="1" or Eliminated="0" in XML) indicates if the candidate was eliminated during ranked choice processing.

• "votes" in JSON ("Votes" in XML) 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.

JSON Example

XML Example

Elections Request

Filtering Races by Reporting Unit ID

In the Elections request, you can now select the races using one or more reporting unit IDs within a state to return only races within those reporting units. You can also specify one or more race IDs in that single state in the same request.

For example, the following request returns election data in the JSON format for the specified race IDs 7162 (U.S. Senate GOP Primary) and 6489 (Governor GOP Primary) in the specified reporting units 6001 (Adams) and 6002 (Alamoso) in Colorado from the 6-28-2022 election:

https://api.ap.org/v3/elections/2022-06-28?statePostal=CO&raceID=7162,6489&reportingUnitID=6001,6002&format=json

Vote Types

The new votetypes=true parameter in the Elections request allows you to receive votes by type for each candidate if available. Examples include Election Day In-Person, Early In-Person and Mail Absentee votes.

Try it out:

https://api.ap.org/v3/elections/2021-11-02?statepostal=VA&votetypes=true&format=json

To learn more, see Vote Types.

Automatic Switch From Live to Certified Results

The new resultsType=b option in the Elections request allows you to receive live data during vote tabulation and switch to certified data as it becomes available without having to change from resultsType=l to resultsType=c to get certified results. Since not all races in a state might be certified at the same time, the response may potentially include a mix of live and certified results (as they become available) when you specify resultsType=b parameter in the request. Use the existing resultsType field in the response to determine whether a race has been certified.

Elections Response

Truncated Responses

When you make a request with the minDateTime parameter by following the next request link, and all available results are returned, isTruncated=false appears at the top of the response.

If you receive isTruncated=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.

JSON example   

XML Example

Delegate Count for Presidential Primaries

For presidential races (officeID=P), delegates won by each candidate (delegateCount in JSON and delegateCount in XML) is now returned at the state level only when level=state, level=fipscode or level=ru is specified in the request.

JSON Example

XML Example

AP Vote Tabulation Status

The Elections API now returns the AP vote tabulation status for every race in the Elections response (tabulationStatus in JSON and TabulationStatus in XML).

Available Vote Tabulation Statuses

JSON Example

XML Example

Race Call Status

When available, the Elections response now includes the race call status (raceCallStatus in JSON and RaceCallStatus in XML). This may be the Called Status (for any race) or the AP Decision Status (for National Races only). If the Called Status becomes available for a national race, it replaces the AP Decision Status.

Called Status

The status of the actual race call:

AP Decision Status

For National Races, the AP Decision status provides you with additional insight about when to expect a race call, if at all. If the Called Status becomes available for a national race, it replaces the AP Decision Status.

JSON Example

XML Example

Incumbents with Parties

For the President, Governor and U.S. Senate office types (office type IDs P, G and S), the incumbents are now returned at the race level in the Elections response, including each incumbent's IDs and party (see Response Examples). The existing labeling of the individual incumbent candidates ("incumbent": true in JSON and Incumbent="1" in XML) remains unchanged for all office types.

Who is Considered an Incumbent?

An incumbent is a current holder of an elected office. During an election, a candidate is labeled as an incumbent if they are seeking re-election to their current legislative body or public office. For example, a current member of the U.S. House of Representatives seeking any seat in the U.S. House will be labeled as an incumbent; a current member of the U.S. House of Representatives seeking election to the U.S. Senate will NOT be labeled as an incumbent.

Incumbents may seek re-election in a district with different boundaries and district names than in the preceding election. This happens most often as a result of redistricting. For example, a U.S. House member currently representing a state's 1st Congressional District seeking re-election to the U.S. House in the state's newly created 2nd Congressional District is still an incumbent. This means that it is possible for a race to feature two or more incumbents.

JSON Example

XML Example

Statewide Race Indicator

Statewide races are voted on by the entire state, and therefore by every RU, and therefore by every precinct; for example, President, Governor, U.S. Senate, Statewide Ballot Measures, Lieutenant Governor, Secretary of State, Attorney General, statewide judicial races.

For each statewide race, the statewide race indicator ("state": true in JSON and State="1" in XML) is now returned in the Elections response. When a race is not a statewide race, this field will not be present (the API does not return State="0").

JSON Example

XML Example

Key Race Indicator

Key races are any Top-of-the-Ticket (TTT) or downballot races deemed editorially important by the AP plus key ballot measures.

For each race that has been designated as a key race by the AP, the key race indicator ("keyRace": true in JSON and KeyRace="True" in XML) is now returned in the Elections response. When a race is not a key race, this field will not be present (the API does not return KeyRace="False").

JSON Example

XML Example

Reporting Unit Level Indicator

A numerical indicator of the results level (reportingUnitLevel in JSON and ReportingUnitLevel in XML) is now returned for each reporting unit in the Elections response. 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.

JSON Example

XML Example

Estimated Expected Vote Percentage (EEVP)

EEVP is now also returned for a race within each reporting unit (RU). In the previous versions of the Elections API, EEVP was applicable only to the Federal -- President and U.S Senate -- and Governor statewide races during the primaries and general election. The EEVP value for a race within an RU is calculated as the total votes tabulated for the race within the reporting unit, divided by an AP internally assigned "estimated expected total votes" parameter for the specific race. The "estimated expected total votes" is determined by AP’s proprietary research, knowledge, and expertise.

The EEVP will vary over the course of the election night tabulation, based on the incoming total votes at any given time for the race, and will represent the percentage of the total votes that AP estimates will eventually be certified. The EEVP is an optional value that may be used in addition to (or instead of) the ReportingPct value to determine the progress of the election on election night. The maximum value for EEVP during tabulation is 99%, which indicates AP estimates that almost all ballots cast have been counted. The EEVP value will not be set to 100% until election officials complete the certification process and declare the election results as final and official.

JSON Example

XML Example

Winner Datetime

The date and time when the winner was declared is now returned in the winnnerDateTime field in JSON and in the WinnerDateTime field in XML.

JSON Example

XML Example

Event ID and State ID

 The ID of an election event and an AP-assigned state ID are now returned in the Elections response.

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.

JSON Example

XML Example

Public Keys

If you are using SHA-256 or EdDSA verification, two new public keys are now required:

• To validate the SHA-256 signature, use this AP public key: 13c816496f281e01198ca3afe052326be11e8d34dd8200fcd537f45a2e414a08

• To validate the EdDSA signature, use this AP public key: BQP15zpzZ7zATz20V+C/NZhWY9GSlrbIGMC2inm7gK8=