Michael Johnson마케팅팀은 TikTok에 신제품 관련 동영상이 올라오기 시작한 것을 알아차렸지만, 매일 여러 해시태그를 직접 확인하기는 어렵습니다. 게시물과 공개 지표의 변화를 시간에 따라 비교하려면 타임스탬프, 원본 응답 보관, 변경 사항 확인을 포함한 반복 가능한 수집 과정이 필요합니다.
이런 프로토타입에는 jsonscraper의 TikTok Scraper API가 적합합니다. 제품 페이지에는 해시태그, 사용자, 동영상, 검색용 엔드포인트가 나열되어 있습니다. 먼저 Postman에서 필요한 엔드포인트와 응답 형식을 확인한 뒤, 검증된 설정을 Python으로 옮기세요. 이렇게 하면 응답에 실제로 존재하는 필드만 추출하는 반복 가능한 프로세스를 만들 수 있습니다.
목표: 인기 동영상 하나가 아니라 추이를 파악하기
조회 수가 높은 게시물 하나가 눈길을 끌 수는 있지만, 캠페인을 계획할 때는 해당 주제의 새 동영상이 얼마나 발견되는지, 이미 찾은 게시물의 공개 지표가 어떻게 달라지는지를 파악하는 편이 더 유용합니다. 예를 들어 스포츠용품 온라인몰은 관련 크리에이티브를 준비하기 전에 특정 운동 종목에 관한 동영상이 얼마나 올라오는지 평가하고 싶을 수 있습니다.
수작업으로 확인하면 비교하기 어렵습니다. 검색 결과가 바뀌고 지표는 누적되며, 직원마다 서로 다른 형식으로 기록할 수 있습니다. 각 실행의 스냅샷을 수집 시각 및 원본 JSON과 함께 저장하면 팀은 자체 관측 기록을 확보하고 분석 스키마가 바뀌었을 때 데이터를 다시 처리할 수 있습니다.
자동화는 몇 단계로 이뤄집니다. 엔드포인트와 매개변수를 확인하고, 일정에 따라 데이터를 요청하고, 응답을 저장한 다음, 구조를 검증하고 필요한 필드를 추출합니다. 이렇게 만든 표는 그래프, 주제 분류 또는 보고서에 사용할 수 있습니다.
API 문서에서 확인할 수 있는 내용
TikTok Scraper API 페이지에는 기본 주소 https://tiktok.evelode.com와 Hashtag 유형의 엔드포인트인 GET /getHashtagInfo, GET /getHashtagFeed, GET /getHashtagFeedByID가 나와 있습니다. 이 페이지에는 license_key 매개변수를 사용하는 다른 엔드포인트의 요청 예시도 있으며, Postman 컬렉션에서 키를 설정하는 방법도 설명합니다.
GET /getHashtagFeed에 대해 공식 엔드포인트 명세는 필수 매개변수 query(해시태그 URL 또는 태그 이름)와 선택 매개변수 cursor, count, region, cache_timeout을 안내합니다. 피드 응답에는 tiktok.aweme_list 배열이 예상되며, 항목 필드로 aweme_id, desc, create_time, share_url, 작성자 데이터, statistics가 나열되어 있습니다. 개별 필드는 누락될 수 있으므로 처리하기 전에 실제 JSON을 확인하세요.
Postman의 jsonscraper 컬렉션에서 테스트 요청을 실행하고 실제 응답을 확인한 다음, 코드를 검증할 테스트 사례를 얻을 수 있습니다. 인증에는 license_key를 전달하세요. 키는 환경 변수에 보관하고 로그에 출력하지 마세요.
먼저 Postman에서 요청 확인하기
테스트용 해시태그 하나로 시작하세요. 컬렉션에서 해시태그 피드 엔드포인트를 선택하고 문서에 안내된 방식으로 license_key를 설정한 뒤, 태그 이름을 query에 전달합니다. 필요하다면 count와 국가 코드를 나타내는 region을 추가하세요. 요청을 실행하고 HTTP 상태, 최상위 status 필드, tiktok.aweme_list 내용을 확인합니다.
성공한 응답을 테스트 JSON 파일로 저장하세요. 이를 바탕으로 게시물 ID, 설명, 게시 시각, 링크, 통계의 존재 여부를 확인합니다. 해당 필드가 필요한 유형으로 전달되는지 확인한 뒤에만 분석 스키마에 포함하세요.
API 키는 소스 파일이 아니라 환경 변수에 보관하세요. 키가 URL로 전달된다면 요청을 기록할 때 키를 마스킹해 전체 주소가 로그에 남지 않도록 하세요.
요청과 보관을 위한 Python 클라이언트
아래 엔드포인트와 매개변수 이름은 게시된 명세에 따릅니다. 해시태그에는 query를 사용하고, 인증 정보는 license_key로 전달합니다. 이 예제는 Python 3.8 이상과 호환되며, 실행 메타데이터와 함께 원본 응답을 저장합니다.
import json
import os
from datetime import datetime, timezone
from pathlib import Path
import requests
BASE_URL = "https://tiktok.evelode.com"
API_KEY = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
def fetch_hashtag_feed(hashtag: str) -> dict:
params = {
"license_key": API_KEY,
"query": hashtag,
"count": 20,
}
response = requests.get(
f"{BASE_URL}/getHashtagFeed",
params=params,
timeout=45,
)
response.raise_for_status()
payload = response.json()
if payload.get("status") != "ok":
raise RuntimeError("API가 ok가 아닌 상태를 반환했습니다")
return payload
def archive_response(hashtag: str, payload: dict) -> Path:
collected_at = datetime.now(timezone.utc).isoformat()
safe_tag = hashtag.lstrip("#").replace("/", "_")
output_dir = Path("data/raw") / safe_tag
output_dir.mkdir(parents=True, exist_ok=True)
filename = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ.json")
file_path = output_dir / filename
file_path.write_text(
json.dumps(
{
"hashtag": hashtag,
"collected_at": collected_at,
"response": payload,
},
ensure_ascii=False,
indent=2,
),
encoding="utf-8",
)
return file_path
if __name__ == "__main__":
tag = "#예시주제"
payload = fetch_hashtag_feed(tag)
saved_path = archive_response(tag, payload)
print(f"보관 파일 저장 완료: {saved_path}")
실행하기 전에 JSONSCRAPER_TIKTOK_LICENSE_KEY 환경 변수를 설정하세요. 이 요청은 확인된 query를 사용하고 count로 요청할 항목 수를 제한합니다. 응답의 외부 상태와 JSON 상태를 확인하며, 보관한 실제 데이터는 이후 처리에 활용할 수 있습니다. 일정과 분석 기능을 추가하기 전에 해시태그 하나로 실행을 확인하세요.
취약한 가정 없이 정규화하기
문서에는 피드 응답에 tiktok.aweme_list 배열이 있다고 안내되어 있습니다. 변환하기 전에 tiktok이 객체이고 aweme_list가 목록인지 확인하세요. 각 항목에서 aweme_id, desc, create_time, share_url 같은 확인된 필드와 statistics의 값을 추출하되, 실제로 존재하는 경우에만 처리합니다.
내부 테이블에는 요청 해시태그, 수집 시각, 동영상 ID, 선택한 지표를 넣을 수 있습니다. 선택 항목이거나 없는 지표는 빈 값으로 저장하세요. 지표가 없는 경우와 측정값이 0인 경우는 다릅니다. 새로 요청하지 않고 테이블을 다시 만들 수 있도록 원본 응답은 별도로 보관하세요.
응답 형식이 바뀌면 유형 검증을 통해 잘못된 처리를 중단하고 진단 메시지를 생성해야 합니다. 파서 테스트와 함께 테스트용 JSON을 저장하세요. 이렇게 하면 코드의 새 버전이 알려진 스키마를 계속 처리하는지 확인할 수 있습니다.
반복 관측을 기반으로 한 지표
응답에 카운터가 포함된다면 각 관측값을 타임스탬프와 함께 저장하세요. 한 게시물의 두 차례 실행에서 값을 비교해 그 사이의 관측된 변화를 계산할 수 있습니다. 비교에는 명세에 나온 aweme_id를 사용하고, 각 항목에 해당 ID가 있는지 확인하세요.
하루 동안 처음 발견한 게시물 수는 실행 결과를 바탕으로 셀 수 있습니다. 이 지표는 특정 매개변수와 일정으로 실행한 요청에서 반환된 게시물 흐름을 나타냅니다. 수집 방법을 일관되게 유지하면 자체 스냅샷을 비교하는 데 도움이 됩니다.
최소한의 보고서에는 날짜별 신규 발견 게시물 수, 사용 가능한 카운터의 분포, 다시 발견된 동영상의 값 변화가 포함될 수 있습니다. 분석가가 각 기록의 출처를 확인할 수 있도록 요청 시각과 원본 파일 이름을 추가하세요.
일정 설정과 오류 처리
요청과 파싱을 검증한 다음 cron, GitHub Actions 또는 데이터 오케스트레이터 등을 이용해 스크립트를 일정에 따라 실행하세요. 해시태그 목록은 별도 설정 파일로 분리하면 클라이언트 로직을 수정하지 않고도 주제를 추가하거나 삭제할 수 있습니다.
자동 실행에는 타임아웃, 일시적인 네트워크 오류에 대한 제한된 재시도 횟수, HTTP 상태와 요청 소요 시간 기록을 설정하세요. 로그에 키를 기록하지 마세요. 파싱에 실패하면 안전한 진단 정보를 저장하고 담당자에게 알립니다.
명세에 따르면 해시태그 피드는 cursor 매개변수로 페이지네이션을 지원합니다. 페이지네이션이 필요하다면 응답에서 커서를 저장하고 변환하지 않은 채 다음 요청에 전달하세요. 반환된 결과만 처리하고, has_more가 존재하면 이를 확인합니다. 여러 해시태그 요청에서 동일한 게시물이 반환되는 경우, 게시물을 해시태그별로 따로 집계할지 고유 동영상만 계산할지 작업 목적에 맞춰 중복 제거 키를 정하세요.
분류와 보고서 자동화
검증된 행을 확보한 뒤에는 동영상 설명을 지정한 주제로 분류할 수 있습니다. desc 필드는 항목 스키마에 나와 있습니다. 모델은 게시물을 튜토리얼, 리뷰, 사용자 경험 등 형식별로 묶을 수 있습니다. 원문, 라벨, 지시문 버전, 결과를 저장하고 판단이 불확실한 사례는 사람이 검토하도록 하세요.
재실행해도 산술 결과를 재현할 수 있도록 수치 지표는 일반 코드로 계산하세요. 분류기는 텍스트 처리에 유용하지만, 최종 보고서는 결론을 구체적인 행 및 관측 날짜와 연결해야 합니다.
노코드 시나리오에서는 같은 단계를 자동화 도구로 연결할 수 있습니다. 일정 실행, 검증된 설정에 따른 HTTP 요청, 응답 확인, JSON 저장, 검증된 필드 변환, 오류 알림 순입니다. 먼저 Postman에서 계약을 확인한 뒤 Python, n8n 또는 Make로 옮기세요.
기대할 수 있는 결과와 다음 단계
설정을 마치면 팀은 선택한 해시태그의 API 응답 보관본과 관측 테이블을 갖게 됩니다. 이를 통해 새 게시물을 찾고, 시간이 지나며 사용 가능한 지표를 비교하고, 심층 분석할 자료를 선택할 수 있습니다. 결과를 비교할 수 있도록 일정, 요청 매개변수, 정규화 규칙을 일관되게 유지하세요.
엔드포인트 하나와 실제 응답 하나로 시작하세요. query 매개변수와 함께 /getHashtagFeed 요청을 실행하고 JSON을 저장한 다음 필드 파싱과 일정 실행을 추가합니다. TikTok Scraper API 페이지에는 기본 주소와 엔드포인트 목록이 나와 있으며, 엔드포인트 명세에는 클라이언트 구현에 필요한 매개변수 이름이 정리되어 있습니다.