election-tonight-client

🗳️ election-tonight-client

Client for the ElectionTonight API, an API for retrieving U.S. election results and exit polls conducted by Edison Research.

📚 API docs

⚙️ GitHub Repo

Features

• ✨ Easy and flexible API to efficiently retrieve data from the ElectionTonight API in whatever way best suits you.
• 🔌 Integrates with your preferred database using Sequelize.
• ✅ Tested across multiple elections.
• 📆 Simulates your own election night tests.

Install

npm install election-tonight-client

Quickstart

Initialise the client.

import ElectionTonightClient from 'election-tonight-client';

import { Sequelize } from 'sequelize';

// ElectionTonight API key
const API_KEY = 'SECRET';
// ElectionTonight event ID
const EVENT_ID = '20221108';
// Sequelize instance to connect to your database
const sequelize = new Sequelize({
  dialect: 'sqlite',
  storage: 'db.sqlite',
  define: { freezeTableName: true },
});


const client = new ElectionTonightClient(API_KEY, EVENT_ID, sequelize);

Setup the event with all its metadata.

await client.setupEvent();

Get all election data in a "sweep" ...

await client.getCountyVotes();
await client.getCalls();
await client.getEditorialTurnout();
await client.getTotalExpectedVote();
await client.getMessages();

... or get just the latest in a "stream."

let updatedEntities = await client.getStreamedCountyVotes();

// Now, do something with the updated entites -- states,
// offices, etc. -- returned from the stream.
for (const updatedEntity of updatedEntites.updated) {
  console.log(`New votes for state: ${updatedEntity.state}`);
}

updatedEntities = await client.getStreamedCalls();
updatedEntities = await client.getStreamedEditorialTurnout();
updatedEntities = await client.getStreamedTotalExpectedVote();
updatedEntities = await client.getStreamedMessages();

Filter requests to only get the county vote data you want.

client.filter({
  states: ['TX', 'KS', 'MO'],
  summary: true,
});

await client.getCountyVotes();

After you've gotten election data from the API, use lookups to retrieve it from your database.

const offices = await elex2nite.lookups.geo.getOfficesByState('TX');

for (const office of offices) {
  const officeVotes = await client.lookups.votes.getVotesByOfficeRace(office.uid);
}

Read more in the client's API docs.

API coverage

Current coverage of ElectionTonight API endpoints. All others are planned by 2024.

Events

	endpoint
✅	event list
✅	absentee-method
✅	county-by-elect
✅	county-by-state
⭕	delegate-district
⭕	delegate-district-type
✅	election
✅	election/race
✅	party-by-office
✅	party-lookup
⭕	past-county-data
⭕	xtab-setup

Results/streams

	endpoint
✅	county-vote
⭕	delegate-allocation
⭕	delegate-vote
✅	editorial-turnout
✅	electoral-vote
✅	est
✅	msg
⭕	national-delegate-summary
✅	total-expected-vote
⭕	xtab

Development

👋 We welcome pull requests, issues and more from the community!

Testing

yarn test

Run specific tests by passing a substring or regular expression to the --grep filter:

yarn test --grep 'your-substring'

Docs

Export with:

yarn docs

After building the docs page by running yarn docs, preview the docs site with:

yarn docs:preview

Terminology

Election races are defined by the election type, state, jurisdiction, and offices. In this library, we define unique IDs for each of these key variables, which we use as UIDs in relevant models:

• electionType: Election type. This value is G for general elections.

• jurisdictionType: The level at which a race takes place. The types are NR (national), CD (congressional district) and SW (state-wide)

• jurisdictionCode: Specifies the district for a race. For example, this value would be 2 if a race is taking place in congressional district 2. This value is 0 for state-wide races.

• jurisdiction: UID formed by concatenating state, jurisdictionType and jurisdictionCode.

• jurisdictionRace: UID formed by concatenating jurisdiction and electionType

• officeBody: The 4 types of national office bodies this library handles: P (president), S (U.S. Senate), H (U.S. House) and G (State governor). Note that officeBody refers to the general office type and not to a specific office in a particular state or jurisdiction.

• office: UID formed by concatenating jurisdiction and officeBody IDs. Note that office refers to a specific office in a particular state and jurisdiction, which is specified in the jurisdiction portion of this UID.

• officeRace: UID formed by concatenating office and electionType IDs. Note that officeRace refers to a specific race for a specific office in a particular state and jurisdiction.

These unique IDs are parsed with the method parseKey defined in utils.