tiktok/
top-search

키워드로 TikTok 동영상과 포토 캐러셀을 검색하고, 캡션, 크리에이터 정보, 미디어 링크, 참여도 수치를 하나의 JSON 목록으로 함께 반환합니다.

TikTok Top Search API

동영상과 포토 캐러셀
키워드 검색
정렬 및 게시 기간 필터
결과당 0.7 크레딧
준비됨
준비됨

매개변수를 입력하고 요청을 전송하세요. 작업 상태와 정규화된 결과가 여기에 표시됩니다.

README

SocQ 작성 · 업데이트

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로 진행 상황을 확인하고 결과를 가져옵니다.

  1. 주제 키워드를 입력하고, 관련도·날짜·좋아요 수 중 가장 유용한 정렬 기준을 고른 뒤 결과 수 제한을 정합니다. 게시 기간이나 지역은 필요할 때만 추가하세요.
  2. 예제를 실행하기 전에 $SOCQ_API_KEY를 자신의 API 키로 바꾸거나 해당 환경 변수를 설정합니다. 아래와 같이 Authorization 헤더와 함께 JSON 입력을 POST /v1/tiktok/top-search로 보내고, 응답의 task_id를 저장합니다.
  3. 저장한 ID로 GET /v1/tasks/{task_id}를 호출해 진행 상황을 확인합니다. queued는 대기 중, running은 수집 진행 중, retrying은 재시도 중이라는 뜻입니다. succeeded가 되면 결과를 읽고, failed이면 error_message에서 이유를 확인합니다.
  4. 작업이 성공하면 data.results.items를 읽습니다. 이 목록의 각 항목은 동영상 또는 포토 캐러셀 게시물 하나를 나타냅니다. 목록이 비어 있으면 작업은 완료되었지만 반환된 레코드가 없다는 뜻입니다.
  5. 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초 동영상이나 조회되지 않은 게시물로 해석하지 말고 해당 수치를 비워 두세요.

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 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

TikTok Top Search API — 자주 묻는 질문

TikTok Top Search API는 키워드나 문구로 공개 TikTok 동영상과 포토 캐러셀을 찾는 프로그래밍 인터페이스입니다. 캡션, 크리에이터, 미디어 링크, 상호작용 수치를 반환하며, 정렬 및 게시 시각 필터를 선택적으로 사용할 수 있습니다.

시청자가 넘겨 볼 수 있는 여러 장의 사진으로 이루어진 TikTok 이미지 게시물입니다. 결과에서는 type=photo_carousel이 해당 형식을 나타내고, media에 이미지 항목이 들어 있습니다.

TikTok Search는 동영상만 반환하는 반면, Top Search는 동영상과 포토 캐러셀을 모두 포함할 수 있습니다. 수집이나 화면에서 이미지 게시물까지 처리해야 하는지에 따라 선택하세요.

사진만 가져오는 입력 필터는 없습니다. 조회한 뒤 type이 photo_carousel인 레코드를 직접 골라야 하며, 결과 수 제한은 형식 필터링 전에 적용되므로 남는 사진 수는 더 적을 수 있습니다.

아니요. region은 검색에서 콘텐츠를 사용할 수 있는 범위를 바꿀 뿐 모든 결과의 지리적 출처를 뜻하지 않습니다. 크리에이터 위치나 게시물 위치 필드를 대신하는 용도로 쓰지 마세요.

아니요. results_limit은 반환되는 선택 범위의 상한일 뿐, 일치하는 모든 TikTok 게시물이 포함된다는 보장은 아닙니다. 검색 결과가 요청한 제한보다 적을 수 있습니다.

반환된 콘텐츠 레코드 1건당 0.7 크레딧이 차감되며, 동영상이든 포토 캐러셀이든 같습니다. 기본 요금은 없으며, 제한 100이면 예상 금액은 70 크레딧이고 레코드 20건이 반환되면 14 크레딧입니다.