Support

Please note that AddThis will be closed for the Labor Day holiday August 30th, 2014 to September 1st, 2014.

AddThis Analytics API

Check out our Analytics API if you're looking for programmatic access to your sharing data. You can use the API to download reports and integrate them your into internal metrics dashboards and workflow. There are a variety of queries to help you understand how your content is being shared, who is sharing it, and what their interests are.



Getting Started

Calling the API is easy, you just make an HTTPS request with your username and password to any of the supported endpoints. You can ask for data in CSV or JSON format and specify a timerange for the query. Try these examples by clicking the links:

If you replace YOUR_PUBID with a valid profile ID these links will ask for your userid and password, and return a CSV file, viewable in excel.

What were my top shared urls?
https://api.addthis.com/analytics/1.0/pub/shares/url.csv?pubid=YOUR_PUBID
How many times was my content shared, by day, over the last week?
https://api.addthis.com/analytics/1.0/pub/shares/day.csv?period=week&pubid=YOUR_PUBID
How many users shared my content this month, broken down by their interests?
https://api.addthis.com/analytics/1.0/pub/sharers/interest.csv?period=month&pubid=YOUR_PUBID
Which sharing services sent the most clicks back to my site this week?
https://api.addthis.com/analytics/1.0/pub/clicks/service.csv?period=week&pubid=YOUR_PUBID

How do these queries work?

Take a look at each of the query urls above, reading the path starting with "/pub/<X>/<Y>". You can interpret each url as a query for "X by Y", e.g. my "shares by url", "shares by day", "sharers by interest" or "clicks by service", respectively. We refer to X and Y as a metric and a dimension. A metric is something that we measure (like shares or clicks) and a dimension is an property for slicing that data (like service or day). You combine a metric and a dimension to make a query, check out the table below for the complete list of supported queries.

 

Services

This table lists all of the queries available from this API, using various combinations of the supported metrics and dimensions. Click the path on each query to try it yourself.

Path Description Supported Query Parameters
/shares/day number of shares per day period,domain,service,url
/shares/url top shared urls (does not contain all urls shared) period,domain,service
/shares/domain shares segmented by content domain period
/shares/service shares segmented by sharing service period,domain,url
/shares/interest shares segmented by sharer's interest period,domain,service,url
/shares/continent shares segmented by sharer's continent period,domain,service,url
/shares/country shares segmented by sharer's country period,domain,service,url
/clicks/day number of clicks per day period,domain,service,url
/clicks/url top clicked urls (does not contain all urls clicked) period,domain,service
/clicks/domain clicks segmented by content domain period
/clicks/service clicks segmented by sharing service period,domain,url
/clicks/interest clicks segmented by clicker's interest period,domain,service,url
/clicks/continent clicks segmented by clicker's continent period,domain,service,url
/clicks/country clicks segmented by clickers's country period,domain,service,url
/subscriptions/day number of subscriptions per day period,domain,service,url
/subscriptions/url top subscribed urls (does not contain all urls) period,domain,service
/subscriptions/domain subscriptions segmented by domain period
/subscriptions/service subscriptions segmented by subscription service period,domain,url
/subscriptions/interest subscriptions segmented by subscriber's interest period,domain,service,url
/subscriptions/continent subscriptions segmented by subscriber's continent period,domain,service,url
/subscriptions/country subscriptions segmented by subscriber's country period,domain,service,url
/sharers/day number of unique sharers per day period,domain,service,url
/sharers/interest sharers segmented by sharer interest period,domain,service,url
/influencers/day number of unique influencers per day period,domain,service,url
/influencers/interest influencers segmented by their interests period,domain,service,url
/clickers/day number of unique clickers per day period,domain,service,url
/clickers/interest clickers segmented by their interests period,domain,service,url
/users/day number of unique sharers and clickers per day period,domain,service,url
/users/interest sharers and clickers segmented by their interests period,domain,service,url
/searches/term top search terms which resulted in shares period,domain,service,url
/referers/domain top referring domains which resulted in shares period,domain,service,url


Requests

Authentication

The Analytics API will require you to authenticate yourself using your AddThis userid and password. See the authentication documentation for details on the authentication mechanisms available and how to use them. We recommend you make your requests over HTTPS to keep your userid and password secure.

URL Format

https://api.addthis.com/analytics/1.0/pub/<metric>[/<dimension>].<format>[?<params>]

Method

To acquire data from the Analytics API use an HTTP GET request.

Rate Limit

This API limits users to 10 requests per minute. See the web service documentation for more on rate limiting in AddThis web services.

Filtering

Optionally, you can filter the data reported using the supported query parameters.

Note: not all reports support all methods of filtering. To determine which filters are available for a given report, see the supported query parameters in the services table below.

Query Parameters
Name Description Value Example Default
pubid The publisher profile for which you're requesting data. Can be omitted if you have only one profile. <pubid> &pubid=ra-4d5ecb7e3779d47e No default
period Collect response data starting from yesterday going back a number of days equal to the specified period. day|week|month|last24 &period=week day
domain Collect response data only on the specified domain <domain name> &domain=www.example.com all domains
service Collect response data only for the specified services. <service code>(,<service code>)* &service=email,print all services
url Collect response data only for the specified url. <url> &url=http%3A//www.example.com all URLs
Notes:
  • Unlike the other parameters, the url and service query parameters cannot be used together in the same request. If both are specified, the url parameter will be ignored.
  • The returned times are of the format YYMMDD, except for last24 which adds hours to become YYMMDDHH.
  • The last24 is only supported for day, url, domain, country, and service dimensions.

Metrics

The analytics api lets you retrieve data on several metrics:

Metric Description
shares Shares of your content using AddThis
clicks Clicks to your shared content
subscriptions Feed subscriptions using AddThis
sharers Unique users who shared your content using AddThis
influencers Unique users who shared your content using AddThis and received at least one click
clickers Unique users who clicked on your shared content
users Unique users who shared or clicked on your content, through AddThis
searches Searches which landed on your site and resulted in shares
referers Referring domains to your site for views which resulted in shares

Dimensions

You can slice your metrics by various dimensions. These dimensions are not available for all metrics, see the chart for details.

Dimension Description Supported Metrics
day By day, over a period of time shares, clicks, subscriptions, sharers, influencers, clickers, users
url By url, (for your top urls) shares, clicks, subscriptions
domain By domain shares, clicks, subscriptions, referers
continent By continent shares, clicks, subscriptions
country By country shares, clicks, subscriptions
service By sharing service shares, clicks, subscriptions
interest By user interest shares, clicks, subscriptions, sharers, influencers, clickers, users
term By search term searches


Responses

Formats

This API supports both JSON and CSV formats. Your request must include either the .json or .csv extension. See the web service documentation for more on response formats in AddThis web services.

Headers

HTTP Headers contained in the response can provide useful information to help your API client process the response data appropriately.

Last-Modified

The Last-Modified header provides the date and time at which the report data was generated. If the server is unable to handle your request in a timely manner, but it has data cached for the requested report, it will respond with the expired or "stale" data from the cache while it is busy generating the updated report. You can check the Last-Modified time to detect if the data reported is stale. New data for a given day becomes available at midnight (00:00:00 EST) the following day. If the Last-Modified time precedes midnight of the current day, the report does not include the latest available data. If your application requires the latest data, retry your query later to get an updated report.

Retry-After

If the server is unable to handle your request in a timely manner and has no cached data to return, you will receive a 503 status (100 error code if you are suppressing HTTP status codes) in your response indicating that the server is busy. The Retry-After header provides an estimated wait time in seconds after which you can expect a successful response should you resubmit your request.

Errors

You may encounter the following error responses while using this API:

Status Code Error Description
400 20 Missing Parameter See message details about which parameter is missing.
400 30 Invalid Parameter Use only valid parameters. Accept no substitutes.
400 90 Rate Limited Whoa there, you've exceeded the rate limit. Take it easy partner, then try your request again.
401 80 Authentication Failed Invalid userid or password. Try again, but this time, get it right.
404 50 Not Found Check to make sure that your path matches the URL format and uses valid path parameters.
406 70 Unsupported Data Format Is your path extension one of the supported response formats?
500 999 Internal Error Something has gone terribly wrong! This should never happen, but on the off chance that it does, we'll be hard at work to correct it. Please let our team know here if you do encounter a problem.
503 100 Service Unavailable Some requests may take longer to satisfy than others, especially if you are requesting data for the first time. If the server is unable to generate a response in a timely manner, it will return with this error instead. This is to be expected while the service is still new and we're in the process of gauging demand and usage patterns. Simply wait for a short period of time (see Retry-After) and retry your request.

See the web service documentation for more on error responses in AddThis web services.

Last Updated: Oct 18, 2013 03:30PM EDT
help@addthis.com
http://assets01.desk.com/
false
desk
Loading
seconds ago
a minute ago
minutes ago
an hour ago
hours ago
a day ago
days ago
about
false
Invalid characters found
/customer/en/portal/articles/autocomplete