|
Vote Types
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).
|
|