Michael Johnson캠페인을 시작한 뒤에는 팀에서 선택한 검색어로 검색했을 때 어떤 공개 동영상이 표시되는지 확인하고 싶을 수 있습니다. 수동 검색은 며칠 뒤에 다시 실행하거나 결과를 비교하기 어렵습니다. 간단한 수집기를 예약 실행해 동일한 검색어로 요청하고, 날짜와 검색 문구를 함께 응답을 보관하면 분석가가 기록을 확인하고 자체 요약을 작성할 수 있습니다.
이 가이드는 고정된 검색 문구에 대한 검색 결과를 저장하는 Python 아카이브 파이프라인을 소개합니다. 개별 해시태그나 계정을 모니터링하는 것과 달리, 결과를 비교하려면 동일한 검색 문구를 반복해서 사용하고 각 응답을 별도의 스냅샷으로 저장해야 합니다. jsonscraper TikTok Scraper API 페이지에는 기본 주소와 GET /searchVideo 경로가 나와 있으며, 해당 경로의 문서에서는 필수 매개변수 keyword에 검색 문구를 전달하도록 안내합니다.
목표와 측정 범위
마케터가 제품명, 카테고리, 고객 문제 표현 등 몇 가지 고정된 문구로 검색 결과를 매일 수집한다고 가정해 보겠습니다. 각 요청에 대해 시스템은 수집 시각과 API 응답을 저장합니다. 응답 예시를 확인한 뒤에는 JSON에 실제로 포함된 필드, 예를 들어 동영상 ID나 공개 카운터가 있다면 해당 값을 정규화할 수 있습니다.
아카이브는 구체적인 질문에 답합니다. 저장된 문구로 검색했을 때 이 실행 시점에 어떤 기록이 반환되었는가? 응답에 지표가 포함되어 있다면 여러 차례 관찰을 통해 각 시점에 기록된 값의 차이를 확인할 수 있습니다. 이 차이는 관찰 가능한 스냅샷과 그 사이의 시간 간격에 해당합니다. 비교하려면 두 수집 시각과 동일한 필드를 모두 저장하세요.
요청과 응답을 함께 저장하세요. 결과 구성은 특정 검색 문구와 수집 시점에 따라 달라집니다. 따라서 이 아카이브는 선택한 검색어의 결과를 추적하는 데 유용하지만, TikTok의 모든 콘텐츠를 포괄적으로 보여 주지는 않습니다. ID, 원본 응답, 타임스탬프를 보관하면 후속 표의 각 행이 어디에서 비롯되었는지 확인할 수 있습니다.
경로와 매개변수 확인
TikTok API 경로 안내에는 기본 주소 https://tiktok.evelode.com와 GET /searchVideo가 나와 있습니다. 최신 API 사양에서는 keyword를 필수 검색 매개변수로 지정하고, 선택 매개변수로 cursor, count, cache_timeout, date_posted, sort_by, region을 열거합니다. 인증에는 license_key를 전달합니다. 경로 정보는 Python SDK 문서에서도 확인할 수 있습니다.
count와 date_posted를 사용하면 응답 크기와 시간 필터를 설정할 수 있습니다. sort_by에는 문서화된 값인 most-liked, relevance, date-posted를 사용할 수 있습니다. 페이지네이션을 사용한다면 이전 응답에서 받은 cursor를 직접 계산하지 말고 불투명한 값 그대로 전달하세요. 매일 비교할 수 있는 아카이브를 만들려면 요청 매개변수와 자체 코드 버전도 데이터와 함께 저장하세요.
아래 예제에서는 테스트 실행을 위해 작은 count 값과 고정 지역 US를 사용합니다. 매일 수집하기 전에 요청 하나를 테스트하고 HTTP 상태와 JSON 구조를 확인하세요. 응답 스키마에서는 검색된 동영상이 tiktok.aweme_list 또는 aweme_info 안에 동영상 객체가 들어 있는 tiktok.search_item_list에 포함될 수 있습니다. 코드는 관찰된 두 형식을 모두 지원합니다.
프로젝트 준비
가상 환경을 만들고 requests를 설치하세요.
python -m venv .venv
source .venv/bin/activate
pip install requestsPowerShell에서는 .venv\Scripts\Activate.ps1 명령으로 환경을 활성화합니다. 환경 변수를 사용해 키와 검색 문구 목록을 설정하세요. TikTok API에는 문서화된 환경 변수 이름인 JSONSCRAPER_TIKTOK_LICENSE_KEY를 사용합니다.
export JSONSCRAPER_TIKTOK_LICENSE_KEY="your_key"
export TIKTOK_QUERIES="product name,product category,customer problem"스냅샷 수집 및 저장
이 예제는 문서화된 경로에 각 검색 문구별로 요청을 하나씩 보내고, 원본 JSON과 수집 시각, 사용한 매개변수를 저장합니다. 파일 이름에는 날짜와 검색 문구가 포함됩니다. 키는 환경에 보관하며 아카이브에는 포함하지 않습니다.
import json
import os
import re
import time
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
ENDPOINT = "/searchVideo"
LICENSE_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
QUERIES = [
item.strip()
for item in os.environ["TIKTOK_QUERIES"].split(",")
if item.strip()
]
OUT = Path("data")
OUT.mkdir(exist_ok=True)
def safe_name(text):
cleaned = re.sub(r"[^a-zA-Z0-9_-]+", "_", text).strip("_")
return cleaned[:80] or "query"
def fetch(query):
params = {
"license_key": LICENSE_KEY,
"keyword": query,
"count": 10,
"region": "US",
}
response = requests.get(
BASE_URL + ENDPOINT,
params=params,
timeout=60,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("API returned a status other than ok")
return payload
def extract_videos(payload):
tiktok = payload.get("tiktok") or {}
videos = list(tiktok.get("aweme_list") or [])
for item in tiktok.get("search_item_list") or []:
video = item.get("aweme_info") or {}
if video:
videos.append(video)
return videos
for query in QUERIES:
collected_at = datetime.now(timezone.utc).isoformat()
payload = fetch(query)
record = {
"collected_at": collected_at,
"query": query,
"request": {
"endpoint": ENDPOINT,
"keyword": query,
"count": 10,
"region": "US",
},
"videos_found": len(extract_videos(payload)),
"payload": payload,
}
filename = OUT / f"{collected_at[:10]}_{safe_name(query)}.json"
filename.write_text(
json.dumps(record, ensure_ascii=False, indent=2),
encoding="utf-8",
)
print(f"Saved response for query: {query}")
time.sleep(1)
print(f"Responses saved: {len(QUERIES)}")이 최소 수집기는 문구당 count=10으로 요청을 한 번 보냅니다. 더 폭넓게 수집하려면 cursor를 이용한 페이지네이션을 추가하세요. API가 다음 결과가 있다고 표시하는 동안 응답의 커서 값을 전달해 요청을 계속하고, 각 응답을 별도로 기록합니다. 커서와 결과 수는 각 수집 작업의 범위를 결정합니다. 저장된 JSON을 통해 각 요청에서 실제로 무엇이 반환되었는지 나중에 확인할 수 있습니다.
예제는 최상위 status를 확인한 뒤 tiktok 객체를 읽습니다. aweme_list의 항목과 해당 형식이 존재할 경우 search_item_list[].aweme_info의 항목을 수집합니다. 동영상 레코드에는 ID, 설명, 작성자, 링크, 통계 등이 포함될 수 있지만 개별 필드는 없을 수도 있습니다. 따라서 전체 응답을 저장하고 정규화할 때는 각 필드의 존재 여부를 확인하세요.
1초 간격은 스크립트 자체 요청 사이의 대기 시간일 뿐, 서비스의 제한에 관한 설명이 아닙니다. 접근 조건과 문서를 고려해 주기와 재시도 횟수를 설정하세요. 검색에는 cache_timeout 매개변수가 문서화되어 있습니다. 사양에 따르면 이 매개변수로 캐시 시간을 초 단위로 지정할 수 있으며, 값이 0이면 캐싱이 비활성화됩니다. 해당 동작이 작업에 적합한 경우 요청에 추가하세요.
실제 응답을 바탕으로 정규화 추가
첫 실행 후 저장된 파일을 열어 payload 구조를 살펴보세요. 예제의 extract_videos 함수는 응답에 사용할 수 있는 것으로 문서화된 두 가지 검색 결과 형식에서 항목을 모읍니다. 분석에 필요한 필드의 정확한 키를 확인하세요. 특정 레코드에 필드가 없다면 추정한 숫자를 넣지 말고 누락된 값으로 저장하세요.
후속 처리를 위해 찾은 객체마다 한 행을 만들고 collected_at과 query를 추가하면 편리합니다. 확인된 필드는 CSV나 데이터베이스에 저장하고, 원본 JSON은 아카이브에 남겨 두세요. 이 두 가지를 함께 보관하면 편리한 표를 만들면서 각 레코드의 출처도 확인할 수 있습니다.
API가 동영상 ID를 반환하면 이를 사용해 여러 실행에서 같은 동영상의 관찰값을 연결하세요. 과거 데이터를 덮어쓰지 말고 각 관찰값을 별도로 보관합니다. 안정적인 ID가 없다면 먼저 어떤 속성으로 레코드를 연결할 수 있는지 확인하고, 설명 텍스트가 같다는 이유만으로 동일한 게시물이라고 단정하지 마세요.
스냅샷을 비교하고 보고서 작성
정규화한 뒤에는 검증된 ID별로 레코드를 그룹화하고 수집 시각순으로 정렬하세요. 카운터 필드는 일반 코드로 연속된 두 값의 차이를 계산할 수 있습니다. 예를 들어 값이 12,400에서 18,900으로 바뀌었다면 두 스냅샷 사이에 카운터 값이 6,500 증가한 것입니다. 보고서에 관찰 날짜와 원본 필드를 명시해 독자가 계산을 확인할 수 있게 하세요.
최종 표에는 검색 문구, 게시물 ID, 수집 시각, 응답에서 선택한 필드를 넣는 것이 좋습니다. 요청별로 요약을 그룹화하고 검증된 카운터 하나를 기준으로 정렬할 수 있습니다. 이렇게 하면 팀에서 추가로 검토할 수 있는, 반환된 레코드의 확인 가능한 목록을 만들 수 있습니다. 실제 스키마를 살펴본 뒤 별도 단계에서 표나 메시지를 구현하세요.
먼저 JSON 파일을 로컬에 저장하세요. 수집을 정기적으로 수행하게 되면 정규화된 행은 PostgreSQL이나 분석 데이터 웨어하우스로 옮기고, 원본 응답은 날짜와 요청을 파일 이름에 포함해 객체 스토리지에 보관하세요. 파서를 개선할 때 원본을 저장해 두면 API를 다시 호출하지 않고도 과거 데이터에 새 파서를 실행할 수 있어 특히 유용합니다.
예약 실행
일일 아카이브를 만들려면 cron이나 환경에서 사용할 수 있는 다른 스케줄러로 스크립트를 실행하세요. 예를 들어 작업이 Python 파일을 하루에 한 번 실행하면서 환경 변수로 키와 검색 문구를 전달하도록 설정할 수 있습니다. 정기 사용에 들어가기 전에 먼저 요청 하나를 테스트하고, 이어서 전체 목록을 시험한 다음, 마지막으로 스케줄러를 연결하세요.
안정적으로 실행하려면 요청별 상태를 저장하고 일시적 오류가 발생했을 때 재시도 횟수를 제한하세요. 검색 문구 하나라도 실패하면 수집이 불완전했음을 표시합니다. 오류 메시지에 키를 포함하지 마세요. 또한 파일을 날짜와 요청 이름별로 분리해 재실행 시 이전 스냅샷을 덮어쓰지 않도록 하는 것이 좋습니다.
작업과 요청량에 맞춰 주기를 정하세요. 일일 개요에는 하루 한 번 실행이면 충분합니다. 팀에서 하루 중 변화를 중요하게 여길 때는 더 자주 수집하는 것이 의미가 있습니다. 먼저 적은 수의 검색 문구로 시작해 결과가 유용한지 확인한 뒤, 접근 조건과 데이터 이용 규칙 범위 안에서 수집을 확대하세요.
AI로 주제별 분류하기
응답 스키마를 확인한 뒤에는 선택한 텍스트 필드를 모델에 전달해 설명을 미리 정한 주제별로 분류하거나 요약 초안을 작성할 수 있습니다. 분류 결과와 함께 원본 게시물 ID, 검색 문구, 범주의 근거가 된 텍스트 일부를 저장하세요. 그러면 분석가가 모델의 결과에서 원본 레코드로 돌아가 확인할 수 있습니다.
숫자 차이 계산, 정렬, 중복 제거는 일반 코드로 처리하세요. 모델은 텍스트 처리와 보고서 문안 작성에 활용하고, 카운터와 타임스탬프는 저장된 응답에서 가져옵니다. 작업을 이렇게 나누면 각 결과의 출처를 명확히 알 수 있습니다.
자동 분류 결과 중 일부는 직접 확인하고 수정 사항을 테스트 예시로 저장하세요. 서로 다른 게시물 유형이 반복해서 하나의 그룹에 들어간다면 범주 정의를 구체화한 뒤 다시 검토합니다. 이러한 과정으로 작업 데이터에서 분류 품질을 평가할 수 있습니다.
결론: 반복 가능한 아카이브와 검증 가능한 요약
keyword 매개변수를 사용해 문서화된 요청을 실행하면 팀은 어떤 문구를 언제 검색했으며 각 검색에 대해 API가 어떤 데이터를 반환했는지 아카이브로 보유하게 됩니다. 이를 바탕으로 결과 표를 만들고, 스냅샷 간 검증된 필드를 비교하며, 수동 분석을 위한 게시물 목록을 준비할 수 있습니다.
테스트 요청 하나로 시작한 뒤 검색 문구 목록과 실행 일정을 설정하세요. TikTok Scraper API 설명에는 기본 주소와 경로 안내가 나와 있으며, /searchVideo의 매개변수와 응답 형식은 API 사양에 설명되어 있습니다. 확인된 응답을 아카이브하면 고정된 검색 문구를 바탕으로 반복 가능한 분석을 수행할 수 있습니다.