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:
- PREREQUISITE: include jQuery library
- Include the rankstr widget Javascript library
- Initiate rankstr widget when document is ready
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.news | OK | Discovered 143 new news articles in the past hour |
| articles.bad_urls | OK | Have 0 urls without proper prefix |
| engines.de | OK | Last DE cycle: 32 seconds ago |
| engines.se-php | OK | Last SE cycle: 17 seconds ago |
| engines.rc | OK | Last RC cycle: 14 seconds ago |
| engines.restart | OK | 0 engines restarts in the past hour |
| engines.br | OK | BR engine is working for 0.0000 hours |
| social.general | OK | Ran 338 article social networks queries in past 5min |
| social.success | OK | Ran 91 article social networks queries in past 5min with social counters change |
| social.pending | OK | 0 items waiting for social networks queries |
| social.twitterapi | OK | Ran 23 twitter lookup queries in the last 15 minutes |
| social.twittersuccess | OK | Got successfull twitter data for 1648 tweets in the last 15 minutes |
| social.twitter_pending | OK | 134 tweets pending for query |
| social.facebookapi | OK | Ran 16 facebok api queries in the last 10 minutes |
| social.facebookqueries | OK | Queried facebook for 143 items in the last hour |
| social.facebook_success_rate | OK | Success rate for facebook queries is 100.00% in the last hour |
| social.facebook_errors_last | OK | FB last query error code is 0 |
| social.facebook_errors | OK | FB last 10 min errors |
| database.article_counts | OK | 6 days left in article_counts |
| www-en.rate | OK | Average rate for first item batch is 6.55 |
| www-he.rate | OK | Average rate for first item batch is 7.09 |
| www-ru.rate | OK | Average rate for first item batch is 7.64 |
| memcache.info | OK | Memcache is up and running. Free space 28MB |