# Voteref US Voter Records Scraper (`dromb/voteref-wave4`) Actor Extract comprehensive voter registration data, person details, household residents, and voting history from Voteref.com public records. Perfect for political research, voter analysis, campaign targeting, and public records workflows. - **URL**: https://apify.com/dromb/voteref-wave4.md - **Developed by:** [Dmitriy Gyrbu](https://apify.com/dromb) (community) - **Categories:** Automation, Developer tools - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $0.60 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 ## Voteref US Voter Records Scraper Extract source-specific voter registration records, person details, same-address residents, and voting participation history from public Voteref records. This Actor is intended for legitimate public-records research, journalism, election analysis, data-quality work, and permitted automation. It preserves Voteref's own `personId` and `voterId` identifiers instead of attempting to match identities across unrelated sources. ### What you can retrieve - `person` — one voter registration record by Voteref `personId` - `residents` — voter records associated with the same source address - `history` — recorded election participation for one `personId` - `search` — paginated state search with optional county, party, age, precinct, senate-district, and congressional-district filters The first three operations are validated with the example `personId` in the default input. Search is more sensitive to Voteref access controls and normally requires US-located proxy access. ### Quick start The default input is a small, working person lookup: ```json { "operation": "person", "state": "fl", "personId": "2b803109-8ae9-4da3-9f6f-f7dcfa0d3614", "includeRaw": false } ```` Same-address residents: ```json { "operation": "residents", "state": "fl", "personId": "2b803109-8ae9-4da3-9f6f-f7dcfa0d3614" } ``` Voting participation history: ```json { "operation": "history", "state": "fl", "personId": "2b803109-8ae9-4da3-9f6f-f7dcfa0d3614" } ``` Small state search: ```json { "operation": "search", "state": "fl", "start": 0, "length": 10 } ``` ### Search filters Search accepts comma-separated source filter values: | Input | Purpose | |---|---| | `counties` | County names | | `parties` | Party affiliations | | `senateDistricts` | State senate districts | | `precinctCodes` | Precinct codes | | `ageRanges` | Source-supported age ranges | | `congressionalDistricts` | Congressional districts | | `start` | Zero-based result offset | | `length` | Page size from 1 to 200 | Start with `length: 10`. Validate the unfiltered state search before adding filters, because labels and district formats are source-specific. ### Output Results are written to the default Dataset. A person lookup produces one flat voter record: ```json { "personId": "2b803109-8ae9-4da3-9f6f-f7dcfa0d3614", "voterId": "100474482", "county": "Alachua", "voterStatus": "Active", "party": "Republican", "state": "FL", "numberOfTimesVoted": 6 } ``` `residents` and `history` may return a Dataset item whose `result` field contains the source collection. The Dataset schema deliberately supports both shapes. The default Key-Value Store contains `OUTPUT`, with: - `success` and `status` - requested `operation` - result totals and published item count - structured errors - proxy diagnostics - run and monetization metadata Treat a platform run status of `SUCCEEDED` as transport completion. For production automation, also require `OUTPUT.success === true` and an empty `OUTPUT.errors` array. ### Ready-to-run Saved Tasks The Store package includes bounded examples for: - voter person record - same-address residents - voting participation history - small state search - county, party, age, and district search variants Lookup tasks use a validated Voteref `personId`. Search tasks are templates and can still require suitable US proxy access; check `OUTPUT` before consuming their Dataset. ### Use with n8n or Make A practical workflow is: `Apify Actor -> wait for run -> check OUTPUT.success -> Dataset -> Google Sheets, Telegram, or CRM` Start a run through the Apify API: ```bash curl -X POST \ "https://api.apify.com/v2/acts/204O2vGygTXHATFRr/runs?token=YOUR_APIFY_TOKEN&waitForFinish=120" \ -H "Content-Type: application/json" \ -d '{"operation":"person","state":"fl","personId":"2b803109-8ae9-4da3-9f6f-f7dcfa0d3614"}' ``` Use the returned `defaultKeyValueStoreId` to read `OUTPUT`, then use `defaultDatasetId` to fetch the Dataset: ```bash curl "https://api.apify.com/v2/key-value-stores/STORE_ID/records/OUTPUT?token=YOUR_APIFY_TOKEN" curl "https://api.apify.com/v2/datasets/DATASET_ID/items?clean=true&format=json&token=YOUR_APIFY_TOKEN" ``` In n8n or Make, keep the Apify token in the platform's credential store. Do not put it directly in a public workflow template. ### Reliability and troubleshooting Voteref is geo-sensitive and may return Cloudflare protection responses, especially for broad searches. The Actor is designed to use US proxy routing when available and records the effective proxy mode in `OUTPUT.proxy`. The default proxy configuration uses Apify's automatic selection, which is the lowest-cost built-in route to try first. If it is blocked and your Apify plan allows residential traffic, select the `RESIDENTIAL` group and country `US` in the Actor input. Specialized SERP proxies are not appropriate for Voteref API requests. - `ProtectionBypassFailed`: retry with suitable US proxy access. - Empty results: broaden the filters and verify the exact source labels. - Invalid person ID: use a current Voteref `personId` from a successful search. - `SUCCEEDED` with `OUTPUT.success: false`: treat the operation as failed. Avoid large retries. A small probe is cheaper and gives a clearer access signal. Blocked requests use a bounded retry budget so an unavailable proxy route fails quickly instead of consuming several minutes of compute. ### Responsible use Voter records can contain personal information even when they are publicly available. Use the Actor only where permitted, minimize the data you collect, secure stored results, respect retention requirements, and do not use the data for harassment, discrimination, intimidation, or unlawful profiling. This is an unofficial Actor and is not affiliated with or endorsed by Voteref. # Actor input Schema ## `operation` (type: `string`): Select a source operation. Search is proxy-sensitive; person, residents, and history require a Voteref personId. ## `state` (type: `string`): Two-letter state code (e.g., 'fl', 'pa', 'tx'). Required for all operations. Use the official state abbreviation. ## `personId` (type: `string`): Unique voter identifier from Voteref. Required for 'person', 'residents', and 'history' operations. Get this from the 'search' results. ## `counties` (type: `string`): Filter by specific counties (comma-separated). Optional for 'search' operation. ## `parties` (type: `string`): Filter by political party affiliation (comma-separated). Optional for 'search' operation. ## `senateDistricts` (type: `string`): Filter by senate districts (comma-separated). Optional for 'search' operation. ## `precinctCodes` (type: `string`): Filter by voting precinct codes (comma-separated). Optional for 'search' operation. ## `ageRanges` (type: `string`): Filter by age ranges (comma-separated). Optional for 'search' operation. ## `congressionalDistricts` (type: `string`): Filter by congressional districts (comma-separated). Optional for 'search' operation. ## `start` (type: `integer`): Zero-based offset for pagination. Use this to navigate through large result sets. Defaults to 0. ## `length` (type: `integer`): Number of search results requested per page. Maximum 200. Start small to validate access and filters. ## `includeRaw` (type: `boolean`): Include the original unnormalized source data in the OUTPUT summary. Useful for debugging and advanced analysis. ## `proxyConfiguration` (type: `object`): Automatic Apify Proxy is the cheapest first attempt. For geo-sensitive failures, try the RESIDENTIAL group with country US. ## Actor input object example ```json { "operation": "person", "state": "fl", "personId": "2b803109-8ae9-4da3-9f6f-f7dcfa0d3614", "start": 0, "length": 10, "includeRaw": false, "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `results` (type: `string`): Normalized dataset items returned by the actor. ## `summary` (type: `string`): Run summary JSON stored under the OUTPUT key. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("dromb/voteref-wave4").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("dromb/voteref-wave4").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 '{}' | apify call dromb/voteref-wave4 --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=dromb/voteref-wave4", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Voteref US Voter Records Scraper", "description": "Extract comprehensive voter registration data, person details, household residents, and voting history from Voteref.com public records. Perfect for political research, voter analysis, campaign targeting, and public records workflows.", "version": "0.1", "x-build-id": "62D9acLJ8jZnvSHV7" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/dromb~voteref-wave4/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-dromb-voteref-wave4", "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/dromb~voteref-wave4/runs": { "post": { "operationId": "runs-sync-dromb-voteref-wave4", "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/dromb~voteref-wave4/run-sync": { "post": { "operationId": "run-sync-dromb-voteref-wave4", "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": [ "operation" ], "properties": { "operation": { "title": "Operation", "enum": [ "search", "person", "residents", "history" ], "type": "string", "description": "Select a source operation. Search is proxy-sensitive; person, residents, and history require a Voteref personId.", "default": "person" }, "state": { "title": "US State", "type": "string", "description": "Two-letter state code (e.g., 'fl', 'pa', 'tx'). Required for all operations. Use the official state abbreviation.", "default": "fl" }, "personId": { "title": "Person ID", "type": "string", "description": "Unique voter identifier from Voteref. Required for 'person', 'residents', and 'history' operations. Get this from the 'search' results.", "default": "2b803109-8ae9-4da3-9f6f-f7dcfa0d3614" }, "counties": { "title": "Counties", "type": "string", "description": "Filter by specific counties (comma-separated). Optional for 'search' operation." }, "parties": { "title": "Political Parties", "type": "string", "description": "Filter by political party affiliation (comma-separated). Optional for 'search' operation." }, "senateDistricts": { "title": "Senate Districts", "type": "string", "description": "Filter by senate districts (comma-separated). Optional for 'search' operation." }, "precinctCodes": { "title": "Precinct Codes", "type": "string", "description": "Filter by voting precinct codes (comma-separated). Optional for 'search' operation." }, "ageRanges": { "title": "Age Ranges", "type": "string", "description": "Filter by age ranges (comma-separated). Optional for 'search' operation." }, "congressionalDistricts": { "title": "Congressional Districts", "type": "string", "description": "Filter by congressional districts (comma-separated). Optional for 'search' operation." }, "start": { "title": "Start Offset", "minimum": 0, "type": "integer", "description": "Zero-based offset for pagination. Use this to navigate through large result sets. Defaults to 0.", "default": 0 }, "length": { "title": "Page Size", "minimum": 1, "maximum": 200, "type": "integer", "description": "Number of search results requested per page. Maximum 200. Start small to validate access and filters.", "default": 10 }, "includeRaw": { "title": "Include Raw Payload", "type": "boolean", "description": "Include the original unnormalized source data in the OUTPUT summary. Useful for debugging and advanced analysis.", "default": false }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "Automatic Apify Proxy is the cheapest first attempt. For geo-sensitive failures, try the RESIDENTIAL group with country US.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } } ```