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:
- Go to Settings → Integrations
- Scroll down to the API Tokens section
- Click Create 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 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'
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'
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_code ⇆ service_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.
