> 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
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
}
```
---
# 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.