Getting Started

ON THIS PAGE          HideON THIS PAGE          Show What is AP Elections API? API Keys Landing Page Typical Workflow Supported Protocol Conventions

What is AP Elections API?

AP Elections API (ELAPI) allows you to retrieve AP elections data using your own tools.

API Keys

An API key is the access key required for making API calls. If you have not received your API key, please contact AP Customer Support.

You can authorize your API request by specifying your API key in the x-api-key HTTP request header.

Landing Page

The Elections API landing page at https://api.ap.org/v3/elections provides:

• Links to the API documentation and resources.

• 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.

Typical Workflow

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.

1. 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 and updates in the races of interest; for example, all races in your state or Top-of-the-Ticket races in all states.

   1. Make an initial request for the election race information for all the races you are interested in. The response includes:

      • Reference information about each race and each candidate.

      • Vote counts and if applicable, delegate or electoral counts.

      • 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.

   2. Use the returned link to make the next request (for more information, see Best Practices). 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.

   For more information, see Elections.

2. Request election reports.
   Throughout the election, your application polls the API at regular intervals to retrieve election reports; for example, delegate tracking reports for presidential primaries. For more information, see Election Reports.
3. Request advance turnout data for presidential and midterm general elections.
   Throughout the election, your application polls the API at regular intervals to retrieve state-by-state data on advance voting, including how many absentee ballots have been requested, sent and returned, demographic data, in-person voting data and historical data comparisons. For more information, see Advance Turnout.
4. Request delegate allocation data for presidential primaries.
   During the presidential primaries, your application polls the API to retrieve the delegate allocation data for Democrats, Republicans or both. For more information, see Delegates.

Supported Protocol

HTTPS with TLS 1.2 or 1.3 is supported for all API calls.

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.