AddThis Academy

An ever-growing library of resources to help you become a better online marketer.

Changes to AddThis Analytics API

This article was updated on July 2nd, 2019

The AddThis Analytics API allows you to view social activity on your website, including shares, follows, and social referrals, originating from AddThis tools. It gives you programmatic access to the same data that you can see in the graphs in your Analytics Dashboard.

How to Access the New AddThis Analytics API

To access the Analytics API, your first step is to generate an access token. To do this, first, log into your AddThis dashboard at https://www.addthis.com/dashboard. Then, choose the profile for which you would like to access analytics, and click on Profile Settings at the top. Next, select API Keys on the left, and click the “Add Analytics API Key” button. Record the token value for use later. You can also use this page to replace or delete a specific token at any time.

While you’re there, also make a note of your Publisher ID (pubid), which is listed after “ID” on the Profile Settings main page. Most pubids start with “ra-” followed by some hexadecimal digits, although you may also have a custom pubid.

When you want to retrieve data, make a GET request with the “X-Api-Key” header set to your access token. Construct the URL by filling in your pubid to one of the following endpoints:

Shares: www.addthis.com/darkseid/analytics-api/[your pubid]/shares.json. Count the number of times that your pages were shared using AddThis tools

Social Referrals: www.addthis.com/darkseid/analytics-api/[yourpubid]/social_referrals.json. Count the number of times that people came to your site in response to seeing an AddThis share on social media.

Follows: www.addthis.com/darkseid/analytics-api/[your pubid]/follows.json. Count the number of times that people followed your social media accounts using AddThis tools

Visits: www.addthis.com/darkseid/analytics-api/[your pubid]/visits.json. Count the number of visits people have made to your site. Visits are roughly analogous to user sessions. Whenever a user views a series of pages on your site with fewer than 30 minutes between each view, we call this a single visit.

Optional Parameters

There are a few optional query parameters that you can add to modify or filter your request. These are:

‘range’: Specify the time range on which to include data. The ‘week’ value is the default if not specified. The options are:

  • ’24hours’ or ‘day’: events for the past 24 hours
  • ’72hours’: events for the past 72 hours
  • ‘yesterday’: events for the last complete day, from Midnight to 11:59 PM US EST
  • ‘7days’ or ‘week’: events for the last seven complete days, based on Eastern Time. This option is the default.
  • ’14days’: events for the last 14 complete days, based on US EST
  • ’30days’ or ‘month’: events for the last 30 complete days, based on US EST

Example: www.addthis.com/darkseid/analytics-api/[your pubid]/shares.json?range=week

‘service’: For shares, social referrals, and follows, you can pass a particular sharing service, such as ‘facebook’, to retrieve only events involving that service. You can find the list of our service codes here.

Example: www.addthis.com/darkseid/analytics-api/[your pubid]/shares.json?range=week&service=facebook

‘domain’: Filter to a specific domain or subdomain on your site. For example, filter to only jobs.mydomain.com rather than everything on mydomain.com. You can only retrieve data for a domain on which your pubid is installed.

Example: www.addthis.com/darkseid/analytics-api/[your pubid]/shares.json?range=week&service=facebook&domain=jobs.mydomain.com

‘device’: Filter the traffic to return only events from that device type. If this parameter is not specified, we default to show events from all devices.

Example: www.addthis.com/darkseid/analytics-api/[your pubid]/shares.json?device=mobile

‘callback’: Specify a JSONP callback function name, which will wrap the data in the response. More info here: https://www.w3schools.com/js/js_json_jsonp.asp

Example: Requesting www.addthis.com/darkseid/analytics-api/[your pubid]/shares.json?range=week&service=facebook&domain=jobs.mydomain.com would retrieve the number of times people shared pages from the jobs.mydomain.com site to Facebook in the past week.

Customize the API Response

Here is an example response, describing the number of shares per day from January 20-January 26, 2018. All dates are presented in YYMMDD format and are based on US EST time.

[{“date”:”180120″,”shares”:30},{“date”:”180121″,”shares”:25},{“date”:”180122″,”shares”:28},{“date”:”180123″,”shares”:30},{“date”:”180124″,”shares”:26},{“date”:”180125″,”shares”:28},{“date”:”180126″,”shares”:32}]

By default, data will be broken down by day. Alternatively, you can use one of the following endpoints to get data broken down by a different dimension, and you can include any of the query parameters listed above as well. For simplicity, the following examples all use share events, but you can replace /shares/ with /social_referrals/, /follows/, or /visits/ to fetch these metrics as well (except where listed).

Domain: www.addthis.com/darkseid/analytics-api/[your pubid]/shares/domain.json
Retrieve events broken down by the domains and subdomains of your site. Example response: [{“domain”:”blog.mydomain.com“, “shares”:100}, {“domain”:”jobs.mydomain.com“, “shares”:10}]

URL: www.addthis.com/darkseid/analytics-api/[your pubid]/shares/urls.json
Retrieve events broken down by the top-performing URLs on your site. Note: due to storage limits we return up to 50 top URLs by overall traffic, not a complete list.

Example response: [{“url”:”blog.mydomain.com/popular-article”, “shares”:800}, {“url”:”blog.mydomain.com/less-popular-article”, “shares”:50}, {“url”:”jobs.mydomain.com/”, “shares”:20}]

Social Service: www.addthis.com/darkseid/analytics-api/[your pubid]/shares/service.json
Only available for shares, social referrals, and follows. Retrieve events broken down by social media service.

Example response: [{“service”:”facebook”, “shares”:500}, {“service”:”linkedin”, “shares”:300}]

To retrieve data in CSV format instead, change ‘.json’ to ‘.csv’ in any of the above endpoints.


If you have any questions, please reach out to our amazing support team at help@addthis.com.

Last modified:  July 15th, 2019