# Threads 키워드 매칭 규칙(API와 MCP)

이 페이지에서는 키워드 검색의 매칭 규칙을 설명합니다. 적용 대상은 다음과 같습니다.

- `GET /post/search`와 MCP 도구 `search_posts`
- `GET /post/keyword-trend`와 MCP 도구 `get_keyword_trend`

예시부터 보려면 [키워드 예시와 목록](/ko/api/guides/search-examples/)을 참고하세요. [시맨틱 검색](/ko/api/semantic-search/)은 「의미」로 매칭하므로 이 페이지의 규칙이 적용되지 않습니다.

## 한 문장 요약

모든 키워드는 **하나의 완전한 구문**으로 처리됩니다. 게시물 내용에 이 구문이 포함되어 있어야 검색됩니다. 무엇을 「포함」으로 보는지는 언어마다 다릅니다.

| 언어 | 매칭 방식 | 검색됨 | 검색 안 됨 |
| --- | --- | --- | --- |
| 중국어 | 글자 단위 매칭, 글자가 연속으로 나와야 함 | `蛋白` → 高**蛋白**質早餐 | `減脂` → 減少脂肪 |
| 영어, 숫자 | 완전한 단어 단위 매칭, 대소문자 구분 없음 | `AI` → **AI**設計, #**ai**, 用 **AI** 寫文案 | `AI` → paid, Taiwan, OpenAI |
| 일본어(한자, 히라가나) | 중국어와 마찬가지로 글자 단위 매칭 | `お金` → **お金**持ち | — |
| 일본어(가타카나) | 완전한 가타카나 단어 단위 매칭 | `コーヒー` → **コーヒー**を飲む | `コーヒー` → アイスコーヒー |
| 한국어 | 공백으로 구분된 완전한 단어 단위 매칭 | `꿀팁` → 오늘의 **꿀팁** | `꿀팁` → 꿀팁을 공유 |

## 중국어: 글자 단위 매칭

중국어 키워드의 모든 글자가 게시물 안에 **순서대로, 연속해서** 나와야 합니다.

- `減脂`로 검색하면 「**減脂**餐」, 「我在**減脂**」를 찾습니다
- `減脂`로 검색하면 「減少脂肪」을 찾지 못합니다(글자가 붙어 있지 않음)
- `蛋白`으로 검색하면 「**蛋白**質」도 찾습니다. 「蛋白」 두 글자가 실제로 연속해서 들어 있기 때문입니다

놓치기 쉬운 세부 사항:

- **번체와 간체는 서로 매칭되지 않습니다.** `減肥`로는 「减肥」를 찾지 못합니다. 두 표기를 모두 찾으려면 둘 다 키워드로 보내세요.
- **문장 부호와 공백은 무시됩니다.** `減脂`로 검색하면 「減，脂」나 「減 脂」처럼 글자 사이에 문장 부호나 공백이 끼어 있는 내용도 찾습니다.
- **한 글자 키워드는 범위가 매우 넓습니다.** `貓`로 검색하면 「熊貓」, 「貓咪」를 포함해 「貓」가 들어간 모든 게시물을 찾습니다. 최소 두 글자 이상을 권장합니다.

## 영어와 숫자: 완전한 단어 단위 매칭

영어는 「문자열 안에 이 글자들이 있는지」를 찾는 것이 아니라 **완전한 단어**를 찾으며, 대소문자는 구분하지 않습니다.

- `coffee`, `Coffee`, `COFFEE`는 결과가 같습니다
- `AI`로 검색하면 「**AI**設計」, 「#**AI**」, 「**AI**-generated」를 찾습니다. 영어가 중국어나 해시태그, 하이픈에 붙어 있어도 독립된 단어로 취급합니다
- `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=减肥'
```

## 해시태그

게시물의 태그(해시태그)는 본문과 함께 검색되므로, 검색할 때 `#`을 붙일 필요가 없습니다. `減脂`와 `#減脂`의 결과는 같으며, 본문에 「減脂」가 없더라도 게시물에 「減脂」 태그가 달려 있으면 검색됩니다.

## 검색 대상 게시물

- **중국어, 일본어, 한국어 위주의 게시물.** 영어나 다른 언어 위주의 게시물은 검색 대상이 아닙니다.
- **답글도 검색됩니다.** 결과에는 기본적으로 원글과 답글이 모두 포함되며, 키워드 트렌드의 수에도 답글이 포함됩니다. `/post/search`에서 `post_type=thread`를 설정하면(`include_details=true`도 함께 설정해야 함) 원글만 볼 수 있습니다. 이 필터는 페이지를 나눈 뒤에 적용되므로 한 페이지의 건수가 `size`보다 적을 수 있습니다.
- **지역별 필터링**: 대만 번체, 홍콩, 중국 간체, 일본, 한국 등으로 필터링할 수 있습니다. 자세한 내용은 [지역과 언어](/ko/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에서 최신 데이터를 실시간으로 읽어 옵니다.