Election Reports Response

 

ON THIS PAGE      Show

 

 

 

 

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

 

  Important

 

  • In v3, the latest version of each report is always available at the same URL. For more information, see Election Report Upgrades.

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

  • All election reports that were previously available in v2 are now also available in v3. New reports and updates to existing reports will be available in v3 only.

  • The Election Reports implementation in v2 has not changed, but it has been deprecated and will be removed in a future release. If you are using Election Reports in v2, we strongly urge you to make changes to your client application and switch to v3.

 

 

 

Response Elements

The following elements describe the response:

 

v3 XML

v2 XML

v3 JSON

v2 JSON

Description

Reports

feed

 

 

 

@ApiVersion

 

"apiVersion"

  

The API version number; for example, 3.1.

@ApiBuild

 

"apiBuild"

  

The API build number; for example, 3.1.104.

@Timestamp

updated

"timestamp"

"updated"

The date and time (in W3C XML Schema’s xs:dateTime format) when the response was returned.

@ID

id

"id"

"id"

The URL for the list of reports.

@Title

title

"title"

"title"

The response name.
 

author

    

Contains the response source.

name

    

The name of the organization that provided the response.

uri

    

The website of the organization that provided the response.

rights

    

Copyright line for the response.

link

link

"nextrequest"

"nextrequest"

Indicates a link for the next request that must be used to request data newer than the data in the previously returned response.

@rel="next"

@rel="next"

@href

@href

 

 

The specific URL for the next request.

The following elements are returned for each report:

 

v3 XML

v2 XML

v3 JSON

v2 JSON

Description

Report

entry

"reports"

"reports"

Contains the data and metadata associated with an individual report.

ID

id

"id"

"id"

The report ID. In v3, all versions of the same report will have the same ID.

  Note for v2 users

 

If a new version of the report arrives, it will have a different ID.

 

 

 

Title

title

"title"

"title"

The report name.

LastUpdated

updated

"lastUpdated"

"updated"

The date and time (in W3C XML Schema’s xs:dateTime format) when the report was generated.

ElectionDate

published

"electionDate"

"electionDate"

Date of the election day.

Type

 

"type"

 

Report type.

SubType

 

"subtype"

 

Report subtype.

ResultsType

  

"resultsType"

 

Live/test data indicator (l indicates live data; t indicates test data).

StatePostal

 

"statePostal"

 

The geo code, such as a two-character state postal code or "US" for national reports.

Version

 

"version"

 

The report version.

 

category

  

"categories"

In v2, contains one of the following report categories (if applicable):

  • Report type

  • Report subtype

  • Live/test data indicator (false or live for live data; true or test for test data)

  • The geo code, such as a two-character state postal code or "US" for national reports

Multiple <category> elements are returned in XML. In JSON, the "categories" property contains all of the report categories.

 

@term

  

"term"

A string that identifies the report category.

 

@scheme

  

"scheme"

A URI for the vocabulary to which a term belongs.

ContentLink

content

"contentLink"

"contentLink"

Contains the direct link to the report. In v3, the latest version of each report is always available at the same URL.

  Important note for v2 users

 

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.

 

 

 

 

@type

 

"contentType"

  • In v2 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 v2 JSON: Indicates the MIME type of the content returned when the original report format is other than XML (for example, "application/csv" for CSV).

  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.

 

 

 

 

@src

 

 

The specific URL to the report.

Response Headers (Optional)

Header

Description

AP_SIGNATURE_SHA256

If includesignature=sha256 or includesignature=eddsa was specified in the request, contains the digital signature. For more information, see Requesting Digital Signatures.

AP_SIGNATURE_EDDSA

Report Examples

 

  Note

 

These examples currently show ELAPI v2 responses. For the ELAPI v3 response examples, please refer to What's New in v3.

 

 

 

Example 1: Live Data

XML  |  JSON

This example shows a list of sample reports for the 2020-07-12 election date in XML and JSON.

Example 2: Test Data

XML  |  JSON

This example shows the list of sample reports from the previous example when the resultsType=t parameter was specified in the request.