Bitly.jl is a Julia package for accessing the Bitly API. Bitly is a popular link shortening service.


b = BitlyToken() # loads API Key
S = shorten(b,"") # is


Accessing the API requires obtaining a Generic Access Token.

  1. You can log on to your Bitly account to generate a Generic Access Token.
  2. You can use the requestBitlyToken(username,password) function to do the same.


Exchanges your username and password for an access token. Your username and password are not stored!

Returns an initialized BitlyToken object.

Note: you can also log on to your account on Bitly and request an access token directly.

Saving the Access Token

The access token does not automatically persist across sessions. You need to save it (using one of two methods) if you would like it to do so.

ENV variable

From the Julia REPL, just do

ENV["BITLY_ACCESS_TOKEN"] = "yourbitlykey"

Key file

In the file ~/.bitlyrc, store the key by itself.

keyfile = "~/.bitlyrc"
open(keyfile,"w") do file

Using the Access Token

Create an instance of BitlyToken either by passing the key in as an argument or it will look for it in the appropriate environment variable or file.


A connection to the Bitly API.


  • BitlyToken(): Token detected automatically. First, looks for the environment variable

BITLY_ACCESS_TOKEN, then looks for the file ~/.bitlyrc.

  • BitlyToken(token::AbstractString): User specifies token directly

See requestBitlyToken.

You have an ugly long link and want a short one?



Shorten url to a shortened link.

Returns a NamedTuple with link and response items. link is the link, while response is the complete JSON response from the Bitly API.

b = BitlyToken()
S = shorten(b,"")

You have a short uninformative link and want the long one?



Recovers the original url from a shortened link.

Returns a NamedTuple with long_url and response items. long_url is the original link, while response is the complete JSON response from the Bitly API.

b = BitlyToken()
S = expand(b,"")

Let's be real. Nobody is clicking your links. Here is how to prove it.


clicks(b::BitlyToken,link; summary=false,unit="day",units=-1,size=50)

Get click information for shortened link link.

summary=true provides a single count, otherwise returns a time series.

unit can be "minute","hour","day","week","month".

units is an integer representing the number of time units to query data for. Pass -1 to return all units available.

size is the quantity of items to be returned.

Returns a Dict.