> For the complete documentation index, see [llms.txt](https://developer.ballotpedia.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.ballotpedia.org/geographic-apis/election_dates.md).
# /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}
* *date*={YYYY-MM-DD}
* *page=*{number}
Example call with no optional parameters defined
```
https://api4.ballotpedia.org/data/election_dates/list
```
Example response
```json
{
"success": true,
"data": {
"total_pages": 205,
"elections": [
{
"id": 1068,
"date": "2018-01-02",
"type": "General",
"description": "Special election",
"candidate_lists_complete": true,
"district_name": "South Carolina House of Representatives District 56",
"district_type": "State Legislative (Lower)",
"state": "SC"
},
{
"id": 1057,
"date": "2018-01-09",
"type": "Primary",
"description": "Special primary election",
"candidate_lists_complete": true,
"district_name": "Oklahoma House of Representatives District 51",
"district_type": "State Legislative (Lower)",
"state": "OK"
},
{
"id": 1069,
"date": "2018-01-09",
"type": "General",
"description": "Special election",
"candidate_lists_complete": true,
"district_name": "Connecticut House of Representatives District 15",
"district_type": "State Legislative (Lower)",
"state": "CT"
},
{
"id": 1070,
"date": "2018-01-09",
"type": "General",
"description": "General election",
"candidate_lists_complete": true,
"district_name": "Georgia State Senate District 17",
"district_type": "State Legislative (Upper)",
"state": "GA"
},
{
"id": 1071,
"date": "2018-01-09",
"type": "General",
"description": "General election",
"candidate_lists_complete": true,
"district_name": "Georgia House of Representatives District 111",
"district_type": "State Legislative (Lower)",
"state": "GA"
},
{
"id": 1072,
"date": "2018-01-09",
"type": "Primary",
"description": "Special primary election",
"candidate_lists_complete": true,
"district_name": "New Hampshire House of Representatives Belknap 3",
"district_type": "State Legislative (Lower)",
"state": "NH"
},
{
"id": 1074,
"date": "2018-01-16",
"type": "General",
"description": "Special election",
"candidate_lists_complete": true,
"district_name": "Iowa House of Representatives District 6",
"district_type": "State Legislative (Lower)",
"state": "IA"
},
{
"id": 1075,
"date": "2018-01-16",
"type": "General",
"description": "Special election",
"candidate_lists_complete": true,
"district_name": "South Carolina House of Representatives District 28",
"district_type": "State Legislative (Lower)",
"state": "SC"
},
{
"id": 1076,
"date": "2018-01-16",
"type": "General",
"description": "Special election",
"candidate_lists_complete": true,
"district_name": "South Carolina House of Representatives District 99",
"district_type": "State Legislative (Lower)",
"state": "SC"
},
{
"id": 1077,
"date": "2018-01-16",
"type": "General",
"description": "Special election",
"candidate_lists_complete": true,
"district_name": "Wisconsin State Assembly District 58",
"district_type": "State Legislative (Lower)",
"state": "WI"
},
{
"id": 1078,
"date": "2018-01-16",
"type": "General",
"description": "Special election",
"candidate_lists_complete": true,
"district_name": "Wisconsin State Assembly District 66",
"district_type": "State Legislative (Lower)",
"state": "WI"
},
{
"id": 1079,
"date": "2018-01-16",
"type": "General",
"description": "Special election",
"candidate_lists_complete": true,
"district_name": "Wisconsin State Senate District 10",
"district_type": "State Legislative (Upper)",
"state": "WI"
},
{
"id": 1081,
"date": "2018-01-23",
"type": "General",
"description": "Special election",
"candidate_lists_complete": true,
"district_name": "Pennsylvania House of Representatives District 35",
"district_type": "State Legislative (Lower)",
"state": "PA"
},
{
"id": 22530,
"date": "2018-01-23",
"type": "Special",
"description": null,
"candidate_lists_complete": true,
"district_name": "Oregon",
"district_type": "State",
"state": "OR"
},
{
"id": 1082,
"date": "2018-01-25",
"type": "Primary",
"description": "Primary election",
"candidate_lists_complete": true,
"district_name": "Tennessee State Senate District 14",
"district_type": "State Legislative (Upper)",
"state": "TN"
},
{
"id": 1083,
"date": "2018-01-29",
"type": "Primary",
"description": "Special primary election",
"candidate_lists_complete": true,
"district_name": "Minnesota State Senate District 54",
"district_type": "State Legislative (Upper)",
"state": "MN"
},
{
"id": 1084,
"date": "2018-01-29",
"type": "Primary",
"description": "Special primary election",
"candidate_lists_complete": true,
"district_name": "Minnesota House of Representatives District 23B",
"district_type": "State Legislative (Lower)",
"state": "MN"
},
{
"id": 1085,
"date": "2018-01-30",
"type": "Primary",
"description": "Special primary election",
"candidate_lists_complete": true,
"district_name": "Florida State Senate District 31",
"district_type": "State Legislative (Upper)",
"state": "FL"
},
{
"id": 1088,
"date": "2018-02-06",
"type": "General",
"description": "Special election",
"candidate_lists_complete": true,
"district_name": "Missouri House of Representatives District 39",
"district_type": "State Legislative (Lower)",
"state": "MO"
},
{
"id": 1089,
"date": "2018-02-06",
"type": "General",
"description": "Special election",
"candidate_lists_complete": true,
"district_name": "Missouri House of Representatives District 97",
"district_type": "State Legislative (Lower)",
"state": "MO"
},
{
"id": 1090,
"date": "2018-02-06",
"type": "General",
"description": "Special election",
"candidate_lists_complete": true,
"district_name": "Missouri House of Representatives District 129",
"district_type": "State Legislative (Lower)",
"state": "MO"
},
{
"id": 1091,
"date": "2018-02-06",
"type": "General",
"description": "Special election",
"candidate_lists_complete": true,
"district_name": "Missouri House of Representatives District 144",
"district_type": "State Legislative (Lower)",
"state": "MO"
},
{
"id": 1239,
"date": "2018-02-06",
"type": "Primary",
"description": "Primary election",
"candidate_lists_complete": true,
"district_name": "Massachusetts State Senate 3rd Essex District",
"district_type": "State Legislative (Upper)",
"state": "MA"
},
{
"id": 1092,
"date": "2018-02-12",
"type": "General",
"description": "Special election",
"candidate_lists_complete": true,
"district_name": "Minnesota State Senate District 54",
"district_type": "State Legislative (Upper)",
"state": "MN"
},
{
"id": 1093,
"date": "2018-02-12",
"type": "General",
"description": "Special election",
"candidate_lists_complete": true,
"district_name": "Minnesota House of Representatives District 23B",
"district_type": "State Legislative (Lower)",
"state": "MN"
}
]
},
"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": {
"total_pages": 1,
"elections": [
{
"id": 22532,
"date": "2020-05-12",
"type": "Special",
"description": "Special election to fill unexpired term",
"candidate_lists_complete": true,
"district_name": "Wisconsin District 7",
"district_type": "Congress",
"state": "WI"
}
]
},
"message": null
}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developer.ballotpedia.org/geographic-apis/election_dates.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.