フィルター済みストリームエンドポイントは、ストリームに適用された一連のルールに一致する投稿を配信します。ルールは、さまざまな投稿属性にマッチするオペレーターで構成されます。
複数のルールは、POST /tweets/search/stream/rules エンドポイントを使用して適用できます。ルールを追加し、GET /tweets/search/stream を使用して接続すると、ルールに一致する投稿のみが配信されます。ルールを追加または削除するために、接続を切断する必要はありません。
ルール数の上限は、ご利用のアクセスレベル によって異なります。具体的な上限については、フィルタ済みストリームの概要 を参照してください。
単独演算子 は、それ単体でも、 (結合が必要なものを含めて) 他の任意の演算子と組み合わせても使用できます。たとえば、このルールが有効なのは、#hashtag が単独演算子だからです。
連結必須オペレーター は、それ単体ではルール内で使用できず、少なくとも 1 つの単体オペレーターと組み合わせてのみ使用できます。これは、これらのオペレーターだけを使用すると、マッチする投稿の件数が極めて多くなってしまうためです。たとえば、次のルールは連結必須オペレーターのみで構成されているため、サポートされていません 。
"X data" のような単独の演算子フレーズを追加すると、ルールは正しく機能します。"X data" has:mentions (has:media OR has:links)
複数の演算子は、次の構文を使って組み合わせて利用できます。
Operator Description Example AND (スペース)投稿は両方の条件を満たす必要があります snow day #NoSchool は “snow” と “day” と #NoSchool をすべて含む投稿に一致しますOR 投稿はいずれか一方の条件を満たす必要があります grumpy OR cat OR #meme は “grumpy” または “cat” または #meme を含む投稿に一致しますNOT (ダッシュ)この条件に一致する投稿を除外します cat #meme -grumpy は “cat” と #meme を含み、“grumpy” を含まない投稿に一致しますGrouping (かっこ)演算子をまとめてグループ化します (grumpy cat) OR (#meme has:images) はいずれかのグループに一致します
否定についての注意
sample: 以外のすべての演算子は否定できます演算子 -is:nullcast は常に否定形として使用する必要があります
否定した演算子を単独では使用できません
グループ化した演算子を否定しないでください。skiing -(snow OR day OR noschool) ではなく、skiing -snow -day -noschool を使用してください
AND と OR を組み合わせる場合:
AND ロジックで接続された演算子が先にまとめて評価されます
次に、OR ロジックで接続された演算子が適用されます
例: Query Evaluated as apple OR iphone ipadapple OR (iphone ipad)ipad iphone OR android(iphone ipad) OR android
あいまいさを避けるには、括弧を使用してください:
句読点、ダイアクリティカルマーク、大文字小文字の区別 ダイアクリティカルマーク: アクセント付きの文字を含むフィルタ済みストリームのルールは、そのアクセントを含む投稿にのみ一致します。たとえば、diacrítica は diacrítica には一致しますが、diacritica には一致しません。大文字小文字の区別: すべてのオペレーターは大文字小文字を区別しません。ルール cat は cat 、CAT 、Cat に一致します。検索投稿は挙動が異なります 検索クエリを構築する 場合、アクセント付きのキーワードは、アクセントの有無にかかわらず投稿に一致します。たとえば、Diacrítica は Diacrítica と Diacritica の両方に一致します。filtered stream を使用する場合、演算子は引用ツイートのコンテンツと 引用された元のポストのコンテンツの両方にマッチします。
Search Posts は挙動が異なり、引用ツイートのコンテンツのみにマッチし、元のポストのコンテンツにはマッチしません。単一のキーワードやハッシュタグのような広すぎるオペレーターの使用は推奨されません。非常に大量の投稿にマッチし、接続をすぐに使い切ってしまいます。
効果的なルールを構築するためのヒント:
最初は具体的に、あとから広げる — 関連性の高い結果を返す、ターゲットを絞ったルールを作成する複数のオペレーターを使用する — オペレーターを組み合わせて結果を絞り込む文字数制限に注意する — ルール文字列全体が上限にカウントされる
ルールの段階的な構築例: # Too broad - 200,000+ Posts per day happy # Better - adds language filter and exclusions (happy OR happiness) lang:en -birthday -is:retweet # さらに良い - 59文字、より具体的 (happy OR happiness) place_country:GB -birthday -is:retweet
ステップ 2: 結果に基づいてテストと絞り込みを行う さまざまな言語の投稿が含まれていることに気付きました。言語フィルターを追加します:
(happy OR happiness) lang:en
誕生日のお祝い投稿がヒットしています。これらとリツイートを除外しましょう:
(happy OR happiness) lang:en -birthday -is:retweet
より幅広いセンチメントを捉えられるように、関連するキーワードを追加します:
(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet
ホリデー関連の投稿が見られるようになっています。これらを除外します:
(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays
POST /2/tweets/search/stream/rules を使用して、ルールを追加または削除できます。value (ルール) と、任意の tag (一致する投稿を識別するため) を含む add 用の JSON 本文を送信します。curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ACCESS_TOKEN " \ -d '{ "add": [ {"value": "cat has:media", "tag": "cats with media"}, {"value": "cat has:media -grumpy", "tag": "happy cats with media"}, {"value": "meme", "tag": "funny things"}, {"value": "meme has:images"} ] }'
削除対象のルールIDを指定して、delete の JSON ボディを送信します。
curl -X POST "https://api.x.com/2/tweets/search/stream/rules" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer $ACCESS_TOKEN " \ -d '{ "delete": { "ids": [ "1165037377523306498", "1165037377523306499" ] } }'
ハリケーン・ハービーについて気象機関が発信した投稿にマッチさせます：
{ "value" : "-is:retweet has:geo (from:NWSNHC OR from:NHC_Atlantic OR from:NWSHouston OR from:NWSSanAntonio OR from:USGS_TexasRain OR from:USGS_TexasFlood OR from:JeffLindner1)" , "tag" : "Hurricane Harvey - weather agencies with geo" }
ポジティブな感情: { "value" : "#nowplaying (happy OR exciting OR excited OR favorite OR fav OR amazing OR lovely OR incredible) (place_country:US OR place_country:MX OR place_country:CA) -horrible -worst -sucks -bad -disappointing" , "tag" : "#nowplaying positive" }
否定的な感情: { "value" : "#nowplaying (horrible OR worst OR sucks OR bad OR disappointing) (place_country:US OR place_country:MX OR place_country:CA) -happy -exciting -excited -favorite -fav -amazing -lovely -incredible" , "tag" : "#nowplaying negative" }
context: 演算子を使って、日本語のペット (猫以外) に関する画像付き投稿を検索します。まず、Post lookup で tweet.fields=context_annotations を指定し、domain と entity の ID を特定します。
猫: domain 66, entity 852262932607926273
ペット: domain 65, entity 852262932607926273
{ "value" : "context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja" , "tag" : "Japanese pets with images - no cats" }
フィルタ済みストリーム クイックスタート ストリームに接続する
