# Threads キーワード照合ルール（API と MCP）

このページでは、キーワード検索の照合ルールを説明します。対象は次のとおりです。

- `GET /post/search` と MCP ツール `search_posts`
- `GET /post/keyword-trend` と MCP ツール `get_keyword_trend`

具体例を先に見たい場合は、[キーワードの例とリスト](/ja/api/guides/search-examples/)をご覧ください。[セマンティック検索](/ja/api/semantic-search/)は「意味」で照合するため、このページのルールは当てはまりません。

## ひとことでまとめると

キーワードはそれぞれ**1 つのフレーズ全体**として扱われ、投稿の内容がそのフレーズを含む場合にだけヒットします。何をもって「含む」とするかは、言語によって異なります。

| 言語 | 照合方法 | ヒットする | ヒットしない |
| --- | --- | --- | --- |
| 中国語 | 文字単位で照合。文字が連続している必要あり | `蛋白` → 高**蛋白**質早餐 | `減脂` → 減少脂肪 |
| 英語・数字 | 単語単位で照合。大文字・小文字は区別しない | `AI` → **AI**設計、#**ai**、用 **AI** 寫文案 | `AI` → paid、Taiwan、OpenAI |
| 日本語（漢字・ひらがな） | 中国語と同じく文字単位で照合 | `お金` → **お金**持ち | — |
| 日本語（カタカナ） | カタカナ語全体で照合 | `コーヒー` → **コーヒー**を飲む | `コーヒー` → アイスコーヒー |
| 韓国語 | スペースで区切られた語全体で照合 | `꿀팁` → 오늘의 **꿀팁** | `꿀팁` → 꿀팁을 공유 |

## 中国語：文字単位で照合

中国語のキーワードは、すべての文字が**順番どおりに連続して**投稿に出現する必要があります。

- `減脂` は「**減脂**餐」「我在**減脂**」にヒットします
- `減脂` は「減少脂肪」にはヒットしません（文字が連続していないため）
- `蛋白` は「**蛋白**質」にもヒットします。「蛋白」の 2 文字が実際に連続して含まれているためです

見落としやすいポイント：

- **繁体字と簡体字は区別されます。** `減肥` では「减肥」はヒットしません。両方の表記を探したい場合は、両方をキーワードとして送信してください。
- **句読点と空白は無視されます。** `減脂` は「減，脂」や「減 脂」のように、文字の間に句読点や空白が入った内容にもヒットします。
- **1 文字だけだと範囲が広すぎます。** `貓` は「貓」を含むすべての投稿にヒットし、「熊貓」「貓咪」なども含まれます。2 文字以上を使うことをおすすめします。

## 英語と数字：単語単位で照合

英語は「文字列にその文字が含まれるか」ではなく、**単語全体**で照合し、大文字・小文字は区別しません。

- `coffee`、`Coffee`、`COFFEE` の結果は同じです
- `AI` は「**AI**設計」「#**AI**」「**AI**-generated」にヒットします。英語が中国語に隣接している場合や、ハッシュタグ、ハイフンでつながっている場合も、独立した単語として扱われます
- `AI` は「paid」「said」「Taiwan」にも、「OpenAI」「ChatGPT」にもヒットしません。これらはそれぞれ 1 つの単語だからです
- `gram` は「Instagram」「Telegram」にヒットしません
- 単数形・複数形や時制はまとめて扱われません。`app` は「apps」にヒットしません

複数の英単語からなるキーワードは、単語が順番どおりに出現する必要があります。`work from home` は「**Work From Home** 一年心得」にヒットしますが、続けて書かれた「#workfromhome」にはヒットしません。**名称に複数の表記がある場合は、すべての表記をキーワードとして送信してください。**

## 日本語

- **漢字とひらがな**：中国語と同じく、文字単位で照合します。`お金` は「**お金**持ち」にヒットします。
- **カタカナ**：**カタカナ語全体**で照合します。`コーヒー` は「**コーヒー**を飲む」「**コーヒー**豆」にヒットします（カタカナ語がそこで終わっているため）。一方、「アイスコーヒー」「コーヒーショップ」にはヒットしません。これらは全体で 1 つの長いカタカナ語だからです。

複合語もカバーしたい場合は、よく使われる組み合わせもまとめて送信してください。例：`コーヒー`、`アイスコーヒー`、`コーヒーショップ`。

## 韓国語

韓国語は**スペースで区切られた語全体**で照合します。韓国語では助詞を名詞の直後に続けて書くため、次のようになります。

- `꿀팁` は「오늘의 **꿀팁**」「**꿀팁**!」にヒットします
- `꿀팁` は「꿀팁을 공유합니다」「꿀팁이」にはヒットしません。`꿀팁을`、`꿀팁이` はそれぞれ 1 つの語として扱われるためです

よく使われる助詞の付いた形もまとめて送信することをおすすめします。例：`꿀팁`、`꿀팁을`、`꿀팁이`、`꿀팁은`。`/post/search` は一度に最大 30 個のキーワードを送信できます。

:::note[対応予定]
カタカナと韓国語の照合方法を改善し、`コーヒー` で「アイスコーヒー」も、`꿀팁` で「꿀팁을」もヒットするようにする予定です。リリースされたらこのページを更新します。
:::

## 複数キーワードの組み合わせ方

- **`/post/search`**：複数のキーワードは「**または**」（OR）の関係で、投稿が**いずれか 1 つ**に一致すれば結果に含まれます。同じ投稿が重複して返されることはありません。一度に最大 30 個のキーワードを送信できます。「かつ」（AND）には現在対応していません。
- **`/post/keyword-trend`**：キーワードごとに個別のトレンドラインを算出し、互いに影響しません。一度に最大 10 個のキーワードを送信できます。

複数のキーワードを送信するときは、同じパラメータを繰り返します。

```bash
curl -G 'https://premium-api.throk.ai/post/search' \
  -H 'Authorization: Bearer sk-throk-...' \
  --data-urlencode 'keywords=減脂' \
  --data-urlencode 'keywords=減肥' \
  --data-urlencode 'keywords=减肥'
```

## ハッシュタグ

投稿のタグ（ハッシュタグ）は本文と一緒に検索されるため、検索時に `#` を付ける必要はありません。`減脂` と `#減脂` の結果は同じです。また、本文に「減脂」と書かれていなくても、投稿に「減脂」のタグが付いていればヒットします。

## 検索の対象になる投稿

- **中国語・日本語・韓国語が中心の投稿。** 英語やその他の言語が中心の投稿は検索対象外です。
- **返信も検索対象です。** 結果にはデフォルトで通常の投稿と返信の両方が含まれ、キーワードトレンドの件数にも返信が含まれます。`/post/search` で `post_type=thread`（`include_details=true` の同時指定が必要）を設定すると、通常の投稿だけに絞り込めます。この絞り込みはページ分割の後に適用されるため、1 ページあたりの件数が `size` より少なくなることがあります。
- **地域で絞り込めます**：台湾の繁体字、香港、中国の簡体字、日本、韓国など。詳しくは[地域と言語](/ja/api/guides/regions/)をご覧ください。

## 検索の対象期間

| エンドポイント | 期間を指定しない場合 | 遡れる最大期間 |
| --- | --- | --- |
| `/post/search` | **直近 3 時間** | 約 90 日（`max_age_hours` の上限は 2160） |
| `/post/keyword-trend` | 直近 7 日（`days=7`） | 90 日（`days` の上限は 90） |
| `/post/hot` | 直近 24 時間 | 30 日 |
| `/post/semantic-search` | 直近 30 日 | 30 日 |

- 時刻のパラメータはすべて **UNIX 秒**で指定します（例：`1790000000`）。
- キーワード検索のデータは約 90 日間保持されます。それより前の投稿はキーワードで見つけることはできません。
- キーワードトレンドは**台湾時間（UTC+8）**の毎日 00:00 で区切ります。最終日は「今日のここまで」の途中の件数です。

:::caution
最も多い質問は「昨日の投稿が検索で見つからないのはなぜか」です。`/post/search` で期間を指定しない場合、検索対象は直近 3 時間だけです。`max_age_hours=24` などの期間を指定してください。
:::

## いいね数と返信数の鮮度

検索結果のいいね数と返信数は、Throk がその投稿を最後に取得した時点の数値です。新しい投稿やバズっている最中の投稿は頻繁に更新されますが、古い投稿や反応の少ない投稿は更新間隔が長く、Threads 上で見える数値より少ないことがあります。

**現時点**の数値が必要な場合は、`GET /live/posts`（MCP：`get_live_posts`）を使ってください。Threads から最新のデータをリアルタイムで取得します。