Url Shortener gem – bit.ly api wrapper in ruby

Url shortener gem came out of my need to tweet rss feeds to twitter every 5 minutes and shortening the url is the first thing required to do that. I looked at different url shortening services and decided to use bit.ly‘s api as it appeared to be mature, comprehensive and more stable compared to other url shortening services.

The url_shortener gem allows to shorten/expand urls, retrieve stats and other information about them.

How to use

Since it is an API wrapper hence an account with bit.ly i.e. login and api key is required to use the url_shortener gem. bit.ly gives an API key to every user so if you have an account with bit.ly then you already have the key otherwise you can get it easily by signing up with bit.ly

Then the usual drill to install the gem

gem sources -a http://gemcutter.org
sudo gem install url_shortener

For a quick test, start an irb session and


require 'rubygems'
require 'url_shortener'

Before sending any request to bit.ly you need to initialize the Authorize and Client classes with bit.ly credentials:

authorize = UrlShortener::Authorize.new 'your_bitly_login', 'your_bitly_api_key'

If you don’t have a bit.ly account then you can use the bitlyapidemo key to try this

authorize = UrlShortener::Authorize.new 'bitlyapidemo', 'R_0da49e0a9118ff35f52f629d2d71bf07'
client = UrlShortener::Client.new(authorize)

bit.ly provides following four main end points or resources:

I suggest to check the xml outputs by clicking on the above end points to familiarize with the results returned.

Shorten Urls
Once you have the client object then call the shorten method on it with the url as the parameter.

shorten = client.shorten('http://www.yahoo.com') # => UrlShortener::Response::Shorten object

This will return a UrlShortener::Response::Shorten object which has several useful methods to parse results and access xml elements

shorten.result # => returns a hash of all data returned from bitly
shorten.urls # => returns the short url

The shorten method accepts a single or multiple url as parameters to shorten the urls

shorten = client.shorten('http://www.yahoo.com', 'http://www.google.com', 'http://github.com')

apart from the #urls and #result method you can also pass
#urls_with_long_url_keys, #hashes_with_long_url_keys, #hash and any xml element name within results->nodeKeyVal element

shorten.urls_with_long_url_keys
#etc

Expand Urls
To expand urls, either the hash or short url hash can be passed to the expand method which returns UrlShortener::Response::Expand object

expand = client.expand(:shortUrl => 'http://bit.ly/1RmnUT') # => UrlShortener::Response::Expand object
#OR
expand = client.expand(:hash => '1RmnUT') # => UrlShortener::Response::Expand object

Similar to the shorten method, you can call #result method to get a hash of xml or #url/#long_url to get the expanded long url

expand.result # => returns a hash of all data returned from bitly
expand.url # => returns a long url string

Stats

stats = client.stats(:shortUrl => 'http://bit.ly/1RmnUT') # => UrlShortener::Response::Stat object
#OR
stats = client.stats(:hash => '1RmnUT') # => UrlShortener::Response::Stat object
stats.result # => returns a hash of all data returned from bitly

There is a #referrers and #user_referrers method in the UrlShortener::Response::Stat class that does the xml parsing to return all referrers and as usual any xml element name can be passed as the method name to the stats response object like

stats.hash # => returns url hash
stats.referrers # => returns an array of referrers
stats.user_referrers # => returns an arrays of referrers
stats.clicks # => returns number of clicks

Info

info = client.info(:shortUrl => 'http://bit.ly/1RmnUT') # => UrlShortener::Response::Info object
#OR
info = client.info(:hash => '1RmnUT') # => UrlShortener::Response::Info object
info.result # => returns a hash of all data returned from bitly

All elements within doc element are available as methods to the info response object.
If you are a ruby purist and don’t want to use camelized method calls then you can use the underscore, for e.g.

info.htmlMetaDescription
#OR
info.html_meta_description

will work seamlessly and give the same results. Checkout the results return by bitly’s info resource to see what other methods are available to info response object.

url_shortener gem is available on github.