# 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) |

<details>

<summary>Example call</summary>

```
  GET /data/election_dates/ballot_measures?year=2024&state=CA
  x-api-key: YOUR_API_KEY
```

</details>

<details>

<summary>Example response</summary>

```json
{
  "success": true,
  "data": [
    { "state": "CA", "date": "2024-03-05" },
    { "state": "CA", "date": "2024-11-05" }
  ],
  "message": null
}
```

</details>

## /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) |

<details>

<summary>Example call</summary>

```
GET /data/ballot_measures?state=CA&election_date=2024-11-05
x-api-key: YOUR_API_KEY
```

</details>

<details>

<summary>Example response</summary>

```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": "<p>A \"<strong>yes</strong>\" vote&nbsp;<u>supported</u><u>:</u>&nbsp;</p><ul><li>repealing the&nbsp;<em>Costa-Hawkins Rental Housing Act</em>&nbsp;(1995),<em> </em>thereby<em>&nbsp;</em>allowing cities and counties to limit rent on any housing and limit the rent for first-time tenants and&nbsp;</li><li>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.\"</li></ul>",
            "no_vote": "<p>A \"<strong>no</strong>\" vote&nbsp;<u>opposed</u>&nbsp;repealing <em>Costa-Hawkins Rental Housing Act</em>, which prohibits rent control on single-family homes and houses completed after February 1, 1995.</p>",
            "official_title": "Proposition 33"
          }
        ]
      }
    ]
  },
  "message": null
}
```

</details>


---

# 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/ballot-measures-api/ballot-measures-endpoints.md?ask=<question>
```

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.