원시 조회수를 비교하지 않고 참여도가 높아지는 TikTok 동영상 찾기

특정 TikTok 동영상의 반응이 늘고 있는지 알아보려면 공개 지표를 이전에 기록한 스냅샷과 비교하세요. 한 번 검색하면 이미 누적된 조회수와 반응을 확인할 수 있지만, 검색으로 찾은 같은 동영상을 다시 수집해야 두 실행 사이의 변화를 볼 수 있습니다. 아래는 검색 요청, CSV에 지표 저장, 변화량 계산을 수행하는 최소한의 실용적인 Python 파이프라인입니다.

이 모니터링은 무엇을 측정하나요?

이 스크립트는 주제별로 검색된 동영상 목록과 확인 가능한 관찰 기록이 필요한 마케터, 분석가 또는 개발자를 위한 것입니다. 예를 들어 한 팀이 제품 출시나 특정 고객층의 검색어와 관련된 동영상을 정기적으로 추적하면서, 이전 확인 이후 어떤 동영상의 조회수, 좋아요, 댓글 또는 공유가 늘었는지 확인하려 할 수 있습니다.

비교의 핵심 단위는 aweme_id로 식별하는 동영상입니다. 각 기록에는 수집 시각, 식별자, 설명, URL, 작성자 이름, 그리고 제공되는 카운터 값이 저장됩니다. 그런 다음 두 스냅샷을 식별자로 대조합니다. 이렇게 하면 한 동영상의 조회수 증가량이 다른 동영상의 누적 조회수와 뒤섞이지 않습니다.

결과는 특정 실행 시 특정 검색어로 반환된 동영상만 설명합니다. 검색 결과는 달라질 수 있고 통계의 일부 필드가 없을 수도 있습니다. 따라서 스냅샷 자체와 수집 시각을 보관하고, 보고서는 해당 주제의 게시물을 모두 망라한 목록이 아니라 이미 찾은 동영상을 관찰한 기록으로 해석하는 편이 좋습니다.

API를 통한 수집은 어떻게 작동하나요?

TikTok Scraper API 문서에는 GET 경로 /searchVideo가 설명되어 있습니다. 검색에는 keyword 문자열이 필수이며, 추가 매개변수로 count, region, sort_by, date_posted를 사용할 수 있습니다. API 키는 license_key로 전달합니다. 문서에 기재된 기본 엔드포인트는 https://tiktok.evelode.com입니다.

응답에는 외부 상태와 tiktok 객체가 포함됩니다. 검색 결과 동영상은 tiktok.aweme_list 또는 tiktok.search_item_list[].aweme_info 안에 있을 수 있습니다. 아래 처리기는 두 가지 형식을 모두 지원합니다. 지표는 statistics에서 가져오며, 여기에는 play_count, digg_count, comment_count, share_count가 포함됩니다. 값이 없으면 0으로 대체하지 않고 빈 값으로 저장합니다.

엔드포인트 문서에는 검색 결과 페이지를 넘길 때 사용하는 cursor가 나와 있으며, date_posted와 sort_by에서 사용할 수 있는 값도 안내되어 있습니다. 간단하고 반복 가능한 모니터링이라면 우선 결과의 첫 페이지를 받아 응답을 기록하고, 필요할 때만 페이지네이션을 추가하면 됩니다. 페이지네이션이 필요하다면 받은 커서를 변환하지 말고 그대로 전달하세요.

Python 실습 예제

python -m pip install requests 명령으로 requests 라이브러리를 설치하고, 환경 변수 JSONSCRAPER_TIKTOK_LICENSE_KEY에 키를 설정하세요. 스크립트는 검색 문구를 인수로 받아 찾은 스냅샷을 하나의 CSV 파일에 추가합니다. 코드는 Python 3.8 이상과 호환됩니다.

import csv
import os
import sys
from datetime import datetime, timezone
from pathlib import Path

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
CSV_PATH = Path("tiktok_video_snapshots.csv")
FIELDS = [
    "collected_at", "aweme_id", "author", "description", "share_url",
    "play_count", "digg_count", "comment_count", "share_count",
]


def extract_items(payload):
    """Support the observed search response layouts."""
    data = payload.get("tiktok") or {}
    items = data.get("aweme_list") or []
    if items:
        return items

    found = []
    for result in data.get("search_item_list") or []:
        info = result.get("aweme_info")
        if info:
            found.append(info)
    return found


def main():
    key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
    if not key:
        raise SystemExit("Set JSONSCRAPER_TIKTOK_LICENSE_KEY first")
    if len(sys.argv) < 2:
        raise SystemExit('Usage: python collect.py "search phrase"')

    params = {
        "license_key": key,
        "keyword": sys.argv[1],
        "count": 20,
        "region": "US",
        "sort_by": "relevance",
        "date_posted": "this-week",
    }
    response = requests.get(BASE_URL, params=params, timeout=30)
    response.raise_for_status()
    payload = response.json()

    if payload.get("status") != "ok":
        raise RuntimeError("API returned a non-ok outer status")
    data = payload.get("tiktok") or {}
    items = extract_items(payload)
    collected_at = datetime.now(timezone.utc).isoformat()

    rows = []
    for item in items:
        stats = item.get("statistics") or {}
        author = item.get("author") or {}
        rows.append({
            "collected_at": collected_at,
            "aweme_id": item.get("aweme_id"),
            "author": author.get("unique_id") or author.get("nickname"),
            "description": item.get("desc"),
            "share_url": item.get("share_url"),
            "play_count": stats.get("play_count"),
            "digg_count": stats.get("digg_count"),
            "comment_count": stats.get("comment_count"),
            "share_count": stats.get("share_count"),
        })

    write_header = not CSV_PATH.exists()
    with CSV_PATH.open("a", newline="", encoding="utf-8") as file:
        writer = csv.DictWriter(file, fieldnames=FIELDS)
        if write_header:
            writer.writeheader()
        writer.writerows(rows)

    print("Saved", len(rows), "returned videos")
    print("has_more:", data.get("has_more"), "cursor:", data.get("cursor"))


if __name__ == "__main__":
    main()

예를 들어 python collect.py "제품 관련 검색어"로 실행하세요. 라이브러리가 키를 URL 매개변수에 넣으며, 스크립트는 키를 터미널에 출력하지 않습니다. 요청 URL에 키가 포함되어 있으므로 전체 URL을 공개 로그에 저장하지 마세요. 운영 환경에서는 비밀 정보 저장소를 사용하고 스냅샷 파일의 접근을 제한하세요.

실행 간 증가량 계산하기

이 스크립트는 이전 값을 덮어쓰지 않고 모든 관측값을 기록합니다. 다음의 간단한 분석기는 동영상별로 가장 최근 스냅샷 두 개를 대조해 카운터의 차이를 출력합니다. 두 기록 중 하나에서 지표 값이 없으면 결과를 사용할 수 없는 값으로 표시합니다.

import csv
from collections import defaultdict
from pathlib import Path

rows_by_video = defaultdict(list)
with Path("tiktok_video_snapshots.csv").open(encoding="utf-8", newline="") as file:
    for row in csv.DictReader(file):
        if row["aweme_id"]:
            rows_by_video[row["aweme_id"]].append(row)

metrics = ("play_count", "digg_count", "comment_count", "share_count")
for video_id, snapshots in rows_by_video.items():
    snapshots.sort(key=lambda row: row["collected_at"])
    if len(snapshots) < 2:
        continue
    previous, latest = snapshots[-2], snapshots[-1]
    changes = {}
    for metric in metrics:
        old, new = previous[metric], latest[metric]
        changes[metric] = int(new) - int(old) if old and new else None
    print(video_id, changes, latest["share_url"])

변화량은 저장된 두 값의 차이이지, 주기가 보장된 성장 속도는 아닙니다. 실행 간격이 다르다면 collected_at을 사용해 두 시점 사이의 시간을 계산하고 실제 경과 시간에 따른 증가량을 비교하세요. 관측 사이에 카운터가 달라질 수 있으므로, 저장된 타임스탬프를 통해 사용한 값이 언제 수집되었는지 확인할 수 있습니다.

보고서를 자동화하고 해석하는 방법

일일 보고서를 만들려면 서버나 CI의 작업 스케줄러에 수집 작업을 등록하고, 고정된 검색어 목록을 설정한 다음 CSV를 저장하거나 행을 데이터베이스에 적재하세요. 반복 실행 때 검색 결과에 중복이 있으면 스냅샷 내에서 aweme_id 기준으로 중복을 제거하세요. 기록을 위해 원본 JSON도 정규화된 열과 함께 보관하면 보고서 스키마가 바뀌어도 다시 처리하기 쉽습니다.

표에는 동영상 ID와 URL, 작성자, 설명, 수집 시각, 지표별 변화량을 표시하면 좋습니다. 조회수 증가량으로 정렬하면 확산 정도를 확인할 수 있고, 댓글이나 공유 증가량으로 정렬하면 다른 유형의 반응을 구분할 수 있습니다. 각 카운터의 의미가 다르므로 명확한 규칙 없이 하나의 점수로 합산하지 마세요.

스케줄러에서 이메일, 스프레드시트 또는 내부 채널로 보고서를 보낼 수 있지만, 그 단계는 사용자의 인프라에서 수행해야 합니다. 위 예제는 데이터 수집과 분석만 합니다. 더 많이 수집하려면 결과 페이지를 순회하며 커서를 저장하고, API가 다음 페이지가 없다고 알리면 반복을 멈추면 됩니다. 검색 커서는 응답에서 받은 불투명한 값이므로 직접 계산하지 마세요. 페이지를 모두 순회하더라도 반환된 검색 결과를 설명할 뿐, 조건에 맞는 모든 게시물의 완전한 목록을 보장하지는 않습니다.

실무에서 기대할 수 있는 결과는 재현 가능한 관측 기록과 찾은 동영상의 변화량 표입니다. 이를 통해 확인 사이에 공개 카운터가 변한 게시물을 파악하고, 구체적인 링크를 전문가에게 전달해 내용을 분석할 수 있습니다. 제품 상세 정보와 API 이용 방법은 TikTok Scraper API 페이지에서 확인할 수 있습니다.

예약 실행 전에 확인할 사항

• tiktok을 처리하기 전에 외부 응답 상태가 ok인지 확인하세요.
• 검색 결과 항목의 두 가지 구조를 모두 확인하세요. 목록이 없으면 오류를 내는 대신 빈 결과로 수집해야 합니다.
• 원본 값과 타임스탬프를 보존하세요. 지표가 비어 있으면 빈 값으로 유지합니다.
• 스냅샷 비교를 더 명확하게 하려면 같은 검색어와 매개변수를 사용하고, 설정 변경 사항은 보고서와 함께 기록하세요.
• 실행 빈도, HTTP 오류, 기록 크기를 관리하고 적용되는 플랫폼 규칙과 데이터 처리 요건을 준수하세요.

요약하면, 관측 결과를 얻으려면 같은 검색을 반복하고 aweme_id로 동영상을 식별한 다음 시간에 따른 저장 지표를 비교하면 됩니다. 이 방법은 이미 찾은 동영상 중 무엇의 공개 카운터가 두 차례 확인 사이에 변했는지라는 구체적인 실무 질문에 답하며, 원본 데이터를 감사와 후속 처리에 활용할 수 있도록 남겨 둡니다.