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