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

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

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

예시부터 보려면 키워드 예시와 목록을 참고하세요. 시맨틱 검색은 「의미」로 매칭하므로 이 페이지의 규칙이 적용되지 않습니다.

한 문장 요약

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

언어	매칭 방식	검색됨	검색 안 됨
중국어	글자 단위 매칭, 글자가 연속으로 나와야 함	蛋白 → 高蛋白質早餐	減脂 → 減少脂肪
영어, 숫자	완전한 단어 단위 매칭, 대소문자 구분 없음	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개의 키워드를 보낼 수 있습니다.

개선 예정

가타카나와 한국어의 매칭 방식을 개선하고 있습니다. コーヒー로 「アイスコーヒー」를, 꿀팁으로 「꿀팁을」을 찾을 수 있게 할 예정이며, 적용되면 이 페이지에 안내하겠습니다.

여러 키워드의 조합 방식

• /post/search: 여러 키워드는 「또는」(OR) 관계입니다. 게시물이 키워드 중 하나라도 맞으면 결과에 나오며, 같은 게시물은 한 번만 나옵니다. 한 번에 최대 30개 키워드를 보낼 수 있습니다. 현재 「그리고」(AND)는 지원하지 않습니다.
• /post/keyword-trend: 키워드마다 트렌드 선이 따로 계산되며 서로 영향을 주지 않습니다. 한 번에 최대 10개 키워드를 보낼 수 있습니다.

여러 키워드를 보낼 때는 같은 매개변수를 반복하세요.

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보다 적을 수 있습니다.
• 지역별 필터링: 대만 번체, 홍콩, 중국 간체, 일본, 한국 등으로 필터링할 수 있습니다. 자세한 내용은 지역과 언어를 참고하세요.

검색 기간

엔드포인트	기간을 지정하지 않았을 때	최대 조회 기간
/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에 나뉘며, 마지막 날은 「오늘 지금까지」의 부분 집계입니다.

주의

가장 흔한 질문은 「어제 게시물이 왜 검색되지 않나요?」입니다. /post/search는 기간을 지정하지 않으면 최근 3시간만 검색합니다. max_age_hours=24 등으로 기간을 추가하세요.

좋아요 수와 답글 수는 얼마나 최신인가요

검색 결과의 좋아요 수와 답글 수는 Throk이 해당 게시물을 마지막으로 수집했을 때의 수치입니다. 새 게시물과 지금 뜨고 있는 게시물은 더 자주 업데이트되고, 오래되었거나 주목받지 못한 게시물은 업데이트 간격이 길어 Threads에서 보이는 수치보다 적을 수 있습니다.

현재 수치가 필요하면 GET /live/posts(MCP: get_live_posts)를 사용하세요. Threads에서 최신 데이터를 실시간으로 읽어 옵니다.