Web Services API
The Voter Guide Toolkit web services API provides RESTful read-only access to the data in your voter guide. Use the WS API to consume your voter guide data for use in other applications. For example, you can use the WS API to create an HTML widget displaying a candidate profile in another part of your web site.
There are three services that comprise the WS API:
- GuideService – returns information about your voter guide
- BallotItemService – returns information about a race or referendum
- BallotItemChoiceService – returns information about a candidate or referendum choice
Detailed API information is available in javadoc format here: //hq.thevoterguide.org/doc/wsapi/
GuideService
Example URL: //www.thevoterguide.org/ws/{guideKey}/voter-guide.xml
Returns top-level information about your guide, including the title and all the races and referendums in the guide.
GuideService/search
Example URL: //www.thevoterguide.org/ws/{guideKey}/voter-guide/search.xml?q=query
Searches the guide for matching races and candidates and returns the top 10 results.
BallotItemService
Example URL: //www.thevoterguide.org/ws/{guideKey}/items/{itemIdOrUserData}.xml
Returns detailed information about a particular race or referendum. You can look up a race/referendum either by its the integer ID or by its string “user data” field.
BallotItemService/search
Example URL: //www.thevoterguide.org/ws/{guideKey}/items/search.xml?q=query
Searches the guide for matching races/referendums and returns the top 10 results.
BallotItemChoiceService
Example URL: //www.thevoterguide.org/ws/{guideKey}/choices/{choiceIdOrUserData}.xml
Returns detailed information about a particular candidate or referendum choice. You can look up a candidate either by its the integer ID or by its string “user data” field.
BallotItemChoiceService/search
Example URL: //www.thevoterguide.org/ws/{guideKey}/choices/search.xml?q=query
Searches the guide for matching candidates/referendum choices and returns the top 10 results.
Formats
The WS API is published in both XML (default) and JSON. Append “.xml” to the URL to format the response in XML. Append “.js” to format the response in JSON. Conversion from XML to JSON is performed according to Jettison’s “Mapped” convention.
Usage
You must have the WS API enabled for your guide and of the API URLs to return data. Contact e-thePeople if you would like the API to be enabled for you guide.
If you will use the WS API for high-traffic web applications, e-thePeople recommends that you proxy and cache the responses of the WS API. e-thePeople may in the future limit traffic to the WS API if client applications are generating too much traffic to the API. Implementing a server-side cache for your application with a timeout of 1 to 6 hours will greatly reduce the load on the e-thePeople servers.