A Ruby wrapper for the bit.ly API
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib Bump to version 1.1.2 Aug 19, 2018
.gitignore Bump oauth2 dependency. Fixes issue 22 Aug 13, 2012
.travis.yml Update Rubies to test in Travis Dec 26, 2017
Gemfile Bump oauth2 dependency. Fixes issue 22 Aug 13, 2012
History.txt Updates changelog Aug 19, 2018
LICENSE.md Moves License to its own file Jan 31, 2016
Rakefile Update Rubies to test in Travis Dec 26, 2017
bitly.gemspec Updates shoulda/activesupport versions of dev dependencies Nov 23, 2017




A Ruby API for http://bitly.com


Build Status


Bitly recently released their version 3 API. From this 0.5.0 release, the gem will continue to work the same but also provide a V3 module, using the version 3 API. The standard module will become deprecated, as Bitly do not plan to keep the version 2 API around forever.

To move to using the version 3 API, call:


Then, when you call Bitly.new(username, api_key) you will get a Bitly::V3::Client instead, which provides the version 3 api calls (shorten, expand, clicks, validate and bitly_pro_domain). See http://dev.bitly.com for details.

Eventually, this will become the default version used and finally, the V3 module will disappear, with the version 3 classes replacing the version 2 classes.

(Please excuse the lack of tests for the v3 classes, they are fully tested and ready to replace this whole codebase in the v3 branch of the GitHub repo, until I realized it would break everything.)


gem install bitly


Version 2 API

Create a Bitly client using your username and api key as follows:

bitly = Bitly.new(username, api_key)

You can then use that client to shorten or expand urls or return more information or statistics as so:

bitly.shorten('http://www.google.com', :history => 1) # adds the url to the api user's history

Each can be used in all the methods described in the API docs, the shorten function, for example, takes a url or an array of urls.

All four functions return a Bitly::Url object (or an array of Bitly::Url objects if you supplied an array as the input). You can then get all the information required from that object.

u = bitly.shorten('http://www.google.com') #=> Bitly::Url

u.long_url #=> "http://www.google.com"
u.short_url #=> "http://bit.ly/Ywd1"
u.bitly_url #=> "http://bit.ly/Ywd1"
u.jmp_url #=> "http://j.mp/Ywd1"
u.user_hash #=> "Ywd1"
u.hash #=> "2V6CFi"
u.info #=> a ruby hash of the JSON returned from the API
u.stats #=> a ruby hash of the JSON returned from the API

bitly.shorten('http://www.google.com', 'keyword')

Version 3 API

Please see the Bit.ly API documentation http://api.bit.ly for details on the V3 API.

Get your access token here: https://bitly.com/a/oauth_apps.

Configure bitly through initializer

If you want to configure bitly through an initializer (e.g. config/initializers/bitly.rb), do the following:


Bitly.configure do |config|
  config.api_version = 3
  config.access_token = "API_KEY"

Instead of using Bitly.new(username, api_key) to get the client, use Bitly.client: