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:
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
- 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
- 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
- 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
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 | default profile |
| period | Collect response data starting from yesterday going back a number of days equal to the specified period. | day|week|month | &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 |
Note: 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.
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 | 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 check the AddThis forum for status information and report any problems you encounter. |
| 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.