bitly APIの使い方

はじめに

bitlyのWeb APIを使ってみたら便利だったのでメモ。
お好みのスクリプトと組み合わせると自動化できて作業効率UPします。

APIドキュメントは↓です。
http://dev.bitly.com/api.html

APIキーの取得

WebAPIを使用するのに必要なoauth2のAPIキーを取得しましょう。

1. bitlyにログインしてhttps://bitly.com/a/settings/advancedにアクセスします。
2. [OAuth Applications]の[here]をクリックします。
3. [Generic Access Token]でパスワードを入力し[Generate Token]をくリックします。
4. 生成されたAPIキーを控えておきます。（忘れてしまったら作り直し）

なお、https://bitly.com/a/settings/advancedにはLegacy API Keyが表示されていますが、これだと一部のAPIしか使用できません。

APIで短縮URLを作成する

shortenを使って短縮URLを作成します。

https://api-ssl.bitly.com/v3/shorten?access_token=ACCESS_TOKEN&longUrl=短縮したいURL

ACESS_TOKENと短縮したいURLを置き換えてください。
ブラウザに打ち込めばそのまま実行できます。

戻り値

{ "status_code": 200, "status_txt": "OK", "data": { "long_url": "https:\/\/bitly.com\/a\/oauth_apps", "url": "http:\/\/bitly.is\/xxxxxxx", "hash": "xxxxxxx", "global_hash": "xxxxxx", "new_hash": 1 } }

ステータスコードや、生成された短縮URLが返ってきます。

何らかのスクリプトで短縮したいURLを動的にセットして実行すると楽ちんです。
わたしは他にも事情があってJava×SeleniumでWevdriverのgetメソッドを使ってブラウザで実行させています。

APIで細かいアクセスログを取得する

https://bitly.com/a/statsでは30日より前の結果や、過去の日付を指定して時間単位のクリック数を見るといったことができません。
ちょっとした分析や報告にも不便なので、細かいログを取り出して見ました。

link/clicksを使って指定した短縮URLのログを取得します。

https://api-ssl.bitly.com/v3/link/clicks?access_token=ACCESS_TOKEN&unit=day&units=52&unit_reference_ts=1402498800&rollup=false&link=SHORT_URL&timezone=Asia/Tokyo

例によってACCESS_TOKENとSHORT_URLは置き換えてください。
いろいろパラメータを指定していますが、こここでは6/12を起点として過去52日分のログを取得しています。
起点の指定はunit_reference_tsに日付をエポック秒に直した値をセットします。
何日分欲しいかの指定はunitsに日数をセットします。

結果はJSONで返ってきます。※見やすいように整形しています。

戻り値

{"status_code": 200, "data": {
	"units": 52, 
	"unit_reference_ts": 1402498800, 
	"tz_offset": 9, 
	"unit": "day", 
	"link_clicks": [
		{"dt": 1402498800, "clicks": 5}, 
		{"dt": 1402412400, "clicks": 20}, 
		{"dt": 1402326000, "clicks": 4}, 
		{"dt": 1402239600, "clicks": 0}, 
		{"dt": 1402153200, "clicks": 1}, 
		{"dt": 1402066800, "clicks": 0}, 
		
		～中略～ ※52日ぶんなので、52個入っている
		
		{"dt": 1398092400, "clicks": 0}]
	}, 
"status_txt": "OK"}

このままだとなんなので、わたしはGsonで分解してCSV形式で出力したものをエクセルで開いて、ピボットテーブルを使って集計したりグラフを作成したりしています。

パラメーターの紹介です。

• link - bitlyの短縮url
• unit - クリック数のカウントを取得する単位。minute, hour, day, week or month, default: day
• units - 単位当たりの数を指定する。unitがdayでunitsが30なら30日分のクリック数を返す。-1だと全部出すけど、クリックがあった日しか出てこずグラフを作ったりしにくいので注意。
• timezone - タイムゾーン。
• rollup - trueまたはfalseを指定。デフォルト（true）だと集計値を返す。* falseだとunit毎の数を返す。
• limit - 1 to 1000 (default=100).
• unit_reference_ts - 基準となるタイムスタンプ。デフォルトは現在時間。5月のクリック数が知りたければ、5/31を指定してunitをday、unitsを31にする