API Designed for Ease
We have optimized for ease of implementation. All API methods are accessible via simple HTTP calls. 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 API endpoints require API authentication credentials to be supplied as query arguments (apikey). To get started, you'll need a free Shareaholic account and Site ID. Signup for an account and then add your site to get your Site ID. The Site ID is your API Key.
Example:
...&api_key=8943b7fd64cd8b1770ff5affa9a9437b&...Note: the apikey used in this document is intended for use as an example only. It is subject to change.
Parameters
Endpoint:https://recs.shareaholic.com/rec/
| Parameter | Description | Required | Example |
|---|---|---|---|
api_key |
API Key | Required | apikey=8943b7fd64cd8b1770ff5affa9a9437b |
location |
URL for which to return recommended content for | Required | location=https://example.com |
internal |
Number of internal results to return in the response. The actual amount returned may be less than requested. | required | internal=3 |
sponsored |
Number of sponsored results to return in the response. The actual amount returned may be less than requested. Results may include content from other websites that are personalized to the visitor. | Optional | sponsored=0 |
canonical |
Canonical URL of the page to return recommended content for | Optional | canonical=https://example.com |
Working Example:
https://recs.shareaholic.com/rec/?location=https%3A%2F%2Fwww.shareaholic.com%2Fblog%2Fquick-qr-code-generator-start-generating-qr-codes-in-less-than-1-minute%2F&internal=1&sponsored=0&api_key=8943b7fd64cd8b1770ff5affa9a9437b
{
"request": {
"deviceType": "Desktop",
"forwardedFor": [
"123.1.123.123"
],
"internal": 1,
"sponsored": 0,
"url": "https://www.shareaholic.com/blog/quick-qr-code-generator-start-generating-qr-codes-in-less-than-1-minute/",
"bot": false
},
"meta": {
"internal_data_available": true
},
"id": "116b7817-7fbf-4230-bad4-db7031257ed8",
"timestamp": "2021-10-26T19:05:56.628Z",
"internal": [
{
"source": 4,
"score": 13,
"url": "https://www.shareaholic.com/blog/search-engine-social-media-traffic-trends-report-2017/",
"title": "Pinterest, Google, & Instagram big winners as Facebook share of visits falls 8% in 2017 [REPORT]",
"description": "Looking back on 2017, we saw a major tide shift in how sites receive their traffic. After years of strong growth by Social Networks, Search finally had a comeback year and overtook Social as the top…",
"author": "Craig Zevin",
"image_url": "//www.shareaholic.com/blog/wp-content/uploads/2018/02/Shareaholic_social_network_search_engine_visit_share_graph_2011_2017-300x130.png",
"published_date": "2018-02-22T14:55:56.000Z",
"modified_date": "2018-03-01T18:17:17.000Z",
"channel_id": "intrec",
"display_url": "https://www.shareaholic.com/blog/search-engine-social-media-traffic-trends-report-2017/"
}
]
}
Error codes
| Code | Description |
|---|---|
| 400 | location or api_key not provided |
Content Meta Tags
Shareaholic creates a "Content Index" for all sites it is installed on. This is done by Steve, our bot that fetches and caches the HTML of each webpage our software is installed on. Our algorithms then evaluate the content of each webpage and select the most appropriate title, description, thumbnail, other meta information, including NLP (Natural Language Processing) semantic analysis of the content.
Optionally, you can provide additional structured information and hints about your content. This is done via Shareaholic Content Meta Tags. These meta tags are placed in the <head> section of the webpage. You can also use a generic meta tag, an Open Graph tag (og:), Twitter tag (twitter:) in addition to Shareaholic-specific meta tag. The latter overrides the former in all cases.
Note: At some point, you may run your site through a W3C validator. All Shareaholic Meta Tags are officially registered with W3.org and should not return any warnings.
| Tag | Description | Example |
|---|---|---|
| shareaholic:url | The canonical URL for the webpage | |
| shareaholic:image | The URL of the image that best represents the webpage | |
| shareaholic:title | The title that best represents the webpage | |
| shareaholic:article_author_name | The name of the author of the content of the webpage | |
| shareaholic:article_author | An URL to the profile of the author of the content of the webpage | |
| shareaholic:keywords | Keywords associated with the content of the webpage |
You may also disambiguate or classify keywords into tags (tag:), categories (cat:) and type (type:). For example: |
| shareaholic:language | Language of the content of the webpage | |
| shareaholic:article_published_time | (ISO 8601) - Timestamp for when the content of the webpage was first published | |
| shareaholic:article_modified_time | (ISO 8601) - Timestamp for when the content on the webpage was last modified | |
| shareaholic:site_name | The site name which should be displayed for the overall site | |
Updating the Cloud Content Index
If your meta tags change or if the Content Index on our servers has out-dated information about your content for any reason, you may manually initiate a content re-index from your site settings dashboard. This process can take a few hours to complete as Content Index requests are processed in the order in which we receive them. Depending on the number of requests ahead of yours, there may be a wait. Once your webpage data has been refreshed in our systems, your Content Index should be updated within a few minutes.
Feature Meta Tags
These meta tags influence functionality.
| Tag | Description | Example |
|---|---|---|
| shareaholic:site_id | Shareaholic Site ID to use | |
| shareaholic:article_visibility | Excludes page from Recommendation Engine Content Pool | |
| Excludes page from Recommendation Engine Content Pool and all Analytics | |
|
| shareaholic:shareable_page | Describes whether the page is shareable | Share Counts are not fetched for pages that are not shareable. |
| shareaholic:outstreamads | Disables Outstream Video Ads App | |
| shareaholic:drupal_version | Shareaholic for Drupal module version (automatically added by module) | |
| shareaholic:wp_version | Shareaholic for WordPress plugin version (automatically added by plugin) | |
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.
