Michael Johnson팀에서 공개 TikTok 영상에 크리에이터와 브랜드의 관계가 어떻게 공개되는지 확인해야 한다면, 첫 결과물은 자동 판정이 아니라 캡션과 링크, 발견된 표식 단어를 담은 간결한 영상 검토 대기열이어야 합니다. 아래에서는 TikTok Scraper API jsonscraper로 검색 요청을 보내고, 두 가지 응답 구조를 하나의 형식으로 정리한 뒤, 전문가 검토용 CSV를 저장하는 실무 흐름을 설명합니다.
목표: 검토할 가치가 있는 영상 찾기
회사 이름을 수동으로 검색하면 같은 절차를 반복하기 어렵습니다. 결과를 하나씩 모아야 하고, 선택한 이유도 브라우저에만 남습니다. 검색을 자동화하면 요청 내용과 실행 날짜, 발견한 자료를 표에 저장할 수 있으므로 팀은 하나의 목록을 기준으로 영상을 검토할 수 있습니다.
이 시나리오에서 ‘검토 후보’란 반환된 검색 결과 중 설명에 미리 지정한 단어나 문구가 포함된 영상만을 뜻합니다. 예를 들어 ‘광고’, ‘파트너십’, ‘후원’ 등이 있습니다. 이 텍스트 필터는 사람이 살펴볼 항목을 추리는 데 도움을 주지만, 영상 자체를 평가하거나 관련 요건의 준수 여부를 판단하지는 않습니다.
마케팅 팀에서는 이 구분이 중요합니다. 미국 연방거래위원회(FTC)의 지침에 따르면 브랜드와의 중요한 관계를 공개해야 하는지는 메시지의 맥락에 따라 달라집니다. FTC는 영상의 경우 공개 내용이 시각적으로도, 음성으로도 전달되는지를 고려할 것을 권고합니다. 캡션 검색은 일부 텍스트 신호를 찾아낼 수 있지만, 결론을 내리려면 게시물을 시청하고 맥락을 평가해야 합니다. FTC의 크리에이터 지침은 예시를 통해 이러한 조건을 설명합니다.
결과물: 선정 근거가 포함된 CSV
파이프라인은 고유한 영상 식별자마다 한 행을 기록하고, 설명 텍스트와 링크, 크리에이터 이름, 공개된 지표, 일치한 표식을 포함합니다. 원래 검색어와 수집 시간도 별도로 추가합니다. 이렇게 하면 표를 실무 검토 대기열로 전달할 수 있고, 나중에 특정 영상이 왜 포함되었는지도 파악할 수 있습니다.
표식 사전은 편집자나 컴플라이언스 담당자가 정합니다. 캠페인에서 실제로 쓰이는 언어와 용어로 시작한 뒤, 결과를 검토하고 필요에 따라 목록을 확장하세요. 아래 코드의 값은 예시일 뿐이므로 브랜드와 시장, 콘텐츠 언어에 맞게 바꿔야 합니다.
TikTok Scraper API 연결
jsonscraper 문서에 따르면 동영상 검색 경로는 기본 주소 https://tiktok.evelode.com의 GET /searchVideo입니다. 필수 매개변수는 keyword이며, 추가 매개변수로 count, date_posted, sort_by, region 등이 있습니다. 키는 license_key로 전달하므로 코드나 CSV에 넣지 말고 환경 변수에 보관하세요. 정확한 매개변수 이름과 경로는 TikTok 엔드포인트 안내서에 나와 있으며, 제품 및 액세스 정보는 TikTok Scraper API 페이지에서 확인할 수 있습니다.
로컬 파서의 완성도에 영향을 주는 중요한 응답 형식이 있습니다. 데이터는 tiktok.aweme_list 또는 tiktok.search_item_list[].aweme_info에 들어갈 수 있습니다. 따라서 스크립트는 두 배열을 모두 확인합니다. 검색 결과가 비어 있으면 가짜 행을 채우지 않고 빈 CSV를 생성합니다.
Python 예제: 검색, 필터링, CSV 생성
이 예제는 Python 3.8 이상의 표준 라이브러리만 사용합니다. 실행하기 전에 환경 변수 JSONSCRAPER_TIKTOK_LICENSE_KEY를 설정하세요. 사양에 명시된 대로 요청에는 keyword를 사용하고, 키는 쿼리 매개변수 license_key로 전달합니다.
import csv
import json
import os
import sys
from datetime import datetime, timezone
from urllib.parse import urlencode
from urllib.request import Request, urlopen
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
KEYWORD = "Acme"
MARKERS = ["реклама", "партнерство", "партнёрство", "спонсор", "ad", "sponsored"]
params = {
"license_key": API_KEY,
"keyword": KEYWORD,
"count": 30,
"sort_by": "date-posted",
"date_posted": "this-month",
"region": "US",
}
url = "https://tiktok.evelode.com/searchVideo?" + urlencode(params)
request = Request(url, headers={"Accept": "application/json"})
with urlopen(request, timeout=30) as response:
payload = json.load(response)
if payload.get("status") != "ok":
raise RuntimeError("API returned a non-ok outer status")
tiktok = payload.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
info = entry.get("aweme_info") or {}
if info:
items.append(info)
seen = set()
rows = []
collected_at = datetime.now(timezone.utc).isoformat()
for item in items:
video_id = item.get("aweme_id")
if not video_id or video_id in seen:
continue
seen.add(video_id)
description = item.get("desc") or ""
lowered = description.casefold()
matched = [word for word in MARKERS if word.casefold() in lowered]
if not matched:
continue
author = item.get("author") or {}
stats = item.get("statistics") or {}
rows.append({
"collected_at_utc": collected_at,
"search_keyword": KEYWORD,
"video_id": video_id,
"share_url": item.get("share_url") or "",
"description": description,
"matched_markers": "; ".join(matched),
"author_name": author.get("nickname") or "",
"author_id": author.get("unique_id") or "",
"play_count": stats.get("play_count", ""),
"digg_count": stats.get("digg_count", ""),
"comment_count": stats.get("comment_count", ""),
"share_count": stats.get("share_count", ""),
})
fields = [
"collected_at_utc", "search_keyword", "video_id", "share_url",
"description", "matched_markers", "author_name", "author_id",
"play_count", "digg_count", "comment_count", "share_count",
]
with open("tiktok_review_queue.csv", "w", newline="", encoding="utf-8-sig") as output:
writer = csv.DictWriter(output, fieldnames=fields)
writer.writeheader()
writer.writerows(rows)
print(f"Saved {len(rows)} review candidates to tiktok_review_queue.csv")스크립트는 먼저 외부 상태를 확인한 다음 tiktok 객체를 읽고 사용 가능한 배열 데이터를 통합합니다. aweme_id 기준으로 중복을 제거하므로 응답의 두 경로에 같은 영상이 있어도 행이 반복되지 않습니다. 지표는 전달받은 값을 그대로 기록하며, 없는 값은 0으로 바꾸지 않고 빈칸으로 둡니다.
이 예제는 /searchVideo에 문서화된 매개변수를 사용합니다. date_posted에는 this-month, sort_by에는 date-posted를 사용할 수 있으며 region에는 국가 코드를 넣습니다. count는 요청하는 결과 수를 정할 뿐, 모든 게시물을 빠짐없이 제공한다고 보장하지는 않습니다. 페이지네이션을 이어갈 때는 반환된 커서를 불투명한 값으로 보관하고 cursor 매개변수로 전달하세요.
사람의 검토와 실행 자동화
CSV를 담당 검토자에게 전달하면서 간단한 안내도 함께 제공하세요. 링크를 열고 영상과 캡션의 맥락을 살핀 뒤, 판단 결과를 기록하고 표식이 다른 의미로 쓰인 경우에는 의견을 덧붙이도록 합니다. 예를 들어 자동 필터링만으로는 광고 공개와 광고의 작동 방식을 논하는 내용을 구분할 수 없습니다. 사람이 검토하면 이러한 의미의 간극을 해소할 수 있습니다.
반복 수집을 위해 cron, CI 스케줄러 또는 작업 오케스트레이터로 스크립트를 예약 실행하세요. 실행 날짜를 포함한 CSV를 보관하거나, 영상 식별자와 관찰 날짜를 조합한 고유 키로 행을 테이블에 적재할 수 있습니다. 감사 기록이 필요하다면 액세스를 통제해 원본 JSON 응답도 보관하세요. 이를 통해 변환 과정을 다시 확인하고 각 행의 출처를 설명할 수 있습니다.
실제 운영에 적용할 때는 네트워크 및 HTTP 오류 처리, 재시도 횟수 제한, 실패 알림을 추가하는 것이 좋습니다. 요청 URL 전체를 출력하지 마세요. URL에 액세스 키가 들어 있습니다. 여러 사용자가 있는 팀이라면 실행 환경의 비밀 관리 서비스에 키를 보관하고 내부 규정에 따라 결과 파일에 대한 액세스를 제한하는 것이 바람직합니다.
이 목록으로 알 수 있는 것
스크립트를 실행하면 팀은 키워드로 발견한 영상의 재현 가능한 목록과 각 후보가 대기열에 포함된 명확한 근거를 얻게 됩니다. 표에서 관련 없는 일치 항목을 수동으로 제외하고, 검토자를 지정하거나 표식 및 크리에이터별로 결과를 묶을 수 있습니다. 정기적으로 수집하면 특정 날짜에 반환된 결과에 어떤 영상이 있었는지도 기록으로 남습니다.
이 방법은 자료를 처음 발견하고 검토 담당자에게 전달하는 데 적합하며, 규정 준수 여부를 자동으로 판정하는 용도가 아닙니다. 검색 결과와 선택한 키워드, 요청 설정, 텍스트 표식에 한계가 있습니다. 특정 협업을 검토하려면 영상을 브리프 및 팀이 보유한 정보와 대조한 뒤, 적용되는 규정에 따라 메시지 자체를 평가하세요.
시작하기 전에 TikTok Scraper API 제품 페이지에서 최신 액세스 권한과 매개변수를 확인하고, 응답 형식과 통합 옵션은 공식 API 문서와 대조하세요.
