How to use the Bitly API in Ruby

Link shortening has been around for a long time and Bitly is arguably the king of the link shorteners. It has support for shortening long URLs as well as custom short links, custom domains, and metrics to track how each link is performing.

For those of us with the power of code at our fingertips, Bitly also has an API. With the Bitly API you can build all of the functionality of Bitly into your own applications and expose it to your users. In this post you’ll learn how to use the Bitly Ruby gem to use the Bitly API in your Ruby applications.

Getting started

To start shortening or expanding links with the Bitly gem, you’ll need Ruby installed and a Bitly account.

To make API requests against the Bitly API you will need an access token. Log in to your Bitly account and head to the API settings. Here you can enter your account password and generate a new token. This token will only be shown once, so copy it now.

Using the Bitly API

Open a terminal and install the Bitly gem:

gem install bitly

Let’s explore the gem in the terminal. Open an irb session:

irb

Require the gem:

require "bitly"

Create an authenticated API client using the token you created in your Bitly account:

client = Bitly::API::Client.new(
  token: "Enter your access token here"
)

Shortening a URL

You can now use this client object to access all the Bitly APIs. For example, you can shorten a URL to a Bitlink like this:

long_url = "https://twitter.com/philnash"
bitlink = client.shorten(long_url: long_url)
bitlink.link
# => "https://bit.ly/3zYdN21"

The shorten endpoint is a simplified method of shortening a URL. You can also use the create endpoint and set other attributes, like adding a title, tags or deeplinks into native applications.

long_url = "https://twitter.com/philnash"
bitlink = client.create_bitlink(
  long_url: long_url,
  title: "Phil Nash on Twitter",
  tags: ["social media", "worth following"]
)
bitlink.link
# => "https://bit.ly/3zYdN21"
bitlink.title
# => "Phil Nash on Twitter"

Expanding a URL

The API client can also be used to expand Bitlinks. You can use the expand method with any Bitlink, not just ones that you have shortened yourself. When you expand a URL you will get back publicly available information about the URL.

bitlink = client.expand(bitlink: "bit.ly/3zYdN21")
bitlink.long_url
# => "https://twitter.com/philnash"
bitlink.title
# => nil
# (title is not public information)

If the URL was a Bitlink from your own account you get more detailed information when you use the bitlink method.

bitlink = client.bitlink(bitlink: "bit.ly/3zYdN21")
bitlink.long_url
# => "https://twitter.com/philnash"
bitlink.title
# => "Phil Nash on Twitter"

Other Bitlink methods

Once you have a bitlink object, you can call other methods on it. If you wanted to update the information about the link, for example, you can use the update method:

bitlink.update(title: "Phil Nash on Twitter. Go follow him")
bitlink.title
# => "Phil Nash on Twitter. Go follow him"

You can also fetch metrics for your link, including the clicks_summary, link_clicks and click_metrics_by_country. For example:

click_summary = bitlink.clicks_summary
click_summary.total_clicks
# => 1
# (not very popular yet)

Methods that return a list of metrics implement Enumerable so you can loop through them using each:

country_clicks = bitlink.click_metrics_by_country
country_clicks.each do |metric|
  puts "#{metric.value}: #{metric.clicks}"
end
# => AU: 1
# (it was just me clicking it)

With these methods, you can create or fetch short links and then retrieve metrics about them. Your application can shorten links and measure their impact with a few lines of code.

There’s more!

For advanced uses, you can also authorise other Bitly accounts to create and fetch short links via OAuth2 as well as manage your account’s users, groups, and organisations.

A useful little tool

To find out more about using the Bitly API with Ruby, you can read the Bitly API documentation, the Bitly gem’s generated documentation and the docs in the GitHub repo.

If you are interested, you can also read a bit more about the backstory of the Bitly Ruby gem. I’ve been working on this project since 2009, would you believe?

Are you using the Bitly API or do you have any feedback or feature requests? Let me know in the comments below, on Twitter at @philnash, or open an issue in the repo.