Little Polls Developer API

Introduction
LittlePolls has launched an API to create polls. Developers are now invited to
use this API to create polls from their applications. Optionally, we also allow
developers to post the polls on selective social networks using our API.

We currently support posting polls to twitter.
Back To Top

Create Poll
Creating a poll on using our API, is as simple as sending a XML Request,
and receiving a XML Response.

We have also provided a sample PHP Client class, which takes cares of the XML
Request, and Response Handling.

XML Request
Here is an example Request XML, followed by an explanation of the elements.

Note: You can specify upto 4 questions in one poll, and upto 4 answers per
question.

Sample XML Request

<?xml version="1.0" encoding="UTF-8" ?>
<request type="createpoll">
    <response responsetype="xml" level="advanced" />
    <server domain="mydomain.com" user="MY_USERID"
apikey="abcdefghabcdefghabcdefghabcdefgh"/>
    <poston server="twitter" user="twitteruser"
passkey="twitterpass" message="Please Vote - {{question}} -
{{url}}" />
    <poll myid="MY_POLLID" validity="14" <a
href="#styles">style</a>="0"
access="public">
        <question>
            <q>Which is the best soft drink in the world?</q>
            <a>Coca-Cola</a>
            <a>Pepsi</a>
            <a>Mirinda</a>
            <a>Mountain Dew</a>
        </question>
        <question>
            <q>Which is the best social network?</q>
            <a>Facebook</a>
            <a>MySpace</a>
            <a>Orkut - Google Rocks!!!</a>
            <a>Twitter</a>
        </question>
        <question>
            <q>Which movie are we going to watch this saturday?</q>
            <a>The Hulk</a>
            <a>Iron Man</a>
            <a>Batman</a>
            <a>Slumdog Millionaire</a>
        </question>
        <question>
            <q>Can I have only two options to a question?</q>
            <a>Yes</a>
            <a>No</a>
        </question>
    </poll>
</request>


Explanation of XML Elements

Back To Top


XML Response
Here are example Response XML as per your response level selected, followed by
an explanation of the elements. The response XML below are for the same request,
and hence only differ in the amount of detail (level).

Level can be specified by using the level attribute.

Sample XML Response - level "url"
Choose this level if you only need the Poll URL as response from the API.

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <poll myid="MY_POLLID" lpid="1">
        <url>http://littlepolls.com/lp1</url>
    </poll>
</response>


Sample XML Response - level "simple"
Choose this level if you only need the Poll URL, post message status, and result
URLs as response from the API.

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <poston server="twitter" status="0"
statusmsg=""/>
    <poll myid="MY_POLLID" lpid="1">
        <url>http://littlepolls.com/lp1</url>
        <result>
            <url>http://littlepolls.com/lr1</url>
           
<xml>http://littlepolls.com/xml/22175bb5f5bc6b1f5dbaff828591efa7.xml</xml>
        </result>
        <votes>0</votes>
    </poll>
</response>


Sample XML Response - level "advanced"
Choose this level if you need all details.

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <server domain="mydomain.com" user="MY_USERID"/>
    <poston server="twitter" status="0"
statusmsg=""/>
    <poll myid="MY_POLLID" lpid="1">
        <url>http://littlepolls.com/lp1</url>
        <embed><![CDATA[<script type="text/javascript"
language="javascript"
src="http://littlepolls.com/polls/1.js"></script><noscript>
<a href ="http://littlepolls.com/" >Little Polls</a> -
<a href ="http://littlepolls.com/lp1" >Take My Poll</a>
</noscript>]]></embed>
        <result>
            <url>http://littlepolls.com/lr1</url>
           
<xml>http://littlepolls.com/xml/22175bb5f5bc6b1f5dbaff828591efa7.xml</xml>
        </result>
        <votes>0</votes>
    </poll>
</response>


Explanation of XML Elements

Poll Results
Littlepolls API returns you the poll result URL, and result XML URL when you
create the poll. This URL is available in response when response level is simple or advanced.

( See result. )
Back To Top


PHP Client
We have written a sample PHP Client, which will manage XML Requests, and
Response for you.

Sample Code
A Sample PHP code demonstrating how the client can be used to create polls.

<?php
    require('class.littlepolls.php');
    $client = new littlepolls();

    $result = $client->createPoll($response, $server, $poston, $poll, $questions);
    if ( $client->getError() == 0 )
    {
        $url = $client->getURL();
        $embedCode = $client->getEmbedCode();
    }
    else
    {
        echo $client->getError() . "<br />";
        echo $client->getErrorString() . "<br
/>";
    }
?>

Back To Top


Constructor: littlepolls()
    //Littlepolls constructor method.
Back To Top


Method: createPoll()
    /**
     * Creates a poll on littlepolls server, and optionally posts it to a social
network.
     *
     *
     * @access public
     * @param array $response - response type(xml), and
level(url/simple/advanced) to receive from server.
     * @param array $server - server details from your
application: your server domain, your user's id, your apikey
     * @param array $poston - social network details to
post the poll on: server, user, passkey, and message
     * @param array $poll - poll details: myid, validity, style, access.
     * @param array $questions - array of questions
     * @return $responseDetails on success HTTP
call to the server, null on failure.
     */

     function createPoll($response, $server, $poston, $poll, $questions)
Back To Top


Method: getError()
    /**
     * This function will return the error (an int value), if any. If no error
has occured, it will return 0.
     * For details of the error codes see Error Codes
     * Note: This function should be called only after a createPoll function is
called.
     *
     * @access public
     * @return $error
     */

     function getError()
Back To Top


Method: getErrorString()
    /**
     * This function will return a more human readable error message.
     * Note: This function should be called only after a createPoll function is
called.
     *
     * @access public
     * @return $errorString
     */

     function getErrorString()
Back To Top


Method: getURL()
    /**
     * This function will return the url of the poll created on littlepolls
server.
     * Note: This function should be called only after a createPoll function is
successful.
     *
     * @access public
     * @return $url
     */

    function getURL()
Back To Top


Method: getEmbedCode()
    /**
     * This function will return the embedcode for the poll created on
littlepolls server.
     * Note: This function should be called only after a createPoll function is
successful.
     *
     * @access public
     * @return $embedCode
     */

    function getEmbedCode()
Back To Top


API Response Configuration
    // Configure the createpoll APIs response type as
desired.
    $response = array(
            'responsetype' => 'xml', // This can be only
'xml'
            'level' => 'advanced' // This can either be
'url', 'simple' or 'advanced'. Please see the explanation of response levels.
        );
Back To Top


Requesting Server Identification
    // If you wish to later retrieve the poll details or
poll results using our APIs, please identify yourself with the following
information.
    $server = array(
            'domain' => 'mydomain.com', // server: This
is your server ID. This should ideally be the domain from which you are sending
a request to littlepolls. e.g. mydomain.com
            'user' => 'myuser' // myuser: This is a
unique ID for the user who is creating a poll. If you provide this field, you
can later retrieve all polls from the same user. It can be the User ID or the
username or a unique user email.
        );
Back To Top


Post Your Poll On Social Networks
    // If you wish us to auto post the poll link to a
social network, please provide the following details in the poston element of
the request.
    $poston = array(
            'server' => 'twitter', // Currently we
support only Twitter
            'user' => 'littlepolls', // User Name to post
as
            'passkey' => 'twitter123', // password or key
to be used for posting
            'message' => '{{user}} wants you to vote on the poll - {{question}}
- {{url}}'
            // message format. {{user}}, {{question}} and
{{url}} string will be auto replaced in our API.
        );
Back To Top


Configure Your Poll
    // Configure the poll element
    $poll = array(
            'myid' => 1, // This is a poll ID for your
own record keeping. You can later send a request to us using this ID or the
LittlePolls pollID returned to you in response to retrieve all details of a
poll.
            'validity' => 14, // Number of days poll
should be kept open for voting.
            'style' => 0, // Color
code for the style to be used on this poll. This can be 0,1,2 or 3.
            'access' => 'public' // public or private.
Whether this poll is public, and should appear in littlepolls directory, allow
users to vote; or it is a private poll (only users who know the poll URL will be
able to vote.)
        );
Back To Top


Configure Poll Questions
    /**
     * Build an array of poll questions and their respective answers
     *             $questions = array(
     *                     array(
     *                         "question" => "Your question 1 here",
     *                         "answers" => array("answer 1", "answer 2",
"answer 3", "answer 4")
     *                         ) ,
     *                     array(
     *                         "question" => "Your question 2 here",
     *                         "answers" => array("answer 1", "answer 2",
"answer 3", "answer 4")
     *                         ) ,
     *                     array(
     *                         "question" => "Your question 3 here",
     *                         "answers" => array("answer 1", "answer 2",
"answer 3", "answer 4")
     *                         ) ,
     *                     array(
     *                         "question" => "Your question 4 here",
     *                         "answers" => array("answer 1", "answer 2",
"answer 3", "answer 4")
     *                         )
     *                     );
     */

    $questions = array();
    for($i=1;$i<=4;$i++)
    {
        if($_REQUEST['q' . $i])
        {
            $questions[$i] = array(
                'question' => $_REQUEST['q' . $i],
                'answers' => array()
                );
            for($j=1;$j<=4;$j++)
                if($_REQUEST['a' . $i . '' . $j])
                    $questions[$i]['answers'][$j] = $_REQUEST['a' . $i . '' .
$j];
        }
    }
Back To Top

Style Code 0	Style Code 1
Style Code 2	Style Code 3