Michael Johnson구매자들이 여러 틱톡 동영상에서 같은 질문을 한다면, 고객 지원팀은 확인할 수 있도록 원본 영상과 질문 표현을 목록으로 받아보는 것이 유용합니다. 여러 검색어의 결과를 수집하고 동영상 ID를 기준으로 통합한 뒤, 표본에 직접 라벨을 붙이는 방식으로 시작할 수 있습니다.
아래 Python 스크립트는 반환된 결과를 수집해 동영상 링크와 설명, 그리고 각 동영상이 검색된 검색어를 담은 CSV 파일을 만듭니다. 이 스크립트는 검색 결과 간 중복을 파악하는 데 도움이 되지만, 의미상 유사한 질문을 판별하지는 않습니다. 질문 분류는 담당자나 별도의 분류기가 수행하고, 이후 검토를 거쳐야 합니다.
수집으로 해결하려는 질문
팀에서 보온 텀블러를 판매하며 공개 영상에서 사람들이 무엇을 묻는지 알고 싶다고 가정해 보겠습니다. ‘보온 텀블러가 샌다’라는 검색어는 불만, 리뷰, 사용법 영상 등을 찾아낼 수 있습니다. ‘보온 텀블러 세척 방법’은 다른 표본을 제공합니다. 여러 표현을 활용하면 고객 지원과 콘텐츠 계획을 검토할 실무용 사례 모음을 만들 수 있습니다.
스크립트가 만드는 표에는 게시물 ID, 설명, 링크, 해당 게시물이 검색된 검색어 목록이 담깁니다. 여러 검색 결과에서 같은 영상이 발견되었다고 해서 그 영상에 반복 질문이 실제로 나온다는 뜻은 아닙니다. 질문 대기열을 만들려면 링크를 열어 맥락을 확인하고, 검증된 표현에 주제를 지정하세요.
이 방식은 수집을 자동화하는 개발자와 분석에 재현 가능한 데이터가 필요한 분석가에게 유용합니다. 원본 영상과 연결해 두면 안내문을 바꾸거나 새 콘텐츠를 제작하기 전에 결론을 검증할 수 있습니다.
검색에서 반환되는 데이터
/searchVideo 경로와 매개변수는 TikTok API 참조 문서에 나와 있습니다. 필수 매개변수는 keyword이며, 추가 매개변수로 count, cursor, region, date_posted, sort_by, cache_timeout이 있습니다. 요청 인증에는 license_key 매개변수를 사용합니다. 아래 예제에서는 검색어와 페이지 크기를 지정합니다.
확인한 응답 구조에는 최상위 status와 tiktok 객체가 있습니다. 항목에는 ID, 설명, 링크, 작성자 정보, 조회수와 댓글 수 같은 통계가 포함될 수 있습니다. 일부 필드는 없을 수 있으므로, CSV에서도 해당 값은 0이 아니라 빈칸으로 남습니다.
검색 응답에는 두 가지 항목 구조가 지원됩니다. 항목은 aweme_list에 있거나 search_item_list[].aweme_info 안에 있을 수 있습니다. 정규화 코드는 두 형태를 모두 처리합니다. 또한 tiktok 객체가 있는지 확인해, 예상하지 못한 응답 구조를 성공적인 빈 검색 결과로 잘못 처리하지 않도록 합니다.
바로 사용할 수 있는 Python 수집기
이 예제는 Python 3.8 이상과 requests 라이브러리에서 작동합니다. 검색어마다 요청을 한 번씩 보내고, HTTP 응답과 API 상태를 확인하며, ID를 기준으로 항목을 통합하고, 일치한 검색어를 저장한 뒤 CSV에 기록합니다. 키는 환경 변수에서 읽으며 출력하지 않습니다.
import csv
import os
import sys
import requests
BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
QUERIES = [
"보온 텀블러가 샌다",
"보온 텀블러 세척 방법",
"보온 텀블러 보온이 안 된다",
]
if not KEY:
sys.exit("JSONSCRAPER_TIKTOK_LICENSE_KEY를 설정하세요")
def extract_items(payload):
data = payload.get("tiktok")
if not isinstance(data, dict):
raise RuntimeError("응답에 tiktok 객체가 없습니다")
items = list(data.get("aweme_list") or [])
for entry in data.get("search_item_list") or []:
video = entry.get("aweme_info") if isinstance(entry, dict) else None
if isinstance(video, dict):
items.append(video)
return items
rows = {}
for query in QUERIES:
response = requests.get(
BASE_URL,
params={"license_key": KEY, "keyword": query, "count": 20},
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("API가 ok가 아닌 상태를 반환했습니다")
for item in extract_items(payload):
video_id = item.get("aweme_id")
if not video_id:
continue
stats = item.get("statistics") or {}
author = item.get("author") or {}
row = rows.setdefault(video_id, {
"video_id": video_id,
"description": item.get("desc"),
"share_url": item.get("share_url"),
"author": author.get("nickname"),
"play_count": stats.get("play_count"),
"comment_count": stats.get("comment_count"),
"matched_queries": set(),
})
row["matched_queries"].add(query)
fields = ["video_id", "description", "share_url", "author",
"play_count", "comment_count", "matched_queries"]
with open("tiktok_questions.csv", "w", newline="", encoding="utf-8-sig") as file:
writer = csv.DictWriter(file, fieldnames=fields)
writer.writeheader()
for row in rows.values():
output = dict(row)
output["matched_queries"] = " | ".join(sorted(row["matched_queries"]))
writer.writerow(output)
python -m pip install requests 명령으로 종속성을 설치하고, 프로세스 환경에서 JSONSCRAPER_TIKTOK_LICENSE_KEY를 설정한 다음 파일을 실행하세요. 키를 소스 코드, CSV, 로그에 넣지 마세요. 정기 실행을 예약할 때는 해당 작업이 환경 변수에 접근할 수 있는 보안 환경에서 스크립트를 실행하세요.
CSV를 질문 대기열로 바꾸는 방법
수집한 뒤 영상을 열어 실제 질문을 직접 추리고, 확인된 표현을 ‘밀폐’, ‘관리’, ‘보온’ 등의 주제로 묶으세요. 검색어는 게시물을 찾는 데 도움이 되지만, 영상 설명이나 여러 검색어와의 일치만으로는 맥락 확인을 대신할 수 없습니다.
언어 모델을 사용하는 경우 영상 설명을 전달하고 간단한 주제 라벨과 가능한 질문을 제안하도록 요청하세요. 전문가가 분류 근거를 검토할 수 있도록 원문, 링크, 모델 결과를 함께 저장하세요. 모델이 제안한 표현이 설명에 실제로 없다면 이를 영상에서 나온 질문 그대로인 것처럼 제시하지 마세요.
찾은 기록 수는 특정 검색어에 대해 반환된 결과만 나타냅니다. 전체 대화량이나 수요를 측정하는 수치는 아닙니다. 내부 보고서에는 실행 날짜, 원래 검색어, ID, API 원본 응답을 저장하세요. 이렇게 하면 실행을 반복해 결과를 비교하고 새 ID를 따로 표시할 수 있습니다.
이 예제에는 자동 페이지네이션이 의도적으로 포함되지 않았습니다. 다음 페이지를 가져올 때는 cursor 매개변수를 사용하며, 문서에 따르면 이전 응답에서 값을 가져와 변환 없이 다음 요청에 전달해야 합니다. 한 페이지에는 받은 결과 일부만 들어 있으며, 전체 검색 결과를 나타내지는 않습니다.
팀에서 확인할 수 있는 내용
tiktok_questions.csv 파일에는 검색어에 해당하는 고유 ID마다 한 행이 기록됩니다. matched_queries 열에서는 해당 영상이 어떤 검색어로 발견되었는지 확인할 수 있습니다. 검색 결과 간 교집합을 파악하고 검토할 사례를 고르는 데 편리하지만, 질문 분류는 별도로 수행해야 합니다.
그런 다음 CSV를 주간 자동화에 포함할 수 있습니다. 스케줄러가 수집을 실행하고, 저장소가 스냅샷을 보관하며, 로그에 아직 없는 ID가 나타나면 알림을 보냅니다. 이는 외부 오케스트레이션의 로직이지 검색 엔드포인트의 기능은 아닙니다. 팀이 받는 것은 분석할 링크 대기열이지, 구매자 행동의 원인에 대한 완성된 결론이 아닙니다.
경로 매개변수는 API 문서에서 확인할 수 있으며, TikTok API 데모 플레이그라운드에서 요청을 시험할 수 있습니다. 정기적으로 수집하기 전에 실제 응답 형식을 확인하고, 요약에서 특정 영상으로 이동하는 데 필요한 값을 저장하세요. 제품 설명은 TikTok Scraper API 페이지에 나와 있습니다.
유용한 결과물은 구체적인 검색 표현과 연결된, 검증 가능한 동영상 모음입니다. 이를 통해 수동 검토에 필요한 자료를 고르고 콘텐츠 계획에 포함된 각 주제의 출처를 보관할 수 있습니다.
