Seat change

Whether a result kept or changed who holds a seat, and whether a partisan seat flipped.

Returned by: GET /v1/contests, GET /v1/contests/{id}, GET /v1/offices/{slug}
Found in: Contest (seat), Contest result (seat_change), Office (contests[].seat_change)
Shapes: The full record is in result.seat_change. The shorter forms in a contest’s seat leave some fields out; a field that isn’t in every form says where it is.

How it connects

Every decided general, special, recall or runoff contest linked to its seat has one, under result.seat_change; a contest’s seat names the seat.

Good to know

It is judged against whoever held the seat going in, from the term history, not the last election: an appointee counts as the incumbent, and a party switch counts.
A seat vacant on election day compares with the last holder before the vacancy; vacant_since says when.
flipped is null for a nonpartisan seat, or when either party is unknown. outcome is unknown until the holder going in is loaded.

Fields

Field	Type	Meaning	Example
`office`	stringMatches ^[a-z0-9]+(-[a-z0-9]+)*$	The seat’s slug.Only in result.seat_change.	`us-house-ca-12`
`outcome`	string	incumbent_reelected, incumbent_defeated, open_seat, new_seat or unknown; for a body electing several members, incumbents_reelected or mixed.`incumbent_reelected`, `incumbent_defeated`, `open_seat`, `new_seat`, `unknown`, `incumbents_reelected`, `mixed` meaningsOnly in result.seat_change.	`unknown`
`partisan`	boolean	Candidates run with party labels.Only in result.seat_change.	`true`
`flipped`	booleanor null	Partisan seats: the winner’s party differs from the party of whoever held the seat going in (appointments and party switches count). null for a nonpartisan seat or when either party is unknown.Only in result.seat_change.	`false`
`holders_going_in`	array of object	Who held the seat (or the seats up) on election day.Only in result.seat_change.	—
`holders_going_in[].name`	string	As the source names them.Only in result.seat_change.	`Nancy Pelosi`
`holders_going_in[].party`	stringor null	Their party going in.Only in result.seat_change.	`Democratic`
`holders_going_in[].how`	string	How their term began.`elected`, `special_election`, `appointed`, `succeeded`, `retained`, `holdover`, `other` meaningsOnly in result.seat_change.	`elected`
`holders_going_in[].start_date`	stringor nullYYYY-MM-DD	When their term began.Only in result.seat_change.	`2019-01-03`
`parties_going_in`	array of string	Parties of the holders going in.Only in result.seat_change.	`["Democratic"]`
`winner_parties`	array of string	Parties of the winners.Only in result.seat_change.	`["Democratic"]`
`incumbents_up`	integer	Holders whose seats were up.Only in result.seat_change.	`0`
`incumbents_reelected`	integer	Of them, how many won.Only in result.seat_change.	`0`
`incumbents_defeated`	integer	Of them, how many ran and lost.Only in result.seat_change.	`0`
`open_seats`	integer	Seats up whose holder didn’t run.Only in result.seat_change.	`0`
`vacant_since`	stringor nullYYYY-MM-DD	When the seat was vacant on election day: the day it fell vacant. holders_going_in is then the last holder before it, with their party when they left.Only in result.seat_change.	—
`slug`	string	The seat’s slug, for GET /v1/offices/{slug}.Only in a contest’s seat.	`us-house-ca-12`
`name`	string	The seat’s name.Only in a contest’s seat.	—
`race_type`	string	regular, special, recall or retention.`regular`, `special`, `recall`, `retention` meaningsOnly in a contest’s seat.	—
`stage`	string	general, primary or runoff. A primary nominates and never gives a term.`general`, `primary`, `runoff` meaningsOnly in a contest’s seat.	—
`seats_up`	integer	How many of the seat’s members this contest elects (1 except for an at-large body).Only in a contest’s seat.	—

Download every dictionary as CSV or JSON.

Sample (JSON)

One seat change as the API returns it, in result.seat_change. More in the sample data.

{
  "office": "us-house-ca-12",
  "flipped": null,
  "outcome": "unknown",
  "partisan": true,
  "open_seats": 0,
  "vacant_since": null,
  "incumbents_up": 0,
  "winner_parties": [
    "Democratic"
  ],
  "holders_going_in": [],
  "parties_going_in": [],
  "incumbents_defeated": 0,
  "incumbents_reelected": 0
}