Welcome to the rankstr API!

You can use our API to access rankstr API endpoints, which can get information on the most shared and viral items on the web.


All requests to the API is done via HTTP GET to

The API endpoint and parameters are provided in the HTTP GET response separated by semicolon (;)

HTTP Request Example


All API responses are in JSON format and include 2 fields:

code The error code as described below.
data The actual response data.


rankstr uses session keys to allow access to the API. All API endpoints expect the session key to be included in all requests to the server.

Getting a session key is done with the auth API, using the application KEY and secret as follows (apply for application API key and secret by email):

HTTP Request


HTTP Response

JSON {"code":200,"data":"SESSION-KEY"}

API Endpoints


This endpoint retrieves items based on their viral volume on social networks (shares and tweets).

HTTP Request


Query Parameters

Parameter Default Description
start 0 If set to 0, previously sent articles will not be sent again. This is useful for 'get more' use case.
If set to 1, the previous sent articles will be cleared.
count 10 Number of articles to get.
time_from 24 Filter articles that were discovered/published within a time window - beginning with time_from (hours).
time_to 0 Filter articles that were discovered/published within a time window - ending with time_to (hours).
lang en Language code. Currently supporting English (en) and Hebrew (he).
order rate The method to order the articles and get the top ones.
rate - will look for average shares per hour.
rank - will look for total shares.

HTTP Request Example


Response Fields

Field Description
id Internal item ID.
url Item's URL - a respective URL to the rankstr API request URL. This should be used when directing the user to the item.
canonical Item's canonical URL to the source site.
title Title.
siteName Source site name.
image Item's image URL - a respective URL to the rankstr API request URL.
rank Total number of shares/tweets.
rate Average number of shares/tweets per hour.
Published Published time of the item - UTC timestamp.

HTTP Response Example

{"code":200,"data":[{"id":"5870210","url":"\/article\/5870210","canonical":"http:\/\/\/miranda-lambert-cries-child-with-cancer\/","title":"Miranda Lambert breaks down when singing to 7-year-old fan with cancer","siteName":"FOX News","siteLogo":null,"published":"1410882350","siteURL":null,"urlHash":null,"image":"\/images\/articles\/300x300-f121438b0464872df34473cebf262d969300b2cb.jpg","siteCode":"FOX","facebookCounter":null,"twitterCounter":null,"rank":"25136","rate":"117.8895","categories":[],"tags":[],"author":null,"externalCode":null,"description":null,"rankings":[],"publishedText":"4 hours ago on FOX News","body":null,"images_json":null,"contentType":"NEWS","rankDisplayShort":"118"}]}


The rankstr API uses the following error codes:

Error Code Meaning
200-299 Success
901 Bad API request
500 General Error. Please contact support
902 Bad auth request - check your application key and secret
903 Unauthorized - Your API key is wrong or expired


rankstr also offer a simple to implemented Widget to put on any other web sites.

The widget is very simple to implement and require jquery, and some very simple javascript additions to the website, where the widget is located.

The changes required to implemnt the rankstr widget:

See example here

Branded widget can also be provided. Please contact us to get more details

Confirm jQuery prerequisite

rankstr widget require jQuery version 1.4.0 or later

Include in HEAD

<script src=''></script>

Note: if your website already using jQuery, you do not need to include it again

Include widget Javascript Library

Simply include the rankstr widget Javascript library into your site code, anywhere in the BODY section

Include in BODY anywhere

<script type=text/javascript src=''></script>

Initiate rankstr Widget

Simply call rankstr_init in your $(document).ready code


$(document).ready(function() {


Parameter Default Description
dom_id rankstrwidget The DOM location where the widget is expected.
count 10 Number of articles to show.
height as count Number of articles visible (controlling the height of the widget).
lang en Language code. Currently supporting English (en) and Hebrew (he).
images 1 Whether to show article thumbnail. 0=no. 1=yes.
theme light Color theme. Currently available options: light, dark.


$(document).ready(function() {
    rankstr_init( {
        lang: 'en',
        count: 5,

iframe Widget

iframe widget is also available. Simply add an iframe with the wanted dimensions pointing to

The iframe link supports similar parameters as the javascript one, with similar format as the rest of the API


<iframe src=';images=1;theme=dark;lang=en' width='400' height='600' frameborder='no' scrolling='no' style='overflow: hidden;padding-bottom:1px;'></iframe>

Service Status - OK

The rankstr service components status:

Component Status Description
articles.newsOKDiscovered 143 new news articles in the past hour
articles.bad_urlsOKHave 0 urls without proper prefix
engines.deOKLast DE cycle: 32 seconds ago SE cycle: 17 seconds ago
engines.rcOKLast RC cycle: 14 seconds ago
engines.restartOK0 engines restarts in the past hour
engines.brOKBR engine is working for 0.0000 hours
social.generalOKRan 338 article social networks queries in past 5min
social.successOKRan 91 article social networks queries in past 5min with social counters change
social.pendingOK0 items waiting for social networks queries
social.twitterapiOKRan 23 twitter lookup queries in the last 15 minutes
social.twittersuccessOKGot successfull twitter data for 1648 tweets in the last 15 minutes
social.twitter_pendingOK134 tweets pending for query
social.facebookapiOKRan 16 facebok api queries in the last 10 minutes
social.facebookqueriesOKQueried facebook for 143 items in the last hour
social.facebook_success_rateOKSuccess rate for facebook queries is 100.00% in the last hour
social.facebook_errors_lastOKFB last query error code is 0
social.facebook_errorsOKFB last 10 min errors
database.article_countsOK6 days left in article_counts
www-en.rateOKAverage rate for first item batch is 6.55
www-he.rateOKAverage rate for first item batch is 7.09
www-ru.rateOKAverage rate for first item batch is 7.64
memcache.infoOKMemcache is up and running. Free space 28MB