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 の2008年6月27日版の大雑把な日本語訳 (ただし、そのまま翻訳したわけではなく、一部、意訳。また、現時点の実装状況に合わせて、内容を修正している) メソッド一覧 ステータス関連のAPI: public_timeline, friends_timeline, user_timeline, show, update, replies, destroy ユーザ情報関連のAPI: friends, followers, featured, show ダイレクトメッセージ関連のAPI: direct_messages, sent, new, destroy フレンド関連のAPI: create, destroy, exists アカウント関連のAPI: verify_credentials, end_session, archive, update_location, update_delivery_device, rate_limit_status お気に入り関連のAPI: favorites, create, destroy IM関連のAPI: follow, leave ブロック関連のAPI: create, destroy 補助API: test, downtime_schedule 認証 public_timeline の取得を除くすべての API で、BASIC認証を使用する。BASIC認証で使用するユーザ名はメールアドレスになる。 (訳者による注記: 現在は、スクリーン名も使える) Webブラウザ等を経由して Twitter にログインしたときに発行される cookie を使うことで BASIC 認証の代わりにすることもできるが、公式には cookie を使っての API 実行はサポートしない。 (訳者による注記: API によっては cookie 使用時も BASIC 認証が要求されるものもある。また、BASIC認証での API 実行と cookie を利用しての API 実行では、異なる結果が返る API もある。特に、protected なユーザに関する挙動い違いが見られる)。 REST Twitter の API は可能な限り REST に準拠しようとしている 引数 API によっては、必須の引数があったり、オプションとして指定可能な引数があったりする。 文字列を引数にとる API を使う場合、その文字列を UTF-8 に変換し、URLエンコードする必要がある。 HTTPリクエスト 特に注釈がない場合、Twitter の API は GET を使う。「発言」の投稿と、ダイレクトメッセージの送信のみ、POST を使う。 since 引数が使える API では、since 引数を使う代わりに、HTTP リクエストヘッダに If-Modified-Since で日時を指定することもできる。 HTTPステータスコード(レスポンス) 存在しない API を実行しようとしたり、存在しないユーザを引数で指定して API を実行しようとすると、404 Not Found が返る。 認証に失敗した場合は、401 Not Authorized が返る。 (訳者による注記: 存在しない API を実行しようとした場合や、Twitter 内で何らかのエラーが発生した場合、200 OK と共に Twitter の login ページが返ってくることもある) 200 OK: 成功 304 Not Modified: 新しい情報はない 400 Bad Request: API の実行回数制限に引っ掛かった、などの理由でリクエストを却下した 401 Not Authorized: 認証失敗 403 Forbidden: 権限がないAPI を実行しようとした(following ではない protected なユーザの情報を取得しようとした、など) 404 Not Found: 存在しない API を実行しようとしたり、存在しないユーザを引数で指定して API を実行しようとした 500 Internal Server Error: Twitter 側で何らかの問題が発生している 502 Bad Gateway: Twitter のサーバが止まっている、あるいはメンテ中 503 Service Unavailable: Twitter のサーバの負荷が高すぎて、リクエストを裁き切れない状態になっている API の実行が失敗した場合は、以下のような形式で、エラー内容詳細が返る(ことがある) /direct_messages/destroy/456.xml No direct message with that ID found. API の実行回数制限 Twitter の API は、60分間に70回まで実行できる。この実行回数制限を超えた状態でさらにリクエストを送った場合、HTTPステータスコード 400 が返る。 [訳者による注記] Twitter の運用状況によっては API 制限がより厳しく設定されることがある(60分間に20回まで、など)。 なお、public_timeline の取得およびPOST系API(発言の投稿、ダイレクトメッセージの送信)は、この実行回数制限には関係なく、何回でも実行できる。 この実行回数制限を適用されると都合が悪い場合は、理由を明示の上、Twitter 開発者にコンタクトを取ること。納得できる理由が示されれば、当該ユーザを、実行回数制限適用外のスクリーン名のリストに入れる。 rate_limit_status という「アカウント関連のAPI」を使うことで、実際の API 制限の実施状況を調べることができる。 変更を検討中のもの ・2007年7月26日: 変更を検討中のAPIに関する説明として "Migrating to Followers and Notifications" (http://groups.google.com/group/twitter-development-talk/web/migrating-to-followers-and-notifications) を用意した。 また、新しい用語(friends が following に変更された)に関しても "Migrating to Followers and Notifications" で解説している。 以下、"Migrating to Followers and Notifications" の要約 [2008年4月25日現在、"Migrating to Followers and Notifications" のWebページは Not Found になってしまっている] ・2007年7月19日に、Twitter のサイト内で使う用語の変更を行なった。その結果、Web サイトとAPIで用語に食い違いが発生してしまったが、いずれ、新しい用語で統一する予定。 ・今まで使っていた用語: friends, followers ・新しい用語: following, followers ・Twitter API を利用しているアプリケーションで新しい用語を使いたい場合は、以下のように、用語の置き換えを行なうことを推奨 friends → following または people you follow (あなたが follow している人) followers → 現状のまま。あるいは people who follow you (あなたを follow している人) か people who follow your updates (あなたの「発言」を追いかけている人) に変更 friends_timeline → timeline of updates from people you follow (あなたが follow している人たちの「発言」を集めた timeline) 友だち関係の create (add) / destroy (delete) → follow (この人の「発言」を追いかける) / stop following (この人の「発言」を追いかけるのをやめる) ・API の変更: 近い将来、API 自体にも、新しい用語を反映させる。新しい API をリリースした後も、しばらくの間は従来の API も使えるようにする。 この用語の件とは別に、ユーザの設定を変更する API の追加を検討中。 あなたの作成したクライアントの名前が、Twitter の Webページ上の発言に“from クライアント名”という形で掲載されるようにする方法 Twitter にログインしている状態で http://twitter.com/help/request_source の各項目に回答することで、クライアント名の掲載を申請することができる (訳者による注記: 以前は、Twitter開発者の Alex氏にメールで交渉するしか手はなかったが、現在は、専用の申請フォームが用意されている) ステータス関連の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 形式で取得する 注意: public_timeline の取得結果は60秒間キャッシュされる。それよりも短い時間間隔で public_timeline を取得したい場合は IM (Jabber Pubsub) を利用すること。[訳者による注記: Jabber Pubsub は1分間に400発言程度まで扱えることを目標にして いるとのこと。つまり、それより発言数が多い場合は、Jabber Pubsub を使ってもとりこぼしが起きる] 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 形式で取得する page=ページ番号 (オプション) (1ページを20件とみなしたときの)ページ番号を指定することで、過去の任意の発言を20件単位で取得する なお、この page オプションは、Twitter の負荷が高いとき等、一時的に使えないようにすることがある 例: http://twitter.com/statuses/friends_timeline.rss?page=3 API実行時点で41件目から60件目に相当するステータスを RSS 形式で取得する 訳者による注記: Twitter に login 中であれば、BASIC 認証なしで GET できる(ただし、protected なユーザの発言は取得できない) 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 形式で取得する since_id=ステータスID (オプション) 指定したステータスID以降のステータスを取得する 例: http://twitter.com/statuses/user_timeline.xml?since_id=12345 ステータスID 12345 以降のステータスを XML 形式で取得する page=ページ番号 (オプション) (1ページを20件とみなしたときの)ページ番号を指定することで、過去の任意の発言を20件単位で取得する なお、この page オプションは、Twitter の負荷が高いとき等、一時的に使えないようにすることがある 例: http://twitter.com/statuses/users_timeline.rss?page=3 API実行時点で41件目から60件目に相当するステータスを 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バイトを超えた部分は必ずしも表示される保証はない。 source=クライアント名 (オプション) ステータスの投稿に使用しているクライアント名を指定する。「クライアント名」を Alex Payne 氏 (http://twitter.com/al3x) にメールで連絡し承認を得ることで、Twitter の Webページ上に“from クライアント名”付きで発言が掲載されるようになる。 なお、本引数は公式のAPI仕様書には掲載されていない。 訳者による注記: 2007年4月はじめごろまでは GET でも構わなかった。現在は、GET は使えなくなっている replies 自分に対する返信(冒頭が @ユーザ名 で始まるステータス)の一覧を取得する (最大20件) なお、現時点では、自分が他のユーザに対して行なった返信の一覧を取得する API は用意されていない。 URL: http://twitter.com/statuses/replies.format (format は xml, json, rss, atom のうちのいずれかを指定) page=ページ番号 (オプション) (1ページを20件とみなしたときの)ページ番号を指定することで、過去の任意の返信を20件単位で取得する 例: http://twitter.com/statuses/replies.xml?page=3 API実行時点で41件目から60件目に相当する返信を RSS 形式で取得する since=日時 (オプション) 指定した日時以降に update されたステータスを取得する 日時のフォーマットは RFC822(の「5. 日付と時刻仕様」) に従う なお、本オプションの代わりに http リクエストヘッダで If-Modified-Since を明示することで、日時を指定することもできる 例: http://twitter.com/statuses/replies.rss?since=Tue%2C+27+Mar+2007+22%3A55%3A48+GMT 2007年3月27日22時55分48秒GMT以降の返信を RSS 形式で取得する since_id=ステータスID (オプション) 指定したステータスID以降のステータスを取得する 例: http://twitter.com/statuses/replies.xml?since_id=12345 ステータスID 12345 以降の返信を XML 形式で取得する 訳者による注記: Twitter に login 中であれば、BASIC 認証なしで GET できる(自分自身が protected なユーザではない場合) Twitter の運用状況によっては、本 API を使えなくすることがある 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 の一覧を取得できる ただし、この API で取得できるデータは最大100件(100人分)である URL: http://twitter.com/statuses/friends.format (format は xml, json のうちのいずれかを指定) 引数: id=ユーザID または id=スクリーン名 (オプション) 指定した ID またはスクリーン名のユーザの friend のステータスを取得する (この引数を指定しない場合は、自分の friend のステータスを取得する) 例: http://twitter.com/statuses/friends/12345.json ユーザID 12345 の friend の一覧を JSON 形式で取得する http://twitter.com/statuses/friends/bob.xml スクリーン名 bob の friend の一覧を XML 形式で取得する page=ページ番号 (オプション) (1ページを100件とみなしたときの)ページ番号を指定することで、指定ユーザの friend の一覧を100件単位で取得する 例: http://twitter.com/statuses/friends.xml?page=2 API実行時点で101件目から200件目に相当する(自分の)friend の一覧を XML 形式で取得する lite=true (オプション) lite=true を指定すると、「各 friend の最新ステータスなし」で friend の一覧を返す 例: http://twitter.com/statuses/friends.xml?lite=true 自分の friend の一覧を「最新ステータスなし」の XML 形式で取得する since=日時 (オプション) 指定した日時以降にステータス が update された friend の一覧を取得する 日時のフォーマットは RFC822(の「5. 日付と時刻仕様」) に従う なお、本オプションの代わりに http リクエストヘッダで If-Modified-Since を明示することで、日時を指定することもできる 例: http://twitter.com/statuses/friends.xml?since=Tue%2C+27+Mar+2007+22%3A55%3A48+GMT 2007年3月27日22時55分48秒GMT以降にステータス が update された friend の一覧を XML 形式で取得する 訳者による注記: Twitter に login 中であれば、BASIC 認証なしで GET できる followers 自分の follower の一覧を(各 follower の最新ステータス付きで)取得する URL: http://twitter.com/statuses/followers.format (format は xml, json のうちのいずれかを指定) 引数: id=ユーザID または id=スクリーン名 (オプション) 指定した ID またはスクリーン名のユーザの follower のステータスを取得する (この引数を指定しない場合は、自分の follower のステータスを取得する) 例: http://twitter.com/statuses/followers/12345.json ユーザID 12345 の friend の一覧を JSON 形式で取得する http://twitter.com/statuses/followers/bob.xml スクリーン名 bob の friend の一覧を XML 形式で取得する page=ページ番号 (オプション) (1ページを100件とみなしたときの)ページ番号を指定することで、指定ユーザの follower の一覧を100件単位で取得する 例: http://twitter.com/statuses/followers.xml?page=2 API実行時点で101件目から200件目に相当する(自分の)follower の一覧を XML 形式で取得する lite=true (オプション) lite=true を指定すると、「各 follower の最新ステータスなし」で follower の一覧を返す 例: http://twitter.com/statuses/followers.xml?lite=true 自分の follower の一覧を「最新ステータスなし」の XML 形式で取得する 訳者による注記: Twitter の運用状況によっては、本 API を使えなくすることがある。もしくは、id 引数が無視されることがある。 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 形式で取得する email=メールアドレス (オプション) 情報取得対象となるユーザをメールアドレスで指定する。このオプション使用時は id の指定は不要。 例: http://twitter.com/users/show.xml?email=test@example.com 登録時のメールアドレスが test@example.com であるユーザの情報を XML 形式で取得する 応答: XML の場合 ユーザID ユーザの名前 ユーザのスクリーン名 ユーザの居住地 ユーザの自己紹介 プロフィールアイコンURL ユーザのWebページURL プロフィールをprotectしているか否か プロフィールの背景の色 プロフィールのテキストの色 プロフィールのリンクの色 サイドバーの背景の色 サイドバーの border の色 friend の数 follower の数 favourite の数 ステータス数 ステータス更新日時 ステータスID ステータス ダイレクトメッセージ関連のAPI direct_messages 自分宛てのダイレクトメッセージの一覧を取得する (最大20件) 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以降に届いたダイレクトメッセージ(のうち新しいもの最大20件)を ATOM 形式で取得する since_id=メッセージID (オプション) 指定したIDより大きな値のIDのダイレクトメッセージを最大20件取得する 例: http://twitter.com/direct_messages.xml?since_id=12345 メッセージID 12345 以降のダイレクトメッセージ(のうち、古いものから順に最大20件)を XML 形式で取得する page=ページ番号 (オプション) (1ページを20件とみなしたときの)ページ番号を指定することで、過去の任意のダイレクトメッセージを20件単位で取得する 例: http://twitter.com/direct_messages.xml?page=3 API実行時点で41件目から60件目に相当するダイレクトメッセージを XML 形式で取得する 応答: XML の場合 メッセージID メッセージ本文 送信者ID 受信者ID 送信日時 送信者スクリーン名 受信者スクリーン名 …… sent 自分が送信したダイレクトメッセージの一覧を取得する (最大20件) URL: http://twitter.com/direct_messages/sent.format (format は xml, json のうちのいずれかを指定) 引数: since=日時 (オプション) 指定した日時以降に送信したダイレクトメッセージを取得する 日時のフォーマットは RFC822(の「5. 日付と時刻仕様」) に従う なお、本オプションの代わりに http リクエストヘッダで If-Modified-Since を明示することで、日時を指定することもできる 例: http://twitter.com/direct_messages/sent.xml?since=Tue%2C+27+Mar+2007+22%3A55%3A48+GMT 2007年3月27日22時55分48秒GMT以降に送信したダイレクトメッセージ(のうち新しいもの最大20件)を XML 形式で取得する since_id=メッセージID (オプション) 指定したIDより大きな値のIDの送信済みダイレクトメッセージを最大20件取得する 例: http://twitter.com/direct_messages/sent.xml?since_id=12345 メッセージID 12345 以降の送信済みダイレクトメッセージ(のうち、古いものから順に最大20件)を XML 形式で取得する page=ページ番号 (オプション) (1ページを20件とみなしたときの)ページ番号を指定することで、過去の任意の送信済みダイレクトメッセージを20件単位で取得する 例: http://twitter.com/direct_messages/sent.xml?page=3 API実行時点で41件目から60件目に相当する送信済みダイレクトメッセージを XML 形式で取得する 訳者による注記: atom 形式や rss 形式での取得はできない new ダイレクトメッセージを送信する。宛先と本文の指定は必須。 この API は必ず POST を使って発行すること。送信が成功した場合は、format で指定した形式で応答が返る URL: http://twitter.com/direct_messages/new.format (format は xml, json のうちのいずれかを指定) 引数: 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 (following) にする URL: http://twitter.com/friendships/create/id.format (format は xml, json のうちのいずれかを指定) 引数: id=ユーザID または id=スクリーン名 (必須) friend にしたいユーザを指定する 例: http://twitter.com/friendships/create/12345.json ユーザID 12345 の人を friend にするリクエストを発行し、実行結果を JSON 形式で取得する http://twitter.com/friendships/create/bob.xml スクリーン名 bob の人を friend にするリクエストを発行し、実行結果を XML 形式で取得する destroy 指定ユーザを自分の friend (following) から外す URL: http://twitter.com/friendships/destroy/id.format (format は xml, json のうちのいずれかを指定) 引数: id=ユーザID または id=スクリーン名 (必須) friend から外したいユーザを指定する 例: http://twitter.com/friendships/destroy/12345.json ユーザID 12345 の人を friend から外すリクエストを発行し、実行結果を JSON 形式で取得する http://twitter.com/friendships/destroy/bob.xml スクリーン名 bob の人を friend から外すリクエストを発行し、実行結果を XML 形式で取得する exists 指定した2ユーザの間の friend 関係を調べる (format は xml, json のうちのいずれかを指定。もしくは何も指定しない) 引数: user_a=調査対象のうち1人目のユーザID または id=スクリーン名 (必須) user_b=調査対象のうち2人目のユーザID または id=スクリーン名 (必須) 例: http://twitter.com/friendships/exists.xml?user_a=alice&user_b=bob スクリーン名 alice の人と bob の人の間に friend 関係があるかどうか調べ、結果を XML 形式で取得する アカウント関連のAPI verify_credentials セッションを開始する。認証に成功すると HTTP 200 OK の応答とともに cookie が返る (以後、この cookie を使うことで、login 状態を継続したまま、各 API を実行することができるようになる[API の実行のたびに BASIC 認証を行なう必要がなくなる]) この API はウィジェットのようなクライアントで簡易ログイン/ログアウトを実現する目的で使うことを想定している URL: http://twitter.com/account/verify_credentials.format (format は xml, json のうちのいずれかを指定。もしくは何も指定しない) または http://twitter.com/account/verify_credentials 応答: 認証成功時、以下のような応答が返る format を指定しない場合 Authorized xml を指定した場合 true json を指定した場合 {"authorized":true} 訳者による注記: 本 API で使用するユーザ名はメールアドレスでも、スクリーン名でも可。 end_session verify_credentials で開始したセッションを終了する(本API実行後、空の cookie が返る) この API はウィジェットのようなクライアントで簡易ログイン/ログアウトを実現する目的で使うことを想定している URL: http://twitter.com/account/end_session 訳者による注記: 実際には、中身の入っている cookie が返ってくる また、http://twitter.com/login にリダイレクトされる archive 自分の最新の発言80件を取得する。取得結果は発言日時の降順で格納される URL: http://twitter.com/account/archive.format (format は xml, json のうちのいずれかを指定) 引数: page=ページ番号 (オプション) (1ページを80件とみなしたときの)ページ番号を指定することで、過去の任意の発言を80件単位で取得する 例: http://twitter.com/account/archive.xml?page=2 API実行時点で81件目から160件目に相当する自分の発言を XML 形式で取得する since=日時 (オプション) 指定した日時以降の発言を取得する 日時のフォーマットは RFC822(の「5. 日付と時刻仕様」) に従う なお、本オプションの代わりに http リクエストヘッダで If-Modified-Since を明示することで、日時を指定することもできる 例: http://twitter.com/account/archive.xml?since=Tue%2C+27+Mar+2007+22%3A55%3A48+GMT 2007年3月27日22時55分48秒GMT以降の発言を(のうち新しいもの最大80件)を XML 形式で取得する since_id=ステータスID (オプション) 指定したIDより大きな値のIDの発言を最大80件取得する 例: http://twitter.com/account/archive.xml?since_id=12345 メッセージID 12345 以降の発言(のうち、古いものから順に最大80件)を XML 形式で取得する update_location 自分の profile の location 欄に表示する情報を更新する。POST でも GET でも可 URL: http://twitter.com/account/update_location.format (format は xml, json のうちのいずれかを指定) 引数: location=ユーザの現在位置 (必須) profile の location 欄に表示したい文字列を指定する。今のところ、地名を標準的な名称に統一したり、緯度・経度で指定した情報を地名に変換して表示する機能はない (要するに、指定した文字列がそのまま表示される) 例: http://twitter.com/account/update_location.xml?location=San%20Francisco profile の location 欄に表示する文字列を 'San Francisco' に変更する update_delivery_device 自分の device を設定する URL: http://twitter.com/account/update_delivery_device.format (format は xml, json のうちのいずれかを指定) 引数: device=sms, im, none のいずれかを指定 (必須) SMS もしくは IM を使って最新の発言を取得したい場合に、本 API にて指定する 例: http://twitter.com/account/update_delivery_device?device=im IM で最新の発言を取得できるように設定する (注意: IM 側の設定も必要) rate_limit_status 自分の「API 制限状況」(この1時間以内にあと何回APIを実行できるか)を取得する。本APIの実行自体はAPI制限の対象外である(何回でも実行できる) URL: http://twitter.com/account/rate_limit_status.format (format は xml, json のうちのいずれかを指定) 引数: なし 応答例: XML の場合 6 20 1214817685 2008-06-30T09:21:25+00:00 お気に入り関連のAPI favorites 自分または指定したユーザの favorites(お気に入り) に登録されている「発言」のうち、最新のものから最大20件取得する URL: http://twitter.com/favorites.format (format は xml, json, rss, atom のうちのいずれかを指定) 引数: id=ユーザID(またはスクリーン名) (オプション) 「お気に入り」一覧を取得したユーザの ID またはスクリーン名を指定する 例: http://twitter.com/favorites/12345.json ユーザID 12345 の人の「お気に入り」一覧を JSON 形式で取得する http://twitter.com/favorites/bob.xml スクリーン名 bob の人の「お気に入り」一覧を XML 形式で取得する page=ページ番号 (オプション) (1ページを20件とみなしたときの)ページ番号を指定することで、過去の任意の「お気に入り」一覧を20件単位で取得する 例: http://twitter.com/favorites.xml?page=3 API実行時点で41件目から60件目に相当する「お気に入り」一覧を XML 形式で取得する 注意: 公式のAPI仕様書では http://twitter.com/favourings.format のように修正されたが、エラーになる(実装は以前の URL のままになっている)。(いずれは仕様書通りの実装になる?) create 指定ステータスを自分の「お気に入り」に登録する。 URL: http://twitter.com/favourings/create/id.format (format は xml, json のうちのいずれかを指定) 引数: id=ステータスID (必須) 「お気に入り」に登録したいステータス(発言)を指定する 例: http://twitter.com/favourings/create/12345.json ステータスID 12345 を「お気に入り」に登録するリクエストを発行し、実行結果を JSON 形式で取得する http://twitter.com/favourings/create/45567.xml ステータスID 45567 を「お気に入り」に登録するリクエストを発行し、実行結果を XML 形式で取得する destroy 指定ステータスを自分の「お気に入り」から外す。 URL: http://twitter.com/favourings/destroy/id.format (format は xml, json のうちのいずれかを指定) 引数: id=ステータスID (必須) 「お気に入り」から外したいステータス(発言)を指定する 例: http://twitter.com/favourings/destroy/12345.json ステータスID 12345 を「お気に入り」から外すリクエストを発行し、実行結果を JSON 形式で取得する http://twitter.com/favourings/destroy/23456.xml ステータスID 23456 を「お気に入り」から外すリクエストを発行し、実行結果を XML 形式で取得する IM関連のAPI follow 指定ユーザ(following)の発言を IM に送信するようにする URL: http://twitter.com/notifications/follow/id.format (formats は xml, json のうちのいずれかを指定) 引数: id=ユーザID(またはスクリーン名) (必須) 発言を IM に送信したいユーザの ID またはスクリーン名を指定する 例: http://twitter.com/notifications/follow/12345.xml ユーザID 12345 の人の発言を IM に送信するようにする http://twitter.com/notifications/follow/bob.json スクリーン名 bob の発言を IM に送信するようにする leave 指定ユーザ(following)の発言を IM に送信するのをやめる URL: http://twitter.com/notifications/leave/id.format (formats は xml, json のうちのいずれかを指定) 引数: id=ユーザID(またはスクリーン名) (必須) 発言を IM に送信するのをやめたいユーザの ID またはスクリーン名を指定する 例: http://twitter.com/notifications/leave/12345.xml ユーザID 12345 の人の発言を IM に送信するのをやめる http://twitter.com/notifications/leave/bob.json スクリーン名 bob の発言を IM に送信するのをやめる ブロック関連のAPI create 指定ユーザをブロックする URL: http://twitter.com/blocks/create/id.format (format は xml, json のうちのいずれかを指定) 引数: id=ユーザID または id=スクリーン名 (必須) ブロックしたいユーザを指定する 例: http://twitter.com/blocks/create/12345.json ユーザID 12345 の人をブロックするリクエストを発行し、実行結果を JSON 形式で取得する http://twitter.com/blocks/create/bob.xml スクリーン名 bob の人をブロックするリクエストを発行し、実行結果を XML 形式で取得する destroy 指定ユーザのブロックを解除する URL: http://twitter.com/blocks/destroy/id.format (format は xml, json のうちのいずれかを指定) 引数: id=ユーザID または id=スクリーン名 (必須) ブロック解除したいユーザを指定する 例: http://twitter.com/blocks/destroy/12345.json ユーザID 12345 の人のブロックを解除するリクエストを発行し、実行結果を JSON 形式で取得する http://twitter.com/blocks/destroy/bob.xml スクリーン名 bob の人のブロックを解除するリクエストを発行し、実行結果を XML 形式で取得する 補助API test 成功すれば(Twitter が正常に稼動していれば)、"ok" という文字列を http ステータスコード 200 OK で返す URL: http://twitter.com/help/test.format (format は xml, json のうちのいずれかを指定) 引数: なし downtime_schedule Twitter のメインテナンスが予定されるときに http://twitter.com/home に表示されるのと同じ文字列を指定formatで返す URL: http://twitter.com/help/downtime_schedule.format (format は xml, json のうちのいずれかを指定) 引数: なし 備考 訳者による注記: JSON 形式で応答を受け取る場合、タイムスタンプのフォーマットがたびたび変更されている。 クライアント作成者は、今までに出現したすべてのパターンに対応しておくとよいと思われる(時々、以前のパターンに戻ることがある)。 例えば、「2007年5月9日 7時56分58秒 UTC」は以下のいずれかのパターンで表現される 05/09/2007 07:56:58 UTC Wed May 09 07:56:58 +0000 2007 Wed 09 May 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 で使用することができる in_reply_to 2008年3月26日ごろから、timeline (status)取得系の API の応答結果に、in_reply_to および in_reply_to_user_id フィールドが追加されるようになった。 @ 付きの発言(reply)に対して、reply 元の status が in_reply_to に、user ID が in_reply_to_user_id に格納される。 in_reply_to は入れ子構造になっていて、(reply の reply の reply の …… の reply という風に)最大10件分(推定)の status が格納される。 (私が調査、観測した範囲では10件を超えるものは未発見) 変更履歴 2008年 6月30日 第十三版 (2008年6月27日版原本がベース) (1) 「メソッド一覧」を追加 (2) 「API の実行回数制限」に注記、説明を追加 (3) 「あなたの作成したクライアントの名前が、Twitter の Webページ上の発言に“from クライアント名”という形で掲載されるようにする方法」を追加 (4) 「ステータス関連のAPI」の public_timeline に「注意」を追加 (5) 「ステータス関連のAPI」の user_timeline に“since_id 引数”を追加 (6) 「ステータス関連のAPI」の replies に“since 引数”と“since_id 引数”を追加。「訳者による注記」に追記 (7) 「ユーザ情報関連のAPI」の friends に“since 引数”を追加 (8) 「ユーザ情報関連のAPI」の followers の“id 引数”を復活。「訳者による注記」を追加 (9) 「フレンド関連のAPI」に exists を追加 (10) 「アカウント関連のAPI」の archive に“since 引数”と“since_id 引数”を追加 (11) 「アカウント関連のAPI」に update_location を追加 (12) 「アカウント関連のAPI」に update_delivery_device を追加 (13) 「アカウント関連のAPI」に rate_limit_status を追加 (14) 「ブロック関連のAPI」(create, destroy)を追加 (15) 「補助API」(test, downtime_schedule)を追加 2008年 4月25日 第十二版 (2008年4月25日版原本がベース) (1) 「ユーザ情報関連のAPI」の friends に“page 引数”と“lite 引数”を追加 (2) 「ユーザ情報関連のAPI」の followers に“page 引数”を追加 (3) 「備考」に“in_reply_to”を追加 2008年 3月 3日 第十一版 (2008年1月22日版原本がベース) 「IM関連のAPI」を追加 2007年11月27日 第十版 (2007年11月20日版原本がベース) (1) 「HTTPステータスコード(レスポンス)」の説明を追加 (2) 「ステータス関連のAPI」の friends_timeline と user_timeline の“page 引数”に「但し書き」を各々追加 (3) 「ユーザ情報関連のAPI」の followers の“id 引数”に関する「但し書き」を追加 (4) 「ユーザ情報関連のAPI」の show に“email 引数”を追加 (5) 「ダイレクトメッセージ関連のAPI」の new の format から rss, atom を削除 (6) 「アカウント関連のAPI」に archive を追加 (7) 「フレンド関連のAPI」の favorites の説明を修正 (仕様書と実装が一致しなくなった) (8) 「フレンド関連のAPI」の create と destroy の「注意書き」を削除 (仕様書と実装が一致するようになった) 2007年11月9日 第九版 (2007年10月19日版原本がベース) // 注: 2007年10月19日版は2007年8月30日版と同じ内容(10月3日に発生した第三者による削除行為後の復旧版が2007年10月19日版である) 「お気に入り関連のAPI」の create と destroy の説明を現実の実装に合わせて修正 2007年8月31日 第八版 (2007年8月30日版原本がベース) (1) 「API の実行回数制限」の説明を更新。ステータスコード 400 に関する記述を追加 (2) 「ステータス関連のAPI」の user_timeline に “page 引数”を追加 (3) 「ユーザ情報関連のAPI」の featured の JSON形式の特殊仕様に関する説明を削除 (callback引数指定時の特殊仕様が廃止された) (4) 「ユーザ情報関連のAPI」の followers に“lite 引数”を追加 (5) 「お気に入り関連のAPI」(favorites, create, destroy) を追加 (6) 「フレンド関連のAPI」の create と destroy の説明を修正 2007年8月16日 第七版 (2007年7月27日版原本がベース) (1) 「ステータス関連のAPI」の destroy の説明を修正 (2) 「ユーザ情報関連のAPI」の friends の説明を修正 (原本自体にも間違いがある → 報告済み) (3) 「ユーザ情報関連のAPI」の followers の説明を修正 (4) 「アカウント関連のAPI」の verify_credentials を修正 (実際に使ってみた結果を反映) (5) 「アカウント関連のAPI」の end_session を修正 (実際に使ってみた結果を反映) (6) 「認証」を追加 (7) 「REST」を追加 (8) 「変更を検討中のもの」を追加 (2007年7月27日版原本で追加された) 2007年7月19日 第六版 (2007年7月17日版原本がベース) (1) 「アカウント関連のAPI」の verify_credentials の仕様を変更 (2) 「備考」のタイムスタンプのパターン例を追加 2007年7月17日 第五版 (2007年7月10日版原本がベース) (1) 「API の実行回数制限」の項を追加 (2) 「ステータス関連のAPI」の friends_timeline に “page 引数”を追加 (3) 「ステータス関連のAPI」の update に “source 引数”を追加 (4) 「ステータス関連のAPI」の replies に “page 引数”を追加 (5) 「ユーザ情報関連のAPI」の friends に最大取得可能件数に関する説明を追加 (6) 「ユーザ情報関連のAPI」の featured の JSON形式の特殊仕様に関する説明を追加 (7) 「ダイレクトメッセージ関連のAPI」の direct_messages の最大取得可能件数に関する説明、“since_id 引数”、“page 引数”を各々追加 (8) 「ダイレクトメッセージ関連のAPI」の sent を追加 (9) 「アカウント関連のAPI」(verify_credentials と end_session) を追加 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日版原本がベース) 備考: 本API仕様書(日本語版)よりもさらに詳細な解説が必要な方は、拙著「Twitter! ― Twitter API ガイドブック」(ISBN: 978-4-86167-194-4)を参照されたい