如何用 Python 归档 TikTok 搜索结果

营销活动启动后，团队可能会想查看所选关键词的搜索结果中出现了哪些公开视频。手动搜索难以重复，也难以在几天后进行比较。一个小型采集器可以按计划执行相同的搜索请求，并按日期和搜索词归档响应，方便分析人员核查记录并编制自己的摘要。

本指南展示一个用 Python 构建的归档流程，用于保存固定搜索词的结果。与监控单个话题标签或账号不同，这种方法的比较关键在于重复使用相同的搜索词，并为每次响应单独保存快照。jsonscraper 的 TikTok Scraper API页面列出了基础地址和 GET /searchVideo 路由；该路由文档规定，搜索词必须通过必填参数 keyword 传入。

任务与测量范围

假设一位营销人员想每天收集几个固定搜索词的结果：产品名称、类别以及客户问题的描述。系统会为每个请求保存采集时间和 API 响应。检查响应示例后，可以添加对 JSON 中实际存在字段的规范化处理，例如视频标识符或公开计数值（如果响应中包含这些字段）。

归档回答的是一个具体问题：这次运行期间，针对已保存的搜索词，搜索返回了哪些记录？如果响应包含指标，多次观测可能显示不同时间记录的数值差异。这种差异仅对应可观察到的快照及其间隔；为便于比较，请保存两次采集时间和相同的字段。

将请求与响应一并保存。结果构成取决于具体搜索词和采集时间。因此，这类归档适合追踪所选查询的搜索结果，并不代表 TikTok 全部内容的完整概览。标识符、原始响应和时间戳有助于核查后续表格中每一行的来源。

检查路由及其参数

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 中包含搜索到的视频，也可能使用 tiktok.search_item_list，其中视频对象位于 aweme_info；代码兼容这两种已观察到的结构。

准备项目

创建虚拟环境并安装 requests：

python -m venv .venv
source .venv/bin/activate
pip install requests

在 PowerShell 中，使用 .venv\Scripts\Activate.ps1 激活环境。通过环境变量设置密钥和搜索词列表。对于 TikTok API，请使用文档规定的变量名 JSONSCRAPER_TIKTOK_LICENSE_KEY：

export JSONSCRAPER_TIKTOK_LICENSE_KEY="你的密钥"
export TIKTOK_QUERIES="产品名称,商品类别,客户问题"

采集并保存快照

此示例针对每个搜索词向有文档说明的路由发送一个请求，然后保存原始 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 返回了非 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"已保存查询响应：{query}")
    time.sleep(1)

print(f"已保存响应数：{len(QUERIES)}")

这个最简采集器针对每个搜索词发送一个 count=10 的请求。如需扩大采集范围，可通过 cursor 添加分页：在 API 指示还有更多结果时，将响应中的游标值传入后续请求，并为每个响应单独保存。游标和结果数量共同决定一次具体的遍历；保存的 JSON 可以让你之后核查每次请求实际返回的内容。

示例会检查外层 status，然后读取 tiktok 对象。它会收集 aweme_list 中的元素，也会收集 search_item_list[].aweme_info 中的元素（如果存在这种结构）。视频记录可能包含标识符、描述、作者、链接和统计数据；个别字段可能缺失。因此，请保存完整响应，并在规范化时检查每个字段是否存在。

一秒的间隔是脚本自身请求之间的暂停，并不代表服务的速率限制。请根据访问条件和文档设置频率与重试策略。搜索接口支持文档规定的 cache_timeout 参数，可指定以秒为单位的缓存时长；根据规范，值为 0 时会禁用缓存。当这种行为适合你的场景时，可将该参数加入请求。

根据实际响应进行规范化

首次运行后，打开保存的文件并检查 payload 结构。示例中的 extract_videos 函数会从响应格式中两个有文档说明的位置收集元素。找出分析所需字段的准确键名。如果某条记录中缺少某个字段，请将其保留为缺失值，不要填入推测的数字。

后续处理时，可以将每个找到的对象整理为一行，并附上 collected_at 和 query。已确认的字段可保存到 CSV 或数据库，原始 JSON 则保留在归档中。这样既能生成便于使用的表格，也能核查每条记录的来源。

如果 API 返回视频标识符，可用它关联同一视频在不同运行中的观测结果。每次观测都单独保存，不要覆盖历史记录。如果没有稳定标识符，请先检查哪些属性可用于匹配记录，不要认为仅凭描述文本就能确保匹配成功。

比较快照并准备报告

完成规范化后，按经过核实的标识符分组，并按采集时间排序。对于计数器字段，可以用常规代码计算相邻两次观测的差值。例如，从 12,400 变为 18,900，表示该计数器在这两个快照之间增加了 6,500。报告中应注明观测日期和原始字段，方便读者核查计算过程。

最终表格可包含搜索词、帖子标识符、采集时间以及响应中的所选字段。摘要可以按查询分组，并依据一个已确认的计数器排序。这样团队就能获得一份可核查的返回记录列表，以供后续查看；表格或消息的生成应作为单独步骤，在检查实际模式之后实现。

首先将 JSON 文件保存在本地。开始定期采集后，可将规范化后的行迁移到 PostgreSQL 或分析型数据仓库，并将原始响应存入对象存储，在文件名中注明日期和查询词。保留原始文件在改进解析器时尤其有用：无需再次调用 API，就可以在历史数据上重新运行解析程序。

按计划运行采集

若要建立每日归档，可通过 cron 或当前环境中的其他调度程序调用脚本。例如，可以设置一个任务，每天运行一次 Python 文件，并通过环境变量传入密钥和搜索词。定期使用前，先检查一个请求，再检查完整列表，最后才接入调度程序。

为确保可靠运行，请记录每个请求的状态，在临时错误时限制重试次数，并在某个搜索词采集失败时标记本次采集不完整。不要在错误消息中包含密钥。也建议按日期和查询名称区分文件，避免再次运行时覆盖先前的快照。

根据任务和请求量选择采集频率。每日概览只需每天运行一次；只有当团队关注日内变化时，更频繁的采集才有意义。先从一小组搜索词开始，检查返回结果是否有用，然后再在访问条件和数据使用规则允许的范围内扩展采集。

使用 AI 进行主题归类

确认响应模式后，可将选定的文本字段交给模型，按预先定义的主题对描述进行归类，或生成简短的摘要草稿。请将分类结果与原帖标识符、搜索词以及作为分类依据的文本片段一并保存。这样分析人员便能从模型输出追溯到原始记录。

数值差异、排序和去重应由常规代码计算。模型适合处理文本和拟写报告措辞，而计数器和时间戳应取自已保存的响应。将这些操作分开，能让每项结论的来源一目了然。

请手动检查一部分自动分类结果，并将修正内容保存为测试样例。如果不同类型的帖子经常被分到同一组，请完善类别定义并重新检查。这个流程有助于评估分类在你的任务数据上的质量。

总结：可重复的归档与可核查的摘要

运行带有 keyword 参数的文档化请求后，团队就能建立一份归档，记录运行过哪些搜索词、何时运行，以及 API 针对每个搜索词返回了哪些数据。基于这份归档，可以构建结果表格、比较不同快照中的已确认字段，并整理出供人工分析的帖子列表。

从一个测试请求开始，然后设置搜索词列表和运行计划。TikTok Scraper API 的介绍页面列出了基础地址和路由列表；/searchVideo 的参数和响应格式则见于 API 规范。归档经过核实的响应，可为基于固定搜索词的可重复分析奠定基础。