# Introduction The quilt of American democracy is highly varied and complex. Ballotpedia strives to create an intuitive data structure to serve the variety of elections across the country, but it still requires some special terminology and a few unique data structures. This site includes information about API syntax, key concepts, data dictionaries, and some details about common edge cases. *Navigate to either* [*Geographic APIs*](/geographic-apis/getting-started-with-geographic-apis) *or* [*Bulk Data*](/bulk-data/downloading-bulk-data-via-the-client-portal) *depending on your use case to learn more.* If you have any questions, please feel free to reach out to your Ballotpedia sales contact. # Getting started with geographic APIs Ballotpedia’s Geographic APIs allow anyone with an active API key to query the API endpoints. **Required parameters:** These parameters are required to successfully hit the endpoint. **Optional parameters:** These parameters are optional and accept one or more from the given comma separated list described under each endpoint. **Data points:** Not all data points may be returned as shown in the examples depending on your API package. **Changes:** We avoid making breaking changes to API endpoints or the structure of returned data without notice. New endpoints and data elements may be added at any time, but we alert our API customers via email 1 month in advance of small changes (like a field being renamed or its format changed) and 3 months in advance of larger changes (like data structure changes or endpoints being retired, etc.). We also avoid making such changes close to large elections to avoid disruptions. If you have questions about this policy, please contact **. All of the endpoints accept HTTP GET requests only. The following two HTTP headers must be included: ``` x-api-key: your_api_key Content-Type: application/json ``` Data will be JSON-formatted text, and successful queries will receive an HTTP 200 response. Unsuccessful queries will respond with an appropriate HTTP response code in the 4xx or 5xx type. {% hint style="warning" %} *Please note that in order to hit the following endpoints from an application on the internet, you must contact the Ballotpedia team to **whitelist** the domains from which those requests will originate. Requests from non-whitelisted origin domains will receive a preflight CORS permissions error. You are free to run test requests locally or in a non-cors context such as cURL, Postman, etc.* {% endhint %} ## Examples Via cURL: ``` curl "https://api4.ballotpedia.org/data/the-endpoint-name-and-options" -X GET -H 'x-api-key: your-api-key' -H 'Content-Type: application/json' ``` Via PHP: ```php $curl = curl_init(); curl_setopt_array($curl, array( CURLOPT_URL => 'https://api4.ballotpedia.org/data/the-endpoint-name-and-options', CURLOPT_RETURNTRANSFER => true, CURLOPT_ENCODING => '', CURLOPT_MAXREDIRS => 10, CURLOPT_TIMEOUT => 0, CURLOPT_FOLLOWLOCATION => true, CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1, CURLOPT_CUSTOMREQUEST => 'GET', CURLOPT_HTTPHEADER => array( 'Content-Type: application/json', 'x-api-key: your-api-key' ), )); $response = curl_exec($curl); curl_close($curl); echo $response; ``` Via JavaScript: ```javascript var myHeaders = new Headers(); myHeaders.append("Content-Type", "application/json"); myHeaders.append("x-api-key", "your-api-key"); var requestOptions = { method: 'GET', headers: myHeaders }; fetch("https://api4.ballotpedia.org/data/the-endpoint-name-and-options", requestOptions) .then(response => response.text()) .then(result => console.log(result)) .catch(error => console.log('error', error)); ``` ## Samples Download sample data sets: * * # About redistricting Redistricting is the act of redrawing a voting district's boundaries. 2020 was the last major redistricting cycle. Ballotpedia tracks which voting district boundary is in effect at a given time using start dates and end dates. The start date corresponds to the date when an officeholder swears into office, and the end date is the officeholder's last day in office. A voting district boundary's start and end dates do not necessarily, and usually do not, equal the election date for that office. Ballotpedia determines which voting district will be used for which race based on several factors, including the voting boundary's start and end dates; the race year; the election date; the race's swearing in date; and whether the race is a regular or special election. As an example, California's 22nd Congressional district has voting district boundaries with the following end dates. * Pre-2020 redistricting boundary end date: 2023-01-02 * Post-2020 redistricting boundary end date: null (implying it will be used for the foreseeable future) In 2022, California's 22nd Congressional district had a special election and regular election on the same date. How did we know which boundary would be used for each race? For the 2022 *special* election, we knew that the *pre-*redistricting voting boundary was used, because * It was a special election * The election date was *before* the boundary's end date For the 2022 *regular* election, we knew that the *post-*redistricting voting boundary was used, because the race's swearing in date was *after* the pre-redistricting boundary's end date. # /districts Voting districts endpoint Given a latitude and longitude point, a list of voting districts will be returned in which that point (address) lies. By default, the returned voting districts are in effect on the current date. An optional date parameter can be provided, which will show the districts which are/were in effect on that date. See the [About redistricting](/geographic-apis/about-redistricting) section for more details. **Required parameters:** *lat, long* **Optional parameters:** *date*
Example call ``` https://api4.ballotpedia.org/data/districts/point?lat=40.5550746&long=-74.27596989999999 ```
Example response ```json { "success": true, "data": [ { "id": "249", "name": "New Jersey District 6", "type": "Congress", "url": "https://ballotpedia.org/New_Jersey%27s_6th_Congressional_District", "ocdid": "ocd-division/country:us/state:nj/cd:6", "nces_id": null, "geo_id": "5001600US3406", "state": "NJ", "end_date": null, "precise_boundary": true }, { "id": "542", "name": "New Jersey", "type": "State", "url": "https://ballotpedia.org/New_Jersey", "ocdid": "ocd-division/country:us/state:nj", "nces_id": null, "geo_id": "0400000US34", "state": "NJ", "end_date": null, "precise_boundary": true }, { "id": "1794", "name": "New Jersey State Senate District 19", "type": "State Legislative (Upper)", "url": "https://ballotpedia.org/New_Jersey_State_Senate_District_19", "ocdid": "ocd-division/country:us/state:nj/sldu:19", "nces_id": null, "geo_id": "610U600US34019", "state": "NJ", "end_date": null, "precise_boundary": true }, { "id": "5625", "name": "New Jersey General Assembly District 19", "type": "State Legislative (Lower)", "url": "https://ballotpedia.org/New_Jersey_General_Assembly_District_19", "ocdid": "ocd-division/country:us/state:nj/sldl:19", "nces_id": null, "geo_id": "620L600US34019", "state": "NJ", "end_date": null, "precise_boundary": true }, { "id": "93743", "name": "United States", "type": "Country", "url": "https://ballotpedia.org/Federal_Politics", "ocdid": "ocd-division/country:us", "nces_id": null, "geo_id": "0100000US", "state": "US", "end_date": null, "precise_boundary": true } ], "message": null } ```
# /officeholders Current officeholders endpoint Given a latitude and longitude point, a list of current officeholders representing the point (address) will be returned with accompanying information and data points on the district, office, officeholder and person. **Required parameters:** *lat, long* **Optional parameters:** *collections=social,contact*
Example call ``` https://api4.ballotpedia.org/data/officeholders?long=-89.3818172&lat=43.079896&collections=contact ```
Example response ```json { "success": true, "data": [ { "elected_officials": { "districts": [ { "name": "Wisconsin District 2", "id": 430, "type": "Congress", "state": "WI", "precise_boundary": true, "offices": [ { "id": 10859, "name": "U.S. House Wisconsin District 2", "type": "Representative", "level": "Federal", "branch": "Legislative", "officeholders": [ { "id": 37193, "status": "Current", "name": "Mark Pocan", "last_name": "Pocan", "url": "https://ballotpedia.org/Mark_Pocan", "partisan_affiliation": 2, "officeholder_contact_information": [ { "contact": "202-225-2906", "contact_type": "Phone" }, { "contact": "https://pocan.house.gov/", "contact_type": "Website" } ], "person_contact_information": null } ] } ] }, { "name": "Wisconsin", "id": 562, "type": "State", "state": "WI", "precise_boundary": true, "offices": [ { "id": 401, "name": "Governor of Wisconsin", "type": "Governor", "level": "State", "branch": "Executive", "officeholders": [ { "id": 56270, "status": "Current", "name": "Tony Evers", "last_name": "Evers", "url": "https://ballotpedia.org/Tony_Evers", "partisan_affiliation": 2, "officeholder_contact_information": [ { "contact": "https://evers.wi.gov/pages/home.aspx", "contact_type": "Website" }, { "contact": "eversinfo@wisconsin.gov", "contact_type": "Email" }, { "contact": "608-266-1212", "contact_type": "Phone" } ], "person_contact_information": null } ] }, { "id": 9723, "name": "Attorney General of Wisconsin", "type": "Attorney General", "level": "State", "branch": "Executive", "officeholders": [ { "id": 294103, "status": "Current", "name": "Josh Kaul", "last_name": "Kaul", "url": "https://ballotpedia.org/Josh_Kaul", "partisan_affiliation": 2, "officeholder_contact_information": [ { "contact": "https://www.doj.state.wi.us/exec-profile/josh-kaul", "contact_type": "Website" }, { "contact": "Josh.Kaul@doj.state.wi.us", "contact_type": "Email" }, { "contact": "608-266-1221", "contact_type": "Phone" } ], "person_contact_information": null } ] }, { "id": 11813, "name": "U.S. Senate Wisconsin", "type": "Senator", "level": "Federal", "branch": "Legislative", "officeholders": [ { "id": 53821, "status": "Current", "name": "Tammy Baldwin", "last_name": "Baldwin", "url": "https://ballotpedia.org/Tammy_Baldwin", "partisan_affiliation": 2, "officeholder_contact_information": [ { "contact": "202-224-5653", "contact_type": "Phone" }, { "contact": "https://www.baldwin.senate.gov/", "contact_type": "Website" } ], "person_contact_information": null }, { "id": 48568, "status": "Current", "name": "Ronald Harold Johnson", "last_name": "Johnson", "url": "https://ballotpedia.org/Ron_Johnson_(Wisconsin)", "partisan_affiliation": 1, "officeholder_contact_information": [ { "contact": "ron_johnson@ronjohnson.senate.gov", "contact_type": "Email" }, { "contact": "202-224-5323", "contact_type": "Phone" }, { "contact": "https://www.ronjohnson.senate.gov/public/", "contact_type": "Website" } ], "person_contact_information": null } ] }, { "id": 21638, "name": "Wisconsin Secretary of State", "type": "Secretary of State", "level": "State", "branch": "Executive", "officeholders": [ { "id": 15676, "status": "Current", "name": "Douglas J. La Follette", "last_name": "Follette", "url": "https://ballotpedia.org/Douglas_La_Follette", "partisan_affiliation": 2, "officeholder_contact_information": [ { "contact": "statesec@wi.gov", "contact_type": "Email" }, { "contact": "608-266-8888", "contact_type": "Phone" } ], "person_contact_information": null } ] }, { "id": 14513, "name": "Lieutenant Governor of Wisconsin", "type": "Lieutenant Governor", "level": "State", "branch": "Executive", "officeholders": [ { "id": 36064, "status": "Current", "name": "Mandela Barnes", "last_name": "Barnes", "url": "https://ballotpedia.org/Mandela_Barnes", "partisan_affiliation": 2, "officeholder_contact_information": [ { "contact": "https://evers.wi.gov/ltgov/Pages/About_LG.aspx", "contact_type": "Website" }, { "contact": "ltgovernor@wisconsin.gov", "contact_type": "Email" }, { "contact": "608-266-3516", "contact_type": "Phone" } ], "person_contact_information": null } ] }, { "id": 20865, "name": "Wisconsin Superintendent of Public Instruction", "type": "Superintendent of Schools", "level": "State", "branch": "Executive", "officeholders": [ { "id": 335652, "status": "Current", "name": "Jill Underly", "last_name": "Underly", "url": "https://ballotpedia.org/Jill_Underly", "partisan_affiliation": 7, "officeholder_contact_information": [ { "contact": "608-520-0547", "contact_type": "Phone" }, { "contact": "https://dpi-transition.wi.gov/Pages/About.aspx", "contact_type": "Website" }, { "contact": "dpiinfo@dpi-transition.wi.gov", "contact_type": "Email" } ], "person_contact_information": [ { "contact": "underlyforwisconsin@gmail.com", "contact_type": "Email" } ] } ] }, { "id": 23727, "name": "Greenfield City Council District 4", "type": null, "level": "Local", "branch": "Legislative", "officeholders": null }, { "id": 32705, "name": "Milwaukee County Clerk of the Circuit Court", "type": null, "level": "Local", "branch": "Executive", "officeholders": null }, { "id": 10347, "name": "Wisconsin Supreme Court", "type": "Judge of court of last resort", "level": "State", "branch": "Judicial", "officeholders": [ { "id": 60167, "status": "Current", "name": "Ann Walsh Bradley", "last_name": "Bradley", "url": "https://ballotpedia.org/Ann_Walsh_Bradley", "partisan_affiliation": 7, "officeholder_contact_information": [ { "contact": "608-266-1886", "contact_type": "Phone" }, { "contact": "https://wicourts.gov/courts/supreme/justices/bradley.htm", "contact_type": "Website" } ], "person_contact_information": null }, { "id": 85877, "status": "Current", "name": "Rebecca Bradley", "last_name": "Bradley", "url": "https://ballotpedia.org/Rebecca_Bradley", "partisan_affiliation": 7, "officeholder_contact_information": [ { "contact": "608-266-1883", "contact_type": "Phone" }, { "contact": "https://wicourts.gov/courts/supreme/justices/rbradley.htm", "contact_type": "Website" } ], "person_contact_information": null }, { "id": 293943, "status": "Current", "name": "Rebecca Dallet", "last_name": "Dallet", "url": "https://ballotpedia.org/Rebecca_Dallet", "partisan_affiliation": 7, "officeholder_contact_information": [ { "contact": "608-266-1884", "contact_type": "Phone" }, { "contact": "https://wicourts.gov/courts/supreme/justices/dallet.htm", "contact_type": "Website" } ], "person_contact_information": null }, { "id": 61839, "status": "Current", "name": "Brian Hagedorn", "last_name": "Hagedorn", "url": "https://ballotpedia.org/Brian_Hagedorn", "partisan_affiliation": 7, "officeholder_contact_information": [ { "contact": "608-266-1885", "contact_type": "Phone" }, { "contact": "https://wicourts.gov/courts/supreme/justices/hagedorn.htm", "contact_type": "Website" } ], "person_contact_information": null }, { "id": 96029, "status": "Current", "name": "Jill Karofsky", "last_name": "Karofsky", "url": "https://ballotpedia.org/Jill_Karofsky", "partisan_affiliation": 7, "officeholder_contact_information": [ { "contact": "608-266-1882", "contact_type": "Phone" }, { "contact": "https://www.wicourts.gov/courts/supreme/justices/karofsky.htm", "contact_type": "Website" } ], "person_contact_information": null }, { "id": 84124, "status": "Current", "name": "Patience Drake Roggensack", "last_name": "Roggensack", "url": "https://ballotpedia.org/Patience_Roggensack", "partisan_affiliation": 7, "officeholder_contact_information": [ { "contact": "608-266-1888", "contact_type": "Phone" }, { "contact": "https://wicourts.gov/courts/supreme/justices/roggensack.htm", "contact_type": "Website" } ], "person_contact_information": null }, { "id": 60263, "status": "Current", "name": "Annette Ziegler", "last_name": "Ziegler", "url": "https://ballotpedia.org/Annette_Ziegler", "partisan_affiliation": 7, "officeholder_contact_information": [ { "contact": "annette.ziegler@wicourts.gov", "contact_type": "Email" }, { "contact": "608-266-1881", "contact_type": "Phone" }, { "contact": "https://wicourts.gov/courts/supreme/justices/ziegler.htm", "contact_type": "Website" } ], "person_contact_information": null } ] }, { "id": 7210, "name": "Wisconsin Treasurer", "type": "Treasurer", "level": "State", "branch": "Executive", "officeholders": [ { "id": 298061, "status": "Current", "name": "Sarah Godlewski", "last_name": "Godlewski", "url": "https://ballotpedia.org/Sarah_Godlewski", "partisan_affiliation": 2, "officeholder_contact_information": [ { "contact": "https://statetreasurer.wi.gov/Pages/About-Sarah.aspx", "contact_type": "Website" }, { "contact": "608-266-1714", "contact_type": "Phone" }, { "contact": "Treasurer@wisconsin.gov", "contact_type": "Email" } ], "person_contact_information": null } ] } ] }, { "name": "Wisconsin State Senate District 26", "id": 2452, "type": "State Legislative (Upper)", "state": "WI", "precise_boundary": true, "offices": [ { "id": 28870, "name": "Wisconsin State Senate District 26", "type": "Senator", "level": "State", "branch": "Legislative", "officeholders": [ { "id": 31647, "status": "Current", "name": "Kelda Roys", "last_name": "Roys", "url": "https://ballotpedia.org/Kelda_Roys", "partisan_affiliation": 2, "officeholder_contact_information": [ { "contact": "608-266-1627", "contact_type": "Phone" }, { "contact": "https://docs.legis.wisconsin.gov/2021/legislators/senate/2252", "contact_type": "Website" }, { "contact": "sen.roys@legis.wisconsin.gov", "contact_type": "Email" } ], "person_contact_information": null } ] } ] }, { "name": "Wisconsin State Assembly District 76", "id": 7302, "type": "State Legislative (Lower)", "state": "WI", "precise_boundary": true, "offices": [ { "id": 11319, "name": "Wisconsin State Assembly District 76", "type": "Representative", "level": "State", "branch": "Legislative", "officeholders": [ { "id": 330225, "status": "Current", "name": "Francesca Hong", "last_name": "Hong", "url": "https://ballotpedia.org/Francesca_Hong", "partisan_affiliation": 2, "officeholder_contact_information": [ { "contact": "608-266-5342", "contact_type": "Phone" }, { "contact": "https://docs.legis.wisconsin.gov/2021/legislators/assembly/2261", "contact_type": "Website" }, { "contact": "rep.hong@legis.wisconsin.gov", "contact_type": "Email" } ], "person_contact_information": null } ] } ] }, { "name": "Dane", "id": 13889, "type": "County", "state": "WI", "precise_boundary": true, "offices": null }, { "name": "Madison Metropolitan School District", "id": 28168, "type": "School District", "state": "WI", "precise_boundary": true, "offices": null }, { "name": "Wisconsin Court of Appeals District IV", "id": 63613, "type": "Judicial District", "state": "WI", "precise_boundary": false, "offices": null }, { "name": "Dane County Circuit Court, Wisconsin", "id": 63626, "type": "Judicial District", "state": "WI", "precise_boundary": true, "offices": null }, { "name": "Madison", "id": 92584, "type": "City-town", "state": "WI", "precise_boundary": true, "offices": null }, { "name": "Madison City Council District 2", "id": 95104, "type": "City-town subdivision", "state": "WI", "precise_boundary": true, "offices": null }, { "name": "Dane County Supervisor District 2", "id": 95124, "type": "County subdivision", "state": "WI", "precise_boundary": false, "offices": null }, { "name": "Sanders County Sewer District at Paradise", "id": 99105, "type": "Special district subdivision", "state": null, "precise_boundary": false, "offices": null } ] } } ], "message": null } ```
# /election\_dates Election dates by point or by state ## Election dates by point Given a latitude and longitude point, a list of election dates will be returned for the particular point (address) that have occurred 1 year in the past and will occur 1 year in the future according to today's date. **Required parameters:** *lat, long* **Optional parameters:** *none*
Example call ``` https://api4.ballotpedia.org/data/election_dates/point?lat=40.5550746&long=-74.27596989999999 ```
Example response ```json { "success": true, "data": { "elections": [ { "type": "General", "id": 18742, "date": "2020-11-03", "description": null }, { "type": "General", "id": 18775, "date": "2020-11-03", "description": "U.S. Presidential election" }, { "type": "General", "id": 22516, "date": "2021-11-02", "description": null } ] }, "message": null } ```
## Election dates by parameters Election dates can be queried via several parameters which will return data from 2018+ and several years into the future. Data is returned in an ascending matter according to date, with limits of 25 results per page. **Required parameters:** *none* **Optional parameters:** * *state=*{state abbreviation} * *type=*General,Primary,Special,Recall * *year=*{year} * *page=*{number}
Example call with no optional parameters defined ``` https://api4.ballotpedia.org/data/election_dates/list ```
Example response ```json { "success": true, "data": { "elections": [ { "date": "2018-01-02", "type": "General", "description": "Special election", "candidate_lists_complete": true, "state": "SC" }, { "date": "2018-01-02", "type": "Recall", "description": "https://ballotpedia.org/Andrew_Hamilton_recall,_Lake_Forest,_Ca", "candidate_lists_complete": true, "state": "CA" }, { "date": "2018-01-09", "type": "Recall", "description": "https://ballotpedia.org/Larry_Thomas_recall,_Washburn_City_Comm", "candidate_lists_complete": true, "state": "ND" }, { "date": "2018-01-09", "type": "Primary", "description": "Special primary election", "candidate_lists_complete": true, "state": "NH" }, { "date": "2018-01-09", "type": "General", "description": "General election", "candidate_lists_complete": true, "state": "GA" }, { "date": "2018-01-09", "type": "General", "description": "General election", "candidate_lists_complete": true, "state": "GA" }, { "date": "2018-01-09", "type": "General", "description": "Special election", "candidate_lists_complete": true, "state": "CT" }, { "date": "2018-01-09", "type": "Primary", "description": "Special primary election", "candidate_lists_complete": true, "state": "OK" }, { "date": "2018-01-09", "type": "General Runoff", "description": "Special election runoff for State Senate District 49", "candidate_lists_complete": true, "state": "MS" }, { "date": "2018-01-16", "type": "General", "description": "Special election", "candidate_lists_complete": true, "state": "SC" }, { "date": "2018-01-16", "type": "Recall", "description": "https://ballotpedia.org/Mayor_and_town_board_recall,_Rockvale,_", "candidate_lists_complete": true, "state": "CO" }, { "date": "2018-01-16", "type": "General", "description": "Special election", "candidate_lists_complete": true, "state": "WI" }, { "date": "2018-01-16", "type": "General", "description": "Special election", "candidate_lists_complete": true, "state": "WI" }, { "date": "2018-01-16", "type": "General", "description": "Special election", "candidate_lists_complete": true, "state": "WI" }, { "date": "2018-01-16", "type": "General", "description": "Special election", "candidate_lists_complete": true, "state": "SC" }, { "date": "2018-01-16", "type": "General", "description": "Special election", "candidate_lists_complete": true, "state": "SC" }, { "date": "2018-01-16", "type": "General", "description": "Special election", "candidate_lists_complete": true, "state": "IA" }, { "date": "2018-01-23", "type": "Special", "description": null, "candidate_lists_complete": true, "state": "OR" }, { "date": "2018-01-23", "type": "General", "description": "Special election", "candidate_lists_complete": true, "state": "PA" }, { "date": "2018-01-23", "type": "General", "description": "Local ballot measures", "candidate_lists_complete": true, "state": "CA" }, { "date": "2018-01-23", "type": "Recall", "description": "https://ballotpedia.org/Francisco_Ramirez_recall,_Hanford_City_", "candidate_lists_complete": true, "state": "CA" }, { "date": "2018-01-25", "type": "Primary", "description": "Primary election", "candidate_lists_complete": true, "state": "TN" }, { "date": "2018-01-29", "type": "Primary", "description": "Special primary election", "candidate_lists_complete": true, "state": "MN" }, { "date": "2018-01-29", "type": "Primary", "description": "Special primary election", "candidate_lists_complete": true, "state": "MN" }, { "date": "2018-01-30", "type": "Primary", "description": "Special primary election", "candidate_lists_complete": true, "state": "FL" } ] }, "message": null } ```
**Example call querying for all Special Elections that occurred in Wisconsin in 2020.**
Example call querying for all Special Elections that occurred in Wisconsin in 2020. ``` https://api4.ballotpedia.org/data/election_dates/list?state=WI&type=Special&year=2020&page=1 ```
Example response ```json { "success": true, "data": { "elections": [ { "date": "2020-05-12", "type": "Special", "description": "Special election to fill unexpired term", "candidate_lists_complete": false, "state": "WI" } ] }, "message": null } ```
# /elections\_by\_point Election ballots and results (candidates running) by point Given a latitude and longitude point and an election date, a list of candidates, ballot measures and races will be returned along with district, office, and person information for the particular point. Races with no official candidates are not returned. If the election date is in the future, a list of candidates and ballot measures are returned who are on the ballot in the upcoming election. If the election date is in the past, a list of candidates and ballot measures will be returned who were on the ballot for that past election. Results of the election will be returned if included in your API package. Including which candidates won/lost, vote totals, and which ballot measures were approved or defeated. **Required parameters:** *lat, long, election\_date* **Optional parameters:** *collections=social,contact*
Example call ``` https://api4.ballotpedia.org/data/elections_by_point?long=-88.72466949999999&lat=43.194246&election_date=2020-11-03 ```
Example response ```json { "success": true, "data": { "longitude": -88.72466949999999, "latitude": 43.194246, "elections": [ { "date": "2020-11-03", "candidate_lists_complete": true, "districts": [ { "id": 93743, "name": "United States", "type": "Country", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31729, "office": { "id": 1, "name": "President of the United States", "level": "Federal", "branch": "Executive", "chamber": null, "is_partisan": "Partisan all", "type": null, "seat": null, "url": null, "office_district": 93743 }, "office_district": 93743, "url": "https://ballotpedia.org/Presidential_election,_2020", "number_of_seats": 1, "year": 2020, "type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "General", "stage_party": null, "candidates": [ { "id": 54804, "fec_id": "P80001571", "race": 31729, "running_mate": "Mike Pence", "stage_party": null, "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 1610065, "ranked_choice_voting_rounds": [], "person": { "id": 15180, "name": "Donald Trump", "first_name": "Donald", "last_name": "Trump", "url": "https://ballotpedia.org/Donald_Trump" } }, { "id": 55042, "fec_id": "P00007864", "race": 31729, "running_mate": null, "stage_party": null, "party_affiliation": [ { "id": 5, "name": "Independent", "url": "https://ballotpedia.org/Independent" } ], "is_incumbent": false, "is_write_in": true, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": null, "ranked_choice_voting_rounds": [], "person": { "id": 312671, "name": "Kasey Wells", "first_name": "Kasey", "last_name": "Wells", "url": "https://ballotpedia.org/Kasey_Wells" } }, { "id": 59216, "fec_id": "P80000722", "race": 31729, "running_mate": "Kamala D. Harris", "stage_party": null, "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Won", "votes_for_cand": 1630673, "ranked_choice_voting_rounds": [], "person": { "id": 26709, "name": "Joe Biden", "first_name": "Joe", "last_name": "Biden", "url": "https://ballotpedia.org/Joe_Biden" } }, { "id": 59781, "fec_id": "P00012211", "race": 31729, "running_mate": "Angela Nicole Walker", "stage_party": null, "party_affiliation": [ { "id": 4, "name": "Green Party", "url": "https://ballotpedia.org/Green_Party" } ], "is_incumbent": false, "is_write_in": true, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": null, "ranked_choice_voting_rounds": [], "person": { "id": 21669, "name": "Howie Hawkins", "first_name": "Howie", "last_name": "Hawkins", "url": "https://ballotpedia.org/Howie_Hawkins" } }, { "id": 65308, "fec_id": "P00013524", "race": 31729, "running_mate": "Spike Cohen", "stage_party": null, "party_affiliation": [ { "id": 3, "name": "Libertarian Party", "url": "https://ballotpedia.org/Libertarian_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 38491, "ranked_choice_voting_rounds": [], "person": { "id": 322425, "name": "Jo Jorgensen", "first_name": "Jo", "last_name": "Jorgensen", "url": "https://ballotpedia.org/Jo_Jorgensen" } }, { "id": 65662, "fec_id": "P00013771", "race": 31729, "running_mate": "Amar Patel", "stage_party": null, "party_affiliation": [ { "id": 17, "name": "American Solidarity Party", "url": null } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 5258, "ranked_choice_voting_rounds": [], "person": { "id": 292603, "name": "Brian T. Carroll", "first_name": "Brian", "last_name": "Carroll", "url": "https://ballotpedia.org/Brian_T._Carroll" } }, { "id": 66060, "fec_id": "P00014209", "race": 31729, "running_mate": "William Mohr", "stage_party": null, "party_affiliation": [ { "id": 6, "name": "Constitution Party", "url": "https://ballotpedia.org/Constitution_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 5144, "ranked_choice_voting_rounds": [], "person": { "id": 292195, "name": "Don Blankenship", "first_name": "Don", "last_name": "Blankenship", "url": "https://ballotpedia.org/Don_Blankenship_(West_Virginia)" } }, { "id": 72757, "fec_id": "P00017202", "race": 31729, "running_mate": null, "stage_party": null, "party_affiliation": [ { "id": 5, "name": "Independent", "url": "https://ballotpedia.org/Independent" } ], "is_incumbent": false, "is_write_in": true, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": null, "ranked_choice_voting_rounds": [], "person": { "id": 312838, "name": "President Boddie", "first_name": "President", "last_name": "Boddie", "url": "https://ballotpedia.org/President_Boddie" } }, { "id": 76526, "fec_id": "P00015537", "race": 31729, "running_mate": "Claudeliah Roze", "stage_party": null, "party_affiliation": [ { "id": 21467, "name": "Becoming One Nation", "url": null } ], "is_incumbent": false, "is_write_in": true, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": null, "ranked_choice_voting_rounds": [], "person": { "id": 324666, "name": "Jade Simmons", "first_name": "Jade", "last_name": "Simmons", "url": "https://ballotpedia.org/Jade_Simmons" } } ] } ] }, { "id": 433, "name": "Wisconsin District 5", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31685, "office": { "id": 18366, "name": "U.S. House Wisconsin District 5", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 5th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_5th_Congressional_District", "office_district": 433 }, "office_district": 433, "url": "https://ballotpedia.org/Wisconsin%27s_5th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "General", "stage_party": null, "candidates": [ { "id": 65365, "fec_id": "H0WI05113", "race": 31685, "stage_party": null, "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Won", "votes_for_cand": 265434, "ranked_choice_voting_rounds": [], "person": { "id": 50408, "name": "Scott Fitzgerald", "first_name": "Scott", "last_name": "Fitzgerald", "url": "https://ballotpedia.org/Scott_Fitzgerald" } }, { "id": 65431, "fec_id": "H8WI05165", "race": 31685, "stage_party": null, "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 175902, "ranked_choice_voting_rounds": [], "person": { "id": 291468, "name": "Tom Palzewicz", "first_name": "Tom", "last_name": "Palzewicz", "url": "https://ballotpedia.org/Tom_Palzewicz" } } ] } ] }, { "id": 7263, "name": "Wisconsin State Assembly District 37", "type": "State Legislative (Lower)", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 49591, "office": { "id": 6123, "name": "Wisconsin State Assembly District 37", "level": "State", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "District 37", "url": "https://ballotpedia.org/Wisconsin_State_Assembly_District_37", "office_district": 7263 }, "office_district": 7263, "url": "https://ballotpedia.org/Wisconsin_State_Assembly_elections,_2020", "number_of_seats": 1, "year": 2020, "type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "General", "stage_party": null, "candidates": [ { "id": 87590, "fec_id": null, "race": 49591, "stage_party": null, "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 14142, "ranked_choice_voting_rounds": [], "person": { "id": 330171, "name": "Abigail Lowery", "first_name": "Abigail", "last_name": "Lowery", "url": "https://ballotpedia.org/Abigail_Lowery" } }, { "id": 87592, "fec_id": null, "race": 49591, "stage_party": null, "party_affiliation": [ { "id": 5, "name": "Independent", "url": "https://ballotpedia.org/Independent" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 1041, "ranked_choice_voting_rounds": [], "person": { "id": 330173, "name": "Stephen Ratzlaff Jr.", "first_name": "Stephen", "last_name": "Ratzlaff", "url": "https://ballotpedia.org/Stephen_Ratzlaff_Jr." } }, { "id": 87593, "fec_id": null, "race": 49591, "stage_party": null, "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Won", "votes_for_cand": 19406, "ranked_choice_voting_rounds": [], "person": { "id": 27978, "name": "John Jagler", "first_name": "John", "last_name": "Jagler", "url": "https://ballotpedia.org/John_Jagler" } } ] } ] } ] } ] }, "message": null } ```
### Ballot measures {% hint style="info" %} *When ballot measures are or were on the ballot, they will populate the ballot\_measures data point as an array for their respective district. Example below.* {% endhint %}
Example call ``` https://api4.ballotpedia.org/data/elections_by_point?long=-88.72466949999999&lat=43.194246&election_date=2020-04-07 ```
Example response ```json { "success": true, "data": { "longitude": -88.72466949999999, "latitude": 43.194246, "elections": [ { "date": "2020-04-07", "candidate_lists_complete": false, "districts": [ { "id": 562, "name": "Wisconsin", "type": "State", "precise_boundary": true, "ballot_measures": [ { "id": 10870, "name": "Wisconsin Marsy's Law Crime Victims Rights Amendment (April 2020)", "url": "https://ballotpedia.org/Wisconsin_Marsy%27s_Law_Crime_Victims_Rights_Amendment_(April_2020)", "status": "Approved", "type": "Legislatively referred constitutional amendment", "district": 562, "yes_vote": " A \"yes\" vote supported this measure to add specific rights of crime victims, together known as a Marsy's Law, to the Wisconsin Constitution. ", "no_vote": " A \"no\" vote opposed this measure to add specific rights of crime victims to the state constitution beyond those found in Section 9m of Article I of the Wisconsin Constitution. ", "official_title": "Question 1", "election_date": "2020-04-07", "yes_votes_total": 1107067, "no_votes_total": 371013 } ], "races": [ { "id": 42310, "office": { "id": 10347, "name": "Wisconsin Supreme Court", "level": "State", "branch": "Judicial", "chamber": null, "is_partisan": "Nonpartisan all", "type": "Judge of court of last resort", "seat": null, "url": "https://ballotpedia.org/Wisconsin_Supreme_Court", "office_district": 562 }, "office_district": 562, "url": "https://ballotpedia.org/Wisconsin_Supreme_Court_elections,_2020", "number_of_seats": 1, "year": 2020, "type": "Regular", "is_marquee": true, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "General", "stage_party": null, "candidates": [ { "id": 59733, "race": 42310, "stage_party": null, "party_affiliation": [ { "id": 7, "name": "Nonpartisan", "url": "https://ballotpedia.org/Nonpartisan" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 693134, "ranked_choice_voting_rounds": [], "person": { "id": 64913, "name": "Daniel Kelly", "first_name": "Daniel", "last_name": "Kelly", "url": "https://ballotpedia.org/Daniel_Kelly_(Wisconsin)" } }, { "id": 59783, "race": 42310, "stage_party": null, "party_affiliation": [ { "id": 7, "name": "Nonpartisan", "url": "https://ballotpedia.org/Nonpartisan" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Won", "votes_for_cand": 855573, "ranked_choice_voting_rounds": [], "person": { "id": 96029, "name": "Jill Karofsky", "first_name": "Jill", "last_name": "Karofsky", "url": "https://ballotpedia.org/Jill_Karofsky" } } ] } ] }, { "id": 63613, "name": "Wisconsin Court of Appeals District IV", "type": "Judicial District", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 50722, "office": { "id": 25941, "name": "Wisconsin Court of Appeals District IV", "level": "State", "branch": "Judicial", "chamber": null, "is_partisan": "Nonpartisan all", "type": null, "seat": "District IV", "url": null, "office_district": 63613 }, "office_district": 63613, "url": "https://ballotpedia.org/Wisconsin_intermediate_appellate_court_elections,_2020", "number_of_seats": 1, "year": 2020, "type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "General", "stage_party": null, "candidates": [ { "id": 68634, "race": 50722, "stage_party": null, "party_affiliation": [ { "id": 7, "name": "Nonpartisan", "url": "https://ballotpedia.org/Nonpartisan" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Won", "votes_for_cand": 341286, "ranked_choice_voting_rounds": [], "person": { "id": 314654, "name": "Rachel Graham", "first_name": "Rachel", "last_name": "Graham", "url": "https://ballotpedia.org/Rachel_Graham" } } ] } ] } ] } ] }, "message": null } ```
# /elections\_by\_state Election ballots and results (candidates running) by state Given a state and an election date, a list of candidates, ballot measures and races will be returned along with district, office, and person information for the entire state. Races with no official candidates are not returned. If the election date is in the future, a list of candidates and ballot measures are returned who are on the ballot in the upcoming election. If the election date is in the past, a list of candidates and ballot measures will be returned who were on the ballot for that past election. Results of the election will be returned if included in your API package. Including which candidates won/lost, vote totals, and which ballot measures were approved or defeated. **Required parameters:** *abbreviated state, election\_date* **Optional parameters:** * *collections*=social,contact * *office\_level*=Federal,State,Local * *office\_branch*=Legislative,Executive,Judicial * *district\_type*=Country,Congress,State,State Legislative (Upper),State Legislative (Lower),Judicial District,County,County subdivision,City-town,School District,State subdivision,Special district subdivision,Judicial district subdivision,Special District,City-town subdivision,School district subdivision * *page*={number} ### Example for statewide results Results for Wisconsin congressional offices on November 3rd, 2020...
Example call ``` https://api4.ballotpedia.org/data/elections_by_state?state=WI&election_date=2020-11-03&office_level=Federal ```
Example response ```json { "success": true, "data": { "election_date": "2020-11-03", "districts": [ { "id": 429, "name": "Wisconsin District 1", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31681, "office": { "id": 2462, "name": "U.S. House Wisconsin District 1", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 1st Congressional District", "url": "https://ballotpedia.org/Wisconsin's_1st_Congressional_District", "office_district": 429 }, "office_district": 429, "url": "https://ballotpedia.org/Wisconsin%27s_1st_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "General", "stage_party": null, "candidates": [ { "id": 86856, "race": 31681, "stage_party": null, "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Won", "votes_for_cand": 238271, "ranked_choice_voting_rounds": [], "person": { "id": 298470, "name": "Bryan Steil", "first_name": "Bryan", "last_name": "Steil", "url": "https://ballotpedia.org/Bryan_Steil" } }, { "id": 71354, "race": 31681, "stage_party": null, "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 163170, "ranked_choice_voting_rounds": [], "person": { "id": 322063, "name": "Roger Polack", "first_name": "Roger", "last_name": "Polack", "url": "https://ballotpedia.org/Roger_Polack" } } ] } ] }, { "id": 430, "name": "Wisconsin District 2", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31682, "office": { "id": 10859, "name": "U.S. House Wisconsin District 2", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 2nd Congressional District", "url": "https://ballotpedia.org/Wisconsin's_2nd_Congressional_District", "office_district": 430 }, "office_district": 430, "url": "https://ballotpedia.org/Wisconsin%27s_2nd_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "General", "stage_party": null, "candidates": [ { "id": 64770, "race": 31682, "stage_party": null, "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Won", "votes_for_cand": 318523, "ranked_choice_voting_rounds": [], "person": { "id": 37193, "name": "Mark Pocan", "first_name": "Mark", "last_name": "Pocan", "url": "https://ballotpedia.org/Mark_Pocan" } }, { "id": 86859, "race": 31682, "stage_party": null, "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 138306, "ranked_choice_voting_rounds": [], "person": { "id": 44392, "name": "Peter Theron", "first_name": "Peter", "last_name": "Theron", "url": "https://ballotpedia.org/Peter_Theron" } } ] } ] }, { "id": 431, "name": "Wisconsin District 3", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31683, "office": { "id": 6351, "name": "U.S. House Wisconsin District 3", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 3rd Congressional District", "url": "https://ballotpedia.org/Wisconsin's_3rd_Congressional_District", "office_district": 431 }, "office_district": 431, "url": "https://ballotpedia.org/Wisconsin%27s_3rd_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "General", "stage_party": null, "candidates": [ { "id": 69082, "race": 31683, "stage_party": null, "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Won", "votes_for_cand": 199870, "ranked_choice_voting_rounds": [], "person": { "id": 48575, "name": "Ronald James Kind", "first_name": "Ronald James", "last_name": "Kind", "url": "https://ballotpedia.org/Ron_Kind" } }, { "id": 78990, "race": 31683, "stage_party": null, "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 189524, "ranked_choice_voting_rounds": [], "person": { "id": 326054, "name": "Derrick Van Orden", "first_name": "Derrick", "last_name": "Van Orden", "url": "https://ballotpedia.org/Derrick_Van_Orden" } } ] } ] }, { "id": 432, "name": "Wisconsin District 4", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31684, "office": { "id": 3854, "name": "U.S. House Wisconsin District 4", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 4th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_4th_Congressional_District", "office_district": 432 }, "office_district": 432, "url": "https://ballotpedia.org/Wisconsin%27s_4th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "General", "stage_party": null, "candidates": [ { "id": 69083, "race": 31684, "stage_party": null, "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Won", "votes_for_cand": 232668, "ranked_choice_voting_rounds": [], "person": { "id": 20718, "name": "Gwen Moore", "first_name": "Gwen", "last_name": "Moore", "url": "https://ballotpedia.org/Gwen_Moore" } }, { "id": 86863, "race": 31684, "stage_party": null, "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 70769, "ranked_choice_voting_rounds": [], "person": { "id": 301297, "name": "Tim Rogers", "first_name": "Tim", "last_name": "Rogers", "url": "https://ballotpedia.org/Tim_Rogers_(Wisconsin)" } }, { "id": 86862, "race": 31684, "stage_party": null, "party_affiliation": [ { "id": 5, "name": "Independent", "url": "https://ballotpedia.org/Independent" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 7911, "ranked_choice_voting_rounds": [], "person": { "id": 47819, "name": "Robert Raymond", "first_name": "Robert", "last_name": "Raymond", "url": "https://ballotpedia.org/Robert_Raymond" } } ] } ] }, { "id": 433, "name": "Wisconsin District 5", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31685, "office": { "id": 18366, "name": "U.S. House Wisconsin District 5", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 5th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_5th_Congressional_District", "office_district": 433 }, "office_district": 433, "url": "https://ballotpedia.org/Wisconsin%27s_5th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "General", "stage_party": null, "candidates": [ { "id": 65431, "race": 31685, "stage_party": null, "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 175902, "ranked_choice_voting_rounds": [], "person": { "id": 291468, "name": "Tom Palzewicz", "first_name": "Tom", "last_name": "Palzewicz", "url": "https://ballotpedia.org/Tom_Palzewicz" } }, { "id": 65365, "race": 31685, "stage_party": null, "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Won", "votes_for_cand": 265434, "ranked_choice_voting_rounds": [], "person": { "id": 50408, "name": "Scott Fitzgerald", "first_name": "Scott", "last_name": "Fitzgerald", "url": "https://ballotpedia.org/Scott_Fitzgerald" } } ] } ] }, { "id": 434, "name": "Wisconsin District 6", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31686, "office": { "id": 3154, "name": "U.S. House Wisconsin District 6", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 6th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_6th_Congressional_District", "office_district": 434 }, "office_district": 434, "url": "https://ballotpedia.org/Wisconsin%27s_6th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "General", "stage_party": null, "candidates": [ { "id": 69084, "race": 31686, "stage_party": null, "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Won", "votes_for_cand": 238874, "ranked_choice_voting_rounds": [], "person": { "id": 20002, "name": "Glenn Grothman", "first_name": "Glenn", "last_name": "Grothman", "url": "https://ballotpedia.org/Glenn_Grothman" } }, { "id": 65708, "race": 31686, "stage_party": null, "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 164239, "ranked_choice_voting_rounds": [], "person": { "id": 25644, "name": "Jessica King", "first_name": "Jessica", "last_name": "King", "url": "https://ballotpedia.org/Jessica_King_(Wisconsin)" } } ] } ] }, { "id": 435, "name": "Wisconsin District 7", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31687, "office": { "id": 4951, "name": "U.S. House Wisconsin District 7", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 7th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_7th_Congressional_District", "office_district": 435 }, "office_district": 435, "url": "https://ballotpedia.org/Wisconsin%27s_7th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "General", "stage_party": null, "candidates": [ { "id": 86868, "race": 31687, "stage_party": null, "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Won", "votes_for_cand": 252048, "ranked_choice_voting_rounds": [], "person": { "id": 56044, "name": "Tom Tiffany", "first_name": "Tom", "last_name": "Tiffany", "url": "https://ballotpedia.org/Tom_Tiffany" } }, { "id": 85345, "race": 31687, "stage_party": null, "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 162741, "ranked_choice_voting_rounds": [], "person": { "id": 293245, "name": "Tricia Zunker", "first_name": "Tricia", "last_name": "Zunker", "url": "https://ballotpedia.org/Tricia_Zunker" } } ] } ] }, { "id": 436, "name": "Wisconsin District 8", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31688, "office": { "id": 16129, "name": "U.S. House Wisconsin District 8", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 8th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_8th_Congressional_District", "office_district": 436 }, "office_district": 436, "url": "https://ballotpedia.org/Wisconsin%27s_8th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "General", "stage_party": null, "candidates": [ { "id": 69085, "race": 31688, "stage_party": null, "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Won", "votes_for_cand": 268173, "ranked_choice_voting_rounds": [], "person": { "id": 39493, "name": "Mike Gallagher", "first_name": "Mike", "last_name": "Gallagher", "url": "https://ballotpedia.org/Michael_Gallagher_(Wisconsin)" } }, { "id": 60416, "race": 31688, "stage_party": null, "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 149558, "ranked_choice_voting_rounds": [], "person": { "id": 1287, "name": "Amanda Stuck", "first_name": "Amanda", "last_name": "Stuck", "url": "https://ballotpedia.org/Amanda_Stuck" } } ] } ] } ] }, "message": null } ```
### Partisan primaries {% hint style="info" %} When a race is a partisan primary, multiple objects will exist in the races array for the respective political party primary. This is defined as **stage\_party**. This applies to both the By Point and By State endpoints. Example below. {% endhint %}
Example call ``` https://api4.ballotpedia.org/data/elections_by_state?state=WI&election_date=2020-08-11 ```
Example response ```json { "success": true, "data": { "election_date": "2020-08-11", "districts": [ { "id": 429, "name": "Wisconsin District 1", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31681, "office": { "id": 2462, "name": "U.S. House Wisconsin District 1", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 1st Congressional District", "url": "https://ballotpedia.org/Wisconsin's_1st_Congressional_District", "office_district": 429 }, "office_district": 429, "url": "https://ballotpedia.org/Wisconsin%27s_1st_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": false, "stage_type": "Primary", "stage_party": "Democratic Party", "candidates": [ { "id": 62622, "race": 31681, "stage_party": "Democratic Party", "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 20608, "ranked_choice_voting_rounds": [], "person": { "id": 301301, "name": "Josh Pade", "first_name": "Josh", "last_name": "Pade", "url": "https://ballotpedia.org/Josh_Pade" } }, { "id": 71354, "race": 31681, "stage_party": "Democratic Party", "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 28697, "ranked_choice_voting_rounds": [], "person": { "id": 322063, "name": "Roger Polack", "first_name": "Roger", "last_name": "Polack", "url": "https://ballotpedia.org/Roger_Polack" } } ] }, { "id": 31681, "office": { "id": 2462, "name": "U.S. House Wisconsin District 1", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 1st Congressional District", "url": "https://ballotpedia.org/Wisconsin's_1st_Congressional_District", "office_district": 429 }, "office_district": 429, "url": "https://ballotpedia.org/Wisconsin%27s_1st_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Republican Party", "candidates": [ { "id": 86856, "race": 31681, "stage_party": "Republican Party", "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 40273, "ranked_choice_voting_rounds": [], "person": { "id": 298470, "name": "Bryan Steil", "first_name": "Bryan", "last_name": "Steil", "url": "https://ballotpedia.org/Bryan_Steil" } } ] } ] }, { "id": 430, "name": "Wisconsin District 2", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31682, "office": { "id": 10859, "name": "U.S. House Wisconsin District 2", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 2nd Congressional District", "url": "https://ballotpedia.org/Wisconsin's_2nd_Congressional_District", "office_district": 430 }, "office_district": 430, "url": "https://ballotpedia.org/Wisconsin%27s_2nd_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Democratic Party", "candidates": [ { "id": 64770, "race": 31682, "stage_party": "Democratic Party", "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 120353, "ranked_choice_voting_rounds": [], "person": { "id": 37193, "name": "Mark Pocan", "first_name": "Mark", "last_name": "Pocan", "url": "https://ballotpedia.org/Mark_Pocan" } } ] }, { "id": 31682, "office": { "id": 10859, "name": "U.S. House Wisconsin District 2", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 2nd Congressional District", "url": "https://ballotpedia.org/Wisconsin's_2nd_Congressional_District", "office_district": 430 }, "office_district": 430, "url": "https://ballotpedia.org/Wisconsin%27s_2nd_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Republican Party", "candidates": [ { "id": 86859, "race": 31682, "stage_party": "Republican Party", "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 18812, "ranked_choice_voting_rounds": [], "person": { "id": 44392, "name": "Peter Theron", "first_name": "Peter", "last_name": "Theron", "url": "https://ballotpedia.org/Peter_Theron" } } ] } ] }, { "id": 431, "name": "Wisconsin District 3", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31683, "office": { "id": 6351, "name": "U.S. House Wisconsin District 3", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 3rd Congressional District", "url": "https://ballotpedia.org/Wisconsin's_3rd_Congressional_District", "office_district": 431 }, "office_district": 431, "url": "https://ballotpedia.org/Wisconsin%27s_3rd_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Republican Party", "candidates": [ { "id": 74688, "race": 31683, "stage_party": "Republican Party", "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 18835, "ranked_choice_voting_rounds": [], "person": { "id": 323890, "name": "Jessi Ebben", "first_name": "Jessi", "last_name": "Ebben", "url": "https://ballotpedia.org/Jessi_Ebben" } }, { "id": 78990, "race": 31683, "stage_party": "Republican Party", "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 36395, "ranked_choice_voting_rounds": [], "person": { "id": 326054, "name": "Derrick Van Orden", "first_name": "Derrick", "last_name": "Van Orden", "url": "https://ballotpedia.org/Derrick_Van_Orden" } } ] }, { "id": 31683, "office": { "id": 6351, "name": "U.S. House Wisconsin District 3", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 3rd Congressional District", "url": "https://ballotpedia.org/Wisconsin's_3rd_Congressional_District", "office_district": 431 }, "office_district": 431, "url": "https://ballotpedia.org/Wisconsin%27s_3rd_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Democratic Party", "candidates": [ { "id": 69082, "race": 31683, "stage_party": "Democratic Party", "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 53064, "ranked_choice_voting_rounds": [], "person": { "id": 48575, "name": "Ronald James Kind", "first_name": "Ronald James", "last_name": "Kind", "url": "https://ballotpedia.org/Ron_Kind" } }, { "id": 71870, "race": 31683, "stage_party": "Democratic Party", "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 12765, "ranked_choice_voting_rounds": [], "person": { "id": 323092, "name": "Mark A. Neumann", "first_name": "Mark", "last_name": "Neumann", "url": "https://ballotpedia.org/Mark_Neumann_(Wisconsin_congressional_candidate)" } } ] } ] }, { "id": 432, "name": "Wisconsin District 4", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31684, "office": { "id": 3854, "name": "U.S. House Wisconsin District 4", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 4th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_4th_Congressional_District", "office_district": 432 }, "office_district": 432, "url": "https://ballotpedia.org/Wisconsin%27s_4th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Democratic Party", "candidates": [ { "id": 69083, "race": 31684, "stage_party": "Democratic Party", "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 68898, "ranked_choice_voting_rounds": [], "person": { "id": 20718, "name": "Gwen Moore", "first_name": "Gwen", "last_name": "Moore", "url": "https://ballotpedia.org/Gwen_Moore" } } ] }, { "id": 31684, "office": { "id": 3854, "name": "U.S. House Wisconsin District 4", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 4th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_4th_Congressional_District", "office_district": 432 }, "office_district": 432, "url": "https://ballotpedia.org/Wisconsin%27s_4th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Republican Party", "candidates": [ { "id": 86863, "race": 31684, "stage_party": "Republican Party", "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 6685, "ranked_choice_voting_rounds": [], "person": { "id": 301297, "name": "Tim Rogers", "first_name": "Tim", "last_name": "Rogers", "url": "https://ballotpedia.org/Tim_Rogers_(Wisconsin)" } }, { "id": 71872, "race": 31684, "stage_party": "Republican Party", "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 6598, "ranked_choice_voting_rounds": [], "person": { "id": 301298, "name": "Cindy Werner", "first_name": "Cindy", "last_name": "Werner", "url": "https://ballotpedia.org/Cindy_Werner" } } ] } ] }, { "id": 433, "name": "Wisconsin District 5", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31685, "office": { "id": 18366, "name": "U.S. House Wisconsin District 5", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 5th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_5th_Congressional_District", "office_district": 433 }, "office_district": 433, "url": "https://ballotpedia.org/Wisconsin%27s_5th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Democratic Party", "candidates": [ { "id": 65431, "race": 31685, "stage_party": "Democratic Party", "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 43710, "ranked_choice_voting_rounds": [], "person": { "id": 291468, "name": "Tom Palzewicz", "first_name": "Tom", "last_name": "Palzewicz", "url": "https://ballotpedia.org/Tom_Palzewicz" } } ] }, { "id": 31685, "office": { "id": 18366, "name": "U.S. House Wisconsin District 5", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 5th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_5th_Congressional_District", "office_district": 433 }, "office_district": 433, "url": "https://ballotpedia.org/Wisconsin%27s_5th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": true, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Republican Party", "candidates": [ { "id": 83219, "race": 31685, "stage_party": "Republican Party", "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 17829, "ranked_choice_voting_rounds": [], "person": { "id": 328083, "name": "Clifford DeTemple", "first_name": "Clifford", "last_name": "DeTemple", "url": "https://ballotpedia.org/Clifford_DeTemple" } }, { "id": 65365, "race": 31685, "stage_party": "Republican Party", "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 60676, "ranked_choice_voting_rounds": [], "person": { "id": 50408, "name": "Scott Fitzgerald", "first_name": "Scott", "last_name": "Fitzgerald", "url": "https://ballotpedia.org/Scott_Fitzgerald" } } ] } ] }, { "id": 434, "name": "Wisconsin District 6", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31686, "office": { "id": 3154, "name": "U.S. House Wisconsin District 6", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 6th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_6th_Congressional_District", "office_district": 434 }, "office_district": 434, "url": "https://ballotpedia.org/Wisconsin%27s_6th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Republican Party", "candidates": [ { "id": 69084, "race": 31686, "stage_party": "Republican Party", "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 52247, "ranked_choice_voting_rounds": [], "person": { "id": 20002, "name": "Glenn Grothman", "first_name": "Glenn", "last_name": "Grothman", "url": "https://ballotpedia.org/Glenn_Grothman" } } ] }, { "id": 31686, "office": { "id": 3154, "name": "U.S. House Wisconsin District 6", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 6th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_6th_Congressional_District", "office_district": 434 }, "office_district": 434, "url": "https://ballotpedia.org/Wisconsin%27s_6th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": false, "stage_type": "Primary", "stage_party": "Democratic Party", "candidates": [ { "id": 73552, "race": 31686, "stage_party": "Democratic Party", "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 7885, "ranked_choice_voting_rounds": [], "person": { "id": 323313, "name": "Michael Beardsley", "first_name": "Michael", "last_name": "Beardsley", "url": "https://ballotpedia.org/Michael_Beardsley" } }, { "id": 63649, "race": 31686, "stage_party": "Democratic Party", "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 4565, "ranked_choice_voting_rounds": [], "person": { "id": 317776, "name": "Matthew Boor", "first_name": "Matthew", "last_name": "Boor", "url": "https://ballotpedia.org/Matthew_Boor" } }, { "id": 65708, "race": 31686, "stage_party": "Democratic Party", "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 38039, "ranked_choice_voting_rounds": [], "person": { "id": 25644, "name": "Jessica King", "first_name": "Jessica", "last_name": "King", "url": "https://ballotpedia.org/Jessica_King_(Wisconsin)" } } ] } ] }, { "id": 435, "name": "Wisconsin District 7", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31687, "office": { "id": 4951, "name": "U.S. House Wisconsin District 7", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 7th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_7th_Congressional_District", "office_district": 435 }, "office_district": 435, "url": "https://ballotpedia.org/Wisconsin%27s_7th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Republican Party", "candidates": [ { "id": 86868, "race": 31687, "stage_party": "Republican Party", "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 62142, "ranked_choice_voting_rounds": [], "person": { "id": 56044, "name": "Tom Tiffany", "first_name": "Tom", "last_name": "Tiffany", "url": "https://ballotpedia.org/Tom_Tiffany" } } ] }, { "id": 31687, "office": { "id": 4951, "name": "U.S. House Wisconsin District 7", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 7th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_7th_Congressional_District", "office_district": 435 }, "office_district": 435, "url": "https://ballotpedia.org/Wisconsin%27s_7th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Democratic Party", "candidates": [ { "id": 85345, "race": 31687, "stage_party": "Democratic Party", "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 51139, "ranked_choice_voting_rounds": [], "person": { "id": 293245, "name": "Tricia Zunker", "first_name": "Tricia", "last_name": "Zunker", "url": "https://ballotpedia.org/Tricia_Zunker" } } ] } ] }, { "id": 436, "name": "Wisconsin District 8", "type": "Congress", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 31688, "office": { "id": 16129, "name": "U.S. House Wisconsin District 8", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 8th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_8th_Congressional_District", "office_district": 436 }, "office_district": 436, "url": "https://ballotpedia.org/Wisconsin%27s_8th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Republican Party", "candidates": [ { "id": 69085, "race": 31688, "stage_party": "Republican Party", "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 50176, "ranked_choice_voting_rounds": [], "person": { "id": 39493, "name": "Mike Gallagher", "first_name": "Mike", "last_name": "Gallagher", "url": "https://ballotpedia.org/Michael_Gallagher_(Wisconsin)" } } ] }, { "id": 31688, "office": { "id": 16129, "name": "U.S. House Wisconsin District 8", "level": "Federal", "branch": "Legislative", "chamber": "Lower", "is_partisan": "Partisan all", "type": "Representative", "seat": "Wisconsin's 8th Congressional District", "url": "https://ballotpedia.org/Wisconsin's_8th_Congressional_District", "office_district": 436 }, "office_district": 436, "url": "https://ballotpedia.org/Wisconsin%27s_8th_Congressional_District_election,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Democratic Party", "candidates": [ { "id": 60416, "race": 31688, "stage_party": "Democratic Party", "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 44793, "ranked_choice_voting_rounds": [], "person": { "id": 1287, "name": "Amanda Stuck", "first_name": "Amanda", "last_name": "Stuck", "url": "https://ballotpedia.org/Amanda_Stuck" } } ] } ] }, { "id": 2428, "name": "Wisconsin State Senate District 2", "type": "State Legislative (Upper)", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 49654, "office": { "id": 13559, "name": "Wisconsin State Senate District 2", "level": "State", "branch": "Legislative", "chamber": "Upper", "is_partisan": "Partisan all", "type": "Senator", "seat": "District 2", "url": "https://ballotpedia.org/Wisconsin_State_Senate_District_2", "office_district": 2428 }, "office_district": 2428, "url": "https://ballotpedia.org/Wisconsin_State_Senate_elections,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Democratic Party", "candidates": [ { "id": 92418, "race": 49654, "stage_party": "Democratic Party", "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": false, "is_write_in": true, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 286, "ranked_choice_voting_rounds": [], "person": { "id": 56305, "name": "Tony Lee", "first_name": "Tony", "last_name": "Lee", "url": "https://ballotpedia.org/Tony_Lee" } } ] }, { "id": 49654, "office": { "id": 13559, "name": "Wisconsin State Senate District 2", "level": "State", "branch": "Legislative", "chamber": "Upper", "is_partisan": "Partisan all", "type": "Senator", "seat": "District 2", "url": "https://ballotpedia.org/Wisconsin_State_Senate_District_2", "office_district": 2428 }, "office_district": 2428, "url": "https://ballotpedia.org/Wisconsin_State_Senate_elections,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Republican Party", "candidates": [ { "id": 86297, "race": 49654, "stage_party": "Republican Party", "party_affiliation": [ { "id": 1, "name": "Republican Party", "url": "https://ballotpedia.org/Republican_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 11224, "ranked_choice_voting_rounds": [], "person": { "id": 47327, "name": "Robert Cowles", "first_name": "Robert", "last_name": "Cowles", "url": "https://ballotpedia.org/Robert_Cowles" } } ] } ] }, { "id": 2430, "name": "Wisconsin State Senate District 4", "type": "State Legislative (Upper)", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 49655, "office": { "id": 28823, "name": "Wisconsin State Senate District 4", "level": "State", "branch": "Legislative", "chamber": "Upper", "is_partisan": "Partisan all", "type": "Senator", "seat": "District 4", "url": "https://ballotpedia.org/Wisconsin_State_Senate_District_4", "office_district": 2430 }, "office_district": 2430, "url": "https://ballotpedia.org/Wisconsin_State_Senate_elections,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Democratic Party", "candidates": [ { "id": 86299, "race": 49655, "stage_party": "Democratic Party", "party_affiliation": [ { "id": 2, "name": "Democratic Party", "url": "https://ballotpedia.org/Democratic_Party" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Advanced", "votes_for_cand": 16898, "ranked_choice_voting_rounds": [], "person": { "id": 34367, "name": "Lena Taylor", "first_name": "Lena", "last_name": "Taylor", "url": "https://ballotpedia.org/Lena_Taylor" } } ] }, { "id": 49655, "office": { "id": 28823, "name": "Wisconsin State Senate District 4", "level": "State", "branch": "Legislative", "chamber": "Upper", "is_partisan": "Partisan all", "type": "Senator", "seat": "District 4", "url": "https://ballotpedia.org/Wisconsin_State_Senate_District_4", "office_district": 2430 }, "office_district": 2430, "url": "https://ballotpedia.org/Wisconsin_State_Senate_elections,_2020", "number_of_seats": 1, "year": 2020, "race_type": "Regular", "is_marquee": false, "office_position": null, "is_ranked_choice": false, "results_certified": true, "stage_type": "Primary", "stage_party": "Republican Party", "candidates": null } ] } ] }, "message": null } ```
### **Ranked-choice voting** {% hint style="info" %} *When a race utilizes Ranked Choice Voting, **is\_ranked\_choice** will be true. The **ranked\_choice\_voting\_rounds** array will be populated with the candidate's round results. The **cand\_status** data point reflects their result at the end of the RCV voting. The **votes\_for\_cand** reflects the total number of votes throughout the rounds. This applies to both the By Point and By State endpoints in which the race uitilizes RCV. Example below.* {% endhint %}
Example response ```json { "id": 93938, "name": "San Francisco Board of Supervisors District 5", "type": "County subdivision", "precise_boundary": true, "ballot_measures": null, "races": [ { "id": 42896, "office": { "id": 12637, "name": "San Francisco Board of Supervisors District 5", "level": "Local", "branch": "Legislative", "chamber": null, "is_partisan": "Nonpartisan all", "type": "City council", "seat": "District 5", "url": null, "office_district": 93938 }, "office_district": 93938, "url": "https://ballotpedia.org/City_elections_in_San_Francisco,_California_(2019)", "number_of_seats": 1, "year": 2019, "race_type": "Special", "is_marquee": false, "office_position": null, "is_ranked_choice": true, "results_certified": true, "stage_type": "General", "stage_party": null, "candidates": [ { "id": 59977, "race": 42896, "stage_party": null, "party_affiliation": [ { "id": 7, "name": "Nonpartisan", "url": "https://ballotpedia.org/Nonpartisan" } ], "is_incumbent": true, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 11538, "ranked_choice_voting_rounds": [ { "rcv_round": 1, "votes_for": 11208, "status": "Advanced" }, { "rcv_round": 2, "votes_for": 51, "status": "Advanced" }, { "rcv_round": 3, "votes_for": 279, "status": "Lost" } ], "person": { "id": 304529, "name": "Vallie Brown", "first_name": "Vallie", "last_name": "Brown", "url": "https://ballotpedia.org/Vallie_Brown" } }, { "id": 59980, "race": 42896, "stage_party": null, "party_affiliation": [ { "id": 7, "name": "Nonpartisan", "url": "https://ballotpedia.org/Nonpartisan" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 1035, "ranked_choice_voting_rounds": [ { "rcv_round": 1, "votes_for": 950, "status": "Advanced" }, { "rcv_round": 2, "votes_for": 85, "status": "Advanced" }, { "rcv_round": 3, "votes_for": null, "status": "Lost" } ], "person": { "id": 314488, "name": "Ryan Lam", "first_name": "Ryan", "last_name": "Lam", "url": "https://ballotpedia.org/Ryan_Lam" } }, { "id": 59979, "race": 42896, "stage_party": null, "party_affiliation": [ { "id": 7, "name": "Nonpartisan", "url": "https://ballotpedia.org/Nonpartisan" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Lost", "votes_for_cand": 278, "ranked_choice_voting_rounds": [ { "rcv_round": 1, "votes_for": 278, "status": "Advanced" }, { "rcv_round": 2, "votes_for": null, "status": "Lost" }, { "rcv_round": 3, "votes_for": 0, "status": "Lost" } ], "person": { "id": 314487, "name": "Nomvula O'Meara", "first_name": "Nomvula", "last_name": "O'Meara", "url": "https://ballotpedia.org/Nomvula_O'Meara" } }, { "id": 59978, "race": 42896, "stage_party": null, "party_affiliation": [ { "id": 7, "name": "Nonpartisan", "url": "https://ballotpedia.org/Nonpartisan" } ], "is_incumbent": false, "is_write_in": false, "withdrew_still_on_ballot": false, "cand_status": "Won", "votes_for_cand": 11723, "ranked_choice_voting_rounds": [ { "rcv_round": 1, "votes_for": 11239, "status": "Advanced" }, { "rcv_round": 2, "votes_for": 70, "status": "Advanced" }, { "rcv_round": 3, "votes_for": 414, "status": "Won" } ], "person": { "id": 13552, "name": "Dean Preston", "first_name": "Dean", "last_name": "Preston", "url": "https://ballotpedia.org/Dean_Preston" } } ] } ] } ```
# /usage Check your current API usage against your plan's rate limit and quota. See also: [Rate limiting](/rate-limiting). Requires your API key, passed via the x-api-key header. **Required parameters:** *none* **Optional parameters:** *none*
Example call ``` https://api4.ballotpedia.org/data/usage ```
Example response ```json { "success": true, "data": { "limit": 200000, "used": 2203, "remaining": 197797, "period": "DAY", "period_start": "2026-07-20", "period_end": "2026-07-20", "throttle": { "rate_limit": 5, "burst_limit": 100 } }, "message": "Usage limit retrieved." } ```
## Details **Definitions:** * limit: The maximum number of requests allowed in the current quota period. * used: Requests made so far in the current period. * remaining: Requests remaining before you hit your quota. * period: The quota period your plan resets on: DAY, WEEK, or MONTH. * period\_start: Start date (UTC) of the current quota period. * period\_end: End date (UTC) covered by this response — today's date. * throttle.rate\_limit: Sustained requests per second your plan allows. * throttle.burst\_limit: Maximum burst of concurrent requests allowed above the rate limit. **Notes** * Use of this API does count against your usage limits. * Used/remaining counts reset every day at midnight UTC. If you have a specialized weekly or monthly quota, this may differ. * AWS quota systems are designed to handle large-scale operations, and as a result, there can be some latency in updating and propagating quota information across their systems. This delay can affect the accuracy of quota monitoring tools and functions. Delays of up to a half hour are not uncommon. # Practical guide This guide is intended for prospective and current API customers of Ballotpedia. We want to make it easy for you to understand and use the data we provide in our API; this document gives concrete examples for some real-world applications you might want to build using the API. ## Sample Ballot Application Suppose you want to provide a sample ballot lookup on your website. This can be accomplished by the following steps: 1. Find the user's location. Ultimately, you’ll need the latitude/longitude coordinates corresponding to the user’s location. This can be accomplished by asking the user to input their address, and using something like Google’s Geocoding API or the AWS Location service to convert that address to latitude/longitude coordinates. 2. With the user's lat/long, query the `/election_dates` endpoint. 3. With the user's lat/long and chosen election date, pass these parameters to the `/elections_by_point` endpoint. 4. Finally, display the results. Exactly how to do this is up to you, but now you have all the data you need to do it. You can loop over the districts, races, and candidates and display their names, party affiliations, link to their Ballotpedia profile, status, and much more. [*Click here to view Ballotpedia's Sample Ballot Tool*](https://ballotpedia.org/Sample_Ballot_Lookup) ## Current Representatives Application Suppose you want to allow users to look up their current elected officials. This can be accomplished by the following steps: 1. Find the user's location. Ultimately, you’ll need the latitude/longitude coordinates corresponding to the user’s location. This can be accomplished by asking the user to input their address, and using something like Google’s Geocoding API or the AWS Location service to convert that address to latitude/longitude coordinates. 2. Fetch the elected officials for the user’s location. Supply the latitude/longitude coordinates from the previous step into the `/officeholders` endpoint. 3. Display the results. This part is up to you, but now you have all the data you need to do it. You can loop over the districts, offices, and officeholders and display their names, party affiliations, link to their Ballotpedia profile, contact information, and much more. # Rate limiting ## Default limits This API is rate-limited using the token bucket algorithm. **Rate:** 5 requests per second * The 5 requests per second applies to how many requests can be initiated each second; the requests do not need to finish before more can be started at the 5 request per second rate. **Burst Capacity:** 100 requests * The burst capacity enables your application to temporarily exceed the 5 RPS limit by using pre-accumulated tokens. This allows for short spikes in traffic to be handled smoothly without triggering throttling, as long as tokens remain available in the burst bucket. * If you send fewer than 5 requests in a given second, burst tokens accumulate (up to 100), allowing for additional bursts in traffic. **Total Daily Quota**: 200k requests * The total number of requests allowed in a 24 hour period. ## **Throttling** If the request rate is exceeded, a response with HTTP 429 Too Many Requests is sent. To avoid throttling: * Keep steady usage at or below 5 requests per second. * Implement exponential backoff with retry logic to space out retries. ## **Higher Limits** If your application requires a higher sustained rate, burst capacity, or daily quota, please contact us. # Ballot measures endpoints Ballotpedia offers a ballot measures-only package, which includes access to the following two endpoints. Access requires an API key passed via the x-api-key request header. ## **/data/election\_dates/ballot\_measures** Returns all states and dates that have ballot measures for a given year. Use this to discover which election dates have ballot measure data before querying for details. | Parameter | Type | Required? | Description | | --------- | ------ | --------- | --------------------------------------------------------- | | year | string | Yes | Four-digit year (e.g. 2024) | | state | string | No | Two-letter state abbreviation to filter results (e.g. CA) |
Example call ``` GET /data/election_dates/ballot_measures?year=2024&state=CA x-api-key: YOUR_API_KEY ```
Example response ```json { "success": true, "data": [ { "state": "CA", "date": "2024-03-05" }, { "state": "CA", "date": "2024-11-05" } ], "message": null } ```
## /data/ballot\_measures Returns ballot measures grouped by district for a given state and election date. | Parameter | Type | Required? | Description | | -------------- | ------ | --------- | ----------------------------------------------------------------------- | | state | string | Yes | Two-letter state abbreviation to filter results (e.g. CA) | | election\_date | string | Yes | Election date in YYYY-MM-DD format | | district\_type | string | No | Comma-separated list of district types to filter by (e.g. State,County) |
Example call ``` GET /data/ballot_measures?state=CA&election_date=2024-11-05 x-api-key: YOUR_API_KEY ```
Example response ```json { "success": true, "data": { "election_date": "2024-11-05", "districts": [ { "id": 123, "name": "California", "type": "State", "ballot_measures": [ { "id": 23475, "name": "California Proposition 33, Prohibit State Limitations on Local Rent Control Initiative (2024)", "url": "https://ballotpedia.org/California_Proposition_33,_Prohibit_State_Limitations_on_Local_Rent_Control_Initiative_(2024)", "status": "Defeated", "yes_votes_total": 5979880, "no_votes_total": 8975542, "type": "Initiated state statute", "yes_vote": "

A \"yes\" vote supported: 

  • repealing the Costa-Hawkins Rental Housing Act (1995), thereby allowing cities and counties to limit rent on any housing and limit the rent for first-time tenants and 
  • adding language to state law to prohibit the state from limiting \"the right of any city, county, or city and county to maintain, enact or expand residential rent control.\"
", "no_vote": "

A \"no\" vote opposed repealing Costa-Hawkins Rental Housing Act, which prohibits rent control on single-family homes and houses completed after February 1, 1995.

", "official_title": "Proposition 33" } ] } ] }, "message": null } ```
# Downloading bulk data via the client portal Ballotpedia’s bulk data clients can access their data on-demand with our client portal at [https://clients.ballotpedia.org/](https://clients.ballotpedia.org/login). The data is refreshed every 24 hours. You may access your data through two methods, as described below: 1. Login with provided password and click to download latest file (detailed below) 2. Access latest data file via API (for technical users, see: [Downloading data via API](/bulk-data/downloading-bulk-data-via-api)) ## Basic instructions Login to the dashboard at with the provided email and password. Upon logging in, you’ll see a list of your available queries with the title and description. For each query, there are two available formats, JSON and CSV. Clicking on either of these buttons will begin the download process for the respective format.

example of client portal

Please contact Ballotpedia’s data sales team to request password changes. # Downloading bulk data via API Ballotpedia’s bulk data clients can access their data on-demand with our client portal at [https://clients.ballotpedia.org/](https://clients.ballotpedia.org/login). The data is refreshed every 24 hours. You may access your data through two methods, as described below: 1. Login with provided password and click to download latest file (for non-technical users) 2. Access latest data file via API (for technical users, [*see next page*](/bulk-data/downloading-bulk-data-via-api)) ## API instructions {% hint style="info" %} Contact Ballotpedia’s data sales staff to request such a key. {% endhint %} The API can be called directly by interacting with two endpoints. Please note that these endpoints can only be accessed from a non-CORS context. ``` GET https://api.ballotpedia.org/getQueryList ``` [
](https://api.ballotpedia.org/getQueryList)This endpoint will return an array of objects, each object represents a data set and contains the ID, Title and Description. The endpoint requires your API Key passed in as a header: ``` x-api-key: [your api key] ``` ### Examples

Example call using Postman

Example response with a single file: {% code overflow="wrap" %} ``` {"success":true,"data":[{"id":"1098","title":"Endorsements Sample for Data Clients","description":"List endorsements for 2020 candidates"}],"message":null} ``` {% endcode %} This endpoint will return a URL to the requested file: ``` POST https://api.ballotpedia.org/getQueryResults ``` The endpoint requires your API Key passed in the header as described above, the content type of application/json, and the ID (obtained from the getQueryList endpoint) of the data set and the format passed via the body in the POST request. \ **Headers** ``` x-api-key: [your api key] Content-Type: application/json ``` **Body** ``` { "id": "1098", "format": "json" } ``` To get the data to return in csv format, make the same call as for json data but change the format parameter from json to csv. ``` { "id": "1098", "format": "csv" } ```

Example call using Postman

\ Example Response: {% code overflow="wrap" %} ``` {"success":true,"data":{"url":"https://ballotpedia-data-clients.s3.amazonaws.com/metabase_query_results_1253.json?AWSAccessKeyId=XXXXXXXXXXXXXXX&Expires=XXXXXXX&Signature=XXXXXXXX"},"message":"Success"} ``` {% endcode %} {% hint style="warning" %} The URL for the downloadable file expires after 5 minutes. The URL returned should change with each call to getQueryResults. Files are re-generated daily, and the URL will always return only the last generated file. {% endhint %} # Rate limiting The bulk data APIs — /getQueryList and /getQueryResults endpoints — are rate-limited as follows. Please contact us if you require a higher limit. **Rate:** 5 requests per second * The 5 requests per second applies to how many requests can be initiated each second; the requests do not need to finish before more can be started at the 5 request per second rate. **Burst Capacity:** 10 requests * The burst capacity enables your application to temporarily exceed the 5 RPS limit by using pre-accumulated tokens. This allows for short spikes in traffic to be handled smoothly without triggering throttling, as long as tokens remain available in the burst bucket. **Total Daily Quota**: 50 requests * The total number of requests allowed in a 24 hour period. # About the Candidates data set ## Key concepts In American elections, there are often multiple stages, phases, or dates associated with a single race or contest. The most common pattern is that of a Primary that leads to a General election. The Primary and the General are what we refer to as distinct Stages, while all are part of the overarching Race or contest to determine who will hold that Office for the next term. Each row in our data set represents either one Candidate’s participation in one Stage, or, in the case of ranked-choice voting, one Candidate, Stage, and ranked-choice round. All candidates for a single contest can be grouped together by their Race ID; the results of any stage can be grouped together by Stage ID; and each candidate (campaign) will have the same Candidate ID for each row of data. In the example graphic below, Candidate A and Candidate B will each have two rows, while Candidate C will only have one. All those rows will have the same Race ID and each row for each candidate will use the same Candidate ID. The Stage ID and Stage Type will help distinguish the stages from each other.

Common election schema


## Common questions **How do I see all the races happening in one state on the same date?** Filter your data set on State and Election date. **Why am I seeing this candidate more than once for the same stage?** This could be due to Ranked-Choice Voting (RCV) or cross-filing. It might also be that the candidate was disqualified under one party and continued to seek the election as a write-in. Look at the two records and see how their parties and status attributes compare. **Why am I seeing a candidate marked as advanced from one stage but no row for their next stage?** If the stage was recently held, the record for their participation in the next stage may be pending creation. ## Edge cases and examples ### Cross-filing Cross-filing occurs when a candidate seeks office under more than one party. This is not allowed in all jurisdictions but is quite common in some states, such as New York and Pennsylvania. In these cases, the candidate will have more than one row in the dataset because of their running under multiple parties so long as they appear on the ballot for each party they run under. Imagine a candidate Luis Montega who is running for a local judgeship; he has cross-filed as a Democrat and a Republican. Montega will have a row for each party’s primary that he participates in as he will appear on the ballot twice in that stage. Though each stage will have its own Stages ID, they will share the same Race ID, and Montega will have the same Candidate ID in all stages. Montega might lose both primaries, advance from only one, or advance from both. If he loses both, he will not have any additional rows (again, excepting if he seeks to participate in the general as a write-in). If he advances under one or both parties, he will have an additional row for the general stage. If he advanced under both, he will be identified as running under both parties in that row.

Cross-filing schema illustration

\ The graphic above illustrates this for a whole race with cross-filing: Candidate A and Candidate B would have three rows in the dataset and Candidate C would only have one. All those rows will have the same Race ID and each row for each candidate will use the same Candidate ID. The Stage ID and Stage Type will help distinguish the stages from each other. \ [Fusion voting](https://ballotpedia.org/Fusion_voting) is a related practice that can lead to a candidate having more than one party associated with them in your dataset. ### Ranked-choice voting (RCV) [Ranked-choice voting (RCV)](https://ballotpedia.org/Ranked-choice_voting_\(RCV\)) is an electoral system in which voters rank candidates by preference on their ballots. If a candidate wins a majority of first-preference votes, he or she is declared the winner. If no candidate wins a majority of first-preference votes, the candidate with the fewest first-preference votes is eliminated. First-preference votes cast for the failed candidate are eliminated, lifting the second-preference choices indicated on those ballots. A new tally is conducted to determine whether any candidate has won a majority of the adjusted votes. The process is repeated until a candidate wins an outright majority. Ballotpedia reports each round of these results, so a candidate in an RCV will have a row for each round of calculation in that stage. The first round of results reported will have this attribute = 1. Rounds will count up until the final round so the ultimate outcome will always be the highest round number in the stage. For example, consider a race with four candidates using RCV. Voters ranked the candidates, and now we are trying to tally up a winner. The first round would look like this: | **Candidate** | **Ranked-choice voting round** | **Votes for** | **Votes against** | **Status** | | ------------- | ------------------------------ | ------------- | ----------------- | ---------- | | Candidate A | 1 | 2000 |


| Advanced | | Candidate B | 1 | 1800 |


| Advanced | | Candidate C | 1 | 1500 |


| Advanced | | Candidate D | 1 | 500 |


| Advanced | The candidates receive a status of advanced because they proceed to the next round of results calculation. None of our candidates received a majority of the first round, so the votes are redistributed in a second round. Note that some voters may not have marked a second preference and if their first preference (Candidate D) is disqualified at this point, their vote will not be transferred to any other candidates. | **Candidate** | **Ranked-choice voting round** | **Votes for** | **Votes against** | **Status** | | ------------- | ------------------------------ | ------------- | ----------------- | ---------- | | Candidate A | 2 | 100 |


| Advanced | | Candidate B | 2 | 300 |


| Advanced | | Candidate C | 2 | 75 |


| Advanced | | Candidate D | 2 |


| 500 | Lost | In this second round (and all subsequent rounds), we report the transferred votes, not a vote total for the candidate. In round 2, our disqualified candidate has all their votes transferred away from them and they now have a status of Lost that will be repeated in later rounds. The other candidates each receive votes as they were the second preference of the ballots cast for Candidate D. The vote totals for the candidates in this round (or any given subsequent round) can be found by summing their votes for and subtracting the sum of their votes against from those rounds (ex. Candidate A now has 2,100 votes). None of our candidates have a majority yet so we proceed to one more round where a winner can be determined: | **Candidate** | **Ranked-choice voting round** | **Votes for** | **Votes against** | **Status** | | ------------- | ------------------------------ | ------------- | ----------------- | ---------- | | Candidate A | 3 | 100 |


| Lost | | Candidate B | 3 | 700 |


| Won | | Candidate C | 3 |


| 1575 | Lost | | Candidate D | 3 |


|


| Lost | There are some variations on how RCV works. In some multi-seat races (rows in your dataset where the seats up for election is greater than 1), one candidate may meet the majority requirement in an earlier round and be declared won in that stage while the other winners require more rounds of calculation to determine. In other multi-seat RCVs, the rounds may be used to calculate a first winner and then repeated without that winner included to determine additional winners. ### Presidential elections Every four years, the presidential election presents a notable exception, in that it is a series of state-level Races for a single, national Office. Many candidates file to run for this office with the Federal Election Commission and are given the candidate status of “Candidacy Declared.” However, only a portion of those will go on to appear on the ballot and participate in the state- and party-specific Stages. In these cases, the same candidate will often appear in the data set many times – once for Iowa’s Republican Caucus, once for a third-party primary in Nebraska, once for the Illinois Republican Primary, etc. For those that make it to the general election, that still means they can appear in multiple, distinct Stages – one for each state that they or their political party qualified to run in. Note, too, that the delegates pledged attribute applies only to the Presidential race. # Data dictionary: Voting rules This document lists data points collected by Ballotpedia related to vote by mail and in-person voting for statewide elections. Ballotpedia defines statewide elections as elections meeting the following criteria: *all voters in the state can participate, and all offices or measures up for election are at either the state or federal level.* Data points are per-election, which may include statewide primaries, major party presidential preference primaries, general elections, and any applicable runoffs. ## Election Date *Depending on your subscription, you may see local election dates included with these basic attributes, but without the voting rules data provided for statewide elections (vote in person or vote by mail rules).* * election\_date * state * district\_type * election\_type * election\_description ## Vote by Mail ### Absentee/mail-in voting requirements * vote\_by\_mail:\_in-person\_request\_deadline * vote\_by\_mail:\_online\_request\_deadline * vote\_by\_mail:\_mail\_request\_deadline * vote\_by\_mail:\_mail\_request\_deadline\_type * vote\_by\_mail:\_in-person\_return\_deadline * vote\_by\_mail:\_mail\_return\_deadline * vote\_by\_mail:\_mail\_return\_deadline\_type ## Vote in Person ### Voter ID requirements * types\_of\_voter\_id\_accepted * required\_materials\_url\_english * required\_materials\_url\_spanish * voter\_id\_required\_for\_all * voter\_id\_source\_english * voter\_id\_source\_spanish * required\_materials ### Voter registration requirements * In-person deadline * Mail deadline * Mail registration deadline type * Online deadline * Election Day registration * Registration status URL English * Registration status URL Spanish * Registration update URL English * Registration update URL Spanish * Register online URL English * Register online URL Spanish ### Early voting * Early voting start date * Early voting end date ### Polling information * Poll times * Voting location URL English * Voting location URL Spanish * Voter info URL English * Voter info URL Spanish # Data dictionary: Officeholders The officeholders data set includes current, elected officeholders for Congress, statewide positions, state legislative positions, as well as elected officials in the [top 100 cities by population](https://ballotpedia.org/Largest_cities_in_the_United_States_by_population#America.27s_largest_cities). {% hint style="info" %} Ballotpedia also maintains a comprehensive directory of school board members across the U.S. Please inquire with our sales team for more information about this. {% endhint %} ## Office, District (Geography) | column\_name | description | | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | state | The state in which the office has jurisdiction (postal abbreviation) | | office\_id | Ballotpedia unique identifier (stable across officeholders) | | office\_name | Name of the office | | office\_level |

Level of government:

-Federal

-State

-Local

| | office\_branch |

Branch of government:

-Executive

-Legislative

-Judicial

| | district\_id | Ballotpedia unique identifier | | district\_ocdid | The[ Open Civic Data Division Identifiers](https://github.com/opencivicdata/ocd-division-ids) project seeks to assign somewhat predictable and globally unique identifiers to political divisions. This field is not uniformly filled due to data availability. | | district\_name | Name of district (geographical area) that elects the office. | | district\_type |

Type of district that elects the office:

-Country

-State

-Congress

-State Legislative (Upper)

-State Legislative (Lower)

-County

-School District

-City-town

-Judicial District

-Special District

-State subdivision

-County subdivision

-Judicial district subdivision

-Special district subdivision

-City-town subdivision

-School district subdivision

| | parent\_district\_id | Ballotpedia unique identifier used to associate a "subdivision" district with its parent (not comprehensive). Example: "X City Council, District 1" and "X City Council, District 2" have a parent district of "X City". | | parent\_district\_name | Name of parent district | ## Officeholder | column\_name | description | | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | | officeholder\_id | Ballotpedia unique identifier | | person\_id | Ballotpedia unique identifier (stable across time or offices held) | | name | Full name of the officeholder | | first\_name | First name of the officeholder | | last\_name | Last name of the officeholder | | url | Link to the Ballotpedia profile about this person | | gender |

One of the following, or NULL:

-Male

-Female

-Neither/Both (if the person explicitly identifies as neither or both of the above)

| | status |

Describes the status of the officeholder. One of the following:

-Current

-Acting

-Elect

-Magistrate

-Senior

| | party\_affiliation | Primarily for officeholders elected in partisan elections, this is the political party with which they are/were affiliated. | | date\_assumed\_office | Date on which they assumed this office (swearing in date or similar) | | appointed\_by | If relevant, the name of the person who appointed this officeholder to this office (such as a Governor) | | date\_appointed | Date of the appointment | | date\_confirmed | Date of the confirmation (judicial) | | date\_term\_ends | For former or outgoing officeholders, the date on which they left or will leave office | ## Contact information (add-on) *Contact information is optional, available for an additional charge.* Values are listed below. The "officeholder" contact is the one used in an official capacity, while "personal" represents contacts or accounts that may not relate to the person's current position. Values: * officeholder\_email * other\_email * officeholder\_website * personal\_website * officeholder\_facebook * personal\_facebook * officeholder\_x * personal\_x * officeholder\_tiktok * personal\_tiktok * officeholder\_instagram * personal\_instagram * officeholder\_youtube * personal\_youtube * office\_mailing\_address * officeholder\_phone * linkedin # Data dictionary: Ballot Measures | column\_name | description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | name | The name or title of this ballot measure, including year | | short\_name | Abbreviated name of measure | | district | Ballotpedia's unique district ID that this ballot measure covers | | district\_name | Name of district (typically a State) | | district\_type | Type of district | | ocdid | The[ Open Civic Data Division Identifiers](https://github.com/opencivicdata/ocd-division-ids) project seeks to assign somewhat predictable and globally unique identifiers to political divisions. This field is not uniformly filled due to data availability. | | election\_date | Date on which this measure will be on the ballot | | status |

The status of this ballot measure. For further detail on each of these, see status definitions below.

Options:

  • Proposed
  • Gathering signatures
  • Signatures submitted
  • Certified to the legislature
  • Qualified for the ballot
  • On the ballot
  • Approved
  • Defeated
  • Not on the ballot
  • Pending official review
  • Pending judicial ruling
  • Too close to call
| | type |

The type of this ballot measure

Options:

  • Advisory question
  • Amendment
  • Automatic ballot referral
  • Bond issue
  • Bond question
  • City charter amendment
  • Combined initiated constitutional amendment
  • Commission-referred ballot measure
  • Constitutional amendment
  • Indirect initiated state statute
  • Initiated amendment
  • Initiated amendment and statute
  • Initiated constitutional amendment
  • Initiated state statute
  • Initiative
  • Initiative to the Legislature
  • Initiative to the People
  • Legislative referral
  • Legislatively referred constitutional amendment
  • Legislatively referred state statute
  • Local
  • Referendum
  • Referral
  • Referred ordinance
  • Statute
  • State statute
  • Veto referendum
| | topics | One or more (semicolon-separated) topics this ballot measure covers | | summary | A summary of the measure | | yes\_vote | A custom explanation of what a YES vote means | | no\_vote | A custom explanation of what a NO vote means | | yes\_votes\_total | The number of YES votes this ballot measure received | | no\_votes\_total | The number of NO votes this ballot measure received | | ballot\_question | Text of the question to appear on the ballot. | | source | A URL to the source of election results | | url | The URL to a Ballotpedia page about this ballot measure |
## Ballot measure status definitions ### Pre-Certification * **Proposed** - The ballot measure has been proposed. * **Pending official review** - The ballot initiative has been filed with election officials but has not yet been cleared for signature gathering * **Cleared for signature gathering** - The ballot initiative has been cleared for signature gathering (campaigns can collect signatures). * **Pending judicial ruling pre-election** - Courts need to decide a case about the ballot measure before it can be certified for the ballot. * **Signatures submitted** - Signatures have been submitted for a ballot initiative and they are pending verification. ### Not on the ballot * **Not on the ballot** - The proposed ballot measure has failed to make the ballot. ### Indirect initiatives * **Certified to the legislature** - When signatures are verified for an [indirect initiative](https://ballotpedia.org/Indirect_initiated_state_statute), they are sent to the legislature before being certified for the ballot. This gives the legislature the option to pass an initiative outright, rather than having it go to voters. * **Approved by the legislature** - This is an indirect initiative that legislators approved. In other words, the initiative was enacted by the legislature, rather than voters. ### Certified for Ballot * **On the ballot** - The ballot measure has been certified for the ballot. * **Qualified for the ballot** - This is a technicality. The ballot measure hasn’t been certified for the ballot but has qualified for the ballot. In California, for example, citizen-initiated ballot measures qualify for the ballot after enough signatures have been verified. However, the secretary of state doesn’t declare they’re on the ballot until 131 days before the election. ### Post-Election Results: * **Approved** - Voters approved the ballot measure. * **Defeated** - Voters rejected the ballot measure. * **Too close to call** - The election has happened, but we have not called the measure approved or defeated. Like candidate elections, when results are close, sometimes you need to wait for 100% of precincts to report results and/or absentee ballots to be received. * **Pending judicial ruling post-election** - There are cases in which voters decide a ballot measure but whether the ballot measure results will be certified or not is dependent on a court ruling. In 2019, for example, a majority of voters approved Marsy’s Law in Pennsylvania. However, results were never certified pending a court ruling (and the court ultimately ruled that votes could not be certified). * **Overturned** - Voters approved the ballot measure, but courts later overturned the measure as unconstitutional or otherwise invalid. # Data dictionary: Candidates The tables below define each of the attributes you may receive in your dataset -- column name and description. ## Basic information | column name | description | | -------------- | -------------------------------------------------------------------- | | election\_year | The year the race is occuring | | state | The state in which the office has jurisdiction (postal abbreviation) | ## Office, District (Geography) | column name | description | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | office\_id | Ballotpedia unique identifier (stable across election years) | | office\_name | Name of the office | | office\_level |

Level of government:

-Federal

-State

-Local

| | office\_branch |

Branch of government:

-Executive

-Legislative

-Judicial

| | district\_id | Ballotpedia unique identifier | | district\_ocdid | The[ Open Civic Data Division Identifiers](https://github.com/opencivicdata/ocd-division-ids) project seeks to assign somewhat predictable and globally unique identifiers to political divisions. This field is not uniformly filled due to data availability. | | district\_name | Name of district (geographical area) that elects the office. | | district\_type |

Type of district that elects the office:

-Country

-State

-Congress

-State Legislative (Upper)

-State Legislative (Lower)

-County

-School District

-City-town

-Judicial District

-Special District

-State subdivision

-County subdivision

-Judicial district subdivision

-Special district subdivision

-City-town subdivision

-School district subdivision

-Township

| | parent\_district\_id | Ballotpedia unique identifier used to associate a "subdivision" district with its parent (not comprehensive). Example: "X City Council, District 1" and "X City Council, District 2" have a parent district of "X City". | | parent\_district\_name | Name of parent district |
## Race | column name | description | | ------------------------ | ----------------------------------------------------------------------------------------- | | race\_id | Ballotpedia unique identifier | | race\_type |

One of the following:

-Regular

-Special

-Recall

-Retention

| | seats\_up\_for\_election | The number of positions this race will fill in the office. | | race\_url | Link to the Ballotpedia overview page about this race/election. | ## Stage, Election Date | column name | description | | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | election\_date\_id | Ballotpedia unique identifier | | election\_date | The date that the stage contest is scheduled to appear before voters. | | election\_date\_district\_type | Often linked to the State, provides additional detail about which geographical area might be having an election at this time. | | stage\_id | Ballotpedia unique identifier (stable across ranked-choice voting rounds, if applicable). | | stage |

One of the following:

-Convention

-Primary

-Primary Runoff

-General

-General Runoff

| | stage\_party | For partisan primaries, provides a political party name. Each partisan primary or primary runoff will have its own stage. | | is\_partisan\_primary | true / false for Primary or Primary Runoff stages, where applicable. Otherwise NULL. This indicates whether candidates in the primary were limited by party (such as a traditional Republican or Democratic Party primary) or not (such as an open primary in California). More information here:[ https://ballotpedia.org/Primary\_election](https://ballotpedia.org/Primary_election) | | stage\_is\_canceled | true / false to indicate if the stage has been canceled | | stage\_is\_ranked\_choice | true / false to indicate if the stage is conducted by[ ranked-choice voting](https://ballotpedia.org/Ranked-choice_voting_\(RCV\)) | | stage\_write\_in\_other\_votes | Includes additional write-in votes for the stage (votes that are not associated with a particular candidate, but relevant to vote totals). | ## Candidate | column name | | | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | candidate\_id | Ballotpedia unique identifier | | person\_id | Ballotpedia unique identifier | | name | Full name of the candidate | | first\_name | First name of the candidate | | last\_name | Last name of the candidate | | ballotpedia\_url | Link to the Ballotpedia profile about this candidate | | gender |

One of the following, or NULL:

-Male

-Female

-Neither/Both (if the person explicitly identifies as neither or both of the above)

| | party\_affiliation |

The political party affiliation that the candidate is running under (one or more). If the candidate is cross-filed in a primary, they will have a row for their participation in each party’s primary they are running in and this field will indicate that party. If they advanced to a general under more than one party, all those parties will be listed in this field.


Party affiliation for candidates in nonpartisan elections is listed as "Nonpartisan".

| | is\_incumbent | true / false to indicate whether the candidate held the office they are seeking at the time of announcing their candidacy. See further details for how Ballotpedia handles appointees and redistricting situations here:[ https://ballotpedia.org/Incumbent](https://ballotpedia.org/Incumbent) | | candidate\_status |

-Candidacy Declared: announced a run for the office but has not yet qualified for the ballot


-On the Ballot: filing with election office is complete, and the election office has published the person as an official candidate


-Advanced: The candidate received the most votes (or was one of the top vote recipients in a race with more than one seat up for election) in this stage of the election (such as a primary) and is going on to further rounds (such as a general). Effectively, this indicates the winner of a stage when the full race is not yet complete. This also applies to RCV stages, where a candidate may advance from multiple rounds within a single stage.


-Won: The candidate received the most votes (or was one of the top vote recipients in a race with more than one seat up for election) and will assume office.


-Lost: The candidate did not advance to another stage (or RCV round) and/or did not garner enough votes to win the seat.


-Withdrew: The candidate withdrew from the election and will not appear on the ballot.

-Withdrew still on ballot: The candidate withdrew from the election but will still appear on the ballot (often in cases where the candidate announced intention to withdraw after the deadline).


-Disqualified: The candidate was disqualified from the election and will not appear on the ballot.

| | is\_write\_in | true / false to indicate if the candidate’s name was or will be printed on the ballot. Note that in some cases write-ins do file official paperwork and can thus have candidate\_status=On the ballot while is\_write\_in=true. | | is\_withdrawn\_still\_on\_ballot | true / false to capture scenarios where a candidate misses the official withdrawal deadline and will appear on the ballot despite announcing publicly their intent to withdraw | | votes\_for | Number of votes received in favor of the candidate in this stage (and RCV round, if applicable) | | votes\_against | Number of votes against the candidate. Only applicable to Recalls, Retentions, and RCVs. | | delegates\_pledged | Applicable to the general election for U.S. President | | ranked\_choice\_voting\_round | RCV results are reported in “rounds” of calculations. Ballotpedia reports each round of these results, so a candidate in an RCV stage will have a row for each round of calculation in that stage. The first round of results reported will be round "1". Rounds will count up by 1 until the final round. | | certified\_vote\_totals | TRUE / FALSE to indicate whether the vote totals for a given stage have been certified | ## Contact information (add-on) *Contact information is optional, available for an additional charge.* Values are listed below. The "campaign" contact is the one used by the candidate's campaign. All other contacts were identified as belonging to the candidate for non-campaign purposes. Values: * campaign\_email * other\_email * campaign\_website * personal\_website * campaign\_facebook * personal\_facebook * campaign\_x * personal\_x * campaign\_tiktok * personal\_tiktok * campaign\_instagram * personal\_instagram * campaign\_youtube * personal\_youtube * campaign\_mailing\_address * campaign\_phone * linkedin # Data dictionary: Endorsements There are two types of endorsements files — one for ballot measures and one for candidates. ## Candidate endorsements | column name | description | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | year | | | candidate\_id | The candidate that is receiving the endorsement (endorsee). This is a unique identifier that links to the candidates file. | | endorsement\_id | Unique identifier for this endorsement | | endorsement\_stage |

If the endorsement is relevant to a specific stage of the election, as opposed to the entire campaign, this can be defined here with one of the following values:
-Convention
-Primary
-Primary Runoff
-General
-General Runoff

Primarily, this is used to distinguish "General" from "Primary" endorsements.

| | endorser\_type |

May be one of the following categories, or NULL:
-Candidate
-Former Official
-Government-Federal Administration
-Government-Governors
-Government-Judicial
-Government-Local
-Government-Mayors
-Government-Other
-Government-President
-Government-State Representatives
-Government-State Senators
-Government-U.S. House
-Government-U.S. Senate
-Individual-Community Leader
-Individual-Other
-Media-Newspaper
-Media-Other
-Organization

| | endorser\_name | The person or organization that is making the endorsement | | endorser\_organizations\_id | Unique identifier if the endorsement is made by an organization | | endorser\_person\_id | Unique identifier if the endorsement is made by a person (individual) | | source | | | office\_level |

One of the following, based on the office sought by endorsee:
-Federal
-State
-Local
-ultralocal\*

\*This is a Ballotpedia-specific designation for local elected offices outside of the top 100 cities in the U.S. by population

| | office\_branch |

One of the following (or NULL), based on the office sought by endorsee:
-Executive
-Legislative
-Judicial

| | state | State postal abbreviation (i.e. "AL") | ## Ballot measure endorsements | column name | description | | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ballot\_measure\_id | Unique identifier that links to the ballot measure file | | support\_oppose | Either "Support" or "Oppose", where the latter means the endorser is campaigning against the measure. | | endorsement\_id | Unique identifier for this endorsement | | endorser\_type |

May be one of the following categories, or NULL:
-Candidate
-Former Official
-Government-Federal Administration
-Government-Governors
-Government-Judicial
-Government-Local
-Government-Mayors
-Government-Other
-Government-President
-Government-State Representatives
-Government-State Senators
-Government-U.S. House
-Government-U.S. Senate
-Individual-Community Leader
-Individual-Other
-Media-Newspaper
-Media-Other
-Organization

| | endorser\_name | The person or organization that is making the endorsement | | endorser\_organizations\_id | Unique identifier if the endorsement is made by an organization | | endorser\_person\_id | Unique identifier if the endorsement is made by a person (individual) | | source | | | election\_year | | | state | State postal abbreviation (i.e. "AL") | # Data dictionary: Campaign themes Campaign themes are quotes from the candidate, often gathered from campaign websites. These are returned as HTML as found in the original source. | column name | description | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------- | | candidate\_id | Ballotpedia's Candidate ID, as described in the Candidates data set | | quote | The quote, with accompanying HTML formatting | | source\_url | The website where the quote was found | | quote\_source\_type | Category for the source type, currently includes: *Website, Interview,* or *Forum*, but options may change. | | source\_date | When the source was published (media + candidate forums) OR when Ballotpedia accessed the campaign website source. YYYY-MM-DD | # Data dictionary: Candidate survey responses The candidate survey responses come from Ballotpedia's Candidate Connection questionnaire: . There are a few required questions and some optional questions. The required questions are: * *Who are you? Tell us about yourself.* * *Please list below 3 key messages of your campaign. What are the main points you want voters to remember about you and your candidacy?* * *What areas of public policy are you personally passionate about?* The survey questions are reviewed annually and may be adjusted. | column name | description | | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | candidate\_id | Ballotpedia's Candidate ID, as described in the Candidates data set | | election\_year | Numeric race year, i.e. "2026" | | state | The state in which the candidate is running (postal abbreviation), i.e. "AL" | | candidate\_name | Name of the candidate | | office\_name | Name of the office sought | | question | Survey question text | | response | Candidate's response to the question | | response\_date | Date response was received (YYYY-MM-DD). *Note that due to our review process, there is some delay between this date and the date on which the response appears in the file.* | # Terms of Use Ballotpedia content is copyrighted by Ballotpedia's editors and contributors. Licensed data sets are the proprietary and confidential property of Ballotpedia. Licensee shall take all reasonable precautions to preserve the confidentiality of Licensor's Software and Data and shall assume responsibility that its employees and assignees will similarly preserve this information against third parties. No right or license is being conveyed to Licensee to use or share the full data sets provided by Ballotpedia with any other company or individual. Data may be used in Licensee’s internal or external products as long as precautions are taken to protect Ballotpedia’s assets by preventing bulk downloads of the data set by third parties. The purchase of Ballotpedia data by Licensee constitutes acceptance of these terms. # Release notes 2026-05-31 These updates apply to *bulk data clients* whose accounts were set up after May 31, 2026. Current clients' data formats are maintained, but can be updated on request. Changes made to the bulk files going forward include: ## candidates * The certified\_vote\_totals boolean field was added indicating whether the vote totals for a given stage has been certified. * The candidate\_status field now distinguishes candidates who withdrew from the race but remain on the ballot: 'Withdrew still on ballot' * Races and stages that have no associated candidates will now appear with blank candidate data fields. Previously, these rows were excluded entirely. This ensures all stages are represented regardless of whether candidate data has been entered. ## officeholders * The officeholder\_mailing\_address column has been replaced by office\_mailing\_address, which now reflects the mailing address of the office rather than the individual officeholder. ## school board officeholders * The ballotpedia\_url field was removed, as pages are not yet published for individual school board officeholders. # Release notes 2026-09-25 These updates apply to the *elections\_by\_state* and *elections\_by\_point* endpoints. Additional "disclaimer" values will be provided where relevant, which provide further detail from Ballotpedia research staff about various edge cases and unique situations, either related to a whole Race, or one part of the Race (a Stage). Example: ``` "race_disclaimers": [ { "id": 26, "sort": 1, "text": "This special primary was scheduled to fill a vacancy in nomination due to the death of Lindsey Graham (R)." } ], "stage_disclaimers": [ { "id": 67, "sort": 1, "text": "Lorna Westlake withdrew from the general election after winning the Democratic primary. John Barbo was nominated to replace her on the general election ballot." } ], ``` In most cases, these values will be NULL.