What's New in Elections API v3

 

ON THIS PAGE      Show

 

 

 

 

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

 

Important

 

You must review the changes in the following sections and adjust your implementation accordingly:

 

 

 

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

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

 

Effective 2024 GE

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

API Security Requirements

 

Important

 

All API requests must use HTTPS and supply the API key in the HTTP request header for secure encrypted transmission. For more information, see 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.

 

AP VoteCast data for past election dates is available to all Elections API customers. If you are interested in subscribing to AP VoteCast to receive VoteCast data for live elections, please contact your AP Sales representative.

 

 

 

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.

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

 

Important

 

  • Election Report upgrades are applicable only to v3.

  • All election reports that were previously available in v2 are now also available in v3. New reports and updates to existing reports will be available in v3 only.

  • The Election Reports implementation in v2 has not changed, but it has been deprecated and will be removed in a future release.

  • If you are using Election Reports in v2, we strongly urge you to make changes to your client application and switch to v3.

 

 

 

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

 

  Important

 

The geo parameter is deprecated and will be removed in a future release. To filter reports by the geo code, use the statePostal parameter instead.

 

 

 

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.

 

  Important

 

Make sure to review the changes and adjust your API implementation accordingly.

 

 

 

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

  Important

 

The latest updates of the Candidate Reports include removed fields and slight changes to the format of the field names. Review your implementation for any dependencies and make changes if necessary.

 

 

 

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:

Election Calendar Report

New fields in the Election Calendar report include:

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.

 

  Note

 

Existing data feeds tracking the results of the Democratic Party’s 2024 primary elections and initial delegate allocations did not change. They continued to show the results of the completed Democratic presidential primary elections and nominating events.

 

 

 

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.

 

  Note

 

The "Advance Turnout So Far" report, which has been replaced by the Advance Turnout API method, is not provided for the 2022 General Election.

 

 

 

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
Candidate Details

 

 

 Notes

 

 

  • Since election authorities release the vote counts for candidates at the state level, only the state-level reporting unit contains "rankedChoiceVoting" in JSON ("RankedChoiceVotingRounds" in XML) for each candidate.

  • At this time, the AP plans to put only a single entry in this array in JSON (a single "RankedChoiceVotingRounds/RankedChoiceVotingRound" element in XML) for the final vote counts for each candidate at the end of the ranked choice process.

 

 

 

 


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

 

  Note

 

For each candidate, "voteCount" in JSON ("VoteCount" in XML) always has the first-choice votes. The "votes" field in the "rankedChoiceVoting" array in JSON (the "Votes" attribute of the "RankedChoiceVotingRounds/RankedChoiceVotingRound" element in XML) has the updated vote count based on ranked choice processing.

 

 

 

JSON Example
           {
            "eventID": "ME-20221108_Eday80",
            "stateID": 20,
            "test": false,
            "resultsType": "live",
            "raceID": "20645",
            "raceType": "General",
            "raceTypeID": "G",
            "tabulationStatus": "End of AP Tabulation",
            "raceCallStatus": "Too Early to Call",
            "officeID": "H",
            "officeName": "U.S. House",
            "description": "North",
            "eevp": 99.51,
            "winThreshold": 50,
            "national": true,
            "rankedChoice": true,
            "seatName": "District 2",
            "seatNum": "2",
            "reportingUnits": [
                {
                    "statePostal": "ME",
                    "stateName": "Maine",
                    "reportingunitID": "20",
                    "reportingunitLevel": 1,
                    "pollClosingTime": "2022-11-09T01:00:00.000Z",
                    "level": "state",
                    "lastUpdated": "2022-12-10T05:41:54.405Z",
                    "precinctsReporting": 421,
                    "eevp": 99.51,
                    "precinctsTotal": 421,
                    "precinctsReportingPct": 100,
                    "candidates": [
                        {
                            "first": "Jared",
                            "last": "Golden",
                            "incumbent": true,
                            "party": "Dem",
                            "candidateID": "29918",
                            "ballotOrder": 2,
                            "polID": "66383",
                            "polNum": "25384",
                            "voteCount": 151570,
                            "rankedChoiceVoting": [
                                {
                                    "eliminated": false,
                                    "votes": 165136
                                }
                            ]
                        },
                        {
                            "first": "Bruce",
                            "last": "Poliquin",
                            "party": "GOP",
                            "candidateID": "31053",
                            "ballotOrder": 3,
                            "polID": "60410",
                            "polNum": "24987",
                            "voteCount": 141119,
                            "rankedChoiceVoting": [
                                {
                                    "eliminated": false,
                                    "votes": 146142
                                }
                            ]
                        },
                        {
                            "first": "Tiffany",
                            "last": "Bond",
                            "party": "Ind",
                            "candidateID": "31450",
                            "ballotOrder": 1,
                            "polID": "67787",
                            "polNum": "25972",
                            "voteCount": 21565,
                            "rankedChoiceVoting": [
                                {
                                    "eliminated": true,
                                    "votes": 0
                                }
                            ]
                        }
                    ]
                },
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

 

Parameter

Description

reportingUnitID

The ID of a reporting unit (RU); for example, a city/town in New England states or a county in other states. Since reporting unit IDs are guaranteed to be unique only within a state, you must use this parameter in conjunction with the statePostal parameter. Multiple values must be for the same state and must be separated by commas. This parameter may be used in conjunction with the raceID parameter.

raceID

AP-assigned race ID. Since race IDs are guaranteed to be unique only within a state, you must use this parameter in conjunction with the statePostal parameter. Multiple values must be for the same state and must be separated by commas. This parameter may be used in conjunction with the reportingUnitID parameter.

statePostal

Two-character state postal code.

  Important

 

When used in conjunction with the reportingUnitID and/or raceID parameter(s), the statePostal parameter is required, and multiple values are not allowed.

 

 

 

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.

 

  Note

 

Not all data is available in any particular state or RU. The available data may change for future election dates depending on the rules and regulations for a particular election.

 

 

 

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

Vote Tab Status

Description

Awaiting Poll Close

(The default) No polls have closed in the state yet. At first poll close, the status automatically changes to "Polls Closed/Waiting First Report."

Polls Closed/Waiting First Report

The first polls in the state have closed, but the AP hasn't yet received any vote reports. When the AP receives the first vote report from the state, the status automatically changes to "Active Tabulation."

Active Tabulation

The AP is currently seeking/expecting vote updates in the short term – usually on the current day, in the next few days after the election, or possibly longer; for example, if the state is recounting votes. This status is reported at the state level if at least one RU in the state is set to "Active Tabulation."

Tabulation Paused

Vote tabulation has been paused; for example, while a potentially problematic issue is being investigated. May include the date and time when the tabulation is expected to resume.

End of AP Tabulation

The state and the RUs have reported to the AP; vote counts are not expected to change until the certification of results.

Gathering Certified Results

The AP is gathering the final, official vote totals from the state or county.

Vote Certified

The final, official vote totals have been provided by the state or, in some cases, county. Certified results may be made available to the AP anywhere between a few days to over a month after the election.

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:

 

Called Status

Description

Called

The AP has declared the winner of the race.

  Important

 

If a race has multiple winners, only some may have been called. Make sure to check the number of winners in this race and how many candidates are marked as winners.

 

 

 

Runoff

The race has been called as advancing to runoff.

  Important

 

If a race has multiple winners, only some may have been called. Make sure to check the number of winners in this race and how many candidates are marked as advancing to runoff.

 

 

 

Winner Not Leading

The winner of the race declared by the AP is currently not leading.

Uncalled

Used very rarely when the AP has already called the race and has to rescind the 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.

 

AP Decision Status

Description

Too Early to Call

(The default) Automatically set at poll close.

Too Close to Call

One of the following:

  • The race will proceed or be subject to a recount.

  • Tabulation is largely complete, but there may remain uncounted provisional or late-arriving absentee ballots that could affect the outcome.

Unable to Call

A deficiency in the data at the source renders the vote count unreliable, preventing the AP from conducting an analysis; distinct from "AP Will Not Call" in that it could change; for example, the 2020 Iowa Caucus.

Awaiting Ranked Choice Results

AP assesses no candidate will win outright, and the election will proceed to election officials tabulating ranked choice vote results.

AP Will Not Call

One of the following:

  • AP is tabulating this race, but knows in advance it will not call it, such as third-party primary elections.

  • AP intended to call this race, but for unforeseen reasons decides after polls close that it will not declare a winner.

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:

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.

 

  Note

 

In New England, the EEVP may only be available statewide and countywide, not by town/reporting unit.

 

 

 

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: