A Ruby API for


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, 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 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 =, api_key)

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

bitly.shorten('', :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('') #=> Bitly::Url

u.long_url #=> ""
u.short_url #=> ""
u.bitly_url #=> ""
u.jmp_url #=> ""
u.user_hash #=> "Ywd1"
u.hash #=> "2V6CFi" #=> a ruby hash of the JSON returned from the API
u.stats #=> a ruby hash of the JSON returned from the API

bitly.shorten('', 'keyword')

Version 3 API

Please see the API documentation for details on the V3 API.

Get your access token here:

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, api_key) to get the client, use Bitly.client: