Twitter API 仕様書 日本語訳: tsupo (http://watcher.moe-nifty.com/ mailto:tsupo@na.rim.or.jp) http://groups.google.com/group/twitter-development-talk/web/api-documentation の2007年6月13日版の大雑把な日本語訳 (ただし、そのまま翻訳したわけではなく、一部、意訳。また、現時点の実装状況に合わせて、内容を修正している) ステータス関連のAPI public_timeline 公開(かつ、自分のアイコンを設定済みの)ユーザの最新のステータス(発言)を取得する (最大20件) この API のみ BASIC認証は不要 URL: http://twitter.com/statuses/public_timeline.format (format は xml, json, rss, atom のうちのいずれかを指定) 引数: since_id=ステータスID (オプション) 指定したIDより大きな値のIDのステータスのみ取得する 例: http://twitter.com/statuses/public_timeline.xml?since_id=12345 ステータスID 12345 以降に update されたステータス(のうち、古いものから順に最大20件)を XML 形式で取得する friends_timeline 自分の friend の過去24時間以内に update されたステータスから最大20件を取得する。 引数 id を指定すれば、その id のユーザの friend のステータスを取得できる URL: http://twitter.com/statuses/friends_timeline.format http://twitter.com/statuses/friends_timeline/id.format (format は xml, json, rss, atom のうちのいずれかを指定) 引数: id=ユーザID または id=スクリーン名 (オプション) 指定した ID またはスクリーン名のユーザの friend のステータスを取得する (この引数を指定しない場合は、自分の friend のステータスを取得する) 例: http://twitter.com/statuses/friends_timeline/12345.xml ユーザID 12345 の friend のステータスを XML 形式で取得する http://twitter.com/statuses/friends_timeline/bob.json スクリーン名 bob の friend のステータスを JSON 形式で取得する since=日時 (オプション) 指定した日時以降に update されたステータスを取得する 日時のフォーマットは RFC822(の「5. 日付と時刻仕様」 = RFC2822 の 3.) に従う なお、本オプションの代わりに http リクエストヘッダで If-Modified-Since を明示することで、日時を指定することもできる 例: http://twitter.com/statuses/friends_timeline.rss?since=Tue%2C+27+Mar+2007+22%3A55%3A48+GMT 2007年3月27日22時55分48秒GMT以降に update されたステータスを RSS 形式で取得する 訳者による注記: Twitter に login 中であれば、BASIC 認証なしで GET できる user_timeline 自分の過去24時間以内に update されたステータスから最大20件を取得する。 引数 id を指定すれば、その id のユーザのステータスを取得できる URL: http://twitter.com/statuses/user_timeline.format http://twitter.com/statuses/user_timeline/id.format (format は xml, json, rss, atom のうちのいずれかを指定) 引数: id=ユーザID または id=スクリーン名 (オプション) 指定した ID またはスクリーン名のユーザのステータスを取得する (この引数を指定しない場合は、自分のステータスを取得する) 例: http://twitter.com/statuses/user_timeline/12345.xml ユーザID 12345 のステータスを XML 形式で取得する http://twitter.com/statuses/user_timeline/bob.json スクリーン名 bob のステータスを JSON 形式で取得する count=件数 (オプション) 指定した件数分、ステータスを取得する。ただし、20 より大きな値は指定できない 例: http://twitter.com/statuses/user_timeline.xml?count=5 自分のステータスのうち最新の5件を XML 形式で取得する since=日時 (オプション) 指定した日時以降に update されたステータスを取得する 日時のフォーマットは RFC822(の「5. 日付と時刻仕様」) に従う なお、本オプションの代わりに http リクエストヘッダで If-Modified-Since を明示することで、日時を指定することもできる 例: http://twitter.com/statuses/user_timeline.rss?since=Tue%2C+27+Mar+2007+22%3A55%3A48+GMT 2007年3月27日22時55分48秒GMT以降に update されたステータスを RSS 形式で取得する 訳者による注記: Twitter に login 中であれば、BASIC 認証なしで GET できる show 指定した ID のステータス(1件)を取得する URL: http://twitter.com/statuses/show/id.format (format は xml, json のうちのいずれかを指定) 引数: id=ステータスID (必須) 指定した ID のステータスを取得する 例: http://twitter.com/statuses/show/123.xml ステータスID 123 に関する情報を XML 形式で取得する 訳者による注記: Twitter に login 中であれば、BASIC 認証なしで GET できる update 自分のステータスを更新(update)する。引数 status は必須。 この API は必ず POST を使って発行すること。update が成功した場合は、format で指定した形式で応答が返る URL: http://twitter.com/statuses/update.format (format は xml, json のうちのいずれかを指定) 引数: status=ステータス (必須) ステータス(発言、投稿内容)を指定する。必ず URL エンコードすること。 ステータスは 160バイト以内におさめること。ただし、140バイトを超えた部分は必ずしも表示される保証はない。 訳者による注記: 2007年4月はじめごろまでは GET でも構わなかった。現在は、GET は使えなくなっている replies 自分に対する返信(冒頭が @ユーザ名 で始まるステータス)の一覧を取得する (最大20件) なお、現時点では、自分が他のユーザに対して行なった返信の一覧を取得する API は用意されていない。 URL: http://twitter.com/statuses/replies.format (format は xml, json, rss, atom のうちのいずれかを指定) 訳者による注記: Twitter に login 中であれば、BASIC 認証なしで GET できる destroy ステータスを削除する。ステータスIDの指定は必須。 削除が成功した場合は、format で指定した形式で応答が返る URL: http://twitter.com/statuses/destroy/id.format (format は xml, json のうちのいずれかを指定) 引数: id=ステータスID (必須) 削除したいステータスのIDを指定する 例: http://twitter.com/statuses/destroy/12345.json ステータスID 12345 のダイレクトメッセージを削除し、実行結果を JSON 形式で受け取る http://twitter.com/statuses/destroy/23456.xml ステータスID 23456 のダイレクトメッセージを削除し、実行結果を XML 形式で受け取る ユーザ情報関連のAPI friends 自分の friend の一覧を(各 friend の最新ステータス付きで)取得する 引数 id を指定すれば、その id のユーザの friend の一覧を取得できる URL: http://twitter.com/statuses/friends.format (format は xml, json, rss, atom のうちのいずれかを指定) 引数: id=ユーザID または id=スクリーン名 (オプション) 指定した ID またはスクリーン名のユーザの friend のステータスを取得する (この引数を指定しない場合は、自分の friend のステータスを取得する) 例: http://twitter.com/statuses/friends/12345.json ユーザID 12345 の friend の一覧を JSON 形式で取得する http://twitter.com/statuses/friends/bob.rss スクリーン名 bob の friend の一覧を XML 形式で取得する 訳者による注記: Twitter に login 中であれば、BASIC 認証なしで GET できる followers 自分の follower の一覧を(各 follower の最新ステータス付きで)取得する 引数 id を指定すれば、その id のユーザの follower の一覧を取得できる URL: http://twitter.com/statuses/followers.format (format は xml, json, rss, atom のうちのいずれかを指定) featured 現在、Twitter に login 中のユーザの一覧を(最新ステータス付きで)取得する(最大20人分) URL: http://twitter.com/statuses/featured.format (format は xml, json のうちのいずれかを指定) 訳者による注記: Twitter に login 中であっても、BASIC 認証でのアクセスが要求される show 指定ユーザに関する詳細な情報を取得する。 ただし、指定ユーザが自分の friend でない場合、この API の実行は失敗する("You are not authorized to see this user." という応答が返る)。 URL: http://twitter.com/users/show/id.format (format は xml, json のうちのいずれかを指定) 引数: id=ユーザID または id=スクリーン名 (必須) 情報取得対象となるユーザを指定する 例: http://twitter.com/users/show/12345.json ユーザID 12345 の情報を JSON 形式で取得する http://twitter.com/users/show/bob.xml スクリーン名 bob の情報を XML 形式で取得する 応答: XML の場合 ユーザID ユーザの名前 ユーザのスクリーン名 ユーザの居住地 ユーザの自己紹介 プロフィールアイコンURL ユーザのWebページURL プロフィールをprotectしているか否か プロフィールの背景の色 プロフィールのテキストの色 プロフィールのリンクの色 サイドバーの背景の色 サイドバーの border の色 friend の数 follower の数 favourite の数 ステータス数 ステータス更新日時 ステータスID ステータス ダイレクトメッセージ関連のAPI direct_messages 自分宛てのダイレクトメッセージの一覧を取得する URL: http://twitter.com/direct_messages.format (format は xml, json, rss, atom のうちのいずれかを指定) 引数: since=日時 (オプション) 指定した日時以降に届いたダイレクトメッセージを取得する 日時のフォーマットは RFC822(の「5. 日付と時刻仕様」) に従う なお、本オプションの代わりに http リクエストヘッダで If-Modified-Since を明示することで、日時を指定することもできる 例: http://twitter.com/direct_messages.atom?since=Tue%2C+27+Mar+2007+22%3A55%3A48+GMT 2007年3月27日22時55分48秒GMT以降に届いたダイレクトメッセージを ATOM 形式で取得する 応答: XML の場合 メッセージID メッセージ本文 送信者ID 受信者ID 送信日時 送信者スクリーン名 受信者スクリーン名 …… new ダイレクトメッセージを送信する。宛先と本文の指定は必須。 この API は必ず POST を使って発行すること。送信が成功した場合は、format で指定した形式で応答が返る URL: http://twitter.com/direct_messages/new.format (format は xml, json, rss, atom のうちのいずれかを指定) 引数: user=ユーザID または user=スクリーン名 (必須) ダイレクトメッセージの宛先を指定する text=本文 (必須) ダイレクトメッセージの本文を指定する。必ず URL エンコードすること。本文は140バイト以内におさめること。 destroy ダイレクトメッセージを削除する。メッセージIDの指定は必須。 削除が成功した場合は、format で指定した形式で応答が返る URL: http://twitter.com/direct_messages/destroy/id.format (format は xml, json のうちのいずれかを指定) 引数: id=メッセージID (必須) 削除したいダイレクトメッセージのIDを指定する 例: http://twitter.com/direct_messages/destroy/12345.json メッセージID 12345 のダイレクトメッセージを削除し、実行結果を JSON 形式で受け取る http://twitter.com/direct_messages/destroy/23456.xml メッセージID 23456 のダイレクトメッセージを削除し、実行結果を XML 形式で受け取る フレンド関連のAPI create 指定ユーザを自分の friend にする(Web ブラウザ経由で add を実行するのに相当する)。 URL: http://twitter.com/friendships/create/id.format (format は xml, json のうちのいずれかを指定) 引数: id=ユーザID または user=スクリーン名 (必須) friend にしたいユーザを指定する 例: http://twitter.com/friendships/create/12345.json ユーザID 12345 の人を friend にするリクエストを発行し、実行結果を JSON 形式で取得する http://twitter.com/friendships/create/bob.xml スクリーン名 bob の人を friend にするリクエストを発行し、実行結果を XML 形式で取得する destroy 指定ユーザを自分の friend から外す(Web ブラウザ経由で remove を実行するのに相当する)。 URL: http://twitter.com/friendships/destroy/id.format (format は xml, json のうちのいずれかを指定) 引数: id=ユーザID または user=スクリーン名 (必須) friend から外したいユーザを指定する 例: http://twitter.com/friendships/destroy/12345.json ユーザID 12345 の人を friend から外すリクエストを発行し、実行結果を JSON 形式で取得する http://twitter.com/friendships/destroy/bob.xml スクリーン名 bob の人を friend から外すリクエストを発行し、実行結果を XML 形式で取得する 備考 訳者による注記: JSON 形式で応答を受け取る場合、タイムスタンプのフォーマットがたびたび変更されている。 クライアント作成者は、今までに出現したすべてのパターンに対応しておくとよいと思われる(時々、以前のパターンに戻ることがある)。 例えば、「2007年5月9日 7時56分58秒 UTC」は以下のいずれかのパターンで表現される 05/09/2007 07:56:58 UTC Wed May 09 07:56:58 +0000 2007 上記以外にも RSS フィード等で見かけるパターン 2007-05-09T07:56:58+00:00 2007-05-09T07:56:58Z Wed, 09 May 2007 07:56:58 +0000 2007-05-09 07:56:58 +0000 2007-05-09 07:56:58 UTC にも対応しておくとよいかもしれない(参考: RFC2822, RFC3161, RFC3339, ISO.8601, ISO.18014, など)。 JSONP 応答(実行結果)を JSON 形式で受け取るよう指定する場合、以下の引数を指定することで JSONP 形式で応答が返るようになる callback=コールバック関数名 この引数は、JSON 形式での応答をサポートしているすべての API で使用することができる 変更履歴 2007年6月13日 第四版 (2007年6月13日版原本がベース) (1) 「ステータス関連のAPI」に destroy を追加 (2) 「ダイレクトメッセージ関連のAPI」に destroy を追加 (3) 「備考」に JSONP に関する記述を追加 2007年6月 4日 第三版 (2007年5月30日版原本がベース) (1) 「ステータス関連のAPI」に replies を追加 (2) 「フレンド関連のAPI」(create と destroy) を追加 (3) 「ユーザ情報関連のAPI」の featured に注記を追加 2007年5月24日 第二版 (2007年5月11日版原本がベース) (1) 「ステータス関連のAPI」の show に関する記述を修正 (2) 「ステータス関連のAPI」の update に注記を追加 (3) 「備考」を追加 2007年4月25日 最初の勝手訳 (2007年4月22日版原本がベース)