by    in API Documentation, Developers

Ranker Widget oEmbed Documentation

Introduction

oEmbed is a format for allowing an embedded representation of a URL on third party sites. The simple API allows a website to display embedded content (such as photos or videos) when a user posts a link to that resource, without having to parse the resource directly.

To find out more information please review the oEmbed specification.

 

oEmbed endpoint URL

You can use the API endpoint to request the embed code for a list from its ID. The response will return in JSON format.

Request Type HTTP(S) GET
Authorization None
URL //widget.ranker.com/oembed/ID
Response Format JSON

 

List ID Discovery

Ranker supports discovery of List IDs. Each list page that supports embedding will have one or more links to an embed (or widget) page. These links can be found under ’embed’ or ‘widget’ links, or via ‘</>’ icons. Once navigated to, these widget pages will both display the List ID in the pages URL and beneath the Embed Code area.

 

Endpoint Parameters

All parameters are sent via query string parameters and must be urlencoded.

format List format type (string1). Defaults to grid.
rows Sizes widget to display this many rows (number2). Defaults to 20.
headername Show the list name (boolean). Defaults to True.
headerimage Show the list image (boolean). Defaults to False.
headerusername Show the list author name (boolean). Defaults to False.
headercriteria Show the list criteria (boolean). Defaults to False.
headerbgcolor Specify the widget header background color (hex3). Defaults to ffffff.
headerfontface Specify the widget header font-face (string4). Defaults to Arial.
headerfontcolor Specify the widget header foreground color (hex3). Defaults to 000000.
listfontface Specify the widget body font-face (string4). Defaults to Arial.
listfontcolor Specify the widget body foreground color (hex3). Defaults to 000000.
listdisplaydescriptions Show list item descriptions (boolean). Defaults to True.
listslidebgcolor Specify the slideshow format background color (hex3). Defaults to ffffff.
listdisplaythumbnails Show slideshow thumbnail carousel (boolean). Defaults to False.
listflatbuttons Show vote buttons in a flat style using your listfontcolor. Defaults to False.
footerbgcolor Specify the widget footer background color (hex3). Defaults to 1e3e66.
footerfontcolor Specify the widget footer foreground color (hex3). Defaults to ffffff.
footersharing Show the widget footer sharing options5 (boolean). Defaults to True.

1 Possible format types are ‘grid’ for poll lists and ‘slideshow’ for photo lists.
2 Rows setting only applies to grid format widgets.
3 Hex values should NOT include the #.
4 Possible font-face values are ‘arial’, ‘helevtica’, ‘verdana’, ‘geneva’, ‘georgia’ or ‘times’ only.
5 Widget sharing options share YOUR page, not the original embedded list.

 

Example endpoint URL

//widget.ranker.com/oembed/517518?format=grid&rows=10&headername=true&headerimage=true

 

Response Parameters

provider_name Name of the embedded content provider, Ranker.
provider_url URL of the embedded content provider, http://www.ranker.com.
author_name List author name.
author_url List author URL.
cache_age How long this embedded content will be cached for.
version Version of this oEmbed response, 1.0.
type Type of embedded content, Rich.
title Name of embedded list.
html Embed code content. This is what you will use on your pages.

 

Example Response

{
provider_name : “Ranker”,
provider_url : “http://www.ranker.com”,
author_name : “Ranky”,
author_url : “http://www.ranker.com/profile-of/ranky”
cache_age : “100”,
version : “1.0”,
type : “rich”,
title : “The Funniest Seinfeld Quotes”,
html : “<a class="rnkrw-widget" data-rnkrw-id="517518"
data-rnkrw-format="grid" data-rnkrw-rows="999"
href="http://www.ranker.com/list/the-funniest-seinfeld- quotes/desertrat89">The Funniest Seinfeld Quotes</a><script
id="rnkrw-loader" type="text/javascript" async src="//widget.ranker.com/static/rnkrw2.js"></script>”
}
by    in Opinion Graph, Pop Culture, Rankings

Examining Regional Voting Differences with Ranker’s Polling Widget

Ranker has a new program where we offer a polling widget to partner sites who want the engagement of a poll in list format (as opposed to the standard radio button poll).  Currently, sites that use our poll (e.g. TheNextWeb or CBC) are seeing 20-50% of visitors engaging in the poll and an increase in returning visitors who want to keep track of results.  We also give partners prominent placement on Ranker.com (details of that here), but a benefit that is less obvious is the potential insights from one’s users that one can gain from the data behind a poll.  To illustrate what is possible, I’m going to use data from one of our regular widget users, Phish.net, who posted this poll on Phish’s best summer concert jams.

One piece of data that Ranker can give partners is a regional breakdown of voters.  Unsuprisingly, there were strong regional differences in voting behavior with voters from the northeast often choosing a jam from their New Jersey show, voters from the west coast often choosing a jam from their Hollywood Bowl show, voters from the south often choosing a jam from their Maryland show, voters from the midwest often choosing a jam from their Chicago show, and voters from the mountain region often choosing a jam from their show at The Gorge.  However, the interesting thing to me was that the leading jam in every region was Tweezer – Lake Tahoe from July 31st.  As someone who believes that better crowdsourced answers are produced by aggregating across bias and who has only been to 1 Phish concert, I’m definitely going to have to check out this jam.  Perhaps the answer is obvious to more experienced Phish fans, but the results of the poll are certainly instructive to the more casual music fan who wants a taste of Phish.

Below are the results of the poll in graphical format.  Notice how the shows cluster based on venue and geography except for Tweezer – Lake Tahoe which is directly in the center of the graph.

If you’re interested in running a widget poll on your site, the benefits are more clearly spelled out here and you can email us at “widget at ranker.com”.  We’d love to provide similar region based insights for your polls as well.

– Ravi Iyer

 

by    in New Features

Introducing the Ranker Partnership Program!

Today we are unveiling the new Ranker Partnership Program! Ranker is partnering with select publishers and individual experts who regularly create high-quality lists on our site. We will feature our Partner Lists in a new section of our homepage and throughout our category pages.

Partner Lists will also have added space for branding, a link back to their own site and an “Official Partner” verification checkmark next to their name.

While believing in the wisdom of crowds is kind of our thing here at Ranker, we will admit that sometimes some people do know more about some topics than others. Hey, I won’t ask you about your favorite Kombucha flavors if you don’t ask me about my favorite GPS fitness-tracking apps. Capiche?

But you know who I would ask about GPS apps? The good people over at The Next Web, who are experts on Internet technology. So when a noted authority on a certain topic (that has an active online community who can make our rankings more accurate) makes a list about a topic that they know a lot about, we thought it’d be nice to call that out.

For this reason, we are unveiling some nifty new features that distinguish expert Partner Lists from user-generated lists. Keep an eye out around the site for these new lists. You will recognize them by their “Official Partner” verified checkmark.

Trusted publishers and individual experts have been making lists on Ranker.com for awhile now and we added these new features to make their lists pop and to highlight their expertise.

Many of our partners use Ranker’s killer interface to create a poll on their topic of choice to host on their very own site. Embedding a list is super easy–just look for the “embed list” button in the footer of any new or pre-existing Ranker list.

If you’d like to be considered for our Partnership Program, send us a note. If you want more details, visit this short guide first. In general, our partners are publications or experts who have their own active online communities and some expertise in a certain subject. Most of our partners produce at least one piece of high quality content a month. And remember, since these lists will be featured on our homepage we tend to prefer partners who produce content that appeals to our broad, diverse online community.

By the way, you don’t have to be a partner to use our widget or enjoy Ranker.com. For most of our users, the new Partnership Program won’t change a thing!