Bulk Data, Research/Records Requests, and the API

Table of Contents

Terms of Use and Enforcement

Use of our data is governed by the following:
As of 2013, our key stated use policy is: "Vote Smart does not permit the use of its name or programs in any campaign activity, including advertising, debates, and speeches."

This is displayed on each candidate's Political Courage Test webpage, on our section describing what the political courage test is, as part of our website's copyright notice, and on our webpage "For Candidates." It is also distributed to all candidates as part of our Political Courage Test Bulk Communications. Violations of this particular policy are addressed as "Candidate Fights," while other violations are addressed by the National Director

Data Restrictions for Redistribution

Data we're generally comfortable giving out:

Content we are hesitant to give out, particularly with some guarantee:
Content we will NOT give out:

Special Delivery Mechanisms for Bulk Data Users


If none of these solutions meet their needs:

What is the API?

Most of Vote Smart’s data is available through the API (Application Program Interface). Subscribers of the API obtain access to a vast database of information that has been collected by Vote Smart’s staff, interns, and volunteers since 1992.

Some of the data Vote Smart covers includes:
Inquiries about campaign finance data should be directed to CRP and NIMSP. We do offer ID matching in order to help subscribers use both data sets.

Purpose of the API:
The API allows people outside of Vote Smart to integrate our data into their applications. Some people even use it for their personal use, news articles, and school research papers. The API responds to simple requests for data, such as ‘get biographical information for candidate Y’ and ‘get votes information for candidate X.’ Each type of request (get bio, get votes) has to be planned for. Our API provides data in XML or JSON format.

Widgets - Vote Smart provides some ‘widgets’ which are essentially completed code so users can just cut and paste them into their websites. This is an easy way for users to integrate Vote Smart data. Widgets are built on top of the API and will require a valid key.

Libraries- Vote Smart provides libraries, which are pieces of code that will directly connect to Vote Smart servers through our API. This gives users controlled access to our database where we provide the data in a way we think will be useful to the users. This is a powerful way for an outside entity to access our data but it does require some technical ability. Multiple libraries are provided so outside developers can work with their preferred programming language; currently we have libraries in Java, Ruby, Python, PHP, and R.

Scope of Data Available in the API

Read:

How To Use the API

Read:
API Info Sheet
About the API
API Documentation
Undocumented API Methods - used mostly for VoteEasy (may only be given out on a case-by-case basis, with permission from the National Director)

Register for a Key to Access It:
http://votesmart.org/share/api/register: You should receive an email from officemgr@votesmart.org with your API Key once payment is made.

Getting Started with the API:
Here is a basic formula for directly interacting with the API in a web browser:
http://api.votesmart.org/<method>?key=<your_key>&<input>

NOTE: The key is case-sensitive and should use the case as listed in the documentation; Semi-Static Data may provide some input values, while others may be retrieved through a combination of API calls; for multiple inputs, separate each input with an ampersand ("&")

For example, the Candidate Bio API method would translate into the following URL: http://api.votesmart.org/CandidateBio.getBio?key=<your_key>&candidateId=9490. In this example, if I didn't know a candidateId, I would look for another method whose output was candidateId. I might start with the Officials.getByLevenshtein() method, where the required input is lastName, because I know the official's last name. Using this: http://api.votesmart.org/CandidateBio.getBio?key=<your_key>&lastName=bullock I discover that Steve Bullock's candidateId is 110899, which I can then use as the input in the first example

By default, the output will be in XML. This is fairly readable as is, but it can be converted into another format of your choosing. For example, a quick search for "xml to csv converter" on Google produces over 3 million results.

Random Note: Caching data helps the stress on our organization's servers. Since most of our data is not updated every day, subscribers don't need to call on our API as frequently. Most large subscribers cache our data. It's our job to give them a sense of the frequency that data updates.

Additional API Resources


DevComm is the primary manager of API subscriptions and is generally the first point of contact with API users. They take the payment and log it in DonorPerfect, activate keys (if needed), answer billing/ account questions. Questions about the fee schedule and API policies are generally answered by the DevComm. High-volume users, name-brand users, users looking to relicense or resell data, users looking for a separate contract, partnership requests, or other unusual questions will be run by the National Director, via DevComm. The National Director may need to consult the President.

Data questions (such as those about our research processes; frequency of update; or sources) should be forwarded to the Research Director at research@votesmart.org.

Technical questions, API bug reports, or API feature requests should be forwarded to IT at webmaster@votesmart.org.

Attachments
File Last modified Size
API Information Sheet.docx 2017-04-21 14:43 6Kb
Vote Smart Data Coverage.ods 2019-07-15 07:42 19Kb
VS API Fact Sheet.pdf 2020-12-10 08:49 89Kb
There is one comment on this page. [Display comment]
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki