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();

});
 });