Bitly.jl
Bitly.jl is a Julia package for accessing the Bitly API. Bitly is a popular link shortening service.
Example
b = BitlyToken() # loads API Key
S = shorten(b,"https://docs.julialang.org/en/v1/")
S.link # is http://bit.ly/2Us5Vl7
API Key
Accessing the API requires obtaining a Generic Access Token.
- You can log on to your Bitly account to generate a Generic Access Token.
- You can use the
requestBitlyToken(username,password)
function to do the same.
Bitly.requestBitlyToken
— FunctionrequestBitlyToken(uname,pw)
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
println(file,"yourbitlykey")
end
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.
Bitly.BitlyToken
— TypeA connection to the Bitly API.
Constructors
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
.
Link Shortening
You have an ugly long link and want a short one?
Bitly.shorten
— Functionshorten(b::Bitly,url::AbstractString)
Shorten url
to a bit.ly/xXxXx
shortened link.
Returns a NamedTuple
with link
and response
items. link
is the bit.ly
link, while response
is the complete JSON
response from the Bitly API.
b = BitlyToken()
S = shorten(b,"https://docs.julialang.org/en/v1/")
S.link
S.response
Link Expansion
You have a short uninformative link and want the long one?
Bitly.expand
— Functionexpand(b::BitlyToken,link::AbstractString)
Recovers the original url
from a bit.ly/xXxXx
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,"http://bit.ly/2Us5Vl7")
S.long_url
S.response
Link Clicks
Let's be real. Nobody is clicking your links. Here is how to prove it.
Bitly.clicks
— Functionclicks(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
.