🗳️ 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 full-featured API to efficiently retrieve data from the ElectionTonight API in whatever way best suits you.
🐇 Fast, efficient and fully typed database queries with Drizzle and Postgres.js.
✅ 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';

// ElectionTonight API key
const API_KEY = 'SECRET';
// ElectionTonight event ID
const EVENT_ID = '20221108';

const client = new ElectionTonightClient(API_KEY, EVENT_ID);

Connect to your PostgreSQL database, using Postgres.js.

const databaseUrl = 'postgresql://localhost:5432/yourdb';

client.connect(databaseUrl);

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 Drizzle queries to retrieve records from your database.

const states = await client.db.query.state.findMany();

Close the PostgreSQL connection when you're done.

await client.disconnect();

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

Testing

Setup

Export a DATABASE_URL environment variable or use the built-in ephemeral PostgreSQL testcontainer.

If using testcontainers, you must have a Docker client installed, e.g., Docker Desktop.

Running tests

npm run test

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

npm run test -- --grep 'your-substring'

☂️ Code coverage

See coverage report.