# Threads 關鍵字比對規則（API 與 MCP）

本頁說明關鍵字搜尋的比對規則，適用於：

- `GET /post/search` 與 MCP 工具 `search_posts`
- `GET /post/keyword-trend` 與 MCP 工具 `get_keyword_trend`

想直接看例子，請見[關鍵字範例與清單](/api/guides/search-examples/)。[語意搜尋](/api/semantic-search/)以「意思」比對，不適用本頁的規則。

## 一句話總結

每個關鍵字都會被當成**一個完整片語**：串文內容必須包含這個片語才會被找到。至於怎樣才算「包含」，依語言而不同：

| 語言 | 比對方式 | 找得到 | 找不到 |
| --- | --- | --- | --- |
| 中文 | 逐字比對，字要連續出現 | `蛋白` → 高**蛋白**質早餐 | `減脂` → 減少脂肪 |
| 英文、數字 | 以完整單字比對，不分大小寫 | `AI` → **AI**設計、#**ai**、用 **AI** 寫文案 | `AI` → paid、Taiwan、OpenAI |
| 日文（漢字、平假名） | 與中文相同，逐字比對 | `お金` → **お金**持ち | — |
| 日文（片假名） | 以完整的片假名詞比對 | `コーヒー` → **コーヒー**を飲む | `コーヒー` → アイスコーヒー |
| 韓文 | 以空格隔開的完整詞比對 | `꿀팁` → 오늘의 **꿀팁** | `꿀팁` → 꿀팁을 공유 |

## 中文：逐字比對

中文關鍵字的每個字都必須**依序、連續**出現在串文中。

- `減脂` 找得到「**減脂**餐」、「我在**減脂**」
- `減脂` 找不到「減少脂肪」（字沒有連在一起）
- `蛋白` 也會找到「**蛋白**質」，因為「蛋白」兩個字確實連續出現在裡面

幾個容易忽略的細節：

- **繁簡不互通。** `減肥` 找不到「减肥」。兩種寫法都想找，就把兩個都當成關鍵字送出。
- **標點與空白會被忽略。** `減脂` 也會找到「減，脂」或「減 脂」這類字中間夾著標點或空白的內容。
- **單一個字的範圍很廣。** `貓` 會找到所有含「貓」的串文，包括「熊貓」、「貓咪」。建議至少用兩個字。

## 英文與數字：完整單字比對

英文不是找「字串裡有沒有這幾個字母」，而是找**完整的單字**，而且不分大小寫。

- `coffee`、`Coffee`、`COFFEE` 結果相同
- `AI` 找得到「**AI**設計」、「#**AI**」、「**AI**-generated」：英文緊貼中文、hashtag 或連字號時，仍算獨立的單字
- `AI` 找不到「paid」、「said」、「Taiwan」，也找不到「OpenAI」、「ChatGPT」：因為它們各自是一個完整的單字
- `gram` 找不到「Instagram」、「Telegram」
- 單複數與時態不會合併：`app` 找不到「apps」

多個英文單字組成的關鍵字，單字要依序出現：`work from home` 找得到「**Work From Home** 一年心得」，但找不到連在一起寫的「#workfromhome」。**如果某個名稱有好幾種寫法，請把每種寫法都當成關鍵字送出。**

## 日文

- **漢字與平假名**：與中文相同，逐字比對。`お金` 找得到「**お金**持ち」。
- **片假名**：以**完整的片假名詞**比對。`コーヒー` 找得到「**コーヒー**を飲む」、「**コーヒー**豆」（片假名詞在這裡就結束了），但找不到「アイスコーヒー」、「コーヒーショップ」，因為這些是一整個較長的片假名詞。

想涵蓋複合詞時，請把常見的組合一併送出，例如 `コーヒー`、`アイスコーヒー`、`コーヒーショップ`。

## 韓文

韓文以**空格隔開的完整詞**比對。韓文習慣把助詞直接黏在名詞後面，所以：

- `꿀팁` 找得到「오늘의 **꿀팁**」、「**꿀팁**!」
- `꿀팁` 找不到「꿀팁을 공유합니다」、「꿀팁이」：`꿀팁을`、`꿀팁이` 各是一個完整的詞

建議把常見的助詞變化一起送出，例如 `꿀팁`、`꿀팁을`、`꿀팁이`、`꿀팁은`。`/post/search` 一次最多可送 30 個關鍵字。

:::note[規劃中]
我們正在改進片假名與韓文的比對方式，讓 `コーヒー` 也能找到「アイスコーヒー」、`꿀팁` 也能找到「꿀팁을」。上線後會在這裡更新。
:::

## 多個關鍵字怎麼組合

- **`/post/search`**：多個關鍵字之間是「**或**」（OR），串文符合**任一個**就會出現在結果裡，同一篇串文只會出現一次。一次最多 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=减肥'
```

## Hashtag

串文的標籤（hashtag）會和內文一起被搜尋，搜尋時不需要加 `#`：`減脂` 和 `#減脂` 的結果相同，而且即使內文沒寫「減脂」，只要串文掛了「減脂」這個標籤，也會被找到。

## 會搜到哪些串文

- **以中文、日文、韓文為主的串文。** 以英文或其他語言為主的串文不在搜尋範圍內。
- **回覆也會被搜到。** 結果預設同時包含主串文與回覆，關鍵字趨勢的數量也把回覆算在內。在 `/post/search` 設定 `post_type=thread`（需同時設定 `include_details=true`）即可只看主串文；這個篩選在分頁之後才套用，所以單頁筆數可能少於 `size`。
- **可依地區篩選**：台灣繁體、香港、中國簡體、日本、韓國等，詳見[地區與語言](/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 讀取最新數據。