API Guide
The Vote-USA API provides developer access to comprehensive non-partisan electoral data, ballot information, candidate profiles, and elected representative details across the United States. It serves as a central data hub designed to power civic engagement applications, election tracking software, and voter education tools by delivering structured, real-time access to municipal, state, and federal political information.
Through standardized web service endpoints, developers can perform targeted queries to return active elections, candidate information, localized ballot contests, and currently serving elected officials based on geographic coordinates or address inputs. The API organizes election data into structured JSON objects containing details such as candidate bios, party affiliations, ballot measures, running mates, office scopes, and social media channels.
Key Requirement: Secret Key
To access any endpoint within the Vote-USA API, requests must include a valid authentication key via the accessKey parameter. Requests submitted without a valid access key or with an unrecognized key will be rejected with an "Unauthorized" status.
Procurement of a Secret Access Key requires formal authorization and must be requested directly from the Vote-USA Administration. Developers must obtain their designated accessKey prior to integrating these API services into production or testing environments.
API Endpoint Reference
Base URL:
https://www.vote-usa.org/api/v1.asmx/[api query name]?[arguments]
1. candidatesQuery
High-Level Explanation
The candidatesQuery API retrieves candidate profile data for each office contest for each election on a specific election date. It returns candidate biographical details, party affiliation, contact links, running mate information, and contest specifics.
Required Arguments
- electionDay: The target election date in yyyy-MM-dd format.
- state: The 2-letter postal code for the U.S. state (e.g., DC, VA, CA).
- accessKey: Your assigned Vote-USA secret authentication key.
- preRelease (Optional): Set to Y to include pre-release data.
Example Usage
HTTP
GET https://www.vote-usa.org/api/v1.asmx/candidatesQuery?electionDay=2024-11-05&state=DC&accessKey=YOUR_SECRET_KEY
Example Usage
JSON Output Nodes & Attributes
| Node / Attribute |
Data Type |
Description |
| kind |
string |
Response type identifier (voteusa#candidatesQuery). |
| status |
String |
Request status message (e.g., "OK", "Invalid state", "Unauthorized"). |
| success |
Boolean |
Indicates overall query success (true/false). |
| electionDay |
String |
Echoed election date formatted as yyyy-MM-dd. |
| state |
String |
Two-letter U.S. state postal code. |
| election |
Object |
Primary election metadata containing id, name, and electionDay. |
| otherElections |
Array |
List of concurrent secondary election objects occurring on the same date. |
| candidates |
Array |
List of candidate objects. |
| candidates[].id |
String |
Unique Politician Key. |
| candidates[].name |
String |
Full formatted candidate name. |
| candidates[].party |
String |
Political party description or name. |
| candidates[].candidateUrl |
String |
Official campaign website URL. |
| candidates[].phone |
String |
Public contact phone number. |
| candidates[].email |
String |
Public contact email address. |
| candidates[].photoUrl |
String |
Direct URL pointing to candidate portrait. |
| candidates[].channels |
Array |
Social media profile objects containing type (platform) and id (link). |
| candidates[].runningMate |
Object |
Nested candidate object detailing running mate information (if applicable). |
| candidates[].contests |
Array |
List of office contests the candidate is participating in. |
| contests[].id |
String |
Formatted contest key (ElectionKey|OfficeKey). |
| contests[].office |
String |
Title of the office being sought. |
| contests[].electionName |
String |
Associated election name (populated if multiple elections exist). |
| contests[].orderOnBallot |
Integer |
Position/order on the ballot. |
2. electionQuery
High-Level Explanation
The electionQuery API returns a list of active and upcoming elections along with high-level statistics for each state, including candidate counts, office counts, and referendum counts.
Required Arguments
- accessKey: Your assigned Vote-USA secret authentication key.
- preRelease (Optional): Set to Y to include pre-release election data.
- seeAll (Optional): Set to Y to retrieve all historical or extended election records.
Example Usage
HTTP
GET https://www.vote-usa.org/api/v1.asmx/electionQuery?accessKey=YOUR_SECRET_KEY
Example Usage
JSON Output Nodes & Attributes
| Node / Attribute |
Data Type |
Description |
| kind |
String |
Response type identifier (voteusa#electionQuery). |
| status |
String |
Request status message (e.g., "OK", "No future elections found"). |
| success |
Boolean |
Indicates overall query success (true/false). |
| elections |
Array |
List of election resource objects. |
| elections[].id |
String |
Unique identifier key for the election. |
| elections[].name |
String |
Full text description/title of the election. |
| elections[].electionDay |
String |
Election date formatted as yyyy-MM-dd. |
| elections[].state |
String |
Two-letter U.S. state postal code. |
| elections[].stateStatistics |
Object |
Summary counts for the election. |
| stateStatistics.candidateCount |
Integer |
Total count of unique candidates registered for the election. |
| stateStatistics.officeCount |
Integer |
Total count of unique offices/contests on the ballot. |
| stateStatistics.referendumCount |
Integer |
Total count of ballot measures/referendums. |
3. voterInfoQuery
High-Level Explanation
The voterInfoQuery API returns the data for a personalized sample ballot based on a voter's geographic coordinates (latitude and longitude), state, and election date. It returns candidate contests, office scopes, and detailed referendum/ballot measure summaries (including pro/con arguments and text briefs).
Required Arguments
- latitude: The latitude coordinate of the voter's location (e.g., 38.8977).
- longitude: The longitude coordinate of the voter's location (e.g., -77.0365).
- electionDay: The election date formatted as yyyy-MM-dd.
- state: The 2-letter state postal code.
- accessKey: Your assigned Vote-USA secret authentication key.
- preRelease (Optional): Set to Y to include pre-release ballot information.
Example Usage
HTTP
GET https://www.vote-usa.org/api/v1.asmx/voterInfoQuery?latitude=38.8977&longitude=-77.0365&electionDay=2024-11-05&state=DC&accessKey=YOUR_SECRET_KEY
Example Usage
JSON Output Nodes & Attributes
| Node / Attribute |
Data Type |
Description |
| kind |
String |
Response type identifier (voteusa#voterInfoQuery). |
| status |
String |
Request status message. |
| success |
Boolean |
Indicates overall query success (true/false). |
| latitude / longitude |
Double |
Echoed location coordinates queried. |
| electionDay |
String |
Targeted election date string. |
| state |
String |
Two-letter state code. |
| election |
Object |
Primary election metadata (id, name, electionDay). |
| otherElections |
Array |
List of concurrent secondary election objects. |
| contests |
Array |
List of office contests and referendum items. |
| contests[].id |
String |
Unique contest key or referendum key. |
| contests[].type |
String |
Contest type (e.g., "Primary", "General", "Run-off", or "Referendum"). |
| contests[].office |
String |
Title of the office being contested. |
| contests[].primaryParty |
String |
Party description if the contest is a primary election. |
| contests[].special |
String |
Indicates special election status ("Yes" or "No"). |
| contests[].numberElected |
Integer |
Number of open seats for the office. |
| contests[].district |
Object |
Geographic district metadata (id, name, scope). |
| district.scope |
String |
Scope level ("national", "congressional", "statewide", "countyWide", "citywide"). |
| contests[].candidates |
Array |
List of candidate objects contesting the office. |
| contests[].referendumTitle |
String |
Official title of the ballot measure (Referendum only). |
| contests[].referendumSubtitle |
String |
Description/subtitle of the measure (Referendum only). |
| contests[].referendumUrl |
String |
Direct web link to complete proposition text/details (Referendum only). |
| contests[].referendumBrief |
String |
Summary brief of the proposition (Referendum only). |
| contests[].referendumText |
String |
Full legal text of the proposition (Referendum only). |
| contests[].referendumDetailForYes |
String |
Summary explanation of a "Yes" vote (Referendum only). |
| contests[].referendumDetailForNo |
String |
Summary explanation of a "No" vote (Referendum only). |
| contests[].referendumDetailPro |
String |
Arguments supporting the measure (Referendum only). |
| contests[].referendumDetailCon |
String |
Arguments opposing the measure (Referendum only). |
4. representativeInfoByAddress
High-Level Explanation
The representativeInfoByAddress API accepts a street address string, normalizes the address, determines the relevant electoral divisions (federal, state, county, and local), and returns all currently serving elected officials mapped to those divisions.
Required Arguments
- address: The full street address string to query.
- accessKey: Your assigned Vote-USA secret authentication key.
- includeOffices (Optional): Boolean flag (true/false) indicating whether to return detailed office and official objects.
- levels (Optional): Comma-separated levels filter (e.g., country, administrativeArea1, locality).
- roles (Optional): Comma-separated roles filter (e.g., headOfGovernment, legislatorUpperBody, executive).
Example Usage
HTTP
GET https://www.vote-usa.org/api/v1.asmx/representativeInfoByAddress?address=1600+Pennsylvania+Ave+NW,+Washington+DC,+20500&accessKey=YOUR_SECRET_KEY
Example Usage
JSON Output Nodes & Attributes
| Node / Attribute |
Data Type |
Description |
| kind |
String |
Response type identifier (voteusa#representativeInfoResponse). |
| status |
String |
Request status message. |
| success |
Boolean |
Indicates overall query success (true/false). |
| normalizedInput |
Object |
Parsed and standardized input address (line1, city, state, zip). |
| divisions |
Dictionary |
Map of Open Civic Data (OCD) division identifiers to division details. |
| divisions[key].name |
String |
Display name of the electoral division. |
| divisions[key].officeIndices |
Array |
Array of 0-based indices mapping to items in the offices array. |
| offices |
Array |
List of political office objects (omitted if includeOffices=false). |
| offices[].name |
String |
Official title of the office. |
| offices[].divisionId |
String |
OCD division identifier string for this office. |
| offices[].levels |
Array<String> |
levels |
| offices[].roles |
Array<String> |
Government roles (e.g., ["headOfGovernment"], ["legislatorUpperBody"]). |
| offices[].voteUSAOfficeId |
String |
Internal Vote-USA unique office key. |
| offices[].officialIndices |
Array<Int> |
Array of 0-based indices mapping to items in the officials array. |
| officials |
Array |
List of serving representative objects (omitted if includeOffices=false). |
| officials[].officialIndex |
Integer |
Index position referenced by office.officialIndices. |
| officials[].name |
String |
Official name of the politician. |
| officials[].voteUSAPoliticianId |
String |
Unique Vote-USA politician key. |
| officials[].party |
String |
Political party description or affiliation. |
| officials[].photoUrl |
String |
Direct link to the official portrait. |
| officials[].phones |
Array<String> |
Public office phone numbers. |
| officials[].urls |
Array<String> |
Official web page URLs. |
| officials[].emails |
Array<String> |
Public contact email addresses. |
| officials[].address |
Array<Object> |
Physical office address objects (line1, line2, city, state, zip). |
| officials[].channels |
Array<Object> |
Social media accounts (type and id). |
Additional Information
Email us at mgr@vote-usa.org for additional information or questions.