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 の場合
        <?xml version="1.0" encoding="UTF-8"?>
        <user>
          <id>ユーザID</id>
          <name>ユーザの名前</name>
          <screen_name>ユーザのスクリーン名</screen_name>
          <location>ユーザの居住地</location>
          <description>ユーザの自己紹介</description>
          <profile_image_url>プロフィールアイコンURL</profile_image_url>
          <url>ユーザのWebページURL</url>
          <protected>プロフィールをprotectしているか否か</protected>
          <profile_background_color>プロフィールの背景の色</profile_background_color>
          <profile_text_color>プロフィールのテキストの色</profile_text_color>
          <profile_link_color>プロフィールのリンクの色</profile_link_color>
          <profile_sidebar_fill_color>サイドバーの背景の色</profile_sidebar_fill_color>
          <profile_sidebar_border_color>サイドバーの border の色</profile_sidebar_border_color>
          <friends_count>friend の数</friends_count>
          <followers_count>follower の数</followers_count>
          <favourites_count>favourite の数</favourites_count>
          <statuses_count>ステータス数</statuses_count>
          <status>
            <created_at>ステータス更新日時</created_at>
            <id>ステータスID</id>
            <text>ステータス</text>
          </status>
        </user>


ダイレクトメッセージ関連の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 の場合
        <?xml version="1.0" encoding="UTF-8"?>
        <direct-messages>
          <direct_message>
            <id>メッセージID</id>
            <text>メッセージ本文</text>
            <sender_id>送信者ID</sender_id>
            <recipient_id>受信者ID</recipient_id>
            <created_at>送信日時</created_at>
            <sender_screen_name>送信者スクリーン名</sender_screen_name>
            <recipient_screen_name>受信者スクリーン名</recipient_screen_name>
          </direct_message>
          ……
        </direct-messages>


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