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年5月30日版の大雑把な日本語訳
  (ただし、そのまま翻訳したわけではなく、一部、意訳。また、現時点の実装状況に合わせて、内容を修正している)

ステータス関連の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 できる


ユーザ情報関連の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バイト以内におさめること。


フレンド関連の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, など)。


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