by    in API Documentation, Developers

Ranker Widget oEmbed Documentation


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 //
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



Response Parameters

provider_name Name of the embedded content provider, Ranker.
provider_url URL of the embedded content provider,
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 : “”,
author_name : “Ranky”,
author_url : “”
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=" quotes/desertrat89">The Funniest Seinfeld Quotes</a><script
id="rnkrw-loader" type="text/javascript" async src="//"></script>”
by    in About Ranker, Opinion Graph, Pop Culture, Rankings

Ranker’s Rankings API Now in Beta

Increasingly, people are looking for specific answers to questions as opposed to webpages that happen to match the text they type into a search engine.  For example, if you search for the capital of France or the birthdate of Leonardo Da Vinci, you get a specific answer.  However, the questions that people ask are increasingly about opinions, not facts, as people are understandably more interested in what the best movie of 2013 was, as opposed to who the producer for Star Trek: Into Darkness was.

Enter Ranker’s Rankings API, which is currently now in beta, as we’d love the input of potential users’ of our API to help improve it.  Our API returns aggregated opinions about specific movies, people, tv shows, places, etc.  As an input, we can take a Wikipedia, Freebase, or Ranker ID.  For example, below is a request for information about Tom Cruise, using his Ranker ID from his Ranker page (contact us if you want to use other IDs to access).

In the response to this request, you’ll get a set of Rankings for the requested object, including a set of list names (e.g. “listName”:”The Greatest 80s Teen Stars”), list urls (e.g. “listUrl”:”” – note that the domain,, is implied), item names (e.g. “itemName”:”Tom Cruise”) position of the item on this list (e.g. “position”:21), number of items on the list (e.g. “numItemsOnList”:70), the number of people who have voted on this list (e.g. “numVoters”:1149), the number of positive votes for this item (e.g. “numUpVotes”:245) vs. the number of negative votes (e.g. “numDownVotes”:169), and the Ranker list id (e.g. “listId”:584305).  Note that results are cached so they may not match the current page exactly.

Here is a snipped of the response for Tom Cruise.

[ { “itemName” : “Tom Cruise”,
“listId” : 346881,
“listName” : “The Greatest Film Actors & Actresses of All Time”,
“listUrl” : “”,
“numDownVotes” : 306,
“numItemsOnList” : 524,
“numUpVotes” : 285,
“numVoters” : 5305,
“position” : 85
{ “itemName” : “Tom Cruise”,
“listId” : 542455,
“listName” : “The Hottest Male Celebrities”,
“listUrl” : “”,
“numDownVotes” : 175,
“numItemsOnList” : 171,
“numUpVotes” : 86,
“numVoters” : 1937,
“position” : 63
{ “itemName” : “Tom Cruise”,
“listId” : 679173,
“listName” : “The Best Actors in Film History”,
“listUrl” : “”,
“numDownVotes” : 151,
“numItemsOnList” : 272,
“numUpVotes” : 124,
“numVoters” : 1507,
“position” : 102


What can you do with this API?  Consider this page about Tom Cruise from Google’s Knowledge Graph.  It tells you his children, his spouse(s), and his movies.  But our API will tell you that he is one of the hottest male celebrities, an annoying A-List actor, an action star, a short actor, and an 80s teen star.  His name comes up in discussions of great actors, but he tends to get more downvotes than upvotes on such lists, and even shows up on lists of “overrated” actors.

We can provide this information, not just about actors, but also about politicians, books, places, movies, tv shows, bands, athletes, colleges, brands, food, beer, and more.  We will tend to have more information about entertainment related categories, for now, but as the domains of our lists grow, so too will the breadth of opinion related information available from our API.

Our API is free and no registration is required, though we would request that you provide links and attributions to the Ranker lists that provide this data.  We likely will add some free registration at some point.  There are currently no formal rate limits, though there are obviously practical limits so please contact us if you plan to use the API heavily as we may need to make changes to accommodate such usage.  Please do let me know (ravi a t ranker) your experiences with our API and any suggestions for improvements as we are definitely looking to improve upon our beta offering.

– Ravi Iyer