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

API の実行回数制限
  Twitter の API は、60分間に70回まで実行できる(71回以上実行しようとするとエラーになる)。
  ただし、public_timeline の取得およびPOST系API(発言の投稿、ダイレクトメッセージの送信)は、この実行回数制限には関係なく、何回でも実行できる。
  この実行回数制限を適用されると都合が悪い場合は、理由を明示の上、Twitter 開発者にコンタクトを取ること。納得できる理由が示されれば、当該ユーザを、実行回数制限適用外のスクリーン名のリストに入れる。


ステータス関連の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 形式で取得する

        page=ページ番号 (オプション)
          (1ページを20件とみなしたときの)ページ番号を指定することで、過去の任意の発言を20件単位で取得する

             例:
               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 形式で取得する

     訳者による注記:
        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 形式で取得する

     訳者による注記:
        Twitter に login 中であれば、BASIC 認証なしで GET できる(自分自身が protected なユーザではない場合)


  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, 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 のうちのいずれかを指定)
          ただし、JSON 形式を指定した場合は、コールバック関数として drawFeaturedList() を使用する形式(JSONP形式)になる。(この API のみの特別な仕様)

     訳者による注記:
        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
    自分宛てのダイレクトメッセージの一覧を取得する (最大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 の場合
        <?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>


  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件)を ATOM 形式で取得する

        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, 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 形式で取得する


アカウント関連のAPI

  verify_credentials
     セッションを開始する。認証に成功すると HTTP 200 OK の応答とともに “Authorized”という文字列と cookie が返る
     (以後、この cookie を使うことで、login 状態を継続したまま、各 API を実行することができるようになる[API の実行のたびに BASIC 認証を行なう必要がなくなる])
     この API はウィジェットのようなクライアントで簡易ログイン/ログアウトを実現する目的で使うことを想定している

     URL: http://twitter.com/account/verify_credentials


  end_session
     verify_credentials で開始したセッションを終了する(本API実行後、空の cookie が返る)
     この API はウィジェットのようなクライアントで簡易ログイン/ログアウトを実現する目的で使うことを想定している

     URL: http://twitter.com/end_session


備考
 訳者による注記:
  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年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日版原本がベース)