TwitterAPI.js2009-04-13

【2010-06-17 追記】
従来と同じ使い方のまま OAuth に対応した、TwitterAPI2.js を公開しました。
下記、TwitAPI.js に対するラッパになります。
詳細は、TwitterAPI2.js を参照して下さい。
【2010-06-12 追記】OAuth 対応版を公開しました
まだ完成度は低いですが、基本的な動作は可能になったので公開しました。インターフェースなどが変更になっていますが、基本的な使用感は変わりません。
TwitAPI.js

現状の TwitterAPI.js は 2010-06-30 2010-08-31 をもって利用できなくなります。
Twitter の BASIC 認証による API 提供が、6月末に終了することが正式発表され、BASIC 認証を利用している現状の TwitterAPI.js はそれと同時に利用できなくなります。TwitterAPI.js の OAuth への対応も検討していますが、現時点での予定は未定です。
従って、これから新しく何かを作成するのに、TwitterAPI.js を選択するのはお勧めしません。Twitter 公式の JavaScript ライブラリ @anywhere も、開発者向けに公開されているので、あわせてご検討下さい。
【追記】
BASIC 認証が不要な API については、7 月以降も TwitterAPI.js でそのまま利用可能な可能性もありますが、現時点では不明です。
【追記】
移行期限を 8 月 16 日まで延長し、8 月 31 日にかけて段階的に終了することがアナウンスされました。

»Download

»Download (Ver 0.9.2)

概要

Twitter の API を JavaScript から簡単に使うためのライブラリです。 上部の Download リンクより、js ファイルをダウンロードして読み込む事で様々なメソッドが利用可能になります。

<script type="text/javascript" src="js/twitterapi_x.x.x.js"></script>

特徴

• Pure JS 実装なのでサーバサイドが不要
• クロスドメイン対策を内部に隠蔽
• API に存在するメソッドをそのまま JavaScript のメソッドとして実装
• コールバック関数として、関数オブジェクトをそのまま渡せる
• 外部の JS ライブラリに依存していない
• 非圧縮で 7KB と軽めの実装
• ブラウザによる BASIC 認証で動作する
• 利用ページのエンコードが UTF-8 でない事による文字化けを回避 (Ver 0.9.3～)
• POST メソッド使用時のコールバック関数にも一部対応 (Ver 0.9.3～)
• 入力済みの BASIC 認証の再ログインを一部サポート (Ver 0.9.3～)

バージョン

まだ枯れているとは言い難いので、現在のバージョンは 0.9.4 です。 不具合がありましたら、コメントなどでお知らせ下さい。

サンプル

TwitterAPI.js を使うと、例えば以下のような事が出来ます。 以下のサンプルを最初に動作させた時は、ブラウザによる BASIC 認証のダイアログが立ち上がるので、Twitter のアカウントで認証して下さい。

≪Twitter で発言する≫

<script type="text/javascript">
  function post(f) {
    var status = f.status.value;
    TwitterAPI.statuses.update(status);
  }
</script>
：
<form>
<input type="text" name="status" style="width:300px" /><input type="button" onclick="post(this.form);" value="UPDATE" />
</form>

≪特定のユーザのタイムラインを取得する≫

<script type="text/javascript">
  function callback(arr) {
    var str = '';
    for (var i=0; i<arr.length; i++) {
      var obj = arr[i];
      str += obj.user.screen_name + ':' + obj.text + '<br />';
    }
    document.getElementById('result').innerHTML = str;
  }
  function getTl() {
    var id = document.getElementById('id').value;
    var param = 'count=10';
    TwitterAPI.statuses.user_timeline(callback, id, param);
  }
</script>
：
<form>
ID <input type="text" id="id" /><input type="button" onclick="getTl();" value="GET TL" />
<div id="result" style="height: 200px; overflow: auto; border: 1px solid #999; background: #ffe;"></div>
</form>

ID 

ここに結果が表示される

API ドキュメント

基本的には本家の API ドキュメントの記述をほぼそのまま使用する事が出来ます。
TwitterAPI.js を使用する場合の基本的な書き方は以下のような形です。

TwitterAPI.MethodName(callback, id, params);

このように書くと、MethodName に該当する同一名の API が実行され、callback で指定した関数に、結果の JSON オブジェクトが渡されます。
Twitter API については、日本語訳を公開して下さっている方がいるので参考にして下さい。
Twitter API 仕様書 (勝手に日本語訳シリーズ)

例えば、サンプルで使用した特定のユーザのタイムラインを取得するメソッドですが、Twitter API だと、以下のような URL です。

http://twitter.com/statuses/user_timeline/id.format?param

これに対応したメソッドは、以下のようになります。(format は json で固定)

TwitterAPI.statuses.user_timeline(callback, id, param)

このように、ほぼ全ての API はそれと同名の専用のメソッドが用意されています。
従って、TwitterAPI.js で使えるメソッドのドキュメントとしては、Twitter API のドキュメントをそのまま参照して下さい。
また、callback に何も指定しなければ、実行結果はそのまま捨てられ、id、param を設定しても無効な API の場合、それらの値は無視されます。

ただし、一部のメソッドには例外があります。以下ではその例外について説明します。

追加されたメソッド

TwitterAPI.users.own(callback, id, param);    // Ver 0.9.2～ 

元々の API には、ユーザデータを取得する http://twitter.com/users/show/id.format という API があり、id を指定しない事で自分自身のデータを取得する事が期待されるのですが、実際には id を指定しないとエラーになってしまいます。
そのため、TwitterAPI.js では、認証されたユーザ自身のデータを取得するためのメソッドを追加しました。

TwitterAPI.relogin();    // Ver 0.9.3～ 

通常、BASIC 認証による認証情報はブラウザ内に保持され、ブラウザを完全に終了するまで任意に書き換えられません。つまり一度ログインするとログアウト出来ないのが普通です。
そのブラウザの動作に対して、あえて偽情報を送り込む事で再認証のためのダイアログを発生させ、再ログインを実現するためのメソッドです。
ただ、セキュリティ的な制限から IE7 では動作しない事を確認しています。恐らく、IE8 でも同様です。
今後のアップデートにより、Firefox や Chrome でも使用出来なくなる可能性があるので、利用には注意を払って下さい。

名前が異なるメソッド

JavaScript の命名ルールの問題から、Twitter API と同じ名称を使用する事が出来なかったものがいくつかあります。
下記の API については別名のメソッドを呼び出して下さい。

// http://twitter.com/direct_messages.format
TwitterAPI.direct_messages.show(func, id, param);

// http://twitter.com/direct_messages/new.format
TwitterAPI.direct_messages.create(user, text);

// http://twitter.com/favorites.format
TwitterAPI.favorites.show(func, id, param);

// http://blocks/blocking.format
TwitterAPI.blocks.blocking.show(func, id, param);

動作が特殊なメソッド

以下のメソッドについては、情報の取得ではなく情報の送信 (POST) を行うためのメソッドであり、JavaScript の技術的制約から、結果を受け取る事が出来ません。
情報の送信にあたっては特別な処理を行うため、メソッドの呼び出し方も専用のものになっています。
また、実行結果を受け取る事は出来ませんが、Ver 0.9.3 より、任意のコールバック関数を実行出来るようになりました。POST 処理完了のタイミングで、コールバック関数が呼び出されます。
ただし、コールバック関数が有効に機能するのは IE 以外のブラウザです。その点には留意して利用して下さい。

TwitterAPI.statuses.update(status, func);
TwitterAPI.direct_messages.create(user, text, func);
TwitterAPI.account.update_location(location, func);

コールバック関数が対応ブラウザでしか動作しない事と、指定できる引数が固定されている点が他のメソッドと大きく異なりますが、その動作については同名の Twitter API と同じ動作をします。
動作の詳細については、API ドキュメントを参照して下さい。

さらに、以下のメソッドについては呼び出し方は他と同様であるものの、やはり情報の送信 (POST) を行うため、結果をコールバック関数で受け取る事が出来ません。
結果自体を受け取る事は出来ませんが、コールバック関数を指定した場合、対応ブラウザでは POST 処理完了時に呼び出されます。

friendships.create(func, id, param);
friendships.destroy(func, id, param);
favorites.create(func, id, param);
favorites.destroy(func, id, param);
blocks.create(func, id, param);
blocks.destroy(func, id, param);

除外したメソッド

以下のメソッドについては、使用頻度が低いと思われる事から実装を見送りました。
どうしても必要であれば、ソースを参照の上で、任意に追加して下さい。メソッドの追加自体は、JavaScript の文法を理解していればシンプルに出来るかと思います。

• trends 系メソッド
• saved_searches 系メソッド
• oauth 系メソッド
• report_spam 系メソッド

動作条件・制限事項・ライセンス

下記のブラウザで動作確認しています。
IE6 / IE7 / Firefox2 (～Ver 0.9.2) / Firefox3 / Firefox3.5 / Firefox3.6 / Chrome (Ver 0.9.3～)
未確認ですが、IE8 / Safari / Opera あたりでもそのまま動作すると思われます。

情報を送信するメソッドを使用する場合、JavaScript を実行している HTML が UTF-8 で書かれていないと、日本語が文字化けします。
POST メソッド使用時、元のページのエンコードにかかわらず、UTF-8 に変換して送信されるため、日本語の文字化けは発生しません。(Ver 0.9.3～)
※Chrome を除く。Chrome ではスクリプトで生成した iframe の文字コードが元の charset を引き継ぐ使用となっているためです(その他のブラウザはデフォルトで UTF-8)。charset を指定して iframe を生成する方法が分からないため、現状で対応出来ていません。

ライセンスは MIT License (日本版 wikipedia の項) で公開します。

更新履歴

Ver.0.9.4 [2010-01-26]

Firefox 3.6 に対応

エスケープの不具合を修正

Ver.0.9.3 [2009-11-02]

全面書き直し (コード最適化により機能増・容量減を達成)

API を最新に追随 Twitter API Documentation

search 系のメソッドを追加

TwitterAPI.relogin を追加

Ver.0.9.2 [2009-05-03]

TwitterAPI.users.own を追加

Ver.0.9.1 [2009-04-13]

TwitterAPI.friends.ids を追加

TwitterAPI.followers.ids

数値の ID を渡した時の不具合を修正

POST で実行しないといけない API を一部 GET で実行していた不具合を修正

Ver.0.9.0 [2009-03-19]

初公開