Field values

Every field in the API that holds a code, such as a contest’s kind, its vote_method, a result’s status or an error’s code, takes one of the values below. Each table says where the values appear and what each one means. The API reference shows the same meanings under each field, and /openapi.json carries them as x-enumDescriptions.

Most sets are fixed: the API returns only these values, and they are an enum in the OpenAPI description. A few come from the election offices’ own classifications (district types, measure types and the like) and are marked open: the table lists every value in our data today, and new ones can appear as we load more places, so treat an unknown value as “other”. A field documented as nullable can also be null.

Value sets

Election type

In Election.type, Event election.type and types= on GET /v1/elections.

Value	Meaning
`general`	A general election: the November election (or a state’s regular election day) that fills offices and decides measures.
`primary`	A primary: voters choose each party’s nominee, or (in top-two and Louisiana-style states) the candidates who go on to the general.
`special`	A special election held outside the regular schedule, usually to fill a vacancy or decide a measure.
`special_primary`	The primary for a special election.
`runoff`	A runoff between the leading candidates when no one won the earlier round outright (the share needed is in the contest’s details.majority_required or vote_required).
`consolidated`	Several jurisdictions’ elections held together on one ballot (a city and school election on the same day, for example); details.consolidated_with names them.

Primary system

In Election.primary_system. How the state picks the candidates who reach this ballot. Set on general and special elections too; null where we don’t have it.

Value	Meaning
`none`	No primary system is recorded for this election.
`closed`	Only voters registered with a party may vote in its primary.
`semi_closed`	A party’s registered voters, plus unaffiliated voters who choose that party’s ballot.
`open`	Any registered voter may choose any one party’s ballot.
`top_two`	Every candidate is on one primary ballot whatever their party, and the top two go on to the general (Washington, California).
`top_four`	Every candidate is on one primary ballot, and the top four go on to a ranked-choice general (Alaska).
`nonpartisan`	Candidates run without party labels; the leading candidates go on, or a majority wins outright.

Contest kind

In Contest.kind, contest_kinds= parameters, Filter.contest_kinds and contest_kind (export CSV).

Value	Meaning
`candidate`	A race for an office: voters choose among candidates.
`measure`	A ballot measure (proposition, amendment, bond, tax, referendum or initiative): voters answer Yes or No.
`retention`	A judicial retention question: should this judge stay in office? Voters answer Yes or No.

Vote method

In Contest.vote_method and vote_method (export CSV). How a voter marks the contest, and so how an endorser’s picks are shaped.

Value	Meaning
`plurality`	Vote for one: the candidate with the most votes wins (or goes to a runoff where a majority is required).
`multi_seat`	Vote for up to N (votes_allowed): several seats are filled at once and the top N win.
`ranked_choice`	Ranked choice: voters rank up to ranks_allowed candidates; endorsements carry the endorser’s rank 1, 2, 3…. rcv_rounds holds the official tabulation once there is one.
`approval`	Approval voting: voters mark every candidate they approve of; the most-approved win (Fargo, St. Louis).
`yes_no`	A Yes or No question: every measure and retention question.

Race type

In Contest.race_type. null for a measure.

Value	Meaning
`regular`	An election for a full term on the regular schedule.
`special`	An election for the rest of an unexpired term, or a contest in a special election.
`recall`	A recall: whether to remove an officeholder before the term ends (and, where the ballot has one, who replaces them).
`retention`	A judicial retention question.

Office type

In Office.type and offices= on GET /v1/contests. Worked out by rule from the contest’s title and district, so the same office has the same type in every state.

Value	Meaning
`president`	President of the United States (with the vice president on the same ticket).
`us_senator`	U.S. Senator.
`us_representative`	U.S. Representative, or a non-voting delegate to the House.
`governor`	Governor.
`lieutenant_governor`	Lieutenant governor.
`attorney_general`	State attorney general.
`secretary_of_state`	Secretary of state.
`state_treasurer`	State treasurer.
`state_auditor`	State auditor, comptroller or controller.
`state_superintendent`	State superintendent of public instruction (the elected head of state schools).
`insurance_commissioner`	State insurance commissioner.
`agriculture_commissioner`	State agriculture commissioner.
`land_commissioner`	State land commissioner (public lands).
`labor_commissioner`	State labor commissioner.
`utility_commission`	A state utility, public service or corporation commission seat.
`university_board`	A state university board of regents or trustees seat.
`state_board_of_education`	A state board of education seat.
`state_senator`	State senator (the upper house of the legislature; Nebraska’s one-house Legislature too).
`state_representative`	State representative, assemblymember or delegate (the lower house).
`state_supreme_court`	A justice of the state’s highest court.
`state_appellate_court`	A judge of a state intermediate appeals court.
`trial_court`	A judge of a general trial court: superior, district, circuit, county or probate court.
`municipal_court`	A city or municipal court judge.
`magistrate`	A magistrate.
`justice_of_the_peace`	A justice of the peace.
`court_clerk`	Clerk of a court.
`mayor`	Mayor.
`local_executive`	Another elected local chief executive: county executive or judge-executive, borough or parish president, first selectman, town or township supervisor, village president.
`city_council`	A city, town, village or borough council, select board or board of aldermen seat.
`county_legislature`	A county commission, board of supervisors, county council, quorum or fiscal court, or police jury seat.
`neighborhood_council`	A neighborhood body: Washington, D.C.’s Advisory Neighborhood Commissions, for example.
`school_board`	A school board or board of education seat.
`school_superintendent`	An elected county or district school superintendent.
`college_board`	A community college district board seat.
`special_district_board`	A board of a special district: hospital, fire, park, library, transit, port, utility and similar.
`water_conservation_board`	A soil and water conservation, water, irrigation, drainage or flood control district board.
`sheriff`	Sheriff.
`prosecutor`	District attorney, state’s attorney, county attorney or solicitor.
`coroner`	Coroner or medical examiner.
`constable`	Constable (or town sergeant).
`assessor`	Assessor, appraiser or property valuation administrator.
`tax_collector`	Tax collector or tax commissioner.
`treasurer`	A county, city or town treasurer.
`auditor`	A county, city or town auditor, comptroller or controller.
`recorder`	Recorder or register of deeds, wills or probate.
`clerk`	A county, city or town clerk, prothonotary or registrar.
`surveyor`	County surveyor or engineer.
`public_works`	Highway, road or street commissioner, or a public works office.
`police_fire`	An elected police chief, fire chief or marshal.
`other_county_office`	Another county office: public defender, public administrator, jailer, election director and similar.
`other`	An office that fits none of the types above.

Office level

In Office.level.

Value	Meaning
`federal`	A federal office: president, U.S. senator, U.S. representative.
`state`	A statewide or state legislative office, or a state court judge (whatever district the court sits in).
`local`	A county, city, town, school or special-district office.

Office branch

In Office.branch.

Value	Meaning
`executive`	Runs government: president, governor, mayor, sheriff, clerk, treasurer and other officers.
`legislative`	Makes laws or policy as a body: Congress, legislatures, councils, commissions and boards.
`judicial`	A judge, justice, magistrate or justice of the peace.

Measure topic

In Contest.topics, topics= on GET /v1/contests and GET /v1/measure-topics. Assigned by rule from a measure’s title, summary and wording. A measure can have several; candidate contests have none.

Value	Meaning
`taxes`	Taxes: new or changed taxes, levies, millage, fees, assessments and exemptions.
`bonds`	Bonds and borrowing: general obligation bonds, debt, lease-purchase.
`budgets`	Budgets and spending limits: appropriations, revenue and spending caps.
`education`	Education and schools: school funding, facilities, districts and colleges.
`housing`	Housing: affordable housing, rent, homelessness.
`elections`	Elections and voting: how elections are run, voting rules, redistricting.
`government`	Government structure and charters: charter amendments, who appoints whom, how offices work.
`term_limits`	Term limits for elected officials.
`ethics`	Ethics and transparency: conflicts of interest, open records, campaign finance.
`local_boundaries`	Annexation, incorporation and dissolution: changing a city’s or district’s boundaries, merging or dissolving one.
`public_safety`	Police, fire and emergency services.
`criminal_justice`	Criminal justice: sentencing, courts, jails, victims’ rights.
`health`	Health care and hospitals.
`mental_health`	Mental health and addiction services.
`environment`	Environment and conservation: open space, pollution, climate.
`energy`	Energy: power generation, fuels, renewables.
`water`	Water and sewer: water supply, treatment and rights.
`transportation`	Transportation and roads: transit, highways, streets.
`parks_recreation`	Parks and recreation.
`libraries`	Libraries.
`land_use`	Land use and zoning: development, planning, growth limits.
`economic_development`	Economic development: business incentives, tourism, development districts.
`cannabis`	Marijuana: legalization, sales, local bans.
`alcohol`	Alcohol: liquor sales, local option (wet/dry) questions.
`gambling`	Gambling: casinos, sports betting, lotteries.
`abortion`	Abortion and reproductive rights.
`civil_rights`	Civil rights: equal rights, discrimination, privacy.
`labor`	Labor and wages: minimum wage, paid leave, unions.
`pensions`	Pensions and public employees: retirement benefits, pay and rules for government workers.
`firearms`	Firearms.
`utilities`	Utilities and broadband: public utilities, franchises, internet service.
`immigration`	Immigration and citizenship.
`veterans`	Veterans’ benefits and services.
`animals`	Animals: animal welfare, hunting, fishing.
`seniors`	Seniors: services and tax relief for older residents.
`children`	Children and families: child care, youth services.

Measure type (open)

In Contest.details.measure_type. How the election office (or the state’s law) classes a ballot measure. Only measures whose source says have it.

Value	Meaning
`local`	A local measure.
`other`	A measure the election office doesn’t class further.
`bond`	Authorizes borrowing by issuing bonds.
`tax_rate`	Sets or changes a tax rate or levy (a millage or levy rate).
`charter_amendment`	Amends a city or county charter.
`local_proposition`	A local proposition.
`constitutional_amendment`	Amends the state constitution.
`charter amendment`	Amends a city or county charter.
`legislative_constitutional_amendment`	A state constitutional amendment the legislature put on the ballot.
`referendum`	A referendum: voters approve or reject a law or action already passed.
`Local Proposition`	A local proposition.
`school_referendum`	A school district referendum, usually an operating levy or bond (Minnesota, Wisconsin).
`Charter Amendment`	Amends a city or county charter.
`general tax`	A general tax: the money goes to the general fund, so a simple majority passes it (California).
`town_question`	A question for a town’s voters.
`local_option`	A local option question, such as allowing alcohol sales (a wet/dry vote).
`levy`	A property tax levy.
`sales tax`	A sales tax.
`special tax`	A special tax: the money is set aside for a purpose, so it usually needs two-thirds (California).
`ordinance`	An ordinance: a local law.
`municipal`	A municipal measure.
`tax`	A tax measure.
`municipality_question`	A question for a municipality’s voters.
`parcel tax`	A parcel tax: a flat tax on each parcel of property (California).
`school_question`	A question for a school district’s voters.
`advisory`	An advisory question: the result is advice to the government, not law.
`local_question`	A question for local voters.
`ordinance (tax)`	A local tax ordinance.
`Bond Issue`	Authorizes borrowing by issuing bonds.
`County Ordinance`	A county ordinance.
`non_binding`	A non-binding (advisory) question: the result is advice to the government, not law.
`city_question`	A question for a city’s voters.
`initiative`	A measure put on the ballot by citizens’ petition.
`initiative_statute`	A state law proposed by citizens’ petition.
`initiated_constitutional_amendment`	A state constitutional amendment put on the ballot by citizens’ petition.
`initiated_statute`	A state law proposed by citizens’ petition.
`initiative_constitutional_amendment`	A state constitutional amendment put on the ballot by citizens’ petition.
`county_question`	A question for a county’s voters.
`legislative_statute`	A state law the legislature referred to the voters.
`school`	A school district measure.
`Constitutional Amendment`	Amends the state constitution.
`legislatively_referred_constitutional_amendment`	A state constitutional amendment the legislature put on the ballot.
`statute`	Changes state law.
`county charter amendment`	Amends a county charter.
`City Charter Amendment`	Amends a city charter.
`County Proposition`	A county proposition.
`appropriations limit`	Sets or raises a government’s appropriations (Gann) limit (California).
`initiative (tax)`	A tax measure put on the ballot by citizens’ petition.
`debt_exclusion`	A debt exclusion: raises property taxes outside Proposition 2½’s limit to pay for a project (Massachusetts).
`formation`	Forms a new district or government.
`initiative constitutional amendment`	A state constitutional amendment put on the ballot by citizens’ petition.
`initiative_to_the_legislature`	A citizens’ initiative sent to the legislature first, then to the voters (Washington).
`recall`	A recall question: whether to remove an officeholder.
`village_question`	A question for a village’s voters.
`charter`	Adopts or revises a charter.
`constitutional_initiative`	A state constitutional amendment put on the ballot by citizens’ petition.
`initiative statute`	A state law proposed by citizens’ petition.
`legislative constitutional amendment`	A state constitutional amendment the legislature put on the ballot.
`statewide_referendum`	A statewide referendum: voters approve or reject a law already passed.
`tax levy`	A property tax levy.
`Charter Amendment by act of County Council`	A county charter amendment the county council put on the ballot (Maryland).
`Initiative`	A measure put on the ballot by citizens’ petition.
`Local Referendum by Petition`	A local referendum citizens forced by petition.
`appointive offices`	Makes elected offices appointed, or the reverse.
`cpa`	Adopts or changes the Community Preservation Act surcharge (Massachusetts).
`fire district`	A fire district measure.
`initiative ordinance`	A local ordinance put on the ballot by citizens’ petition.
`land use`	A land use or zoning measure.
`lease approval`	Approves a lease of public property.
`legislative_bond`	A bond measure the legislature referred to the voters.
`ordinance (land use)`	A local land use ordinance.
`sales surtax`	A sales surtax (Florida).
`Bond Act`	A state bond act (New York).
`Charter Amendment by Petition`	A charter amendment put on the ballot by citizens’ petition.
`Charter Amendment via Local Petition`	A charter amendment put on the ballot by citizens’ petition.
`Charter Resolution`	A charter amendment proposed by resolution of the governing body.
`County Charter Adoption Referendum`	Whether to adopt a county charter.
`General Assembly Referendum`	A question the state legislature (General Assembly) referred to the voters.
`appointive office`	Makes an elected office appointed, or the reverse.
`bylaw amendment`	Amends a town’s bylaws (New England).
`charter and general tax`	A charter amendment that also sets a general tax.
`city_referendum`	A city referendum.
`constitutional_convention`	Whether to call a state constitutional convention.
`county`	A county measure.
`county measure`	A county measure.
`county parcel tax (initiative)`	A county parcel tax put on the ballot by citizens’ petition.
`county tax`	A county tax.
`county tax (initiative)`	A county tax put on the ballot by citizens’ petition.
`fee`	Sets or changes a fee.
`general plan amendment`	Amends a city’s or county’s general plan.
`hospital lease`	Approves a lease of a public hospital.
`hotel tax`	A hotel (transient occupancy) tax.
`initiated_act`	A state law proposed by citizens’ petition (an initiated act).
`initiative bond`	A bond measure put on the ballot by citizens’ petition.
`initiative constitutional amendment and statute`	A citizens’ initiative that amends the state constitution and changes state law.
`initiative_constitutional_amendment_and_statute`	A citizens’ initiative that amends the state constitution and changes state law.
`legislative bond`	A bond measure the legislature referred to the voters.
`legislative statute`	A state law the legislature referred to the voters.
`legislative_constitutional_ratification`	Ratifies a state constitutional amendment the legislature passed.
`legislative_referral`	A measure the legislature referred to the voters.
`ordinance (initiative)`	A local ordinance put on the ballot by citizens’ petition.
`parcel tax (initiative)`	A parcel tax put on the ballot by citizens’ petition.
`property transfer`	Approves selling or transferring public property.
`regional tax`	A tax across several counties or cities.
`reorganization`	Reorganizes a government or district (merging, dividing or restructuring it).

Referendum type (open)

In Contest.details.ref_type. For a school or local levy referendum, what the money is for (Minnesota).

Value	Meaning
`nonrecurring`	A nonrecurring (one-time or limited-term) levy.
`debt`	A levy to pay debt, such as a bond.
`operating`	An operating levy for day-to-day costs.
`other`	Another kind of referendum.

Contest stage (open)

In Contest.details.stage. Which round of a multi-round election a contest belongs to.

Value	Meaning
`open_primary`	Louisiana’s open (jungle) primary: every candidate on one ballot; a majority wins outright, else the top two go to a runoff.
`runoff`	The runoff round.
`general`	The general election round.

Question wording (open)

In Contest.details.question_wording. Present only where description isn’t the printed question.

Value	Meaning
`notice`	description summarizes the official election notice (Ohio) instead of quoting the printed question.

District level

In District.level, levels= parameters, Filter.levels and district_level (export CSV). The level of the district a contest is voted in. A state court judge voted on in a county is county here, but state in Office.level.

Value	Meaning
`federal`	The whole country, or a U.S. House district.
`state`	A whole state, or a state legislative, judicial or other state district.
`county`	A county (a parish in Louisiana, a borough in Alaska) or a district within one.
`city`	A city, town, township, village or borough, or a ward or council district within one.
`school`	A school district, community college district, or a trustee area within one.
`special`	A special district: water, fire, hospital, park, transit, port, conservation and the like.

District type (open)

In District.type and district_type (stream CSV). What kind of district a contest is voted in, as the election office names it. Each meaning ends with an example from our data.

Value	Meaning
`airport_authority`	An airport authority’s district. Example: Hall County Airport Authority.
`anc_smd`	A single-member district of a Washington, D.C. Advisory Neighborhood Commission. Example: ANC 1A01.
`annexation_area`	The area a proposed annexation would add to a city. Example: Tucker annexation area (SB 622).
`appellate_district`	A state appellate court district. Example: Illinois Appellate Court, First District.
`appraisal_district`	A property appraisal district. Example: Collin Central Appraisal District.
`assistance_district`	A county assistance district (Texas), proposed or in place. Example: Carson County Assistance District (proposed; Carson County outside Panhandle, White Deer, Groom, Skellytown and Fritch).
`board_district`	A member district of a local board (a city, utility or similar board). Example: Hot Springs Board District 2.
`board_of_education_district`	A member district of a county or city board of education. Example: Anderson County Board of Education District 1.
`board_of_equalization`	A district of a state board of equalization (California’s tax board). Example: State Board of Equalization District 2.
`board_of_regents`	A district of a state university’s board of regents. Example: University of Nebraska Board of Regents District 1.
`board_of_review_district`	A district of a county property-tax board of review. Example: Cook County Board of Review District 1.
`cemetery_district`	A cemetery district. Example: Chugwater Cemetery District.
`chancery_court_district`	A chancery court district (Mississippi, Tennessee). Example: 1st Chancery Court District.
`chancery_court_district_subdistrict`	A subdistrict that elects one chancery judge. Example: Chancery Court Subdistrict 5-1.
`circuit_court`	A circuit court’s circuit. Example: 6th Judicial Circuit.
`circuit_court_district`	A circuit court district. Example: 1st Circuit Court District.
`circuit_court_district_subdistrict`	A subdistrict that elects one circuit judge. Example: Circuit Court Subdistrict 4-1.
`city`	A whole city. Example: City of Oakland.
`city_council`	A city council district. Example: Portland District 4.
`college`	A community college district. Example: Grossmont-Cuyamaca Community College District.
`college_district`	A community college district. Example: Collin County Community College District.
`commission`	A county commission, or a district of one. Example: Clay County Commission, Eastern District.
`commission_district`	A county or city commission district. Example: Jefferson County Commission District 1.
`commissioner_district`	A county commissioner district. Example: El Paso County Commissioner District 1.
`commissioner_precinct`	A county commissioners court precinct (Texas). Example: Travis County Commissioners Precinct 2.
`community_college`	A community college district. Example: San Francisco Community College District.
`community_college_district`	A community college district. Example: Lansing Community College.
`congressional`	A U.S. House district (or a whole state with one at-large seat). Example: California Congressional District 11.
`conservancy_district`	A conservancy (water) district. Example: Garrison Diversion Conservancy District, Wells County.
`conservation_district`	A conservation district. Example: Minnehaha Conservation District.
`constable_district`	A constable’s district. Example: Washington County Constable District 1.
`constable_precinct`	A constable precinct (Texas). Example: Travis County Constable Precinct 4.
`council`	A city or county council district. Example: City of Oakland Council District 2.
`council_district`	A city or county council district. Example: Austin City Council District 1.
`county`	A whole county (parish, borough), or a consolidated city and county. Example: City and County of San Francisco.
`county_budget_committee`	A county budget committee district. Example: Knox County Budget Committee District 6.
`county_commission`	A county commission or board of supervisors district. Example: Yavapai County Board of Supervisors District 2.
`county_commission_district`	A county commission district. Example: Blount County Commission District 4.
`county_council`	A county council district. Example: Cuyahoga County Council District 1.
`county_council_district`	A county council district. Example: Franklin County Council/Commissioner District 3.
`county_court_district`	A county court district. Example: Hinds County Court District 1.
`county_division`	A division of a county with its own courthouse or offices (Bessemer, Alabama). Example: Bessemer Division of Jefferson County.
`county_part`	The part of a county outside (or inside) certain cities, for a contest voted on only there. Example: Fayette County outside Somerville, Oakland, Piperton and Rossville.
`court_district`	The district of a city, municipal or other local court. Example: Lafayette City Court.
`court_of_appeal`	A state court of appeal circuit (Louisiana). Example: Louisiana 1st Circuit Court of Appeal.
`court_of_appeal_district`	An election district within a court of appeal circuit. Example: 1st Circuit Court of Appeal, District 2.
`court_of_appeals`	A state court of appeals district. Example: Fifteenth Court of Appeals District (statewide).
`court_of_appeals_district`	A state court of appeals district. Example: Kentucky Court of Appeals District 3.
`court_of_appeals_division`	A division of a state court of appeals. Example: Washington Court of Appeals Division 3.
`district`	A seat or district of a local board or special district. Example: Beach Mosquito Control District, Seat 2.
`district_attorney`	A district attorney’s district. Example: Berkshire District Attorney District.
`district_attorney_district`	A district attorney’s district. Example: 17th Circuit Court District (District Attorney).
`district_court`	A district court’s district. Example: Kittitas County District Court, Lower County.
`district_court_district`	A district court’s district. Example: 14A District Court.
`division`	A division (member district) of a special district. Example: Fallbrook Public Utility District Division 2.
`educational_service_unit`	An educational service unit district (Nebraska). Example: Educational Service Unit 1 District 1.
`election_district`	A county election district. Example: Montgomery County Election District 12 (Damascus).
`emergency_services_district`	An emergency services district. Example: Wheeler County Emergency Services District No. 1.
`ems_district`	An emergency medical services district. Example: Glendo Emergency Services District.
`executive_council`	A district of New Hampshire’s Executive Council. Example: New Hampshire Executive Council District 1.
`fire`	A fire protection district. Example: Sni Valley Fire Protection District.
`fire_district`	A fire district. Example: Union Grove Volunteer Fire District 16.
`fire_protection_district`	A fire protection district. Example: Newport Township Fire Protection District.
`forest_preserve_district`	A forest preserve district (Illinois). Example: Forest Preserve District of DuPage County.
`gid`	A general improvement district (Nevada). Example: Incline Village General Improvement District.
`governors_council`	A district of the Massachusetts Governor’s Council. Example: Massachusetts Governor's Council District 1.
`hospital_district`	A hospital district. Example: North Pine Area Hospital District.
`judicial`	A judicial district or circuit. Example: Court of Appeal, First Appellate District.
`judicial_circuit`	A judicial circuit. Example: 7th Judicial Circuit.
`judicial_district`	A judicial district. Example: 207th Judicial District.
`judicial_subcircuit`	A judicial subcircuit (Illinois). Example: DuPage County (18th Circuit) Judicial Subcircuit 4.
`justice_court`	A justice court’s district. Example: Roy/Weber County Justice Court.
`justice_court_district`	A justice court district. Example: Lauderdale County Justice Court District 2.
`justice_precinct`	A justice of the peace precinct. Example: Travis County Justice of the Peace Precinct 1.
`learning_community_subcouncil`	A subcouncil district of Nebraska’s Learning Community. Example: Learning Community of Douglas and Sarpy Counties Subcouncil 1.
`legislative`	A legislative district (Nebraska’s one-house Legislature). Example: Nebraska Legislative District 2.
`library_district`	A library district. Example: Vernon Area Public Library District.
`magistrate`	A magistrate district. Example: Doña Ana County Magistrate District 1.
`magistrate_district`	A magistrate or magisterial district. Example: Jefferson County Magisterial District 1.
`mental_health_district`	A mental health services district. Example: Proposed Mid-Northside Expanded Mental Health Services Program territory.
`municipality`	A whole municipality: a city, borough, town or village. Example: East Newark Borough.
`natural_resources_district`	A natural resources district or subdistrict (Nebraska). Example: Papio-Missouri River NRD Subdistrict 2.
`nursing_home`	A nursing home district. Example: Golden Age Nursing Home District.
`park_district`	A park district. Example: Hennepin County Park District 1.
`pec_district`	A Public Education Commission district (New Mexico). Example: Public Education Commission District 1.
`place`	A whole city or town (a Census place). Example: City of Camp Verde.
`port_district`	A port district. Example: Grant County Port Dist #4.
`precinct`	A single voting precinct. Example: Chicago Ward 7, Precinct 13.
`precinct_group`	A group of voting precincts. Example: Chicago Ward 7 Precinct 14 and Ward 10 Precincts 2 and 4.
`probate_district`	A probate court district. Example: Tobacco Valley Probate District.
`prosecutorial`	A prosecutorial district. Example: Prosecutorial District 1 (York County).
`prosecutorial_district`	A prosecutorial district. Example: Prosecutorial District 17.
`psc_district`	A public service commission district. Example: Montana Public Service Commission District 1.
`public_power_district`	A public power district or subdivision (Nebraska). Example: Omaha Public Power District Subdivision 1.
`public_service_commission`	A public service commission district. Example: Louisiana Public Service Commission District 1.
`public_service_district`	A public service commission district. Example: Mississippi Central Public Service Commission District.
`public_utility_district`	A public utility district. Example: Lincoln County Public Utility District.
`quorum_court_district`	A quorum court district (Arkansas’s county legislature). Example: Pulaski County Quorum Court District 1.
`reclamation_district`	A reclamation district or subdivision. Example: Twin Loups Reclamation District Subdivision 1.
`regents_district`	A board of regents district. Example: Board of Regents District 2.
`regional`	A region made of several counties or cities, for a regional measure. Example: Regional Transit Measure area (Alameda, Contra Costa, San Francisco, San Mateo, Santa Clara).
`regional_office_of_education`	A regional office of education (Illinois). Example: Regional Office of Education 4 (Boone and Winnebago Counties).
`registry_district`	A registry of deeds district. Example: Aroostook County Registry of Deeds, Northern District.
`road`	A road district. Example: Stone County Northern Road District.
`rtm_district`	A Representative Town Meeting district (Connecticut). Example: Darien RTM District 1.
`sanitary_district`	A sanitary district. Example: East Joliet Sanitary District.
`sboe`	A state board of education district. Example: Kansas State Board of Education District 10.
`sboe_district`	A state board of education district. Example: Nevada State Board of Education District 1.
`school`	A school district (or a whole district, for a district-wide seat). Example: San Francisco Unified School District.
`school_board`	A school board member district. Example: Matanuska-Susitna Borough School District, School Board District 3.
`school_board_district`	A school board member district. Example: Jefferson County Board of Education District 4.
`school_district`	A whole school district. Example: Princeton Independent School District.
`school_district_area`	A residence or trustee area of a school district. Example: LCSD 1 Residence Area 1.
`school_subdistrict`	A school board subdistrict. Example: Omaha Public Schools Subdistrict 8.
`school_tax_district`	A school tax or attendance district. Example: Odenville School Attendance and Tax District.
`school_zone`	A school board zone. Example: Conway Public Schools Zone 3.
`service_district`	A service district (senior citizens, recreation and the like). Example: Natrona County Senior Citizens Service District.
`sewer_district`	A sewer district. Example: West Side Sewer District.
`sldl`	A district of the lower house of the state legislature. Example: Arizona State House District 1.
`sldu`	A district of the upper house (state senate). Example: Colorado State Senate District 10.
`soil_conservation_district`	A soil conservation district. Example: Cass County Soil Conservation District.
`soil_water_district`	A soil and water conservation district. Example: Aitkin County Soil and Water Conservation District.
`special`	A special district: library, water, fire, park, transit and the like. Example: Altadena Library District.
`special_district`	A special district. Example: Tarrant Appraisal District.
`state`	A whole state. Example: Nevada.
`state_board_of_education`	A state board of education district. Example: Texas State Board of Education District 2.
`state_house`	A state house district (the lower house). Example: South Carolina House District 1.
`state_lower`	A district of the lower house of the state legislature. Example: State Assembly District 17.
`state_upper`	A district of the upper house (state senate). Example: State Senate District 2.
`statewide`	A whole state. Example: California.
`superior_court`	A superior court’s district. Example: Superior Court of Ferry, Pend Oreille and Stevens Counties.
`superior_court_district`	A superior court district. Example: Superior Court District 17.
`supervisorial`	A county (or city and county) supervisorial district. Example: Supervisorial District 2.
`supreme_court_district`	A state supreme court district. Example: Kentucky Supreme Court District 3.
`tax_district`	A tax district. Example: Fulton County outside the City of Atlanta.
`town`	A whole town. Example: Town of Carmel.
`township`	A township. Example: Pulaski County, Big Rock Township (Constable).
`transit`	A transit district’s member district. Example: BART District 8.
`transit_district`	A transit district or its director district. Example: RTD Director District B.
`transportation_district`	A transportation district (a transportation benefit district, for example). Example: Chelan Transportation Benefit District.
`trustee_area`	A trustee area of a school or college district. Example: Grossmont-Cuyamaca Community College District Trustee Area 5.
`trustee_district`	A trustee district of a school district. Example: Austin ISD Trustee District 1.
`tv_district`	A television district (Nevada’s TV translator districts). Example: Verdi Television District.
`utility_district`	A utility district. Example: Horizon Regional MUD, Mountain Shadow Unit 1 Defined Area.
`village`	A whole village. Example: Village of Brewster.
`ward`	A city ward. Example: Little Rock Ward 1.
`water`	A water supply district. Example: Stone County Public Water Supply District No. 1.
`water_district`	A water district. Example: Lower Valley Water District.
`water_reclamation_district`	A water reclamation district. Example: Metropolitan Water Reclamation District of Greater Chicago.
`water_sewer_district`	A water and sewer district. Example: Jamestown/Rio Vista Water and Sewer District.
`watershed_district`	A watershed district. Example: South Tyger River Watershed Conservation District.

Measure answer

In Choice.measure_answer, Pick.measure_answer, Endorsement choice.measure_answer and measure_answer (export CSV). null for a candidate.

Value	Meaning
`yes`	The Yes line of a measure or retention question. On an endorsement: the endorser says vote Yes.
`no`	The No line. On an endorsement: the endorser says vote No.

Special ballot line

In Choice.option. null for an ordinary line (a candidate or a Yes/No answer).

Value	Meaning
`none_of_these`	Nevada’s “None of these candidates” line, printed in statewide races. It can get votes but can’t win.

Result status

In ContestResult.status, result_statuses= on GET /v1/contests and result_status (export CSV).

Value	Meaning
`unofficial`	Election-night and canvass counts: still changing. We read them again every day until they’re certified.
`certified`	The canvass is certified: the final official count.

Result source kind

In ContestResult.source_kind and result_source_kind (export CSV).

Value	Meaning
`official`	A state, county, city or federal election office.
`compiled`	Certified official returns compiled by a research group (the MIT Election Data and Science Lab’s precinct returns), summed to the contest. Used for past elections; official_url links to the state’s own results where we have them.
`party`	A state or national party’s announcement of the winner, with no vote counts (party_reported is true). Replaced as soon as an official result appears.

Endorser category (open)

In Category.slug, EndorserCategory.slug, categories= parameters, Filter.categories and endorser_category (export CSV). The kinds of endorser. GET /v1/endorser-categories lists them with their counts.

Value	Meaning
`editorial`	Voter guides & editorial boards: each one a voter guide.
`labor`	Labor: each one a labor union.
`environment`	Environment & transportation: each one a environmental group.
`business`	Housing & business: each one a housing or business group.
`party`	Political parties: each one a political party.
`club`	Political clubs: each one a political club.
`community`	Community & advocacy: each one a community group.
`officials`	Elected officials: each one a elected official.

Added by

In added_by on every endorsement and added_by (export CSV). How the endorsement got into our data.

Value	Meaning
`automatic`	Added by our automatic watch of the endorser’s own website. It only adds a candidate the endorser’s own page names for that election; source_url is that page.
`staff`	Entered by hand by BallotData staff.
`data_load`	Loaded in one of our researched data passes.

Endorsement stage

In stage on Pick, Endorsement, EndorsementDetail, CandidateEndorsement. Worked out from the type of the election the contest is in.

Value	Meaning
`general`	The endorsement is for a general, special or consolidated election.
`primary`	The endorsement is for a primary or special primary.
`runoff`	The endorsement is for a runoff.

Change

In HistoryEntry.change, Change.change, types= on the stream and Filter.types.

Value	Meaning
`created`	A new endorsement.
`updated`	An existing endorsement changed; changed lists the fields.
`deleted`	The endorsement was withdrawn by the endorser or removed by us.

Changed field

In HistoryEntry.changed, Change.changed and Event.changed.

Value	Meaning
`choice_id`	The endorser now backs a different choice in the same contest.
`rank`	The ranked-choice rank changed.
`statement`	What the endorser said changed.
`source_url`	Where it was published changed.
`published_on`	The publication date changed.

Event type

In Event.type and the event: line of GET /v1/stream.

Value	Meaning
`endorsement.created`	A new endorsement.
`endorsement.updated`	An endorsement changed; changed and previous say how.
`endorsement.deleted`	An endorsement was withdrawn or removed.

Party (open)

In Party.slug and party (export CSV, as the name). Every party in our data, by slug, with its name and the abbreviation printed on ballots. A choice’s party_label has the party text exactly as printed where it differs.

Value	Meaning
`conservative`	Conservative (CON).
`constitution`	Constitution (CON).
`dc-statehood-green`	DC Statehood Green (STG).
`democratic`	Democratic (DEM).
`green`	Green (GRN).
`independent-american`	Independent American (IAP).
`independent-party`	Independent Party (IP).
`independent-party-of-delaware`	Independent Party of Delaware (IPD).
`independent-party-of-oregon`	Independent Party of Oregon (IPO).
`legal-marijuana-now`	Legal Marijuana NOW (LMN).
`libertarian`	Libertarian (LIB).
`pacific-green`	Pacific Green (PGP).
`progressive`	Progressive (PRO).
`progressive-party-of-oregon`	Progressive Party (PRO).
`republican`	Republican (REP).
`working-families`	Working Families (WFP).

Contact source kind

In Contact.sources[].kind.

Value	Meaning
`wikidata`	Wikidata (CC0): website and social accounts.
`open_states`	Open States (CC0): an incumbent’s official email, phone, website and social accounts.
`fec_filing`	The campaign committee’s Federal Election Commission filing: its mailing address.
`official_filing`	A state, county or city candidate list or campaign-finance filing.
`campaign_website`	The campaign’s own website.

Issue (open)

In Issue.slug, IssuePosition.issue.slug and issues= on GET /v1/issue-positions. The issues we record candidates’ positions on. Each is a yes/no question that a position’s stance answers; GET /v1/issues has the full descriptions.

Value	Meaning
`abortion`	Abortion. Should abortion be legal in most or all cases?
`death-penalty`	Death penalty. Should the death penalty be allowed?
`guns`	Gun laws. Should gun laws be made stricter?
`immigration-enforcement`	Immigration enforcement. Should immigration enforcement be expanded, including large-scale deportations?
`path-to-citizenship`	Path to citizenship. Should some undocumented immigrants, such as those brought here as children, be able to earn legal status or citizenship?
`school-choice`	School choice. Should public money pay for private or religious school tuition (vouchers, education savings accounts, tax-credit scholarships)?
`public-school-funding`	Public school funding. Should funding for public K-12 schools be increased?
`social-security-medicare`	Social Security and Medicare. Should Social Security and Medicare benefits be protected from cuts?
`medicaid-snap`	Medicaid and SNAP. Should Medicaid and SNAP (food assistance) be protected from cuts and new eligibility limits such as work requirements?
`health-coverage`	Health coverage. Should government do more to provide health coverage (for example, keep enhanced ACA subsidies, expand Medicaid, or add a public option or Medicare for All)?
`climate-clean-energy`	Climate and clean energy. Should government act to cut greenhouse gas emissions and speed the shift to clean energy?
`taxes-high-earners`	Taxes on high earners and corporations. Should taxes be raised on high earners and corporations?
`minimum-wage`	Minimum wage. Should the minimum wage be raised?
`unions`	Labor unions. Should it be easier for workers to form unions and bargain collectively (for example, the PRO Act)?
`lgbtq-protections`	LGBTQ protections. Should LGBTQ people have legal protection from discrimination (for example, the Equality Act)?
`transgender-athletes`	Transgender athletes. Should school and college sports teams be limited by sex at birth?
`criminal-justice`	Criminal justice. Should criminal-justice policy focus more on reducing incarceration (for example, sentencing reform, bail reform, alternatives to jail)?
`marijuana`	Marijuana. Should recreational marijuana be legal?
`voter-id`	Voter ID and proof of citizenship. Should voters have to show photo ID to vote, or prove citizenship to register?
`tariffs`	Tariffs. Should the U.S. impose broad tariffs on imported goods?
`ukraine-aid`	Aid to Ukraine. Should the U.S. keep providing military aid to Ukraine?
`money-in-politics`	Money in politics. Should limits on money in politics be strengthened (for example, overturning Citizens United or banning corporate PAC money)?
`congress-stock-trading`	Stock trading by members of Congress. Should members of Congress be banned from trading individual stocks?

Stance

In IssuePosition.stance and stances= on GET /v1/issue-positions. The answer to the issue’s yes/no question (GET /v1/issues). null for a stated position that doesn’t answer it either way.

Value	Meaning
`supports`	Yes to the issue’s question.
`opposes`	No to the issue’s question.
`mixed`	Yes to part of it, or yes with limits the summary spells out.

Issue position source kind

In IssuePositionSource.kind.

Value	Meaning
`candidate_website`	The candidate’s own campaign site.
`voting_record`	An official roll-call vote record (Congress’s or a legislature’s).
`official_statement`	An official statement: a press release or a statement from their office.
`questionnaire`	A published candidate questionnaire.
`debate`	A debate.
`news`	News reporting quoting or describing the candidate.

Officeholder office

In Officeholder.office and offices= on GET /v1/officeholders.

Value	Meaning
`us_senator`	U.S. Senator.
`us_representative`	U.S. Representative, or a non-voting delegate.
`governor`	Governor (or D.C.’s mayor).
`lieutenant_governor`	Lieutenant governor.
`attorney_general`	State attorney general.
`secretary_of_state`	Secretary of state.
`chief_election_officer`	The state’s chief election officer, where that isn’t the secretary of state.
`treasurer`	State treasurer.
`auditor`	State auditor or comptroller.
`state_senator`	State senator (upper house).
`state_representative`	State representative, assemblymember or delegate (lower house).
`state_legislator`	A member of a one-house legislature (Nebraska).
`city_council`	A member of the Council of the District of Columbia.

Officeholder level

In Officeholder.level and levels= on GET /v1/officeholders.

Value	Meaning
`federal`	Congress.
`state`	A statewide office or the state legislature.
`city`	The Council of the District of Columbia.

Officeholder office classification (open)

In Officeholder.offices[].classification. From Open States.

Value	Meaning
`capitol`	The office at the capitol (or in Washington).
`district`	An office in the member’s district.
`home`	A home or personal address the member lists for constituents.
`capitol-mail`	A mailing address for the capitol office, where it differs from the street address.
`district-mail`	A mailing address for the district office, where it differs from the street address.
`primary`	The member’s main office, where the legislature doesn’t say capitol or district.

Language

In lang= on data endpoints.

Value	Meaning
`en`	English (the default).
`es`	Spanish ballot text (titles, choices, measure text, statements) where the state publishes it; English where it doesn’t. Names are never translated.

Export format

In format= on GET /v1/elections/{slug}/export.

Value	Meaning
`json`	One JSON document: the election, then every contest with its choices, result and every endorser’s position (the default).
`csv`	One row per endorsement (a ranked-choice order is a row per rank), with its election, contest, district, choice and result. Contests with no endorsements have no rows.

Stream start

In from= on GET /v1/stream and GET /v1/events.

Value	Meaning
`latest`	Only changes from now on (the default).
`earliest`	The oldest change the stream still holds, up to 7 days back.

Error code

In Error.error.code. Every error response is { "error": { "code", "message", "request_id" } }. The HTTP status for each code is in the table.

Value	HTTP	Meaning
`missing_api_key`	401	No API key was sent. Send it as Authorization: Bearer <key> (or X-API-Key).
`invalid_api_key`	401	The key isn’t one we issued: mistyped, cut off, or from another site.
`revoked_api_key`	401	The key was revoked in the console. Use another key.
`expired_api_key`	401	The key passed the expiry date set on it.
`ip_not_allowed`	403	The key is limited to certain addresses and this request came from another.
`account_pending`	403	The account is waiting for approval.
`account_suspended`	403	The account is suspended. Write to us.
`account_closed`	403	The account is closed.
`insufficient_scope`	403	The key lacks the scope this endpoint needs (data:read, stream:read or subscriptions:write).
`no_access`	403	The account’s purchases don’t include this part of the API (the stream, for example), or they have ended.
`outside_purchase`	403	The record is in a state or election the account hasn’t bought. The message says what it does cover.
`invalid_parameter`	400	A parameter has a value we can’t use: the message names it.
`invalid_cursor`	400	The cursor isn’t one we gave out. Pass next_cursor back exactly as you got it.
`invalid_filter`	400	A stream filter parameter is invalid: the message says which.
`invalid_json`	400	The request body isn’t valid JSON.
`invalid_subscription`	400	The subscription’s name or filter is invalid: the message says which.
`body_too_large`	413	The request body is over 100 KB.
`not_found`	404	Nothing has that id or slug.
`subscription_not_found`	404	No subscription in your account has that id or name.
`conflict`	409	A subscription with that name already exists in your account.
`too_many_requests`	429	Too many requests from one address. Wait for Retry-After seconds.
`too_many_failures`	429	Too many requests with a missing or wrong key from one address. Wait for Retry-After seconds.
`rate_limit_exceeded`	429	Over your plan’s requests a minute. Wait for Retry-After seconds.
`daily_limit_exceeded`	429	Over your plan’s requests a day (the day is UTC).
`too_many_streams`	429	Your account already has as many streams open as its plan allows.
`cursor_expired`	410	The cursor or since time is older than the 7 days of changes the stream keeps. Start again with from=earliest, and catch up with GET /v1/changes.
`warming_up`	503	The stream is still loading on this server. Try again in a few seconds.
`server_busy`	503	This server has too many open streams. Try again.
`not_available`	503	This data isn’t loaded yet (officeholders, for example). Try again later.
`internal_error`	500	Something went wrong on our side. Quote request_id when you write to us.