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

Docs

Export with:

yarn docs

Preview the docs site with:

yarn docs:preview