Contests and officeholders
Which district each race is for, and who holds each seat now. The API has no address or geography lookups (see what was retired): districts are named and identified, never drawn.
A contest’s district
Every contest, in /v1/contests, /v1/endorsements, /v1/recommendations and on the stream, carries the district it’s voted in:
"district": { "id": 77, "ocd_id": "ocd-division/country:us/state:ca/county:san_francisco/council_district:8",
"name": "San Francisco Supervisorial District 8", "level": "county", "type": "council", "state": "CA" }level is federal, state, county, city, school or special. ocd_id is the Open Civic Data division id where there is one; pass it as districts to /v1/contests or /v1/officeholders to find the races for, or the people holding, that seat.
Officeholder endpoints
| Endpoint | What |
|---|---|
GET /v1/officeholders | People in office now, with party, term, phone, email, offices, website and photo. states, offices, levels, districts (OCD ids), q |
GET /v1/officeholders/{person_id} | One officeholder, with every seat they hold |
List parameters take comma-separated values: offices=governor,us_senator.
Officeholders
Officeholders come from Open States and are refreshed as it updates. Each has a person_id that stays the same across terms and offices, the office and the office_title the state uses (Assemblymember, Delegate), and the seat’s district, district_ocd_id and district_id (a contest’s district.id, where it matches). A seat’s district is the one its holder was elected in, which can differ from the district on the next ballot where lines have been redrawn. Local offices other than the D.C. Council aren’t included yet.