Ow.ly API Documentation

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"). To enquire about getting an API key for your application, please contact us by email at support at HootSuite dot com.

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

/url/shorten

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 mre details.

Method:
GET
Request Params:
apiKey
longUrl
Response:
Returns short url data on success

Example Calls:


  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"}}
      

/url/expand

Given an ow.ly URL, returns the original full URL.

Method:
GET
Request Params:
apiKey
shortUrl
Response:
Returns the original url.

Example Response:


  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"}}
      

/url/info

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 Response:


  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"}}
      

/url/clickStats

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 Calls:
http://ow.ly/api/1.1/url/clickStats?apiKey=1b2b374b212&shortUrl=http://ow.ly/1234
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}]}
      

/photo/upload (updated for v1.1)

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 is 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 Response:


  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}}
      

/doc/upload (updated for v1.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 is 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 Response:


  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}}