API Beta
To make our service even better, we're opening it up to developers so that they can build slick poll visualizations or integrate real-time text message voting with websites and applications.
Disclaimer
This API is Beta which means these XML APIs are subject to change without notice. While we will do our best to tell you when we change our APIs, we can not be responsible if it breaks your application.
Our XML format is different then that of ActiveRecords to_xml method; we include href attributes for all of our related resources. You should not manually resolve URLs in your application; rather, you should consume our href tags to access any related entities. This will make your application much less brittle in the event that we have to change the locations of our resources.
Authentication
Certain portions of this application are password protected including the list of polls that a user owns and the results of a poll. To access any password protected resources, use basic HTTP authentication.
Polls
To retrieve a list of polls that the current user owns:
$ curl http://www.polleverywhere.com/polls.xml -basic --basic -u username:password
<?xml version="1.0" encoding="UTF-8"?>
<polls>
<poll>
<id href="/polls/LTcyOTI2ODU4MQ.xml">LTcyOTI2ODU4MQ</id>
<question>What is your favorite RGB color?</question>
<multivote type="boolean">false</multivote>
<is-open>false</is-open>
<updated-at type="datetime">Sun Dec 09 21:33:59 -0600 2007</updated-at>
<created-at type="datetime">Sun Dec 09 21:33:59 -0600 2007</created-at>
<options href="/polls/LTcyOTI2ODU4MQ/options.xml"/>
<results href="/polls/LTcyOTI2ODU4MQ/results.xml"/>
</poll>
<poll>
<id href="/polls/LTMzMjY1MTc0Mw.xml">LTMzMjY1MTc0Mw</id>
<question>What is your favorite CYMK color?</question>
<multivote type="boolean">false</multivote>
<is-open>false</is-open>
<updated-at type="datetime">Sun Dec 09 21:34:43 -0600 2007</updated-at>
<created-at type="datetime">Sun Dec 09 21:34:43 -0600 2007</created-at>
<options href="/polls/LTMzMjY1MTc0Mw/options.xml"/>
<results href="/polls/LTMzMjY1MTc0Mw/results.xml"/>
</poll>
</polls>
To retrieve a specific poll:
$ curl http://www.polleverywhere.com/polls/LTE4NDg0Njk3OQ.xml
<?xml version="1.0" encoding="UTF-8"?>
<poll>
<id href="/polls/LTE4NDg0Njk3OQ.xml">LTE4NDg0Njk3OQ</id>
<question>What is your favorite color?</question>
<multivote type="boolean">true</multivote>
<is-open>true</is-open>
<updated-at type="datetime">Sun Dec 09 15:00:27 -0600 2007</updated-at>
<created-at type="datetime">Sun Dec 09 15:00:27 -0600 2007</created-at>
<options href="/polls/LTE4NDg0Njk3OQ/options.xml"/>
<results href="/polls/LTE4NDg0Njk3OQ/results.xml"/>
</poll>
It is important to note that while poll URLs are obscufated to prevent people from guessing the URL of a poll, they are public! If you share or publish the URL to a poll, other people my access and vote on the poll.
Options
A Poll has many options that a user can choose from as well as the number of "votes" that each option contains. The options can be polled regularly by your application to update the votes while making them appear in realtime. We recommend polling the votes once every 5 seconds. The Choice is the SMS value that a voter will text to our shortcode, 41411.
$ curl http://www.polleverywhere.com/polls/LTE4NDg0Njk3OQ/options.xml
<?xml version="1.0" encoding="UTF-8"?>
<options>
<option>
<id href="/polls/LTE4NDg0Njk3OQ/options/106.xml">106</id>
<value>Red</value>
<results-count>0</results-count>
<position>1</position>
<choice>CAST 1047</choice>
<poll-id href="/polls/LTE4NDg0Njk3OQ.xml">LTE4NDg0Njk3OQ</poll-id>
</option>
<option>
<id href="/polls/LTE4NDg0Njk3OQ/options/104.xml">104</id>
<value>Blue</value>
<results-count>2</results-count>
<position>2</position>
<choice>CAST 1048</choice>
<poll-id href="/polls/LTE4NDg0Njk3OQ.xml">LTE4NDg0Njk3OQ</poll-id>
</option>
<option>
<id href="/polls/LTE4NDg0Njk3OQ/options/110.xml">110</id>
<value>Green</value>
<results-count>0</results-count>
<position>3</position>
<choice>CAST 1049</choice>
<poll-id href="/polls/LTE4NDg0Njk3OQ.xml">LTE4NDg0Njk3OQ</poll-id>
</option>
</options>
Results
Each vote for a poll is stored as a result which includes information about what option the respondent chose, they poll they voted on, and when they voted. Access to this information requires authentication.
$ curl http://www.polleverywhere.com/polls/LTcyOTI2ODU4MQ/results.xml -basic --basic -u username:password
<?xml version="1.0" encoding="UTF-8"?>
<results>
<result>
<id href="/polls/LTcyOTI2ODU4MQ/results/2999.xml">2999</id>
<received-at>Tue Jan 01 15:32:29 UTC 2008</recieved-at>
<option href="/polls/LTcyOTI2ODU4MQ/options/1258.xml">Blue</option>
<poll-id href="/polls/LTcyOTI2ODU4MQ.xml">LTcyOTI2ODU4MQ</poll-id>
</result>
<result>
<id href="/polls/LTcyOTI2ODU4MQ/results/2998.xml">2998</id>
<received-at>Tue Jan 01 15:32:27 UTC 2008</recieved-at>
<option href="/polls/LTcyOTI2ODU4MQ/options/1259.xml">Green</option>
<poll-id href="/polls/LTcyOTI2ODU4MQ.xml">LTcyOTI2ODU4MQ</poll-id>
</result>
<result>
<id href="/polls/LTcyOTI2ODU4MQ/results/2997.xml">2997</id>
<received-at>Tue Jan 01 15:32:25 UTC 2008</recieved-at>
<option href="/polls/LTcyOTI2ODU4MQ/options/1258.xml">Blue</option>
<poll-id href="/polls/LTcyOTI2ODU4MQ.xml">LTcyOTI2ODU4MQ</poll-id>
</result>
<result>
<id href="/polls/LTcyOTI2ODU4MQ/results/2996.xml">2996</id>
<received-at>Tue Jan 01 15:32:23 UTC 2008</recieved-at>
<option href="/polls/LTcyOTI2ODU4MQ/options/1257.xml">Red</option>
<poll-id href="/polls/LTcyOTI2ODU4MQ.xml">LTcyOTI2ODU4MQ</poll-id>
</result>
</results>