Use theAnalytics Data API to programatically access and integrate Shareaholic report data
Build custom dashboards, automate reporting or integrate with other applications.
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 requireSecret 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 aShareaholic account and Site ID. Signup for an account andadd your site to get a Site ID.
Once you have your Site ID:
- Go toSettings →Integrations
- Scroll down to theAPI Tokens section
- ClickCreate new token
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 apassword manager orsecrets 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 asIANA 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'URL,sharesshareaholic.com/blog,123shareaholic.com,4562. 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 asIANA 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'service_code,service_name,sharesfacebook,Facebook,3fark,Fark,1sms,SMS,23. List of possibleservice_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 theirservice_code ⇆service_name map.
curl -XGET 'https://www.shareaholic.com/api/v3/services.json'[ { "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 | Missingsite_id |
| 404 | 101 | Invalidsite_id |
| 400 | 110 | Missing date |
| 400 | 111 | Invalid date provided |
| 400 | 112 | Date range should be 60 or fewer days |
| 400 | 140 | Missing or invalidURL |
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, anapproved 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 tohear 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.
