{"__v":0,"_id":"591021f8d4cd662d00c82fa1","api":{"auth":"never","params":[],"results":{"codes":[]},"settings":"","url":""},"body":"Please see <a href='http://www.sharedcount.com/pricing.php' target='_blank'>pricing page</a> for detailed quota information and information on paid plans with extra API quota.\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"API Calls\"\n}\n[/block]\nYou can retrieve SharedCount data from a JSON/JSONP API. \n\n\n[block:callout]\n{\n  \"type\": \"success\",\n  \"body\": \"Your API Key\\n**[[app:key]]**\\n\\nYour endpoint URL\\n**https://[[app:plan]].sharedcount.com/v1.0/**\",\n  \"title\": \"Your API Information\"\n}\n[/block]\nValues of queries may be cached for up to an hour for repeated URLs.\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"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}\",\n      \"language\": \"json\",\n      \"name\": \"Sample Response\"\n    }\n  ]\n}\n[/block]\n------------------\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"\",\n  \"body\": \"All the plans use a single URL endpoint, except dedicated users, which have their own custom domain.\\n\\n**Free, Plus, and Business Plan Users**\\n*https://api.sharedcount.com/v1.0/*\\n\\n**Dedicated Users**\\n*https://custom-domain.sharedcount.com/v1.0/*\"\n}\n[/block]\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Upgrading from the old endpoint\",\n  \"body\": \"The endpoint URL has changed from /url to /v1.0/ (please note the trailing backslash).\"\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Errors\"\n}\n[/block]\nWhen 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"Error\\\": \\\"Free API quota exceeded. Quota will reset tomorrow. Visit SharedCount to inquire about paid plans. http://sharedcount.com/quota\\\", \\\"Type\\\": \\\"quota_exceeded\\\"}\\n\",\n      \"language\": \"json\",\n      \"name\": \"quota_exceeded (HTTP 401): Exceeded the API quota.\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"Error\\\":\\\"Not a valid URL.\\\", \\\"Type\\\": \\\"invalid_url\\\"}\\n\",\n      \"language\": \"text\",\n      \"name\": \"invalid_url (HTTP 400): The URL you passed to the API is invalid.\\n\"\n    }\n  ]\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"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\\\"}\\n\",\n      \"language\": \"json\",\n      \"name\": \"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.\\n\"\n    }\n  ]\n}\n[/block]\n##Domain Whitelist\n\nFor 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 secure your 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. \n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"API Quota\"\n}\n[/block]\nEach API key is allocated a daily quota for their number of API calls. API keys sending more than their allocated quota in a day will see their queries rejected with an HTTP Status Code of 401. Paid users can, by request, enable quota overages. \n\nYou can monitor your API usage by inspecting the response headers `X-Quota-Remaining`. Note that cached queries may return stale quota results.\n\nUsers can check their *current* API quota by querying the end-point\n<a target='_blank' href='https://[[app:plan]].sharedcount.com/quota?apikey=[[app:key]]'>`/quota?apikey=[[app:key]]`</a>\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Sample Code\"\n}\n[/block]\nBelow 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.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"jQuery.sharedCount = function(url, fn) {\\n    url = encodeURIComponent(url || location.href);\\n    var domain = \\\"//[[app:plan]].sharedcount.com/v1.0/\\\"; /* SET DOMAIN */\\n    var apikey = \\\"[[app:key]]\\\" /*API KEY HERE*/\\n    var arg = {\\n\\t    data: {\\n\\t    \\turl : url,\\n\\t    \\tapikey : apikey\\n\\t    },\\n        url: domain,\\n        cache: true,\\n        dataType: \\\"json\\\"\\n    };\\n    if ('withCredentials' in new XMLHttpRequest) {\\n        arg.success = fn;\\n    }\\n    else {\\n        var cb = \\\"sc_\\\" + url.replace(/\\\\W/g, '');\\n        window[cb] = fn;\\n        arg.jsonpCallback = cb;\\n        arg.dataType += \\\"p\\\";\\n    }\\n    return jQuery.ajax(arg);\\n};\\n\",\n      \"language\": \"javascript\",\n      \"name\": \"jQuery Plugin\"\n    }\n  ]\n}\n[/block]\nThis plugin utilizes CORS on CORS-compliant browsers. \n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \" jQuery(document).ready(function($){\\n \\t\\t$.sharedCount(location.href, function(data){\\n        $(\\\"#tweets\\\").text(data.Twitter); \\t \\n        $(\\\"#likes\\\").text(data.Facebook.like_count);\\n        $(\\\"#plusones\\\").text(data.GooglePlusOne);\\n        $(\\\"#sharedcount\\\").fadeIn();\\n\\n});\\n });\\n\",\n      \"language\": \"javascript\"\n    }\n  ]\n}\n[/block]","category":"591021f8d4cd662d00c82f9f","createdAt":"2014-10-07T18:36:03.269Z","excerpt":"This page will help you get started with SharedCount. You'll be up and running in a jiffy!","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","next":{"pages":[],"description":""},"order":0,"parentDoc":null,"project":"54343293fa5527080064f472","slug":"getting-started","sync_unique":"","title":"Getting Started with SharedCount","type":"basic","updates":[],"user":"5434326ae532ff0800e185ab","version":"591021f7d4cd662d00c82f9e","childrenPages":[]}

Getting Started with SharedCount

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

Please see <a href='http://www.sharedcount.com/pricing.php' target='_blank'>pricing page</a> for detailed quota information and information on paid plans with extra API quota. [block:api-header] { "type": "basic", "title": "API Calls" } [/block] You can retrieve SharedCount data from a JSON/JSONP API. [block:callout] { "type": "success", "body": "Your API Key\n**[[app:key]]**\n\nYour endpoint URL\n**https://[[app:plan]].sharedcount.com/v1.0/**", "title": "Your API Information" } [/block] Values of queries may be cached for up to an hour for repeated URLs. [block:code] { "codes": [ { "code": "{\"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}", "language": "json", "name": "Sample Response" } ] } [/block] ------------------ [block:callout] { "type": "info", "title": "", "body": "All the plans use a single URL endpoint, except dedicated users, which have their own custom domain.\n\n**Free, Plus, and Business Plan Users**\n*https://api.sharedcount.com/v1.0/*\n\n**Dedicated Users**\n*https://custom-domain.sharedcount.com/v1.0/*" } [/block] [block:callout] { "type": "info", "title": "Upgrading from the old endpoint", "body": "The endpoint URL has changed from /url to /v1.0/ (please note the trailing backslash)." } [/block] [block:api-header] { "type": "basic", "title": "Errors" } [/block] 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. [block:code] { "codes": [ { "code": "{\"Error\": \"Free API quota exceeded. Quota will reset tomorrow. Visit SharedCount to inquire about paid plans. http://sharedcount.com/quota\", \"Type\": \"quota_exceeded\"}\n", "language": "json", "name": "quota_exceeded (HTTP 401): Exceeded the API quota." } ] } [/block] [block:code] { "codes": [ { "code": "{\"Error\":\"Not a valid URL.\", \"Type\": \"invalid_url\"}\n", "language": "text", "name": "invalid_url (HTTP 400): The URL you passed to the API is invalid.\n" } ] } [/block] [block:code] { "codes": [ { "code": "{\"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\"}\n", "language": "json", "name": "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.\n" } ] } [/block] ##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 secure your 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. [block:api-header] { "type": "basic", "title": "API Quota" } [/block] Each API key is allocated a daily quota for their number of API calls. API keys sending more than their allocated quota in a day will see their queries rejected with an HTTP Status Code of 401. Paid users can, by request, enable quota overages. You can monitor your API usage by inspecting the response headers `X-Quota-Remaining`. Note that cached queries may return stale quota results. Users can check their *current* API quota by querying the end-point <a target='_blank' href='https://[[app:plan]].sharedcount.com/quota?apikey=[[app:key]]'>`/quota?apikey=[[app:key]]`</a> [block:api-header] { "type": "basic", "title": "Sample Code" } [/block] 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. [block:code] { "codes": [ { "code": "jQuery.sharedCount = function(url, fn) {\n url = encodeURIComponent(url || location.href);\n var domain = \"//[[app:plan]].sharedcount.com/v1.0/\"; /* SET DOMAIN */\n var apikey = \"[[app:key]]\" /*API KEY HERE*/\n var arg = {\n\t data: {\n\t \turl : url,\n\t \tapikey : apikey\n\t },\n url: domain,\n cache: true,\n dataType: \"json\"\n };\n if ('withCredentials' in new XMLHttpRequest) {\n arg.success = fn;\n }\n else {\n var cb = \"sc_\" + url.replace(/\\W/g, '');\n window[cb] = fn;\n arg.jsonpCallback = cb;\n arg.dataType += \"p\";\n }\n return jQuery.ajax(arg);\n};\n", "language": "javascript", "name": "jQuery Plugin" } ] } [/block] This plugin utilizes CORS on CORS-compliant browsers. [block:code] { "codes": [ { "code": " jQuery(document).ready(function($){\n \t\t$.sharedCount(location.href, function(data){\n $(\"#tweets\").text(data.Twitter); \t \n $(\"#likes\").text(data.Facebook.like_count);\n $(\"#plusones\").text(data.GooglePlusOne);\n $(\"#sharedcount\").fadeIn();\n\n});\n });\n", "language": "javascript" } ] } [/block]