# AP Elections API MCP MCP > AP Elections API allows your agent to audit real-time election results; it retrieves vote totals, tracks candidate performance across races, and lists participating candidates for any given date. This MCP automates political research by converting complex data querying into a simple conversation with your AI client. ## Overview - **Category:** data-analytics - **Price:** Free - **Tags:** election-results, political-research, real-time-data, voting-data, candidate-tracking, data-journalism ## Description Your agent handles the whole political research workflow using this connector. Instead of manually logging into multiple election portals and running separate queries, you just ask your AI client for what you need. It instantly retrieves race outcomes, audits candidate performance, and pulls up vote totals without touching a news terminal. Whether you’re monitoring local legislative shifts or analyzing deep national trends, the system gives you authoritative data immediately. Because this MCP is hosted on Vinkius, you get access to reliable, real-time political intelligence right alongside your other professional tools. ## Tools ### check_api_status Checks if the Associated Press Elections API is currently operational. ### get_election_results Retrieves full election results for a specific date (YYYY-MM-DD). ### get_race_details Gets detailed results and metrics using a specific race ID. ### list_election_candidates Lists every candidate participating in elections on a given date. ## Prompt Examples **Prompt:** ``` Get election results for '2024-11-05' in 'California' using AP Elections. ``` **Response:** ``` I've retrieved the results for the November 5th election in California! Multiple races are identified, including Presidential and Congressional. Leading candidates include [Name] with 55% of the vote. Would you like the detailed breakdown by race ID? ``` **Prompt:** ``` Who are the candidates for the presidential race on '2024-11-05'? ``` **Response:** ``` I've scanned the candidate list for the 2024 presidential race. It includes candidates from the Democratic, Republican, and Libertarian parties. I can provide the vote count and delegate progress for each candidate if results are available. ``` **Prompt:** ``` Show results for race ID '12345' on election date '2024-03-05'. ``` **Response:** ``` I've retrieved the details for race 12345! It was a Congressional Primary. The winner was identified as [Name] with 12,500 votes. I can assist you with more candidate metadata for this specific race if you'd like. ``` ## Capabilities ### Check API operational status Verifies if the AP Elections API is currently running and available for use. ### Get results by specific date Retrieves high-resolution election data, including office names and geographic distribution, for a given day. ### Audit details for one race Pulls deep performance metrics for an individual race using its unique ID. ### List all election candidates Provides a complete list of every candidate participating in elections on a specified date. ## Use Cases ### Confirming results after an unexpected primary A journalist needs to confirm the winner and vote count from a specific Congressional Primary on '2024-03-05'. The agent uses `get_race_details` to pull the exact metrics, confirming [Name] won with 12,500 votes. This is faster than cross-referencing multiple news reports. ### Mapping state-level political changes A policy researcher needs to understand how vote shares changed between neighboring states in the last cycle. They ask their agent to query by state, getting immediate data on regional shifts across multiple election dates and races. ### Preparing for a campaign kickoff meeting A political analyst needs a list of all candidates who ran in key swing states last year. They use `list_election_candidates` to generate the full roster, ensuring no potential opponent is overlooked. ### Validating data consistency before publishing A newsroom editor wants to know if the API is working correctly for today's results. They first run `check_api_status` to confirm the feed is live, preventing a broken report from going out. ## Benefits - Audits race outcomes with `get_election_results`. You get high-resolution data covering office names and geographic distribution for specific dates. This eliminates guesswork when checking preliminary numbers. - Track individual candidate performance using the MCP's capabilities. Your agent audits vote share, giving you a clear view of party distribution across various races. - Understand regional trends by querying election results state-by-state. The tool allows instant electoral discovery, helping pinpoint political shifts far from your desk. - Deep dive into data intelligence with `get_race_details`. You retrieve specific vote counts and candidate metadata for deeper classification work. - `list_election_candidates` gives you a full roster of participants for any election date. This is critical for confirming who was even in the race. ## How It Works The bottom line is, you ask your agent a question about elections; it uses this MCP to get the definitive answer. 1. Subscribe to this MCP and input your AP Elections API Key. 2. Your AI client executes the necessary tool call (e.g., checking status or retrieving results). 3. The system processes the query against real-time election data and returns structured, actionable findings. ## Frequently Asked Questions **How do I check if the AP Elections API is working right now using `check_api_status`?** You simply call `check_api_status`. The MCP verifies the connection and reports operational status. This confirms you can proceed with other data queries without worrying about service outages. **Can I get election results for a whole month using `get_election_results`?** No; `get_election_results` requires a specific date (YYYY-MM-DD). If you need multiple dates, run the tool repeatedly or ask your agent to iterate across a list of target dates. **What is the difference between using `get_election_results` and `get_race_details`?** `get_election_results` gives you an overview for a date, listing multiple races. `get_race_details` requires a specific race ID to pull deep metrics for only one contest. **Do I need the candidate list tool if I know the election date? (list_election_candidates)** Not necessarily, but it's useful. If you are auditing a specific race ID using `get_race_details`, that tells you about the outcome. Using `list_election_candidates` gives you the roster *before* the result is known. **What do I need to know about authentication when using `get_election_results`?** You must provide a valid AP Elections API key. Always secure this key and follow the official documentation for the exact header structure required by your AI client before making any calls. **What happens if I use `get_race_details` with an invalid or non-existent race ID?** The tool will return a specific error status, indicating that the provided race ID could not be found in the database. Don't assume data exists; always check the response code first. **Does `get_election_results` require me to provide state or office type filters?** Yes, while you can specify a date, including parameters like state or office name greatly narrows the results. This ensures your agent returns relevant data instead of an overwhelming list. **If I need candidate lists for many different years, is there a limit when using `list_election_candidates`?** There are rate limits on how frequently you can query the API. To prevent errors and maintain performance, batch your requests or implement a delay between calls.