tiktok/
search-live

키워드로 TikTok LIVE를 검색해 지금 방송 중인 라이브의 방 ID, 호스트 ID, 제목, 현재 시청자 수, 좋아요 수, 시작 시각을 받아 라이브 쇼핑 조회에 바로 연결합니다.

TikTok Live Search API

키워드 검색
방송 중인 라이브만
방 ID와 호스트 ID
결과당 0.6 크레딧
준비됨
준비됨

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

README

SocQ 작성 · 업데이트

TikTok Live Search

TikTok LIVE 방은 진행 중인 방송 하나를 가리키며, 방 ID로 식별되고 제목, 호스트, 실시간 시청자 수, 누적 좋아요 수, 시작 시각을 갖습니다. 이 방들을 키워드로 걸러 내면 지금 어떤 주제로 누가 방송 중이고 시청자는 얼마나 되는지 알 수 있어, 라이브 쇼핑 조사, 호스트 발굴, 브랜드 주변의 라이브 활동 추적이 여기서 시작됩니다.

TikTok Live Search API 주요 기능

  • 키워드를 넣으면 방송 중인 라이브가 나옴query에 키워드 하나를 넣으면 그 시점에 방송 중인 라이브가 돌아오며, 모든 레코드의 status는 live입니다.
  • 한 레코드에 방 ID와 호스트 IDid는 방 ID, author.id는 호스트의 사용자 ID로, TikTok Live Shopping이 그 방송의 상품을 조회할 때 필요한 두 값입니다.
  • 수집 시점의 시청자 규모metrics.viewers_count는 방에 들어와 있는 사람 수, metrics.likes_count는 지금까지 모은 좋아요 수이며, collected_at 시각이 함께 찍힙니다.
  • 제목, 시작 시각, 커버, LIVE 페이지레코드마다 방송 제목, published_at의 시작 시각, media의 커버 이미지, url의 호스트 LIVE 페이지 링크가 있고, 호스트의 핸들·표시 이름·아바타도 포함됩니다.

TikTok Live Search API 매개변수

매개변수필수설명
query필수LIVE 방송을 찾을 키워드입니다.
results_limit선택반환할 방송의 개수로, 1~200 사이 값입니다. 기본값은 20입니다.

TikTok Live Search API 사용 방법

키워드를 검색하고 지금 라이브 중인 방송을 읽습니다.

  1. {"query": "deals", "results_limit": 20}을 /v1/tiktok/search-live로 POST합니다.
  2. status가 succeeded가 될 때까지 GET /v1/tasks/{task_id}를 폴링합니다.
  3. results.items에서 방송을 읽고, has_more가 true인 동안 results.next_cursor를 다시 보내 이어서 가져옵니다.
curl -X POST "https://api.socq.ai/v1/tiktok/search-live" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"deals","results_limit":20}'

# id is the room ID; author.id is the host ID for TikTok Live Shopping.

TikTok Live Search API 추천 활용 사례

  • 경쟁 셀러의 라이브 판매 살펴보기: deals처럼 판매자가 방송에서 자주 말하는 상품 관련 단어로 검색한 뒤, 각 방의 id와 author.id를 TikTok Live Shopping에 넘겨 어떤 상품이 올라와 있는지 확인합니다.
  • 키워드 주변의 라이브 활동량 집계: 같은 검색어를 일정 주기로 실행해 방송 중인 라이브 수와 viewers_count를 기록하면, 어느 시점에 어떤 주제나 브랜드가 라이브 시청자를 끄는지 알 수 있습니다.
  • 협업 후보 호스트 추리기: 주제에 맞는 라이브를 진행 중인 호스트를 모아 viewers_count와 likes_count 순으로 정렬한 뒤 연락합니다.

TikTok Live Search API 활용 팁

  • 같은 니치도 표현을 바꿔 여러 번 검색하고 id로 목록을 합치세요. 키워드마다 서로 다른 방송이 나오고, 방송 하나가 여러 키워드에 걸릴 수도 있습니다.
  • id와 author.id는 따로 저장하세요. id는 방송 한 건을, author.id는 호스트를 가리키므로 여러 날에 걸쳐 호스트를 따라가려면 author.id를 쓰세요.
  • 방 하나의 시청자 추이를 보려면 반복 검색 대신 해당 room_id와 user_id로 TikTok Live Room Info를 사용하세요.

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

  • TikTok Profiles API — 사용자 이름으로 공개 프로필 정보, 소개글, 계정 속성, 오디언스 수치를 가져옵니다.
  • TikTok Hashtags API — 지정한 해시태그의 공개 동영상, 크리에이터, 미디어, 사운드, 참여도를 수집합니다.
  • TikTok Search API — 키워드로 공개 동영상을 검색하며, 지원되는 정렬 및 게시 기간 필터를 사용할 수 있습니다.
  • TikTok Live Room Info API — 방 ID와 소유자 ID 쌍으로 알고 있는 라이브 방송 하나를 조회하며, 상태, 소유자 맥락, 커버 미디어, 시청자 수를 반환합니다.
  • TikTok Search Users API — 키워드로 공개 TikTok 계정을 검색합니다.
  • TikTok Live Shopping API — LIVE 방송 쇼핑백에 담긴 상품을 현재 가격, 판매 수량과 함께 나열합니다.

다른 플랫폼 둘러보기

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

TikTok Live Search API — 자주 묻는 질문

TikTok Live Search API는 키워드와 일치하며 지금 방송 중인 TikTok LIVE를 찾는 프로그래밍 인터페이스이고, results_limit으로 가져올 개수를 정합니다. 레코드마다 방 ID, 호스트 ID, 제목, 현재 시청자 수, 좋아요 수, 커버 이미지, 시작 시각이 들어 있습니다.

결과의 id를 room_id로, author.id를 user_id로 TikTok Live Shopping에 보내세요. 두 값은 반드시 같은 결과에서 가져와야 합니다.

results_limit은 1~200을 받고 기본값은 20이며, 일치하는 방송이 그보다 적으면 목록이 먼저 끝납니다. 반환된 방송 1개당 0.6 크레딧이 청구되고, 일치하는 방송이 없는 검색은 청구되지 않습니다.

아니요. 검색을 제출한 시점에 방송 중인 라이브만 나열하며 모든 레코드의 status는 live입니다. 지난 방송은 반환되지 않습니다.

방송은 하루 종일 시작되고 끝나기 때문에 방송 중인 목록이 실행할 때마다 바뀝니다. 방송을 구분하는 키는 id로, 수집 시점은 collected_at으로 쓰세요.

요청에는 query와 results_limit만 있습니다. 결과의 metrics.viewers_count를 읽어 직접 필터링하세요.

이 엔드포인트는 키워드로 검색합니다. 계정이 정해져 있다면 사용자 이름을 받아 계정별 라이브 상태를 알려 주는 TikTok User Live를 사용하세요.