search エンドポイントは GET リクエストで単一のクエリを受け取り、そのクエリに一致する過去の Post の集合を返します。クエリは、さまざまな Post の属性にマッチさせるためのオペレーターで構成されます。
使用しているアクセスレベルに応じて、クエリには制限があります。
ベーシックまたはプロのアクセスの場合、Recent Search エンドポイント向けのクエリは最大512文字までです。
プロのアクセスの場合、Full Archive Search エンドポイント向けのクエリは最大1,024文字までです。
ほとんどの演算子はすべての開発者が利用できますが、特定のアクセスレベルに限定されるものもあります。各演算子の提供範囲は、以下のラベルを用いて演算子一覧の表に示しています。
- Core operators: いずれのProjectでも利用可能。
- Advanced operators: 特定のアクセスレベルを持つ Project を使用する場合に利用可能。
単体オペレーター は、それ単独でも、他の任意のオペレーター（連結が必要なものを含む）と組み合わせても使用できます。
たとえば、次のクエリは単体オペレーターである #hashtag を使用しているため動作します。
#xapiv2
連結必須 オペレーターは、クエリ内で単独では使用できません。少なくとも1つの単体オペレーターがクエリに含まれている場合にのみ使用できます。これは、これらのオペレーターを単独で使うと条件があまりに一般的になり、極めて大量の Post に一致してしまうためです。
たとえば、次のクエリは連結必須オペレーターしか含まないためサポートされません。
has:media
has:links OR is:retweet
"X data" のような単体オペレーターを追加すれば、そのクエリは正しく動作します。
"X data" has:mentions (has:media OR has:links)
1 つのクエリで複数の演算子を組み合わせたい場合、次の方法を使用できます。
| |
|---|
| AND ロジック | 演算子をスペースで続けて並べると、ブールの「AND」ロジックになります。これは、両方の条件を満たす場合にのみ Post が一致することを意味します。たとえば、snow day #NoSchool は、snow と day という用語およびハッシュタグ #NoSchool を含む Post に一致します。 |
| OR ロジック | 演算子の間に OR を挟んで続けて並べると、OR ロジックになります。これは、いずれかの条件を満たす場合に Post が一致することを意味します。たとえば、grumpy OR cat OR #meme を指定すると、少なくとも grumpy または cat という用語、またはハッシュタグ #meme を含む任意の Post に一致します。 |
| NOT ロジック（否定） | キーワード（または任意の演算子）の前にダッシュ（-）を付けると否定（NOT）できます。たとえば、cat #meme -grumpy は、ハッシュタグ #meme と用語 cat を含む Post に一致しますが、用語 grumpy を含まない場合に限ります。よく使われるクエリ句に -is:retweet があり、Retweet には一致しないため、元の Post、Quote Tweet、返信のみに一致します。すべての演算子は否定できますが、否定された演算子を単独で使用することはできません。 |
| グルーピング | 演算子をまとめてグループ化するには、丸括弧を使用できます。たとえば、(grumpy cat) OR (#meme has:images) は、grumpy と cat という用語を含む Post、または画像がありハッシュタグ #meme を含む Post のいずれかを返します。AND が先に適用され、その後に OR が適用される点に注意してください。 |
-is:nullcast は常に否定形でなければなりません。
否定された演算子は単独では使用できません。
丸括弧でまとめた演算子の集合全体を否定しないでください。代わりに、各演算子を個別に否定してください。たとえば、skiing -(snow OR day OR noschool) を使うのではなく、skiing -snow -day -noschool の使用を推奨します。
AND と OR の機能を組み合わせる場合、クエリは次の演算順序で評価されます。
- AND ロジックで結合された演算子が先にまとめて評価される
- 次に OR ロジックで結合された演算子が適用される
例:
apple OR iphone ipad は apple OR (iphone ipad) として評価されますipad iphone OR android は (iphone ipad) OR android として評価されます
あいまいさを避け、意図どおりにクエリを評価させるため、必要に応じて括弧で用語をグループ化してください。
例:
(apple OR iphone) ipadiphone (ipad OR android)
アクセントやダイアクリティカルマークを含むキーワードまたはハッシュタグでクエリを指定すると、アクセント等を含む用語と、通常の文字のみの用語の両方を含むPostテキストに一致します。たとえば、キーワード Diacrítica またはハッシュタグ #cumpleaños を用いたクエリは、チルデ付きの í やエニェを含む Diacrítica や #cumpleaños に加えて、チルデやエニェのない Diacritica や #cumpleanos にも一致します。
アクセントやダイアクリティカルマーク付きの文字は通常の文字と同様に扱われ、語境界としては扱われません。たとえば、キーワード cumpleaños のクエリは、単語 cumpleaños を含むアクティビティにのみ一致し、cumplea、cumplean、または os を含むアクティビティには一致しません。
すべてのオペレーターは大文字小文字を区別せずに評価されます。たとえば、クエリ cat は次のいずれの場合もPostに一致します: cat、CAT、Cat。
filtered stream のマッチング動作は Search Posts とは異なります。building a filtered stream rule の際、アクセントやダイアクリティカルマークを含むキーワードやハッシュタグは、それらのマークを含む用語にのみ一致し、通常の文字のみを用いる用語には一致しない点に留意してください。
たとえば、キーワード Diacrítica またはハッシュタグ #cumpleaños を含む filtered stream ルールは、Diacrítica および #cumpleaños にのみ一致し、チルデ付きの í やエニェのない Diacritica や #cumpleanos には一致しません。
クエリの作成を始める際には、いくつか留意すべき点があります。
- 単一のキーワードや #hashtag のような幅広い「単体」オペレーターのみをクエリに使うのは、一般的に推奨されません。膨大な数のPostに一致してしまう可能性が高いためです。より堅牢なクエリを作成することで、より特定的な一致Postの集合が得られ、ペイロード内のノイズが減り、有用なインサイトを見つけるために精査すべき量を抑えられることが期待できます。
- たとえば、クエリがキーワード
happy だけの場合、1日あたり約200,000〜300,000件のPostが返ってくる可能性があります。
- 条件付きオペレーターを追加すると検索結果が絞り込まれます。例:
(happy OR happiness) place_country:GB -birthday -is:retweet
- 効率的なクエリ作成は、クエリの文字数制限内に収めるうえでも有益です。文字数には、スペースやオペレーターを含むクエリ文字列全体が含まれます。
- たとえば、次のクエリは59文字です:
(happy OR happiness) place_country:GB -birthday -is:retweet
Search Posts エンドポイントを使用する場合、オペレーターは引用元のオリジナルの Post の内容には一致せず、引用ツイートに含まれる内容に一致します。
ただし、filtered stream では、引用されたオリジナルの Post の内容と引用ツイートの内容の両方に一致する点にご留意ください。
クエリは早いうちからこまめにテストする
最初の試行で「正しい」結果を返すクエリを作成できることは稀です。X には、当初は気づきにくい点が非常に多く、上記のクエリ構文を望む検索に的確に合わせるのは難しい場合があります。クエリを作成する際は、定期的に検証することが重要です。
このセクションでは、次のクエリから始め、テストで得られた結果に基づいて調整していきます。
happy OR happiness
結果を活用してクエリを絞り込む
クエリをテストする際は、返ってきた Post を確認し、期待している data が含まれているかを確認してください。広めのクエリと Post の一致候補を網羅するスーパーセットから始めることで、結果を見直して不要なものを除外するようにクエリを絞り込めます。
例のクエリをテストしたところ、さまざまな言語の Post が返ってくることに気付きました。この状況では英語の Post のみを受け取りたいので、lang: オペレーターを追加します:
(happy OR happiness) lang:en
テストでは、人々に誕生日おめでとうを願う Post が多数返ってきたため、否定のキーワードオペレーターとして -birthday を追加します。さらに、オリジナルの Post のみを受け取りたいので、否定の -is:retweet オペレーターも追加します:
(happy OR happiness) lang:en -birthday -is:retweet
必要に応じて網羅性を高める
想定している data が返ってこない一方で、返されるはずの既存の Post があることが分かっている場合は、目的の data を除外している可能性のあるオペレーターを外して、クエリを広げる必要があるかもしれません。
この例では、探している感情を表している他の Post が自分のタイムラインにあるのに、テスト結果には含まれていないことに気づきました。カバレッジを高めるため、excited と elated というキーワードを追加します。
(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet
対象期間内の人気トレンドや突発的な盛り上がりに合わせて調整する
X ではトレンドの移り変わりが早いため、クエリのメンテナンスは継続的・能動的に行う必要があります。クエリを一定期間使う予定がある場合は、受け取っているdataを定期的に確認し、調整が必要かどうか見直すことをおすすめします。
この例では、「happy holidays」と挨拶するPostが混入し始めたことに気づきました。これらのPostを結果に含めたくないため、否定の -holidays キーワードを追加します。
(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays
作成したクエリをリクエストに追加するには、query パラメータを使用します。ほかのクエリパラメータと同様に、作成したクエリは必ず HTTP エンコードしてください。
以下は cURL コマンドを用いた例で、tweet.fields と max_results パラメータを含めています。このコマンドを使用する場合は、$BEARER_TOKEN を自身の Bearer Token に置き換えてください。
curl https://api.x.com/2/tweets/search/recent?query=cat%20has%3Amedia%20-grumpy&tweet.fields=created_at&max_results=100 -H "Authorization: Bearer $BEARER_TOKEN"
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) -is:retweet
以下は、HTTPエンコード、クエリパラメータ、および recent search のURIを適用した場合のクエリです。
https://api.x.com/2/tweets/search/recent?query=-is%3Aretweet%20has%3Ageo%20(from%3ANWSNHC%20OR%20from%3ANHC\_Atlantic%20OR%20from%3ANWSHouston%20OR%20from%3ANWSSanAntonio%20OR%20from%3AUSGS\_TexasRain%20OR%20from%3AUSGS_TexasFlood%20OR%20from%3AJeffLindner1)
次のルールは、ハッシュタグ「#nowplaying」を巡って展開される会話のセンチメントをより的確に把握するために使用できますが、北米で公開されたPostのみに範囲を絞っています。
以下は、HTTPエンコードなしの場合の、ポジティブ用とネガティブ用の2つのクエリ例です。
#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
#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
そして、HTTPエンコード、クエリパラメータ、および recent search のURIを含めると、クエリは次のようになります。
https://api.x.com/2/tweets/search/recent?query=%23nowplaying%20(happy%20OR%20exciting%20OR%20excited%20OR%20favorite%20OR%20fav%20OR%20amazing%20OR%20lovely%20OR%20incredible)%20(place\_country%3AUS%20OR%20place\_country%3AMX%20OR%20place_country%3ACA)%20-horrible%20-worst%20-sucks%20-bad%20-disappointing
https://api.x.com/2/tweets/search/recent?query=%23nowplaying%20(horrible%20OR%20worst%20OR%20sucks%20OR%20bad%20OR%20disappointing)%20(place\_country%3AUS%20OR%20place\_country%3AMX%20OR%20place_country%3ACA)%20-happy%20-exciting%20-excited%20-favorite%20-fav%20-amazing%20-lovely%20-incredible
このルールは、投稿言語が日本語で、猫ではないペットの画像を含むオリジナルのPostを検索するために作成されました。そのために、context: オペレーターを使い、Post annotation 機能を活用しました。まず、Post lookup エンドポイントと tweet.fields=context_annotations fields パラメータを使用して、クエリで用いるべき domain.entity のIDを特定しました。
- 猫に関連するPostは、
domain 66（Interests and Hobbies カテゴリ）と entity 852262932607926273（Cats）を返します。
- ペットに関連するPostは、
domain 65（Interests and Hobbies Vertical）と entity 852262932607926273（Pets）を返します。
HTTPエンコードなしの場合、クエリは次のとおりです。
context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja
HTTPエンコード、クエリパラメータ、recent search のURIを含める場合、クエリは次のとおりです。
https://api.x.com/2/tweets/search/recent?query=context%3A65.852262932607926273%20-context%3A66.852262932607926273%20-is%3Aretweet%20has%3Aimages%20lang%3Aja
さらにサポートが必要な場合は、query builder tool をお試しください。 
