クエリを作成する

演算子を使用して検索クエリを構築する方法を学びます

検索エンドポイントは、1 つのクエリを含む GET リクエストを受け取り、そのクエリに一致する過去の投稿の集合を返します。クエリは、さまざまなポストの属性に一致する演算子で構成されます。

---

クエリの制限

使用しているアクセスレベルに応じて、クエリには制限があります。

アクセスレベル	最近の検索	全アーカイブ検索
セルフサービス	512文字	1,024文字
エンタープライズ	4,096文字	4,096文字

---

オペレーターの利用可否

ほとんどのオペレーターはどの開発者でも利用できますが、一部は特定のアクセスレベルに限定されています。

• コアオペレーター： すべてのProjectで利用可能
• アドバンスドオペレーター： 特定のアクセスレベルを持つ Project でのみ利用可能

利用可否の詳細については、オペレーターの一覧を参照してください。

---

演算子の種類: 単独使用可能なものと結合が必要なもの

単独演算子 は、それ単体で、または (結合が必要な演算子を含む) 他の任意の演算子と組み合わせて使用できます。

たとえば、このクエリが有効なのは、#hashtag が単独演算子だからです。

#xapiv2

結合必須の演算子 は、クエリ内で単独では使用できません。少なくとも 1 つ以上の単独で使用可能な演算子と組み合わせて使用する必要があります。これは、これらの演算子だけを使用すると、非常に大量の投稿にマッチしてしまうためです。

たとえば、次のクエリは結合必須の演算子のみで構成されているため、サポートされません。

has:media

has:links OR is:retweet

たとえばフレーズ "X data" のような単独の演算子を追加すると、クエリは正常に動作します。

"X data" has:mentions (has:media OR has:links)

---

ブール演算子とグルーピング

複数の演算子を、次の構文を使って組み合わせます。

Operator	Description	Example
AND (space)	投稿が両方の条件に一致する必要があります	snow day #NoSchool は “snow” AND “day” AND #NoSchool を含む投稿にマッチします
OR	投稿がいずれか一方の条件に一致する必要があります	grumpy OR cat OR #meme は “grumpy” OR “cat” OR #meme を含む投稿にマッチします
NOT (dash)	この条件に一致する投稿を除外します	cat #meme -grumpy は “cat” と #meme を含み、かつ “grumpy” は含まない投稿にマッチします
Grouping (parentheses)	演算子をまとめてグループ化します	(grumpy cat) OR (#meme has:images) はどちらか一方のグループにマッチします

否定に関する注意

• 演算子 -is:nullcast は常に否定形で使用する必要があります
• 否定された演算子だけを単独で使用することはできません
• グループ化された演算子全体を否定しないでください。skiing -(snow OR day OR noschool) の代わりに、skiing -snow -day -noschool を使用してください

---

演算の順序

AND と OR を組み合わせる場合：

1. AND ロジックで接続された演算子が先にまとめて評価される
2. 次に、OR ロジックで接続された演算子が適用される

例:

Query	Evaluated as
apple OR iphone ipad	apple OR (iphone ipad)
ipad iphone OR android	(iphone ipad) OR android

あいまいさを避けるには、かっこを使用します：

(apple OR iphone) ipad

iphone (ipad OR android)

---

句読点、ダイアクリティカルマーク、大文字と小文字の区別

ダイアクリティカルマーク: アクセントやダイアクリティカルマークを含む検索クエリは、それらのアクセントの有無にかかわらず投稿にマッチします。たとえば、Diacrítica は Diacrítica と Diacritica の両方にマッチします。

大文字と小文字の区別: すべてのオペレーターは大文字と小文字を区別しません。クエリ cat は cat、CAT、Cat にマッチします。

Filtered stream の動作は異なります

Filtered stream のルールを構築する場合、アクセント付きのキーワードは、同じくアクセントを含む投稿にのみマッチします。たとえば、Diacrítica は Diacrítica のみにマッチし、Diacritica にはマッチしません。

---

引用ツイートのマッチング

Search Posts を使用する場合、オペレーターは引用ツイートのコンテンツにはマッチしますが、引用された元のポストのコンテンツにはマッチしません。

Filtered stream は挙動が異なり、引用ツイートと元のポストの両方のコンテンツにマッチします。

---

具体性と効率性

単一のキーワードやハッシュタグといった広範なオペレーターの使用は推奨されません。膨大な数の投稿にマッチし、利用上限をすぐに消費してしまいます。

効果的なクエリを構築するためのヒント:

1. 最初は条件を絞り、あとから広げる — 関連性の高い結果を返す、ターゲットを絞ったクエリを作成する
2. 複数のオペレーターを使う — オペレーターを組み合わせて結果を絞り込む
3. 文字数を意識する — クエリ文字列全体が上限にカウントされる

進め方の例:

# 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

---

クエリを段階的に構築する

ステップ1：基本的なクエリから始める

happy OR happiness

Step 2: 結果に基づいてテストし、絞り込む

多くの言語の投稿が含まれていることが分かりました。言語フィルターを追加します:

(happy OR happiness) lang:en

誕生日のお祝いメッセージがヒットしています。これらとリツイートを除外しましょう:

(happy OR happiness) lang:en -birthday -is:retweet

ステップ3: カバレッジを広げる

より多くの感情を捉えられるように、関連キーワードを追加しましょう:

(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet

ステップ 4: トレンドに合わせて調整する

ホリデー関連の投稿がヒットしています。これらを除外します:

(happy OR happiness OR excited OR elated) lang:en -birthday -is:retweet -holidays

---

リクエストにクエリを追加する

query パラメータを指定し、クエリをHTTPエンコードしてください。

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

完全なリクエスト URL：

https://api.x.com/2/tweets/search/recent?query=has%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)%20-is%3Aretweet

#nowplaying の感情分析

ポジティブな感情:

#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

ポストのアノテーションを使用する

context: 演算子を使用して、画像付きの日本語の、猫以外のペットに関する投稿を検索します。

まず、Post lookup で tweet.fields=context_annotations を指定して、domain および entity の ID を特定します。

• Cats: domain 66, entity 852262932607926273
• Pets: domain 65, entity 852262932607926273

クエリ:

context:65.852262932607926273 -context:66.852262932607926273 -is:retweet has:images lang:ja

---

ツール

クエリビルダーツール

クエリを対話的に作成してテストできます

---

次のステップ

演算子リファレンス

利用可能な演算子の一覧

検索クイックスタート

最初の検索リクエストを実行する

連携ガイド

連携のための包括的なドキュメント