クエリを組み立てる

search エンドポイントは GET リクエストで単一のクエリを受け取り、クエリに一致する履歴投稿のセットを返します。クエリは、さまざまな投稿属性に対して一致を行う演算子で構成されます。

クエリの制限

クエリは、使用しているアクセスレベルによって制限されます:

Access level	Recent search	Full-archive search
Self-serve	512 文字	1,024 文字
Enterprise	4,096 文字	4,096 文字

演算子の可用性

ほとんどの演算子はすべての開発者が利用できますが、特定のアクセスレベルのみに提供される演算子もあります:

Core 演算子: 任意の Project で利用可能
Advanced 演算子: 特定のアクセスレベルを持つ Project で利用可能

利用可能性の詳細は、演算子の完全な一覧を参照してください。

演算子の種類: standalone と conjunction-required

Standalone 演算子 は単独でも、他の演算子(conjunction-required の演算子を含む)と組み合わせても使用できます。たとえば、#hashtag は standalone 演算子であるため、次のクエリは動作します:

#xapiv2

Conjunction-required 演算子 は単独でクエリとしては使用できず、少なくとも 1 つの standalone 演算子を含む場合にのみ使用できます。これらの演算子を単独で使うと非常に大量の投稿に一致してしまうためです。たとえば、以下のクエリは conjunction-required 演算子のみを含んでいるため、サポートされていません:

has:media

has:links OR is:retweet

standalone 演算子(たとえばフレーズ "X data")を追加すると、クエリは正しく動作します:

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

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

以下のツールを使って複数の演算子を組み合わせられます:

Operator	Description	Example
AND(空白)	両方の条件を満たす投稿に一致	`snow day #NoSchool` は “snow” AND “day” AND #NoSchool を含む投稿に一致
OR	いずれかの条件を満たす投稿に一致	`grumpy OR cat OR #meme` は “grumpy” OR “cat” OR #meme を含む投稿に一致
NOT(ダッシュ)	この条件を満たす投稿を除外	`cat #meme -grumpy` は “cat” と #meme を含み、“grumpy” を含まない投稿に一致
グルーピング(括弧)	演算子をグループ化	`(grumpy cat) OR (#meme has:images)` はいずれかのグループに一致

否定に関する注意

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

演算の順序

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

AND ロジックで接続された演算子が最初にまとめられます
次に、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 には一致しません。

Quote Tweet の一致

Search Posts を使用する場合、演算子は Quote Tweet の内容には一致しますが、引用元のオリジナル投稿の内容には一致しません。

Filtered stream は挙動が異なり、Quote Tweet の内容と元の投稿の内容の両方に一致します。

具体性と効率

単一のキーワードやハッシュタグのような広範な演算子の使用は推奨されません。大量の投稿に一致し、使用量上限をすぐに消費してしまうためです。

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

具体的に始めて、その後広げる — 関連する結果を返すターゲットを絞ったクエリを作成
複数の演算子を使う — 演算子を組み合わせて結果を絞り込む
文字数に注意 — クエリ文字列全体が上限にカウントされます

進化の例:

# 広すぎる - 1 日 200,000 件以上の投稿
happy

# 改善 - 言語フィルターと除外を追加
(happy OR happiness) lang:en -birthday -is:retweet

# さらに改善 - 59 文字でより具体的
(happy OR happiness) place_country:GB -birthday -is:retweet

クエリを反復的に構築する

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

happy OR happiness

ステップ 2: 結果を基にテストして絞り込む

多くの言語の投稿があることに気付きました。言語フィルターを追加します:

(happy OR happiness) lang:en

誕生日のお祝いが含まれています。それらと Retweet を除外します:

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

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

より多くの感情を捉えたいので、関連キーワードを追加します:

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

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

Holiday の投稿が出てきました。除外します:

(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"

クエリの例

自然災害を追跡する

ハリケーン Harvey に関する気象機関からの投稿に一致: クエリ:

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

Post annotations を使用する

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

Getting Started

Products

Fundamentals

Partners & Customers

Resources

クエリを組み立てる

クエリの制限

演算子の可用性

演算子の種類: standalone と conjunction-required

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

演算の順序

句読点、発音区別符、大文字小文字の区別

Quote Tweet の一致

具体性と効率

クエリを反復的に構築する

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

ステップ 2: 結果を基にテストして絞り込む

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

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

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

クエリの例

自然災害を追跡する

#nowplaying のセンチメント分析

Post annotations を使用する

ツール

Query Builder ツール

次のステップ

演算子リファレンス

検索クイックスタート

統合ガイド

​クエリの制限

​演算子の可用性

​演算子の種類: standalone と conjunction-required

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

​演算の順序

​句読点、発音区別符、大文字小文字の区別

​Quote Tweet の一致

​具体性と効率

​クエリを反復的に構築する

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

​ステップ 2: 結果を基にテストして絞り込む

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

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

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

​クエリの例

​自然災害を追跡する

​#nowplaying のセンチメント分析

​Post annotations を使用する

​ツール

Query Builder ツール

​次のステップ

演算子リファレンス

検索クイックスタート

統合ガイド

クエリの制限

演算子の可用性

演算子の種類: standalone と conjunction-required

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

演算の順序

句読点、発音区別符、大文字小文字の区別

Quote Tweet の一致

具体性と効率

クエリを反復的に構築する

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

ステップ 2: 結果を基にテストして絞り込む

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

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

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

クエリの例

自然災害を追跡する

#nowplaying のセンチメント分析

Post annotations を使用する

ツール

次のステップ