Use the Analytics Data API to programatically access and integrate Shareaholic report data

Build custom dashboards, automate reporting or integrate with other applications.

Analytics Data Feed API

API Designed for Ease

We have optimized for ease of implementation. Most implementations of this API take less than 15 minutes to setup. Simply call the provided URLs with their respective parameters, and you're done.

Getting Started: Authentication

All analytics data API endpoints require Secret API token authentication credentials to be supplied. If you don't include your secret token when making an API request or use an incorrect or outdated one, you will get an error. To get your API Token, you need a Shareaholic account and Site ID. Signup for an account and add your site to get a Site ID.

Once you have your Site ID:

  1. Go to SettingsIntegrations
  2. Scroll down to the API Tokens section
  3. Click Create new token
We also offer the option to automatically export raw analytics event data to your Amazon AWS S3 Bucket for custom analysis every hour, day, etc. Setup under Site Profile → Integrations → Amazon AWS S3.

Keeping your Secret API tokens safe

You should treat your Secret API token as you would any other password. Publicly exposing your credentials can result in your account being compromised. Grant access only to those who need it. Ensure it is kept out of any version control system you may be using. Control access to your key using a password manager or secrets management service.

API Endpoints

1. Total share button clicks for each URL in a given timeframe

curl -XGET 'https://www.shareaholic.com/api/v3/analytics/share/pages.csv?site_id=:site_id&start=:interval_start&end=:interval_end' \
-H 'Authorization: Bearer :secret_api_token'

Parameter Description Required Parameter Type Example
site_id Site Profile ID Required Query site_id=8943b7fd64cd8b1770ff5affa9a9437b
start Date (and optional hour) of the start of the period Required Query start=2021-10-01, start=2021-10-01T14
end Date (and optional hour) of the end of the period required Query end=2021-10-01, end=2021-10-01T14
domain Domain or sub-domain to filter. Defaults to all domains i.e. no filter. Optional Query domain=shareaholic.com
tz Time zone as IANA Time zone ID or ISO–8601 UTC offset (preferred). Defaults to UTC. Optional Query Formats supported:
tz=America/New_York (IANA Time zone ID)
tz=-04:00 (ISO–8601 UTC offset)
service Service to get counts for. Defaults to all services. Optional Query service=facebook

Example:

curl -XGET 'https://www.shareaholic.com/api/v3/analytics/share/pages.csv?site_id=pde830kcbe239e821h33381e9175062f&start=2021-10-01&end=2021-10-02' \
-H 'Authorization: Bearer 12cad1l17b7f3b79d91a1e7593e5f9a1'

Result:

URL,shares
shareaholic.com/blog,123
shareaholic.com,456

2. Share button clicks for a given URL in a given timeframe by service

curl -XGET 'https://www.shareaholic.com/api/v3/analytics/share/counts.csv?site_id=:site_id&start=:interval_start&end=:interval_end&url=shareaholic.com/blog' \
-H 'Authorization: Bearer :secret_api_token'

Parameter Description Required Parameter Type Example
site_id Site Profile ID Required Query site_id=8943b7fd64cd8b1770ff5affa9a9437b
start Date (and optional hour) of the start of the period Required Query start=2021-10-01, start=2021-10-01T14
end Date (and optional hour) of the end of the period required Query end=2021-10-01, end=2021-10-01T14
url URL to get data for (protocol is optional) Required Query url=shareaholic.com/blog
tz Time zone as IANA Time zone ID or ISO–8601 UTC offset (preferred). Defaults to UTC. Optional Query Formats supported:
tz=America/New_York (IANA Time zone ID)
tz=-04:00 (ISO–8601 UTC offset)
service Service to get counts for. Defaults to all services. Optional Query service=facebook

Example:

curl -XGET 'https://www.shareaholic.com/api/v3/analytics/share/counts.csv?site_id=pde830kcbe239e821h33381e9175062f&start=2021-10-01&end=2021-10-02&url=shareaholic.com/blog' \
-H 'Authorization: Bearer 12cad1l17b7f3b79d91a1e7593e5f9a1'

Result:

service_code,service_name,shares
facebook,Facebook,3
fark,Fark,1
sms,SMS,2

3. List of possible service_code values

The web is dynamic. Services can be added and retired over time. This API makes it convenient to fetch the most up-to-date list of supported services and their service_codeservice_name map.

curl -XGET 'https://www.shareaholic.com/api/v3/services.json'

Result:

[
 {
    "service_id":5,
    "service_code":"facebook",
    "service_name":"Facebook"
 },
 {
    "service_id":7,
    "service_code":"twitter",
    "service_name":"Twitter"
 },
 ...
]

Error codes

HTTP Response Error Code Description
401 10 Not authorized - No credentials provided
403 11 Forbidden - Provided credentials do not have permission
404 100 Missing site_id
404 101 Invalid site_id
400 110 Missing date
400 111 Invalid date provided
400 112 Date range should be 60 or fewer days
400 140 Missing or invalid URL

Branding Requirements

We require that you adhere to our branding requirements, as follows:

  • Any displayed metrics must cite "Shareaholic" as the source
  • Where possible, any displayed metrics must provide an active link to https://www.shareaholic.com
  • If data is used to create a graphical representation of the metrics, an approved Shareaholic logo needs to be present within or adjacent to the graphic. It is up to the discretion of the publisher where to specifically place the logo within or adjacent to the graphic.

Feedback

If you believe you have found a bug, or you’d like to request additional functionality, or you release something using this API, we’d love to hear from you.

Build with Shareaholic

Developer Tools and APIs that are reliable, stable, and fast. Built and run on the same scaled cloud infrastructure that runs Shareaholic products and powers functionality across over 300,000+ sites. Over 10 rock solid years in production.

As seen in