bit.ly APIに関する説明資料

bit.ly API についての資料bit.lyはデータをAPIを経由して公開しているので、開発者はプログラムからbit.lyのウェブサイトと連携できます。このドキュメントはそれら機能の公式レファレンスです。APIの現バージョンは3.0です。目次

● 始めに ● 認証と共通引数● リクエスト・レスポンス形式 ● 利用制限

○ 高ボリューム利用者の方へ● OAuth

○ OAuth Web Flow ○ OAuth XAuth Flow

● QR コード● REST API

○ / v 3/ shorten ○ / v 3/ expand ○ / v 3/ validate ○ / v 3/ clicks ○ / v 3/ referrers ○ / v 3/ countries ○ / v 3/ clicks _ by _ minute ○ / v 3/ bitly _ pro _ domain ○ / v 3/ lookup ○ / v 3/ authenticate ○ / v 3/ info ○ / oauth / access _ token ○ / v 3/ user / clicks ○ / v 3/ user / referrers ○ / v 3/ user / countries ○ / v 3/ user / realtime _ links

本資料の原文は、http :// orino . co / bwePRr (英語)でご覧になれます。

始めにbit.lyのREST API ドキュメンテーションにて紹介されるトピックスは次の通りです。

認証と共通引数全てのAPIのエンドポイントは認証情報がクエリーの引数として指定されているのを必要と

しています。まず、無料の bit.lyアカウントと apiKeyを作成する必要があります。次のリンクのページからアカウントを作成できます。http://bit.ly/a/sign_up アカウント作成後 apiKeyは次のページにて確認できます。http://bit.ly/a/your_api_key login=login&apiKey=apiKey 注意：bitlyapidemo のアカウント情報及び apiKeyはこのドキュメンテーションの中でのサ

ンプルのためのみに表示しています。

リクエスト・レスポンス形式全ての bit.ly APIはオプションのレスポンス形式引数が利用できます。デフォルトのレスポンス形式は jsonですが xmlも提供しています。エンドポイントによっては txt形式も利用出

来るものもあります。format=json

1bit.ly API documentation – revised 10/22/2010

日本語でのお問い合わせはOrinoco株式会社まで：www.orinoco.jp / [email protected]

http://www.orinoco.jp/

全ての bit.ly APIでは jsonpも利用できます。jsonpはコールバックが指定された json形式です。例えば:format=json&callback=callback_method

● 全てのAPIリクエストはapi.bit.lyドメインに対して行う必要があります(例で確認してください)。

● json及び xml形式に対する正常なレスポンスのHTTP Response Status Code は200 です。 json及び xmlのレスポンスの場合は、status_code及び status_txtの値はリクエストが整形式かつ妥当で有ることを意味します。

● txt形式のリクエストの場合HTTP Response Status Codeの 403、500と 503は利用制限の注意、リクエストのフォーマットの問題及び不明なエラーが有ることを意味します。レスポンス本文は 200レスポンス外の json及び xmlコールのstatus_txt 部分と同等です。

● status_code は妥当なリクエストの場合は 200、利用制限の場合は 403、不明なエラーか一時利用不可の場合は 503、その他の無効なリクエストやレスポンスの場合は500 です。

● status_txt は発生したエラーの内容を説明する値が表示されます。表示される頻度が高い値はURL引数が必要なときのMISSING_ARG_%s やリクエスト引数に無効な値が含まれている場合の INVALID_%s 等があります（%sの部分にリクエスト引数の名前が表示されます）。

例： ● json { "status_code": 200, "status_txt": "OK", "data" : ... } ● json { "status_code": 403, "status_txt": "RATE_LIMIT_EXCEEDED", "data" :

null } ● json { "status_code": 500, "status_txt": "INVALID_URI", "data" : null } ● json { "status_code": 500, "status_txt": "MISSING_ARG_LOGIN", "data" :

null } ● json { "status_code": 503, "status_txt": "UNKNOWN_ERROR", "data" : null } ● jsonp callback_method({ "status_code": 200, "status_txt": "OK", "data" : ... }) ● xml

<?xml version="1.0" encoding="UTF-8"?><response> <status_code>200</status_code> <status_txt>OK</status_txt> <data> ... </data></response>

利用制限現在 bit.lyはAPIの利用者に対して一つの IPアドレスからの同時接続数を５接続で制限しています。さらに、各API毎に時間毎、分毎、そして IPアドレスごとの利用制限も設けていま

す。利用制限はしていますが、デフォルトの制限はほとんどのサイトのニーズに十分対応出来る用に設定されています。APIの利用制限は毎時間の始まり（００分）にリセットされます。利用制限によるエラーが発生している場合は次の時間が始まるまでお待ちください。利用制限による問題を回避するにはAPI の利用に関する注意事項を確認ください。高ボリューム利用者の方へもし bit.lyAPIの利用制限を超えるような高ボリュームの利用を推定される場合は [email protected]

までご連絡をしてください。ご連絡の際に bit.ly APIの利用方法、利用している、APIエンドポイント及び、２４時間で利

用されたいボリュームもお伝え下さい。




OAuth¶bit.ly は、OAuth 2 draft specification をサポートしています。全ての OAuth 2 リクエス

トは、 https://api-ssl.bit.ly/ にある SSL エンドポイントを利用しなくてはいけません。OAuth 2.0 はシンプルで、安全な認証の方法です。OAuth 2.0をりようすることにより、ウェブのアプリケーションが、bit.lyサイトにリダイレクトする為に必要なアクセストークンを得る事が出来ます。アクセストークンを得た後、ユーザーのリンクに関する測定値や、当該アカウントを利用した短縮URLの生成ができます。OAuthによる認証は、以下の方法で出来ます。

OAuth Web Flow¶以下の方法で、ウェブアプリケーションは、OAuthのアクセストークンを得る事が出来ま

す。● まず、api @ bit . ly （英語）にご連絡頂き、アプリケーションの登録アクセスを申請下さい。（日本語で申請ご希望の場合は、bitly @ orinoco . jp までご連絡下さい。）申請終了後、お客様の bit.lyアカウントの「設定」(settings) メニューで、あなたのアプリケーションを登録して下さい。登録後、client_id と client_secretが与えられま

す。● アクセストークンを入手後、client IDとリダイレクトを行いたいページを client_id

と redirect_uri parametersを使って転送し、ユーザーを https://bit.ly/oauth/authorize にリダイレクトして下さい。リダイレクトのURLの例は以下の通りです。https://bit.ly/oauth/authorize?client_id=...&redirect_uri=http://myexamplewebapp.com/oauth_page

● アプリケーションを認証後、ユーザーに redirect_uri パラメータで指定されたページ”が表示されます。 code”パラメータをURIに添付していますが、このパラメータ

は、下記の oauth/access_token エンドポイント資料を使う事でOAuthのアクセストークンに変換される値を含んでいます。例えば、次の redirect_uri の値をパスし

た場合、http://myexamplewebapp.com/oauth_page, 認証が成功した場合、ユーザーを下記のURI に転送します。http://myexamplewebapp.com/oauth_page?code=....

● その前のリダイレクトに bit.ly ”によって添付された code”値と、同様のその前に使われた redirect_uri 値をパスする事により、下記の the /oauth/access_token API エンドポイント資料を使って、OAUthのアクセストークンを入手する。APIエンドポイントによって、OAuthアクセストークン、特定された bit.lyユーザーのログインとAPIキーが発行され、お客様のアプリケーションが、bit.lyのAPIを利用する事が可能となります。

OAuth XAuth Flow¶OAuth web flow の利用が出来ないアプリケーション（例えば、ブラウザーレイヤーの無いモバイルアプリ）に関しては、/oauth/access_token APIエンドポイントに、ユーザーのbit.lyアカウント情報を x_auth_username と x_auth_password パラメータを使ってコールをかけて頂く事で、OAuthアクセストークンを入手する事が出来ます。

注：ユーザーは、ユーザーネームとパスワードを一度だけ登録する必要があります。XAuthを使ったアプリケーションは、決してユーザーのパスワードを保存しないで下さい。XAuthを利用した認証については、api＠bit.ly宛にアクセスの申請を行って下さい。（日本語で申請ご希望の場合は、bitly @ orinoco . jp までご連絡下さい。）

QR コード¶QR コードを作成するには、bit.ly のリンクの最後に .qrcode を添付して下さい。例えばURL: http://bit.ly/3eI7.qrcode により、http :// bit . ly /3 eI 7 の bit . ly にリンクするQRコード

が作成されます。







REST API/v3/shorten長いURL に対して、 /v3/shorten はURLをエンコードして短縮URLを返します。

引数● format （オプション）レスポンスの形式を指定できます。サポートしている形式：

json （デフォルト）、 xml 、 txt 。● longUrl 短縮される元のURL （例： http :// betaworks . com / ）。● domain （オプション） bit.lyか j.mpドメインを指定できます。出力される urlの

値が変わります。● x_login （オプション）その他の bit.lyユーザーの代わりにリクエストをする場合のそのユーザーのログイン情報です。これを利用することによりアプリケーション開発者はそのユーザーの bit.ly ログイン情報を送ることが出来ます。

● x_apiKey （オプション）その他の bit.lyユーザーの代わりにリクエストをする場合に利用するそのユーザーの apiKey 情報です。これを利用することによりアプリケーション開発者はそのユーザーの bit.ly apiKey情報を送ることが出来ます。

注意● 元のURLのURLエンコードをおすすめします。「& 」、「? 」、「# 」、「」、などの特定引数を含むURLは先にURL エンコードする必要があります。

● 空白を含むURLは利用できません：空白を含む元のURLは受け付けられません。全ての空白は%20もしくは+でエンコードする必要があります。タブ、改行、URL後の空白は全てエラーになります。URL前後の空白を除いてからURL短縮を行ってく

ださい。● 元のURLはドメインとパスのあいだにスラッシュが必要です。例えば、http://

example.com?query=parameter はエラーになりますので、http://example.com/?query=parameter 形式に先に変換擦る必要があります。

● x_loginと x_apiKeyが指定されている場合は、x_loginで指定されているユーザーの履歴に短縮URLが追加されます。loginで指定されているユーザーの履歴には追加さ

れません。出力● new_hash は元URLが初めて短縮されたことを表します。戻り値が 1の場合、long_urlが初めて短縮された事を表します。ユーザーの履歴にも追加されます。

● url は実際使用するべきの linkです。この値は、各 bit.lyアカウント毎の独特な値です。

● hash は long_urlに対する bit.ly の識別値で、各アカウント毎の独特な値です。● global_hash は long_urlに対する hashを全て統括する bit.lyの識別値であり、それに対する全ての bit.ly リンクの統計を表示するために使用できます。

● long_url は longUrlリクエスト引数のエコーです。必ずしも元のURLと同じだとは限りません。long_url はリクエスト引数とは機能的には同等です。

例● json 形式 http://api.bit.ly/v3/shorten?

login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&longUrl=http%3A%2F%2Fbetaworks.com%2F&format=json { "status_code": 200, "data": { "url": "http://bit.ly/cmeH01", "hash": "cmeH01", "global_hash": "1YKMfY", "long_url": "http://betaworks.com/", "new_hash": 0 }, "status_txt": "OK"}




● xml 形式 http://api.bit.ly/v3/shorten?login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&longUrl=http%3A%2F%2Fbetaworks.com%2F&format=xml <?xml version="1.0" encoding="UTF-8"?><response> <status_code>200</status_code> <status_txt>OK</status_txt> <data> <url>http://bit.ly/cmeH01</url> <hash>cmeH01</hash> <global_hash>1YKMfY</global_hash> <long_url>http://betaworks.com/</long_url> <new_hash>0</new_hash> </data></response>

● txt 形式 http://api.bit.ly/v3/shorten?login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&longUrl=http%3A%2F%2Fbetaworks.com%2F&format=txt http://bit.ly/cmeH01

/v3/expandbit.ly URLや hash(複数も可) を渡せば /v3/expand はデコードしてターゲットURLを返します。

引数● format （オプション）レスポンスの形式を指定できます。サポートしている形式：

json （デフォルト）、 xml 、 txt。● shortUrl は一つもしくは複数の bit.ly URL です、（例： http :// bit . ly /1 RmnUT か

http :// j . mp /1 RmnUT ）。● hash は一つもしくは複数の bit.ly hash です、（例： 2bYgqR かカスタム名）。注意● shortUrlも hash も引数としてリクエストされる必要があります。● shortURL及び hash引数の最高数は１５です。出力● short_url shortUrl リクエスト引数のエコーです。● hash は hash リクエスト引数のエコーです。● user_hash 関連する bit.lyユーザー ID。● global_hash 元URLに対する bit.lyの統括 hashの ID 。● error 特定の shortUrlもしくは hashに対するデータを取得においてエラーが生じた事を意味します。エラーの例は「NOT_FOUND 」。

● long_url は short_urlもしくは hashが指定しているターゲットURL です。

例● json 形式 http://api.bit.ly/v3/expand?shortUrl=http%3A%2F%2Ftcrn.ch

%2Fa4MSUH&shortUrl=http%3A%2F%2Fbit.ly%2F1YKMfY&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&hash=j3&hash=a35.&format=json { "status_code": 200, "data": { "expand": [ { "short_url": "http://tcrn.ch/a4MSUH",




"global_hash": "bWw49z", "long_url": "http://www.techcrunch.com/2010/01/29/windows-mobile-foursquare/", "user_hash": "a4MSUH" }, { "short_url": "http://bit.ly/1YKMfY", "global_hash": "1YKMfY", "long_url": "http://betaworks.com/", "user_hash": "1YKMfY" }, { "long_url": "http://www.scotster.com/qf/?1152", "global_hash": "lLWr", "hash": "j3", "user_hash": "j3" }, { "hash": "a35.", "error": "NOT_FOUND" } ] }, "status_txt": "OK"}

● xml 形式 http://api.bit.ly/v3/expand?shortUrl=http%3A%2F%2Ftcrn.ch%2Fa4MSUH&shortUrl=http%3A%2F%2Fbit.ly%2F1YKMfY&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&hash=j3&hash=a35.&format=xml <?xml version="1.0" encoding="UTF-8"?><response> <status_code>200</status_code> <status_txt>OK</status_txt> <data> <entry> <short_url>http://tcrn.ch/a4MSUH</short_url> <long_url>http://www.techcrunch.com/2010/01/29/windows-mobile-foursquare/</long_url> <user_hash>a4MSUH</user_hash> <global_hash>bWw49z</global_hash> </entry> <entry> <short_url>http://bit.ly/1YKMfY</short_url> <long_url>http://betaworks.com/</long_url> <user_hash>1YKMfY</user_hash> <global_hash>1YKMfY</global_hash> </entry> <entry> <hash>j3</hash> <long_url>http://www.scotster.com/qf/?1152</long_url> <user_hash>j3</user_hash> <global_hash>lLWr</global_hash> </entry> <entry>




<error>NOT_FOUND</error> <hash>a35.</hash> </entry> </data></response>

● json 形式 http://api.bit.ly/v3/expand?shortUrl=http%3A%2F%2Fbit.ly%2F31IqMl&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&format=json { "status_code": 200, "data": { "expand": [ { "short_url": "http://bit.ly/31IqMl", "global_hash": "31IqMl", "long_url": "http://cnn.com/", "user_hash": "31IqMl" } ] }, "status_txt": "OK"}

● xml 形式 http://api.bit.ly/v3/expand?shortUrl=http%3A%2F%2Fbit.ly%2F31IqMl&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&format=xml <?xml version="1.0" encoding="UTF-8"?><response> <status_code>200</status_code> <status_txt>OK</status_txt> <data> <entry> <short_url>http://bit.ly/31IqMl</short_url> <long_url>http://cnn.com/</long_url> <user_hash>31IqMl</user_hash> <global_hash>31IqMl</global_hash> </entry> </data></response>

● txt 形式 http://api.bit.ly/v3/expand?shortUrl=http%3A%2F%2Fbit.ly%2F31IqMl&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&format=txt http://cnn.com/

/v3/validatebit.lyのユーザーログインと apiKeyに対して、そのペアが現在有効かどうかを確認できま

す。引数● format （オプション）レスポンスの形式を指定できます。サポートしている形

式： json （デフォルト）、 xml 、 txt。● x_login ユーザーの bit.lyログイン ID（認証用）。● x_apiKey ユーザーの bit.ly apiKey（認証用）。出力




● valid 0か 1の値により、x_loginと x_apiKeyのペアが現在有効かどうかが示されます。

例● json 形式 http://api.bit.ly/v3/validate?

x_login=notbilytapi&x_apiKey=not_apikey&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&login=bitlyapidemo&format=json { "status_code": 200, "data": { "valid": 0 }, "status_txt": "OK"}

● xml 形式 http://api.bit.ly/v3/validate?x_login=notbilytapi&x_apiKey=not_apikey&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&login=bitlyapidemo&format=xml <?xml version="1.0" encoding="UTF-8"?><response> <status_code>200</status_code> <status_txt>OK</status_txt> <data> <valid>0</valid> </data></response>

● txt 形式 http://api.bit.ly/v3/validate?x_login=notbilytapi&x_apiKey=not_apikey&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&login=bitlyapidemo&format=txt 0

/v3/clicks一つもしくは複数の bit.ly URL及び hashに対して、そのリンクに対するクリックの統計を

呼び出せます。引数● format （オプション）レスポンスの形式を指定できます。サポートしている形

式： json （デフォルト）、 xml 。● shortUrl は一つもしくは複数の bit.ly URL です、（例： http :// bit . ly /1 RmnUT か

http :// j . mp /1 RmnUT ）。● hash は一つもしくは複数の bit.ly hash です、（例： 2bYgqR かカスタム名）。

注意● shortUrlも hash も引数としてリクエストされる必要があります。● shortURL及び hash引数の最高数は１５です。出力● short_url shortUrl リクエスト引数のエコーです。● hash は hash リクエスト引数のエコーです。● user_hash 関連する bit.lyユーザー ID。● global_hash 元URLに対する bit.lyの統括 hashの ID 。● user_clicks 指定されたユーザーの bit.ly リンクへのクリック総数です。● global_clicks 元のURLに対しての bit.ly リンク全体のクリック総数です。● error 特定の shortUrlもしくは hashに対するデータを取得においてエラーが生じた事を意味します。エラーの例は「NOT_FOUND 」。

例




● json 形式 http://api.bit.ly/v3/clicks?shortUrl=http%3A%2F%2Ftcrn.ch%2Fa4MSUH&shortUrl=http%3A%2F%2Fbit.ly%2F1YKMfY&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&hash=j3&hash=a35.&format=json { "status_code": 200, "data": { "clicks": [ { "short_url": "http://tcrn.ch/a4MSUH", "global_hash": "bWw49z", "user_clicks": 0, "user_hash": "a4MSUH", "global_clicks": 1105 }, { "short_url": "http://bit.ly/1YKMfY", "global_hash": "1YKMfY", "user_clicks": 2218, "user_hash": "1YKMfY", "global_clicks": 2218 }, { "hash": "j3", "global_hash": "lLWr", "user_clicks": 105, "user_hash": "j3", "global_clicks": 106 }, { "hash": "a35.", "error": "NOT_FOUND" } ] }, "status_txt": "OK"}

● xml 形式 http://api.bit.ly/v3/clicks?shortUrl=http%3A%2F%2Ftcrn.ch%2Fa4MSUH&shortUrl=http%3A%2F%2Fbit.ly%2F1YKMfY&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&hash=j3&hash=a35.&format=xml <?xml version="1.0" encoding="UTF-8"?><response> <status_code>200</status_code> <data> <clicks> <short_url>http://tcrn.ch/a4MSUH</short_url> <global_hash>bWw49z</global_hash> <user_clicks>0</user_clicks> <user_hash>a4MSUH</user_hash> <global_clicks>1105</global_clicks> </clicks> <clicks> <short_url>http://bit.ly/1YKMfY</short_url>




<global_hash>1YKMfY</global_hash> <user_clicks>2218</user_clicks> <user_hash>1YKMfY</user_hash> <global_clicks>2218</global_clicks> </clicks> <clicks> <user_clicks>105</user_clicks> <global_hash>lLWr</global_hash> <hash>j3</hash> <user_hash>j3</user_hash> <global_clicks>106</global_clicks> </clicks> <clicks> <hash>a35.</hash> <error>NOT_FOUND</error> </clicks> </data> <status_txt>OK</status_txt></response>

/v3/referrers¶特定の bit.ly短縮URLに対してのリファラーサイトと、リファラーあたりのクリック数に関するデータを提供します。パラメータ

● format (optional) リクエストの回答フォーマット. 現状サポートされているフォーマットは jasonと xmlになります。

● shortUrl は bit.lyの短縮URL を意味します。 (e.g.: http :// bit . ly /1 RmnUT or http :// j . mp /1 RmnUT ).

● hash は bit.ly のハッシュ以下の文字列を意味します。(e.g.: 2bYgqR もしくはカスタムの名前).

Note ● shortUrl もしくは hashがパラメータとして指定される必要があります。● このAPI エンドポイントは、APIコールひとつあたり、ひとつの bit.ly短縮URLの

データしか返しません。アウトプット

● short_url これは、shortUrl リクエストパラメータと合致します。● hash hash リクエストパラメータと合致します。● user_hash は bit.ly のユーザーを特定するものです。● global_hash 元URLに対する bit.lyの統括 hashの ID 。● referrer は、bit.ly 短縮URL に対するリファラーサイトです。● referrer_app は、ある特定の bit.ly短縮URLに対するリファラーとなっているア

プリケーション（例： Tweetdeck）です。● url リファラーとなっているアプリケーションのURL です。 ( 例：

http :// tweetdeck . com ). ● clicks はリファラーに対するクリック数です。

例● json フォーマット http://api.bit.ly/v3/referrers?shortUrl=http%3A%2F

%2Fbit.ly%2FdjZ9g4&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&format=json { "data": { "created_by": "bitly",




"global_hash": "djZ9g4", "referrers": [ { "clicks": 42, "referrer": "direct" }, { "clicks": 15, "referrer": "http://twitter.com/" }, { "clicks": 12, "referrer": "http://twitter.com/bitly" }, { "clicks": 8, "referrer_app": "TweetDeck", "url": "http://www.tweetdeck.com/" }, { "clicks": 1, "referrer": "http://bit.ly/a/sidebar" }, { "clicks": 1, "referrer": "http://translate.googleusercontent.com/translate_c" }, { "clicks": 1, "referrer": "http://twitter.com/atul/statuses/26029156685" }, { "clicks": 1, "referrer": "http://twitter.com/home" }, { "clicks": 1, "referrer": "http://untiny.me/" } ], "short_url": "http://bit.ly/djZ9g4", "user_hash": "djZ9g4" }, "status_code": 200, "status_txt": "OK"}

● xml フォーマット http://api.bit.ly/v3/referrers?shortUrl=http%3A%2F%2Fbit.ly%2FdjZ9g4&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&format=xml <?xml version="1.0" encoding="UTF-8"?><response> <status_code>200</status_code> <data> <short_url>http://bit.ly/djZ9g4</short_url>




<global_hash>djZ9g4</global_hash> <user_hash>djZ9g4</user_hash> <created_by>bitly</created_by> <referrers> <referrer>direct</referrer> <clicks>42</clicks> </referrers> <referrers> <referrer>http://twitter.com/</referrer> <clicks>15</clicks> </referrers> <referrers> <referrer>http://twitter.com/bitly</referrer> <clicks>12</clicks> </referrers> <referrers> <url>http://www.tweetdeck.com/</url> <referrer_app>TweetDeck</referrer_app> <clicks>8</clicks> </referrers> <referrers> <referrer>http://bit.ly/a/sidebar</referrer> <clicks>1</clicks> </referrers> <referrers> <referrer>http://translate.googleusercontent.com/translate_c</referrer> <clicks>1</clicks> </referrers> <referrers> <referrer>http://twitter.com/atul/statuses/26029156685</referrer> <clicks>1</clicks> </referrers> <referrers> <referrer>http://twitter.com/home</referrer> <clicks>1</clicks> </referrers> <referrers> <referrer>http://untiny.me/</referrer> <clicks>1</clicks> </referrers> </data> <status_txt>OK</status_txt></response>

/v3/countries¶bit.ly短縮URLのクリックが発生した国名と、国ごとのクリック数に関するデータを提供します。パラメータ






● hash は bit.ly のハッシュ以下の文字列を意味します。(e.g.: 2bYgqR もしくはカスタムの名前)。

Note ● Either shortUrl or hash must be given as a parameter. ● This API endpoint can only provide data for one bit.ly short link per API call.

アウトプット● short_url これは、shortUrl リクエストパラメータと合致します。● hash hash リクエストパラメータと合致します。● user_hash は bit.ly のユーザーを特定するものです。● global_hash 元URLに対する bit.lyの統括 hashの ID 。● countries bit.lyの短縮URL に関するクリックが発生された国の一覧です。● clicks は、各国から発生したクリックの数です。

例● json フォーマット http://api.bit.ly/v3/countries?shortUrl=http%3A%2F

%2Fbit.ly%2FdjZ9g4&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&format=json { "data": { "countries": [ {"clicks": 40, "country": "US"}, {"clicks": 7,"country": null}, {"clicks": 4,"country": "AU"}, {"clicks": 4,"country": "BR"}, {"clicks": 4,"country": "FR"}, {"clicks": 3,"country": "CA"}, {"clicks": 3,"country": "GB"}, {"clicks": 2,"country": "DE"}, {"clicks": 2,"country": "IN"}, {"clicks": 2,"country": "NO"}, {"clicks": 2,"country": "PL"}, {"clicks": 2,"country": "TW"}, {"clicks": 1,"country": "BE"}, {"clicks": 1,"country": "BG"}, {"clicks": 1,"country": "ES"}, {"clicks": 1,"country": "HK"}, {"clicks": 1,"country": "PH"}, {"clicks": 1,"country": "PT"}, {"clicks": 1,"country": "SE"}, {"clicks": 1,"country": "VE"} ], "created_by": "bitly", "global_hash": "djZ9g4", "short_url": "http://bit.ly/djZ9g4", "user_hash": "djZ9g4" }, "status_code": 200, "status_txt": "OK"}

● xml フォーマット http://api.bit.ly/v3/countries?shortUrl=http%3A%2F%2Fbit.ly%2FdjZ9g4&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&format=xml




<?xml version="1.0" encoding="UTF-8"?><response> <status_code>200</status_code> <data> <short_url>http://bit.ly/djZ9g4</short_url> <global_hash>djZ9g4</global_hash> <user_hash>djZ9g4</user_hash> <created_by>bitly</created_by> <countries><country>US</country><clicks>40</clicks></countries> <countries><country/><clicks>7</clicks></countries> <countries><country>AU</country><clicks>4</clicks></countries> <countries><country>BR</country><clicks>4</clicks></countries> <countries><country>FR</country><clicks>4</clicks></countries> <countries><country>CA</country><clicks>3</clicks></countries> <countries><country>GB</country><clicks>3</clicks></countries> <countries><country>DE</country><clicks>2</clicks></countries> <countries><country>IN</country><clicks>2</clicks></countries> <countries><country>NO</country><clicks>2</clicks></countries> <countries><country>PL</country><clicks>2</clicks></countries> <countries><country>TW</country><clicks>2</clicks></countries> <countries><country>BE</country><clicks>1</clicks></countries> <countries><country>BG</country><clicks>1</clicks></countries> <countries><country>ES</country><clicks>1</clicks></countries> <countries><country>HK</country><clicks>1</clicks></countries> <countries><country>PH</country><clicks>1</clicks></countries> <countries><country>PT</country><clicks>1</clicks></countries> <countries><country>SE</country><clicks>1</clicks></countries> <countries><country>VE</country><clicks>1</clicks></countries> </data> <status_txt>OK</status_txt></response>

/v3/clicks_by_minute¶１つ以上の bit.ly短縮URLに対して、最後の一時間の分刻みのデータを提供します。（最新の時間から順番となります）パラメータ



● hash は bit.ly のハッシュ以下の文字列を意味します。(e.g.: 2bYgqR もしくはカスタムの名前).

Note ● shortUrl もしくは hashがパラメータとして指定される必要があります。● shortUrl と hashがパラメータの最大数は１５です。

アウトプット

● short_url これは、shortUrl リクエストパラメータと合致します。● hash hash リクエストパラメータと合致します。● user_hash は bit.ly のユーザーを特定するものです。● global_hash 元URLに対する bit.lyの統括 hashの ID 。● clicks は、特定の bit.ly短縮URL に対する分ごとのクリック数です。

例




● json フォーマット http://api.bit.ly/v3/clicks_by_minute?shortUrl=http%3A%2F%2Fj.mp%2F9DguyN&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&format=json { "data": { "clicks_by_minute": [ { "clicks": [0,0,0,0,2,2,4,3,1,0,1,0,2,0,0,0,1,1,0,0,2,1,1,3,1,2,1,1,0,1,1,0,1,1,1,0,1,1,1,0,2,3,1,1,3,2,0,3,3,2,2,1,3,3,2,1,0,4,0,2,1], "global_hash": "9DguyN", "short_url": "http://j.mp/9DguyN", "user_hash": "9DguyN" } ] }, "status_code": 200, "status_txt": "OK"}

● xml フォーマット http://api.bit.ly/v3/clicks_by_minute?shortUrl=http%3A%2F%2Fj.mp%2F9DguyN&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&format=xml <?xml version="1.0" encoding="UTF-8"?><response> <status_code>200</status_code> <data> <clicks_by_minute> <short_url>http://j.mp/9DguyN</short_url> <global_hash>9DguyN</global_hash> <user_hash>9DguyN</user_hash> <clicks>0</clicks> <clicks>0</clicks> <clicks>0</clicks> <clicks>0</clicks> <clicks>2</clicks> <clicks>2</clicks> <clicks>4</clicks> <clicks>3</clicks> <clicks>1</clicks> <clicks>0</clicks> <clicks>1</clicks> <clicks>0</clicks> <clicks>2</clicks> <clicks>0</clicks> <clicks>0</clicks> <clicks>0</clicks> <clicks>1</clicks> <clicks>1</clicks> <clicks>0</clicks> <clicks>0</clicks> <clicks>2</clicks> <clicks>1</clicks>




<clicks>1</clicks> <clicks>3</clicks> <clicks>1</clicks> <clicks>2</clicks> <clicks>1</clicks> <clicks>1</clicks> <clicks>0</clicks> <clicks>1</clicks> <clicks>1</clicks> <clicks>0</clicks> <clicks>1</clicks> <clicks>1</clicks> <clicks>1</clicks> <clicks>0</clicks> <clicks>1</clicks> <clicks>1</clicks> <clicks>1</clicks> <clicks>0</clicks> <clicks>2</clicks> <clicks>3</clicks> <clicks>1</clicks> <clicks>1</clicks> <clicks>3</clicks> <clicks>2</clicks> <clicks>0</clicks> <clicks>3</clicks> <clicks>3</clicks> <clicks>2</clicks> <clicks>2</clicks> <clicks>1</clicks> <clicks>3</clicks> <clicks>3</clicks> <clicks>2</clicks> <clicks>1</clicks> <clicks>0</clicks> <clicks>4</clicks> <clicks>0</clicks> <clicks>2</clicks> <clicks>1</clicks> </clicks_by_minute> </data> <status_txt>OK</status_txt></response>

/v3/bitly_pro_domainこのクエリーでは特定のショートドメインが bitly.Pro用にすで登録されているかを確認できます、このクエリーを用いてその他 apiコール用に有効な shortUrl引数かどうかを確認できます。尚、bitly.Pro のドメインは１４文字以内に制限されています。

引数● domain ショートドメイン（nyti.ms 等）。● format （オプション）レスポンスの形式を指定できます。サポートしている形

式： json （デフォルト）、 xml。出力




● bitly_pro_domain 0か 1で現在 bitly.Pro のドメインか示されます。● domain リクエスト引数のエコーです。

例● json 形式 http://api.bit.ly/v3/bitly_pro_domain?

domain=nyti.ms&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&login=bitlyapidemo&format=json { "status_code": 200, "data": { "domain": "nyti.ms", "bitly_pro_domain": 1 }, "status_txt": "OK"}

● xml 形式 http://api.bit.ly/v3/bitly_pro_domain?domain=nyti.ms&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&login=bitlyapidemo&format=xml <?xml version="1.0" encoding="UTF-8"?><response> <status_code>200</status_code> <data> <domain>nyti.ms</domain> <bitly_pro_domain>1</bitly_pro_domain> </data> <status_txt>OK</status_txt></response>

/v3/lookup特定の元URLに対する bit.lyリンクをクエリーするために使用できます。例えば特定の元URｌから/v3/lookupのあとに/v3/clicks を利用してクリックデータ等を引き出せます。

引数● url 一つもしくは複数の元URL ● format （オプション）レスポンスの形式を指定できます。サポートしている形

式： json （デフォルト）、 xml。注意● url引数の上限は 15 です。出力● url url引数のエコー。● short_url 関連 bit.ly 短縮リンク。

例● json 形式 http://api.bit.ly/v3/lookup?url=http%3A%2F%2Fbetaworks.com

%2F&url=http%3A%2F%2Fcode.google.com%2Fp%2Fbitly-api%2F&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&format=json { "data": { "lookup": [ { "global_hash": "beta", "short_url": "http://bit.ly/beta", "url": "http://betaworks.com/" },




{ "global_hash": "1oDCU", "short_url": "http://bit.ly/1oDCU", "url": "http://code.google.com/p/bitly-api/" } ] }, "status_code": 200, "status_txt": "OK"}

● xml 形式 http://api.bit.ly/v3/lookup?url=http%3A%2F%2Fbetaworks.com%2F&url=http%3A%2F%2Fcode.google.com%2Fp%2Fbitly-api%2F&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&format=xml <?xml version="1.0" encoding="UTF-8"?><response> <status_code>200</status_code> <data> <lookup> <url>http://betaworks.com/</url> <short_url>http://bit.ly/beta</short_url> <global_hash>beta</global_hash> </lookup> <lookup> <url>http://code.google.com/p/bitly-api/</url> <short_url>http://bit.ly/1oDCU</short_url> <global_hash>1oDCU</global_hash> </lookup> </data> <status_txt>OK</status_txt></response>

● json 形式 http://api.bit.ly/v3/lookup?url=asdf%3A%2F%2Fwww.google.com%2Fnot%2Fa%2Freal%2Flink&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&format=json { "data": { "lookup": [ { "error": "NOT_FOUND", "url": "asdf://www.google.com/not/a/real/link" } ] }, "status_code": 200, "status_txt": "OK"}

● xml 形式 http://api.bit.ly/v3/lookup?url=asdf%3A%2F%2Fwww.google.com%2Fnot%2Fa%2Freal%2Flink&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&format=xml <?xml version="1.0" encoding="UTF-8"?><response> <status_code>200</status_code>




<data> <lookup> <url>asdf://www.google.com/not/a/real/link</url> <error>NOT_FOUND</error> </lookup> </data> <status_txt>OK</status_txt></response>

/v3/authenticate特定のユーザーの bit.lyユーザー名及びパスワードを元に bit.ly API keyを探し出すために利

用できます。このエンドポイントへのアクセスは制限されており、アクセスのリクエストは [email protected]

宛にメールする必要があります。アクセスをリクエストする際には、アプリケーションのログイン ID及び apiKey、利用方法、そしてリクエストの想定ボリュームも一緒にお送りくだ

さい。引数● x_login ユーザーの bit.ly ユーザー名もしくはメールアドレス。● x_password ユーザーの bit.lyパスワード。● format （オプション）レスポンスの形式を指定できます。サポートしている形

式： json （デフォルト）、 xml。注意● このリクエストはHTTP POSTしか使えません、HTTP GETのリクエストは受け付け

ていません。出力● successful はログイン・パスワードの組み合わせが有効かどうかを表示します。● username は指定された bit.ly ユーザーのユーザー名です。● api_key は指定された bit.lyユーザーの apiKey です。

例● json 形式 http://api.bit.ly/v3/authenticate

POST: x_login=bitlyapidemo&x_password=bad-password&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&login=bitlyapidemo&format=json { "data": { "authenticate": { "successful": false } }, "status_code": 200, "status_txt": "OK"}

● xml 形式 http://api.bit.ly/v3/authenticate POST: x_login=bitlyapidemo&x_password=bad-password&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&login=bitlyapidemo&format=xml <?xml version="1.0" encoding="UTF-8"?><response> <status_code>200</status_code> <data> <authenticate> <successful>0</successful>




</authenticate> </data> <status_txt>OK</status_txt></response>

● json 形式 http://api.bit.ly/v3/authenticate POST: x_login=bitlyapidemo&x_password=good-password&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&login=bitlyapidemo&format=json { "data": { "authenticate": { "api_key": "R_0da49e0a9118ff35f52f629d2d71bf07", "successful": true, "username": "bitlyapidemo" } }, "status_code": 200, "status_txt": "OK"}

● xml 形式 http://api.bit.ly/v3/authenticate POST: x_login=bitlyapidemo&x_password=good-password&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&login=bitlyapidemo&format=xml <?xml version="1.0" encoding="UTF-8"?><response> <status_code>200</status_code> <data> <authenticate> <username>bitlyapidemo</username> <successful>1</successful> <api_key>R_0da49e0a9118ff35f52f629d2d71bf07</api_key> </authenticate> </data> <status_txt>OK</status_txt></response>

/v3/info特定の bit.ly リンクのページタイトルを引き出すために使用します。

引数● format （オプション）レスポンスの形式を指定できます。サポートしている形

式： json （デフォルト）、 xml 、 txt。● shortUrl は一つもしくは複数の bit.ly URL です、（例： http :// bit . ly /1 RmnUT か

http :// j . mp /1 RmnUT ）。● hash は一つもしくは複数の bit.ly hash です、（例： 2bYgqR かカスタム名）。注意● shortUrlも hash も引数としてリクエストされる必要があります。● shortURL及び hash引数の最高数は１５です。出力● short_url shortUrl リクエスト引数のエコーです。● hash は hash リクエスト引数のエコーです。● user_hash 関連する bit.lyユーザー ID。● global_hash 元URLに対する bit.lyの統括 hashの ID 。




● error 特定の shortUrlもしくは hashに対するデータを取得においてエラーが生じた事を意味します。エラーの例は「NOT_FOUND 」。

● title リンク先ページのHTML page title （存在する場合）。● created_by この linkを最初に短縮した bit.ly のユーザー名

例● json 形式 http://api.bit.ly/v3/info?shortUrl=http%3A%2F%2Ftcrn.ch

%2Fa4MSUH&shortUrl=http%3A%2F%2Fbit.ly%2F1YKMfY&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&hash=j3&hash=a.35&format=json { "data": { "info": [ { "created_by": "scotster", "global_hash": "lLWr", "hash": "j3", "title": null, "user_hash": "j3" }, { "error": "NOT_FOUND", "hash": "a.35" }, { "created_by": "j3h14h", "global_hash": "bWw49z", "short_url": "http://tcrn.ch/a4MSUH", "title": "Windows Mobile Finally Checks Out Foursquare", "user_hash": "a4MSUH" }, { "created_by": "bitly", "global_hash": "1YKMfY", "short_url": "http://bit.ly/1YKMfY", "title": null, "user_hash": "1YKMfY" } ] }, "status_code": 200, "status_txt": "OK"}

● xml 形式 http://api.bit.ly/v3/info?shortUrl=http%3A%2F%2Ftcrn.ch%2Fa4MSUH&shortUrl=http%3A%2F%2Fbit.ly%2F1YKMfY&login=bitlyapidemo&apiKey=R_0da49e0a9118ff35f52f629d2d71bf07&hash=j3&hash=a.35&format=xml <?xml version="1.0" encoding="UTF-8"?><response> <status_code>200</status_code> <data> <info> <global_hash>lLWr</global_hash> <hash>j3</hash> <user_hash>j3</user_hash>




<created_by>scotster</created_by> <title/> </info> <info> <hash>a.35</hash> <error>NOT_FOUND</error> </info> <info> <short_url>http://tcrn.ch/a4MSUH</short_url> <global_hash>bWw49z</global_hash> <user_hash>a4MSUH</user_hash> <created_by>j3h14h</created_by> <title>Windows Mobile Finally Checks Out Foursquare</title> </info> <info> <short_url>http://bit.ly/1YKMfY</short_url> <global_hash>1YKMfY</global_hash> <user_hash>1YKMfY</user_hash> <created_by>bitly</created_by> <title/> </info> </data> <status_txt>OK</status_txt></response>

/oauth/access_token¶このエンドポイントで、OAuth アクセストークンを入手出来ます。OAuth アプリケーションを登録するには、api @ bit . ly （英語）もしくは、bitly @ orinoco . jp （日本語）へご連絡下さい。

OAuth Web flow のパラメータ● client_id あなたのアプリケーションの bit.ly client id です。● client_secret は、あなたのアプリケーションの bit.ly client secretです。● code は、OAuthのウェブ認証プロトコールによって獲得されたOAuth 認証コード

です。● redirect_uri は、ユーザーが認証後にリダイレクトされたページのURL です。

OAuth XAuthのパラメータ ● client_id あなたのアプリケーションの bit.ly client id です。● client_secret は、あなたのアプリケーションの bit.ly client secretです。● x_auth_username は、XAuth 認証のみのエンドユーザーの bit.lyユーザー名で

す。● x_auth_password は、XAuth 認証のみのエンドユーザーの bit.lyパスワードです。

Note ● HTTP POST リクエストである必要があります。● このエンドポイントは、こちらのURLからのみアクセスかのうです。https://api-

ssl.bit.ly/ ● x_auth_username と x_auth_password は、ウェブでのリダイレクトが出来なかった時にのみ使われます。（例えば、ブラウザーレイヤーの無いモバイルアプリ）

● 注：XAuthを利用した認証については、api＠bit.ly宛にアクセスの申請を行って下さい。（日本語で申請ご希望の場合は、bitly @ orinoco . jp までご連絡下さい。）

アウトプットaccess_token=%s&login=%s&apiKey=%s フォーマットでURLエンコードされたストリ

ング




● access_token は、特定のユーザーへのOAuth アクセストークン● login は、エンドユーザーの bit.ly ユーザー名● apiKey は、エンドユーザーの bit.ly API キー

/v3/user/clicks¶一日あたりのユーザーの bit.ly短縮URLに関するトータルのクリック数を提供するOAuth 2 エンドポイントです。パラメータ

● access_token は、特定のユーザーへのOAuth アクセストークン● days (optional) さかのぼってデータを取得する日数の整数(最新から逆算で) (最小:1, 最大:30, でフォルト:7)。

● format (optional) はリクエストされたレスポンスのフォーマットです。サポートされているフォーマットは、json (default)と xmlになります。

注● このエンドポイントは、 https://api-ssl.bit.ly/ でのみ利用可能です● 結果は最新から順に返されます。

アウトプット● clicks その日のトータルのクリック数です。

/v3/user/referrers¶特定のユーザーの bit.ly短縮URLに対してのトップリファラー（最大１日５００件）と、リファラーあたりのクリック数に関するデータを提供するOAuth 2エンドポイントです。

パラメータ● access_token は、特定のユーザーへのOAuth アクセストークン● days (optional) さかのぼってデータを取得する日数の整数(最新から逆算で) (最小:1, 最大:30, でフォルト:7)。



アウトプット● referrers 最大５００件とする、その日のトップリファラーのリスト● clicks その日の特定のリファラーに対するクリック数

/v3/user/countries¶bit.lyユーザーの短縮URLへののクリックが発生した国名と、国ごとのクリック数に関するデータを提供するOAuth 2のエンドポイントです。

パラメータ● access_token は、特定のユーザーへのOAuth アクセストークン● days (optional) さかのぼってデータを取得する日数の整数(最新から逆算で) (最小:1, 最大:30, でフォルト:7)。



アウトプット● countries bit.lyの短縮URLに関するクリックが発生された国の一覧です。● clicks は、各国から発生したクリックの数です。




/v3/user/realtime_links¶過去１時間のトラフィックやリンクに対するクリック数によって、あるユーザーの最も人気の１００のリンクを提供するOAuth2 エンドポイント。パラメータ

● access_token は、特定のユーザーへのOAuth アクセストークン● days (optional) さかのぼってデータを取得する日数の整数(最新から逆算で) (最小:1, 最大:30, でフォルト:7)。


注● このエンドポイントは、 https://api-ssl.bit.ly/ でのみ利用可能です● このエンドポイントは最大１００件の結果を返します。

アウトプット● clicks は、過去１時間のクリック数です。● user_hash は、対応する bit.ly user link identifier です。




Documents

bit.ly APIに関する説明資料