> 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.

# views 为 null 是不是浏览量为零？

> 在 twitter.web.fetch_search_timeline 响应中，data.timeline[].views 为 null 表示未返回浏览量，仅字符串 "0" 代表 0 浏览量；计算均值时应排除 null 与缺失项。

不是。在已保存的 `twitter.web.fetch_search_timeline` 响应中，`data.timeline[].views` 为 `null` 表示本次观察未返回浏览量；只有字符串 `"0"` 代表报告了 0 浏览量。计算平均值时应排除 `null` 和缺失的 `views` 条目，并在每个均值旁注明有多少篇帖子实际报告了浏览量。

## 先看一条帖子是否返回了浏览量

逐条检查 `data.timeline[].views`。`views` 的已发布类型为字符串或 `null`：

| `views` 的值   | 含义                | 是否计入平均值 |
| ------------ | ----------------- | ------- |
| `"0"`        | 报告了 0             | 计入      |
| `null`       | 本次观察未返回数值         | 不计入     |
| 没有 `views` 键 | 字段缺失，另记为 `absent` | 不计入     |

仅凭 `views` 字段无法判断帖子是否被删除、设为私密、刚刚发布或从未被浏览。

## 浏览量缺失会怎样影响调研报告？

以三条示例帖子为例，其 `views` 分别为 `"100"`、`"0"` 和 `null`。报告应写明「3 篇中 2 篇有浏览量，已报告总和 100，有值的 2 篇均值 100 / 2 = 50」。直接除以 3 会把 `null` 误算为 0，既拉低均值，又掩盖数据覆盖缺口。均值 50 只适用于这 2 篇报告了数值的帖子，不代表全体受众均值、独立触达人数，也不代表 X 上所有匹配帖子的估算值。

对比两组关键词时，应将每组的覆盖比例放在均值旁边。大部分帖子缺少 `views` 的结果集不能与几乎全部有 `views` 的结果集直接横向比较。每组查询词、排序方式和观察时间都要与对应原始响应文件一起保存。对比多轮快照时，按 `tweet_id` 精确匹配，仅在两轮快照都返回数字字符串时计算变化值，其余留空。

## 用一个已存搜索页生成覆盖表

使用通过[关键词搜索指南](/zh/guides/x-search-posts)保存的成功响应。`views_coverage.py` 不调用 X 或 BeatAPI，不拉取下一页，也不调用模型。请将原始请求清单放在输出目录旁以便审计查询词与排序设置。响应包含续页游标时，`views_coverage.py` 只记录 `continuation_available`，不会跟随游标翻页。

将脚本保存为 `views_coverage.py`：

```python
import csv,datetime,hashlib,json,pathlib,sys
source=pathlib.Path(sys.argv[1]);stamp=sys.argv[2];target=pathlib.Path(sys.argv[3])
dt=datetime.datetime.fromisoformat(stamp.replace("Z","+00:00"))
if dt.tzinfo is None:raise ValueError("Record the actual collection time with timezone")
raw=source.read_bytes();payload=json.loads(raw);action="twitter.web.fetch_search_timeline"
if not isinstance(payload,dict) or payload.get("status")!="succeeded" or payload.get("action")!=action or payload.get("error") is not None:raise ValueError("Use a successful search response")
rid=payload.get("request_id")
if not isinstance(rid,str) or not rid.strip():raise ValueError("Missing request ID")
data=payload.get("data")
if not isinstance(data,dict) or not isinstance(data.get("timeline"),list):raise ValueError("Missing timeline array is not an empty page")
cursor=data.get("next_cursor")
if cursor is not None and not isinstance(cursor,str):raise ValueError("Unexpected cursor type")
rows=[];seen=set();total=0;counts={"reported":0,"null":0,"absent":0}
for item in data["timeline"]:
    if not isinstance(item,dict):raise ValueError("Invalid post object")
    ident=item.get("tweet_id")
    if not isinstance(ident,str) or not ident.isascii() or not ident.isdigit() or int(ident)==0 or ident in seen:raise ValueError("Require distinct original nonzero string IDs")
    seen.add(ident)
    state="absent" if "views" not in item else ("null" if item["views"] is None else "reported")
    value=None
    if state=="reported":
        text=item["views"]
        if not isinstance(text,str) or not text.isascii() or not text.isdigit():raise ValueError("views must be its original digit string, null or absent")
        value=int(text);total+=value
    counts[state]+=1
    rows.append({"tweet_id":ident,"views_state":state,"views":"" if value is None else str(value)})
digest=hashlib.sha256(raw).hexdigest()
summary={"action":action,"request_id":rid,"collected_at":stamp,"source_sha256":digest,
         "unique_posts":len(rows),"states":counts,"reported_sum":str(total),
         "reported_mean_fraction":None if not counts["reported"] else {"numerator":str(total),"denominator":counts["reported"]},
         "coverage_fraction":{"numerator":counts["reported"],"denominator":len(rows)} if rows else None,
         "scope":"one saved search page","continuation_available":bool(cursor and cursor.strip())}
target.mkdir()
(target/"raw-response.json").write_bytes(raw)
(target/"summary.json").write_text(json.dumps(summary,ensure_ascii=False,indent=2),encoding="utf-8")
with (target/"views.csv").open("x",encoding="utf-8-sig",newline="") as f:
    writer=csv.DictWriter(f,fieldnames=["tweet_id","views_state","views"]);writer.writeheader();writer.writerows(rows)
print(str(target))
```

运行 `python3 views_coverage.py page-1.json ACTUAL_COLLECTION_TIME new-coverage-folder`。将 `ACTUAL_COLLECTION_TIME` 替换为采集该响应时记录的带时区真实时间（格式如 `2026-11-16T10:00:00Z`），不要照抄示例时间。目标目录 `new-coverage-folder` 必须尚不存在。

输出目录包含 `views.csv`、`summary.json` 以及与原响应逐字节一致的 `raw-response.json`。`summary.json` 以精确整数分子和分母存储各项比例，避免大计数因浮点舍入失真。没有任何已报告值的页面不会生成均值，成功的空页没有覆盖比例；空页与全部 `views` 为 `null` 的页面属于两种不同状态。遇到重复 ID、异常值、失败调用或缺少 `timeline` 数组时，`views_coverage.py` 会在创建输出目录前退出。若脚本拒绝意外的数值类型，请核查原始响应，不要凭猜测将其转为字符串。

`summary.json` 中的 `source_sha256` 哈希仅用于标识已保存字节，不能证明数据来源真实或手工填写的采集时间准确。导入电子表格时，请将数字形态的 `tweet_id` 和大计数按文本导入以保留精度。重复运行 `views_coverage.py` 不消耗 API 调用；刷新数据或跟随游标翻页则属于新的查询。

[搜索CSV与原请求清单](/zh/guides/x-search-posts) · [排查搜索空结果](/zh/faq/x-empty-search-results)

免费合同参考：`data:twitter.web.fetch_search_timeline`。