Michael Johnson지원팀에는 사람들이 이해하기 어려운 기능을 논의하거나 제품에 관해 질문하는 공개 TikTok 동영상 목록이 필요할 수 있습니다. 수동 검색은 같은 방식으로 반복하기 어렵고, 검색 API 응답은 JSON의 서로 다른 위치에 동영상 정보를 담을 수 있습니다. 아래는 키워드로 결과를 요청하고 두 가지 구조를 합친 뒤 ID 기준으로 중복을 제거해 CSV로 저장하는 간단한 Python 스크립트입니다.
스크립트가 만들어 내는 결과
결과는 동영상 ID, 링크, 설명, 게시 시간, 작성자, 이용 가능한 반응 수치를 담은 표입니다. 지원팀이나 마케팅팀은 어떤 주제에 답변이 필요한지, 안내 자료를 업데이트할지, 자체 CRM에서 확인할지 직접 표시할 수 있습니다. 이 표는 지정한 검색어에 대해 API가 반환한 결과만 보여 줍니다. 따라서 모든 논의를 빠짐없이 담은 목록이 아니라 검토용 표본으로 취급하세요.
이 스크립트는 수집과 1차 분류를 담당합니다. 설명이 질문인지, 불만인지, 농담인지를 자동으로 판단하지는 않습니다. 이런 표시는 직접 확인한 뒤 추가하거나 별도의 분류기를 사용해 부여하는 편이 좋습니다. 이때 원문과 판단 근거를 함께 기록하세요.
요청할 데이터와 응답 구조
jsonscraper는 동영상 검색에 https://tiktok.evelode.com 호스트의 GET 경로 /searchVideo를 문서화하고 있습니다. 필수 매개변수는 keyword입니다. count, 지역, 정렬 방식, 게시 기간, 다음 페이지를 위한 커서도 전달할 수 있습니다. 예를 들어 기능 이름, 흔히 쓰이는 오류 표현, 설정에 관한 짧은 질문처럼 미리 정해 둔 여러 문구로 검색을 반복할 수 있습니다. 매개변수와 허용 값은 TikTok API 참조 문서에 나와 있습니다.
파서를 작성할 때 유의할 점이 있습니다. 검색 결과의 aweme_list 배열이 비어 있고, 찾은 객체가 search_item_list에 있으며 각 객체 안에 aweme_info가 들어 있을 수 있습니다. 아래 처리 코드는 두 형식을 모두 확인합니다. 응답 예시와 2026년 10월 25일 확인 과정에서 관찰된 필드는 jsonscraper 기본 사양에 제시되어 있습니다. 통계 필드는 없을 수도 있으므로 코드에서 임의의 값을 채워 넣지 않습니다.
키와 검색어 목록 준비하기
키는 소스 파일에 넣지 말고 JSONSCRAPER_TIKTOK_LICENSE_KEY 환경 변수에 저장하세요. Linux 또는 macOS 셸에서는 다음과 같이 설정할 수 있습니다.
export JSONSCRAPER_TIKTOK_LICENSE_KEY="사용자_키"요청 라이브러리를 설치하고, 한 줄에 검색 문구 하나씩 담은 queries.txt 파일을 준비하세요. 예를 들면 제품 이름 설정과 기능 이름 작동하지 않음을 넣을 수 있습니다. 검색 문구는 대상 고객의 언어에 맞게 선택하고 별도 목록으로 관리하면, 매주 같은 검색어를 기준으로 결과를 비교할 수 있습니다.
python -m pip install requests동영상을 수집하고 정규화하기
이 예제는 Python 3.8 이상과 호환됩니다. 각 문구에 대해 결과 수를 제한해 한 번씩 요청하고, HTTP 오류와 응답의 상위 상태를 확인한 뒤 실제로 존재하는 필드만 저장합니다. aweme_id로 중복 항목을 합치고, 해당 동영상을 찾은 모든 검색어는 keywords 필드에 기록합니다. 별도의 collected_at_utc 필드에는 데이터를 가져온 시각을 저장해 다음 실행 결과와 비교할 수 있습니다.
import csv
import os
import sys
from datetime import datetime, timezone
import requests
BASE_URL = "https://tiktok.evelode.com/searchVideo"
API_KEY = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not API_KEY:
raise SystemExit("JSONSCRAPER_TIKTOK_LICENSE_KEY를 설정하세요")
def get_items(tiktok):
"""문서화된 두 가지 검색 응답 형식에서 동영상을 추출합니다."""
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
info = entry.get("aweme_info") if isinstance(entry, dict) else None
if info:
items.append(info)
return items
with open("queries.txt", encoding="utf-8") as query_file:
queries = [line.strip() for line in query_file if line.strip()]
collected_at = datetime.now(timezone.utc).isoformat()
videos = {}
for keyword in queries:
response = requests.get(
BASE_URL,
params={
"license_key": API_KEY,
"keyword": keyword,
"count": 30,
"region": "US",
"sort_by": "relevance",
},
timeout=30,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
print("API 상태가 실패로 반환된 검색어:", keyword, file=sys.stderr)
continue
tiktok = payload.get("tiktok") or {}
for item in get_items(tiktok):
video_id = item.get("aweme_id")
if not video_id:
continue
if video_id not in videos:
author = item.get("author") or {}
stats = item.get("statistics") or {}
videos[video_id] = {
"aweme_id": video_id,
"keywords": [keyword],
"description": item.get("desc"),
"share_url": item.get("share_url"),
"create_time": item.get("create_time"),
"author": author.get("unique_id") or author.get("nickname"),
"play_count": stats.get("play_count"),
"digg_count": stats.get("digg_count"),
"comment_count": stats.get("comment_count"),
"share_count": stats.get("share_count"),
"collected_at_utc": collected_at,
}
elif keyword not in videos[video_id]["keywords"]:
videos[video_id]["keywords"].append(keyword)
columns = [
"aweme_id", "keywords", "description", "share_url", "create_time",
"author", "play_count", "digg_count", "comment_count", "share_count",
"collected_at_utc",
]
with open("tiktok_support_review.csv", "w", newline="", encoding="utf-8-sig") as output:
writer = csv.DictWriter(output, fieldnames=columns)
writer.writeheader()
for video in videos.values():
row = dict(video)
row["keywords"] = " | ".join(row["keywords"])
writer.writerow(row)
print("저장된 고유 동영상 수:", len(videos))요청은 params 매개변수를 통해 전송되므로 라이브러리가 검색 문구를 URL에 올바르게 인코딩합니다. 문서에 설명된 대로 키는 쿼리 매개변수에 포함됩니다. 애플리케이션 로그에 요청의 전체 URL을 출력하지 마세요. 문제를 진단할 때는 HTTP 응답 코드, 검색 문구, 실행 시각을 기록하되 작업에 불필요한 비밀 정보와 개인 정보는 제외하세요.
CSV를 과도하게 해석하지 않고 읽는 법
keywords 열에는 동영상을 찾은 모든 검색 문구가 들어갑니다. collected_at_utc를 보면 게시 시각과 수집 시각을 구분할 수 있습니다. ID는 중복 제거에, 링크는 사람이 직접 확인하는 데 유용합니다. 카운터가 비어 있다면 해당 응답에 필드가 없었다는 뜻이지, 값이 0이라는 뜻은 아닙니다.
1차 분류를 위해 작업용 CSV에 주제, 신호 유형, 답변 필요 여부, 내부 자료 링크 열을 추가하세요. 주제 선택지는 제품에 맞춰 설치, 결제, 호환성, 오류 해결 등으로 정할 수 있습니다. 이렇게 하면 수집 결과를 검토 대기열로 활용하면서 원본 동영상을 바탕으로 판단을 다시 확인할 수 있습니다.
일정에 맞춰 수집 실행하기
먼저 스크립트를 직접 실행해 몇 개의 행과 링크가 올바른지 확인하세요. 그런 다음 Python 프로세스를 실행할 수 있는 cron, CI 작업 또는 자동화 스크립트에 추가하면 됩니다. 정기 보고서를 만들려면 각 수집 결과를 별도로 저장하거나 동영상의 고유 키와 스냅샷 날짜를 기준으로 저장소에 행을 추가하세요. 그러면 새로 발견된 게시물과 반복해서 관찰된 게시물을 구분하고 실행 간에 이용 가능한 카운터가 어떻게 변하는지 추적할 수 있습니다.
cursor 매개변수는 검색 결과의 다음 부분을 불러올 때 사용하며, 이전 호출의 응답에서 받은 값을 전달해야 합니다. 이 최소 예제에서는 페이지네이션을 의도적으로 제외했습니다. 제한된 검색어 집합이 확인과 재현에 더 쉽기 때문입니다. 페이지를 추가한다면 커서를 불투명한 값으로 취급하고, 계속 여부 플래그에 따라 중단하며, 한 번의 실행에서 호출할 수 있는 횟수에 상한을 두세요. API 요청은 표본을 반환하므로 행 수를 TikTok 전체에 대한 완전한 범위로 해석하지 마세요.
실용적인 사용 범위
검색 결과는 팀이 이미 알고 있는 문구를 바탕으로 동영상을 찾는 데 적합합니다. 분류할 자료를 모으는 데 도움은 되지만 고객 문의, 자체 사이트 분석, 동영상 맥락 확인을 대신하지는 않습니다. 설명에 동영상의 핵심이 담기지 않을 수 있고, 이용 가능한 지표는 데이터를 가져온 시점의 상태를 반영합니다. 직원이 분류를 다시 검토할 수 있도록 주제와 결론은 원본 필드와 별도로 표시하세요.
정기 모니터링을 시작하기 전에 누가 수집 결과에 접근할 수 있는지, 데이터를 얼마나 오래 보관할지, 공개 정보를 어떤 목적으로 사용할지 정하세요. 제품 검토에 필요한 필드만 저장하고 미디어 파일을 복사하는 대신 원본 게시물 링크를 우선 사용하세요. 요청 방법과 이용 가능한 통합 방식을 확인하려면 TikTok Scraper API 페이지와 검색 경로 문서를 살펴보세요.
