Vote Types

 

ON THIS PAGE      Show

 

 

 

 

Description

The votetypes=true parameter in the Elections request allows you to receive votes by type for each candidate if available:

 

Vote Type

JSON

Description

Election Day In-Person

"electionDayInPerson"

(Also known as "poll votes," "polling place votes" or "vote center votes") Votes cast in person at a polling place or vote center on Election Day (may also include Provisional votes in certification).

Provisional

"provisional"

(Also known as "Affidavits") Type of ballot used when there are questions about the voter's identity or eligibility to vote. Votes cast by provisional ballot are counted when the voter's identity or eligibility is confirmed. In certified results, provisional votes are often merged within another vote type.

Advance Total

"advanceTotal"

Advance vote total (votes cast prior to Election Day), which may be the sum of the Early In-Person, Absentee In-Person and/or Absentee Mail vote types, or populated when a further breakdown is not available.

Early In-Person

"earlyInPerson"

(Also known as "early votes") Votes cast in person at an early voting location before Election Day (if applicable).

Absentee Total

"absenteeTotal"

Absentee vote total, which may be the sum of Absentee In-Person and/or Absentee Mail, or populated when a further breakdown is not available.

Absentee In-Person

"absenteeInPerson"

Votes cast in person by absentee ballot (if applicable). How is Absentee In-Person different from Early In-Person?

Absentee Mail

"absenteeMail"

Absentee mail ballot votes (may include ballots deposited in drop boxes, overseas & military ballots, and so on).

In-Person Total

"inPersonTotal"

Votes cast in person. This category will be used primarily when a state merges results for Election Day In-Person and Early In-Person, and no further breakdown is available.

Advance In-Person
Total

"advanceInPersonTotal"

Votes cast in person (not by mail) prior to Election Day, which may include Early In-Person and/or Absentee In-Person votes, or populated when a further breakdown is not available. Currently, no states apply to this category.

 

 Notes

 

  • Not all vote types are 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. The Elections API returns specific vote types only if available.

  • The names of the vote type response elements in the XML response are similar to the names of the JSON properties. For more information, see Elections Response.

  • For backwards compatibility, the "avotes" field for each candidate is returned when the avotes=true parameter or the votetypes=true parameter is specified in the request. The value returned in "avotes" field is the A-report votes for a particular candidate as provided by the state and may differ from the "advanceTotal" value.

 

 

 

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

Request URI

 

Method

Request URI

GET

https://api.ap.org/v3/elections/{electionDate}?votetypes=true[{OtherParameters}]

 

  Important

 

The request URI must be URL-encoded.

 

 

 

Request URI Example

Sample URI

Returned Results

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

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

Parameters Used in the Sample URI

 

Parameter

Description

Example

electionDate

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

2021-11-02

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.

VA

votetypes

Indicates whether to return vote types. Valid values are:

  • true (includes the vote types for each candidate, if available).

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

true

format

The response format (xml or json).

json

Response

On success, returns the standard HTTP status code of "200 – OK" and results in the requested format (XML or JSON). The response contains a list of races, reporting units within each race and candidates in each reporting unit. Votes types are returned for each candidate if available. For information about error codes, see API Codes.

Response Examples

The following examples show partial JSON and XML responses to the sample request (for brevity, in a single RU, and only for major candidates in JSON):

JSON

XML

How is Absentee In-Person different from Early In-Person?

In recent years, a number of states have implemented "no-excuse, in-person” absentee voting. This type of voting does require an application, but the process is often streamlined so that the voter can apply for the ballot, receive it and cast it in one visit to a county election office. Depending on how well it is publicized, this type of voting can be very popular and can result in increased absentee voting rates. This differs from early voting in that the early voter’s eligibility is verified before the casting of a ballot while the in-person absentee eligibility is generally determined after the voter has submitted the ballot.

Early in-person voting is characterized by the following:

  • It is “in-person” by definition.

  • It features a finite pre-election voting period (for instance, the 20th day through the 4th day before the election).

  • There is no voter requirement beyond that the voter has to be on the registration roll/qualified voter list. No application is required.

  • Early voters cast votes at special or satellite locations, or polling places, in addition to the county election office (as opposed to in-person absentee voting, which is usually limited to the county election office).

  • Early voters usually cast votes on the same election equipment as Election Day voters (as opposed to the equipment that might be used for the absentee ballots).

  • Early votes are often cast on the equipment in which they will be tabulated, and often the counties will therefore know the number of early votes cast during each early voting day.

  • The early voter’s voting experience is similar to that of an election-day voter (as opposed to in-person absentee voters who must sign an application).