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日版原本がベース)