Receiving Election Updates

 

ON THIS PAGE      Show

 

 

 

 

 

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

 

 

 

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

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.

 

 

 

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.

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.

  • In v3, the latest version of each report is always available at the same URL.

  • In v2, there is a different direct link to each new version of a report. If you are using v2, do not follow stored direct links to reports because these reports may already be outdated. To monitor for new versions of the reports in v2, always submit a new search request using the 'next request' link.