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
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.
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
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
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 = client.stats(:shortUrl => 'http://bit.ly/1RmnUT') # => UrlShortener::Response::Stat object
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 = client.info(:shortUrl => 'http://bit.ly/1RmnUT') # => UrlShortener::Response::Info object
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.
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.