Advance Turnout

 

ON THIS PAGE      Show

 

 

 

 

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}]

 

  Important

 

The request URI must be URL-encoded.

 

 

 

Required 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:

  • state (this is the default). Returns advance turnout for each of the specified states, without the details for each of the reporting units (cities and towns for the New England states and counties for the other states).

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

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.

 

  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.

 

 

 

Data 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:

  • State for state-level data

  • Subunit for RU-level data

@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