> ## Documentation Index
> Fetch the complete documentation index at: https://docs.x.com/llms.txt
> Use this file to discover all available pages before exploring further.

# クエリを組み立てる

> search エンドポイントは GET リクエストで単一のクエリを受け取り、クエリに一致する履歴投稿のセットを返します。integrate を扱う X API v2 スタンダードティアのリファレンス。

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

***

## クエリの制限

クエリは、使用している[アクセスレベル](/x-api/getting-started/about-x-api)によって制限されます:

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

***

## 演算子の可用性

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

* **Core 演算子:** 任意の [Project](/resources/fundamentals/developer-apps) で利用可能
* **Advanced 演算子:** 特定のアクセスレベルを持つ Project で利用可能

利用可能性の詳細は、[演算子の完全な一覧](/x-api/posts/search/integrate/operators)を参照してください。

***

## 演算子の種類: 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)` はいずれかのグループに一致             |

<Note>
  **否定に関する注意**

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

***

## 演算の順序

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* に一致します。

<Note>
  **Filtered stream は挙動が異なります**

  [Filtered stream ルールを組み立てる](/x-api/posts/filtered-stream/integrate/build-a-rule)場合、アクセント付きのキーワードはアクセントを含む投稿にのみ一致します。たとえば `Diacrítica` は *Diacrítica* のみに一致し、*Diacritica* には一致しません。
</Note>

***

## Quote Tweet の一致

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

<Note>
  [Filtered stream](/x-api/posts/filtered-stream/introduction) は挙動が異なり、Quote Tweet の内容と元の投稿の内容の両方に一致します。
</Note>

***

## 具体性と効率

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

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

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

**進化の例:**

```
# 広すぎる - 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 エンコードします:

```bash theme={null}
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](/x-api/posts/lookup/introduction) を `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
```

***

## ツール

<Card title="Query Builder ツール" icon="wrench" href="https://developer.x.com/apitools/query?query=">
  クエリをインタラクティブに構築・テスト
</Card>

***

## 次のステップ

<CardGroup cols={2}>
  <Card title="演算子リファレンス" icon="https://mintcdn.com/x-preview/ygI6sSJPehlc0qNT/icons/xds/icon-bulleted-list.svg?fit=max&auto=format&n=ygI6sSJPehlc0qNT&q=85&s=b9bf8323233df59c682b0fec8e3f88d5" href="/x-api/posts/search/integrate/operators" width="24" height="24" data-path="icons/xds/icon-bulleted-list.svg">
    利用可能な演算子の完全なリスト
  </Card>

  <Card title="検索クイックスタート" icon="https://mintcdn.com/x-preview/oR-aRNyj1BKPJtxM/icons/xds/icon-rocket.svg?fit=max&auto=format&n=oR-aRNyj1BKPJtxM&q=85&s=b978d7a9225de31709efbbed5b84e92d" href="/x-api/posts/search/quickstart/recent-search" width="24" height="24" data-path="icons/xds/icon-rocket.svg">
    最初の検索リクエストを行う
  </Card>

  <Card title="統合ガイド" icon="https://mintcdn.com/x-preview/Vn2KEkZaPF9LiPi3/icons/xds/icon-book.svg?fit=max&auto=format&n=Vn2KEkZaPF9LiPi3&q=85&s=22ac564792481d14ae36a941546039c8" href="/x-api/posts/search/integrate/overview" width="24" height="24" data-path="icons/xds/icon-book.svg">
    完全な統合ドキュメント
  </Card>
</CardGroup>