> 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/ballot-measures-api/ballot-measures-endpoints.md).

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

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