Elections Request

 

ON THIS PAGE      Show

 

 

 

 

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 Headers

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

If-None-Match 

The document’s ETag identifier. For more information, see Conditional Requests.

"4135cda4"

Request URI

 

Method

Request URI

GET

https://api.ap.org/{version}/elections/{electionDate}?[{OptionalParameters}]

 

  Important

 

The request URI must be URL-encoded.

 

 

 

Required Parameters

 

Parameter

Description

Example

version

The API version: v2 or v3.

v3

electionDate

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

2012-04-24

Race Filtering Parameters

You can select the races by specifying either of the following:

  • One or more reporting unit IDs within a state and/or one or more race IDs in that single state.

  • A combination of other race filtering criteria; for example, office ID and winner.

Filtering by Race IDs and/or Reporting Unit IDs

You can 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

Example

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.

7162

7162,6489

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.

6001

6001,6002

statePostal

Two-character state postal code.

  Important

 

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

 

 

 

CO

Filtering by Other Criteria

Parameter

Description

Example

statePostal

Two-character state postal code. The value of “US” may be used during the general election in a presidential year to receive presidential popular votes and electoral counts at the U.S. national rolled-up summary level. Multiple values must be separated by commas.

NJ,PA,NY

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). Multiple values must be separated by commas. For a full list of possible values, see Office Type IDs.

P,S,H,G

winner

Filters races based on the election result. Possible values are:

  • X (returns only races where a winner has been declared)

  • R (returns only races which are advancing to a runoff)

  • U (returns only races where a winner has not yet been declared)

  • A (all races, this is the default)

 

  Notes

 

  • Multiple values are not allowed.

  • The winner=X option is useful if you are requesting only the details of called races (where a winner has been declared) to update a feed or ticker.

 

 

 

X

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). Multiple values must be separated by commas. For a full list of possible values, see Race Type IDs.

D

party

Political party code. Multiple values must be separated by commas. For a list of possible values, see Party Codes.

  Note

 

This parameter is not applicable to general election races. 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.

 

 

 

GOP

Dem,Lib

uncontested

Filters races based on whether they are contested or not. Valid values are:

  • false (returns only contested races)

  • true (returns only uncontested races)

  • all (returns both contested and uncontested races; this is the default)

 

  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.

 

 

 

false

national

Filters races based on whether they are national or not. National races are President, U.S. Senate, U.S. House and Governor for primaries and the general election; and for the general election, ballot measures deemed by the AP to be of national interest. Valid values are:

  • true (returns only national races)

  • false (returns only state and local races)

  • all (returns national, state and local races; this is the default)

true

seatNum

The district number. This parameter does not typically apply to statewide races; for example, Governor races.

25

seatName

The district or ballot measure name. This parameter does not typically apply to statewide races; for example, Governor races.

District 25

1 - Raise General Reserve Fund

Other Optional Parameters

The following parameters can be used to control the returned result data and format.

 

Parameter

Description

Example

resultsType

Indicates whether to return live, test or certified elections data. Possible values are:

  • l. Live data; this is the default.

  • t. Test data.

  • c. Certified results. Any 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.

  • b. Switch to certified data as it becomes available without having to change from resultsType=l to resultsType=c to get certified results.

 

  Important

  

  • During testing, make sure to add the resultsType=t parameter to the request URL to receive test data, including candidates, races, RUs and votes. If neither resultsType=t nor test=true is specified during testing, only the race and candidate initialization data is returned (not including RUs or votes).

  • On election day/LIVE (midnight), remove resultsType=t or test=true from your request URL to receive candidates, races, RUs and votes. Using resultsType=t or test=true on election day/post-election day returns the race and candidate initialization data only.

  • When you use resultsType=b in the request, the response may potentially include a mix of live and certified results (as they become available) because not all races in a state might be certified at the same time. Use the existing resultsType field in the response to determine whether a race has been certified.

  

 

  

c

test
(deprecated)

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

  Important

 

This parameter is deprecated and will be removed in a future release. Use the resultsType=t parameter instead.

 

 

 

true

votetypes

Indicates whether to return votes by type if available. Examples include Election Day In-Person, Early In-Person and Mail Absentee votes. Valid values are:

  • true (includes votes by type for each candidate, if available).

  • false (returns unmodified results; this is the default).

true

avotes

Indicates whether to return the A-report votes. Valid values are:

  • true (includes the A-report vote count for each candidate, if available, in the "AVotes" attribute in XML or the "avotes" property in JSON).

  • false (returns unmodified results; this is the default).

true

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

level

Determines the granularity of the returned races. Valid options are:

  • state (this is the default). Returns the races for each of the specified states, without the details for each of the reporting units. For the general election in a presidential year, also returns presidential popular and electoral votes at the state and U.S. national rolled-up summary levels.

 

 

 Notes

 

 

  • Reporting units are the units at which AP is tabulating the results: cities and towns for the New England states and counties for the other states.

  • In Alaska (AK), AP tabulates votes only at the state level.

 

 

 

 

  • RU. Returns the races for both the specified states and each of the reporting units within each state.

 

 

 Note

 

 

FIPS codes at the county level are returned for each reporting unit (see American National Standards Institute (ANSI) Codes for States).

 

 

 

 

  • FIPScode. Returns the races for both the specified states and each of the FIPS codes within each state.

 

 

 Note

 

 

This option is recommended for receiving results aggregated to the county level in the New England states. For more information about FIPS codes, see American National Standards Institute (ANSI) Codes for States.

 

 

 

 

  • district. Returns one of the following:

    • For the presidential primaries, returns the races (including vote and delegate counts) for both the specified states and each of the delegate districts within each state.

    • For the general election in Maine and Nebraska in a presidential year prior to 2024, returns presidential results and electoral counts by district. Starting from the 2024 GE and onward, you no longer need to specify level=district; the ME and NE presidential results and electoral counts are returned as separate races by default (level=state) or when you specify level=ru or level=fipscode. Fore more information, see Presidential Results and Electoral Counts by District.

RU

candidateInfo

Returns full or brief candidate information. Valid values are:

  • full (returns all available candidate information listed under 'Candidate').

  • brief (returns only the candidate ID, vote/delegate/electoral counts and the winner indicator; this option is useful if you are maintaining a database of candidate information and are requesting vote/delegate/electoral count updates and race calls).

 

  Note

 

If a candidate's reference information has been updated, and you are using the next request link to get updates, the response will include the candidate information update indicator (InfoUpdated="1" in XML and "infoUpdated"="true" in JSON). If you requested brief candidate information, the full candidate information will be returned for the updated candidate.

 

 

 

brief

setZeroCounts

 

Overrides results with zeros; omits the winner indicator. Valid values are:

  • true (sets the vote, delegate, electoral and reporting precinct counts to zero; does not return the winner indicator)

  • false (returns unmodified results; this is the default)

 

  Notes

 

  • The setZeroCounts and omitResults parameters are mutually exclusive.

  • You can use setZeroCounts=true to initialize your database before the start of the election.

 

 

 

true

omitResults

Returns only the reference information about the races and candidates without election results, such as vote/delegate/electoral counts, the winner indicator and reporting units.

  • true (returns reference information without election results)

  • false (returns unmodified results; this is the default)

 

  Note

 

The omitResults and setZeroCounts parameters are mutually exclusive.

 

 

 

true

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

Filtering by Race IDs

Sample URI

Returned Results

https://api.ap.org/v2/elections/2012-04-24?statePostal=PA&raceID=39290,39593&format=json

Election data in the JSON format for the specified race IDs in Pennsylvania from the 4/24/2012 election.

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

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.

Filtering by Other Criteria

Sample URI

Returned Results

https://api.ap.org/v2/elections/2012-04-24?statePostal=PA&officeID=S,H&raceTypeID=D,R

4/24/12 election data for all Democrat and Republican U.S. Senate and U.S. House primary races in Pennsylvania.

https://api.ap.org/v2/elections/2012-04-24?statePostal=NY,PA&officeID=P&raceTypeID=R

4/24/12 election data for Republican presidential primary races in New York and Pennsylvania.

https://api.ap.org/v2/elections/2012-04-24?officeID=H&winner=X

4/24/12 election data for all U.S. House races where a winner has been declared.

https://api.ap.org/v2/elections/2014-08-26?statePostal=VT&officeID=H,G&party=GOP

8/26/14 election data for Republican primary races for U.S. House and Governor in Vermont.

https://api.ap.org/v2/elections/2012-04-24?statePostal=PA&officeID=H&raceTypeID=D&format=json

4/24/12 election data in the JSON format for Democratic U.S. House primary races in Pennsylvania.

https://api.ap.org/v2/elections/2012-11-06?national=true&statepostal=WA

The GE 2012 data showing all national races for WA - President, Governor, U.S. Senate, U.S. House and two ballot measures that were deemed by the AP to be of national interest.

https://api.ap.org/v2/elections/2015-09-01?statePostal=WV&officeID=P&level=district&resultsType=t

9/1/15 test election data by delegate district for Democratic and Republican presidential primary races in West Virginia.

  Note

 

The request URL in the example above includes the resultsType=t parameter, which is strongly recommended for receiving test election data since the test=true parameter has been deprecated.

 

 

 

 

https://api.ap.org/v2/elections/2016-11-08?officeID=P

11/8/2016 U.S. national and state-by-state presidential results and electoral counts.

https://api.ap.org/v2/elections/2012-11-06?statePostal=NJ,US&officeID=P

11/6/2012 presidential results and electoral counts for the state of New Jersey and U.S. national rolled-up summary level.

https://api.ap.org/v2/elections/2016-11-08?level=district

11/8/2016 presidential results and electoral counts by district for the states that use the district-based method for awarding electoral votes (Maine and Nebraska in 2016).

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

11/6/2012 presidential results and electoral counts by district in Maine.

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

11/2/2021 VA statewide and RU-level votes by type in addition to the current total vote count for each candidate.

https://api.ap.org/v2/elections/2020-06-03?statePostal=PA&avotes=true

6/3/2020 PA statewide A-report votes in addition to the current total vote count for each candidate.