以下のリクエストパラメータを使用して、ストリーミングAPIエンドポイントから取得するデータを指定します:
特に注意書きがない限り、このパラメータは全てのストリームエンドポイントで使用できます。
このパラメータにlength
の文字列を設定すると、ストリーム内のステータスを区切らなければならないことを表します。そうすることで、クライアントはステータスメッセージの終わりまでに何バイトを読み込むことになるのかを知ります。 Statuses are represented by a length, in bytes, a newline, and the status text that is exactly length bytes.
各lengthの前には“キープアライブ”用の改行が入ることがあるので注意してください。
例として、 https://stream.twitter.com/1.1/statuses/filter.json?delimited=length&track=twitterapi
とリクエストした場合の応答を見てみましょう:
HTTP/1.1 200 OK Content-Type: application/json Transfer-Encoding: chunked 1953 {"retweet_count":0,"text":"Man I like me some @twitterapi","entities":{"urls":[],"hashtags":[],"user_mentions":[{"indices":[19,30],"name":"Twitter API","id":6253282,"screen_name":"twitterapi","id_str":"6253282"}]},"retweeted":false,"in_reply_to_status_id_str":null,"place":null,"in_reply_to_user_id_str":null,"coordinates":null,"source":"web","in_reply_to_screen_name":null,"in_reply_to_user_id":null,"in_reply_to_status_id":null,"favorited":false,"contributors":null,"geo":null,"truncated":false,"created_at":"Wed Feb 29 19:42:02 +0000 2012","user":{"is_translator":false,"follow_request_sent":null,"statuses_count":142,"profile_background_color":"C0DEED","default_profile":false,"lang":"en","notifications":null,"profile_background_tile":true,"location":"","profile_sidebar_fill_color":"ffffff","followers_count":8,"profile_image_url":"http:\/\/a1.twimg.com\/profile_images\/1540298033\/phatkicks_normal.jpg","contributors_enabled":false,"profile_background_image_url_https":"https:\/\/si0.twimg.com\/profile_background_images\/365782739\/doof.jpg","description":"I am just a testing account, following me probably won't gain you very much","following":null,"profile_sidebar_border_color":"C0DEED","profile_image_url_https":"https:\/\/si0.twimg.com\/profile_images\/1540298033\/phatkicks_normal.jpg","default_profile_image":false,"show_all_inline_media":false,"verified":false,"profile_use_background_image":true,"favourites_count":1,"friends_count":5,"profile_text_color":"333333","protected":false,"profile_background_image_url":"http:\/\/a3.twimg.com\/profile_background_images\/365782739\/doof.jpg","time_zone":"Pacific Time (US & Canada)","created_at":"Fri Sep 09 16:13:20 +0000 2011","name":"fakekurrik","geo_enabled":true,"profile_link_color":"0084B4","url":"http:\/\/blog.roomanna.com","id":370773112,"id_str":"370773112","listed_count":0,"utc_offset":-28800,"screen_name":"fakekurrik"},"id":174942523154894848,"id_str":"174942523154894848"}
The 1953
indicates how many bytes to read off of the stream to get the rest of the Tweet (including
). The next length delimiter will occur exactly after 1953
bytes.
特に注意書きがない限り、このパラメータは全てのストリームエンドポイントで使用できます。
このパラメータに true
の文字列を設定すると、クライアントの接続が切断されそうになった場合に定期メッセージを通知します。
このメッセージはクライアントで遅延が発生している時のみに送信され、最大で5分に1回の割合で発生します。
このパラメータは、 firehoseのような広帯域幅の接続のクライアントで使用するようのが最も良いでしょう。
警告メッセージは以下のようになります:
{ "warning":{ "code":"FALLING_BEHIND", "message":"Your connection is falling behind and messages are being queued for delivery to you. Your queue is now over 60% full. You will be disconnected when the queue is full.", "percent_full": 60 } }
特に注意書きがない限り、このパラメータは全てのストリームエンドポイントで使用できます。
このパラメータに none
か low
か medium
のどれかを設定すると、ツイートをストリームの取り込むのに必要な属性filter_level
の最小値が設定されます。既定値は none
で、使用可能な全てのツイートを取得することができます。
エンドユーザーにツイートストリームを表示する場合は (例えば、プレゼンテーションや会議で使うダッシュボードやライブフィード)、medium
を設定することをお勧めします。
特に注意書きがない限り、このパラメータは全てのストリームエンドポイントで使用できます。
Twitterの高度な検索ページの言語一覧に対応するBCP 47の言語識別子をコンマ区切りでまとめた一覧をこのパラメータに設定すると、指定した言語で書かれているツイートのみを返します。例えば、 language=en
と指定して接続すると、英語のツイートのみを検出します。
ストリーム上で流すツイートのツイート主を示すユーザーIDをコンマ区切りでまとめた一覧。フォーロープロテクトしているユーザーはサポートしていません。 指定した各ユーザーについて、ストリームは以下のものを取り込みます:
ストリームは以下のものは取り込みません:
ストリーム上で流すツイートを決めるために使われるフレーズをコンマ区切りでまとめた一覧。
フレーズは一つ以上の用語をスペースで区切っても良く、用語の全てがツイート内で使用されていた場合は、使用順序や大文字小文字の区別に関わらずそのフレーズに合致したと見なします。
このモデルから、コンマは論理積(OR)、スペースは論理和(AND) と考えることができます (例えば ‘the twitter
’ は the AND twitter
、 ‘the,twitter
’ はthe OR twitter
).
ツイートのテキストと、いくつかのエンティティフィールドが合致判定の対象と見なされます。具体的にいうと、ツイートの text
属性、リンクとメディアの expanded_url
および display_url
、ハッシュタグの text
、ユーザーメンションの screen_name
が合致しているかチェックされます。
各フレーズは1バイトから60バイトまでの範囲にしなけれなりません(60バイトはOK)。
フレーズの完全一致 (検索エンジンなどで、キーワードを引用符で囲んで行う検索) はサポートしていません。
句読点や特殊文字は、隣接している用語の一部と見なされます。そういった意味で、 “hello.” と “hello”は異なる検索用語として扱われますが、 合致判定において句読点の存在を無視されます。そのため、 “hello” は “hello world” と “my brother says hello.” の両方と合致します。 句読点は #hashtag や @mention の一部とは見なされないので注意してください。そのため、句読点を含む検索用語は#hashtags や @mentions と合致しません。
“同等の” ASCII 文字があったとしても、 UTF-8文字では完全一致で判定を行います。 例えば、 “touché” は “touche”を含むツイートとは合致しません。
CJKのようなスペースで区切られない言語は現在サポートしていません。
URLs are considered words for the purposes of matches which means that the entire domain and path must be included in the track query for a Tweet containing an URL to match.
display_url
にはドメインが含まれていないため、合致判定を実行するために必須ではないので注意してください。
Twitter では現在、合致判定を実行する前に “www.example.com” ドメインを “example.com” へ正規化し、URLの検索用語から “www” を省きます。
最後に、特定のドメイン名の全てのメンションを検索するためは (すなわち、サブドメインやパスに関わらず)、“example.com”を検索するパラメータとして “example com”を使う必要があります (検索パラメータの“example” と“com” の間にコンマがないことに気づいたでしょう)。 これだと対象が広すぎるので、あなたのプログラム内で追加の合致パターンを実装してください。この問題に関連したサンプルをもっと知りたいのであれば以下のテーブルを参照してください。
検索例:
パラメータ値 | 合致するツイートは… | 合致しないツイートは… |
---|---|---|
TWITTER “Twitter” twitter. http://twitter.com |
TwitterTracker #newtwitter |
|
Twitter’s | I like Twitter’s new design | Someday I’d like to visit @Twitter’s office |
twitter api,twitter streaming |
The Twitter API is awesome The twitter streaming service is fast Twitter has a streaming API |
I’m new to Twitter |
example.com | Someday I will visit example.com | There is no example.com/foobarbaz |
example.com/foobarbaz |
example.com/foobarbaz www.example.com/foobarbaz |
example.com |
www.example.com/foobarbaz | www.example.com/foobarbaz | |
example com |
example.com www.example.com foo.example.com foo.example.com/bar I hope my startup isn’t merely another example of a dot com boom! |
ツイートを絞り込むための領域範囲を設定する経度と緯度の組み合わせを、コンマ区切りでまとめた一覧。 設定した領域範囲内に位置するツイートのみが取得されます。— 検索用APと違い、ツイート主のプロフィールに記載された位置情報はツイートの選別に使用されません。
各領域範囲には経度と緯度の組み合わせを二つ設定してください。最初に設定した経度・緯度情報が、領域範囲の左下(南西)座標になります:
パラメータ値 | ツイートの検索対象場所 |
---|---|
-122.75,36.8,-121.75,37.8 | サンフランシスコ |
-74,40,-73,41 | ニューヨークシティ |
-122.75,36.8,-121.75,37.8,-74,40,-73,41 |
サンフランシスコ OR ニューヨークシティ |
領域範囲は、他のフィルタ用パラメータと連携した動作はしません。例えば、 track=twitter&locations=-122.75,36.8,-121.75,37.8
と指定してリクエストすると、Twitter という用語を含むツイート(地域情報がないツイートであっても)か、サンフランシスコのエリアでつぶやかれたツイートに合致します。
ストリーミングAPI では以下のヒューリスティックを使用して指定したツイートが領域範囲内のものか判別します:
coordinates
フィールドが設定されている場合、その値が領域範囲内にあるか確認します。このフィールドはgeoJSON の順(経度、緯度の順)に使われるので注意してください。
coordinates
は設定されていないが place
が設定されていた場合、place
で定義された場所が領域範囲と重なるかチェックします。重なっていれば合致していると見なします。
geo
フィールドは非推奨で、ストリーミングAPIでは無視されるので注意してください。
place
に合致する結果を除外したり、指定した領域内に完全に入るplace
のみを取得するには、フィルタしたストリームを読み込んだ後にプログラム内で追加のフィルタを実施しなければなりません。
リツイートはこのパラメータでは抽出 できない ので注意してください。ツイートは位置情報を持っていますが、リツイートは位置情報を持っていません。
このパラメータはサイトストリームで使用できます。
This parameter requires elevated access to use.
エンドポイントへ再接続する場合、アクセスの多いクライアントではcount
パラメータを設定して、接続が切断が発生した間に取得できなかったメッセージの埋め戻しを行うことができます。設定できる値は 1
から 150000
、もしくは -1
から -150000
の数値です。
正の数字が設定されると、クライアントへ埋め戻し用データが配信された後に the stream will transition to live values 。
負の数字が設定されると、クライアントへ埋め戻し用データが配信された後にストリームは切断されます。これはデバッグの際の便利です。
高い値を設定すると後続の処理で接続が切断される可能性が高まるので、このパラメータを使用する際には慎重に検討して下さい。 分かりやすいように、クライアントが埋め戻しを使わずに接続するケースを考えてみましょう。 接続が確立されると、Twitter は固定サイズのキューを割り当て、クライアントへストリーミング配信するメッセージを追加します。クライアントの読み込みが遅すぎる場合、キューは一杯になってしまいます。一杯になると、 Twitter はクライアントとの接続を切断します:
埋め戻しのためにクライアント接続された時、キューにはいくつかのメッセージが即座に追加されます。 埋め戻し領域を確保している分だけ切断されるまでのバッファ領域が少なくなっているため、クライアントは、このメッセージがキューに追加される速度よりも速く、メッセージの読み込みを行わなければなりません。
with
パラメータでは、ユーザーストリームとサイトストリームのクライアントへ送るメッセージのタイプを制御します。
with=user
で、そのストリームと関連のあるユーザーのメッセージのみが流れます。
with=followings
で、そのユーザーがフォローしているアカウントのメッセージを追加します。ユーザーのホームタイムラインの表示と同じ内容になります。
既定値は違いますが、サイトストリームとユーザーストリームにはそれぞれuser
パラメータとfollowings
パラメータの両方を設定できます。
既定では、 @replies はリプライの送信者と受信者がお互いにフォローし合っている場合にのみ送信されます。例えば、アリスはボブをフォローしているが、キャロルをフォローしていないケースを考えてください。既定では、ボブがキャロルに @replies を送った場合、アリスにそのツイートは表示されません。これは twitter.com と api.twitter.com の動作に準じています。
ストリーム接続でそうしたツイートを取得するには、接続時に replies=all
と設定してください。
既定では、ユーザーストリームとトサイトストリームはフレンドリスト を数値型の配列として送信します (stringify_friend_ids=false
と設定した時の動きと同じです。)。
しかし、Twitter のユーザー数が増えるにつれて、ユーザーIDが32ビット整数の上限へ急速に達しつつあります。上限を超えた場合、あなたのプログラムで64ビット整数を制御できるようにする必要があります。いくつかの言語やライブラリ(JSON デコーダを含む)は JSON で使う整数を32ビットと想定しており、したがって予測不能な誤動作をする可能性をはらんでいます。
64ビット整数問題に直面した場合は、stringify_friend_ids=true
のパラメータを使用してフレンドリストを(数値型ではなく)文字列型の配列として取得することをお勧めします。
このパラメータを使用した場合、friends
配列のあった位置には代わりにfriends_str
配列が取得されるので注意してください。
ペイロードの例については Friends List メッセージタイプを参照してください。