跳到导航

做海外市场选题,怎么用 X 国家趋势判断一个话题值不值得跟?

做海外市场选题,用 twitter.web.fetch_trending 给目标国家取一份趋势快照,例如日本填 country:"Japan"。从实际返回的话题里挑出和品牌有关的几个,再用 twitter.web.fetch_search_timeline 按话题搜索,读原帖核对事件和时间。

交付的选题简报保留发现市场、快照时间、话题原名、实际帖子和准备采用的角度,同事能逐条复查简报里的判断。

先定市场和这轮要做的内容

先明确要服务的市场、读者和产品问题,再决定看哪个国家。实际记录 country 输入,不从话题语言或作者账号推断国家。twitter.web.fetch_trending 返回指定国家的快照;不传 country 时返回美国快照,不能称为全球榜。

同一轮比较多个市场时,尽量在相近的时间取各市场的快照,并保留每份快照的实际时间。榜单内的位置不是可以跨国比较的热度分数;同一个名字在不同市场也可能指不同事件,先分别核实各市场的语境再合并。

拿到榜单,哪些话题值得继续读?

下表是常见候选情况的编辑判断方法:

榜单中的情况编辑先怎么判断下一步
与产品使用场景直接相关有可能提供实用角度读相关帖子,确认大家在讨论的具体问题。
只认得名称,不清楚发生什么背景待核,先不写结论保存原名,核实事件与可信原始出处。
娱乐或抽奖话题很靠前,但与受众任务无关可以排除,写明原因不为凑热点付费扩采。
多个市场都出现同一词可能有共同话题,也可能是歧义分市场核对各自的上下文,不直接称“全球爆发”。
名字相关但材料无法核实保留待核不让AI把缺失简介补成官方解释。

每个选中的话题先读一页搜索结果,核对含义、发布时间和与品牌的关联。需要严格日期范围时,用实际返回的时间核查。twitter.web.fetch_search_timeline 没有国家筛选,不能由趋势的来源国家推断发帖者所在地。

交给同事什么,才能决定发不发?

交一份简短的选题卡,包含:目标市场与观察时间、原始话题名、实际读到的来源、与受众的关联、拟回答的问题或角度、还需核实什么,以及“考虑/排除/待核”的人工决定。原名和事实原句与编辑归纳分开写。

本地脚本 prepare_trends.py 生成 trends.csv、selected-searches.json 和 coverage.json。脚本只整理已保存的快照、生成未执行的搜索计划,不写选题卡、不验证新闻,也不发布内容。编辑理由在另一份工作表里填写;缺失的字段保持缺失。合同没有提供热度、帖子总量或历史增长,就不要生成这些数值。

先用小范围决定是否值得继续花费

先取一个国家的快照,选定话题后再批准搜索;已有快照时直接在本地制表,不为重新制表再取一次。一个国家快照加一个话题的一页搜索是两次调用;每多一个国家、一个词或一页,都各增加一次调用,按各动作的当前价格分别计算。

搜索结果不相关时,先修改选题判断,不要自动把榜上所有词都搜一遍。简报里说明实际观察范围和未核实的部分;一份快照不代表连续监测,也不证明话题正在增长。下面第 1–6 步是取快照、读帖和生成计划的具体步骤。

1. 检查国家参数

curl -sS https://api.beatapi.io/v1/capabilities/inspect \
-H 'Content-Type: application/json' \
-d '{"reference":"data:twitter.web.fetch_trending"}'

Inspect 免费。当前参数是 country,默认值 UnitedStates;公开说明列出的其他值包括 Japan、Germany、UnitedKingdom 等。不要用别家的 region: JP。不传 country 得到的是默认的美国结果,不能解释成全球榜。

2. 获取一个国家的趋势快照

确认价格后,请求日本的趋势快照:

curl -sS https://api.beatapi.io/v1/social-data/call \
-H "Authorization: Bearer $BEATAPI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"action":"twitter.web.fetch_trending","params":{"country":"Japan"}}' \
-o x-japan-trends.json

检查执行状态。已发布的输出列表是 data.trends,每项的 name 是话题名,context 是分类或上下文。description 在已观察的样本里为 null;不要把 AI 写的解释当成返回的官方简介。

3. 先看名称,再选词

下面的命令只读取刚保存的文件,不发起新请求:

import json
with open("x-japan-trends.json", encoding="utf-8") as source:
result = json.load(source)
if result["status"] != "succeeded":
raise RuntimeError("Inspect the failed response before using trends")
for position, trend in enumerate(result["data"]["trends"], start=1):
print(position, trend.get("name", ""), trend.get("context", ""))

打印的序号只是条目在已保存响应里的位置,不是合同保证的官方 rank 字段。合同没有承诺固定 30 条、热度数值或历史曲线,也没有发布翻页参数,所以不要给这些内容造列。

4. 搜索一个真实返回的话题

先免费 Inspect 搜索能力,再根据当前价格决定是否付费搜索:

curl -sS https://api.beatapi.io/v1/capabilities/inspect \
-H 'Content-Type: application/json' \
-d '{"reference":"data:twitter.web.fetch_search_timeline"}'

将 <returned_trend_name> 换成实际返回的完整名称,JSON 中的引号等字符需要正确转义:

curl -sS https://api.beatapi.io/v1/social-data/call \
-H "Authorization: Bearer $BEATAPI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"action":"twitter.web.fetch_search_timeline","params":{"keyword":"<returned_trend_name>","search_type":"Latest"}}' \
-o x-trend-posts.json

twitter.web.fetch_search_timeline 没有 country 参数。返回的是匹配这个话题的帖子,不能宣称这些帖子全部来自日本。按每条帖子的实际正文和 lang 判断相关性;选了某个国家的趋势,不等于按作者所在地筛选。

5. 交付选题简报

保存国家输入、获取时间、原始话题名、返回的上下文、引用的帖子和你的选题判断。敏感事件或歧义词先核实;热门标签不是已确认的新闻。

一次国家趋势加一次话题搜索,共两次收费调用;比较两个国家并各搜一个词,共四次。金额按两个 action 执行前 Inspect 到的单价分别计算,不能套用别家的单价或失败计费规则。

检查日本 X 趋势能力与价格,确认后取一次快照。让我选择一个话题,再确认搜索价格并取一页相关帖子。保留原话题、时间与来源,不生成未返回的热度、官方排名或作者国籍。

来源:免费合同 data:twitter.web.fetch_trending 和 data:twitter.web.fetch_search_timeline;本文不提供当天的真实热榜。翻页与 CSV 处理见关键词搜索。

6. 交付国家趋势表与选题查询计划

做多市场选题会时,先把已保存的国家快照排成一张表,再选需要了解背景的话题。

  1. 创建 trend-inputs.json,country 记录每次请求实际发送的值,不能从话题语言反推国家。
  2. 同一批里每个国家只用一份快照。
  3. 用 response_position 选择话题;response_position 是条目在一次响应里的位置,不是官方排名。

下面的示例只选日本快照的第一项,不预设这一项的内容:

{"snapshots":[{"country":"Japan","file":"x-japan-trends.json","collected_at":"2026-11-16T10:00:00Z"}],"selected":[{"country":"Japan","response_position":1}]}

把脚本保存为 prepare_trends.py,执行 python3 prepare_trends.py trend-inputs.json trend-review。脚本输出 trends.csv、selected-searches.json 和 coverage.json;选定的话题名经 JSON 编码后直接放进搜索的 params.keyword,不用手工拼字符串。prepare_trends.py 不发请求,只生成待批准的计划。空的趋势数组会输出空表,但不能选择不存在的位置。

执行计划前,先核对搜索单价,再按计划条数批准费用。搜索结果没有国家筛选,source_country 只记录“这个话题来自哪份趋势快照”。拿到搜索结果后,复用搜索指南的离线导出器,把具体原文和你的编辑判断写进选题简报;不要把模型生成的解释冒充缺失的官方 description。

import csv
import hashlib
import json
import sys
from datetime import datetime
from pathlib import Path
manifest_file, output = map(Path, sys.argv[1:])
manifest = json.loads(manifest_file.read_text(encoding="utf-8"))
snapshots = manifest.get("snapshots")
selected = manifest.get("selected", [])
if not isinstance(snapshots, list) or not snapshots or not isinstance(selected, list):
raise SystemExit("Expected snapshots and optional selected entries")
rows, by_position, countries, requests = [], {}, set(), set()
evidence = []
for entry in snapshots:
country = entry.get("country")
if not isinstance(country, str) or not country.strip() or country != country.strip() or country in countries:
raise SystemExit("Use one snapshot per distinct country in this batch")
countries.add(country)
time = datetime.fromisoformat(entry["collected_at"].replace("Z", "+00:00"))
if time.utcoffset() is None:
raise SystemExit("Collection time requires timezone")
source = manifest_file.parent / entry["file"]
source_bytes = source.read_bytes()
digest = hashlib.sha256(source_bytes).hexdigest()
raw = json.loads(source_bytes)
if not isinstance(raw, dict) or raw.get("error") is not None or raw.get("status") != "succeeded" or raw.get("action") != "twitter.web.fetch_trending":
raise SystemExit("Expected a successful direct trend response")
request_id = raw.get("request_id")
if not isinstance(request_id, str) or not request_id.strip() or request_id in requests:
raise SystemExit("Missing or repeated request ID")
requests.add(request_id)
data = raw.get("data")
trends = data.get("trends") if isinstance(data, dict) else None
if not isinstance(trends, list):
raise SystemExit("Expected data.trends array")
evidence.append({"country": country, "collected_at": entry["collected_at"], "request_id": request_id,
"source_file": str(source.resolve()), "source_sha256": digest,
"saved_file": "raw-" + str(len(evidence) + 1) + ".json", "bytes": source_bytes})
for position, trend in enumerate(trends, 1):
if not isinstance(trend, dict):raise SystemExit("Invalid trend object")
for field in ("context", "description"):
if trend.get(field) is not None and not isinstance(trend[field], str):raise SystemExit("Unexpected trend text type")
name = trend.get("name")
if not isinstance(name, str) or not name.strip():
raise SystemExit("Missing trend name")
row = {"country_input": country, "response_position": position, "name": name,
"context": trend.get("context"), "description": trend.get("description"),
"collected_at": entry["collected_at"], "source_file": entry["file"], "request_id": request_id, "source_sha256": digest}
rows.append(row)
by_position[(country, position)] = row
plan, seen = [], set()
for choice in selected:
country, position = choice.get("country"), choice.get("response_position")
if not isinstance(position, int) or isinstance(position, bool):
raise SystemExit("Choose an integer response position")
key = (country, position)
if key not in by_position or key in seen:
raise SystemExit("Unknown or duplicated selected trend")
seen.add(key)
row = by_position[key]
plan.append({"source_country": country, "source_request_id": row["request_id"], "source_sha256": row["source_sha256"],
"action": "twitter.web.fetch_search_timeline", "params": {"keyword": row["name"], "search_type": "Latest"},
"executed": False})
output.mkdir(exist_ok=False)
for item in evidence:
(output / item["saved_file"]).write_bytes(item["bytes"])
(output / "sources.json").write_text(json.dumps([{k: v for k, v in item.items() if k != "bytes"} for item in evidence], ensure_ascii=False, indent=2), encoding="utf-8")
columns = ["country_input", "response_position", "name", "context", "description", "collected_at", "source_file", "request_id", "source_sha256"]
with (output / "trends.csv").open("x", encoding="utf-8-sig", newline="") as handle:
writer = csv.DictWriter(handle, fieldnames=columns)
writer.writeheader()
for row in rows:
writer.writerow({k: ("'" + v if isinstance(v, str) and v.lstrip().startswith(("=", "+", "-", "@")) else v) for k, v in row.items()})
(output / "selected-searches.json").write_text(json.dumps(plan, ensure_ascii=False, indent=2), encoding="utf-8")
(output / "coverage.json").write_text(json.dumps({"countries": len(countries), "returned_topics": len(rows),
"planned_search_calls": len(plan), "executed_calls": 0,
"scope": "response positions, not official ranks; searches do not filter author country"}, indent=2), encoding="utf-8")

输出还为每份快照保存一个 raw-N.json,并在 sources.json 里记录每份快照的原国家输入、时间、请求号和字节哈希。每条选中的搜索都引用所来自快照的哈希。空榜也有 sources.json 记录和保存的原文件,但不生成搜索计划条目。原输入清单也一并保存:国家和时间是记录下来的请求上下文,不是从帖子语言推断的,也没有经过密码学验证。