Bit.ly URL Shortening Service ColdFusion API
Shrink it, expand it, explore it, understand it... there are a few things you can do with a URL if you use the bit.ly URL service.
To make things a little easier for ColdFusion developers and URL-shrinking fans alike, I've built a ColdFusion CFC wrapper to interact with the bit.ly service API. Your URL shortening concerns may now be a thing of the past. :)
The open-source code is available now to download from RIA Forge: http://bitly.riaforge.org/
What is it?
The bit.ly API service requires an active account. Registration is free, and once created you will be provided with the API key required to use the API.
The API only offers five functions, so it's not an overly complex model to work with. These functions are:
- Shorten a URL
- Expand a URL back to the original
- Obtain information on a shortened URL
- Get stats on the URL such as traffic and referrer data
- Get a list of error codes from the API
Instantiate the bit.ly object
Invoking the object is a simple matter of passing through the two required parameters; the bit.ly username and API key.
<cfscript> strUser = 'your bit.ly account name' strKey = 'your bit.ly api key' // instantiate the object objBitly = createObject('component', 'com.coldfumonkeh.bitly.bitly'). init(username=strUser,apikey=strKey,parse=true); </cfscript>
In the above code example, I am also sending through an optional parameter called 'parse'. Set to false by default, the returned data will be in literal string format. Set to true as it is now, XML responses will be returned using the XmlParse() function, and JSON response using the DeserializeJSON() function, hopefully providing the developer an easier option to view when debugging or working with the data.
You can also set the response format 'globally' (ie for all methods within the CFC). By default, this is set to 'XML', and all methods will return XML-formatted data.
You can choose to set this across the board for all functions, or specify an individual return format per-method using the format argument, which will override the global setting.
Strip it down
In the following example, we are sending a request through to shorten a specific URL, and are overriding the global return format for this method by asking for the response in JSON format.
// let's shorten a URL shorten = objBitly.shorten( longURL='http://www.scotch-on-the-rocks.co.uk/', format='json');
As we have set the global 'parse' parameter to true, the output will be returned to us as ColdFusion structural information, as seen here:
Blow it back up
Let's now run a reverse on the URL we have just shortened to obtain the original URL, using the expand() method. This function will allow you to provide either the shortURL or the hash key generated and provided with the shorten response.
// let's expand a URL using a bit.ly short URL expand = objBitly.expand(shortURL='http://bit.ly/bQ8Nbv'); // or by using the bit.ly hash expand = objBitly.expand(hash='OWJV4');
In the above example, I have not provided a specific return format, so the global default option is used and will return XML, as below:
Grabbing some information
Let's now run the info() method to see what data we can retrieve from the same shortened URL. As with the previous method, you could choose to run this method using either the shortURL or the hash parameter:
// get info on a shortURL or hash info = objBitly.info(shortURL='http://bit.ly/bQ8Nbv',format='JSON');
The response from the info() request pulls back a lot of detailed information read from the target page, including meta-data stripped from the head tags. It will also provide you with the username of the original 'shrinkee'.
Get your facts
The stats() method allows you to view information on the traffic and referrers on a particular shortURL or hash. Total clicks, referrer address details and clicks per site are included in the response.
Getting this information is incredibly easy:
// get info on a shortURL info = objBitly.info(shortURL='http://bit.ly/bQ8Nbv',format='JSON');
The response from the above example can be seen below, again in Deserialized JSON format as we have provided the global parse and per-method format parameters.
Sounds good. Where can I get it?
The bit.ly API ColdFusion wrapper is available to download now from RIA Forge: http://bitly.riaforge.org/