> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.beatapi.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server.

# 做海外市场选题，怎么用 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. 检查国家参数

```bash
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. 获取一个国家的趋势快照

确认价格后，请求日本的趋势快照：

```bash
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. 先看名称，再选词

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

```python
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 搜索能力，再根据当前价格决定是否付费搜索：

```bash
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 中的引号等字符需要正确转义：

```bash
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 处理见[关键词搜索](/zh/guides/x-search-posts)。

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

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

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

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

```json
{"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。

```python
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` 记录和保存的原文件，但不生成搜索计划条目。原输入清单也一并保存：国家和时间是记录下来的请求上下文，不是从帖子语言推断的，也没有经过密码学验证。