Overview

The basic idea behind the Top Shares API is to expose portions of the ShareThis service architecture as consumable resources for publishers and users. This approach enables inclusion of ShareThis data in external applications for a variety of uses, such as, publishers being able to access their analytics data for integration in their own system or even expose pieces of their data, like Top Shared Content, via their website.

Features

Access and Authentication

You must have the ShareThis sharing widget deployed on your website in order to use the Top Shares Api. If you are interested in using the Top Shares API then please email pubrelations@sharethis.com for more information.

Resources

The Top Shares API conforms to REST design principles and supports representation selection by changing the file extension of the requested resource. Since all resources require authentication initially, the representations that we support are limited. Currently, only the XML data format will be supported, but future releases may includethe ability to recieve JSON data with callback support, HTML data with elements clssed for styling, PHP data as a serialized or CSV data for data processing.

HTTP Requests

Currently, the API is read-only, so only GET requets are accepted. Future release may include support for adding, modifying or deleting data from ShareThis.

  • GET: read data from ShareThis
  • POST: add or update data in ShareThis
  • DELETE: remove data from ShareThis

If a specific request method is not supported by a resource, an error will be returned.

HTTP Status Codes

  • 200 OK: request was valid and no errors were encountered
  • 400 Bad Request: request was received, but it wasn't valid (e.g. required parameters were missing)
  • 401 Not Authorized: request requires authentication, but they weren't provided or were invalid
  • 403 Forbidden: request was received, but we will not fulfill it
  • 404 Not Found: request was received, but resources was not recognized or does not exist
  • 500 Internal Server Error: request was received, but something went terribly wrong on our side

Error Messages

Error responses are returned in the format that was requested, where applicable. For example, an XML request will return properly formatted XML as the response.


Methods
  • pubstats_content: Returns most popular content for the time period being requested.
  • URL: http://rest.sharethis.com/pubstats_content.format
  • Format(s): XML
  • Method(s): GET
  • Parameters:

publisher (required) - Publishers Key (value of publisher parameter in ShareThis Javascript code)
domain (optional) - Domain Name (supports single domain, multiple domains by passing comma-separated list, or not domain to receive all records)
start (required) - Starting Date [Format: mm/dd/yyyy]
end (required) - Ending Date [Format: mm/dd/yyyy] (must be no more that 7 days greater than "start")

Sample Response: 
			
				
				<?xml version="1.0" encoding="UTF-8"?>
				<response>
					<content id="12345">
						<title>My Article Title</title>
						<url>http://path.to/article.html</url>
						<shares total="36">
							<destination type="email">23</destination>
							<destination type="facebook">13</destination>
						</shares>
					</content>
				</response>

Example

Top Shares in ShareThis Firefox Add-on
Top Shares in ShareThis Firefox Addon image

Publishers