Revision [17884]
This is an old revision of APIandDataRequests made by KristenVicedomini on 2016-06-07 09:04:26.
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: "Project 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:-information sourced from the public domain (government websites, campaign websites, etc.)
-unique content generated by Project Vote Smart (for example, ratings reports, legislative summaries, PCT questions)
-candidate-submitted content that we otherwise display publicly
Content we are hesitant to give out, particularly with some guarantee:
-content we are using under fair use but do not have clear authorization to redistribute (speeches)
-content which may be of an unclear origin and thus our rights to redistribute are unclear (photos)
-candidate-submitted content not publicly-available on our website (except at the request of the candidate who authored it, journalists, and academics)
Content we will NOT give out:
-raw data provided by our data partners (though zip-to-district queries may be done via the API and our widget)
-information about our members and users (see: our privacy policy)
Special Delivery Mechanisms for Bulk Data Users
- Our primary delivery mechanism for bulk data is through our API, though this typically requires the use of a developer. Direct people here first: it's relatively low-maintenance on our end and will fulfill most needs.
- We may allow "scraping" of our website on a case-by-case basis, but generally discourage this practice
- Special permission may be granted on a case-by-case basis to our PCT Archives (for journalists and academics only), as long as they abide by our terms of use. They must create a MyVoteSmart account on our site first, at which point we would create a mantis ticket asking IT to grant access to the PCT Archives for that username. They would then access the data by logging in and going to their User Panel. As of 6/7/16 the PCT Archives may be a little buggy, but we currently do not have the resources to apply to updates at present, or to provide users with this historical data in bulk in some other format
- Non-developers who wish to incorporate our content on their website may wish to use our widget, RSS feeds, and linking options available on our website
If none of these solutions meet their needs:
- determine if they truly need bulk data? depending on their needs, they may actually find want they're looking for on our voter-oriented tools listed here
- As of 2014, we do not provide "data dumps" or bulk data that requires IT assistance or significant staff time, though this may be considered for a fee or for partners. Research staff and interns may fulfill simple requests as part of SQL skill development.
How To Use the API
Read:
API Crib Sheet
About the API
API Documentation
Undocumented API Methods (may only be given out on a case-by-case basis, with permission from the National Director)
Register for a Key to Access It:
Registration
You should receive an email with your API Key once it is approved by the API Administrator.
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 that it 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.
