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/
10 Comments on "Bit.ly URL Shortening Service ColdFusion API"
Hey Matt…
I actually have a library that works with multiple URL shortening services, allowing you to call just one shrink command and pass it the appropriate parameters. Perhaps we could work together and combine our codebases?
http://shrinkurl.riaforge.org/
Hey Andy
I actually noticed your project shortly after I’d submitted mine. Great job!
Would love to collaborate on combining the two if possible.
Nice wrapper, thanks.
I do have a question: in the bit.ly shorten response above, how do i reference ( i mean: use it, show on screen, put in db) the shortened url?
I prefer using dot notation to reference API responses, problem here is the url (in your example scoth-on-the-rocks.co.uk) which is being used as a ‘structkey’ (or key-name, don’t know how its called) so dot notation becomes a problem (because of the backslashes, which break dot-notation).
This is probably very simple todo, any advice appreciated.
Hey Marc –
thanks for the comment; always nice to hear when someone is using the wrappers
There are a few ways to access the struct within the results:
1. If you pass the URL into the shorten() method as a variable, then use that variable again to access the struct like so:
shorten.results[urlString].shortUrl
2. a slightly longer method, but using structFindKey() you can also access the data, bypassing the lengthy and unfriendly URL:
structFindKey(shorten.results, ‘shortUrl’)[1].owner.shortUrl
Works like a charm, many thanks for that.
The solution i’m using, based on your comment:
#shorten.results['http://www.google4games.com'.shortUrl#
So, the trick is in using the [' anyUrl '] apostrofes and brackets.
@Marc –
glad you got it working. The apostrophes are necessary as you are referencing the literal string, whereas in the above example I was calling the variable instead.
Both the same and both get the result at the end of the day.
Happy ‘bit.ly’-ing
Hello,
I’ve just found this wrapper and am trying to get it to work. I’m using Marc’s example above: #shorten.results[‘http://www.google4games.com'.shortUrl#
but I’m getting Variable SHORTEN is undefined.
Any idea what could be wrong?
Please ignore the last comment, just found out that my version of ColdFusion is too old!
Hi Joh
Which version of ColdFusion are you running?
Hi Matt,
Thanks so much for this. I got it working quickly except for one thing that I probably should have figured out sooner – URL encoding. You may want to build this in to auto encode the longUrl string. I couldn’t figure out why bit.ly kept ignoring all but the first URL variable!
I couldn’t figure out how best to update your CFC so I just encoded the URL before passing it in.
Thanks again,