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. 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 for the URL Shortener API.
Example:
...&apikey;=8943b7fd64cd8b1770ff5affa9a9437b&...
Note: the apikey used in this document is intended for use as an example only. It is subject to change.
Parameters
Endpoint:https://www.shareaholic.com/v2/share/shorten_link/
Parameter | Description | Required | Example |
---|---|---|---|
url |
URL to shorten | Required | url=http://www.google.com/ |
apikey |
API Key | Required | apikey=8943b7fd64cd8b1770ff5affa9a9437b |
service[name] |
Shortener Service | Optional | service[name]=shrlc (shrlc|bitly|tinyurl) |
service[token] |
Service Authentication | Optional | service[token]=0642e640dc831a3f32b68e579acssdbeaab1b360 |
Working Example:
https://www.shareaholic.com/v2/share/shorten_link?apikey=8943b7fd64cd8b1770ff5affa9a9437b&url;=http://google.com/&service;[name]=shrlc
You may use your own Bitly Generic Access Token by passing in an additional service[token]
parameter. When set, the URL Shortener API will use your personal key to shorten the link.
https://www.shareaholic.com/v2/share/shorten_link?apikey=8943b7fd64cd8b1770ff5affa9a9437b&url;=http://google.com/&service;[name]=bitly&service;[token]=[INSERT YOUR BITLY Generic Access Token]
Example success response:
{
"status_code": "200",
"data": "https://go.shr.lc/2sZ8JZo"
}
Give it a try: Shorten with SHRLC
Example error response:
{
"errors":[
{
"code":"140",
"source":{
"pointer":"/data/attributes/url"
},
"detail":"Missing or invalid URL. See https://www.shareaholic.com/api/shortener/ for usage examples."
}
]
}
Safety
URL Shortener API checks if the provided URL
is safe with the help of Google Safe Browsing. In the case of unsafe URL, the API will respond with the original URL and message that indicates why the URL is not safe.
For example:
https://www.shareaholic.com/v2/share/shorten_link?apikey=8943b7fd64cd8b1770ff5affa9a9437b&url;=http://testsafebrowsing.appspot.com/apiv4/ANY_PLATFORM/MALWARE/URL/&service;[name]=shrlc
Response:
{
"errors": [
{
"code": "145",
"source": {
"pointer": "/data/attributes/short-url"
},
"detail": "Unsafe URL: Malware (Any platform)"
}
]
}
Error codes
Code | Description |
---|---|
100 | apikey not provided |
101 | apikey provided is invalid |
140 | Missing or invalid URL |
145 | URL shortening problem or unsafe URL |
Rate Limits
In order to maintain an efficient, secure, and high-performing API, there are limits on how many times this API can be called in any given period. If you exceed your per-hour or per-minute call limit, you will receive a rate_limit_exceeded
429 error. To increase your limit, subscribe to a higher plan or contact your account manager for assistance. API responses include X-RateLimit-*
headers that describe rate limit usage.
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.