🗳️ 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();

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

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.