Skip to content

About

Every election in the world, down to the ballot box.

Resources

Contributing

Security policy

Stars

7 stars

Watchers

1 watching

Forks

Repository files navigation

Elections Archive holds results for more than 960,000 contests in 224,000 elections, from the 1787 elections in the United States to this year's, by precinct, polling station, and ballot box where the official count goes that deep. Every number links to the source that published it.

County map of the 2024 United States presidential election on electionsarchive.com, shaded by margin, with a color key and a histogram of county margins

  • Every number cites its source. Each figure traces to a source and to the changeset that wrote it. Figures read from scanned books keep the page and the box on that page they came from.
  • Down to the finest unit. Precincts in the US, ballot boxes in Türkiye, polling stations in France, sections in Brazil, and polling districts in Germany.
  • Declared, then checked. Official winners and seats are stored as declared. A seat engine, tested against real elections, recomputes them for comparison and never overwrites them.
  • Live on election night. Returns update as counties report, and every race has a share card that redraws as the count moves.
  • Built for agents. Every page is also Markdown and JSON, the REST API is described by OpenAPI, and an MCP server and an agent skill expose the same data.
  • Open to corrections. Anyone can report a mistake or suggest a source through a GitHub issue form, and every fix is published as a changeset that cites its source.

What's inside

Country Since Finest unit
🇺🇸 United States 1787 precinct
🇬🇧 United Kingdom 1832 ward
🇨🇭 Switzerland 1848 commune
🇨🇦 Canada 1867 polling division
🇹🇷 Türkiye 1923 ballot box
🇮🇹 Italy 1948 polling section
🇩🇪 Germany 1949 polling district
🇫🇷 France 1958 polling station
🇪🇺 European Union 1979 member state
🇮🇪 Ireland 1979 Dáil constituency
🇧🇷 Brazil 1994 section

Depth varies by country and year. The coverage page measures each country against an outside count of its elections and lists what is still missing.

Every race, ready to share

Share card for the 2024 Pennsylvania US Senate race: both candidates with vote shares and totals, a winner tag, a share bar, and a county map shaded by the leading party

Each contest page has a card like this one, drawn from the same numbers as the page. Add .png to a page's path under /og/live/ to get it; during a count it redraws every minute.

Use it

Add .md or .json to any page:

curl https://electionsarchive.com/us/2024-11-05-general/president.md

Search and query through REST:

curl "https://electionsarchive.com/api/v1/search?q=istanbul"

Connect your agent

Install the skill, which teaches an agent the site's URLs, twins, and API:

npx skills add electarchive/electionsarchive

Or add the MCP server. In Claude Code:

claude mcp add --transport http electionsarchive https://electionsarchive.com/mcp

In any other client:

{
  "mcpServers": {
    "electionsarchive": {
      "type": "http",
      "url": "https://electionsarchive.com/mcp"
    }
  }
}

Reading needs no key. A key from your settings gives your agent higher limits. The agents page has setup for other clients and example questions.

How the data gets in

flowchart LR
  S["Official results, books, and scans"] --> P["Pipelines<br>fetch, parse, emit"]
  P --> C["Packages and changesets"]
  C --> A{"Checks and review"}
  A --> D[("Postgres + PostGIS")]
  D --> W["Website"]
  D --> R["REST and MCP"]
  D --> T["Markdown and JSON twins"]
  D --> B["Bulk releases"]
Loading

One database is the source of truth, and every write to it is recorded as a changeset. Each source has a pipeline that fetches the official files into a raw cache and parses them. A new source builds packages, one Parquet folder per election. The packages are checked without a database and then loaded in bulk. Older pipelines and curated edits emit changesets, which pass the same checks before they publish. Scanned books are digitized page by page, and each figure keeps its page and position. docs/pipelines.md walks through both paths, using Canada's federal elections as the example you can run. docs/architecture.md and docs/data-model.md cover the rest.

Run it locally

You need Node.js 24, pnpm 12, uv, and Docker (or Postgres 18 with PostGIS 3.6 and Redis 8).

pnpm install
cp .env.example .env
docker compose -f infra/compose.yaml up -d
pnpm --filter @ea/db migrate
pnpm dev

The app runs at http://localhost:5173. Fill in BETTER_AUTH_SECRET in .env first, and CLOUDFLARE_ACCOUNT_ID and CLOUDFLARE_EMAIL_TOKEN if you want sign-in emails. Then load real data, for example Canada's federal elections since 1867:

cd pipelines
uv run ea fetch ca.elections
uv run ea parse ca.elections
uv run ea apply "$(uv run ea emit ca.elections)"

CONTRIBUTING.md covers the seed dump, the checks, and the rest of the setup.

Repository

Path Contents
apps/web SvelteKit app: pages, RPC, REST, MCP, twins, and sign-in
packages/db SQL migrations and the Drizzle schema
packages/engine Seat allocation and referendum outcomes, tested against real elections
packages/analytics Comparisons between elections, change metrics, and indices
packages/view-spec The JSON view spec schema
pipelines Python pipelines that fetch, parse, check, and load results
infra Docker Compose for local Postgres and Redis
spike The schema spike: proven DDL and benchmarks
docs Guides for contributors

Contributing

Code comes in through pull requests, and data corrections come in through the site: open the page with the mistake, choose Edit, and cite your source. See CONTRIBUTING.md, and report vulnerabilities privately as described in SECURITY.md.

License

The code is licensed under the GNU Affero General Public License v3.0. The data is published under CC BY 4.0, except where a source's own license differs; each result set records its source's license.

About

Every election in the world, down to the ballot box.

Resources

Contributing

Security policy

Stars

7 stars

Watchers

1 watching

Forks

Releases

Contributors

Languages