Revision [18142]

This is an old revision of APIandDataRequests made by KristenVicedomini on 2016-07-28 12:19:43.

 

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


If none of these solutions meet their needs:


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.


How to Manage The API Subscribers


Understanding the API

In order to answer the bulk of questions you will get, you will need to familiarize yourself with:
the purpose and role of the API
how the API and registration process works for users ( It helps to go through and register for a key for yourself, and then use that key to pull out data)
the data included in it (and not included)- see: the API documentation, and the data crib sheet Data Restrictions for Redistribution
the policies surrounding it: http://wiki.votesmart.org/APIandDataRequests#hn_Terms_of_Use_and_Enforcement Terms of Use and Enforcement]], Subscription Terms, and Charging Policies

History of API Subscriptions and Future Considerations
see: hr/3-HUMAN RESOURCES/New Hires/1-Job Descriptions/Operations/Office Manager
DevComm- Data Entry into Donor Perfect

Administration of the Registration Process
In mid-October 2012, a new registration system through Django Admin was instituted to streamline registration with a MyVotesmart account. New registrations submit payment and complete a form, at which point an API key is automatically activated. Previous subscribers wishing to resubscribe should be able to simply login to their account and submit their payment due in order to reactivate the key. Officemgr@votesmart.org receives a purchase confirmation, which is then forwarded to membership@votesmart.org. The Development Department then adds the API Subscriber (if new) and their gift information into Donor Perfect

If the subscriber marks that they are a member, the key is not automatically activated. Membership@votesmart.org receives an email, with the subject line: [pypvs] API Subscription Activation Review], asking to verify membership. Membership forwards the request to officemgr@votesmart.org stating whether or not the person is a member at the $45 level or higher. Office Manager will then either activate the key if they are a member (by clicking on the link contained in the member verification email) or contact the individual to let them know that their key cannot be activated without the appropriate payment.

If the subscriber indicates that they are unsure which payment level to choose, then an email will be sent to officemgr@votesmart.org – [pypvs] API Subscription Intervention Needed. The email will contain a link to the fee schedule. After reviewing the registration form (found in Django administration, http://skittles.votesmart.org/admin/ - Survey Answers, checking the user and submission date) check the box next to the correct payment level, click submit, and an email will be sent to the user. Note: for those subscribers who may be at a level higher than the $2,000 subscription level, you should defer to the National Director (who will consult the President) to assign the appropriate fee


Some subscribers may request a more formal invoice or receipt. Templates for these may be found in hr>Partnerships and API Sales->API Information->Pricing


Reviewing Existing API Subscriptions
If you need to review an API registration at a later date, you can access their user account through Django admin (http://skittles.votesmart.org/admin). Click on Users, search by user name or email address, and then click on the user. Scroll down to the bottom of the page, which displays the API key next to API Registration. The key is a link, which will then display information including the subscription type, whether the key is active, and survey details. From this interface you may manually activate or deactivate a key. Click on the link by survey details (API Subscription Survey) to review the registration form. *Check Mantis ticket #0006752 to see if this has changed per Melanie and Mike's conversation*API subscribers imported from the old system may not have had their survey transferred, and their answers may only be available via the original survey in Icontact. This is also stored here: hr/5- PROJECT MGMT/API Information/Nov 11 - Oct 12 API Registration Forms. If you want them to fill out the survey, you can send them to the following page and just tell them not to bother with making payment at the following step: http://votesmart.org/share/api/register/step-2 [^]. An email may also be sent out to affected users to make this request\

For more information about API subscribers see:
hr>Partnerships and API Sales->API Information->Subscribers
Partnerships and Large API Users Contact Notes

For more information about API subscription payments see:
Donor Perfect records
hr>Partnerships and API Sales->API Information


The Office Manager is the primary manager of API subscriptions and is generally the first point of contact with API users.

All API correspondence and receipts should be saved and filed in the appropriate folders of the officemgr@votesmart.org account for future reference.

Questions about the fee schedule and API policies are generally answered by the Office Manager.

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

API users can discuss usage and implementation problems with other users by subscribing to the mailing list by E-mailing pvsapi-subscribe@vote-smart.org.

To confirm API payments have been received, consult the Development department.

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 should be run by the National Director. The National Director may need to consult the President




hr>Partnerships and API Sales->API Information->Subscribers
Partnerships and Large API Users Contact Notes
There is one comment on this page. [Display comment]
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki