# Ballotpedia.org Scraper (`lexis-solutions/ballotpedia-org-scraper`) Actor

Scrape Ballotpedia.org political encyclopedia articles — ballot measures, legislation, lawsuits & electoral data. Extract structured JSON with title, URL & full text. Ideal for political research, news monitoring & content aggregation.

- **URL**: https://apify.com/lexis-solutions/ballotpedia-org-scraper.md
- **Developed by:** [Lexis Solutions](https://apify.com/lexis-solutions) (community)
- **Categories:** News, AI, Agents
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.90 / 1,000 articles

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).


# README

![Ballotpedia.org Scraper](https://i.postimg.cc/Pr76JkyP/image.png)

### What does Ballotpedia.org Scraper do?

Ballotpedia.org Scraper extracts political encyclopedia content from **ballotpedia.org**. It navigates search pages and article detail pages to collect structured content including ballot measures, legislation, lawsuit news, and political information. The scraper supports exporting the extracted dataset via REST API and standard download formats.

### Ballotpedia.org Scraper

This actor collects political content and encyclopedia articles from Ballotpedia.org. It targets search/listing pages to discover article URLs and detail pages to extract the full content (HTML and cleaned text). The output is normalized per-article JSON items suitable for research, analysis, and content aggregation.

### What data can I extract from Ballotpedia.org with this actor?

The actor extracts structured article and content data. Typical fields include:

<table>
<tr>
<td>url</td>
<td>Article URL on ballotpedia.org</td>
</tr>
<tr>
<td>title</td>
<td>Page title</td>
</tr>
<tr>
<td>pageHtml</td>
<td>Full HTML content of the article body</td>
</tr>
<tr>
<td>pageText</td>
<td>Clean text content with whitespace normalized and formatted for readability</td>
</tr>
</table>

### Why scrape Ballotpedia.org?

Political encyclopedia data is useful for research, analysis, monitoring, and content aggregation. Scraping Ballotpedia.org enables:

- Tracking ballot measures and legislative activity across states
- Monitoring political news and lawsuit developments
- Building databases of political and electoral information
- Research on initiative, referendum, and recall processes
- Historical analysis of political trends and legal cases

### How to use Ballotpedia.org Scraper?

Quick start guide:

1. Create or log into your Apify account.
2. Open the Ballotpedia.org Scraper actor on Apify.
3. Click **Try for free** or run the actor with your configuration.
4. Provide one or more `startUrls` (search pages with query results).
5. Set `maxItems` to limit how many articles to process per start URL.
6. Start the actor and wait for completion; download results as JSON/CSV/Excel/NDJSON.

### Input

The actor accepts the following input parameters:

- `startUrls` (array of objects) - **Required**. URLs to start crawling from. Use search pages with query results to discover articles.
- `maxItems` (integer) - Maximum number of articles to scrape per start URL. Default: 3.
- `proxyConfiguration` (object) - Proxy configuration for crawling. Residential proxies are recommended for reliability.

#### Supported URL Types

**Search Page Example:**

- `https://ballotpedia.org/wiki/index.php?search=ballot+measure&title=Special%3ASearch&profile=default&fulltext=1`
- `https://ballotpedia.org/wiki/index.php?search=lawsuit&title=Special%3ASearch&profile=default&fulltext=1`

Example input:

```json
{
    "startUrls": [
        {
            "url": "https://ballotpedia.org/wiki/index.php?search=ballot+measure&title=Special%3ASearch&profile=default&fulltext=1"
        },
        {
            "url": "https://ballotpedia.org/wiki/index.php?search=referendum&title=Special%3ASearch&profile=default&fulltext=1"
        }
    ],
    "maxItems": 5,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US"
    }
}
````

#### Note: The `startUrls` field is required and we can only scrape from a search page.

### Output

The scraped data is saved as a dataset. Each item represents one article with its content. You can download the output in JSON, JSONL, CSV, Excel, or NDJSON.

Sample output (one dataset item):

```json
{
    "url": "https://ballotpedia.org/Ballot_measure_lawsuit_news",
    "title": "Ballot measure lawsuit news - Ballotpedia",
    "pageHtml": "<div class=\"mw-parser-output\"><table style=\"border-spacing:8px; margin:0px -8px;\">...</table></div>",
    "pageText": "Ballot measure lawsuit breaking news Ballot Law Update: 2014 Year in Review By Josh Altic This edition of the Ballot Law Update features a year-end summary of legislation proposed in 2014 concerning laws governing the powers of initiative, referendum and recall. Of the 113 bills Ballotpedia tracked, 13 were approved in 5 states, while three were carried over to next year, and 97 were defeated..."
}
```

#### Notes and Limitations

- The actor depends on the current Ballotpedia.org page structure. If the site changes, the actor may require updates.
- Use the actor in compliance with Ballotpedia.org terms of service and applicable laws.
- If you encounter blocking, try running with residential proxies and reasonable concurrency settings.
- The `pageText` field is cleaned to remove excessive whitespace, tabs, and newlines for better readability.
- **Residential proxies are required**: Ballotpedia.org has anti-bot measures that detect and block datacenter proxies. Running without residential proxies will result in frequent blocking and failed requests. This is why residential proxies are enabled by default in the input schema.

#### Looking to Scrape more News Websites?

In addition to this actor, you can explore our suite of dedicated scrapers. Each scraper is optimized for its target site to provide accurate, structured, and reliable data extraction.

| Scraper                                                                                     | Region | Description                                                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| [Ynet.co.il Scraper](https://apify.com/lexis-solutions/ynet)                                | Isreal | Scrape news content from ynet.co.il to gather headlines, summaries, and metadata. Ideal for news aggregation, market analysis, and tracking real-time trends. Fast, structured, and customizable extraction from an Israel-based source.                           |
| [ElEspanol.com Scraper](https://apify.com/lexis-solutions/elespanol)                        | Spain  | Scrape news content from El Español - including headlines, summaries, article bodies, authors, and publish dates. Ideal for news aggregation, market analysis, and trend tracking. Fast, structured, and customizable extraction from Spain’s leading news source. |
| [Construction Dive Scraper](https://apify.com/lexis-solutions/constructiondive-com-scraper) | USA    | Construction Dive scraper for USA construction news and press releases: extract articles, contacts, images, and metadata from ConstructionDive.com Deep Dive section for construction tech, PR, and market research workflows.                                     |

Explore these solutions to expand your data collection capabilities.

***

p.s.

Got feedback or need an extension?

Lexis Solutions is a [certified Apify Partner](https://apify.com/partners). We can help you with custom solutions or data extraction projects.

Contact us over [Email](mailto:info@lexis.solutions) or [LinkedIn](https://www.linkedin.com/company/lexis-solutions)

### Image Credit

Image credit: https://ballotpedia.org

# Actor input Schema

## `startUrls` (type: `array`):

URLs to start with.

## `maxItems` (type: `integer`):

Maximum number of news articles that will be extracted.

## `proxyConfiguration` (type: `object`):

Select proxies to be used by your crawler. Residential proxies are required by default as Ballotpedia.org blocks datacenter IPs. Do not disable proxies unless you have confirmed the site is accessible without them.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://ballotpedia.org/wiki/index.php?limit=20&profile=default&search=news&title=Special:Search&ns0=1&ns4=1"
    }
  ],
  "maxItems": 5,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}
```

# Actor output Schema

## `results` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startUrls": [
        {
            "url": "https://ballotpedia.org/wiki/index.php?limit=20&profile=default&search=news&title=Special:Search&ns0=1&ns4=1"
        }
    ],
    "maxItems": 5,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "US"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("lexis-solutions/ballotpedia-org-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "startUrls": [{ "url": "https://ballotpedia.org/wiki/index.php?limit=20&profile=default&search=news&title=Special:Search&ns0=1&ns4=1" }],
    "maxItems": 5,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "US",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("lexis-solutions/ballotpedia-org-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startUrls": [
    {
      "url": "https://ballotpedia.org/wiki/index.php?limit=20&profile=default&search=news&title=Special:Search&ns0=1&ns4=1"
    }
  ],
  "maxItems": 5,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "US"
  }
}' |
apify call lexis-solutions/ballotpedia-org-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=lexis-solutions/ballotpedia-org-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "Ballotpedia.org Scraper",
        "description": "Scrape Ballotpedia.org political encyclopedia articles — ballot measures, legislation, lawsuits & electoral data. Extract structured JSON with title, URL & full text. Ideal for political research, news monitoring & content aggregation.",
        "version": "1.0",
        "x-build-id": "hG9jqjwx2hCti0A6U"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/lexis-solutions~ballotpedia-org-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-lexis-solutions-ballotpedia-org-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/lexis-solutions~ballotpedia-org-scraper/runs": {
            "post": {
                "operationId": "runs-sync-lexis-solutions-ballotpedia-org-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/lexis-solutions~ballotpedia-org-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-lexis-solutions-ballotpedia-org-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "required": [
                    "startUrls"
                ],
                "properties": {
                    "startUrls": {
                        "title": "Start URLs",
                        "type": "array",
                        "description": "URLs to start with.",
                        "items": {
                            "type": "object",
                            "required": [
                                "url"
                            ],
                            "properties": {
                                "url": {
                                    "type": "string",
                                    "title": "URL of a web page",
                                    "format": "uri"
                                }
                            }
                        }
                    },
                    "maxItems": {
                        "title": "Maximum number of items",
                        "type": "integer",
                        "description": "Maximum number of news articles that will be extracted."
                    },
                    "proxyConfiguration": {
                        "title": "Proxy configuration",
                        "type": "object",
                        "description": "Select proxies to be used by your crawler. Residential proxies are required by default as Ballotpedia.org blocks datacenter IPs. Do not disable proxies unless you have confirmed the site is accessible without them."
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```