tiktok/
trending-feed

지역 코드에 해당하는 현재 공개 TikTok 동영상 피드를 수집하고, 동영상 ID, 캡션, 크리에이터, 커버 이미지, 타임스탬프, 공개된 참여도를 반환합니다.

TikTok Trending Feed API

지역별 피드
정규화된 동영상
현재 시점 스냅샷
결과당 0.7 크레딧
준비됨
README

SocQ 작성 · 업데이트

TikTok Trending Feed

TikTok Trending Feed 동영상은 특정 지역 맥락에서 노출되는 공개 피드 항목으로, 동영상·크리에이터 식별 정보, 캡션, 커버 이미지, 타임스탬프, 공개된 참여도를 담고 있습니다. 이러한 콘텐츠·성과 신호는 지역별 탐색 스냅샷, 크리에이티브 조사, 특정 시점 비교에 활용할 수 있습니다.

TikTok Trending Feed API 주요 기능

  • 지역 단위 공개 피드비어 있지 않은 region 값을 받아, 해당 지역 요청 맥락에서 노출되는 현재 공개 동영상 피드를 수집합니다.
  • 정규화된 동영상·크리에이터 정보동영상 ID와 원본 URL, 캡션, 크리에이터 식별 정보, 커버 이미지 참조, 생성·수집 타임스탬프를 일관된 레코드로 반환합니다.
  • 공개된 참여도 지표반환되는 동영상마다 공개된 조회수, 좋아요 수, 댓글 수, 공유 수, 저장 수를 함께 담습니다.
  • 범위가 제한된 현재 스냅샷원본의 이어지는 페이지를 따라가지 않고 하나의 지역 피드 응답을 results_limit만큼만 잘라 가져오며, 순위나 과거 시계열이 아니라 현재 피드의 표본을 보존합니다.

TikTok Trending Feed API 매개변수

매개변수필수설명
region필수비어 있지 않아야 하는 필수 지역 값입니다. 백엔드에서 앞뒤 공백을 제거하고 대문자로 바꿉니다. 대상 지역 맥락에는 US 같은 표준 두 글자 지역 코드를 사용하세요.
results_limit선택4~2,000 사이의 정수로 된 상한이며 선택 사항입니다. 기본값은 100이고, 단일 피드 응답을 잘라 가져오므로 동영상이 더 적을 수 있습니다.

TikTok Trending Feed API 사용 방법

지역 피드 요청을 비동기 작업으로 제출하고, 작업 결과 커서 페이지네이션으로 정규화된 동영상을 읽습니다.

  1. 비어 있지 않은 region 값을 입력합니다. 대상 지역 맥락에는 US 같은 표준 두 글자 코드를 사용하고, results_limit은 4~2,000 사이에서 고르거나 기본값 100을 그대로 둡니다.
  2. region과 results_limit을 /v1/tiktok/trending-feed로 POST하고, 반환된 task_id를 저장합니다.
  3. status가 succeeded 또는 failed가 될 때까지 /v1/tasks/{task_id}를 폴링합니다.
  4. /v1/tasks/{task_id}?limit=50에서 data.results.items를 읽고, results.has_more가 true인 동안 results.next_cursor로 이어서 가져옵니다.
curl -X POST "https://api.socq.ai/v1/tiktok/trending-feed" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"region":"US","results_limit":20}'

# Poll GET /v1/tasks/{task_id}, then read data.results.items and follow results.next_cursor.

TikTok Trending Feed API 추천 활용 사례

  • 지역별 탐색 스냅샷 확보: 한 번의 지역 피드 요청에서 동영상 ID, 원본 URL, 캡션, 크리에이터, collected_at을 저장해, 수집 시점에 공개적으로 노출된 구성을 기록합니다.
  • 현재 크리에이티브 패턴 표본 조사: 캡션, 크리에이터 이름, 커버 이미지, 생성 시각을 검토해 선택한 지역 피드에서 보이는 크리에이티브 구성을 비교합니다.
  • 공개된 참여도 비교: 조회수, 좋아요 수, 댓글 수, 공유 수, 저장 수를 collected_at과 함께 사용해 반환된 동영상 간 공개 참여도 신호를 비교합니다.

TikTok Trending Feed API 활용 팁

  • 현재 런타임은 비어 있지 않은 값만 요구하지만, 표준 두 글자 지역 코드를 사용하세요. 백엔드는 공백을 제거하고 대문자로 변환합니다.
  • 엔드포인트가 피드 응답 하나를 잘라 가져올 뿐 원본의 이어지는 페이지를 요청하지 않으므로, results_limit은 예상 개수가 아니라 상한으로 정하세요.
  • region은 피드 제공 범위를 나타내는 맥락일 뿐 동영상의 출처를 증명하지 않습니다. extra.region은 행 단위 데이터이며 비어 있거나 요청과 다를 수 있습니다.
  • 작업 결과 커서는 SocQ에 이미 저장된 레코드를 페이지로 넘기는 용도로만 쓰세요. 지역 피드의 다른 페이지를 가져오지는 않습니다.
  • 반복 실행한 결과를 비교할 때는 동영상 id로 중복을 제거하고 collected_at을 보관하세요. 요청마다 피드의 구성과 순서가 달라질 수 있습니다.
  • 크리에이터 필드, 지표, 커버 미디어, 타임스탬프, extra 값은 null일 수 있다고 보고 처리하고, 공개 캡션은 표시하기 전에 이스케이프 처리하세요.

TikTok Trending Feed API 외에 TikTok의 다른 유형의 공개 데이터가 필요할 때 이 API를 사용하세요.

  • TikTok Comments API — 공개된 최상위 댓글, 작성자, 참여도, 멘션, 크리에이터 상호작용 플래그를 수집합니다.
  • TikTok Videos API — 동영상 URL에서 크리에이터, 캡션, 미디어, 음악, 태그, 멘션, 참여도를 가져옵니다.
  • TikTok User Videos API — 사용자 이름으로 공개 프로필 피드 동영상을 수집하며, 캡션, 크리에이터, 미디어, 타임스탬프, 참여도, 출처 계정 맥락을 포함합니다.
  • TikTok Video Transcript API — 공개 동영상 URL에서 제공되는 스크립트 텍스트, 언어, 형식, 출처 맥락을 추출합니다.
  • TikTok Song API — 클립 ID 또는 음악 URL로 공개 사운드 메타데이터를 가져옵니다.
  • TikTok Song Videos API — 지정한 사운드 ID를 사용한 공개 동영상을 수집합니다.

다른 플랫폼 둘러보기

TikTok 데이터를 지원되는 다른 소셜 플랫폼의 공개 데이터와 함께 활용하세요.

TikTok Trending Feed API — 자주 묻는 질문

TikTok Trending Feed API는 비어 있지 않은 region 값에 노출되는 현재 공개 TikTok 동영상 피드를 수집하는 프로그래밍 인터페이스입니다. 정규화된 동영상 식별 정보, 캡션, 크리에이터, 커버 이미지, 타임스탬프, 공개된 참여도를 반환하며, 제공되는 경우 행 단위 지역·광고 맥락도 함께 반환합니다.

비어 있지 않은 region 값을 제출하면 백엔드가 공백을 제거하고 대문자로 변환합니다. 공개 문서와 원본 인터페이스가 의도한 지역 입력이 그러하므로 US 같은 표준 두 글자 코드를 사용하세요. 다만 현재 런타임은 두 글자 형식을 강제하지 않습니다.

results_limit의 기본값은 100이며 4~2,000 사이의 정수를 받습니다. 반환된 지역 피드 응답 하나를 잘라 가져오므로, 한도를 높여도 원본의 이어지는 페이지를 요청하지 않으며 그만큼의 동영상이 있다는 보장도 없습니다.

레코드에는 동영상 ID와 원본 URL, 캡션, 크리에이터 ID·사용자 이름·표시 이름, 공개된 조회수·좋아요 수·댓글 수·공유 수·저장 수, 커버 이미지 하나, 생성 및 수집 시각, 그리고 extra.region과 extra.is_ad가 포함될 수 있습니다.

아니요. region은 요청에 대한 피드 제공 범위를 정할 뿐 크리에이터의 위치나 동영상의 출처를 뜻하지 않습니다. extra.region은 행마다 제공되며 비어 있거나 다를 수 있습니다.

아니요. 현재 노출되는 피드의 동영상을 반환할 뿐이며 정규화된 순위, 순위 변동, 해시태그 집계, 크리에이터 차트, 노래 차트, 과거 시계열 필드는 없습니다. 비교가 필요하면 반복 실행한 작업 결과를 collected_at과 함께 저장해 직접 만드세요.

정상적으로 저장된 정규화 동영상 1건당 0.7 크레딧이 차감되며 작업 기본 요금은 없습니다. 처음 예상 금액은 results_limit 또는 기본값 100을 기준으로 하고, 사용하지 않은 선차감 크레딧은 작업이 정산될 때 환불됩니다.