@reuters-graphics/election-api-client

Typed TypeScript client for Reuters' Election.API. Fetches US election metadata and results and persists them into your own PostgreSQL database, then hands you Drizzle models to query them with.

Credentials are required, and they are not public

This package does nothing on its own. Election.API is a credentialed Reuters service; without a client ID and secret issued by Reuters there is nothing to connect to. The client is published under MIT so it can be installed and read like any other dependency — that does not make the data behind it available.

Install

npm install @reuters-graphics/election-api-client

Requires Node >= 22 and a PostgreSQL database you supply — this library writes into a database you own and never provisions one.

Usage

import { ElectionApiClient } from '@reuters-graphics/election-api-client';

const client = new ElectionApiClient({
  credentials: { clientId, clientSecret, tokenEndpoint },
  baseUrl,
  country: 'us',
  electionDate: '2026-11-03',
});

client.connect(process.env.DATABASE_URL);
await client.migrate();

// Fetch and persist. Idempotent, and safe to poll.
await client.syncMetadata();
await client.syncResults();

// Then query your own database.
const votes = await client.queries.votes({ state: 'TX' }, 'summary');

await client.disconnect();

Credentials are passed explicitly and never read from the environment, so the library is safe to import in any process and you can hold two clients with different credentials at once.

A client is bound to one election event — one country and electionDate — at construction. A database may accumulate many events over a season, so queries are scoped explicitly rather than implicitly.

What you get

• syncMetadata() / syncResults() — fetch and upsert into a reuters_election schema. Never destructive: absence in a response never deletes.
• Conditional fetching — repeat calls send the stored ETag, so an unchanged result answers 304 and writes nothing.
• A change report — every sync returns what actually moved, so a publishing job can rewrite only the files that are stale.
• Exported Drizzle models — every table and row type, under models. Query client.db however you like.
• Shortcut queries — queries.metadata(), queries.votes() and queries.staleSince() return plain, JSON-safe objects with exported types, ready to serialise and type a fetch on the other side.

No race calls

Election.API does not report who won — no call, projection or declared winner, for any contest. You get votes, not winners, and a winner must never be derived from vote counts: that is an editorial decision, not an arithmetic one. Calls come from whichever system your newsroom uses to make them.

Migrations

Migrations ship inside the package and are applied by client.migrate(). They create and manage the reuters_election schema only, and leave the rest of your database alone.

Contributing

See CONTRIBUTING.md in the repository for local setup, scripts and build details.

License

MIT