Optimizing Elections API Requests

ON THIS PAGE          HideON THIS PAGE          Show Always Use the Next Request Link  Use a Reasonable Polling Interval  Limit Each Request to the Data You Need  Request One State at a Time  Request Only the Required Reporting Level  Request Live and Certified Results with One Call  Request Vote Types Only When Needed  Filter the Races in the Response Reduce Candidate Data  Recommended Request Checklist

 

Use narrowly scoped requests to request only the data your application needs. Smaller responses are processed and returned more quickly, reducing bandwidth and helping your application handle election updates efficiently. 

Always Use the Next Request Link 

Make one initial request for the races you need. For every subsequent update, use the "nextrequest" URL returned in the JSON response or the link with rel="next" returned in the XML response. 

The next request link returns a payload only containing races with vote, race call or candidate information changes since the preceding request. When no data has changed, the response contains only the next request link.

 

Important
Store and use each newly returned next request link. Do not reconstruct the URL or continue using the previous link.

 

For more information, see Receiving Election Updates. 

Use a Reasonable Polling Interval 

The appropriate request frequency depends on your application’s requirements. However, AP does not recommend making requests more frequently than every few seconds.

Polling more frequently, such as every second or multiple times per second, is unlikely to deliver updates materially sooner than polling on a slightly longer cadence, such as every five seconds. After each polling interval, use the latest nextrequest URL returned by the API.

Limit Each Request to the Data You Need 

Request One State at a Time 

Ideally, specify one state in each request by using the statePostal parameter. If your application requires results from multiple states, make separate state-specific requests.

Many smaller requests are typically faster than one request containing multiple states. State-specific requests also produce smaller responses that are easier to process.

Request Only the Required Reporting Level 

Set level to the least granular value you require: 

• Use the default, level=state,  when you need only statewide race totals. 

• Use level=ru only when you need reporting-unit data, such as county or municipality results.

Reporting unit data can substantially increase the response size, particularly when several races or states are included.

Request Live and Certified Results with One Call 

Use resultsType=b to receive a mixture of live and certified results. Live results will be returned until certified results become available. 

Request Vote Types Only When Needed 

Do not specify votetypes=true unless your application uses votes broken down by type, such as electionDayInPerson, advanceInPerson and absenteeMail votes. 

The default, votetypes=false, returns the cumulative results without the additional vote by type data.

Filter the Races in the Response

Filtering Parameters

Use the available filtering parameters to request only relevant races.

 

Parameter	Recommended use
officeID	Limit results to specific office types. Common values include P for President, G for Governor, S for U.S. Senate and H for U.S. House.
raceTypeID	Limit results to specific race types. For example, use G for a general election or D for a Democratic primary.
raceID	Request only specific races. Because race IDs are unique only within a state, use raceID with a single statePostal value.
national	Use national=true when you need only races designated as being of national interest.
winner	Use winner=X when you need only races where a winner has been declared, such as when updating a called race feed or ticker. This can significantly reduce the response size.

Combining Filters 

Multiple compatible filters can be combined to narrow a request further; for example:

https://api.ap.org/v3/elections/{electionDate}?statePostal=PA&officeID=P,S,H&raceTypeID=G&level=state&resultsType=l&candidateInfo=brief&format=json 

After the initial response, use its returned next request link for all updates.

Reduce Candidate Data 

Use candidateInfo=brief when your application already stores candidate reference information and needs only candidate IDs, vote, delegate or electoral counts and winner indicators.

If a candidate’s reference information changes, a response obtained through the next request link identifies the update and returns the candidate’s full information even when candidateInfo=brief was requested.

Use candidateInfo=full only when your application needs all available candidate details.

Recommended Request Checklist 

Before sending an Elections API request, confirm that: 

• The request covers one state whenever possible. 

• The request includes only the required offices, race types or race IDs. 

• level requests no more geographic detail than necessary. 

• votetypes=true is included only when vote by type data is required.

• candidateInfo=brief is used when full candidate details are unnecessary. 

• Every update request uses the latest returned next request link.

• Requests are spaced at least five seconds apart.