API for developers

Read-only JSON (or CSV) for districts, members, results, the calendar and polls. You don't need a key or an account.

Quickstart

Districts and officials for an address:

curl -X POST "https://www.electionwrld.com/api/v1/lookup" \
  -H "Content-Type: application/json" \
  -d '{"address": "605 E Main St, Charlottesville, VA 22902"}'

Base URL: https://www.electionwrld.com/api/v1
Formats: JSON by default. Add ?format=csv for CSV on every endpoint except lookup.
CORS: Open to every origin (Access-Control-Allow-Origin: *).
Caching: Data responses may be cached for one hour. Lookups are never cached.
Limits: No key. Address lookups are capped at 10 a minute from one connection on each server. Data endpoints have no limit in the code today.
License: Our tables are CC BY 4.0. Credit Election Wrld; polls also credit VoteHub. Each response carries the license.
Missing data: A value we don’t have is null. A file we haven’t loaded returns 404 with a message. Nothing is estimated.

Try it

Try VA-07, WY-AL or ocd-division/country:us/state:va/sldl:57.

Endpoints

EndpointReturnsExample
POST /api/v1/lookupUS House, state senate and state house districts for a street address, with the members and the next election for each. POST only, so the address stays out of URLs and logs. Addresses are not stored.Example POST body with an address
/api/v1/states/{st}State reference, governor, US senators, US House members and upcoming elections. CSV gives the officials table.Example /api/v1/states/va
/api/v1/districts/{id}Member, results since 1976 and upcoming elections. The id is a key such as VA-07 or WY-AL, or a state legislative OCD-ID. CSV gives the results.Example /api/v1/districts/VA-07
/api/v1/house/{year}Every US House race in one year, all states.Example /api/v1/house/2024?format=csv
/api/v1/polls2026 polls as published. Filters: state, type (us-senate, governor, us-house, generic-ballot, approval), race, pollster, limit (up to 500), offset.Example /api/v1/polls?state=ga&type=us-senate
/api/v1/calendarElections 2026 to 2032. Filters: state, office, kind, from, to.Example /api/v1/calendar?state=ga&from=2026-11-01
/api/v1/datasetsIndex of every downloadable table, with JSON and CSV links.Example /api/v1/datasets
/api/v1/datasets/{id}One whole table. Per-state tables add /{st}.Example /api/v1/datasets/house/va?format=csv

State legislative districts

Use the OCD-ID as the path. Slashes are fine, and one URL-encoded segment also works. Multi-member districts keep one id with a seat count.

curl https://www.electionwrld.com/api/v1/districts/ocd-division/country:us/state:va/sldl:57

Screen-record mode

For video. These pages have no menu or footer and are laid out 16:9. In a wide window they scale to fit, so a 1280 by 720 or 1920 by 1080 recording looks the same. Every view carries a credit line and the date of its data. The data is CC BY 4.0, so keep that line in frame.

/embed/matchup/ga/us-senateOne race: the candidates, the newest poll and every published poll over time. Also /governor and /congress/10 in place of /us-senate. A seat with a regular and a special election takes ?race=special.
/embed/early-vote/NCOne state’s early ballot count with its county map, as of the date its election office last updated it.
/embed/poll-closingsWhen polls close in every state, in Eastern time.

Add ?theme=dark or ?theme=light to pick a theme. Below 900 pixels wide the page stops scaling and reflows for a phone. The district cards (/embed/va/congress/7) are the small ones for an iframe.

Coming from Google Civic?

The migration guide maps the Civic Information API’s representatives and divisions calls to these endpoints, field by field, and lists what we don’t cover.