# BallotReady MCP > BallotReady connects your agent directly to nonpartisan civic data, letting you analyze election information without visiting dozens of confusing government websites. Your AI client can identify upcoming local, state, and national elections based on any address, pull detailed candidate profiles, map voting districts, and explain ballot measures in plain conversation. It’s the fastest way to handle complex voter research. ## Overview - **Category:** productivity - **Price:** Free - **Tags:** civic-engagement, voter-information, election-data, candidate-profiles, nonpartisan ## Description BallotReady gives your agent a direct line into America's civic data. Instead of building custom scrapers that break when a county updates its website, you just ask your AI client a question about an election or a candidate. Your agent can instantly check for upcoming local and federal races using only an address. It pulls detailed profiles on candidates running for office, shows exactly which voting districts cover that spot, and explains complex ballot measures in plain English—all without you ever touching a government portal. By connecting BallotReady through Vinkius, your agent gets access to this whole network of election data, acting as a reliable bridge to the democratic process whether you're building an outreach tool or just fact-checking for a story. ## Tools ### get_account_check Verifies the connection status of your BallotReady account. ### get_ballot_measures Pulls the specific text and details for ballot measures in a given election. ### get_candidate Retrieves a full, detailed profile for one specified candidate. ### get_districts_by_address Returns all relevant voting districts that cover an inputted address. ### get_elections_by_address Lists all upcoming elections (local, state, federal) tied to a specific address. ### get_officeholders Gets the names and roles of current elected officials for specified districts. ### list_candidates Provides a list of candidates who are running in an election. ### list_districts Matches any given address to its specific set of voting districts. ### list_elections Finds all upcoming elections based on an input physical address. ### list_positions Lists the specific public offices that are currently up for election in a district or state. ## Prompt Examples **Prompt:** ``` What elections are coming up for the address 123 Main St, Chicago, IL? ``` **Response:** ``` I've found 2 upcoming elections for that address: the General Election on November 3rd and a Municipal Special Election on June 15th. Would you like to see the candidates or ballot measures for either? ``` **Prompt:** ``` Show me the profile for candidate ID 98765. ``` **Response:** ``` Candidate Profile: Jane Smith. She is running for State Senate. Her platform focuses on education reform and infrastructure. I can provide more details on her previous experience if needed. ``` **Prompt:** ``` Which voting districts cover 1600 Pennsylvania Ave NW, Washington, DC? ``` **Response:** ``` Retrieving district mapping... That address is covered by DC's At-Large Congressional District and DC Council Ward 2. I can also list the current officeholders for these districts. ``` ## Capabilities ### Map addresses to voting districts Determines which specific electoral districts cover any physical address in the U.S. ### Discover upcoming elections Lists all current and future local, state, or federal elections associated with a given address. ### Retrieve candidate biographies Pulls comprehensive profiles, including platforms and history, for specific candidates running for office. ### Analyze ballot measures Retrieves and explains the details of specific referendums or ballot initiatives for an election. ### Audit elected officials Lists current officeholders who represent a given voting district. ## Use Cases ### Voter Outreach Campaign Setup A non-profit needs to know which districts in a new zip code are affected by water quality referendums. They use `get_districts_by_address` first, then feed those results into `get_ballot_measures` to get the exact text they need for their materials. ### Fact-Checking a Local Election Claim A journalist receives an unsubstantiated claim about a candidate's platform. They use `get_candidate` to pull the official, nonpartisan profile and compare it directly against the published information. ### Planning Field Events An advocacy group is planning a rally and needs to know who represents the area. They run `list_elections` first to confirm active races, then use `get_officeholders` to get the current elected leadership list. ### Building a Civic Dashboard A developer wants to build a tool that lists all possible offices in an area. They run `list_positions` to see what's on the ballot, then use `list_candidates` to populate who is running for those roles. ## Benefits - Find every upcoming race: Instead of searching county websites, your agent uses `list_elections` to pull all local, state, and federal election dates for any address in the U.S. - Deep candidate dives: Use `get_candidate` to instantly retrieve detailed bios and campaign positions without leaving your chat client. It's better than reading dozens of individual Wikipedia pages. - District mapping solved: You don't need to know zoning laws; calling `list_districts` reliably maps an address to its exact voting boundaries, which is critical for targeting outreach. - Understand the ballot: For complex local votes, `get_ballot_measures` explains referendums and initiatives in plain language. It cuts through confusing government jargon. - Know who's serving: Need to verify leadership? Running `get_officeholders` lists the current elected officials for a district so you don't have outdated contacts. ## How It Works The bottom line is you send natural language prompts to your AI client and get structured electoral data back. 1. Subscribe to the MCP and enter your API key. 2. Ask your agent for specific election details or candidate information using an address as context. 3. The system executes a sequence of data calls, returning structured civic information directly into your chat window. ## Frequently Asked Questions **How do I find out which elections are coming up for my address using list_elections?** You pass your physical address to the `list_elections` tool, and it returns a structured list of all upcoming local, state, or federal races at that location. **What is the difference between get_districts_by_address and list_districts?** `get_districts_by_address` retrieves districts for a specific address you provide. `list_districts` does the same thing, but it's generally used when listing boundaries based on an input. **Can I use get_ballot_measures to see about referendums?** Yes, that’s exactly what it does. You specify which election you are looking at, and the tool pulls all available ballot measures for review. **Do I need list_positions to know who is running? ** No. While `list_positions` tells you what offices exist, use `list_candidates` after determining the election ID; that gives you the actual people running. **How do I verify my API connection using get_account_check?** You run `get_account_check` to instantly confirm your BallotReady access status. This simple call verifies that your agent has the necessary permissions and is actively connected, letting you troubleshoot before running complex searches. **If I need to know who currently holds office, should I use get_officeholders?** Yes, `get_officeholders` pulls a list of current elected officials for specific voting districts. It's the right tool when you need an accurate view of existing local leadership, separate from candidates running in an election. **What information does the tool need when I call get_candidate?** The system requires a unique identifier for the candidate to pull their profile. Providing this ID ensures your agent fetches the precise, detailed biography and platform you are looking for, avoiding any confusion. **When I use list_candidates, am I getting full biographies, or just names?** The `list_candidates` tool provides a simple roster of every person running in an election. It gives you the basic name and office information; remember to call `get_candidate` for detailed bios. **Can I search for elections using just a city name?** For the highest accuracy, BallotReady tools like `list_elections` require a specific physical address (Street, City, State, ZIP). This ensures the agent returns the exact ballot measures and candidates for that specific location. **Does this integration provide information for international elections?** Currently, BallotReady focuses exclusively on comprehensive civic data within the United States, including local, state, and federal contests. **Can the agent tell me who my current representatives are?** Yes. Use the `get_officeholders` tool by providing a district ID (retrieved via `list_districts` for an address) to see a list of current leaders representing that area.