Advance Turnout
|
|
|
|
Description
For presidential and midterm general elections, the Advance Turnout API method returns 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.
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/v3/elections/{electionDate}/advance?[{OptionalParameters}] |
|
|
|
|
The request URI must be URL-encoded. |
|
|
|
|
ImportantRequired Parameter
|
Parameter |
Description |
Example |
|
electionDate |
Date of the election in the YYYY-MM-DD format. For the current election, pre-election data is returned. For previous elections, post-election data is returned. |
2020-11-03 |
Optional Parameters
The following parameters can be used to control the returned data and format:
|
Parameter |
Description |
Example |
|
statePostal |
Two-character state postal code. Multiple values must be separated by commas. When the statePostal parameter is not specified in the request, advance turnout for all states is returned. |
NJ,NY,CT |
|
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 data. Valid options are:
|
RU |
Request URI Example
|
Sample URI |
Returned Results |
|
https://api.ap.org/v3/elections/2020-11-03/advance?statepostal=nc&format=json |
Advance turnout in the JSON format in North Carolina from the current election (2020-11-03 in the example). |
|
https://api.ap.org/v3/elections/2018-11-06/advance?statepostal=nc |
Advance turnout in the XML format in North Carolina from a previous election. |
Response
On success, returns the standard HTTP status code of "200 – OK" and results in the requested format (XML or JSON). The response contains the advance turnout data for the requested states. For information about error codes, see API Codes.
|
|
|
|
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. |
|
|
|
|
NoteData Elements
|
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. |
|
@Disclaimer |
"disclaimer" |
A statement about the sources of the advance turnout data. |
|
AdvanceTurnout |
|
|
|
ReportingUnit |
"reportingUnits" |
Container for the reporting unit(s) for which the data is returned. |
|
@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). |
|
"reportingunitName" |
||
|
@ID |
"reportingunitID" |
Reporting unit ID. |
|
@Level |
"level" |
Region the advance turnout is reported from:
|
|
@LastUpdated |
"lastUpdated" |
Date and time when the advance voting data for this reporting unit were last updated. |
|
Pre-Election Data |
|
Advance turnout data for the current election. |
|
RequestedBallots |
"requested" |
Mail/absentee ballots requested. |
|
@Total |
"total" |
The total number of mail/absentee ballots requested. |
|
Party |
"party" |
Requested mail/absentee ballots by party affiliation. |
|
@Name |
"id" |
Party code (for example, Dem, GOP). For more information, see Party Codes. |
|
@Total |
"total" |
The number of mail/absentee ballots requested by voters affiliated with this party. |
|
IssuedBallots |
"issued" |
Mail/absentee ballots issued. |
|
@Total |
"total" |
The total number of mail/absentee ballots issued. |
|
Party |
"party" |
Issued mail/absentee ballots by party affiliation. |
|
@Name |
"id" |
Party code (for example, Dem, GOP). For more information, see Party Codes. |
|
@Total |
"total" |
The number of mail/absentee ballots sent to voters affiliated with this party. |
|
ReceivedBallots |
"received" |
Advance votes cast broken down by party, ethnicity, gender and age where available. |
|
Party |
"party" |
The number of advance votes cast by members of a certain party. |
|
@Name |
"id" |
Party code (for example, Dem, GOP). For more information, see Party Codes. |
|
@Total |
"total" |
The number of advance votes cast by members of this party. |
|
Ethnicity |
"ethnicity" |
Advance votes cast by people of a certain race/ethnic group. |
|
@Name |
"id" |
The race/ethnic group name, such as White, Black, Hispanic, Other, Unknown. |
|
@Total |
"total" |
The number of advance votes cast by this ethnic group. |
|
Gender |
"gender" |
Advance votes cast by people of a certain gender. |
|
@Name |
"id" |
The voter's gender, such as Women, Men, Unknown. |
|
@Total |
"total" |
The number of advance votes cast by voters of this gender. |
|
Age |
"age" |
Advance votes cast by a certain age group. |
|
@Name |
"id" |
The voter's age group, such as 18-29, 30-44, 45-59, over60, Unknown. |
|
@Total |
"total" |
The number of advance votes cast by voters of this age group. |
|
Summary |
"summary" |
|
|
@MailAbsenteeAccepted |
"mailAbsenteeAccepted" |
Mail/absentee ballots returned or accepted. |
|
@EarlyInPerson |
"earlyInPerson" |
Early in-person votes. |
|
@AdvanceTotal |
"advanceTotal" |
Total number of advance votes cast (mail/absentee plus early in-person votes). |
|
PercentageOfPrevious |
"percentageOfPrevious" |
This year's advance votes as a percentage of a previous election advance turnout. |
|
@PreviousYear |
"previous" |
Previous year (for example, 2016 or 2018). |
|
@Percentage |
"percentage" |
Percentage of that year's election advance turnout. |
|
Historical |
"historical" |
Historical election data. |
|
@Year |
"year" |
The year of a previous election; for example, 2016 or 2018. |
|
@BallotsCast |
"ballotsCast" |
Total number of ballots cast in that election. |
|
@AdvanceCast |
"advanceCast" |
Total number of advance votes cast in that election. |
|
HistoricalRace |
"historicalRace" |
Data for a specific historical race. |
|
@Type |
"type" |
Race type; for example, Pres (Presidential), Sen (Senator), Gov (Governor) or Primary (Presidential Primary). |
|
@TotalNoWriteIn |
"noWriteIn" |
Total number of votes without write-in in that race. |
|
@AdvanceTotal |
"advanceTotal" |
Total number of advance votes cast in that race. |
|
@TotalDem |
"dem" |
Number of advance votes for Democratic candidate in that race. |
|
@TotalGOP |
"gop" |
Number of advance votes for Republican candidate in that race. |
|
Post-Election Data |
|
Advance turnout data for a previous election (that is, an election that happened prior to the current election). |
|
PostElection |
"postElection" |
The container for the post-election data. |
|
@TotalAbsenteeReturned |
"totalAbsenteeReturned" |
Total absentee ballots returned and submitted for counting. |
|
@TotalEarlyCast |
"totalEarlyCast" |
(If available) Total early in-person votes cast. |
|
@TotalCast |
"totalCast" |
Total ballots cast. |
|
@TotalAbsenteeSent |
"totalAbsenteeSent" |
Total number of absentee ballots sent to voters. |
Response Examples
The following examples show partial JSON and XML responses to the sample requests.
Example 1: Advance turnout for the current election
|
JSON |
XML |
 |
 |
Example 2: Advance turnout for a previous election
|
JSON |
XML |
 |
 |