API-documentation/faq
See frequently asked questions about Ballotpedia's bulk data and API below.
What is the difference between the bulk data and the API?
We offer flat spreadsheet files from our database for a reduced cost for those who are doing research or need less real-time or location-based data. These are downloadable from our password-protected client dashboard as often as once per day in order to reflect changes throughout, for example, an election cycle.
Our API can be used by clients looking to more fully integrate the data with their own apps or online tools. The key feature included in the API, aside from more real-time updates and customization, is access to geography-based filters such as the ability to query for upcoming elections based on a latitude/longitude point. You can see Ballotpedia’s own Sample Ballot Lookup tool for an example of an app like this that serves millions of voters per year, based on the Ballotpedia API.
Bulk data and the API both access the exact same database.
What data is included?
Ballotpedia maintains lists of all elected officials across the country at the federal, statewide, state legislative, and state judicial levels. We cover election results and compile candidate lists for these offices, as well as provide comprehensive local election coverage in the largest 100 U.S. cities by population. This includes any election that overlaps with part or all of one of those cities, including county races and special districts. We also cover the mayors, city council members, and district attorneys in the remaining 32 state capitals. Request samples from [email protected].
Ballotpedia also covers all statewide ballot measures in the nation, as well as notable local ballot measures across the country, as determined by our Editorial staff.
Our elections data is available in full back to 2018. We are happy to discuss custom research projects to collect or compile older data, as well.
How much does it cost?
This depends on the amount of data you are looking for, but we do set the minimum purchase price at $500. If your original request comes in well under that amount, we’ll try to find additional data to get you up to the minimum so you can maximize your purchase!
What are your terms of use?
More details will be specified in the data license, but primarily we expect you to protect the confidentiality of our data to the best of your ability and not make the full data set available for others to download or easily scrape. You are free to use the data in a public way as part of a larger, value-added product, of course.
What if you don't have what I'm looking for?
We are happy to take on custom projects. Email [email protected] for more information!
Do you offer discounts?
We offer discounts for academic projects and 501(c)3 nonprofits. We do not offer discounted data or API access to students at this time. We will consider API discounts during the development phase of projects on an individual basis.
What are your sources?
Ballotpedia's staff research and compile the data from a variety of sources, including Secretary of State's offices, county election offices, news outlets, and the candidates or officeholders themselves. We collect from official sources wherever possible.
Can I suggest a partnership or in-kind trade for data?
If you’re interested in a partnership, please contact [email protected].
I am a web developer and would like to learn more about the API; where can I find that documentation and pricing?
Please refer to developer.ballotpedia.org for documentation and email [email protected] for rates.
I just logged into my brand-new account and don’t see any data–help!
If your account was just created, you will not be able to see any data until after the next scheduled refresh (daily, between 12 AM and 6 AM Eastern). If you do not see any data after 24 hours, please contact the data team for assistance.
Why is Candidate X not in my dataset? They said they are running this year.
Our team updates the dataset with the vast majority of candidates after the state’s filing deadline passes based on official lists from the election board. This policy is to ensure the information appearing on our website is accurate. You may experience some delay between when a candidate states they are running and when they appear in your dataset.
How many queries have I used today? Do you track this?
Ballotpedia does not have the ability to track this for you. We recommend you build a small function that increments a saved number locally to keep track on your side.
How do I know when new candidates have been added to my dataset?
Right now, the most straightforward solution is to compare two sheets using Google Sheets.
Can I see which officeholders are running this year?
The officeholders dataset only allows you to see information about who is currently in office (like their name, office, party affiliation, if they are elected or appointed, and other basic information). The candidates dataset marks if a candidate is the incumbent (person currently in office) or not. You will need the candidate dataset if you want to identify who is running for office this year.
See more:
How do I create a lookup tool for my own site?
Custom
If you want to create a sample ballot lookup for your own site, based on Ballotpedia's data, we can help you do so.
You will need:
- a Ballotpedia API key
- a geolocation API or other method for mapping the addresses onto districts (we use Google's)
See also this description of the district matching endpoint. Please contact us at [email protected] to discuss such a project further.
Template:API docs nav
