使用 Python 监测 TikTok 话题标签：可运行的 API 请求

营销团队注意到 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。

使用 jsonscraper 的 Postman 集合可以方便地执行测试请求、核对实际响应，并取得后续代码测试所需的样例。身份验证通过 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 和选定指标。对于可选或缺失的指标，请保存为空值：指标缺失与测得为零并不相同。原始响应应单独保存，这样无需再次请求即可重新生成表格。

如果响应格式发生变化，类型检查应停止不正确的数据处理，并生成诊断消息。将测试 JSON 与解析器测试一同保存，以便验证新版本代码仍能处理已知的数据结构。

基于重复观测的指标

如果响应提供计数器，请将每次观测连同时间戳一起保存。对于同一条帖子，比较两次运行中的数值，并计算观测区间内的变化。匹配时请使用规范中列出的 aweme_id，并检查每个条目中是否都有该字段。

每日首次发现的帖子数量，可以根据运行结果计算。该指标反映的是在指定参数和计划安排下，具体请求返回的内容。如果采集方法保持一致，就可以用它比较自己的数据快照。

最简报告可以展示每天新发现的帖子数量、可用计数器的分布，以及重复发现的视频中指标值的变化。请添加请求时间和原始文件名，以便分析人员追溯每条记录的来源。

定时运行与错误处理

验证请求和解析逻辑后，可以通过 cron、GitHub Actions 或数据编排工具等方式，按计划运行脚本。将话题标签列表单独放在配置文件中，这样无需修改客户端逻辑，就能添加或移除主题。

对于自动运行，请设置超时时间、针对临时网络错误的有限重试次数，并记录 HTTP 状态和请求耗时。不要将密钥写入日志。如果解析失败，应保存安全的诊断信息，并通知负责人。

话题标签信息流接口的规范支持通过 cursor 参数进行分页。如果需要分页，请保存响应中的游标，并在下一次请求中原样传递；只处理返回的结果，并在 has_more 存在时监控其值。如果多个话题标签的请求返回同一条帖子，应根据任务选择去重键：按话题标签分别统计帖子，还是只统计唯一视频。

分类与报告自动化

获得经过验证的记录后，可以根据指定主题对视频描述进行分类：条目结构中列出了 desc 字段。模型可以按内容形式对帖子分组，例如教程、评论或用户体验。请保存原始文本、标签、提示词版本和结果，并将存疑案例交由人工审核。

数值指标应由常规代码计算，以确保重复运行时算术结果可复现。分类器适合处理文本；最终报告应将结论与具体记录及观测日期关联起来。

在无代码工作流中，也可以通过自动化工具串联相同步骤：定时触发、使用已验证的配置发起 HTTP 请求、检查响应、保存 JSON、转换已确认的字段，以及在出错时发送通知。先在 Postman 中验证接口约定，再将其移植到 Python、n8n 或 Make。

预期成果与下一步

完成配置后，团队将拥有 API 响应归档，以及针对所选话题标签建立的观测表。这些数据有助于发现新帖子、比较一段时间内可用指标的变化，并筛选素材进行深入分析。为保证结果可比，请保持采集计划、请求参数和规范化规则一致。

从一个接口路径和一份真实响应开始：使用 query 参数请求 /getHashtagFeed，保存 JSON，然后再逐步添加字段解析和定时任务。TikTok Scraper API页面展示了基础地址和接口路径概览，而接口路径规范列出了客户端实现所需的参数名称。