AP ASSOCIATED PRESS
AP ELECTIONS API 2.1
Developer?s Guide
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
TABLE OF CONTENTS
INTRODUCTION ................................................................ 3
About This Guide ...................................3
Audience ........................................................... 3
Searching This Guide....................................... 3
Conventions ..................................................... 3
About AP Elections API ..........................3
Typical Workflow Overview ............................ 3
API Keys ........................................................... 4
Getting Started: Landing Page ........................ 4
Supported Protocol .......................................... 4
Client Implementation Requirement ............. 4
Recommended Practices ................................. 4
Response .............................................. 11
Response Elements ......................................... 11
Examples .........................................................14
ELECTION REPORTS ......................................................30
Description ......................................... 30
Request ............................................... 30
Request URI Parameters ............................... 30
Request Headers (Optional)...........................31
Request URI Examples .................................. 32
What's New ............................................5
Response ............................................. 32
Metadata Elements ........................................ 32
Examples ........................................................ 33
Resolved Issues ..................................... 6
APPENDIX ........................................................................36
Contacting Support ............................... 6
Error Codes ......................................... 36
ELECTIONS ..........................................................................7
Office ID Examples .............................. 36
Description ............................................ 7
Party Value Examples ..........................37
Request .................................................. 7
Request URI Parameters..................................7
Request Headers (Optional) ..........................10
Request URI Examples ..................................10
April 22, 2016 © 2016 The Associated Press
2
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
INTRODUCTION
ABOUT THIS GUIDE
Audience
This guide is intended for software engineers who develop applications that access AP election data through
application programming interfaces (APIs).
Searching This Guide
To search this guide, choose Edit → Find in Adobe Acrobat.
Conventions
− In request syntax, variable names are shown in braces { }. Optional parameters are shown in brackets [ ]. Do
not type the braces and brackets in the request.
− In response descriptions, attributes are indicated by an at sign (@).
− In response examples, an ellipsis (…) indicates information that is omitted for brevity.
ABOUT AP ELECTIONS API
AP Elections API allows you to retrieve AP elections data using your own tools. The API provides access to all
data that is available via FTP at ftp://electionsonline.ap.org.
Typical Workflow Overview
Integrate your election systems with AP Elections API. Your election results delivery application (for
example, a results loader that powers your election websites) retrieves election race information from AP
Elections API.
Request election race information, including vote updates and race calls. Throughout the
election, your application polls the API at regular intervals to retrieve election race information in the races
of interest:
a) Make an initial request for the election race information. Initially, you make a request for all
of the races you are interested in. The response includes:
− Reference information about each race and each candidate.
− Vote/delegate/electoral counts and race calls (races that have been called are the races where a
winner has been declared and the races that are advancing to a runoff).
− The link to use in the next request.
b) Use the returned link to make the next request (for more information, see "Recommended
Practices" on page 4). The response includes the races for which the vote, delegate or electoral count,
race call and/or candidate information have been updated since your previous request and the link to
use in the next request. You can now repeat this step during the election to get updates.
April 22, 2016
3
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
Request election reports. Throughout the election, your application polls the API at regular intervals to
retrieve election reports (for example, delegate reports for presidential primaries, presidential vote and
electoral count reports for the general election in a presidential year, and national party balance of
power/trends for Governors, U.S. Senate and U.S. House for the general election).
a) Make an initial request for all available reports. Initially, your application makes a request for
all of the reports you are interested in. The response includes a list of all reports available to you that
match the specified criteria and the link to use in the next request. Do not store any direct links to
individual reports (if a new version of a report arrives, there will be a different direct link to this new
version). Always use the 'next request' link to monitor for the new versions of reports.
b) Use the returned link to make the next request. The response includes the latest versions of
the reports that have become available since your previous request and the link to use in the next
request. You can now repeat this step throughout the election.
API Keys
An API key is the access key required for making API calls. If you have not received your API key, please contact
Customer Support.
Getting Started: Landing Page
The AP Elections API landing page at https://api.ap.org/v2/elections?apiKey={apiKey} provides:
− Links to the API documentation and Election Calendars.
− A list of currently available elections data by date.
Note: Available data may change daily.
− A link to the Query Explorer, an interactive tool for creating API requests that helps you get familiar with the
API parameters and allows you to view available elections data.
Supported Protocol
HTTPS 1.1 is supported for all API calls.
Client Implementation Requirement
The implementation of your client application must allow new data elements and attributes to be added by the
AP by ignoring any markup that it does not recognize.
Recommended Practices
Receiving Election Updates
Important: For improved performance, it is strongly recommended to receive updates using the
returned link to make the next request (see "Using the Returned Link for the Next Request" on page 4).
However, if you are not using the next request links and are repeatedly requesting the full set of election
results, it is recommended to use conditional requests with Etag to avoid redundant processing of
unchanged responses (see "Conditional Requests" on page 5).
Using the Returned Link for the Next Request
To check for any new data since your previous request, it is strongly recommended that your client application
use the link returned in the response for the next request, as described in "Typical Workflow Overview" on page
3. The next request link (link/@rel="next" in XML and "nextrequest" in JSON) is available in the responses of
all of the Election API methods.
If there have been changes since your previous request, the server sends back the HTTP/200 OK header and the
new data in the response body. If there have been no changes, the server returns the HTTP/200 OK header and
only the link for the next request in the response body.
April 22, 2016
4
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
Conditional Requests
Important: This section applies to requesting election result updates using the /elections API method.
Do not use conditional requests with Etag for requesting election report updates. For more information,
see "Getting Election Report Updates" on page 5.
If you are not following the recommended practice of using returned 'next request' links and are repeatedly
requesting the full set of election results, it is recommended that your client application send a conditional GET
request to the AP Elections API server to check if there have been any updates since your last request. This
practice helps avoid redundant processing of unchanged responses.
AP Elections API responses include the ETag header; for example:
HTTP/1.x 200 OK
...
Etag: "4135cda4"
(a unique hash for the document)
When making a conditional request, your client application must provide the AP Elections API server
the ETag identifier of the previous request using the If-None-Match header. If the client’s document is the latest
(based on this value), the server sends back the HTTP/304 Not Modified header without the response body.
Alternatively, if the client’s document is outdated, the server sends back the HTTP/200 OK header and the new
response body.
Getting Election Report Updates
To request election report updates, use the 'next request' links, as described in "Using the Returned Link for the
Next Request" on page 4.
The list of reports returned when you submit a new search request for reports using optional filtering parameters
always includes links to the latest available versions of the reports. If a new version of the report arrives, there
will be a different direct link to this new version. Do not follow stored direct links to reports because these
reports may already be outdated. To monitor for new versions of the reports, always submit a new search request
using the 'next request' link.
Working with Query Quotas
Your AP Elections API key is assigned a quota (also referred to as throttle) setting for the number of API queries
you can make per minute. Your API throttle value is indicated in your AP Elections API Welcome letter.
The recommended practices for working with API quotas are:
− No need to synchronize your clock with the API. The minute time period covering each quota cycle
does not begin at second one on a particular clock; instead, it begins when you make your first request (or
first request following an idle period). Therefore, you do not need to synchronize your clock with the API.
− Processing occasional '403: Per-minute quota exceeded' errors. Due to the timing differences
between your client application sending a request and it being received and processed by the API, precise
per-second quota management is not always practical from both the server and client perspective. Therefore,
it is recommended that your client application gracefully handle occasional '403: Per-minute quota
exceeded" errors by waiting 5-10 seconds and trying again.
Note: Retrieving each individual report linked to the list of reports returned by the Election Reports
method does not count against your quota limit.
WHAT'S NEW
− Presidential results and electoral counts. For the general election in a presidential year, in addition to
popular votes, the API provides electoral counts at the state and U.S. national rolled-up summary levels.
District-level results are also available for states that award electoral votes using the district-based method
(currently, Maine and Nebraska).
− National and state-by-state results and electoral counts. The U.S. national and state-by-state
presidential popular votes and electoral counts are returned by the /elections API method; for example:
https://api.ap.org/v2/elections/2016-11-08?officeID=P&apiKey={apiKey}
To request presidential results and electoral counts for specific states and the U.S. national summary
level, use the statePostal parameter (with the value of "US" indicating the national level); for example:
https://api.ap.org/v2/elections/2016-11-08?officeID=P&statePostal=NY,NJ,US&apiKey={apiKey}
April 22, 2016
5
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
Note: When level=ru or level=fipscode is specified in the request, electoral counts (both the state
electoral count and the candidates’ electoral votes) are added to the state results summary returned
at the top of these responses. Only presidential popular vote results are available for the lower-level
reporting units (counties or cities/towns for the New England states for level=ru or FIPS codes for
level=fipscode).
For more information, see "Presidential Results and Electoral Counts - National and State-by-State" on
page 25.
− Presidential popular and electoral votes at the district level. During the general election in a
presidential year, use the level=district parameter in the /elections API method to receive presidential
results and electoral counts by district (currently only for Maine and Nebraska). For example, this URL
returns results by district and state for Maine and Nebraska from the 2016 general election:
https://api.ap.org/v2/elections/2016-11-08?level=district&apiKey={apiKey}
For more information, see "Presidential Results and Electoral Counts by District" on page 27.
− New election report types are now available via the API, including presidential vote and electoral count
reports for the general election in a presidential year, and national party balance of power/trends for
Governors, U.S. Senate and U.S. House for the general election. For more information, see "Election
Reports" on page 30.
− Query quota management changes. Retrieving each individual report linked to the list of reports
returned by the Election Reports method no longer counts against your quota limit. For more information
about quotas, refer to "Working with Query Quotas" on page 5.
− Changes to recommended practices. These changes do not affect your current workflows; you may
continue using your existing workflow for receiving election updates.
− Using 'next request' links is strongly encouraged for receiving efficient updates on election results
and reports; however, combining the 'next request' links with conditional requests is no longer
recommended.
− Conditional requests using Etag are recommended only if you cannot avoid repeatedly requesting the
full set of election results. Using the If-Modified-Since header in conditional requests is no longer
required. Conditional requests must not be used for requesting election report updates.
For more information, see "Recommended Practices" on page 4.
RESOLVED ISSUES
− Duplicate election reports are no longer delivered in this release.
− Leading zeros in FIPS codes are no longer being trimmed; the FIPS codes with leading zeros are now
delivered correctly (for example, "01001" instead of "1001").
CONTACTING SUPPORT
For technical help, contact AP Customer Support:
− Phone: 877-836-9477 (U.S. toll-free number) or 212-621-7361 (from outside of the U.S.)
− E-mail: APCustomerSupport@ap.org
− Website: http://customersupport.ap.org
To comment on the documentation, send an e-mail message to documentation@ap.org.
April 22, 2016
6
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
ELECTIONS
DESCRIPTION
Returns election race information for the specified filtering criteria (for example, state postal code or office ID),
including updates to vote/delegate/electoral count, race call and candidate information since the last request and
the link to use in the next request. Races that have been called are the races where a winner has been declared
and the races that are advancing to a runoff.
Important: Requesting Election Race Information Updates
Throughout the election, your application polls the API at regular intervals to retrieve
vote/delegate/electoral count updates for each candidate, candidate information updates and race calls
for the races of interest; for example, all races in your state or Top-of-the-Ticket races in all states.
The following workflow is strongly recommended for requesting updates:
a) Make an initial request for the election race information. Initially, you make a request for
all of the races you are interested in. The response includes reference information about the races and
candidates, vote/delegate/electoral counts, race calls and the link to use in the next request.
b) Use the returned link to make the next request (for more information, see "Recommended
Practices" on page 4). The response includes the races for which the vote count, race call and/or
candidate information has been updated since your previous request and the link to use in the next
request. You can now repeat this step throughout the election.
REQUEST
METHOD
GET
REQUEST URI
https://api.ap.org/{version}/elections/{electionDate}?apiKey={apiKey}[{OtherParameters}]
Important: The request URI must be URL-encoded.
Request URI Parameters
Required Parameters
PARAMETER
version
electionDate
DESCRIPTION
The API version. Currently, the only valid value is v2.
Date of the election in the YYYY-MM-DD format.
EXAMPLE
v2
2012-04-24
Race Filtering Parameters
You can select the races by specifying either of the following:
− One or more race IDs and a single state.
− A combination of other race filtering criteria; for example, office ID and winner.
Filtering by Race IDs
PARAMETER
raceID
statePostal
April 22, 2016
DESCRIPTION
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.
Two-character state postal code.
Important: When used in conjunction with the raceID parameter, this
parameter is required, and multiple values are not allowed.
EXAMPLE
93593
NJ
7
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
Filtering by Other Criteria
PARAMETER
statePostal
officeID
winner
raceTypeID
party
uncontested
national
seatNum
seatName
April 22, 2016
DESCRIPTION
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.
Single-character Office Type ID; for example: P (President), S (U.S. Senate), H
(U.S. House) and G (Governor). Multiple characters must be separated by
commas. For a list of possible values, see "Office ID Examples" on page 36.
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.
Single-character race type ID. Multiple values must be separated by commas.
Possible values are: D (Dem Primary), R (GOP Primary), G (General), E (Dem
Caucus), S (GOP Caucus).
Party abbreviation. Multiple values must be separated by commas. For a list of
possible values, see "Party Value Examples" on page 37.
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.
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.
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 issues 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)
The district or ballot initiative number. This parameter does not typically apply to
statewide races; for example, Governor races.
The district or ballot initiative name. This parameter does not typically apply to
statewide races; for example, Governor races.
EXAMPLE
NJ,PA,NY
P,S,H,G
X
G
GOP
Dem,Lib
false
true
25
District 25
1A-Abortion
8
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
Other Optional Parameters
The following parameters can be used to control the result format.
PARAMETER
test
format
level
candidateInfo
April 22, 2016
DESCRIPTION
Indicates whether to return live or test elections data. Possible values are:
− false (live data; this is the default)
− true (test data)
Important: To receive test data, make sure to add the optional test=true
parameter to the request URL.
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.
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 reporting 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 statewide 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 https://www.census.gov/geo/reference/codes/cou.html).
− 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 https://www.census.gov/geo/reference/codes/cou.html.
− 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 a presidential year, returns presidential results
and electoral counts by district (currently, only for Maine and Nebraska).
Returns full or brief candidate information. Valid values are:
− full (returns all available candidate information listed under 'Candidate' on
page 13).
− 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.
EXAMPLE
true
json
RU
brief
9
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
PARAMETER
setZeroCounts
omitResults
DESCRIPTION
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.
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.
EXAMPLE
true
true
Request Headers (Optional)
HEADER
Accept
If-None-Match
Accept-Encoding
DESCRIPTION
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.
The document’s ETag identifier. For more information, see
"Conditional Requests" on page 5.
Compresses the response to the gzip format.
EXAMPLE
application/json
"4135cda4"
gzip
Request URI Examples
Filtering by Race IDs
SAMPLE URI
https://api.ap.org/v2/elections/2012-04-24?apiKey=
{apiKey}&statePostal=PA&raceID=39290,39593
&format=json
RETURNED RESULTS
Election data in the JSON format for the specified
race IDs in Pennsylvania from the 4-24-2012
election.
Filtering by Other Criteria
SAMPLE URI
https://api.ap.org/v2/elections/2012-04-24?apiKey=
{apiKey}&statePostal=PA&officeID=S,H&raceTypeID=
D,R
https://api.ap.org/v2/elections/2012-04-24?apiKey=
{apiKey}&statePostal=NY,PA&officeID=P&raceTypeID
=R
https://api.ap.org/v2/elections/2012-04-24?apiKey=
{apiKey}&officeID=H&winner=X
https://api.ap.org/v2/elections/2014-08-26?apiKey=
{apiKey}&statePostal=VT&officeID=H,G&party=GOP
https://api.ap.org/v2/elections/2012-04-24?apiKey=
{apiKey}&statePostal=PA&officeID=H&raceTypeID=D
&format=json
April 22, 2016
RETURNED RESULTS
4/24/12 election data for all Democrat and
Republican US Senate and US House primary races
in Pennsylvania.
4/24/12 election data for Republican presidential
primary races in New York and Pennsylvania.
4/24/12 election data for all US House races where
a winner has been declared.
8/26/14 election data for Republican primary races
for U.S. House and Governor in Vermont.
4/24/12 election data in the JSON format for
Democrat US House primary races in
Pennsylvania.
10
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
SAMPLE URI
https://api.ap.org/v2/elections/2012-1106?apiKey={apikey}&national=true&statepostal=WA
RETURNED RESULTS
The GE 2012 data showing all national races for
WA—President, Governor, U.S. Senate, U.S. House
and two ballot initiatives that were deemed by the
AP to be of national interest.
https://api.ap.org/v2/elections/2015-09-01?apiKey=
9/1/15 test election data by delegate district for
{apiKey}&statePostal=WV&officeID=P&level=district
Democrat and Republican presidential primary
&test=true
races in West Virginia.
Note: The request URL in the example above includes the test=true parameter, which is required for
receiving test election data.
https://api.ap.org/v2/elections/2016-11-08?apiKey=
11/8/2016 U.S. national and state-by-state
{apiKey}&officeID=P
presidential results and electoral counts.
https://api.ap.org/v2/elections/2012-11-06?apiKey=
11/6/2012 presidential results and electoral counts
{apiKey}&statePostal=NJ,US&officeID=P
for the state of New Jersey and U.S. national rolledup summary level.
https://api.ap.org/v2/elections/2016-1111/8/2016 presidential results and electoral counts
08?level=district&apiKey={apiKey}
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?apiKey=
11/6/2012 presidential results and electoral counts
{apiKey}&statePostal=ME&level=district
by district in Maine.
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. For information about error codes, see “Error Codes” on page 36.
Note: Not all data is available in any particular state or race. The available data may change for future
election dates depending on the rules and regulations for a particular election.
Response Elements
XML ELEMENT
Vote
JSON PROPERTY
DESCRIPTION
@ElectionDate
@Timestamp
Race
@Test
"electionDate"
"timestamp"
"races"
"test"
Date of the election day.
Timestamp when the file was created on the AP Elections system.
@ID
@Type
"raceID"
"raceType"
@TypeID
"raceTypeID"
@OfficeID
"officeID"
@OfficeName
@Desc
"officeName"
"description"
April 22, 2016
Indicates whether the elections data is live or for test purposes only:
− In XML: Test="1" (test data); Test="0" (live data)
− In JSON: "test": true (test data); "test": false (live data)
Unique race ID for a specific state.
Character string indicating the type of race (for example, GOP Primary,
General, Democratic Caucus).
Single-character race type ID: D (Dem Primary), R (GOP Primary), G
(General), E (Dem Caucus), S (GOP Caucus).
Office type ID, usually a single character; for example: P (President), G
(Governor), S (U.S. Senate) and H (U.S. House).
Name of the office, ballot initiative or other race.
Description of the office, ballot initiative or other (if applicable).
11
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
XML ELEMENT
@Party
JSON PROPERTY
"party"
@SeatName
"seatName"
@SeatNum
"seatNum"
@Uncontested
"uncontested"
@National
"national"
@NumWinners
"numWinners"
@NumRunoff
ReportingUnit
@StatePostal
@Name
"numRunoff"
"reportingUnits"
"statePostal"
"stateName"
"reportingunitName"
@Level
"level"
@ElectTotal
"electTotal"
@FipsCode
@DistrictType
"fipsCode"
"districtType"
@LastUpdated
"lastUpdated"
@ID
"reportingunitID"
April 22, 2016
DESCRIPTION
Party abbreviation (for example, Dem, GOP, Lib). This field is
not applicable to a general election race. 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.
The district or ballot initiative name; for example: District 1,
1A-Abortion). Typically not applicable to statewide races.
The district or ballot initiative number. Typically not
applicable to statewide races.
Indicates that the race is uncontested:
− In XML: Uncontested="1"
− In JSON: "uncontested": true
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.
Indicates that the race is national:
− In XML: National="1"
− In JSON: "national": true
The maximum number of allowed winners (returned only if
there is more than one).
The maximum number of candidates in a runoff race.
Two-character state postal code.
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) or the district
name (for example, At-Large, District 1, PLEO).
Region the vote results are reported from:
− national for presidential results and electoral count at the
U.S. national rolled-up summary level (only for the
general election in a presidential year)
− state for state-level results
− subunit for results at the RU or FIPS code level
− district for delegate results at the district level from the
presidential primaries OR presidential results and
electoral counts by district (currently, in Maine and
Nebraska) for the general election in a presidential year
The state or U.S. national electoral count (only for the
general election in a presidential year).
County FIPS code.
District type; for example, CD for Congressional District,
AtLarge for At-Large (awarded based on statewide
presidential vote), PLEO for Party Leaders and Elected
Officials (awarded based on statewide presidential vote; for
Dem only).
Date and time when the results for this reporting unit were
last updated.
Reporting unit ID or district number (for example, 4 for
Congressional District 4).
12
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
XML ELEMENT
Precincts
@Reporting
@Total
@ReportingPct
Candidate
@ID
JSON PROPERTY
DESCRIPTION
"precinctsReporting"
"precinctsTotal"
"precinctsReportingPct"
"candidates"
"candidateID"
The number of precincts reporting.
The total number of precincts.
The percentage of precincts reporting.
@Party
"party"
@Incumbent
"incumbent"
@First
@Middle
@Last
@Abbrv
"first"
"middle"
"last"
"abbrv"
@JR
@PolID
"suffix"
"polID"
@BallotOrder
"ballotOrder"
@PolNum
"polNum"
@VoteCount
"voteCount"
@DelegateCount
"delegateCount"
@ElectWon
"electWon"
@Winner
"winner"
@InfoUpdated
"infoUpdated"
link
@rel="next"
@href
April 22, 2016
"nextrequest"
AP-assigned unique ID for this candidate in a state's race. If a
candidate is running in multiple races, this candidate has a
different Candidate/@ID (or "candidateID") in each race.
Party affiliation for a specific candidate, abbreviation (for
example, Dem, GOP, Lib).
Indicates that the candidate is an incumbent:
− In XML: Incumbent="1"
− In JSON: "incumbent": true
Candidate's first name.
Candidate's middle name.
Candidate's last name.
Candidate's abbreviated name, usually last name with some
vowels removed if too long. This attribute is omitted if its
value is identical to the candidate's last name.
Candidate's suffix.
Unique National Politician ID across all states and races
(only for politicians who have run in a national race). For
local politicians, this value is set to "0".
Ballot order of this candidate. There may be gaps in sequence
in this order field.
AP-assigned unique ID for this candidate in a specific state,
regardless of race candidacy.
Current number of votes for a particular candidate.
Delegates won by this candidate in this district (only for
delegate results for presidential primaries).
The candidate’s electoral votes (only for the general election
in a presidential year).
Single character indicating whether the candidate is a
winner:
− X (the candidate is a winner)
− R (the candidate is advancing to a runoff)
− N (the candidate is no longer considered the winner due
to a race call reversal)
Indicates that the candidate information has been updated:
− In XML: InfoUpdated="1"
− In JSON: "infoUpdated": true
Indicates a link for the next request that must be used to
request data newer than the data in the previously returned
response.
The specific URL for the next request.
13
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
Examples
State-Level Results
This example shows state-level results of primary races for Governor in Vermont. Both contested and uncontested
races are returned by default. Since the level parameter is not specified in the request, the response does not
include the details for each of the reporting units.
Note: For the general election in a presidential year, results at the default level=state also include
presidential popular and electoral votes at the state and U.S. national rolled-up summary levels. For more
information, see "Presidential Results and Electoral Counts - National and State-by-State" on page 25.
XML
JSON
{
"electionDate": "2014-08-26",
"timestamp": "2015-09-01T19:00:42.813Z",
"races": [
{
"test": false,
"raceID": "46005",
"raceType": "Primary",
"raceTypeID": "D",
"officeID": "G",
"officeName": "Governor",
"party": "Dem",
"national": true,
"reportingUnits": [
{
"statePostal": "VT",
"stateName": "Vermont",
"level": "state",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 275,
"precinctsTotal": 275,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Peter", "last": "Shumlin", "party": "Dem", "incumbent": true, "candidateID": "51977", "polID": "45461",
"ballotOrder": 2, "polNum": "49003", "voteCount": 15292, "winner": "X"},
{"first": "Brooke", "last": "Paige", "party": "Dem", "candidateID": "51976", "polID": "62482", "ballotOrder": 1, "polNum":
"49570", "voteCount": 3229}]}]},
April 22, 2016
14
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
{
{
"test": false,
"raceID": "46006",
"raceType": "Primary",
"raceTypeID": "R",
"officeID": "G",
"officeName": "Governor",
"party": "GOP",
"national": true,
"reportingUnits": [
{
"statePostal": "VT",
"stateName": "Vermont",
"level": "state",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 275,
"precinctsTotal": 275,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Scott", "last": "Milne", "party": "GOP", "candidateID": "52295", "polID": "64039", "ballotOrder": 2, "polNum":
"49776", "voteCount": 11491, "winner": "X"},
{"first": "Steve", "last": "Berry", "party": "GOP", "candidateID": "51978", "polID": "63906", "ballotOrder": 1, "polNum":
"49686", "voteCount": 1106},
{"first": "Emily", "last": "Peyton", "party": "GOP", "candidateID": "51980", "polID": "60894", "ballotOrder": 3, "polNum":
"49526", "voteCount": 1055}]}]},
"test": false,
"raceID": "46683",
"raceType": "Primary",
"raceTypeID": "0",
"officeID": "G",
"officeName": "Governor",
"party": "Oth",
"uncontested": true,
"national": true,
"reportingUnits": [
{
"statePostal": "VT",
"stateName": "Vermont",
"level": "state",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 0,
"precinctsTotal": 0,
"precinctsReportingPct": 0.0,
"candidates": [
{"first": "Pete", "last": "Diamondstone", "abbrv": "Dmndstn", "party": "Oth", "candidateID": "51981", "polID": "1157",
"ballotOrder": 1, "polNum": "48967", "voteCount": 0, "winner": "X"}]}]}],
"nextrequest": "https://api.ap.org/v2/elections/2014-08-26?statePostal=VT&officeID=G&format=json
&minDateTime=2015-09-01T18%3a17%3a32.000Z"}
Results by Reporting Unit
This example (in XML and JSON) shows results by reporting unit for the primary races for Governor in Vermont.
Since the level=ru parameter is specified in the request, the response includes results for both the specified state
(Vermont) and each of the reporting units within this state (cities and towns in this example since Vermont is a
New England state). Note that in addition to the reporting unit ID, the county FIPS code is also reported for each
New England city or town, so that you can aggregate results to the county level.
XML
April 22, 2016
15
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
...
...
...
JSON
{
"electionDate": "2014-08-26",
"timestamp": "2015-09-01T19:26:17.198Z",
"races": [
{
"test": false,
"raceID": "46005",
"raceType": "Primary",
"raceTypeID": "D",
April 22, 2016
16
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
{
"officeID": "G",
"officeName": "Governor",
"party": "Dem",
"national": true,
"reportingUnits": [
{
"statePostal": "VT",
"stateName": "Vermont",
"level": "state",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 275,
"precinctsTotal": 275,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Peter", "last": "Shumlin", "party": "Dem", "incumbent": true, "candidateID": "51977", "polID": "45461",
"ballotOrder": 2, "polNum": "49003", "voteCount": 15292, "winner": "X"},
{"first": "Brooke", "last": "Paige", "party": "Dem", "candidateID": "51976", "polID": "62482", "ballotOrder": 1, "polNum":
"49570", "voteCount": 3229}]},
{
"statePostal": "VT",
"reportingunitName": "Addison",
"reportingunitID": "46001",
"level": "subunit",
"fipsCode": "50001",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 1,
"precinctsTotal": 1,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Peter", "last": "Shumlin", "party": "Dem", "incumbent": true, "candidateID": "51977", "polID": "45461",
"ballotOrder": 2, "polNum": "49003", "voteCount": 26, "winner": "X"},
{"first": "Brooke", "last": "Paige", "party": "Dem", "candidateID": "51976", "polID": "62482", "ballotOrder": 1, "polNum":
"49570", "voteCount": 5}]},
{
"statePostal": "VT",
"reportingunitName": "Albany",
"reportingunitID": "46002",
"level": "subunit",
"fipsCode": "50019",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 1,
"precinctsTotal": 1,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Peter", "last": "Shumlin", "party": "Dem", "incumbent": true, "candidateID": "51977", "polID": "45461",
"ballotOrder": 2, "polNum": "49003", "voteCount": 12, "winner": "X"},
{"first": "Brooke", "last": "Paige", "party": "Dem", "candidateID": "51976", "polID": "62482", "ballotOrder": 1, "polNum":
"49570", "voteCount": 4}]}]},
...
"test": false,
"raceID": "46006",
"raceType": "Primary",
"raceTypeID": "R",
"officeID": "G",
"officeName": "Governor",
"party": "GOP",
"national": true,
"reportingUnits": [
{
"statePostal": "VT",
"stateName": "Vermont",
"level": "state",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 275,
"precinctsTotal": 275,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Scott", "last": "Milne", "party": "GOP", "candidateID": "52295", "polID": "64039", "ballotOrder": 2, "polNum":
"49776", "voteCount": 11491, "winner": "X"},
{"first": "Steve", "last": "Berry", "party": "GOP", "candidateID": "51978", "polID": "63906", "ballotOrder": 1, "polNum":
"49686", "voteCount": 1106},
{"first": "Emily", "last": "Peyton", "party": "GOP", "candidateID": "51980", "polID": "60894", "ballotOrder": 3, "polNum":
"49526", "voteCount": 1055}]},
{
"statePostal": "VT",
"reportingunitName": "Addison",
"reportingunitID": "46001",
April 22, 2016
17
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
{
{
"level": "subunit",
"fipsCode": "50001",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 1,
"precinctsTotal": 1,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Scott", "last": "Milne", "party": "GOP", "candidateID": "52295", "polID": "64039", "ballotOrder": 2, "polNum":
"49776", "voteCount": 51, "winner": "X"},
{"first": "Steve", "last": "Berry", "party": "GOP", "candidateID": "51978", "polID": "63906", "ballotOrder": 1, "polNum":
"49686", "voteCount": 6},
{"first": "Emily", "last": "Peyton", "party": "GOP", "candidateID": "51980", "polID": "60894", "ballotOrder": 3, "polNum":
"49526", "voteCount": 4}]},
"statePostal": "VT",
"reportingunitName": "Albany",
"reportingunitID": "46002",
"level": "subunit",
"fipsCode": "50019",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 1,
"precinctsTotal": 1,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Scott", "last": "Milne", "party": "GOP", "candidateID": "52295", "polID": "64039", "ballotOrder": 2, "polNum":
"49776", "voteCount": 32, "winner": "X"},
{"first": "Steve", "last": "Berry", "party": "GOP", "candidateID": "51978", "polID": "63906", "ballotOrder": 1, "polNum":
"49686", "voteCount": 6},
{"first": "Emily", "last": "Peyton", "party": "GOP", "candidateID": "51980", "polID": "60894", "ballotOrder": 3, "polNum":
"49526", "voteCount": 5}]}]},
...
"test": false,
"raceID": "46683",
"raceType": "Primary",
"raceTypeID": "0",
"officeID": "G",
"officeName": "Governor",
"party": "Oth",
"uncontested": true,
"national": true,
"reportingUnits": [
{
"statePostal": "VT",
"stateName": "Vermont",
"level": "state",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 0,
"precinctsTotal": 0,
"precinctsReportingPct": 0.0,
"candidates": [
{"first": "Pete", "last": "Diamondstone", "abbrv": "Dmndstn", "party": "Oth", "candidateID": "51981", "polID": "1157",
"ballotOrder": 1, "polNum": "48967", "voteCount": 0, "winner": "X"}]},
{
"statePostal": "VT",
"reportingunitName": "Addison",
"reportingunitID": "46001",
"level": "subunit",
"fipsCode": "50001",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 0,
"precinctsTotal": 0,
"precinctsReportingPct": 0.0,
"candidates": [
{"first": "Pete", "last": "Diamondstone", "abbrv": "Dmndstn", "party": "Oth", "candidateID": "51981", "polID": "1157",
"ballotOrder": 1, "polNum": "48967", "voteCount": 0, "winner": "X"}]},
{
"statePostal": "VT",
"reportingunitName": "Albany",
"reportingunitID": "46002",
"level": "subunit",
"fipsCode": "50019",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 0,
"precinctsTotal": 0,
"precinctsReportingPct": 0.0,
"candidates": [
{"first": "Pete", "last": "Diamondstone", "abbrv": "Dmndstn", "party": "Oth", "candidateID": "51981", "polID": "1157",
April 22, 2016
18
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
"ballotOrder": 1, "polNum": "48967", "voteCount": 0, "winner": "X"}]}]}],
...
"nextrequest": "https://api.ap.org/v2/elections/2014-08-26?statePostal=VT&officeID=G&format=json&level=ru
&minDateTime=2015-09-01T18%3a17%3a32.000Z"}
Results by FIPS Code
This example (in XML and JSON) shows results by FIPS code for the primary races for Governor in Vermont.
Since the level=fipscode parameter is specified in the request, the response includes results for both the
specified state (Vermont) and each of the county FIPS codes (city/town results aggregated to the county level in
this example since Vermont is a New England state).
XML
...
...
April 22, 2016
19
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
...
JSON
{
"electionDate": "2014-08-26",
"timestamp": "2015-09-02T14:29:18.281Z",
"races": [
{
"test": false,
"raceID": "46005",
"raceType": "Primary",
"raceTypeID": "D",
"officeID": "G",
"officeName": "Governor",
"party": "Dem",
"national": true,
"reportingUnits": [
{
"statePostal": "VT",
"stateName": "Vermont",
"level": "state",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 275,
"precinctsTotal": 275,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Peter", "last": "Shumlin", "party": "Dem", "incumbent": true, "candidateID": "51977", "polID": "45461",
"ballotOrder": 2, "polNum": "49003", "voteCount": 15292, "winner": "X"},
{"first": "Brooke", "last": "Paige", "party": "Dem", "candidateID": "51976", "polID": "62482", "ballotOrder": 1, "polNum":
"49570", "voteCount": 3229}]},
{
"statePostal": "VT",
"level": "FIPSCode",
"fipsCode": "50001",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 23,
"precinctsTotal": 23,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Peter", "last": "Shumlin", "party": "Dem", "incumbent": true, "candidateID": "51977", "polID": "45461",
"ballotOrder": 2, "polNum": "49003", "voteCount": 1020, "winner": "X"},
{"first": "Brooke", "last": "Paige", "party": "Dem", "candidateID": "51976", "polID": "62482", "ballotOrder": 1, "polNum":
"49570", "voteCount": 199}]},
{
"statePostal": "VT",
"level": "FIPSCode",
"fipsCode": "50019",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 20,
"precinctsTotal": 20,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Peter", "last": "Shumlin", "party": "Dem", "incumbent": true, "candidateID": "51977", "polID": "45461",
"ballotOrder": 2, "polNum": "49003", "voteCount": 371, "winner": "X"},
{"first": "Brooke", "last": "Paige", "party": "Dem", "candidateID": "51976", "polID": "62482", "ballotOrder": 1, "polNum":
"49570", "voteCount": 178}]}]},
...
{
"test": false,
"raceID": "46006",
"raceType": "Primary",
"raceTypeID": "R",
"officeID": "G",
"officeName": "Governor",
"party": "GOP",
"national": true,
April 22, 2016
20
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
"reportingUnits": [
{
"statePostal": "VT",
"stateName": "Vermont",
"level": "state",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 275,
"precinctsTotal": 275,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Scott", "last": "Milne", "party": "GOP", "candidateID": "52295", "polID": "64039", "ballotOrder": 2, "polNum":
"49776", "voteCount": 11491, "winner": "X"},
{"first": "Steve", "last": "Berry", "party": "GOP", "candidateID": "51978", "polID": "63906", "ballotOrder": 1, "polNum":
"49686", "voteCount": 1106},
{"first": "Emily", "last": "Peyton", "party": "GOP", "candidateID": "51980", "polID": "60894", "ballotOrder": 3, "polNum":
"49526", "voteCount": 1055}]},
{
"statePostal": "VT",
"level": "FIPSCode",
"fipsCode": "50001",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 23,
"precinctsTotal": 23,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Scott", "last": "Milne", "party": "GOP", "candidateID": "52295", "polID": "64039", "ballotOrder": 2, "polNum":
"49776", "voteCount": 661, "winner": "X"},
{"first": "Steve", "last": "Berry", "party": "GOP", "candidateID": "51978", "polID": "63906", "ballotOrder": 1, "polNum":
"49686", "voteCount": 37},
{"first": "Emily", "last": "Peyton", "party": "GOP", "candidateID": "51980", "polID": "60894", "ballotOrder": 3, "polNum":
"49526", "voteCount": 52}]},
{
"statePostal": "VT",
"level": "FIPSCode",
"fipsCode": "50019",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 20,
"precinctsTotal": 20,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Scott", "last": "Milne", "party": "GOP", "candidateID": "52295", "polID": "64039", "ballotOrder": 2, "polNum":
"49776", "voteCount": 1156, "winner": "X"},
{"first": "Steve", "last": "Berry", "party": "GOP", "candidateID": "51978", "polID": "63906", "ballotOrder": 1, "polNum":
"49686", "voteCount": 124},
{"first": "Emily", "last": "Peyton", "party": "GOP", "candidateID": "51980", "polID": "60894", "ballotOrder": 3, "polNum":
"49526", "voteCount": 133}]}]},
...
{
"test": false,
"raceID": "46683",
"raceType": "Primary",
"raceTypeID": "0",
"officeID": "G",
"officeName": "Governor",
"party": "Oth",
"uncontested": true,
"national": true,
"reportingUnits": [
{
"statePostal": "VT",
"stateName": "Vermont",
"level": "state",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 0,
"precinctsTotal": 0,
"precinctsReportingPct": 0.0,
"candidates": [
{"first": "Pete", "last": "Diamondstone", "abbrv": "Dmndstn", "party": "Oth", "candidateID": "51981", "polID": "1157",
"ballotOrder": 1, "polNum": "48967", "voteCount": 0, "winner": "X"}]},
{
"statePostal": "VT",
"level": "FIPSCode",
"fipsCode": "50001",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 0,
"precinctsTotal": 0,
"precinctsReportingPct": 0.0,
"candidates": [
April 22, 2016
21
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
{
{"first": "Pete", "last": "Diamondstone", "abbrv": "Dmndstn", "party": "Oth", "candidateID": "51981", "polID": "1157",
"ballotOrder": 1, "polNum": "48967", "voteCount": 0, "winner": "X"}]},
"statePostal": "VT",
"level": "FIPSCode",
"fipsCode": "50019",
"lastUpdated": "2015-09-01T18:17:32Z",
"precinctsReporting": 0,
"precinctsTotal": 0,
"precinctsReportingPct": 0.0,
"candidates": [
{"first": "Pete", "last": "Diamondstone", "abbrv": "Dmndstn", "party": "Oth", "candidateID": "51981", "polID": "1157",
"ballotOrder": 1, "polNum": "48967", "voteCount": 0, "winner": "X"}]}]}],
...
"nextrequest": "https://api.ap.org/v2/elections/2014-0826?statePostal=VT&officeID=G&format=json&level=fipscode&minDateTime=2015-09-01T18%3a17%3a32.000Z"}
Results by District During Presidential Primaries
This example (in XML and JSON) shows results by district (including the delegate count for each candidate if
applicable) for the Democrat and Republican presidential primary races in West Virginia.
XML
...
JSON
{
"electionDate": "2012-05-08",
"timestamp": "2015-09-01T16:52:48.276Z",
"races": [
{
"test": true,
"raceID": "49001",
"raceType": "Primary",
"raceTypeID": "D",
"officeID": "P",
"officeName": "President",
"party": "Dem",
"national": true,
"reportingUnits": [
{
"statePostal": "WV",
"stateName": "West Virginia",
"level": "state",
"lastUpdated": "2015-08-26T18:25:35Z",
"precinctsReporting": 1846,
"precinctsTotal": 1846,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Barack", "last": "Obama", "party": "Dem", "incumbent": true, "candidateID": "55621", "polID": "1918",
"ballotOrder": 2, "polNum": "51722", "voteCount": 105833, "delegateCount": 0, "winner": "X"},
{"first": "Keith", "last": "Judd", "party": "Dem", "candidateID": "55622", "polID": "58194", "ballotOrder": 1, "polNum":
April 22, 2016
23
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
{
"52049", "voteCount": 72459, "delegateCount": 0}]},
{
"statePostal": "WV",
"reportingunitName": "At Large",
"reportingunitID": "49008",
"level": "district",
"lastUpdated": "2015-08-26T18:25:35Z",
"precinctsReporting": 1846,
"precinctsTotal": 1846,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Barack", "last": "Obama", "party": "Dem", "incumbent": true, "candidateID": "55621", "polID": "1918",
"ballotOrder": 2, "polNum": "51722", "voteCount": 105833, "delegateCount": 0, "winner": "X"},
{"first": "Keith", "last": "Judd", "party": "Dem", "candidateID": "55622", "polID": "58194", "ballotOrder": 1, "polNum":
"52049", "voteCount": 72459, "delegateCount": 0}]}]},
"test": true,
"raceID": "49002",
"raceType": "Primary",
"raceTypeID": "R",
"officeID": "P",
"officeName": "President",
"party": "GOP",
"national": true,
"reportingUnits": [
{
"statePostal": "WV",
"stateName": "West Virginia",
"level": "state",
"lastUpdated": "2015-08-26T18:25:35Z",
"precinctsReporting": 1846,
"precinctsTotal": 1846,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Newt", "last": "Gingrich", "party": "GOP", "candidateID": "55623", "polID": "12094", "ballotOrder": 1, "polNum":
"52050", "voteCount": 6986, "delegateCount": "0"},
{"first": "Ron", "last": "Paul", "party": "GOP", "candidateID": "55624", "polID": "302", "ballotOrder": 2, "polNum":
"52052", "voteCount": 12263, "delegateCount": "0"},
{"first": "Mitt", "last": "Romney", "party": "GOP", "candidateID": "55626", "polID": "893", "ballotOrder": 4, "polNum":
"52054", "voteCount": 77477, "delegateCount": "21", "winner": "X"},
{"first": "Rick", "last": "Santorum", "abbrv": "Santorm", "party": "GOP", "candidateID": "55628", "polID": "1752",
"ballotOrder": 5, "polNum": "52055", "voteCount": 13408, "delegateCount": "2"},
{"first": "Buddy", "last": "Roemer", "party": "GOP", "candidateID": "55625", "polID": "22007", "ballotOrder": 3, "polNum":
"52053", "voteCount": 1129, "delegateCount": "0"},
{"first": "No Votes", "last": "Uncommitted", "abbrv": "Uncmmt", "party": "GOP", "candidateID": "55990", "polID":
"100004", "ballotOrder": 6, "polNum": "52394", "voteCount": 0, "delegateCount": "5"}]},
{
"statePostal": "WV",
"reportingunitName": "At Large",
"reportingunitID": "49008",
"level": "district",
"lastUpdated": "2015-08-26T18:25:35Z",
"precinctsReporting": 1846,
"precinctsTotal": 1846,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Newt", "last": "Gingrich", "party": "GOP", "candidateID": "55623", "polID": "12094", "ballotOrder": 1, "polNum":
"52050", "voteCount": 6986, "delegateCount": "0"},
{"first": "Ron", "last": "Paul", "party": "GOP", "candidateID": "55624", "polID": "302", "ballotOrder": 2, "polNum":
"52052", "voteCount": 12263, "delegateCount": "0"},
{"first": "Mitt", "last": "Romney", "party": "GOP", "candidateID": "55626", "polID": "893", "ballotOrder": 4, "polNum":
"52054", "voteCount": 77477, "delegateCount": "15", "winner": "X"},
{"first": "Rick", "last": "Santorum", "abbrv": "Santorm", "party": "GOP", "candidateID": "55628", "polID": "1752",
"ballotOrder": 5, "polNum": "52055", "voteCount": 13408, "delegateCount": "2"},
{"first": "Buddy", "last": "Roemer", "party": "GOP", "candidateID": "55625", "polID": "22007", "ballotOrder": 3, "polNum":
"52053", "voteCount": 1129, "delegateCount": "0"},
{"first": "No Votes", "last": "Uncommitted", "abbrv": "Uncmmt", "party": "GOP", "candidateID": "55990", "ballotOrder": 6,
"polID": "100004", "polNum": "52394", "voteCount": 0, "delegateCount": "2"}]},
{
"statePostal": "WV",
"reportingunitName": "District 1",
"reportingunitID": "49010",
"level": "district",
"districtType": "CD",
"lastUpdated": "2015-08-26T18:25:35Z",
"precinctsReporting": 649,
"precinctsTotal": 649,
April 22, 2016
24
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
{
{
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Newt", "last": "Gingrich", "party": "GOP", "candidateID": "55623", "polID": "12094", "ballotOrder": 1, "polNum":
"52050", "voteCount": 2785, "delegateCount": "0"},
{"first": "Ron", "last": "Paul", "party": "GOP", "candidateID": "55624", "polID": "302", "ballotOrder": 2, "polNum":
"52052", "voteCount": 4689, "delegateCount": "0"},
{"first": "Mitt", "last": "Romney", "party": "GOP", "candidateID": "55626", "polID": "893", "ballotOrder": 4, "polNum":
"52054", "voteCount": 30138, "delegateCount": "2", "winner": "X"},
{"first": "Rick", "last": "Santorum", "abbrv": "Santorm", "party": "GOP", "candidateID": "55628", "polID": "1752",
"ballotOrder": 5, "polNum": "52055", "voteCount": 5347, "delegateCount": "0"},
{"first": "Buddy", "last": "Roemer", "party": "GOP", "candidateID": "55625", "polID": "22007", "ballotOrder": 3, "polNum":
"52053", "voteCount": 423, "delegateCount": "0"},
{"first": "No Votes", "last": "Uncommitted", "abbrv": "Uncmmt", "party": "GOP", "candidateID": "55990", "polID":
"100004", "ballotOrder": 6, "polNum": "52394", "voteCount": 0, "delegateCount": "1"}]},
"statePostal": "WV",
"reportingunitName": "District 2",
"reportingunitID": "49011",
"level": "district",
"districtType": "CD",
"lastUpdated": "2015-08-26T18:25:35Z",
"precinctsReporting": 557,
"precinctsTotal": 557,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Newt", "last": "Gingrich", "party": "GOP", "candidateID": "55623", "polID": "12094", "ballotOrder": 1, "polNum":
"52050", "voteCount": 2424, "delegateCount": "0"},
{"first": "Ron", "last": "Paul", "party": "GOP", "candidateID": "55624", "polID": "302", "ballotOrder": 2, "polNum":
"52052", "voteCount": 4874, "delegateCount": "0"},
{"first": "Mitt", "last": "Romney", "party": "GOP", "candidateID": "55626", "polID": "893", "ballotOrder": 4, "polNum":
"52054", "voteCount": 29316, "delegateCount": "2", "winner": "X"},
{"first": "Rick", "last": "Santorum", "abbrv": "Santorm", "party": "GOP", "candidateID": "55628", "polID": "1752",
"ballotOrder": 5, "polNum": "52055", "voteCount": 4853, "delegateCount": "0"},
{"first": "Buddy", "last": "Roemer", "party": "GOP", "candidateID": "55625", "polID": "22007", "ballotOrder": 3, "polNum":
"52053", "voteCount": 418, "delegateCount": "0"},
{"first": "No Votes", "last": "Uncommitted", "abbrv": "Uncmmt", "party": "GOP", "candidateID": "55990", "polID":
"100004", "ballotOrder": 6, "polNum": "52394", "voteCount": 0, "delegateCount": "1"}]},
"statePostal": "WV",
"reportingunitName": "District 3",
"reportingunitID": "49012",
"level": "district",
"districtType": "CD",
"lastUpdated": "2015-08-26T18:25:35Z",
"precinctsReporting": 640,
"precinctsTotal": 640,
"precinctsReportingPct": 100.0,
"candidates": [
{"first": "Newt", "last": "Gingrich", "party": "GOP", "candidateID": "55623", "polID": "12094", "ballotOrder": 1, "polNum":
"52050", "voteCount": 1777, "delegateCount": "0"},
{"first": "Ron", "last": "Paul", "party": "GOP", "candidateID": "55624", "polID": "302", "ballotOrder": 2, "polNum":
"52052", "voteCount": 2700, "delegateCount": "0"},
{"first": "Mitt", "last": "Romney", "party": "GOP", "candidateID": "55626", "polID": "893", "ballotOrder": 4, "polNum":
"52054", "voteCount": 18023, "delegateCount": "2", "winner": "X"},
{"first": "Rick", "last": "Santorum", "abbrv": "Santorm", "party": "GOP", "candidateID": "55628", "polID": "1752",
"ballotOrder": 5, "polNum": "52055", "voteCount": 3208, "delegateCount": "0"},
{"first": "Buddy", "last": "Roemer", "party": "GOP", "candidateID": "55625", "polID": "22007", "ballotOrder": 3, "polNum":
"52053", "voteCount": 288, "delegateCount": "0"},
{"first": "No Votes", "last": "Uncommitted", "abbrv": "Uncmmt", "party": "GOP", "candidateID": "55990", "polID":
"100004", "ballotOrder": 6, "polNum": "52394", "voteCount": 0, "delegateCount": "1"}]}]}],
"nextrequest": "https://api.ap.org/v2/elections/2012-05-08?statePostal=WV&level=district&test=true&format=json
&minDateTime=2015-08-26T18%3a25%3a35.000Z"}
Presidential Results and Electoral Counts - National and State-by-State
This example shows presidential popular votes and electoral counts for the state of New Jersey and U.S. national
rolled-up summary popular vote and electoral count results at the default level=state. "ElectTotal" indicates the
state or U.S. national electoral count, and "ElectWon" shows the candidate’s electoral votes. Only four candidates
are shown at the U.S. national level for illustration purposes; however, the actual response will include every
presidential candidate across the country, even if they are on the ballot in one state.
Note: When level=ru or level=fipscode is specified in the request, electoral counts (both the state
electoral count and the candidates’ electoral votes) are added to the state results summary returned at the
top of these responses. Only presidential popular vote results are available for the lower-level reporting
units (counties or cities/towns for the New England states for level=ru or FIPS codes for level=fipscode).
April 22, 2016
25
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
XML
...
JSON
{
"electionDate": "2012-11-06",
"timestamp": "2016-04-06T14:20:52.453Z",
"races": [
{
"test": true,
"raceID": "0",
"raceType": "General",
"raceTypeID": "G",
"officeID": "P",
"officeName": "President",
"national": true,
"reportingUnits": [
{
"statePostal": "US",
"stateName": "Unites States",
"level": "national",
"electTotal": 538,
"lastUpdated": "2016-04-06T14:20:52.453Z",
"precinctsReporting": 172307,
"precinctsTotal": 174047,
"precinctsReportingPct": 99.0,
"candidates": [
{"first": "Barack", "last": "Obama", "party": "Dem", "incumbent": true, "candidateID": "6017", "polID": "1918",
"ballotOrder": 2, "polNum": "3987", "voteCount": 62615406, "electWon": 332, "winner": "X"},
{"first": "Mitt", "last": "Romney", "party": "GOP", "candidateID": "6018", "polID": "893", "ballotOrder": 3, "polNum": "3978",
"voteCount": 59142004, "electWon": 206},
April 22, 2016
26
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
{
{"first": "Gary", "last": "Johnson", "party": "Lib", "candidateID": "6028", "polID": "31708", "ballotOrder": 1, "polNum":
"4137", "voteCount": 1211982, "electWon": 0},
{"first": "Jill", "last": "Stein", "party": "Grn", "candidateID": "6148", "polID": "895", "ballotOrder": 4, "polNum": "4181",
"voteCount": 431719, "electWon": 0}]},
"statePostal": "NJ",
"stateName": "New Jersey",
"level": "state",
"electTotal": 14,
"lastUpdated": "2016-03-28T22:11:17.847Z",
"precinctsReporting": 6271,
"precinctsTotal": 6338,
"precinctsReportingPct": 98.94,
"candidates": [
{"first": "Barack", "last": "Obama", "party": "Dem", "incumbent": true, "candidateID": "37673", "polID": "1918",
"ballotOrder": 1, "polNum": "34212", "voteCount": 1924329, "electWon": 14, "winner": "X"},
{"first": "Mitt", "last": "Romney", "party": "GOP", "candidateID": "37680", "polID": "893", "ballotOrder": 2, "polNum":
"34497", "voteCount": 1361154, "electWon": 0},
{"first": "Gary", "last": "Johnson", "party": "Lib", "candidateID": "37825", "polID": "31708", "ballotOrder": 7, "polNum":
"34557", "voteCount": 19260, "electWon": 0},
{"first": "Jill", "last": "Stein", "party": "Grn", "candidateID": "37827", "polID": "895", "ballotOrder": 10, "polNum": "34559",
"voteCount": 8926, "electWon": 0},
{"first": "Virgil", "last": "Goode", "party": "CST", "candidateID": "37822", "polID": "713", "ballotOrder": 5, "polNum":
"34554", "voteCount": 1877, "electWon": 0},
{"first": "Rocky", "last": "Anderson", "abbrv": "Andersn", "party": "JP", "candidateID": "37820", "polID": "43773",
"ballotOrder": 3, "polNum": "34553", "voteCount": 1546, "electWon": 0},
{"first": "Jeff", "last": "Boss", "party": "Ind", "candidateID": "37821", "polID": "59593", "ballotOrder": 4, "polNum": "34216",
"voteCount": 888, "electWon": 0},
{"first": "James", "last": "Harris", "party": "SWP", "candidateID": "37824", "polID": "3486", "ballotOrder": 6, "polNum":
"34556", "voteCount": 654, "electWon": 0},
{"first": "Merlin", "last": "Miller", "party": "ATP", "candidateID": "37826", "polID": "62536", "ballotOrder": 9, "polNum":
"34558", "voteCount": 609, "electWon": 0},
{"first": "Peta", "last": "Lindsay", "party": "PSL", "candidateID": "37823", "polID": "62562", "ballotOrder": 8, "polNum":
"34555", "voteCount": 441, "electWon": 0}]}]}],
"nextrequest": "https://api.ap.org/v2/elections/2012-11-06?statepostal=NJ%2cUS&officeid=P&test=true&format=json
&minDateTime=2016-03-28T22%3a11%3a17.847Z"}
Presidential Results and Electoral Counts by District
This example shows presidential popular votes and electoral counts by district for the presidential election in
Maine, a state that awards presidential electoral votes using the district-based method instead of the “WinnerTake-All” method. The district-based method is currently used in Maine and Nebraska.
In the response, "ElectTotal" shows the district or state electoral count, and "ElectWon" shows the candidate’s
electoral votes. The 2012 data shown in this example are test data used for illustration purposes only.
XML
April 22, 2016
27
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
JSON
{
"electionDate": "2012-11-06",
"timestamp": "2016-04-08T16:44:49.595Z",
"races": [
{
"test": true,
"raceID": "0",
"raceType": "General",
"raceTypeID": "G",
"officeID": "P",
"officeName": "President",
"national": true,
"reportingUnits": [
{
"statePostal": "ME",
"stateName": "Maine",
"level": "state",
"electTotal": 4,
"lastUpdated": "2016-03-28T22:11:55.557Z",
"precinctsReporting": 538,
"precinctsTotal": 599,
"precinctsReportingPct": 89.82,
"candidates": [
{"first": "Barack", "last": "Obama", "party": "Dem", "incumbent": true, "candidateID": "28154", "polID": "1918",
"ballotOrder": 2, "polNum": "25228", "voteCount": 373936, "electWon": 4, "winner": "X"},
{"first": "Mitt", "last": "Romney", "party": "GOP", "candidateID": "28155", "polID": "893", "ballotOrder": 3, "polNum":
"25229", "voteCount": 272106, "electWon": 0},
{"first": "Gary", "last": "Johnson", "party": "Lib", "candidateID": "28577", "polID": "31708", "ballotOrder": 1, "polNum":
"25275", "voteCount": 12819, "electWon": 0},
{"first": "Jill", "last": "Stein", "party": "Grn", "candidateID": "28578", "polID": "895", "ballotOrder": 4, "polNum": "25276",
"voteCount": 8527, "electWon": 0}]},
{
"statePostal": "ME",
"reportingunitName": "At Large",
"reportingunitID": "20005",
"level": "district",
"districtType": "AtLarge",
"electTotal": 2,
"lastUpdated": "2016-03-28T22:11:55.557Z",
"precinctsReporting": 538,
"precinctsTotal": 599,
"precinctsReportingPct": 89.82,
"candidates": [
{"first": "Barack", "last": "Obama", "party": "Dem", "incumbent": true, "candidateID": "28154", "polID": "1918",
"ballotOrder": 2, "polNum": "25228", "voteCount": 373936, "electWon": 2, "winner": "X"},
{"first": "Mitt", "last": "Romney", "party": "GOP", "candidateID": "28155", "polID": "893", "ballotOrder": 3, "polNum":
"25229", "voteCount": 272106, "electWon": 0},
{"first": "Gary", "last": "Johnson", "party": "Lib", "candidateID": "28577", "polID": "31708", "ballotOrder": 1, "polNum":
"25275", "voteCount": 12819, "electWon": 0},
{"first": "Jill", "last": "Stein", "party": "Grn", "candidateID": "28578", "polID": "895", "ballotOrder": 4, "polNum": "25276",
April 22, 2016
28
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
{
{
"voteCount": 8527, "electWon": 0}]},
"statePostal": "ME",
"reportingunitName": "District 1",
"reportingunitID": "20026",
"level": "district",
"districtType": "CD",
"electTotal": 1,
"lastUpdated": "2016-03-28T22:11:55.557Z",
"precinctsReporting": 171,
"precinctsTotal": 175,
"precinctsReportingPct": 97.71,
"candidates": [
{"first": "Barack", "last": "Obama", "party": "Dem", "incumbent": true, "candidateID": "28154", "polID": "1918",
"ballotOrder": 2, "polNum": "25228", "voteCount": 211977, "electWon": 1, "winner": "X"},
{"first": "Mitt", "last": "Romney", "party": "GOP", "candidateID": "28155", "polID": "893", "ballotOrder": 3, "polNum":
"25229", "voteCount": 136051, "electWon": 0},
{"first": "Gary", "last": "Johnson", "party": "Lib", "candidateID": "28577", "polID": "31708", "ballotOrder": 1, "polNum":
"25275", "voteCount": 8438, "electWon": 0},
{"first": "Jill", "last": "Stein", "party": "Grn", "candidateID": "28578", "polID": "895", "ballotOrder": 4, "polNum": "25276",
"voteCount": 4822, "electWon": 0}]},
"statePostal": "ME",
"reportingunitName": "District 2",
"reportingunitID": "20027",
"level": "district",
"districtType": "CD",
"electTotal": 1,
"lastUpdated": "2016-03-28T22:11:55.557Z",
"precinctsReporting": 367,
"precinctsTotal": 424,
"precinctsReportingPct": 86.56,
"candidates": [
{"first": "Barack", "last": "Obama", "party": "Dem", "incumbent": true, "candidateID": "28154", "polID": "1918",
"ballotOrder": 2, "polNum": "25228", "voteCount": 161959, "electWon": 1, "winner": "X"},
{"first": "Mitt", "last": "Romney", "party": "GOP", "candidateID": "28155", "polID": "893", "ballotOrder": 3, "polNum":
"25229", "voteCount": 136055, "electWon": 0},
{"first": "Gary", "last": "Johnson", "party": "Lib", "candidateID": "28577", "polID": "31708", "ballotOrder": 1, "polNum":
"25275", "voteCount": 4381, "electWon": 0},
{"first": "Jill", "last": "Stein", "party": "Grn", "candidateID": "28578", "polID": "895", "ballotOrder": 4, "polNum": "25276",
"voteCount": 3705, "electWon": 0}]}]}],
"nextrequest": "https://api.ap.org/v2/elections/2012-11-06?statePostal=ME&officeID=P&level=district&test=true&format=json
&minDateTime=2016-04-08T16%3a44%3a49.595Z"}
Requesting Updates - No Changes since the Previous Request
It is strongly recommended to request updates using the returned link to make the next request (for more
information, see "Recommended Practices" on page 4); for example:
https://api.ap.org/v2/elections/2012-05-08?statePostal=WV&level=district&test=true&minDateTime=2015
-09-01T17%3a14%3a04.973Z
If there have been no updates since your previous request, the response contains only the link for the next
request. Examples are shown below.
XML
JSON
{
"electionDate": "2012-05-08",
"timestamp": "2015-09-01T17:14:34.000Z",
"races": [ ],
"nextrequest": "https://api.ap.org/v2/elections/2012-05-08?statePostal=WV&level=district&test=true&format=json
&minDateTime=2015-09-01T17%3a14%3a04.973Z"
}
April 22, 2016
29
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
ELECTION REPORTS
DESCRIPTION
Returns election reports, including delegate reports for presidential primaries, presidential vote and electoral
count reports for the general election in a presidential year, and national party balance of power/trends for
Governors, U.S. Senate and U.S. House for the general election.
Note: For more information about the data delivered in the election reports, refer to the AP Elections
Online (APEO) FTP Services guide.
Important: To request election report updates, use the 'next request' links (see "Using the Returned
Link for the Next Request" on page 4). The list of reports returned when you submit a new search request
for reports using optional filtering parameters always includes links to the latest available versions of the
reports. If a new version of the report arrives, there will be a different direct link to this new version. Do
not follow stored direct links to reports because these reports may already be outdated. To monitor for
new versions of the reports, always submit a new search request using the 'next request' link.
REQUEST
METHOD
GET
REQUEST URI
https://api.ap.org/{version}/reports?apiKey={apiKey}[{OptionalParameters}]
Important: The request URI must be URL-encoded.
Request URI Parameters
Required Parameter
PARAMETER
version
DESCRIPTION
The API version. Currently, the only valid value is v2.
EXAMPLE
v2
Optional Parameters
PARAMETER
test
electionDate
geo
format
type
(continued
on next
page)
April 22, 2016
DESCRIPTION
Indicates whether to return live or test elections data. Possible values are:
− false (live data; this is the default)
− true (test data)
Important: To receive test data, make sure to add the optional test=true
parameter to the request URL.
Date of the election in the YYYY-MM-DD format.
The geo code, such as a two-character state postal code or "US" for national
reports ("US" is the only valid value for delegate, presidential and trends reports).
The response format (xml or json). If no format is specified as the format
parameter value or in the Accept header, XML is returned. The format parameter
value takes precedence over the Accept header value when both are specified.
The report type. Multiple values must be separated by commas. Examples of
possible values are:
− delegates. Returns delegate reports for presidential primaries.
− pres. For the general election in a presidential year, returns presidential
popular votes and electoral count at the state and U.S. national rolled-up
summary levels.
− trend. For the general election, returns national party balance of power/trends
for Governors, U.S. Senate and U.S. House. These reports show a party
breakdown if the present trends in the vote count continue in the races for
Governors, U.S. Senate and U.S. House.
EXAMPLE
true
2012-04-24
US
json
delegates
30
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
PARAMETER
type
(continued)
subtype
DESCRIPTION
EXAMPLE
For more information, see the subtype parameter below.
Tip: You can find possible report type values in the Election Reports method
response: in the category/@term value (XML) or the categories.term value
(JSON) when the scheme value is "https://api.ap.org/cv/type/".
The report subtype. Multiple values must be separated by commas.
Important: This parameter must be used in conjunction with the type
parameter.
Delegate Reports
Examples of possible values for delegate reports are as follows (they must be used
in conjunction with the type=delegates parameter):
− delsum. The current summary delegate total for each candidate across the
country as well as the change in the past 24 hours, past week and past month.
− delstate. The current delegate total for each candidate in each state and at the
national level as well as the change in the past 24 hours.
− delsuper. The current delegate and unpledged delegate totals for each
candidate in each state and at the national level (note that anonymous
unpledged delegates are not counted at the state level).
Presidential Vote and Electoral Count Reports
Examples of possible values for the presidential reports are as follows (they must
be used in conjunction with the type=presidential parameter):
− statebystate_pres. Presidential state-by-state popular vote results and
electoral count for all candidates (major and minor candidates).
− pres_summary. Presidential U.S. national rolled-up popular vote results and
electoral count for the top major candidates and minor candidates, who are
grouped under "Others."
− pres_summary_all. Presidential U.S. national rolled-up popular vote results
and electoral count for all candidates (major and minor candidates).
National Party Balance of Power/Trends Reports
Examples of possible values for trends reports are as follows (they must be used in
conjunction with the type=trends parameter):
− g. Governors trends report.
− s. U.S. Senate trends report.
− h. U.S. House trends report.
Note: For more information about the delegate reports for presidential
primaries, presidential reports and national party balance of power/trends
reports, refer to the AP Elections Online (APEO) FTP Services guide.
Tip: You can find other possible report subtype values in the Election
Reports method response: in the category/@term value (XML) or the
categories.term value (JSON) when the scheme value is
delsum
"https://api.ap.org/cv/subtype/".
Request Headers (Optional)
HEADER
Accept
Accept-Encoding
April 22, 2016
DESCRIPTION
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.
Compresses the response to the gzip format.
EXAMPLE
application/json
gzip
31
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
Request URI Examples
SAMPLE URI
https://api.ap.org/v2/reports?apiKey={apiKey}
https://api.ap.org/v2/reports?apiKey={apiKey}
&electionDate=2015-03-14
https://api.ap.org/v2/reports?apiKey={apiKey}&type=
delegates&subtype=delsum&electionDate=2015-03-14
RETURNED RESULTS
All the latest reports currently available to you.
All the latest available reports from the 03-14-2015
election date.
All the latest available summary delegate reports
from the 03-14-2015 election date.
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 reports for the specified filtering parameters (for example, election date or
report type). For information about error codes, see "Error Codes" on page 36.
Metadata Elements
The following elements describe the response:
XML ELEMENT
id
JSON PROPERTY
"id"
link
"nextrequest"
@rel="next"
@href
title
updated
"title"
"updated"
author
name
uri
rights
DESCRIPTION
The URL for the list of reports.
Indicates a link for the next request that must be used to request data newer
than the data in the previously returned response.
The specific URL for the next request.
The response name.
The date and time (in W3C XML Schema’s xs:dateTime format) when the
response was returned.
Contains the response source.
The name of the organization that provided the response.
The website of the organization that provided the response.
Copyright line for the response.
The following elements are returned for each report:
XML ELEMENT
entry
id
JSON PROPERTY
"reports"
"id"
title
updated
"title"
"updated"
published
category
"electionDate"
"categories"
@term
@scheme
April 22, 2016
"term"
"scheme"
DESCRIPTION
Contains the data and metadata associated with an individual report.
The report ID.
Note: If a new version of the report arrives, it will have a different ID.
The report name.
The date and time (in W3C XML Schema’s xs:dateTime format) when the
report was generated.
Date of the election day.
Contains one of the following report categories (if applicable):
− Report type
− Report subtype
− Live/test data indicator (false indicates live data; true indicates test data)
− The geo code, such as a two-character state postal code or "US" for
national reports
Multiple elements are returned in XML. In JSON, the
"categories" property contains all of the report categories.
A string that identifies the report category.
A URI for the vocabulary to which a term belongs.
32
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
XML ELEMENT
content
@type
@src
JSON PROPERTY
"contentLink"
"contentType"
DESCRIPTION
Contains the direct link to the report.
Important: If a new version of the report arrives, there will be a
different direct link to this new version. Do not follow stored direct
links to reports because these reports may already be outdated. To
monitor for new versions of the reports, always submit a new search
request using the 'next request' link. The returned report list always
includes links to the latest available versions of the reports.
− In XML: Indicates the MIME type of the content returned when the link
in the "src" attribute is followed (for example, "application/xml" for
XML).
− In JSON: Indicates the MIME type of the content returned when the
original report format is other than XML.
Note: Any report available in XML is also available in JSON. By
default, the XML version of the report is returned when you follow the
direct link to the report from the report list. To receive the JSON
version of the report, make sure to add the format=json parameter to
the report URL or specify application/json in the Accept header.
The specific URL to the report.
Examples
Live Data
The following example shows a list of sample reports for the 03-14-2015 election date in XML and JSON.
XML
https://api.ap.org/v2/reports
Election Reports
2015-03-14T18:30:02Z
The Associated Press
http://www.ap.org
Copyright 2012 The Associated Press. All rights reserved.
https://api.ap.org/v2/reports/44b7b12492594fe1a2e4bce4c685f30b
Delegates / delsum
2015-03-14T18:25:21Z
2015-03-14
https://api.ap.org/v2/reports/06e24b2e75234c1c84b33d6c43b55018
Delegates /delstate
2015-03-14T18:27:14Z
2015-03-14
https://api.ap.org/v2/reports/7e37fccaca0e4d8891eb55ca5eb0c0ed
Delegates / delsuper
2015-03-14T18:34:35Z
2015-03-14
April 22, 2016
33
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
JSON
{
}
"id": "https://api.ap.org/v2/reports",
"title": "Election Reports",
"updated": "2015-03-14T18:30:02Z",
"reports": [
{
"id": "https://api.ap.org/v2/reports/44b7b12492594fe1a2e4bce4c685f30b",
"title": "Delegates / delsum",
"updated": "2015-03-14T18:25:21Z",
"electionDate": "2015-03-14",
"categories": [
{"term": "Delegates", "scheme": "https://api.ap.org/cv/type/"},
{"term": "delsum", "scheme": "https://api.ap.org/cv/subtype/"},
{"term": "false", "scheme": "https://api.ap.org/cv/test/"}],
"contentLink": "https://api.ap.org/v2/reports/44b7b12492594fe1a2e4bce4c685f30b",
"contentType": "application/xml"},
{
"id": "https://api.ap.org/v2/reports/06e24b2e75234c1c84b33d6c43b55018",
"title": "Delegates / delstate",
"updated": "2015-03-14T18:27:14Z",
"electionDate": "2015-03-14",
"categories": [
{"term": "Delegates", "scheme": "https://api.ap.org/cv/type/"},
{"term": "delstate", "scheme": "https://api.ap.org/cv/subtype/"},
{"term": "false", "scheme": "https://api.ap.org/cv/test/"}],
"contentLink": "https://api.ap.org/v2/reports/06e24b2e75234c1c84b33d6c43b55018",
"contentType": "application/xml"},
{
"id": "https://api.ap.org/v2/reports/7e37fccaca0e4d8891eb55ca5eb0c0ed",
"title": "Delegates / delsuper",
"updated": "2015-03-14T18:34:35Z",
"categories": [
{"term": "Delegates", "scheme": "https://api.ap.org/cv/type/"},
{"term": "delsuper", "scheme": "https://api.ap.org/cv/subtype/"},
{"term": "false", "scheme": "https://api.ap.org/cv/test/"}],
"contentLink": "https://api.ap.org/v2/reports/7e37fccaca0e4d8891eb55ca5eb0c0ed",
"contentType": "application/xml"}],
"nextrequest": "https://api.ap.org/v2/reports?2015-03-14&minDateTime=2015-05-05T10%3a34%3a44.000Z"
Test Data
The following example shows the list of sample reports from the previous example when the test=true
parameter was specified in the request.
XML
https://api.ap.org/v2/reports
Election Reports
2015-03-14T18:30:02Z
The Associated Press
http://www.ap.org
Copyright 2012 The Associated Press. All rights reserved.
https://api.ap.org/v2/reports/44b7b12492594fe1a2e4bce4c685f30b
Delegates / delsum / test
2015-03-14T18:25:21Z
2015-03-14
https://api.ap.org/v2/reports/06e24b2e75234c1c84b33d6c43b55018
Delegates / delstate / test
2015-03-14T18:27:14Z
2015-03-14
April 22, 2016
34
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
https://api.ap.org/v2/reports/7e37fccaca0e4d8891eb55ca5eb0c0ed
Delegates / delsuper / test
2015-03-14T18:34:35Z
2015-03-14
JSON
{
}
"id": "https://api.ap.org/v2/reports",
"title": "Election Reports",
"updated": "2015-03-14T18:30:02Z",
"reports": [
{
"id": "https://api.ap.org/v2/reports/44b7b12492594fe1a2e4bce4c685f30b",
"title": "Delegates / delsum / test",
"updated": "2015-03-14T18:25:21Z",
"electionDate": "2015-03-14",
"categories": [
{"term": "Delegates", "scheme": "https://api.ap.org/cv/type/"},
{"term": "delsum", "scheme": "https://api.ap.org/cv/subtype/"},
{"term": "true", "scheme": "https://api.ap.org/cv/test/"}],
"contentLink": "https://api.ap.org/v2/reports/44b7b12492594fe1a2e4bce4c685f30b",
"contentType": "application/xml"},
{
"id": "https://api.ap.org/v2/reports/06e24b2e75234c1c84b33d6c43b55018",
"title": "Delegates / delstate / test",
"updated": "2015-03-14T18:27:14Z",
"electionDate": "2015-03-14",
"categories": [
{"term": "Delegates", "scheme": "https://api.ap.org/cv/type/"},
{"term": "delstate", "scheme": "https://api.ap.org/cv/subtype/"},
{"term": "true", "scheme": "https://api.ap.org/cv/test/"}],
"contentLink": "https://api.ap.org/v2/reports/06e24b2e75234c1c84b33d6c43b55018",
"contentType": "application/xml"},
{
"id": "https://api.ap.org/v2/reports/7e37fccaca0e4d8891eb55ca5eb0c0ed",
"title": "Delegates / delsuper / test",
"updated": "2015-03-14T18:34:35Z",
"categories": [
{"term": "Delegates", "scheme": "https://api.ap.org/cv/type/"},
{"term": "delsuper", "scheme": "https://api.ap.org/cv/subtype/"},
{"term": "true", "scheme": "https://api.ap.org/cv/test/"}],
"contentLink": "https://api.ap.org/v2/reports/7e37fccaca0e4d8891eb55ca5eb0c0ed",
"contentType": "application/xml"}],
"nextrequest": "https://api.ap.org/v2/reports?2015-03-14&minDateTime=2015-05-05T10%3a34%3a44.000Z"
April 22, 2016
35
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
APPENDIX
ERROR CODES
In addition to the standard HTTP error codes, the error response includes a message in XML or JSON
(depending on the format specified in the request); for example:
XML
400
Specified parameter(s) 'officeNum' is invalid
JSON
{
}
"errorCode": 400,
"errorMessage": "Specified parameter(s) 'officeNum' is invalid"
CODE
MESSAGE
400
Specified parameter(s) {ParameterName(s)} is invalid.
ACTION
Check the request syntax and parameters.
Invalid value for parameter {ParameterName}
{ParameterValue}.
When 'raceID' is specified, 'statePostal' is required,
and multiple 'statePostal' values are not allowed.
401
Invalid API Key
403
Per-minute Quota ({QuotaLimit}) Exceeded, try again
in a little bit.
405
Request method {MethodName} not supported
414
URI length exceeds 6000 characters
500
Internal Server Error
502
Bad Gateway
503
Service Unavailable
504
Gateway Timeout
Check the API key. If you have just received your key, wait for
a few hours and try again. If you are still getting an error,
contact APCustomerSupport@ap.org.
Wait for 5-10 seconds and try again. If you are still getting an
error, contact APCustomerSupport@ap.org.
Check the request method. Currently, GET is the only
supported HTTP method for AP Elections API requests.
Make sure that your request is no longer than 6,000
characters.
Contact APCustomerSupport@ap.org.
OFFICE ID EXAMPLES
Office IDs Unique Across All States
These Office IDs are unique at the
national level (across all states):
State-Specific Office IDs
These are examples only and may vary from state to state (for example, "L" may
be associated with "Lieutenant Governor" in one state and "City Comptroller" in
another state). These IDs are only unique within a state for a given election date.
ID
NAME
G
Governor
U.S. House
Amendment, Ballot Measure,
Initiative, Proposal, Proposition,
Referendum or Question
ID
NAME
A
President
U.S. Senate
State House, State Assembly,
General Assembly or House of
Delegates
J
State Senate
T
Attorney General
Controller or Comptroller
District Attorney
Education Commissioner or Supt Public Instruction
Insurance Commissioner
Lieutenant Governor
Mayor
City Council
Secretary of State
Treasurer
H
I
P
S
Y
Z
April 22, 2016
C
D
E
L
M
N
R
36
AP ELECTIONS API 2.1 DEVELOPER'S GUIDE
PARTY VALUE EXAMPLES
Note: This list is as of October 2015 and is subject to change.
PARTY ABBREVIATION
AME
AMR
AO
CON
CST
DEM
DCG
IGR
GRN
GRP
IND
IAP
IPH
INP
IP
LIB
LAB
LUN
MNT
MOD
NPD
NPA
NLP
NO
NP
PEC
PFP
PRG
PAG
GOP
RP
UST
UCZ
UNI
UNA
UTY
WF
YES
April 22, 2016
PARTY NAME
Americans Elect
American Party
All Others
Conservative
Constitution
Democrat
DC Statehood Green
Independent Green
Green
Grass Roots
Independent
Independent American
Independent Party Of Hawaii
Independence
Independent Party
Libertarian
Labor
Liberty Union
Mountain Party
Moderate
No Party Designation
No Party Affiliation
Natural Law
No
NON PARTISAN
Petitioning Candidate
Peace & Freedom
Progressive
Pacific Green
Republican
Reform
U.S. Taxpayers
United Citizens
United Independent
Unaffiliated
Unity
Working Families
Yes
37