API Docs

Version:  1.0

Getting Started with SharedCount

This page will help you get started with SharedCount. You'll be up and running in a jiffy!

Please see pricing page for detailed quota information and information on paid plans with extra API quota.

API Calls


You can retrieve SharedCount data from a JSON/JSONP API.

Your API Information


Your API Key

YOUR_APP_KEY


Your endpoint URL

https://YOUR_APP_PLAN.sharedcount.com/v1.0/

Values of queries may be cached for up to an hour for repeated URLs

Sample Response

{"StumbleUpon":1,"Pinterest":9,"LinkedIn":3744,"Facebook":{"total_count":
168,"comment_count":53,"reaction_count":14,"share_count":
101, "comment_plugin_count":0},"GooglePlusOne":189}

All the plans use a single URL endpoint, except dedicated users, which have their own custom domain.


Free, Plus, and Business Plan Users

https://api.sharedcount.com/v1.0/


Free, Plus, and Business Plan Users

https://api.sharedcount.com/v1.0/

Upgrading from the old endpoint


The endpoint URL has changed from /url to /v1.0/ (please note the trailing backslash).

Errors


When an error occurs, SharedCount returns JSON with a key "Error" with a message, and a "Type" with a classification. For JSONP calls, we'll always return a 200 code.

quota_exceeded (HTTP 401): Exceeded the API quota.

{"Error": "Free API quota exceeded. Quota will reset tomorrow. Visit
SharedCount to inquire about paid plans. http://sharedcount.com/quota",
"Type": "quota_exceeded"}

invalid_url (HTTP 400): The URL you passed to the API is invalid.

{"Error":"Not a valid URL.", "Type": "invalid_url"}

Upgrading from the old endpoint


The endpoint URL has changed from /url to /v1.0/ (please note the trailing backslash).

no_jquery_cachebusting (JSONP Only): You're using jQuery's default JSONP plugin, which cachebusts too aggressively and thus is barred from use. Use our jQuery plugin below instead.

{"Error": "Your Request uses jQuery\'s cachebusting function. Visit http://
sharedcount.com/jsonp to get access to a cache-friendly JavaScript plugin you can
use instead.", "Type":"no_jquery_cachebusting"}

Domain Whitelist

For users using SharedCount from the client-side, we offer the ability to whitelist specific domains that can be queried using your API key. For example, if your site is foo.com, and the only domains you query from SharedCount are on foo.com and sub.foo.com, then you can secureyour API key by only allowing these domains to utilize your API key. This is useful for sites that use SharedCount for reporting their own sites' data within the browser. You can toggle this feature from the User Center and add your domains.

Sample Code


Below is an example of how you would call SharedCount's API from JavaScript. If you're integrating SharedCount into a live website, this is the recommended usage. We do not recommend using SharedCount in a way that it is called from the backend every time a page loads, as this can lead to negative performance impact.

JQuery Plugin

jQuery.sharedCount = function(url, fn) {
    url = encodeURIComponent(url || location.href);
    var domain = "//YOUR_APP_PLAN.sharedcount.com/v1.0/"; /* SET DOMAIN */
    var apikey = "YOUR_APP_KEY" /*API KEY HERE*/
    var arg = {
      data: {
        url : url,
        apikey : apikey
      },
        url: domain,
        cache: true,
        dataType: "json"
    };
    if ('withCredentials' in new XMLHttpRequest) {
        arg.success = fn;
    }
    else {
        var cb = "sc_" + url.replace(/\W/g, '');
        window[cb] = fn;
        arg.jsonpCallback = cb;
        arg.dataType += "p";
    }
    return jQuery.ajax(arg);
};

This plugin utilizes CORS on CORS-compliant browsers.

JavaScript

jQuery(document).ready(function($){
    $.sharedCount(location.href, function(data){
        $("#facebook").text(data.Facebook.total_count);
        $("#linkedin").text(data.LinkedIn);
        $("#pinterest").text(data.Pinterest);
        $("#stumbles").text(data.StumbleUpon);
        $("#comments").text(data.Facebook.comment_count);
        $("#plusones").text(data.GooglePlusOne);
        $("#sharedcount").fadeIn();

});
 });

Bulk API

Upgrading from the old endpoint

Users on paid plans have access to a bulk querying endpoint, where you can POST a large batch of URLs all at once, and poll for the result once its ready. Responses will be in JSON. This endpoint will not be available in JSONP.

URLs are transmitted one per line in the POST body, with a trailing line-break after the final URL.

For example, you would query:

POST https://YOUR_APP_PLAN.sharedcount.com/bulk?apikey=YOUR_APP_KEY

Request Body:
http://www.google.com/
http://www.amazon.com/

Please see pricing page for detailed quota information and information on paid plans with extra API quota.

Batch size


The maximum number of URLs you can query in a batch depends on your plan:

  • Plus: 500
  • Business: 1,000
  • Dedicated: 10,000

Successfully completed API queries done via batching will count against your daily API quota. Requests exceeding your API quota will be rejected. Under the covers, the bulk endpoint acts as a layer on top of the existing API; one which handles the queueing and processing of a large number of queries for the purposes of reducing transit overhead.

When you make your POST request, you'll receive a response giving you a bulk_id, and also the number of URLs that were accepted and queued for querying. Invalid URLs will be silently ignored.

The bulk_id can be used to fetch the completed response:

GET YOUR_APP_PLAN.sharedcount.com/bulk?apikey=YOUR_APP_KEY&bulk_id=:bulk_id

When you make this request, you'll get back an object indicating the number of URLs completed thus far. If all of the queued URLs are complete, the full data will be returned. When this complete state is reached and your full data is returned, further requests for that bulk_id may no longer return data.

If you want to receive your data incrementally while it's being churned, you can add a &force=1 parameter to the URL, and each request will contain the completed URL data up until that point:

GET YOUR_APP_PLAN.sharedcount.com/bulk?apikey=YOUR_APP_KEY&bulk_id=:bulk_id&force=1

This can be useful if for some reason one or two URLs remain outstanding for an extended period of time.

GET/v1.0/

Return share counts for a URL.


Definition

https://YOUR_APP_PLAN.sharedcount.com/v1.0/


Parameters

Query Params
url:
required
string
The URL you're querying.

apikey:
required
stringYOUR_APP_KEY
Your API key.

callback:	string
For JSONP, the callback function name.

custom_ttl:	integer
Number of seconds you'd like the results to be cached. (Available only on the Dedicated Plan).


Result Format

Success
Failure
{"StumbleUpon":1,"Pinterest":9,"LinkedIn":3744,"Facebook":{"total_count":168,"comment_count":53,
"reaction_count":14,"share_count":101,"comment_plugin_count":0},"GooglePlusOne":189}
{"Error": "Error message here", "Type": "error_type"}

Documentation

This endpoint returns null (instead of 0) when a service fails to report a number. It removes values from the responses that SharedCount no longer queries, like Buzz, Reddit and Delicious.

Generally speaking, it does not guarantee the presence of particular network's data in every response, which may be removed without notice. (For example, Buzz is still shown in normal API responses, despite not existing for several years).

This means that usage of this API requires ensuring that the particular attribute you're accessing is available on the object, and handling null values for when it is available.

JavaScript

jQuery.sharedCount = function(url, fn) {
  url = encodeURIComponent(url || location.href);
  var domain = "//YOUR_APP_PLAN.sharedcount.com/v1.0/"; /* SET DOMAIN */
  var apikey = "YOUR_APP_KEY" /*API KEY HERE*/
  var arg = {
    data: {
      url: url,
      apikey: apikey
    },
    url: domain + "/url",
    cache: true,
    dataType: "json"
  };
  if ('withCredentials' in new XMLHttpRequest) {
    arg.success = fn;
  } else {
    var cb = "sc_" + url.replace(/\W/g, '');
    window[cb] = fn;
    arg.jsonpCallback = cb;
    arg.dataType += "p";
  }
  return jQuery.ajax(arg);
};
$.sharedCount(location.href, function(data){
     console.log(data.Twitter);
       console.log(data.Facebook.like_count);
});

Custom Cache Times

Users on Dedicated Plans may specify a custom cache time for a given URL by passingcustom_ttlas a parameter with a non-negative integer representing the number of seconds you'd like the value to be cached. The default is 1200, which corresponds to 20 minutes.

To disable any kind of caching, setcustom_ttlto0.

By settingcustom_ttl, you have the effect of altering theExpiresandCache-Controlheader, as well as configuring how long the application itself will cache the data for that URL.

Setting thecustom_ttlparameter only affects subsequent requests for that given URL. If previous requests for that URL set a differentcustom_ttlvalue, those original values may continue to be respected.

POST/v1.0/bulk

Post a large number of URLs all at once to calculate bulk social counts. (This page is incomplete.)


Definition

https://YOUR_APP_PLAN.sharedcount.com/v1.0/bulk


Parameters

Body Params
apikey:	stringYOUR_APP_KEY
urls:	stringone URL per line

Result Format

Success
{"count":921,"bulk_id":"4a7d9ca68177713593c713cc584a7edf9ee9017c"}

Documentation

URLs are transmitted one per line in the POST body, with a trailing line-break after the final URL.

Shell

POST YOUR_APP_PLAN.sharedcount.com/bulk?apikey=YOUR_APP_KEY

Request Body:
http://www.google.com/
http://www.amazon.com/

Successfully completed API queries done via batching will count against your daily API quota. Requests exceeding your API quota will be rejected. Under the covers, the bulk endpoint acts as a layer on top of the existing API; one which handles the queueing and processing of a large number of queries for the purposes of reducing transit overhead.

When you make your POST request, you'll receive a response giving you a bulk_id, and also the number of URLs that were accepted and queued for querying. Invalid URLs will be silently ignored.

Use theGET /bulkcall to retrieve your data from the endpoint after posting.

GET/v1.0/bulk

BETA: Get a large number of recently-posted URLs all at once to calculate bulk social counts.


Definition

https://YOUR_APP_PLAN.sharedcount.com/v1.0/bulk


Parameters

Query Params
bulk_id:
required
string
The bulk_id provided by the /bulk POST call.

apikey:
required
stringYOUR_APP_KEY
force:	string
Set this parameter to 1 force results to return even if not all URLs have completed processing.

Result Format

Success
Incomplete
Text
{
    "data": {
        "http://google.com/": {
            "StumbleUpon": 11000,
            "Pinterest": 1436815,
            "LinkedIn": 1920,
            "Facebook": {
              "total_count":4629449,
              "comment_count":225136,
              "reaction_count":1258082,
              "share_count":3145819,
              "comment_plugin_count":412
            },
            "GooglePlusOne": 12219845
        },
        "http://stackoverflow.com/": {
            "...snip...": "98 URLs not shown for brevity..(snip).."
        }

    },
    "_meta": {
        "urls_completed": 100,
        "bulk_id": "a4f8f0fd436995987dbef98bbff9accc61282c63",
        "completed": true,
        "urls_queued": 100
}
{"data": [],
  "_meta": {
    "urls_completed": 90,
    "bulk_id": "a4f8f0fd436995987dbef98bbff9accc61282c63",
    "completed": false,
    "urls_queued": 100
    }
  }
No Content

Documentation

No Content

GET/v1.0/quota

Return information about your quota allocation for the day.


Definition

https://YOUR_APP_PLAN.sharedcount.com/v1.0/quota


Parameters

Query Params
apikey:
required
stringYOUR_APP_KEY

Result Format

Success
{"quota_used_today":132820,"plan":"business","quota_remaining_today":1867180,
"quota_allocated_today":2000000}

Documentation

...

GET/v1.0/usage

Return historical quota usage information.


Definition

https://YOUR_APP_PLAN.sharedcount.com/v1.0/bulk


Parameters

Query Params
apikey:
required
stringYOUR_APP_KEY

Result Format

Success
{"2014-02-13": {"date": "2014-02-13", "queries": 320, "quota": 10000}, "2014-02-14":
{"date": "2014-02-14", "queries": 4403, "quota": 10000}, "2014-02-15":
{"date": "2014-02-15", "queries": 202, "quota": 10000}, "2014-02-16":
{"date": "2014-02-16", "queries": 105, "quota": 10000}}

Documentation

...

GET/v1.0/domain_whitelist

Return a list of domains added to your domain whitelist, and whether the domain whitelist is currently being enforced.


Definition

https://YOUR_APP_PLAN.sharedcount.com/v1.0/domain_whitelist


Parameters

Query Params
apikey:
required
stringYOUR_APP_KEY

Result Format

Success
Failure
For users with the whitelist enabled
{"domains": [], "whitelist_domains_enabled": false}
Unauthorized
{"domains": ["yourdomain.com"], "whitelist_domains_enabled": true}

Documentation

...

GET/v1.0/status

Check to see if the SharedCount API is currently up.


Definition

https://YOUR_APP_PLAN.sharedcount.com/v1.0/status


Result Format

Success
Failure
{"status":"up"}
No Content

Documentation

...