TikTok Top Search
TikTok Top 검색은 키워드나 문구를 중심으로 동영상과 포토 캐러셀(여러 장의 이미지로 이루어진 게시물)을 한데 모아 보여 줍니다. 캡션, 크리에이터 정보, 미디어, 상호작용 수치를 통해 같은 주제가 서로 다른 콘텐츠 형식에서 어떻게 나타나는지 비교할 수 있습니다.
TikTok Top Search API 주요 기능
- 한 번의 검색으로 동영상과 이미지 게시물 찾기같은 키워드 검색으로 동영상 게시물과 포토 캐러셀을 모두 받을 수 있으며, type 필드로 형식을 구분하므로 하나의 데이터셋에 함께 두거나 따로 나누어 검토할 수 있습니다.
- 정렬 기준과 게시 기간 선택일치하는 콘텐츠를 관련도, 게시 날짜, 좋아요 수 기준으로 정렬하고 게시 시각 필터를 더해, 살펴보려는 종류의 콘텐츠로 반환 범위를 좁힙니다.
- 콘텐츠를 크리에이터·수치와 함께 확인결과마다 캡션, 크리에이터 정보, 미디어 링크, 제공되는 상호작용 수치가 함께 담겨 있어, 게시물의 주제와 형식을 게시한 계정과 연결해 볼 수 있습니다.
TikTok Top Search API 매개변수
| 매개변수 | 필수 | 설명 |
|---|---|---|
query | 필수 | 찾고 싶은 대상을 나타내는 키워드 또는 문구로, 필수 값입니다(예: coffee, home workout). TikTok 게시물 URL이 아니라 검색 텍스트를 입력하세요. |
sort_by | 선택 | 정렬 기준이며 선택 사항입니다. relevance는 관련도가 높은 순, date는 게시 날짜순, likes는 좋아요 수순입니다. 기본값은 relevance입니다. |
published_within | 선택 | 게시 시각 범위이며 선택 사항입니다. day는 어제, week는 이번 주, month는 이번 달, three_months는 최근 3개월, six_months는 최근 6개월을 선택합니다. 비워 두면 추가 게시 시각 필터를 적용하지 않습니다. |
region | 선택 | US, GB 같은 두 글자 지역 코드이며 선택 사항입니다. 검색에서 접근할 수 있는 콘텐츠가 달라지지만, 반환된 게시물이나 크리에이터가 해당 국가에 있다는 증거는 아닙니다. |
results_limit | 선택 | 콘텐츠 레코드의 최대 개수이며 선택 사항으로 1~2000 사이이고 기본값은 100입니다. 동영상과 포토 캐러셀이 모두 이 총량에 포함되며, 더 적게 반환될 수 있습니다. |
TikTok Top Search API 사용 방법
이 요청은 백그라운드 수집 작업을 시작하므로 첫 응답에는 완성된 데이터가 아니라 작업 ID가 담겨 있습니다. 이 ID로 진행 상황을 확인하고 결과를 가져옵니다.
- 주제 키워드를 입력하고, 관련도·날짜·좋아요 수 중 가장 유용한 정렬 기준을 고른 뒤 결과 수 제한을 정합니다. 게시 기간이나 지역은 필요할 때만 추가하세요.
- 예제를 실행하기 전에 $SOCQ_API_KEY를 자신의 API 키로 바꾸거나 해당 환경 변수를 설정합니다. 아래와 같이 Authorization 헤더와 함께 JSON 입력을 POST /v1/tiktok/top-search로 보내고, 응답의 task_id를 저장합니다.
- 저장한 ID로 GET /v1/tasks/{task_id}를 호출해 진행 상황을 확인합니다. queued는 대기 중, running은 수집 진행 중, retrying은 재시도 중이라는 뜻입니다. succeeded가 되면 결과를 읽고, failed이면 error_message에서 이유를 확인합니다.
- 작업이 성공하면 data.results.items를 읽습니다. 이 목록의 각 항목은 동영상 또는 포토 캐러셀 게시물 하나를 나타냅니다. 목록이 비어 있으면 작업은 완료되었지만 반환된 레코드가 없다는 뜻입니다.
- data.results.has_more가 true이면 next_cursor 값은 저장된 결과의 다른 페이지를 가리키는 표식입니다. 이 값을 그대로 GET /v1/tasks/{task_id}?cursor=...의 cursor 매개변수에 복사해 넣고, has_more가 false가 될 때까지 이어서 가져옵니다.
curl -X POST "https://api.socq.ai/v1/tiktok/top-search" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query":"coffee","sort_by":"relevance","results_limit":20}'TikTok Top Search API 추천 활용 사례
- 주제별 콘텐츠 컬렉션 구축: coffee 같은 주제를 검색한 뒤 캡션, 크리에이터 핸들, 링크, 콘텐츠 유형을 동영상과 이미지 게시물 사례가 함께 담긴 검토용 표로 저장합니다.
- 반환된 게시물의 상호작용 수치 비교: 제공되는 좋아요 수, 댓글 수, 공유 수를 게시물의 형식 및 게시 시각과 결합해 비교 시트를 준비하고, 사례가 어떻게 선택되었는지 알 수 있도록 검색어와 필터를 함께 보관합니다.
TikTok Top Search API 활용 팁
- 결과를 표시할 때는 type과 media를 먼저 확인하세요. photo_carousel은 이미지 게시물이므로 동영상 플레이어가 아니라 이미지 갤러리로 보여 주어야 합니다.
- 키워드를 여러 개 수집할 때는 게시물 ID로 중복된 일치 항목을 제거하고, 수집마다 키워드를 연결해 보관해서 같은 게시물이 실수로 여러 번 집계되지 않도록 하세요.
- 워크플로가 동영상만 받는다면 TikTok Search를 사용하고, 동영상과 이미지 게시물이 모두 필요하다면 Top Search를 유지하되 화면에서 두 형식을 모두 처리하세요.
- 사진 결과에 재생 시간이나 재생수가 없으면, 0초 동영상이나 조회되지 않은 게시물로 해석하지 말고 해당 수치를 비워 두세요.
관련 API
TikTok Top Search API 외에 TikTok의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.
- TikTok Profiles API — 사용자 이름으로 공개 프로필 정보, 소개글, 계정 속성, 오디언스 수치를 가져옵니다.
- TikTok Hashtags API — 지정한 해시태그의 공개 동영상, 크리에이터, 미디어, 사운드, 참여도를 수집합니다.
- TikTok Comments API — 공개된 최상위 댓글, 작성자, 참여도, 멘션, 크리에이터 상호작용 플래그를 수집합니다.
- TikTok Videos API — 동영상 URL에서 크리에이터, 캡션, 미디어, 음악, 태그, 멘션, 참여도를 가져옵니다.
- TikTok Search API — 키워드로 공개 동영상을 검색하며, 지원되는 정렬 및 게시 기간 필터를 사용할 수 있습니다.
- TikTok Live Room Info API — 방 ID와 소유자 ID 쌍으로 알고 있는 라이브 방송 하나를 조회하며, 상태, 소유자 맥락, 커버 미디어, 시청자 수를 반환합니다.
- TikTok Comment Replies API
- TikTok Followers List API
- TikTok Following List API
- TikTok User Videos API
- TikTok Trending Feed API
- TikTok Video Transcript API
- TikTok Search Users API
- TikTok Song API
- TikTok Song Videos API
- TikTok Popular Songs API
- TikTok User Live API
- TikTok Audience Demographics API
- TikTok Similar Accounts API
- TikTok Reposts API
- TikTok Playlists API
- TikTok Hashtag Views API
- TikTok Sound Search API
- TikTok Live Search API
- TikTok Photo Search API
- TikTok Trending Searches API
- TikTok Creator Search Insights API
- TikTok Live Ranking API
- TikTok Live Shopping API
- TikTok Fake Views Checker API
- TikTok Comment Keywords API