twitter apiについて
| ドキュメントURL |
[本家] : http://dev.twitter.com/doc/ [日本語訳] : http://watcher.moe-nifty.com/memo/docs/twitterAPI.txt |
|---|---|
| 認証・制限など | 一部のapiは、OAuth認証を必要とする。（2010/12/14時点） |
| 概要 | twitterの各種データにアクセスできる。 |
ここはなに？
twitterの各種apiをコールしたときに、具体的にどんな値が返ってくるのか一瞬で分かります。
キーの意味を知るよりも、実際にどんな値が入っているかを知るほうが理解しやすいと思います。
目的の値を見つけて、あぁこの値を取り出すのはこのキーだな、とそんな使い方を想定しています。
使い方
まずは、上のボタンからOAuth認証してください。（認証している場合は解除ボタンになります）
次は、このページの下にあるapiの一覧から目的っぽいページに移動しましょう。
パラメータをセットして、「call update」と書かれたボタンを押します。
百聞は一見にしかずです。 statuses/public_timelineに移動し、「call update」を押してみてください。
１つだけ注意があります。
当サイトで発行されるapi、特に更新系のapiにはご注意ください。
テストだと思って、statuses/updateを発行すると、あなたのtwitterにも反映されます。
OAuthでログインするアカウントにはご注意ください。
タイムライン関連
statuses/public_timeline
公開状態で自分のアイコンを設定しているユーザーの発言を最新から取得（最大20件）
API実行後60秒間は再リクエストをしてもキャッシュ（同一内容）が返ります。
statuses/home_timeline
本家web版twitterの「ホーム」タイムラインと同じ内容
自分とfriendのツイートを過去800件のうちの20件を取得
statuses/friends_timeline
自分のfriendの過去800件分のステータスを取得。
include_rts指定時は、最大20件。
statuses/user_timeline
自分の過去3200件分のステータスから最大20件(count引数使用時は最大200件)を取得する。
id, user_id, screen_name のいずれかの引数を指定すれば、そのユーザのステータスを取得できる
statuses/mentions
自分あての返信(@自身を含むツイート)を最大20件ずつ取得。
直近800件より古い発言にはアクセスできない。
statuses/retweeted_by_me
自分が投稿した retweet の一覧を取得する
statuses/retweeted_to_me
自分の friends が投稿した retweet の一覧を取得する
statuses/retweets_of_me
自分が投稿した発言のうち(自分以外の)誰かによって retweet されたものの一覧を取得する
ツイート関連
statuses/show
指定した ID のステータス(1件)を取得する
statuses/update
ステータスを更新する。 ＝ ツイートする。
1日の上限は、他のクライアントやwebも含めて1ユーザー1000回まで。上限時403エラー。
同一内容は投稿できない。無視される。無視されたときの応答内容は最初に投稿した時の内容。
statuses/destroy
ステータス(ツイート)を削除する。
statuses/retweet
指定したステータス（投稿）を retweet (公式RT) する。
statuses/retweets
指定したステータスを retweet しているユーザのうち最初の100人分を取得
statuses/retweeted_by
指定したステータス（投稿）を retweets しているユーザー情報の一覧。
statuses/retweeted_by/ids
指定したステータス（投稿）を retweets しているユーザーIDの一覧を取得する。
ユーザ情報関連
users/show
指定したユーザーの詳細な情報を取得。
パラメータはいずれか１つ以上必要。
ただし、friendでない(フォローしていない)ユーザーの場合は失敗する。
users/lookup
指定したユーザーの詳細な情報を取得。
ユーザーは、カンマ区切りで最大100まで指定できる。
パラメータが長くなる時はPOST推奨。
users/search
条件に一致するユーザーを検索する。
users/suggestions
suggested user list のカテゴリ一覧を取得する。
認証不要。IPアドレス単位で制限あり
users/suggestions/twitter
suggested user list から指定したカテゴリの詳細を取得する。
認証不要。IPアドレス単位で制限あり
users/profile_image/twitter
このAPIはかなり特殊です！
formatに、jsonもしくはxmlを指定しますが、json、xmlの形式は返却されません。
代わりに、httpステータスコード302（リダイレクト）とともにhtmlが返却されます。
このAPIはアプリ開発者がプロフィール画像の存在を確認するためだけに使います。
このAPIで得られる結果をそのまま画面に表示する用途として使ってはいけません。
※翻訳に自信が無いので、英語版の本家ドキュメントでご確認ください。
statuses/friends
指定したユーザーのfriend(フォロー)の一覧を取得する。
statuses/followers
指定したユーザーのfollowers(フォロワー)の一覧を取得する。
トレンド関連
trends
twitter全体で人気のある話題を取得する。
trends/current
twitter全体で人気のある話題を取得する。
trendsと似ているが戻り値の形式が異なる。
trends/daily
twitter全体で人気のある話題を日付を指定して取得する。
trends/weekly
twitter全体で人気のある話題を週（日付）を指定して取得する。
指定するのは日付で、日付が含まれる週が対象となる。
指定した日の5日前から7日分が取得される様子。
(例) 2010-11-26 を指定。 2010-11-21 ～ 2010-11-27 まで。
一般的な「一週間」という表現とは異なる？
ローカルトレンド関連
trends/available
twitter全体で人気のある話題が存在する地域情報（国？）を取得する。
緯度、経度を指定すれば、その場所に近い順に取得。
trends/1
指定した地点で、人気のある話題を取得する。
list 関連
user/lists/create
List(リスト)を作成する。ユーザー１人につき20リストまで。
user/lists/id/update
List(リスト)を更新する。
user/lists
指定したユーザーのList(リスト)の一覧を取得する。
user/lists/id/show
指定したList(リスト)の詳細を取得する。
user/lists/id/destroy
指定したList(リスト)を削除する。
POSTメソッドで発行する際は、 _method パラメータが必要。
_method を省略してPOSTすると、/twitter/user/lists/id/update の扱いになる。
user/lists/id/statuses
指定したList(リスト)のタイムラインを取得する。
user/lists/memberships
指定したユーザーが登録されているList(リスト)の一覧を取得する。
user/lists/subscriptions
指定したユーザーが購読しているList(リスト)の一覧を取得する。
list のメンバー
user/list_id/members/get
指定したList(リスト)に登録されているユーザーの一覧を取得する。
user/list_id/members/post
指定したList(リスト)にユーザーを追加する。
user/list_id/create_all
指定したList(リスト)に、複数のユーザーをまとめて加える。
user/list_id/members/delete
指定したList(リスト)からユーザーを削除する。
user/list_id/members
指定したList(リスト)に、ユーザーが追加済みかどうか調べる。
登録済みならそのユーザーの情報が、未登録ならエラーが返る。
list の購読
user/list_id/subscribers/get
指定したList(リスト)を購読（フォロー）しているユーザーの一覧を取得する。
user/list_id/subscribers/post
指定したList(リスト)を購読（フォロー）する。
user/list_id/subscribers/delete
指定したList(リスト)の購読（フォロー）を解除する。
user/list_id/subscribers
指定したList(リスト)を、ユーザーが購読しているかどうか調べる。
購読しているならそのユーザーの情報が、未購読ならエラーが返る。
ダイレクトメッセージ
direct_messages
自分宛のダイレクトメッセージの一覧を取得
direct_messages/sent
自分が送信したダイレクトメッセージの一覧を取得
direct_messages/new
ダイレクトメッセージを送信する。
1日1000回まで。
direct_messages/destroy
指定したダイレクトメッセージを削除する。
フレンド関連
friendships/create
指定したユーザーをfriend（フォロー）する。
成功時 : ユーザーの情報が返る。
失敗時 : エラー内容が返る。
既にフォローしていた場合 : HTTPステータスコード 403 が返る。
friendships/destroy
指定したユーザーをfriend（フォロー）を解除する。
成功時 : 削除したユーザーの情報が返る。
失敗時 : エラー内容が返る。
friendships/exists
指定したユーザー２人のfriend（フォロー）の関係を取得。
true または false のみのいずれかが返って来る。
friendships/show
指定したユーザー２人の関係を詳しく取得する。
[※1]認証なしでコールする場合は次のパラメータのいずれかが必須
[※1]認証ありで次のパラメータを省略した場合、1人目は自分になる。
source_id / source_screen_name
[※2]いずれかが必須
target_id / target_screen_name
friendships/incoming
自身がprotected の時に使用。
自身に対してフォローリクエストをしているユーザーのうち、リクエストを保留しているユーザーの一覧。
自身が protected でなければ、空の一覧が返却される。
friendships/outgoing
相手がprotected の時、 自身がフォローリクエストを送り、保留にされたままのユーザー一覧。
ソーシャルグラフ関連
friends/ids
user_id / screen_name のいずれかで指定したユーザーが、フォローしているfriendsのユーザーID一覧。
パラメータ cursor は、将来「必須」になる予定とのこと。
followers/ids
user_id / screen_name のいずれかで指定したユーザーが、フォローされているユーザーのユーザーID一覧。
パラメータ cursor は、将来「必須」になる予定とのこと。
アカウント関連
account/verify_credentials
ログイン中であれば、HTTPステータスコード200とユーザーの情報が返る。
そうでなければ、HTTPステータスコード401とエラーメッセージが返る。
認証が有効化どうか調べるために使用する。
account/rate_limit_status
Apiの制限内容を取得。1時間内での残りapi回数など。
OAuth認証でアクセスすればユーザー単位。認証なしならばIPアドレス単位での制限情報。
account/end_session
無効なcookieを返して、セッションを終了する。
Basic認証？
account/update_delivery_device
自分の device を設定する
2010/12/15現在、error(68)が返る。
account/update_profile_colors
web版twitterの「設定」=>「デザイン」=>「デザインと色を変更する」を更新する。
色を、#fff形式、#ffffff形式のいずれかで指定する。
省略した箇所は変更されない。
account/update_profile_image
web版twitterの「設定」=>「プロフィール」=>「アイコン」を更新する。
account/update_profile_background_image
web版twitterの「設定」=>「デザイン」=>「背景画像」を更新する。
account/update_profile
web版twitterの「設定」=>「プロフィール」=>「名称、位置情報、Web、自己紹介」を更新する。
パラメータのうち1つ以上を指定。省略時は無視される。
お気に入り関連
favorites
指定したユーザーのお気に入り発言(favorites)を取得する。
favorites/create
指定した発言をお気に入りにする。
favorites/destroy
指定した発言のお気に入りを外す。
「指定デバイス」関連
notifications/follow
指定したユーザーの発言を「指定デバイス」に送信する。
※指定するユーザーは、friendになっていること
user_id または screen_name のいずれか１つ指定すること。
notifications/leave
指定したユーザーの発言を「指定デバイス」への送信を解除する。
user_id または screen_name のいずれか１つ指定すること。
ブロック関連
blocks/create
指定したユーザーをブロックする。
指定ユーザーが、friend なら同時にfriendも解除される。
user_id または screen_name のいずれか１つを指定すること。
blocks/destroy
指定したユーザーのブロックを解除する。
user_id または screen_name のいずれか１つを指定すること。
blocks/exists
指定したユーザーをブロックしているかどうか調べる。
user_id または screen_name のいずれか１つを指定すること。
ブロックをしていない、もしくは、アカウントが存在しない場合は、HTTP404が返る。
ブロックしている場合は、ユーザの情報が返ってくる。
blocks/blocking
自分がブロックしているユーザーの一覧を取得。
blocks/blocking/ids
自分がブロックしているユーザーIDの一覧を取得。
検索条件保存
saved_searches
保存されている検索クエリの一覧を取得する。
saved_searches/show
指定した検索クエリの詳細を取得する。
saved_searches/create
指定した検索クエリを保存する。
saved_searches/destroy
指定した検索クエリを削除する。
OAuth関連
oauth/request_token
リクエストトークンを取得する。
本api（OAuth関連）は、ライブラリなどが配布されているので「OAuth」で検索エンジンで探すことをオススメします。
oauth/authorize
ユーザーにアクセス許可を求めます。
OAuthでよく見られるtwitterに転送して許可を求めるページのURLになります。
本api（OAuth関連）は、ライブラリなどが配布されているので「OAuth」で検索エンジンで探すことをオススメします。
oauth/authenticate
ユーザーにアクセス許可を求めます。
webアプリ向けのapiです。
OAuthでよく見られるtwitterに転送して許可を求めるページのURLになります。
本api（OAuth関連）は、ライブラリなどが配布されているので「OAuth」で検索エンジンで探すことをオススメします。
oauth/access_token
アクセストークンを取得します。
本api（OAuth関連）は、ライブラリなどが配布されているので「OAuth」で検索エンジンで探すことをオススメします。
位置情報関連
geo/nearby_places
/geo/nearby_places は現在推奨されていません。代わりに geo/search を使います。(2010/12/16確認)
指定した地域のエリア情報を取得する。
いずれかのパラメータ１つ以上必要。
アメリカ合衆国内にしか対応していない様子。
geo/search
指定した地域のエリア情報を取得する。
アメリカ合衆国内にしか対応していない様子。
geo/similar_places
指定した座標の近くで、類似した場所の候補を取得する。
アメリカ合衆国内にしか対応していない様子。
geo/reverse_geocode
経度緯度から指定した地域のエリア情報を取得する。
アメリカ合衆国内にしか対応していない様子。
geo/id/place_id
指定した場所の詳細情報を取得する。
アメリカ合衆国内にしか対応していない様子。
geo/place
指定した座標に新しい場所を登録する。
アメリカ合衆国内にしか対応していない様子。
規約API
legal/tos
Twitterの利用規約を返す。
※開発者利用規約ではないことに注意。
※このapiは、callback引数をつけてjsonをコールしても、jsonテキストとして返ってくる。(2010/12/16確認)
legal/privacy
Twitterのプライバシーポリシーを返す。
※このapiは、callback引数をつけてjsonをコールしても、jsonテキストとして返ってくる。(2010/12/16確認)
検索関連
search
twitter全体を検索して、一致する発言を返す。
このapiは問題を抱えています。
検索結果の to_user_id と from_user_id を信用しないでください。
他のapiで使われる user_id とは無関係です。
正確な user_id を得るには、 検索結果の screen_name (from_user) を基に users/show を実行して得る必要があります。
