# ElectionGuide API

> ElectionGuide returns upcoming elections and national election results as a workflow and API.

List upcoming elections returns dates and statuses for elections and referendums within six months; filter by region or country. Get election results returns turnout and published results; provide a country, with an optional year and election category.

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

## Methods

### Get election results

Operation `get_election_results`, 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 country's most recent held national election or referendum in a year, including turnout and published candidate or party results. Some held elections do not have a published result breakdown; candidate party names may be unavailable.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `year` | integer | no | `2024` | Election year, for example 2025. Omit for the most recent held election. |
| `country` | string | yes | `"Germany"` | Country name, for example Germany. |
| `election_type` | string | no | `"presidential"` | Election category, for example legislative. Defaults to any. |

**Input schema**

```json
{
  "type": "object",
  "required": [
    "country"
  ],
  "properties": {
    "year": {
      "type": "integer",
      "maximum": 2100,
      "minimum": 1900,
      "description": "Election year, for example 2025. Omit for the most recent held election.",
      "examples": [
        2024,
        2018,
        2012
      ]
    },
    "country": {
      "type": "string",
      "description": "Country name, for example Germany.",
      "examples": [
        "Germany",
        "Ghana",
        "United States"
      ]
    },
    "election_type": {
      "enum": [
        "any",
        "presidential",
        "legislative",
        "referendum"
      ],
      "type": "string",
      "default": "any",
      "description": "Election category, for example legislative. Defaults to any.",
      "examples": [
        "presidential",
        "referendum"
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "country": "Germany"
    },
    {
      "year": 2024,
      "country": "Ghana",
      "election_type": "presidential"
    },
    {
      "year": 2018,
      "country": "Ghana",
      "election_type": "referendum"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `date` | string | `"2025-02-23"` |  |
| `link` | string | `"https://www.electionguide.org/elections/id/4574/"` |  |
| `note` | string or null | `"Candidate, party, or referendum option results are not published for this election on ElectionGuide."` |  |
| `country` | string | `"Germany"` |  |
| `results` | array |  |  |
| `results[].name` | string | `"Christian Democratic Union (CDU) (Christlich Demokratische Union Deutschlands)"` |  |
| `results[].party` | string or null | `"Christian Democratic Union (CDU) (Christlich Demokratische Union Deutschlands)"` |  |
| `results[].votes` | integer or null | `11194700` |  |
| `results[].seats_won` | integer or null | `164` |  |
| `results[].vote_share_percent` | number or null | `22.6` |  |
| `votes_cast` | integer or null | `49927315` |  |
| `election_name` | string | `"German Federal Diet"` |  |
| `election_type` | string | `"legislative"` |  |
| `turnout_percent` | number or null | `82.54` |  |
| `registered_voters` | integer or null | `60490603` |  |

**Example input**

```json
{
  "country": "Germany"
}
```

**Example output**

```json
{
  "date": "2025-02-23",
  "link": "https://www.electionguide.org/elections/id/4574/",
  "note": null,
  "country": "Germany",
  "results": [
    {
      "name": "Christian Democratic Union (CDU) (Christlich Demokratische Union Deutschlands)",
      "party": "Christian Democratic Union (CDU) (Christlich Demokratische Union Deutschlands)",
      "votes": 11194700,
      "seats_won": 164,
      "vote_share_percent": 22.6
    },
    {
      "name": "Alternative for Germany (Alternative für Deutschland)",
      "party": "Alternative for Germany (Alternative für Deutschland)",
      "votes": 10327148,
      "seats_won": 152,
      "vote_share_percent": 20.8
    },
    {
      "name": "Social Democratic Party",
      "party": "Social Democratic Party",
      "votes": 8148284,
      "seats_won": 120,
      "vote_share_percent": 16.4
    }
  ],
  "votes_cast": 49927315,
  "election_name": "German Federal Diet",
  "election_type": "legislative",
  "turnout_percent": 82.54,
  "registered_voters": 60490603
}
```

### List upcoming elections

Operation `list_upcoming_elections`, 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 upcoming elections and referendums in the next six months, with dates, statuses and links. Includes countries and territories listed by ElectionGuide.

**Input**

| Field | Type | Required | Example | Description |
|---|---|---|---|---|
| `region` | string | no | `"africa"` | Region to filter by, such as africa. |
| `country` | string | no | `"Brazil"` | Country name to filter by, such as Brazil. Leave blank for all countries. |
| `max_results` | integer | no | `100` | Maximum number of elections to return, such as 25. |

**Input schema**

```json
{
  "type": "object",
  "properties": {
    "region": {
      "enum": [
        "any",
        "africa",
        "americas",
        "asia_pacific",
        "europe",
        "middle_east"
      ],
      "type": "string",
      "default": "any",
      "description": "Region to filter by, such as africa.",
      "examples": [
        "africa"
      ]
    },
    "country": {
      "type": "string",
      "default": "",
      "description": "Country name to filter by, such as Brazil. Leave blank for all countries.",
      "examples": [
        "Brazil",
        "Atlantis"
      ]
    },
    "max_results": {
      "type": "integer",
      "default": 25,
      "maximum": 100,
      "minimum": 1,
      "description": "Maximum number of elections to return, such as 25.",
      "x-fous-developer": true,
      "examples": [
        100
      ]
    }
  },
  "additionalProperties": false,
  "examples": [
    {
      "country": "Brazil"
    },
    {},
    {
      "country": "Atlantis"
    }
  ]
}
```

**Output**

| Field | Type | Example | Description |
|---|---|---|---|
| `elections` | array |  |  |
| `elections[].link` | string | `"https://www.electionguide.org/elections/id/5091/"` |  |
| `elections[].type` | string | `"Presidential"` |  |
| `elections[].status` | string | `"Confirmed"` |  |
| `elections[].country` | string | `"Brazil"` |  |
| `elections[].election_date` | string | `"2026-10-04"` |  |
| `elections[].election_name` | string | `"Brazilian Presidency"` |  |

**Example input**

```json
{
  "country": "Brazil"
}
```

**Example output**

```json
{
  "elections": [
    {
      "link": "https://www.electionguide.org/elections/id/5091/",
      "type": "Presidential",
      "status": "Confirmed",
      "country": "Brazil",
      "election_date": "2026-10-04",
      "election_name": "Brazilian Presidency"
    },
    {
      "link": "https://www.electionguide.org/elections/id/5090/",
      "type": "Legislative - lower house",
      "status": "Confirmed",
      "country": "Brazil",
      "election_date": "2026-10-04",
      "election_name": "Brazilian Chamber of Deputies"
    },
    {
      "link": "https://www.electionguide.org/elections/id/5089/",
      "type": "Legislative - upper house",
      "status": "Confirmed",
      "country": "Brazil",
      "election_date": "2026-10-04",
      "election_name": "Brazilian Federal Senate"
    }
  ]
}
```

## 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": "@electionguide",
  "visibility": "public",
  "operation": "get_election_results",
  "version": 1,
  "input": {
    "country": "Germany"
  },
  "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\": \"@electionguide\",\n  \"visibility\": \"public\",\n  \"operation\": \"get_election_results\",\n  \"version\": 1,\n  \"input\": {\n    \"country\": \"Germany\"\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": "@electionguide",
  "visibility": "public",
  "operation": "get_election_results",
  "version": 1,
  "input": {
    "country": "Germany"
  },
  "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/electionguide`
- Authorization: `Authorization: Bearer <Fous API key>`

**Tools**

- `get_election_results`: Get election results. 1 credit per completed call. Failed calls without a completed billing receipt are free; completed work can remain charged if delivery is interrupted.
- `list_upcoming_elections`: List upcoming elections. 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-electionguide https://api.fous.com/mcp/tools/electionguide --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

- Track upcoming elections and referendums by country or region
- Review election dates and statuses across countries
- Compare published candidate or party votes, seats, and vote shares
- Monitor voter turnout and registered voters by election
- Find a country's most recent held national election

## 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 ElectionGuide 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 ElectionGuide account?

No. You only need a Fous account.

### How current is the data?

Fous gets the data from electionguide.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 elections are coming up in Brazil?

Use List upcoming elections with Brazil as the country to see scheduled elections and referendums, including dates and statuses.

### Who won a country's most recent national election?

Use Get election results with the country name to see published candidate or party results, when available.

### What was voter turnout for an election?

Use Get election results with the country and, optionally, the election year and category to see turnout when available.

## Related

- [TMDB API](https://fous.com/tools/tmdb.md): TMDB returns movie and TV details, cast, trailers, releases, viewing services, scheduled upcoming movies, and up to 20 homepage trending titles; future episode details depend on published schedules.
- [Ballotpedia API](https://fous.com/tools/ballotpedia.md): Ballotpedia provides state and local election information, ballot measure coverage, statewide measure details and results by year, and candidate and officeholder profiles with available background and election results.
- [Nager.Date API](https://fous.com/tools/nager-date.md): Nager.Date returns annual holiday calendars, long weekends, holiday or weekend checks, country details, and up to 50 upcoming holidays within 365 days; coverage varies.
- [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.
- [parkrun API](https://fous.com/tools/parkrun.md): Free community walking and running events and their public results.
- [Epic Games Store API](https://fous.com/tools/epic-games-store.md): Epic Games Store provides current and upcoming free games, plus game details including country-specific prices and sales; free-game availability varies by country.
- [World Bank API](https://fous.com/tools/world-bank.md): World Bank provides country statistics and latest values within selected years, plus country rankings for a chosen year or the latest broadly covered year.
- [Nike API](https://fous.com/tools/nike.md): Nike returns country-specific listings and details, including prices, sizes, availability and reviews, plus publicly shown upcoming or recently stocked SNKRS releases with local launch times.
- [All Government tools](https://fous.com/tools/category/government)