# Ballotpedia API

> Ballotpedia returns statewide ballot measures and candidate profiles as a workflow and API.

List ballot measures returns statewide measures, election dates, topics, vote meanings, and results for a required state and year. Get candidate returns a candidate or officeholder profile, including election results and background, for a required name and optional state.

- Page: https://fous.com/tools/ballotpedia
- Handle: `@ballotpedia`
- Category: [Government](https://fous.com/tools/category/government)
- Source website: https://ballotpedia.org
- Last verified: Sep 29, 2026

## Methods

### Get candidate

Operation `get_candidate`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

Get a Ballotpedia candidate or officeholder profile by name, with election results, background, and published links. A state can narrow people with the same name; unreported details are left blank.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `name` | string | yes | `"Alexandria Ocasio-Cortez"` | Candidate or officeholder name, for example Alexandria Ocasio-Cortez. |
| `state` | string | no | `"Texas"` | Optional state name or two-letter code to distinguish candidates, for example New York or NY. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "name"
  ],
  "properties": {
    "name": {
      "type": "string",
      "description": "Candidate or officeholder name, for example Alexandria Ocasio-Cortez.",
      "examples": [
        "Alexandria Ocasio-Cortez",
        "John Smith",
        "Bernie Sanders"
      ]
    },
    "state": {
      "type": "string",
      "description": "Optional state name or two-letter code to distinguish candidates, for example New York or NY.",
      "examples": [
        "Texas"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "name": "Alexandria Ocasio-Cortez"
    },
    {
      "name": "John Smith",
      "state": "Texas"
    },
    {
      "name": "Bernie Sanders"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `party` | string or null | `"Democratic Party"` |  |
| `state` | string or null | `"New York"` |  |
| `biography` | string or null | `"Alexandria Ocasio-Cortez graduated from Boston University College of Arts & Sciences in 2011 with a Bachelor of Arts de` |  |
| `elections` | array |  |  |
| `elections[].year` | integer | `2026` |  |
| `elections[].stage` | string | `"Primary"` |  |
| `elections[].office` | string | `"U.S. House New York District 14"` |  |
| `elections[].result` | string | `"Won"` |  |
| `elections[].vote_percentage` | number or null | `86.9` |  |
| `elections[].ballotpedia_link` | string | `"https://ballotpedia.org/Alexandria_Ocasio-Cortez#2026"` |  |
| `full_name` | string | `"Alexandria Ocasio-Cortez"` |  |
| `photo_link` | string or null | `"https://s3.amazonaws.com/ballotpedia-api4/files/thumbs/200/300/Alexandria_Ocasio-Cortez.jpg"` |  |
| `office_since` | string or null | `"2019-01-03"` |  |
| `other_matches` | array |  |  |
| `other_matches[].name` | string | `"John Smith (Mart Independent School District, At-large, Texas, candidate 2025)"` |  |
| `other_matches[].ballotpedia_link` | string | `"https://ballotpedia.org/John_Smith_(Mart_Independent_School_District,_At-large,_Texas,_candidate_2025)"` |  |
| `current_office` | string | `"U.S. House New York District 14"` |  |
| `ballotpedia_link` | string | `"https://ballotpedia.org/Alexandria_Ocasio-Cortez"` |  |
| `campaign_website` | string or null | `"https://www.ocasiocortez.com"` |  |
| `official_website` | string or null | `"https://ocasio-cortez.house.gov/"` |  |
| `social_media_links` | array |  |  |
| `social_media_links[].link` | string | `"https://www.facebook.com/repAOC/"` |  |
| `social_media_links[].platform` | string | `"Facebook"` |  |
| `social_media_links[].account_type` | string | `"Official"` |  |
| `key_positions_or_campaign_themes` | array |  |  |

**Example input**

```json
{
  "name": "Alexandria Ocasio-Cortez"
}
```

**Example output**

```json
{
  "party": "Democratic Party",
  "state": "New York",
  "biography": "Alexandria Ocasio-Cortez graduated from Boston University College of Arts & Sciences in 2011 with a Bachelor of Arts degree in international relations and economics. She was a volunteer organizer for …",
  "elections": [
    {
      "year": 2026,
      "stage": "Primary",
      "office": "U.S. House New York District 14",
      "result": "Won",
      "vote_percentage": 86.9,
      "ballotpedia_link": "https://ballotpedia.org/Alexandria_Ocasio-Cortez#2026"
    },
    {
      "year": 2024,
      "stage": "General",
      "office": "U.S. House New York District 14",
      "result": "Won",
      "vote_percentage": 68.9,
      "ballotpedia_link": "https://ballotpedia.org/Alexandria_Ocasio-Cortez#2024"
    }
  ],
  "full_name": "Alexandria Ocasio-Cortez",
  "photo_link": "https://s3.amazonaws.com/ballotpedia-api4/files/thumbs/200/300/Alexandria_Ocasio-Cortez.jpg",
  "office_since": "2019-01-03",
  "other_matches": [],
  "current_office": "U.S. House New York District 14",
  "ballotpedia_link": "https://ballotpedia.org/Alexandria_Ocasio-Cortez",
  "campaign_website": "https://www.ocasiocortez.com",
  "official_website": "https://ocasio-cortez.house.gov/",
  "social_media_links": [
    {
      "link": "https://www.facebook.com/repAOC/",
      "platform": "Facebook",
      "account_type": "Official"
    },
    {
      "link": "https://x.com/RepAOC",
      "platform": "X",
      "account_type": "Official"
    }
  ],
  "key_positions_or_campaign_themes": [
    "During her campaign, Ocasio-Cortez said she supported policies including universal Medicare, free tuition for public college and trade school, 100% renewable energy, abolishing Immigration and Customs…"
  ]
}
```

### List ballot measures

Operation `list_ballot_measures`, version 1. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.

List statewide ballot measures in a US state and year, in Ballotpedia order, with election dates, topics, measure types, yes/no vote meanings and results. Years without statewide measures return an empty list.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `year` | integer | yes | `2026` | Election year, for example 2024. |
| `state` | string | yes | `"Nevada"` | US state name or two-letter code, for example California. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "state",
    "year"
  ],
  "properties": {
    "year": {
      "type": "integer",
      "description": "Election year, for example 2024.",
      "examples": [
        2026,
        2024,
        2023
      ]
    },
    "state": {
      "type": "string",
      "description": "US state name or two-letter code, for example California.",
      "examples": [
        "Nevada",
        "California",
        "Florida"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "year": 2026,
      "state": "Nevada"
    },
    {
      "year": 2024,
      "state": "California"
    },
    {
      "year": 2024,
      "state": "Florida"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `measures` | array |  | Statewide measures in the order listed by Ballotpedia. |
| `measures[].link` | string | `"https://ballotpedia.org/Nevada_Question_6,_Right_to_Abortion_Initiative_(2026)"` |  |
| `measures[].type` | string or null | `"Citizen-initiated constitutional amendment"` |  |
| `measures[].result` | string | `"upcoming"` |  |
| `measures[].topics` | array |  |  |
| `measures[].measure_name` | string | `"Nevada Question 6"` |  |
| `measures[].election_date` | string | `"2026-11-03"` |  |
| `measures[].no_vote_means` | string | `"A \"no\" vote opposes providing for a state constitutional right to an abortion, providing for the state to regulate ab` |  |
| `measures[].yes_vote_means` | string | `"A \"yes\" vote supports providing for a state constitutional right to an abortion, providing for the state to regulate ` |  |
| `measures[].no_vote_percentage` | number or null | `49.82` |  |
| `measures[].yes_vote_percentage` | number or null | `50.18` |  |

**Example input**

```json
{
  "year": 2026,
  "state": "Nevada"
}
```

**Example output**

```json
{
  "measures": [
    {
      "link": "https://ballotpedia.org/Nevada_Question_6,_Right_to_Abortion_Initiative_(2026)",
      "type": "Citizen-initiated constitutional amendment",
      "result": "upcoming",
      "topics": [
        "Constitutional rights",
        "Abortion"
      ],
      "measure_name": "Nevada Question 6",
      "election_date": "2026-11-03",
      "no_vote_means": "A \"no\" vote opposes providing for a state constitutional right to an abortion, providing for the state to regulate abortion after fetal viability , except where medically indicated to \"protect the lif…",
      "yes_vote_means": "A \"yes\" vote supports providing for a state constitutional right to an abortion, providing for the state to regulate abortion after fetal viability , except where medically indicated to \"protect the l…",
      "no_vote_percentage": null,
      "yes_vote_percentage": null
    },
    {
      "link": "https://ballotpedia.org/Nevada_Question_7,_Require_Voter_Identification_Initiative_(2026)",
      "type": "Citizen-initiated constitutional amendment",
      "result": "upcoming",
      "topics": [
        "Voter ID"
      ],
      "measure_name": "Nevada Question 7",
      "election_date": "2026-11-03",
      "no_vote_means": "A \"no\" vote opposes amending the constitution to require that Nevada residents present a form of photo identification to verify their identity while voting in person, or to verify their identity using…",
      "yes_vote_means": "A \"yes\" vote supports amending the constitution to require that Nevada residents present a form of photo identification to verify their identity while voting in person, or to verify their identity usi…",
      "no_vote_percentage": null,
      "yes_vote_percentage": null
    }
  ]
}
```

## Quick start

Replace `YOUR_API_KEY` with a Fous API key. To create one, open Developers at the bottom of Fous Studio, turn on Developer mode, then go to API keys (https://app.fous.com/keys). Change the values in `input` to run the same tool on new data.

```bash
curl 'https://api.fous.com/v1/query' \
  --fail-with-body --silent --show-error --max-time 180 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "api": "@ballotpedia",
  "visibility": "public",
  "operation": "get_candidate",
  "version": 1,
  "input": {
    "name": "Alexandria Ocasio-Cortez"
  },
  "response": {
    "format": "json"
  }
}'
```

```python
# Save as fous.py and run with python3 fous.py. No packages needed.
import json
import urllib.error
import urllib.request

api_key = "YOUR_API_KEY"

body = json.loads("{\n  \"api\": \"@ballotpedia\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_candidate\",\n  \"version\": 1,\n  \"input\": {\n    \"name\": \"Alexandria Ocasio-Cortez\"\n  },\n  \"response\": {\n    \"format\": \"json\"\n  }\n}")
request = urllib.request.Request(
    "https://api.fous.com/v1/query",
    data=json.dumps(body).encode("utf-8"),
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json",
    },
    method="POST",
)
try:
    with urllib.request.urlopen(request, timeout=180) as response:
        result = json.load(response)
except urllib.error.HTTPError as error:
    raise RuntimeError(f"HTTP {error.code}: {error.read().decode('utf-8', errors='replace')}") from error
if result.get("success") is False:
    raise RuntimeError(result.get("error", {}).get("message", "Request failed"))
print(json.dumps(result["data"]["output"], indent=2))
```

```typescript
// Save as fous.mts and run with npx tsx fous.mts.
const apiKey = "YOUR_API_KEY";

const response = await fetch("https://api.fous.com/v1/query", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  signal: AbortSignal.timeout(180_000),
  body: JSON.stringify({
  "api": "@ballotpedia",
  "visibility": "public",
  "operation": "get_candidate",
  "version": 1,
  "input": {
    "name": "Alexandria Ocasio-Cortez"
  },
  "response": {
    "format": "json"
  }
}),
});
type ApiResult = { success: boolean; data?: { output: unknown }; error?: { message: string } };
const result: ApiResult = await response.json();
if (!response.ok || result.success === false) {
  throw new Error(result.error?.message ?? `HTTP ${response.status}`);
}
if (!result.data) throw new Error("Missing API response data");
console.log(result.data.output);
```

## Use from an AI assistant

Connect this tool to Claude Code, Claude Desktop, Cursor, VS Code, Codex and any MCP client as its own MCP server. Each method is a typed tool whose arguments are the method’s input.

- Server URL: `https://api.fous.com/mcp/tools/ballotpedia`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `get_candidate`: Get candidate. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `list_ballot_measures`: List ballot measures. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `fous_get_run`: the result of a run that was still going, by its `request_id`. Free.

Claude Code:

```bash
claude mcp add --scope user --transport http fous-ballotpedia https://api.fous.com/mcp/tools/ballotpedia --header "Authorization: Bearer ${FOUS_API_KEY:?Set FOUS_API_KEY to your Fous API key}"
```

To give the assistant every tool, connect `https://api.fous.com/mcp`: it finds one with `fous_search_tools` and runs it with `fous_run_tool`. Setup for other clients: https://fous.com/llms-full.txt.

## Use cases

- Compare statewide measures across election years
- Review yes and no vote meanings and results
- Research candidates’ election histories
- Find candidate background and published links

## FAQ

### Can I run it with my own inputs?

Yes. Change the inputs in Studio and press Run, or send new inputs from your code, or ask a connected AI assistant.

### Can I call this Ballotpedia tool as an API?

Yes. Send a POST request to /v1/query with your Fous API key and the inputs, and get JSON back.

### How much does it cost?

Each completed run costs 1 credit. Failed runs without a completed receipt are free; completed work can remain charged if delivery is interrupted. With pay as you go, a credit costs 1¢. Monthly plans cost less per credit.

### Do I need a Ballotpedia account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from ballotpedia.org when you run it. Some results are reused for up to 24 hours, and results that use your account or key are never reused. It was last verified on Sep 29, 2026.

### What statewide measures appeared in a state and year?

List ballot measures returns statewide measures for a required state and year.

### How did a ballot measure vote turn out?

List ballot measures includes the measure’s result and yes and no vote percentages.

### What elections has a candidate participated in?

Get candidate returns election years, stages, offices, results, and vote percentages.

## Related

- [FEC API](https://fous.com/tools/fec.md): FEC provides federal campaign finance data, including candidate fundraising and spending for a two-year period and candidate totals from the latest available filings.
- [ElectionGuide API](https://fous.com/tools/electionguide.md): ElectionGuide provides worldwide election dates and information, including upcoming elections and referendums within six months and the latest held national election or referendum in a specified year, with results when published.
- [PolitiFact API](https://fous.com/tools/politifact.md): Fact checks of political claims and public statements.
- [IMDb API](https://fous.com/tools/imdb.md): IMDb returns movie, TV, person, episode, chart and Parents Guide details, including available weekly rank changes; missing details are null, and unaired or unrated episodes lack ratings.
- [MLB API](https://fous.com/tools/mlb.md): MLB provides scores, schedules and game details for one date or up to seven days, regular-season division standings defaulting to the current year, and player profiles with regular-season stats for a selected season and career.
- [Social Security Administration API](https://fous.com/tools/social-security-administration.md): The Social Security Administration reports annual U.S. baby-name ranks and counts nationwide since 1880 and by state since 1960; counts under five are withheld.
- [Congress.gov API](https://fous.com/tools/congress-gov.md): Congress.gov returns federal bills and resolutions matching topic, Congress, status, or chamber, and provides an individual bill’s status, summary, titles, actions, and related bills; summaries may be unavailable.
- [Yelp API](https://fous.com/tools/yelp.md): Yelp returns local business matches, public profiles, ratings and up to 60 publicly shown reviews; matches are unsponsored and Yelp-ordered, but later results may lack contact or location details.
- [All Government tools](https://fous.com/tools/category/government)