Ow.ly API Reference
API Access
Ow.ly API for URL shortening is available to Enterprise users only. If you currently have an Enterprise Account, please contact your Customer Success Manager (CSM) to request Ow.ly API access. Should you wish to discuss our Enterprise Plan features and pricing, please contact our Sales Team.
Current API Version: 1.1
Ow.ly's API lets developers interact with ow.ly's link shrinking and expanding capabilities. Using the API, you're also able to view the info (e.g. HTML page title, votes) of an Ow.ly link without fully expanding it. Basic click stats are also available.
Ow.ly adopts RESTful method for API provisioning. At this time only JSON responses are supported.
HTTP Response codes
- 200 - OK
- 304 - Not Modified
- 400 - Bad Request*
- 401 - Not Authorized**
- 403 - Forbidden
- 404 - Not Found
- 406 - Not Acceptable
- 408 - Request Timeout
- 500 - Internal Server Error
- 501 - Not Implemented
- 502 - Bad Gateway
- 503 - Service Unavailable***
*Normally used to indicate the request has missing/wrong info. For example, not passing a short url to the 'info' method
**Indicates Invalid API key
***Indicates API usage has exceeded the allowed limit (there is no limit while in beta)
Authentication
All requests require an API key parameter (field name should be "apiKey").
Your API account controls how the "/url/shorten" method behaves. The default behavior is to return a static short url hash if the long url is the same. As an example, http://hootsuite.com
will always return http://ow.ly/1abc23
.
Alternatively, you can have your API account configured to always return unique short url hashes. In this case, http://hootsuite.com
will return different hashes every time you shorten it. Please consider which type of short url generation you want to use in your application when asking for an API Key.
In addition, every API call needs to indicate an API version in the path. Currently, the only version available is 1.1
Example call to Ow.ly API:
http://ow.ly/api/1.1/url/shorten?apiKey=12345ABCD57EF&longUrl=http://hootsuite.com
Error Handling
If a Request fails, an error will be provided whenever possible. For example, if you try to shorten text that is not a valid url, the http response code will be 400, and what you'll get in response body is:
{"request":"\/api\/1.1\/url\/shorten","error":"Invalid longUrl parameter provided."}
API Methods
List of Ow.ly API methods:
Root URL: http://ow.ly/api/[version#]. i.e. http://ow.ly/api/1.1
Please note: All parameters should be URL Encoded
Given a full URL, returns an ow.ly short URL. Currently the API only supports shortening a single URL per API call.
Your API Key controls whether the short url returned is a static value(default), or whether it's always a unique value. See the Authentication section above for more details.
- Method:
- GET
- Request Params:
- apiKey
- longUrl
- Response:
- Returns short url data on success
Example Call:
http://ow.ly/api/1.1/url/shorten?apiKey=1b2b374b212&longUrl=http://www.hootsuite.com
Example Response:
{"results":{"hash":"2blNn6","longUrl":"http:\/\/hootsuite.com","shortUrl":"http:\/\/ow.ly\/2blNn6"}}
Given an ow.ly URL, returns the original full URL.
- Method:
- GET
- Request Params:
- apiKey
- shortUrl
- Response:
- Returns the original url.
Example Call:
http://ow.ly/api/1.1/url/expand?apiKey=1b2b374b212&shortUrl=http://ow.ly/1234
Example Response:
{"results":{"hash":"2blNn6","longUrl":"http:\/\/hootsuite.com","shortUrl":"http:\/\/ow.ly\/2blNn6"}}
Given an ow.ly URL, returns information about the page, including the original URL, the HTML title, total clicks, and the "votes" value for the link (votes may be a positive or negative value).
- Method:
- GET
- Request Params:
- apiKey
- shortUrl
- Response:
- Returns full short url data on success.
Example Call:
http://ow.ly/api/1.1/url/info?apiKey=1b2b374b212&shortUrl=http://ow.ly/1234
Example Response:
{"results":{"hash":"2blNn6","longUrl":"http:\/\/hootsuite.com","title":"Welcome to HootSuite - The Professional Twitter Client","votes":3,"totalClicks":15,"shortUrl":"http:\/\/ow.ly\/2blNn6"}}
Given an ow.ly URL, returns an array of dates and the number of clicks on that date. The default behavior is to return all dates/clicks for that short URL. You can optionally specify a date range to retrieve a subset of the data.
Date fields must be in the following format: YYYY-MM-DD HH:MM:SS
- Method:
- GET
- Request Header:
- Authorization
- Request Params:
- apiKey
- shortUrl
- from (optional date field)
- to (optional date field)
- Response:
- Returns click data for the given time period on success.
Example Call:
http://ow.ly/api/1.1/url/clickStats?apiKey=1b2b374b212&from=2009-03-04 00:00:00&to=2009-03-06 23:59:59&shortUrl=http://ow.ly/1234
Example Response:
{"results":[{"date":"2009-03-04","clickCount":27},{"date":"2009-03-05","clickCount":12},{"date":"2009-03-06","clickCount":2}]}
Upload a photo to ow.ly file hosting service. (post data should be formatted as multipart/form-data)
Photos must be associated with a Twitter account. To validate the Twitter account you must pass an OAuth header to us that we then forward to Twitter. This method will return a 401 error if the header is not verified by Twitter.
OAuth header must be signed for url:
https://api.twitter.com/1.1/account/verify_credentials.json
- Method:
- POST
- Request Header:
- Authorization
- Request Params:
- apiKey
- fileName
- uploaded_file (binary file data)
- Response:
- Returns information about the file uploaded on success.
Example Call:
Authorization Header:
OAuth realm="http://api.twitter.com/", oauth_consumer_key="GDdmIQH6jhtmLUypg82g",
oauth_signature_method="HMAC-SHA1", oauth_token="819797-Jxq8aYUDRmykzVKrgoLhXSq67TEa5ruc4GJC2rWimw",
oauth_timestamp="1272325550", oauth_nonce="153515616126262",
oauth_version="1.0", oauth_signature="U1obTfE7Rs9J1kafTGwufLJdspo%3D"
apiKey = "1234ABCD56"
fileName: "trip_photo1.jpg"
uploaded_file: (binary data for trip_photo1.jpg)
Example Response:
{"results":{"hash":"3sw2D","caption":"trip_photo1.jpg","url":"http:\/\/ow.ly\/i\/3sw2D","cameraMake":"EASTMAN KODAK COMPANY","cameraModel":"KODAK Z7590 ZOOM DIGITAL CAMERA","latitude":null,"longitude":null,"score":1}}
Upload a document to ow.ly file hosting service. (post data should be formatted as multipart/form-data)
Documents must be associated with a Twitter account. To validate the Twitter account you must pass an OAuth header to us that we then forward to Twitter. This method will return a 401 error if the header is not verified by Twitter.
OAuth header must be signed for url: https://api.twitter.com/1.1/account/verify_credentials.json
- Method:
- POST
- Request Header:
- Authorization
- Request Params:
- apiKey
- fileName
- uploaded_file (binary file data)
- Response:
- Returns information about the file uploaded on success.
Example Call:
Authorization Header:
OAuth realm="http://api.twitter.com/", oauth_consumer_key="GDdmIQH6jhtmLUypg82g",
oauth_signature_method="HMAC-SHA1", oauth_token="819797-Jxq8aYUDRmykzVKrgoLhXSq67TEa5ruc4GJC2rWimw",
oauth_timestamp="1272325550", oauth_nonce="153515616126262",
oauth_version="1.0", oauth_signature="U1obTfE7Rs9J1kafTGwufLJdspo%3D"
apiKey = "1234ABCD56"
fileName: "map.pdf"
uploaded_file: (binary data for map.pdf)
Example Response:
{"results":{"hash":"a3ds4","caption":"map.pdf","url":"http:\/\/ow.ly\/d\/a3ds4","score":1}}
Updated 3 months ago