Skip to content

Latest commit

 

History

History
 
 

v4

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 

README.md

Polar API

Note that if you are using the Polar API to displaying Polar content yourself, you must adhere to Polar's display guidelines.

Production and test accounts

The base URL for all production API's is:

https://polarb.com/api/v4

For testing, the base URL can point to our staging servers:

https://polar-rails-staging.herokuapp.com/api/v4

If you plan on using an API endpoint which requires authentication (see below), you will need to sign up at a polar account on each environment you wish to use:

Create a development account: https://polar-rails-staging.herokuapp.com/join

Create a production account: http://polarb.com/join

API endpoints

Get current user information

Get credentials for the current viewing user.

GET /users/me

Returns the following if the user is not authenticated:

{
  "anonymousUserID": "d611093317bbe73c6327773b551af0c646b8cb9cefe57ef7b0dd3862c711"
}

Returns the following if the user is authenticated:

{
  "userID": 1,
  "username": "jcole",
  "name": "Jeffrey",
  "location": "Newton, MA",
  "url": "/users/jcole",
  "twitter_username": "jeff_cole",
  "profilePhotoLarge": "http://polar-development-avatars-jeff.s3.amazonaws.com/000/000/001/1-large_retina-dc41e6a5a7d95012.jpg",
  "profilePhotoSmall": "http://polar-development-avatars-jeff.s3.amazonaws.com/000/000/001/1-small_retina-dc41e6a5a7d95012.jpg",
  "authToken": "xxAuthTokenHerexx",
  "publisher": {
    "id": 58,
    "name": "jcole_publisher",
    "display_name": "Jeff Cole Publisher"
  }
}

The publisher attribute exists if the user belongs to a publisher team.

Example
https://polarb.com/api/v4/users/me

Authentication

Log in and get user credentials.

POST /users/authenticate
Param Type Required Description
email_or_username string required User's Polar username or email. Case insensitive.
password string required User's Polar password.

Returns:

{
  "userID": 1,
  "username": "jcole",
  "name": "Jeffrey",
  "location": "Newton, MA",
  "url": "/users/jcole",
  "twitter_username": "jeff_cole",
  "profilePhotoLarge": "http://polar-development-avatars-jeff.s3.amazonaws.com/000/000/001/1-large_retina-dc41e6a5a7d95012.jpg",
  "profilePhotoSmall": "http://polar-development-avatars-jeff.s3.amazonaws.com/000/000/001/1-small_retina-dc41e6a5a7d95012.jpg",
  "website": "",
  "about": "About Me",
  "pollsCreatedCount": 490,
  "pollsVotedOnCount": 195,
  "votesReceivedCount": 1274,
  "favoriteCount": 60,
  "favoritesReceivedCount": 39,
  "commentsCount": 240,
  "commentsReceivedCount": 307,
  "followingCount": 3,
  "followedByCount": 7,
  "success": true,
  "email": "[email protected]",
  "confirmed": true,
  "authToken": "xxAuthTokenHerexx",
  "following_ids": [45, 337, 338],
  "favorite_poll_ids": [294, 645, 652,]
}

Get a list of recent polls

Get a list of recent popular polls on Polar. Returns a set of 10 polls.

To get the next 10 polls, use the before_poll_id parameter.

Authentication is not required for this endpoint.

GET /polls
Param Type Required Description
before_poll_id number optional Get the next set of polls prior to this poll id. 
[
  {
    "pollID": 153722,
    "url": "http://polarb.com/153722-which-game-are-you-going-to-play-in-2014",
    "shortUrl": "http://polarb.com/153722",
    "caption": "Which Game Are You Going To Play In 2014?",
    "created": "2014-01-20T12:46:53Z",
    "public": true,
    "creator": {
      "userID": 19251,
      "name": "Mike Topo",
      "username": "TopoMaschio",
      "profilePhotoSmall": "http://avatars-polarb-com.a.ssl.fastly.net/000/019/251/19251-small_retina-6cd9fe6fbbca3bd8.jpg"
    },
    "choices": [
      {
        "name": "Driveclub",
        "sortOrder": 1,
        "voteCount": 7
      },
      {
        "name": "The Crew",
        "sortOrder": 2,
        "voteCount": 5
      }
    ],
    "images": [
      {
        "sortOrder": 1,
        "url": "http://polls-polarb-com.a.ssl.fastly.net/000/153/722/153722-1-medium-34615e8fee6b5176.jpg",
        "largeUrl": "http://polls-polarb-com.a.ssl.fastly.net/000/153/722/153722-1-large-34615e8fee6b5176.jpg"
      }
    ],
    "voteCount": 12,
    "favoriteCount": 0,
    "commentCount": 1,
    "comments": [
      {
        "commentID": 258899,
        "body": "#2014games2play",
        "date": "2014-01-20T13:28:56Z",
        "userID": 19251,
        "username": "TopoMaschio",
        "profilePhotoSmall": "http://avatars-polarb-com.a.ssl.fastly.net/000/019/251/19251-small_retina-6cd9fe6fbbca3bd8.jpg"
      }
    ]
  },
  ...
]

Example
https://polarb.com/api/v4/polls

Get a list of polls created by a user

Get a list of polls created by a user on Polar. Returns a set of polls. These are paginated -- by default, 10 are returned for each call.

Authentication is not required for this endpoint.

GET /users/:username/polls_created
Param Type Required Description
username string required User's Polar username (case insensitive).
page number optional For paging through result set: show page 1-n. Default is 1.
limit number optional Size of result set (i.e, number of polls) to return. Default is 10. 
[{
  "pollID": 98779,
  "url": "http://polarb.com/98779-ios-icon-showdown-photos",
  "shortUrl": "http://polarb.com/98779",
  "caption": "iOS Icon Showdown: Photos?",
  "pollType": "single-photo",
  "created": "2013-06-21T16:46:32Z",
  "public": true,
  "private": false,
  "creator": {
    "userID": 522,
    "name": "Sonja",
    "username": "giantsquid",
    "profilePhotoSmall": "http://avatars-polarb-com.a.ssl.fastly.net/000/000/522/522-small_retina-71f6db4617740052.jpg"
  },
  "choices": [
    {
      "name": "iOS 6",
      "sortOrder": 1,
      "voteCount": 13935,
      "isWinning": false
    },
    {
      "name": "iOS 7",
      "sortOrder": 2,
      "voteCount": 23520,
      "isWinning": true
    }
  ],
  "images": [
    {
      "sortOrder": 1,
      "url": "http://polls-polarb-com.a.ssl.fastly.net/000/098/779/98779-1-medium-0a7356c3965f3606.jpg",
      "largeUrl": "http://polls-polarb-com.a.ssl.fastly.net/000/098/779/98779-1-large-0a7356c3965f3606.jpg"
    }
  ],
...
}]

Example
https://polarb.com/api/v4/users/jcole/polls_created

Get a list of ids for all polls created by a user

Get a list of ID's for all polls created by a user on Polar. Returns a set of poll_ids.

Authentication is not required for this endpoint.

GET /users/:username/poll_ids_created
Param Type Required Description
username string required User's Polar username (case insensitive).
unvoted string optional Only show poll_ids that the viewing user has not already voted on. Valid values: "true" or "false"
anonymous_user_id string optional Then identification of the user viewing, if the user does not have a Polar account. See authentication for users without a Polar account to get this value. 
{
  "poll_ids": [856, 855, 852, 851, 850, 849, 848]
}

Example
https://polarb.com/api/v4/users/jcole/poll_ids_created

Get a list of poll sets created by a publisher

Get a list of all poll sets created by a publisher on Polar.

Authentication is not required for this endpoint.

GET /publishers/:publisher_name/poll_sets
Param Type Required Description
publisher_name string required The name of the publisher. This value can be found in the returned JSON from the /users/me endpoint if the viewing user belongs to a publisher. 
[
  {
    "created_at": "2014-02-06T21:45:22Z",
    "display_name": "Car Questions",
    "id": 1335,
    "name": "Car Questions",
    "poll_ids": [
      129302,
      152921,
      153126,
      129304,
      153123,
      153122,
      150020,
      146669,
      59375
    ],
    "publisher_id": 58,
    "updated_at": "2014-02-06T21:45:22Z"
  },
  {
    "created_at": "2013-12-21T18:54:19Z",
    "display_name": "Jeff's Golf Survey",
    "id": 661,
    "name": "Jeff's Golf Survey",
    "poll_ids": [
      119684,
      128455,
      555,
      121497,
      462,
      65051,
      593,
      579,
      429
    ],
    "publisher_id": 58,
    "updated_at": "2013-12-21T18:54:40Z"
  }
]

Example
https://polarb.com/api/v4/publishers/jcole/poll_sets

Get data for a poll

Get all data for a poll. Includes poll caption, choice names, image location, comments (if any), and most recent votes (if any).

Authentication is not required for this endpoint.

GET /polls/:poll_id
Param Type Required Description
poll_id number required Poll ID. 
{
  "pollID": 98779,
  "url": "http://polarb.com/98779-ios-icon-showdown-photos",
  "shortUrl": "http://polarb.com/98779",
  "caption": "iOS Icon Showdown: Photos?",
  "pollType": "single-photo",
  "created": "2013-06-21T16:46:32Z",
  "public": true,
  "private": false,
  "creator": {
    "userID": 522,
    "name": "Sonja",
    "username": "giantsquid",
    "profilePhotoSmall": "http://avatars-polarb-com.a.ssl.fastly.net/000/000/522/522-small_retina-71f6db4617740052.jpg"
  },
  "choices": [
    {
      "name": "iOS 6",
      "sortOrder": 1,
      "voteCount": 13935,
      "isWinning": false
    },
    {
      "name": "iOS 7",
      "sortOrder": 2,
      "voteCount": 23520,
      "isWinning": true
    }
  ],
  "images": [
    {
      "sortOrder": 1,
      "url": "http://polls-polarb-com.a.ssl.fastly.net/000/098/779/98779-1-medium-0a7356c3965f3606.jpg",
      "largeUrl": "http://polls-polarb-com.a.ssl.fastly.net/000/098/779/98779-1-large-0a7356c3965f3606.jpg"
    }
  ],
  "voteCount": 37455,
  "favoriteCount": 2,
  "commentCount": 5,
  "comments": [
    {
      "commentID": 156820,
      "body": "#iosicons",
      "date": "2013-06-21T16:58:00Z",
      "userID": 522,
      "username": "giantsquid",
      "profilePhotoSmall": "http://avatars-polarb-com.a.ssl.fastly.net/000/000/522/522-small_retina-71f6db4617740052.jpg"
    },
    {
      "commentID": 156845,
      "body": "I think the majority of votes at new icons are given just because they are new, and not because they are the most beautiful",
      "date": "2013-06-21T17:53:05Z",
      "userID": 17006,
      "username": "Ricky-el",
      "profilePhotoSmall": "http://avatars-polarb-com.a.ssl.fastly.net/000/017/006/17006-small_retina-4b36f1eaf8291b75.jpg"
    },
    {
      "commentID": 157183,
      "body": "Agreed. People crave novelty. As long as its new, who cares if its good?",
      "date": "2013-06-22T07:31:06Z",
      "userID": 17463,
      "username": "ahmed_von_ahmed",
      "profilePhotoSmall": "http://avatars-polarb-com.a.ssl.fastly.net/000/017/463/17463-small_retina-6cedf042ee8626dc.jpg"
    },
    {
      "commentID": 158918,
      "body": "Agreed. But does it reflect end user mindset or a vocal minority?",
      "date": "2013-06-24T23:50:12Z",
      "userID": 8694,
      "username": "dhstannard",
      "profilePhotoSmall": "http://avatars-polarb-com.a.ssl.fastly.net/000/008/694/8694-small_retina-0ff851691c1bfaa8.jpg"
    },
    {
      "commentID": 196661,
      "body": "I vote for ones I like best. So a mix of both.",
      "date": "2013-08-17T02:06:50Z",
      "userID": 16300,
      "username": "bulbie",
      "profilePhotoSmall": "http://avatars-polarb-com.a.ssl.fastly.net/000/016/300/16300-small_retina-45e41e46e64ab6fb.jpg"
    }
  ],
  "firstChoiceName": "iOS 6",
  "secondChoiceName": "iOS 7",
  "firstChoiceVoteCount": 13935,
  "secondChoiceVoteCount": 23520,
  "firstChoicePercentage": 37,
  "secondChoicePercentage": 63,
  "firstWinning": false,
  "secondWinning": true,
  "image": {
    "sortOrder": 1,
    "url": "http://polls-polarb-com.a.ssl.fastly.net/000/098/779/98779-1-medium-0a7356c3965f3606.jpg",
    "largeUrl": "http://polls-polarb-com.a.ssl.fastly.net/000/098/779/98779-1-large-0a7356c3965f3606.jpg"
  },
  "userVote": 2,
  "userVoteDate": "2013-06-21T17:49:31Z",
  "votes": [
    {
      "voteID": 24435051,
      "userID": null,
      "anonymousUserID": "0375645f3df85bf5595643cdb83c886079ca7b59ea40a44261784c6616ebf99d29f2f41e1d03137c62c299abe104996c7958843ce5dbb6017445a9e9d035d48f",
      "name": null,
      "username": "New Polar",
      "choice": 2,
      "date": "2014-03-04T14:59:12Z",
      "profilePhotoSmall": "http://assets-polarb-com.a.ssl.fastly.net/assets/user_default-345995fd38b8bf93e962b909e1c03c9b.png"
    },
    {
      "voteID": 24433600,
      "userID": null,
      "anonymousUserID": "51bf492873cf02ad246ce2e888afbbcbabfdcbca48765cd975f3bff2b0493272d6d1c9fd52d3d57afdd13546d43c47546f8f78a2ccb13af2dc3323fc8a458b3f",
      "name": null,
      "username": "New Polar",
      "choice": 2,
      "date": "2014-03-04T14:20:14Z",
      "profilePhotoSmall": "http://assets-polarb-com.a.ssl.fastly.net/assets/user_default-345995fd38b8bf93e962b909e1c03c9b.png"
    }
  ]
}

Example
http://polarb.com/api/v4/polls/98779

Vote on a poll

Vote on a poll for a user. Note: voting multiple times on a poll for the same user will not create an additional vote: it will either switch the vote choice (if the choice has changed) or result in a no-op (if the choice remained the same).

POST /polls/:poll_id/votes
Param Type Required Description
poll_id number required The ID of the poll to vote on.
option number required The choice the user is voting on: either 1 (first choice) or 2 (second choice).
auth_token string optional Then Polar authentication token for the user voting, if the user has a Polar account. As returned by authToken in the authentication endpoint.
anonymous_user_id string optional Then identification of the user voting, if the user does not have a Polar account. See authentication for users without a Polar account to get this value.

Note: one of either auth_token or anonymous_user_id is required.

Returns:

{ 
  "success": true
}

Remove a vote on a poll

Remove a vote on a poll for a user if it exists.

DELETE /polls/:poll_id/votes/remove
Param Type Required Description
poll_id number required The ID of the poll to vote on.
auth_token string optional Then Polar authentication token for the user voting, if the user has a Polar account. As returned by authToken in the authentication endpoint.
anonymous_user_id string optional Then identification of the user voting, if the user does not have a Polar account. See authentication for users without a Polar account to get this value.

Note: one of either auth_token or anonymous_user_id is required.

Returns:

{ 
  "success": true
}

Create a poll

Creating a poll requires three steps:

  1. Post your poll to Polar.
  2. Take the returned S3 credentials and upload your poll image to S3.
  3. Notify Polar that the images have finished uploading.

Note about images: even though some Polar polls appear to have two images, it is really one image of the two composited side-by-side. At this time, the client is responsible for doing this -- so yours will have to, as well.

Post your poll to Polar

POST /polls
Param Type Required Description
caption string required The question to ask in the poll, e.g. "Which phone do you prefer?"
choice1 string required The text for the first choice, e.g. "iPhone for sure!"
choice2 string required The question to ask in the poll, e.g. "Android all the way"
auth_token string required Then Polar authentication token for the user creating the poll. As returned by authToken in the authentication endpoint.

Returns:

{
  "pollID": 815,
  "url": "http://localhost:3000/815-test-pol",
  "shortUrl": "http://localhost:3000/815",
  "caption": "Test Pol?",
  "pollType": "single-photo",
  "created": "2014-01-13T15:53:59Z",
  "public": false,
  "private": false,
  "creator": {
    "userID": 1,
    "name": "Jeffrey",
    "username": "jcole",
    "profilePhotoSmall": "http://polar-development-avatars-jeff.s3.amazonaws.com/000/000/001/1-small_retina-dc41e6a5a7d95012.jpg"
  },
  "choices": [{
    "name": "Yes",
    "sortOrder": 1,
    "voteCount": 0,
    "isWinning": false
  }, {
    "name": "No",
    "sortOrder": 2,
    "voteCount": 0,
    "isWinning": false
  }],
  "images": [
    // these don't exist until step 3!
  ],
  "voteCount": 0,
  "favoriteCount": 0,
  "commentCount": 0,
  "comments": [

  ],
  "firstChoiceName": "Yes",
  "secondChoiceName": "No",
  "firstChoiceVoteCount": 0,
  "secondChoiceVoteCount": 0,
  "firstChoicePercentage": 0,
  "secondChoicePercentage": 0,
  "firstWinning": false,
  "secondWinning": false,
  "image": null,
  "imageID": 797,
  "uploadData": { // used for s3 upload
    "postUrl": "https://polar-development-upload-jeff.s3.amazonaws.com",
    "formData": {
      "AWSAccessKeyId": "AKIAJNT4KV2W2N6XPSFA",
      "policy": "eyJleHBpcmF0aW9uIjoiMjAxNC0wMS0xNFQwMTo1NDowMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCw0MDk2MDAwXSx7IkNvbnRlbnQtVHlwZSI6ImltYWdlL2pwZWcifSx7ImtleSI6IjAwMC8wMDAvODE1LzgxNS0xLW9yaWdpbmFsLTZjNDJkYTUwZTg1YWI0MWMuanBlZyJ9LHsiYnVja2V0IjoicG9sYXItZGV2ZWxvcG1lbnQtdXBsb2FkLWplZmYifSx7ImFjbCI6InByaXZhdGUifV19",
      "signature": "z7Wts+wj+df68RvWWziqfYn7OxI=",
      "key": "000/000/815/815-1-original-6c42da50e85ab41c.jpeg",
      "acl": "private",
      "Content-Type": "image/jpeg"
    }
  }
}

Upload your poll images to S3

The response from creating your poll in last step will return JSON that has your S3 upload credentials in the uploadData attribute, e.g.:

"uploadData": {
  "postUrl": "https://polar-development-upload-jeff.s3.amazonaws.com",
  "formData": {
    "AWSAccessKeyId": "AKIAJNT4KV2W2N6XPSFA",
    "policy": "eyJleHBpcmF0aW9uIjoiMjAxNC0wMS0xNFQwMTo1NDowMFoiLCJjb25kaXRpb25zIjpbWyJjb250ZW50LWxlbmd0aC1yYW5nZSIsMCw0MDk2MDAwXSx7IkNvbnRlbnQtVHlwZSI6ImltYWdlL2pwZWcifSx7ImtleSI6IjAwMC8wMDAvODE1LzgxNS0xLW9yaWdpbmFsLTZjNDJkYTUwZTg1YWI0MWMuanBlZyJ9LHsiYnVja2V0IjoicG9sYXItZGV2ZWxvcG1lbnQtdXBsb2FkLWplZmYifSx7ImFjbCI6InByaXZhdGUifV19",
    "signature": "z7Wts+wj+df68RvWWziqfYn7OxI=",
    "key": "000/000/815/815-1-original-6c42da50e85ab41c.jpeg",
    "acl": "private",
    "Content-Type": "image/jpeg"
  }
}

You can use this information to post the image to the S3 postUrl with the provided credentials. Here is an example of how that would be done in JS with jQuery:

var fd = new FormData();
fd.append('AWSAccessKeyId', formData.AWSAccessKeyId);
fd.append('policy', formData.policy);
fd.append('signature', formData.signature);
fd.append('key', formData.key);
fd.append('acl', formData.acl);
fd.append('Content-Type', "image/jpeg");
fd.append('file', myImageFile, 'poll-image.jpeg');

$.ajax({
  url: url,
  type: "POST",
  data: fd,
  processData: false,  // tell jQuery not to process the data
  contentType: false   // tell jQuery not to set contentType
})
.done(function(data) {
  // success!!
})
.fail(function( jqXHR, textStatus, errorThrown ) {
  // error
});

Notify Polar that the images have finished uploading

This lets Polar know that the poll is ready to be seen and thumbnail versions of the poll image can be created. Call this endpoint after you have uploaded your images to S3.

POST /polls/:poll_id/image_uploaded
Param Type Required Description
poll_id number required The ID of the poll that we are creating. Returned in the response from the first step.
image_id number required The ID of the image that was uploaded. Returned in the response from the first step. (Note: the current version of Polar only uses one image per poll, so future verisons of the API can drop the requirement for this parameter.)
auth_token string required Then Polar authentication token for the user creating the poll. As returned by authToken in the authentication endpoint.
first_image_full_url string optional The URL for the the image for the first choice (if applicable).
first_image_context_url string optional The URL for the web site where the image for the first choice can be found (if applicable).
first_public_domain boolean optional Indicates whether the image for the first choice is public domain
second_image_full_url string optional The URL for the the image for the second choice (if applicable).
second_image_context_url string optional The URL for the web site where the image for the second choice can be found (if applicable).
second_public_domain boolean optional Indicates whether the image for the second choice is public domain

Returns:

{ 
  "success": true
}

Delete a poll

Delete a poll.

DELETE /polls/:poll_id
Param Type Required Description
poll_id number required The ID of the poll to delete.
auth_token string optional Then Polar authentication token for the user voting, if the user has a Polar account. As returned by authToken in the authentication endpoint.

Returns:

{ 
  "success": true
}

Get publisher embed results

Get the voting and viewing results for all polls/poll sets a publisher has embedded in their website or app.

Authentication is not required for this endpoint.

GET /publishers/:publisher_name/stats
Param Type Required Description
publisher_name string required The name of the publisher. This value can be found in the returned JSON from the /users/me endpoint if the viewing user belongs to a publisher. 
{
{
  "total": {
    "publisher_id": 38,
    "publisher_name": "HoustonChronicle",
    "publisher_display_name": "Houston Chronicle",
    "embeds_count": 61,
    "embed_views": 27613250,
    "embed_viewers": 6187996,
    "embed_votes": 162103,
    "embed_voters": 78498,
    "embed_time_voting": 1157391
  },
  "embeds": [
    {
      "publisher_id": 38,
      "publisher_name": "HoustonChronicle",
      "publisher_display_name": "Houston Chronicle",
      "embed_name": "Worst Dressed at the Oscars",
      "poll_id": null,
      "poll_set_id": 1859,
      "tag_id": null,
      "views": 2926,
      "viewers": 1457,
      "votes": 25,
      "voters": 7,
      "percent_voters": 0.004804392587508579,
      "votes_per_voter": 3.5714285714285716,
      "seconds_per_voter": 16.428571428571427,
      "time_voting": 115,
      "first_vote_date": "2014-03-01T14:45:07Z",
      "last_vote_date": "2014-03-02T17:00:19Z"
    },
    {
      "publisher_id": 38,
      "publisher_name": "HoustonChronicle",
      "publisher_display_name": "Houston Chronicle",
      "embed_name": "The HOV lanes should always require three or more riders.",
      "poll_id": 158886,
      "poll_set_id": null,
      "tag_id": null,
      "views": 11381,
      "viewers": 10032,
      "votes": 868,
      "voters": 868,
      "percent_voters": 0.08652312599681021,
      "votes_per_voter": 1.0,
      "seconds_per_voter": 6.0,
      "time_voting": 5208,
      "first_vote_date": "2014-02-13T21:29:33Z",
      "last_vote_date": "2014-02-24T15:20:40Z"
    }
  ]
}

Example
http://polarb.com/api/v4/publishers/houstonchronicle/stats