Election Reports Request

Required Request Headers
Optional Request Header
Request URI
Required Parameter
Optional Parameters
Request URI Examples

Important

To request election report updates, use the 'next request' links (see Receiving Election Updates). The list of reports returned when you submit a new search request for reports using optional filtering parameters always includes links to the latest available versions of the reports.

In v3, the latest version of each report is always available at the same URL. For more information, see Election Report Upgrades.
In v2, there is a different direct link to each new version of a report. If you are using v2, do not follow stored direct links to reports because these reports may already be outdated. To monitor for new versions of the reports in v2, always submit a new search request using the 'next request' link.

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.

Required Request Headers

Header	Description	Example
x-api-key	Specifies the API key to authorize the request. The x-apikey header is also currently supported.	apikey
Accept-Encoding	Compresses the response to the gzip format.	gzip

Optional Request Header

Header	Description	Example
Accept	The MIME type of the returned data format: XML or JSON. The default is application/xml. The format parameter value takes precedence over the Accept header value when both are specified.	application/json

Request URI

Method	Request URI
GET	https://api.ap.org/{version}/reports?[{OptionalParameters}]

Important
The request URI must be URL-encoded.

Required Parameter

Parameter	Description	Example
version	The API version: v2 or v3.	v3

Optional Parameters

Parameter

Description

Example

resultsType

Indicates whether to return live or test election reports. Possible values are t (test reports) or l (live reports; this is the default).

Important
To receive test reports, make sure to add the optional resultsType=t parameter to the request URL.

test
(deprecated)

Indicates whether to return live or test election reports. Possible values are true (test reports) and false (live reports; this is the default).

Important
This parameter is deprecated and will be removed in a future release. To request test reports, use the resultsType=t parameter instead.

true

electionDate

Date of the election in the YYYY-MM-DD format.

Note

This parameter does not apply to reports generated prior to 2016‑11‑08 (the 2016 Delegate reports are available for historical purposes, but do not have a published date or geo field).

Exception: A special separate set of 2012‑11‑06 election reports was generated.

2020-02-03

statePostal

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.

VT,US

geo
(deprecated)

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

VT,US

format

The response format (xml or json). The format parameter value takes precedence over the Accept header value when both are specified. If no format is specified as the format parameter value or in the Accept header, XML is returned.

json

type

The report type. Multiple values must be separated by commas. Examples of possible values are:

delegates. Returns delegate tracking reports for presidential primaries.
delbreakout. See Delegate Breakout Report.
pres. For the general election in a presidential year, returns presidential popular votes and electoral count at the state and U.S. national rolled-up summary levels.
trend. For the general election, returns national party balance of power/trends for Governors, U.S. Senate and U.S. House. These reports show a party breakdown if the present trends in the vote count continue in the races for Governors, U.S. Senate and U.S. House.
EstimatedVotePercentage. See Estimated Expected Vote Percentage (EEVP) Report.
calendar. See Election Calendar Report, Deadlines and Milestones Report and Customer Testing Schedule.
candidates. See Election Candidate Reports.
advvotes. See Advance Voting Rules Report.
AvailableVoteTypes. See Available Vote Types Report (also known as "What's Available Where Report").
parties. See Political Party Report.
pollhours. See Poll Hours Report.
elninfo. See Primary Runoff and Majority Vote Rules Report, Voter Registration Requirements, Write-In Rules Report and Recount Rules Report.

For more information, see the subtype parameter below.

Tip

You can find other possible report type values in the Election Reports response:

In v3, in the Type value (XML) or the "type" value (JSON).
In v2, in the category/@term value (XML) or the categories.term value (JSON) when the scheme value is "https://api.ap.org/cv/type/".

delegates

subtype

The report subtype. Multiple values must be separated by commas.

Important
In v2, this parameter must be used in conjunction with the type parameter.

Delegate Tracking Reports

Examples of possible values for the delegate tracking reports are as follows (in v2, they must be used in conjunction with the type=delegates parameter):

delsum. The current summary delegate total for each candidate across the country as well as the change in the past 24 hours, past week and past month.
delstate. The current delegate total for each candidate in each state and at the national level as well as the change in the past 24 hours.
delsuper. The current delegate and unpledged delegate totals for each candidate in each state and at the national level (note that anonymous unpledged delegates are not counted at the state level).

Tip
If multiple delegate reports of the same subtype are returned, use the entry with the most current election date in v3 (and additionally, the latest updated datetime in v2), which shows the most current delegate data available.

Delegate Breakout Report

A possible value example is as follows (in v2, must be used in conjunction with the type=delbreakout parameter):

delbreakout2024. The Democratic and Republican delegate totals by state and type.

Presidential Vote and Electoral Count Reports

Examples of possible values for the presidential reports are as follows (in v2, they must be used in conjunction with the type=pres parameter):

statebystate_pres. Presidential state-by-state popular vote results and electoral count for all candidates (major and minor candidates).
pres_summary. Presidential U.S. national rolled-up popular vote results and electoral count for the top major candidates and minor candidates, who are grouped under "Others."
pres_summary_all. Presidential U.S. national rolled-up popular vote results and electoral count for all candidates (major and minor candidates).

National Party Balance of Power/Trends Reports

Examples of possible values for trends reports are as follows (in v2, they must be used in conjunction with the type=trend parameter):

g. Governors trends report.
s. U.S. Senate trends report.
h. U.S. House trends report.

Calendar, Deadline and Schedule Reports

Examples of possible values are as follows (in v2, they must be used in conjunction with the type=calendar parameter):

elections2024. 2024 Election Calendar.
deadlinesmilestones. Deadlines and Milestones report.
customertesting2023. 2023 Customer Testing Schedule.

Notes
Election Calendar reports are not available for years prior to 2020. Customer Testing Schedule reports are not available for years prior to 2021.

Election Candidate Reports

The value must be in the officeYYYY format; for example, ushouse2020, ussenate2020, governor2020, uspresident2020. In v2, these subtype parameter values must be used in conjunction with the type=candidates parameter.

Note
Election Candidate reports are not available for years prior to 2020.

Advance Voting Rules Report

A possible value example is as follows (in v2, must be used in conjunction with the type=advvotes parameter):

advvotingrules2022GE. State-by-state rules and information about advance voting, including voter requirements for mail-in ballots, changes due to COVID-19 and details regarding in-person advance voting.

Political Party Codes

A possible value is as follows (in v2, must be used in conjunction with the type=parties parameter):

partycodes. The codes and names for political parties active from 2020 to present.

Election Information Reports

Examples of possible values are as follows (in v2, they must be used in conjunction with the type=elninfo parameter):

runoffmajority. Primary Runoff and Majority Vote Rules Report.
regrules. Voter Registration Requirements Report.
writeinrules. Write-In Rules Report.
recountrules. Recount Rules Report.

For more information, see Election Report Data.

Tip

You can find other possible report subtype values in the Election Reports response:

In v3, in the SubType value (XML) or the "subtype" value (JSON).
In v2, in the category/@term value (XML) or the categories.term value (JSON) when the scheme value is "https://api.ap.org/cv/subtype/".

delsum

includesignature

Returns a digital signature in the HTTP response header. Possible values are sha256, eddsa and none (the default). For more information, see Requesting Digital Signatures.

sha256

Request URI Examples

Sample URI	Returned Results
https://api.ap.org/v3/reports	All the latest reports currently available to you.
https://api.ap.org/v3/reports?electionDate=2022-06-28	All the latest available reports from the 06-28-2022 election date.
https://api.ap.org/v3/reports?type=delegates	All the latest delegate reports available to you.
https://api.ap.org/v3/reports?subtype=delsum&electiondate=2020-02-03	All the latest cumulative delegate reports ("DelSum") from the 02-03-2020 election date.
https://api.ap.org/v3/reports?subtype=h,s&electionDate=2020-11-03	All the latest available U.S. Senate and U.S. House Trend reports from the 11-03-2020 election date (v3).
https://api.ap.org/v2/reports?type=trend&subtype=h,s&electionDate=2020-11-03	All the latest available U.S. Senate and U.S. House Trend reports from the 11-03-2020 election date (v2).
https://api.ap.org/v3/reports?type=estimatedvotepercentage&electionDate=2022-06-28	All the latest available Estimated Vote Percentage (EEVP) reports from the 06-28-2022 election date.