NAV
Examples

Introduction

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.

Protocol

All requests to the API is done via HTTP GET to http://api.rankstr.com/v1/

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

HTTP Request Example

GET http://api.rankstr.com/v1/api={ENDPOINT};{PARAM1}={VALUE1};...


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

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

Authentication

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

GET http://api.rankstr.com/v1/api=auth;appkey={APPKEY};secret={SECRET}

HTTP Response

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

API Endpoints

getitems

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

HTTP Request

GET http://api.rankstr.com/v1/api=getitems;session_key={SESSION-KEY}

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

GET http://api.rankstr.com/v1/api=getitems;count=1;session_key={SESSION-KEY}

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:\/\/tasteofcountry.com\/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"}]}

Errors

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

Widget

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='https://code.jquery.com/jquery-1.4.min.js'></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='http://api.rankstr.com/v1/widget/widget.min.js'></script>

Initiate rankstr Widget

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

example

$(document).ready(function() {
    rankstr_init();
});

Parameters

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.

example

$(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 http://api.rankstr.com/v1/widget/iframe

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

example

<iframe src='http://api.rankstr.com/v1/widget/iframe/count=20;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 294 new news articles in the past hour
articles.bad_urlsOKHave 0 urls without proper prefix
engines.deOKLast DE cycle: 106 seconds ago
engines.se-phpOKLast SE cycle: 65 seconds ago
engines.rcOKLast RC cycle: 10 seconds ago
engines.restartOK0 engines restarts in the past hour
engines.brOKBR engine is working for 0.0000 hours
social.generalOKRan 793 article social networks queries in past 5min
social.successOKRan 394 article social networks queries in past 5min with social counters change
social.pendingOK140 items waiting for social networks queries
social.twitterapiOKRan 42 twitter lookup queries in the last 15 minutes
social.twittersuccessOKGot successfull twitter data for 3331 tweets in the last 15 minutes
social.twitter_pendingOK148 tweets pending for query
social.facebookapiOKRan 43 facebok api queries in the last 10 minutes
social.facebookqueriesOKQueried facebook for 3213 items in the last hour
social.facebook_success_rateOKSuccess rate for facebook queries is 97.23% in the last hour
social.facebook_errors_lastOKFB last query error code is 0
social.facebook_errorsOKFB last 10 min errors
social.fb_user_postOK5 users posts in FB in last 10 hours
database.article_countsOK6 days left in article_counts
www-en.rateOKAverage rate for first item batch is 4.27
www-he.rateOKAverage rate for first item batch is 5.82
www-ru.rateOKAverage rate for first item batch is 6.91
www-ar.rateOKAverage rate for first item batch is 7.45
www-tr.rateOKAverage rate for first item batch is 4.64
memcache.infoOKMemcache is up and running. Free space 29MB