# /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: 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:
```
GET https://developer.ballotpedia.org/geographic-apis/election_dates.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.