jsonscraper
시장
저널로 돌아가기

TikTok 검색을 주간 변경 로그로 만드는 방법

Python 스크립트로 새로 발견된 동영상을 저장하고 ID를 대조해 정기 검토용 CSV를 생성합니다

편집 정책 오류 제보

TikTok 검색 주간 보고서는 지난번 실행 이후 새 표본에 어떤 동영상이 추가됐는지 보여줄 때 유용합니다. 이미 확인한 동영상 ID를 저장하고 새로운 결과를 CSV에 추가하면 됩니다. 아래는 TikTok Scraper API를 사용하는 재현 가능한 Python 스크립트입니다. 키워드로 동영상을 요청하고, 문서에 설명된 두 가지 응답 형식을 모두 파싱하며, ID의 로컬 데이터베이스를 관리합니다.

목표: 전체 결과를 다시 살펴보지 않고 새 항목 찾기

지원팀, 시장 조사자 또는 콘텐츠 분석가는 제품 관련 검색어로 공개 동영상을 정기적으로 수집해야 할 수 있습니다. 매번 결과 전체를 내보내면 반복되는 동영상 때문에 검토가 번거로워지고 새 항목이 기존 자료 사이에 묻힐 수 있습니다. ID 로그를 사용하면 각 실행 결과를 비교할 수 있습니다. CSV에는 이 프로세스에서 새로 확인된 동영상과 응답에 포함된 주요 필드만 담깁니다.

이 로그는 범위가 제한적이지만 실용적인 질문에 답합니다. 현재 실행의 응답에 나타났으며 저장된 ID 집합에는 없던 항목은 무엇인가? 이 결과는 수동 검토 대기열로 활용하거나 스프레드시트 또는 후속 분석에 전달하기 좋습니다. 수집 결과는 지정한 쿼리에 대한 API 응답을 반영할 뿐이며, TikTok의 모든 게시물을 설명하지는 않습니다.

준비 사항

  • Python 3.8 이상.
  • TikTok Scraper API 액세스 및 라이선스 키.
  • 제품명이나 구체적인 문구처럼 의미를 바꾸지 않고 반복해서 사용할 수 있는 쿼리.

키는 스크립트 파일에 넣지 말고 JSONSCRAPER_TIKTOK_LICENSE_KEY 환경 변수에 저장하세요. 아래 예시에서는 API 스키마에 따라 키를 license_key 쿼리 매개변수로 전달합니다. 실행 로그에 키를 출력하지 마세요.

export JSONSCRAPER_TIKTOK_LICENSE_KEY="your_key"
python -m pip install requests

Windows PowerShell에서는 다음과 같이 현재 세션에 변수를 설정할 수 있습니다. $env:JSONSCRAPER_TIKTOK_LICENSE_KEY="your_key". 실제 비밀 정보를 Git이나 공유 CSV에 추가하지 마세요.

연동: 검색을 요청하고 JSON 정규화하기

동영상 검색을 위해 문서에는 필수 keyword 매개변수를 받는 GET 경로 /searchVideo가 설명되어 있습니다. 요청에는 count, 지역, 정렬, 기간 필터, 결과 탐색용 커서를 지정할 수도 있습니다. 이 최소 예제에서는 키워드, 요청 항목 수, 미국 지역만 사용합니다. TikTok API 경로 안내서에서 매개변수의 정확한 이름을 확인할 수 있습니다.

검색 응답은 구조를 별도로 살펴야 합니다. aweme_list 배열이 비어 있을 수 있고, 동영상 항목은 데이터가 aweme_info 안에 중첩된 search_item_list에 있을 수도 있습니다. 따라서 코드는 두 경로를 모두 확인한 뒤 항목을 합치고 aweme_id를 기준으로 중복을 제거합니다. 이렇게 하면 JSON을 정상적으로 파싱했는데도 보고서가 비어 있는 것으로 잘못 처리되는 일을 방지할 수 있습니다.

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

import requests

BASE_URL = "https://tiktok.evelode.com/searchVideo"
KEYWORD = "product name"
REGION = "US"
COUNT = 30
STATE_FILE = Path("seen_video_ids.json")
OUTPUT_FILE = Path("new_tiktok_videos.csv")

license_key = os.environ.get("JSONSCRAPER_TIKTOK_LICENSE_KEY")
if not license_key:
    raise RuntimeError("Set JSONSCRAPER_TIKTOK_LICENSE_KEY")

response = requests.get(
    BASE_URL,
    params={
        "license_key": license_key,
        "keyword": KEYWORD,
        "count": COUNT,
        "region": REGION,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

# The example response contains an outer status and a nested tiktok object.
if "status" in data and data["status"] != "ok":
    raise RuntimeError("API returned a status other than ok")

tiktok = data.get("tiktok") or {}
items = list(tiktok.get("aweme_list") or [])
for entry in tiktok.get("search_item_list") or []:
    info = entry.get("aweme_info")
    if isinstance(info, dict):
        items.append(info)

# Unique items in the current response, preserving order.
current = {}
for item in items:
    video_id = item.get("aweme_id")
    if video_id:
        current[str(video_id)] = item

if STATE_FILE.exists():
    seen = set(json.loads(STATE_FILE.read_text(encoding="utf-8")))
else:
    seen = set()

new_items = [(video_id, item) for video_id, item in current.items()
             if video_id not in seen]
run_time = datetime.now(timezone.utc).isoformat()

fields = ["collected_at_utc", "query", "aweme_id", "created_at",
          "author", "description", "share_url", "play_count",
          "digg_count", "comment_count", "share_count"]
write_header = not OUTPUT_FILE.exists() or OUTPUT_FILE.stat().st_size == 0
with OUTPUT_FILE.open("a", newline="", encoding="utf-8") as f:
    writer = csv.DictWriter(f, fieldnames=fields)
    if write_header:
        writer.writeheader()
    for video_id, item in new_items:
        author = item.get("author") or {}
        stats = item.get("statistics") or {}
        writer.writerow({
            "collected_at_utc": run_time,
            "query": KEYWORD,
            "aweme_id": video_id,
            "created_at": item.get("create_time"),
            "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"),
        })

seen.update(current.keys())
STATE_FILE.write_text(json.dumps(sorted(seen)), encoding="utf-8")
print(f"Response: {len(current)} unique videos; new: {len(new_items)}")

JSON에 값이 없는 항목은 CSV에서 빈 셀로 기록됩니다. 개별 레코드에 필드나 지표가 없을 수도 있기 때문입니다. 코드는 누락된 값을 0으로 바꾸지 않으며, 0을 데이터 누락으로 간주하지도 않습니다. 수집 시각과 API가 create_time 필드로 반환하는 게시 시각은 별도로 기록됩니다.

변경 확인 방식

  1. 요청은 지정된 키워드의 검색 결과 페이지를 반환합니다.
  2. 정규화 단계에서 aweme_list와 search_item_list[].aweme_info의 레코드를 모읍니다.
  3. 스크립트는 동영상 ID를 기준으로 응답 내 중복을 제거합니다.
  4. ID를 로컬 JSON 로그와 대조합니다.
  5. 새 ID를 CSV에 추가한 다음, 확인한 전체 집합을 저장해 다음 실행에 사용합니다.
기사: TikTok 검색을 주간 변경 로그로 만드는 방법
요약: 키워드로 TikTok 동영상을 반복 수집하고 API 응답의 두 가지 형식을 처리하세요. 중복을 제거하고 주간 보고서에 새 항목만 저장하는 방법을 알아봅니다.
이미지 역할: 보조 일러스트 2 — 다른 구체적 측면
섹션: 변경 확인 방식
시각적 주제: 다섯 가지 검증된 작업 단계를 러시아어 레이블로 보여주는 명확한 인포그래픽: 검색 요청 / 두 응답 배열 / awe 기준 중복 제거
이 도식은 검색 응답에서 새 항목 CSV와 다음 실행에 사용할 JSON 로그까지의 흐름을 보여줍니다.© jsonscraper · AI 생성 일러스트
기사: TikTok 검색을 주간 변경 로그로 만드는 방법
요약: 키워드로 TikTok 동영상을 반복 수집하고 API 응답의 두 가지 형식을 처리하세요. 중복을 제거하고 주간 보고서에 새 항목만 저장하는 방법을 알아봅니다.
이미지 역할: 표지 — 핵심 아이디어
섹션: 변경 확인 방식
시각적 주제: 주간 데이터 검토를 표현한 에디토리얼 정물화: 공개 짧은 동영상 검색 결과를 나타내는 반투명 카드 더미와 옆에 놓인 새 카드, 간결한
로컬 로그에 새로 추가된 ID와 다시 검색된 동영상을 구분합니다.© jsonscraper · AI로 제작

스크립트를 동료에게 전달할 때 이 과정을 시각화하면 유용합니다. CSV는 추가 전용 로그이고 JSON은 중복 제거 상태를 나타냅니다. 두 파일은 코드와 별도로 보관하고 함께 백업할 수 있습니다. 팀 또는 클라우드에서 실행하려면 로컬 JSON 파일을 적절한 영구 저장소로 바꾸고, 병렬 실행이 서로의 상태를 덮어쓰지 않도록 원자적 업데이트를 구현하세요.

재실행 및 페이지네이션

운영체제 스케줄러, CI 작업 또는 자동화 워크플로를 사용해 정기적으로 실행하세요. 쿼리의 의미를 바꾸지 않고 키워드를 수정하지 마세요. 서로 다른 쿼리는 서로 다른 표본을 만들므로 하나의 로그에 섞으면 해석이 어려워집니다. 간단한 예제 스크립트는 쿼리 하나를 사용하지만, 쿼리 목록을 반복 처리하고 각 행에 query 필드를 저장할 수도 있습니다.

API는 검색 결과를 탐색할 때 cursor를 지원합니다. 페이지네이션을 추가한다면 이전 응답의 커서를 전달하고, 이를 불투명한 값으로 저장하며, 추가 페이지가 필요하지 않을 때 탐색을 멈추세요. count는 요청할 항목 수를 지정하지만 실제 레코드 수는 응답으로 확인해야 합니다. 여러 페이지를 가져오더라도 이는 검색 결과 페이지일 뿐, 플랫폼 전체를 빠짐없이 수집한다는 보장은 아닙니다.

현재 스크립트에는 텍스트 자동 분류나 ‘트렌드’ 판정이 의도적으로 포함되지 않았습니다. CSV를 통해 새로 발견된 항목을 빠르게 추릴 수 있으며, 분석가가 이후 주제, 의도 또는 질문 유형에 따라 분류하고 사례를 직접 확인할 수 있습니다. 언어 모델을 연결한다면 필요한 텍스트 필드만 전달하고, 결과를 검증하고 원본 레코드와 연결할 수 있도록 원래 ID와 함께 범주를 반환하도록 요청하세요.

점검 항목 및 흔한 오류

  • HTTP 오류. raise_for_status()는 성공 범위를 벗어난 HTTP 코드가 반환되면 실행을 중단합니다. 상태 파일을 업데이트하기 전에 API 이용 가능 여부, 매개변수, 계정을 확인하세요.
  • API 상태가 ok와 다름. 응답에 최상위 status 필드가 있고 그 값이 다르면 스크립트는 결과를 기록하기 전에 중단됩니다. 이렇게 하면 이전 로그가 보존되고, 잘못된 응답을 빈 검색 결과로 오인하지 않을 수 있습니다.
  • aweme_list가 비어 있음. search_item_list도 확인하세요. 코드는 두 구조를 모두 처리합니다.
  • 실행 간 동영상 중복. 검색 결과 페이지가 겹치면 예상되는 현상입니다. 이미 저장된 ID는 보고서에 다시 추가되지 않습니다.
  • 지표 누락. 해당 셀은 비어 있습니다. 계산할 때 누락값과 실제 0을 구분하세요.
  • 상태 파일 분실. 스크립트는 반환된 모든 ID를 새 항목으로 간주합니다. seen_video_ids.json을 CSV와 함께 백업하거나 영구 데이터베이스를 사용하세요.

자동화할 때는 키를 제외한 진단 정보를 저장하세요. 실행 시각, HTTP 코드, API 상태, 파싱된 레코드 수, 새 ID 수가 이에 해당합니다. 이를 통해 새 동영상이 없었던 경우와 요청 실패를 구별할 수 있습니다. 스키마를 나중에 재확인해야 한다면 원본 전체 응답을 별도로 보관할 수 있습니다. 팀의 목적에 맞춰 접근 권한과 보관 기간을 제한하세요.

결과

실행 후에는 로그에 새로 추가된 동영상 ID와 설명, 링크, 사용 가능한 공개 필드가 담긴 CSV와 다음 실행에서 비교할 JSON 상태 파일을 얻을 수 있습니다. 이 결과물은 지원, 분석 또는 콘텐츠 팀이 활용할 간결한 검토 대기열로 적합합니다. API 설명과 액세스 옵션은 TikTok Scraper API 페이지에서 확인할 수 있으며, 정확한 검색 매개변수는 공식 경로 안내서와 대조하세요.

사람들

아직 이 기사에 등록된 사람이 없습니다.

계속 읽으세요틱톡에서 제품 관련 반복 질문 찾기
다음 기사 읽기

읽은 내용을 실제 연동으로 구현하세요

jsonscraper 소셜 데이터 API를 살펴보고 요청을 테스트하여 다음 워크플로를 구축하세요.

API 둘러보기