Revision [18147]

This is an old revision of APIandDataRequests made by KristenVicedomini on 2016-07-29 09:40:15.

 

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:

Scope of Data Available in the API

see:

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:

Current Policies for Standard API Subscriptions


The reason we charge for the API is to support the costs of collecting and delivering the data. We attempt to apply these fees as equitably as possible based on the potential for usage
.
Note: exceptions should only be considered if the user requests an exception

High-volume users, name-brand users, users looking to relicense or resell data, users looking for a separate contract, or other unusual questions should be run by the National Director prior to setting a fee amount

General Terms
Subscribers are required to fill out the usage survey upon registration and submit the appropriate payment in accordance with our charging policy. They sign up for a MyVoteSmart account in the process. See:[[http://wiki.votesmart.org/APIandDataRequests#hn_Administration_of_the_Registration_Process Administration of the Registration Process]]

Subscribers are required to abide by the terms of use
Each API user is given a unique API key, which gives them access to the API and allows us to control and monitor their usage.

Subscription Length
as of 2016, subscriptions are based on the election cycle. This is a Bi-annual subscription which begins at registration and generally lasts through December 31 of even-numbered (general election) years. Those who sign up between November 1 and December 31 of even-numbered years will have their subscription extended through December 31 of two years later. So, for example, those who sign up between November 1, 2014 and October 31, 2016 will have a subscription term starting upon sign-up and ending December 31, 2016. Those that sign up from November 1, 2016 through October 31, 2018 would have a subscription term starting upon sign-up and ending December 31, 2016.

Exceptions: A trial key may be possible, upon request. A one month trial key can be issued through the “Already a Member” option with the understanding that the key will be deactivated after 30 days, at which time the user cannot use any Vote Smart data obtained by the API. A longer trial key can be issued for potential partner/high-tier organizations. We may also choose to charge a pro-rated fee for longer trial session. If the user decides to purchase an API key at the end of the trial, be sure to change the user api information in Django admin to reflect the subscription type, payment date, and subscription start date

Subscribers Receive

Charging Policy
the standard charging policy is stated in the registration form and the Upper Tier fee schedule (also located at hr>Partnerships and API Sales->API Information->Pricing)

Personal Use Exceptions: Undergraduate and graduate students who are conducting research for a class can access the API at the $45 level. If that is too burdensome, then they can purchase a Millennial Membership at $15.

Other Uses
Businesses, academic institutions or other groups wishing to use the API, or individuals looking to publish our data to the public must pay for “Other Use” which can span anywhere from $100 to $50,000+. The fee schedule is based on Organization's potential for use. Those wishing to relicense or resell data must pay a minimum of $15,000.
Exceptions: If someone claims the fee is too burdensome, we can consider a reduced fee on a case-by-case basis. Generally, we will suggest a reduced fee of $250, but only if 2 out of 3 of the following criteria are met: 1. low quality/traffic website, 2. small budget, 3. not a direct competitor.


Custom API Subscriptions and Partnerships

High-volume users, name-brand users, users looking to relicense or resell data, users looking for a separate contract, or other unusual questions should be run by the National Director prior to setting a fee amount. The National Director will need approval from the President for any non-standard agreements. Sometimes a separate agreement may be necessary, or we may want to develop more of a two-way partnership with them

Current Partnerships and Potential Partnerships: Partnerships and Large API Users Contact Notes
actual contracts are located in the physical administrative files

Past Partnership and Other Info:
hr>Partnerships and API Sales->API Information->Subscribers
hr>partnerships & api sales>contracts and partnership discussions
hr>partnerships & api sales>link to partnership with media orgs

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
hr>partnerships & api sales>contracts and partnership discussions
hr>partnerships & api sales>link to partnership with media orgs

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

Resources for API Subscribers

[[Scope of Data
hr>partnerships & api sales>data collection processes
Current Policies for API Subscriptions
Terms of Use


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

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