JSON 파싱 시 TikTok 검색 결과를 놓치지 않는 방법

API를 통해 TikTok 동영상을 검색할 때, 처리 코드가 가장 먼저 예상하는 배열에 동영상이 없을 수 있습니다. jsonscraper의 `\/searchVideo` 요청에서 확인된 응답에서는 `aweme_list`가 비어 있었고, 동영상 데이터가 담긴 항목은 `search_item_list[].aweme_info`에 있었습니다. 코드가 `aweme_list`만 읽으면 응답에 검색 결과가 들어 있어도 동영상을 하나도 저장하지 못합니다. 개발자가 해결해야 할 구체적인 안정성 문제는 두 데이터 형태를 모두 추출해 데이터베이스에 기록하거나 보고서로 보내기 전에 하나의 목록으로 정규화하는 것입니다.

실제 사례 확인과 엔드포인트 설명은 jsonscraper API 사양과 TikTok 엔드포인트 문서에서 확인할 수 있습니다. 사양에 담긴 스키마 스냅샷의 날짜는 2026년 10월 25일입니다. 이 스냅샷은 특정 응답의 구조를 보여 주며, 이후 모든 요청에 모든 필드가 존재한다고 보장하지는 않습니다.

파서가 빈 목록을 반환할 수 있는 이유

`GET https:\/\/tiktok.evelode.com\/searchVideo` 경로는 필수 매개변수 `keyword`를 사용해 동영상을 검색합니다. 문서에는 `cursor`, `count`, `cache_timeout`, `date_posted`, `sort_by`, `region`도 나와 있습니다. 관찰된 응답 스키마의 최상위 객체에는 `status`와 중첩 객체 `tiktok`이 있습니다. 그 안에는 `cursor`, `has_more`, `status_code`, `aweme_list`, `search_item_list`가 들어 있습니다.

키워드와 `count=3`을 사용한 구체적인 사례에서는 `aweme_list` 배열이 비어 있었습니다. 반면 `search_item_list`에는 동영상 정보가 `aweme_info`에 담긴 항목이 있었습니다. 이러한 객체에는 동영상 ID, 설명, 게시물 URL, 작성자, 조회수·좋아요·댓글 수 같은 통계가 포함될 수 있습니다. 이 필드들은 관찰된 스키마를 반영하므로, 처리 코드는 여전히 값이 누락되는 상황을 허용해야 합니다.

실무적으로는 HTTP 요청의 성공 여부와 예상한 특정 필드가 비어 있지 않은지가 서로 다른 확인 사항입니다. 먼저 최상위 상태와 `tiktok` 객체의 존재를 확인한 다음, 문서에 나온 각 위치에서 동영상을 수집하세요. 분석을 위해 ID와 원본 응답을 저장하면 특정 레코드가 어떻게 추출되고 정규화되었는지 추적할 수 있습니다.

저장소에 기록하기 전에 응답 정규화하기

API와 자체 시스템 사이의 경계에는 중첩된 `tiktok` 객체를 받아 통일된 항목을 반환하는 함수를 두면 편리합니다. 이 함수는 두 배열을 모두 처리하고, 딕셔너리가 아니거나 비어 있는 항목은 건너뛰며, `aweme_id`를 기준으로 같은 동영상의 중복을 제거해야 합니다. 제공자가 카운터를 반환하지 않으면 비워 두세요. 0은 측정된 값을 뜻하지만, `None`은 해당 필드가 없다는 뜻입니다.

아래는 Python 3.8 이상을 위한 간단한 예제입니다. 요청을 한 번 보내고, 전송 상태와 최상위 상태를 확인하며, 결과의 두 가지 형태를 정규화한 다음 선택한 필드를 출력합니다. 키는 환경 변수에서 읽으며 로그에 출력하지 않습니다.

import os
import requests

BASE_URL = "https:\/\/tiktok.evelode.com"


def extract_videos(tiktok):
    candidates = []
    aweme_list = tiktok.get("aweme_list") or []
    if isinstance(aweme_list, list):
        candidates.extend(aweme_list)

    search_items = tiktok.get("search_item_list") or []
    if isinstance(search_items, list):
        for item in search_items:
            if isinstance(item, dict):
                candidates.append(item.get("aweme_info"))

    unique = {}
    for video in candidates:
        if not isinstance(video, dict):
            continue
        video_id = video.get("aweme_id")
        if video_id:
            unique[video_id] = video
    return list(unique.values())


license_key = os.environ["JSONSCRAPER_TIKTOK_LICENSE_KEY"]
response = requests.get(
    BASE_URL + "\/searchVideo",
    params={
        "license_key": license_key,
        "keyword": "python tutorial",
        "count": 10,
        "region": "US",
    },
    timeout=30,
)
response.raise_for_status()
payload = response.json()

if payload.get("status") != "ok":
    raise RuntimeError("TikTok API returned a non-ok status")

tiktok = payload.get("tiktok")
if not isinstance(tiktok, dict):
    raise RuntimeError("Response has no tiktok object")

for video in extract_videos(tiktok):
    stats = video.get("statistics") or {}
    author = video.get("author") or {}
    print({
        "aweme_id": video.get("aweme_id"),
        "desc": video.get("desc"),
        "share_url": video.get("share_url"),
        "author": author.get("unique_id"),
        "play_count": stats.get("play_count"),
        "digg_count": stats.get("digg_count"),
        "comment_count": stats.get("comment_count"),
    })

python -m pip install requests 명령으로 의존성을 설치하고, 실행 환경에 `JSONSCRAPER_TIKTOK_LICENSE_KEY`를 설정한 뒤 파일을 예를 들어 `search_videos.py`로 저장하세요. 요청 매개변수는 문서에 나온 이름인 `keyword`, `count`, `region`을 사용하며, `license_key`는 쿼리 매개변수로 전달됩니다. 이 코드는 기록된 사례처럼 응답에 `status: "ok"`가 들어 있다고 가정합니다. API가 다른 상태를 반환하면, 의심스러운 구조를 다음 단계로 전달하기 전에 처리를 중단합니다.

예제를 반복 가능한 수집 작업으로 발전시키기

일회성 내보내기라면 정규화된 항목을 JSON Lines나 표에 기록하면 충분합니다. 상시 실행하는 프로세스에는 수집 시각과 검색어를 원본 응답과 함께 저장하는 기능을 추가하세요. 정규화된 동영상용 별도 테이블에서 `aweme_id`를 키로 사용하면 반복된 결과가 기존 레코드를 갱신하고, 두 배열에 같은 ID가 있어도 중복이 생기지 않습니다.

다음 페이지를 요청할 때는 이전 응답에서 받은 값을 `cursor` 매개변수로 전달하라고 문서에서 안내합니다. 이 값을 불투명 토큰으로 취급해 변환 없이 저장하고 다시 전달하세요. 페이지네이션 루프는 `has_more`가 더 이상 이어지지 않음을 나타내거나 API가 쓸 수 있는 커서를 제공하지 않을 때 종료해야 합니다. 잘못된 로직으로 무한 루프가 생기지 않도록 한 번 실행할 때 가져올 페이지 수를 제한하세요. 확인된 자료는 매개변수 이름과 관찰된 스키마의 `cursor`, `has_more` 필드 존재를 뒷받침하지만, 결과의 완전성을 보장하지는 않습니다.

여러 검색어를 모니터링할 때는 검색어를 동영상 ID와 수집 시각과 함께 저장하세요. 그러면 검색어별로 결과를 나누고, 실행 간 결과를 비교하며, 새 ID를 추가 분류 작업 대기열에 보낼 수 있습니다. 이런 시스템이 기록하는 것은 수집된 검색 결과이며, 데이터셋은 요청, 지역, 시점, 그리고 API가 실제로 반환한 항목에 따라 달라집니다.

요청 성공 여부만 보지 말고 데이터 품질도 확인하기

정규화 후에는 자체 파이프라인의 기본 기술 지표를 기록하는 것이 좋습니다. 각 배열에서 가져온 레코드 수, 고유 ID 수, ID가 없는 항목의 비율, 통계가 없는 항목의 비율이 이에 해당합니다. 이 지표는 구체적인 응답의 처리 상태를 나타낼 뿐 동영상 인기도를 평가하지는 않습니다. 예를 들어 `play_count`가 없는 항목이 늘어나면 분석 과정에서 알 수 없는 값을 저장하고 필드의 완전성을 표시해야 합니다. 0을 대신 넣어서는 안 됩니다.

모든 동영상에 반드시 같은 통계 필드가 있다고 가정하지 마세요. 원시 데이터를 보존하려면 전체 JSON을 남기고, 분석 테이블에는 필요한 필드만 선택하며 `NULL`을 허용하세요. 응답 형식이 바뀌어도 원본 아카이브가 있으면 다시 요청하지 않고 정규화기를 재실행할 수 있습니다.

API 키는 CI 비밀 저장소나 오케스트레이터의 환경 변수를 통해 전달하세요. 로그에 저장되는 URL에 키를 넣지 말고, 요청 매개변수 객체를 출력하거나 원본 응답과 함께 키 값을 저장하지 마세요. 작업이 일정에 따라 실행된다면 요청 시간 제한, HTTP 오류 처리, 지연을 둔 재시도를 추가하세요. 페이지가 서로 다른 검색 결과끼리 섞이지 않도록 커서는 해당 검색어와 함께 저장해야 합니다.

결과: 누락된 동영상 대신 하나의 통일된 표

정규화 후에는 항목이 `aweme_list`에서 왔든 `search_item_list[].aweme_info`에서 왔든 후속 코드가 하나의 동영상 목록을 받습니다. ID를 기준으로 중복을 제거하고 선택 필드가 없는 경우에는 명시적으로 비워 둡니다. 이렇게 하면 배열 하나만 읽어서 보고서가 비는 위험을 줄이고, 내보내기·필터링·분류 같은 다음 단계의 동작을 예측하기 쉬워집니다.

TikTok Scraper API 페이지에서 기본 API 주소를 확인하고 데모로 이동할 수 있습니다. 통합에는 공식 문서를 사용하고, 먼저 적은 수의 항목으로 처리를 검증하세요. 필요하면 `count`를 늘리고 문서화된 커서를 사용해 결과를 이어서 가져오면 됩니다. 그 결과는 작업에 활용할 수 있는 정돈된 데이터 계층이지, TikTok 전체를 빠짐없이 포괄한다는 가정이 아닙니다.