サイトのトップへ戻る

Twitter 開発者 ドキュメント日本語訳

ストリーミングAPI のリクエストパラメータ

  1. delimited
  2. stall_warnings
  3. filter_level
  4. language
  5. follow
  6. track
  7. locations
  8. count
  9. with
  10. replies
  11. stringify_friend_id

以下のリクエストパラメータを使用して、ストリーミングAPIエンドポイントから取得するデータを指定します:



delimited

特に注意書きがない限り、このパラメータは全てのストリームエンドポイントで使用できます。

このパラメータに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.



stall_warnings

特に注意書きがない限り、このパラメータは全てのストリームエンドポイントで使用できます。

このパラメータに 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
  }
}


filter_level

特に注意書きがない限り、このパラメータは全てのストリームエンドポイントで使用できます。

このパラメータに nonelowmedium のどれかを設定すると、ツイートをストリームの取り込むのに必要な属性filter_levelの最小値が設定されます。既定値は noneで、使用可能な全てのツイートを取得することができます。

エンドユーザーにツイートストリームを表示する場合は (例えば、プレゼンテーションや会議で使うダッシュボードやライブフィード)、mediumを設定することをお勧めします。



language

特に注意書きがない限り、このパラメータは全てのストリームエンドポイントで使用できます。

Twitterの高度な検索ページの言語一覧に対応するBCP 47の言語識別子をコンマ区切りでまとめた一覧をこのパラメータに設定すると、指定した言語で書かれているツイートのみを返します。例えば、 language=en と指定して接続すると、英語のツイートのみを検出します。



follow

ストリーム上で流すツイートのツイート主を示すユーザーIDをコンマ区切りでまとめた一覧。フォーロープロテクトしているユーザーはサポートしていません。 指定した各ユーザーについて、ストリームは以下のものを取り込みます:

  • 指定したユーザーがつぶやいたツイート。
  • 指定したユーザーにリツイートされたツイート。
  • 指定したユーザーがつぶやいたツイートへのリプライ。
  • 指定したユーザーがつぶやいたツイートのリツイート。
  • リプライボタンを押さずに作成された手動リプライ (例えば “@twitterapi I agree”)。

ストリームは以下のものは取り込みません:

  • 指定したユーザーについて言及しているツイート (例えば “Hello @twitterapi!”).
  • リツイートボタンを押さずに作成された手動リツイート (例えば “RT @twitterapi The API is great”).
  • プロテクトユーザーのツイート。


track

ストリーム上で流すツイートを決めるために使われるフレーズをコンマ区切りでまとめた一覧。 フレーズは一つ以上の用語をスペースで区切っても良く、用語の全てがツイート内で使用されていた場合は、使用順序や大文字小文字の区別に関わらずそのフレーズに合致したと見なします。 このモデルから、コンマは論理積(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
“Twitter”
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!


locations

ツイートを絞り込むための領域範囲を設定する経度と緯度の組み合わせを、コンマ区切りでまとめた一覧。 設定した領域範囲内に位置するツイートのみが取得されます。— 検索用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のみを取得するには、フィルタしたストリームを読み込んだ後にプログラム内で追加のフィルタを実施しなければなりません。

リツイートはこのパラメータでは抽出 できない ので注意してください。ツイートは位置情報を持っていますが、リツイートは位置情報を持っていません。



count

このパラメータはサイトストリームで使用できます。

This parameter requires elevated access to use.

エンドポイントへ再接続する場合、アクセスの多いクライアントではcountパラメータを設定して、接続が切断が発生した間に取得できなかったメッセージの埋め戻しを行うことができます。設定できる値は 1 から 150000 、もしくは -1 から -150000の数値です。 正の数字が設定されると、クライアントへ埋め戻し用データが配信された後に the stream will transition to live values 。 負の数字が設定されると、クライアントへ埋め戻し用データが配信された後にストリームは切断されます。これはデバッグの際の便利です。

高い値を設定すると後続の処理で接続が切断される可能性が高まるので、このパラメータを使用する際には慎重に検討して下さい。 分かりやすいように、クライアントが埋め戻しを使わずに接続するケースを考えてみましょう。 接続が確立されると、Twitter は固定サイズのキューを割り当て、クライアントへストリーミング配信するメッセージを追加します。クライアントの読み込みが遅すぎる場合、キューは一杯になってしまいます。一杯になると、 Twitter はクライアントとの接続を切断します:

Image showing a queue filling up and a disconnect when full

埋め戻しのためにクライアント接続された時、キューにはいくつかのメッセージが即座に追加されます。 埋め戻し領域を確保している分だけ切断されるまでのバッファ領域が少なくなっているため、クライアントは、このメッセージがキューに追加される速度よりも速く、メッセージの読み込みを行わなければなりません。

Image showing a smaller queue after backfill is requested


with

GET userGET siteで使用できます。

with パラメータでは、ユーザーストリームとサイトストリームのクライアントへ送るメッセージのタイプを制御します。

  • サイトストリームの既定値は with=userで、そのストリームと関連のあるユーザーのメッセージのみが流れます。
  • ユーザーストリームの既定値はwith=followingsで、そのユーザーがフォローしているアカウントのメッセージを追加します。ユーザーのホームタイムラインの表示と同じ内容になります。

既定値は違いますが、サイトストリームとユーザーストリームにはそれぞれuserパラメータとfollowingsパラメータの両方を設定できます。



replies

GET userGET siteで使用できます。

既定では、 @replies はリプライの送信者と受信者がお互いにフォローし合っている場合にのみ送信されます。例えば、アリスはボブをフォローしているが、キャロルをフォローしていないケースを考えてください。既定では、ボブがキャロルに @replies を送った場合、アリスにそのツイートは表示されません。これは twitter.com と api.twitter.com の動作に準じています。 ストリーム接続でそうしたツイートを取得するには、接続時に replies=all と設定してください。



stringify_friend_ids

GET userGET siteで使用できます。

既定では、ユーザーストリームとトサイトストリームはフレンドリスト を数値型の配列として送信します (stringify_friend_ids=falseと設定した時の動きと同じです。)。 しかし、Twitter のユーザー数が増えるにつれて、ユーザーIDが32ビット整数の上限へ急速に達しつつあります。上限を超えた場合、あなたのプログラムで64ビット整数を制御できるようにする必要があります。いくつかの言語やライブラリ(JSON デコーダを含む)は JSON で使う整数を32ビットと想定しており、したがって予測不能な誤動作をする可能性をはらんでいます。 64ビット整数問題に直面した場合は、stringify_friend_ids=true のパラメータを使用してフレンドリストを(数値型ではなく)文字列型の配列として取得することをお勧めします。 このパラメータを使用した場合、friends配列のあった位置には代わりにfriends_str 配列が取得されるので注意してください。 ペイロードの例については Friends List メッセージタイプを参照してください。