SocQ로 TikTok 동영상과 사진 캐러셀을 함께 조사하세요. 키워드 하나를 중심으로 캡션, 크리에이터, 미디어 링크, 참여 지표를 수집하고, 동영상 시연, 레시피 카드, 이미지 가이드를 같은 주제 데이터셋에 정리할 수 있습니다.
SocQ TikTok Top Search API는 키워드로 공개 동영상과 사진 캐러셀을 검색합니다. 이 가이드에서는 요청, 결과 형식 처리, 게시물과 순서가 있는 이미지 링크 내보내기를 다룹니다.
빠른 답변:
POST /v1/tiktok/top-search에 필수 값인query를 보내세요. 작업이 성공하면data.results.items를 읽습니다. 동영상은type=video, 이미지 게시물은type=photo_carousel을 사용하며, 캐러셀의 이미지 항목은media에 들어 있습니다.
콘텐츠 형식에 맞는 검색 엔드포인트 고르기
| 출발점 | SocQ 엔드포인트 | 결과 범위 |
|---|---|---|
| 키워드, 동영상만 | TikTok Search | 동영상 검색 워크플로 |
| 키워드, 동영상과 이미지 게시물 | TikTok Top Search | type으로 구분되는 혼합 결과 |
| 알고 있는 게시물 URL | TikTok Videos | 지정한 콘텐츠 조회 |
| 알고 있는 사운드 ID | TikTok Song Videos | 해당 사운드와 연결된 동영상 찾기 |
Top Search는 키워드에 해당하는 기존 게시물을 반환합니다. 사진 게시물만 다루려면 결과에서 type=photo_carousel을 고르고 media의 이미지를 읽으세요.
키워드로 TikTok 검색하기
SOCQ_API_KEY를 설정하고 레코드 20개로 제한한 검색을 제출합니다.
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}'
data.task_id를 TASK_ID로 저장하고 해당 작업을 조회합니다.
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
상태가 queued, running, retrying인 동안에는 간격을 두고 확인하세요. succeeded가 되면 data.results.items를 읽고, failed가 되면 data.error_message를 확인합니다. 결과에 has_more=true가 있으면 next_cursor를 따라가 저장된 나머지 페이지를 읽으세요.
작업 결과 커서는 저장된 레코드를 읽습니다. 수집 상한은 제출한 results_limit이 정합니다. 클라이언트 타임아웃이 발생하면 기존 작업 ID로 조회를 이어가세요.
정렬, 게시 기간 필터, 지역 설정
| 매개변수 | 허용 값 또는 범위 | 의미 |
|---|---|---|
query | 비어 있지 않은 키워드 또는 문구(필수) | 검색할 주제 |
sort_by | relevance, date, likes | 요청한 결과 정렬. 기본값은 relevance |
published_within | day, week, month, three_months, six_months | 선택적 게시 시점 필터 |
region | US 같은 두 글자 코드 | 검색에서 접근할 수 있는 콘텐츠 범위 |
results_limit | 1~2000의 정수. 기본값 100 | 반환되는 콘텐츠 형식 전체에 적용되는 상한 |
day는 어제, week는 이번 주, month는 이번 달을 선택합니다. 이 세 가지 옵션은 달력 기준 기간을 사용합니다. three_months와 six_months는 각각 최근 3개월과 6개월을 선택합니다.
region은 검색에서 접근할 수 있는 콘텐츠를 바꿉니다. region=US는 요청 조건으로 저장하고, 크리에이터의 위치는 별도의 지리 정보로 확인하세요.
예를 들어 결과 20개 중 사진 캐러셀이 8개라면 형식 필터링으로 사진 게시물 8개가 나옵니다. results_limit은 두 형식을 합산한 개수이며, 사진 게시물의 수는 해당 수집 시점의 분포에 따라 달라집니다.
동영상과 사진 캐러셀 결과 읽기
다음 동영상 예시와 이미지 5장짜리 캐러셀 예시로 각 결과 형식을 읽는 방법을 확인하세요.
| 관측 필드 | 동영상 레코드 | 사진 캐러셀 레코드 |
|---|---|---|
id | 7678536068550970638 | 7685189869970246926 |
type | video | photo_carousel |
author.username | patrickmcgee62 | coffeewithcandace |
duration_seconds | 5.247 | null |
| 미디어 항목 | 동영상 1개 | 이미지 5장 |
표준 레코드는 캡션을 text에, 미디어를 media에, 사운드 정보를 audio에, 참여 지표를 metrics에 저장합니다. 이후 쿼리는 해당 작업이 반환한 레코드를 기준으로 처리하세요.
캐러셀 이미지는 반환된 미디어 순서대로 읽으세요. duration_seconds가 null이면 길이 정보가 제공되지 않았다는 뜻이고, 지표가 null이면 측정값이 제공되지 않았다는 뜻입니다. 반환된 0은 그대로 유지하고, 재생수와 조회수는 각자의 필드에 따로 보관하세요.
Python으로 검색 결과와 캐러셀 이미지 내보내기
표준 라이브러리만 쓰는 이 헬퍼를 socq_collect.py로 저장하세요.
import json
import os
import time
from urllib.parse import urlencode
from urllib.request import Request, urlopen
BASE = "https://api.socq.ai/v1"
PENDING = {"queued", "running", "retrying"}
def api(method, path, payload=None):
body = json.dumps(payload).encode("utf-8") if payload is not None else None
request = Request(
BASE + path, data=body, method=method,
headers={
"Authorization": "Bearer " + os.environ["SOCQ_API_KEY"],
"Content-Type": "application/json",
},
)
with urlopen(request, timeout=60) as response:
result = json.load(response)
if result.get("code") != 200:
raise RuntimeError(result)
return result["data"]
def collect(endpoint, payload):
task_id = api("POST", "/" + endpoint, payload)["task_id"]
print("Task:", task_id, flush=True)
path = "/tasks/" + task_id
deadline = time.monotonic() + 600
data = api("GET", path + "?limit=100")
while data["status"] in PENDING:
if time.monotonic() >= deadline:
raise TimeoutError("Resume GET " + path + "; do not resubmit automatically")
time.sleep(2)
data = api("GET", path + "?limit=100")
if data["status"] != "succeeded":
raise RuntimeError(data.get("error_message") or data["status"])
items, seen_cursors = [], set()
while True:
if time.monotonic() >= deadline:
raise TimeoutError("Resume pagination for " + task_id)
page = data["results"]
items.extend(page["items"])
if not page["has_more"]:
return task_id, items
cursor = page.get("next_cursor")
if not cursor or cursor in seen_cursors:
raise RuntimeError("Missing or repeated result cursor")
seen_cursors.add(cursor)
data = api("GET", path + "?" + urlencode({"limit": 100, "cursor": cursor}))
if data["status"] != "succeeded":
raise RuntimeError("Task is not ready for result pagination")
다음 코드를 같은 디렉터리에 export_search.py로 저장하세요.
import csv
import json
from socq_collect import collect
payload = {"query": "coffee", "sort_by": "relevance", "results_limit": 20}
task_id, records = collect("tiktok/top-search", payload)
with open("tiktok-search.json", "w", encoding="utf-8") as f:
json.dump({"task_id": task_id, "input": payload, "items": records},
f, ensure_ascii=False, indent=2)
def csv_cell(value):
if value is None:
return ""
if isinstance(value, str) and value.lstrip().startswith(("=", "+", "-", "@")):
return "'" + value
return value
def write_csv(path, fields, rows):
with open(path, "w", encoding="utf-8-sig", newline="") as f:
writer = csv.DictWriter(f, fieldnames=fields)
writer.writeheader()
writer.writerows({k: csv_cell(v) for k, v in row.items()} for row in rows)
posts, images, seen_ids = [], [], set()
for item in records:
post_id = item.get("id")
if post_id is not None:
if str(post_id) in seen_ids:
continue
seen_ids.add(str(post_id))
metrics = item.get("metrics") or {}
posts.append({"post_id": post_id, "type": item.get("type"),
"text": item.get("text"), "url": item.get("url"),
"username": (item.get("author") or {}).get("username"),
"published_at": item.get("published_at"),
"likes_count": metrics.get("likes_count"),
"views_count": metrics.get("views_count"),
"collected_at": item.get("collected_at")})
if item.get("type") == "photo_carousel":
for position, media in enumerate(item.get("media") or [], start=1):
if media.get("type") == "image":
images.append({"post_id": post_id, "media_position": position,
"image_url": media.get("url"),
"width": media.get("width"), "height": media.get("height")})
write_csv("tiktok-search.csv", ["post_id", "type", "text", "url", "username",
"published_at", "likes_count", "views_count", "collected_at"], posts)
write_csv("tiktok-carousel-images.csv", ["post_id", "media_position", "image_url",
"width", "height"], images)
python3 export_search.py
JSON에는 수집한 모든 레코드가 그대로 남습니다. 게시물 CSV는 ID 기준으로 중복을 제거하고, 이미지 CSV는 캐러셀 순서를 복원할 수 있도록 게시물 ID와 미디어 위치를 저장합니다. ID가 없는 레코드는 따로 유지되므로, 다른 데이터셋과 결합하기 전에 원본 게시물을 확인하세요.
원본 게시물을 열고 미디어에 접근하려면 게시물 URL과 미디어 URL을 모두 보관하세요. 이미지 주소가 없으면 빈 값 그대로 유지합니다. CSV에서는 수식처럼 보이는 공개 텍스트가 이스케이프되며, 모든 자릿수를 보존하려면 게시물 ID를 텍스트로 가져와야 합니다.
수집한 게시물로 주제 리뷰 만들기
커피 레시피 리뷰라면 수집한 게시물을 이미지 카드와 동영상 시연으로 분류하세요. 주제를 지정할 때는 캡션과 미디어를 모두 읽어야 합니다. 이미지 안에 표시된 전체 텍스트를 추출하려면 별도의 텍스트 인식 단계가 필요합니다.
비교할 때마다 쿼리, 필터, 수집 시각을 함께 보관하세요. 로컬에서 좋아요순으로 정렬한 결과는 "이 표본 내 좋아요 순위"로 표기하고, 표본 크기와 수집 범위를 함께 밝히세요.
오디오 중심의 탐색은 TikTok 음악 차트 튜토리얼을 참고하세요. 프로필, 알고 있는 동영상, 댓글 워크플로는 TikTok 스크래핑 가이드를 사용하세요.
동영상과 이미지를 위한 하나의 리서치 데이터셋 만들기
SocQ Top Search는 동영상과 사진 캐러셀에 하나의 요청 워크플로를 사용하며, 표준 필드로 각 형식을 구분합니다. 내보내기 코드는 게시물 표와 순서가 있는 이미지 표를 모두 만들어, 주제 라이브러리나 리뷰 화면에 필요한 소스 링크와 슬라이드 위치를 제공합니다.
자주 묻는 질문(FAQ)
TikTok 검색 API로 사진 캐러셀도 가져올 수 있나요?
Top Search는 동영상과 사진 캐러셀을 type으로 구분해 반환하며, 미디어는 media에 들어 있습니다. 별도의 TikTok Search 엔드포인트는 동영상 검색용입니다.
TikTok 사진만 검색할 수 있나요?
결과를 수집한 다음 type=photo_carousel을 선택하세요. 사진 필터링은 애플리케이션에서 처리하며, 수집 상한은 두 형식을 합산해 계산합니다.
Top Search가 인기 검색어나 검색량도 반환하나요?
Top Search는 입력한 키워드를 받아 게시물 레코드를 반환합니다. 키워드 검색량과 트렌드 검색어 목록은 별도의 데이터 유형이며 이 응답에 포함되지 않습니다.
region으로 크리에이터가 사는 곳을 알 수 있나요?
region은 검색에서 접근할 수 있는 콘텐츠를 조정합니다. 크리에이터의 거주지나 게시 위치는 별도로 확인하세요.
키워드에 맞는 모든 게시물을 가져올 수 있나요?
이 엔드포인트는 해당 검색이 선택한 게시물을 results_limit까지 반환합니다. 모든 결과 페이지를 읽으면 그 작업에 저장된 전체 결과 집합을 가져올 수 있으며, 주제를 얼마나 포괄하는지는 그 레코드에 따라 정해집니다.
사진 게시물에 길이나 재생수가 없는 이유는 무엇인가요?
사진 캐러셀은 이미지 항목으로 읽으세요. 길이나 재생수 측정값이 없으면 null로 유지하고, 소스가 0을 반환하면 0으로 유지하세요.
이 API로 캐러셀을 게시할 수 있나요?
Top Search는 기존 공개 콘텐츠를 가져옵니다. 캐러셀 게시에는 별도의 게시 워크플로를 사용합니다. 이 엔드포인트의 입력, 필드, 과금은 Top Search API 페이지를 참고하세요.
TIKTOK API
공개 TikTok URL로 워크플로를 테스트하세요
공개 데이터 입력을 제출하면 출처를 추적할 수 있는 컨텍스트가 포함된 정규화된 레코드를 받을 수 있습니다.
TikTok API 살펴보기