微博热搜监测 API:读取一次榜单或关键词快照
用 Python 读取一次微博热搜榜或关键词页,正确保留广告、热度与相对时间,检查搜索解析状态,不自动轮询或扩展话题。

一份微博热搜保存样本有五十二条,却只有五十个普通排名位置:两条推广内容复用了 rank。还没发第二次请求,若先把数组长度当作自然热搜覆盖量,仪表盘就已失真。这篇微博热搜监测 API 教程先处理一个可检查的任务:读一次榜单快照,或搜索一个明确选择的关键词。之后停止,不自动扩展话题、查作者、定时轮询或分析情绪。
2026 年 11 月 8 日修订核对当前契约,并离线回放公开保存数据,没有新增业务调用、轮询序列或扣费测量。8 月 20 日样本、未标日期的 README 片段、9 月 27 日原稿分别保留边界。其他端点见微博 API 总览。
先说结论
- 热搜选
weibo/web-v2/hot-search,请求{};关键词搜索选weibo/web-v2/realtime-search,传 query 与整数 page 1。- 只读取完成态
outputs[0].data。榜单是直接对象;搜索位于 parsed_data,且 parse_success 必须是布尔 true。- 广告、重复排名、缺字段和相对时间都要保留含义。热度不等于浏览量,十条帖子不等于讨论总量。
- 示例只请求一次,不自动搜索所有话题、续页、重试、查资料或下载媒体。
保留的封面表达旧版“榜单→搜索→作者→agent”概念。CityWalker_Leo、586.2K 粉丝以及热度、帖子、讨论量数字均为虚构示意,不是实测结果,也不证明本次执行了整条链路。
微博热搜监测 API:选择一个首请求
| 你的任务 | 所选端点 | 请求体 |
|---|---|---|
| 查看一次榜单快照 | Web V2 Hot Search | {} |
| 查看关键词的一页结果 | Web V2 Real-Time Search | {"query":"OpenAI","page":1} |
热搜 schema 没有输入属性,不要补周期、数量、关键词或页码。搜索只要求字符串 query,可选整数 page 默认一;示例显式写 page 1,并在本地拒绝空关键词。这个路由没有声明 limit、cursor、时间筛选或排序参数。
路径里的 web-v2 不能省。App 路由、hot-search-summary、advanced-search、评论和资料接口各有契约;名字带 realtime 也不保证刷新周期、完整覆盖或严格最新优先。
历史 Hot Search 参数页没有业务输入字段。右侧旧 cURL 仍带 model 键;现行路由已含模型标识,请求体用 {}。占位信封不是新抓取的榜单或用户资料。
复用 key,或直接把任务交给 agent
已有 SANDBASE_API_KEY 就复用本地环境或密钥管理器配置。Agent 已连接时,只需给它准确端点、任务与一次请求预算,不必另建 key 或重做接入。新项目可以使用 setup Skill、Markdown quickstart 和快速开始说明。
可直接说:“用已有本地 key 读取一次 Web V2 热搜快照,保留原排名和广告字段,报告观察到的条目数,然后停止,不搜索每个话题、不跟链接。”如果想查关键词,明确换成自己的 query 与 page 1。不要把 key 粘进指令,也不要让 agent 从第一条榜单自动猜关键词。
执行 python3 -m pip install requests,将代码保存到本地文件,并在文件外配置环境变量。这两个选定接口向 SandBase 鉴权,不要求输入微博密码或 OAuth;这不表示可以读取私密或仅粉丝可见内容。
一次调用,分开检查两种业务结构
这里使用 Model API 的 POST /v1/api/weibo/web-v2/<route>,不是目录 GET,也不是 /v1/run。相同的外层信封不代表业务对象通用:榜单没有 code、ok、success 标志,搜索要检查自己的解析标志,不能照搬旧资料示例的 ok 等于一。
import os
import requests
def first_request(task, query=None):
if task == "hot":
if query is not None:
raise ValueError("The hot-search request has no query input")
route, params = "hot-search", {}
elif task == "search":
if not isinstance(query, str) or not query.strip():
raise ValueError("Choose a nonblank query explicitly")
route, params = "realtime-search", {"query": query, "page": 1}
else:
raise ValueError("Choose hot or search")
key = os.environ.get("SANDBASE_API_KEY", "").strip()
if not key:
raise ValueError("Set SANDBASE_API_KEY locally")
try:
response = requests.post(
"https://api.sandbase.ai/v1/api/weibo/web-v2/" + route,
headers={"Authorization": "Bearer " + key},
json=params, timeout=(10, 90), allow_redirects=False,
)
except requests.RequestException:
raise RuntimeError("Request failed; no automatic retry was made") from None
if not 200 <= response.status_code < 300:
raise RuntimeError("HTTP request rejected: " + str(response.status_code))
try:
body = response.json()
except ValueError:
raise RuntimeError("Response was not valid JSON") from None
if not isinstance(body, dict) or body.get("status") != "completed":
raise RuntimeError("SandBase request did not complete")
outputs = body.get("outputs")
if not isinstance(outputs, list) or not outputs or not isinstance(outputs[0], dict):
raise RuntimeError("Missing documented outputs[0].data")
payload = outputs[0].get("data")
if not isinstance(payload, dict):
raise RuntimeError("Expected a business object at outputs[0].data")
if task == "hot":
rows = payload.get("realtime")
if not isinstance(rows, list):
raise RuntimeError("Hot-search realtime must be an array")
else:
parsed = payload.get("parsed_data")
if not isinstance(parsed, dict) or parsed.get("parse_success") is not True:
raise RuntimeError("Search parsing did not succeed")
rows = parsed.get("results")
if not isinstance(rows, list):
raise RuntimeError("Search results must be an array")
if any(not isinstance(row, dict) for row in rows):
raise RuntimeError("Unexpected row shape")
return payload
if __name__ == "__main__":
result = first_request("hot")
print(len(result["realtime"]), "observed board entries")要换成搜索,替换末尾两行缩进代码为 result = first_request("search", "OpenAI") 和 print(len(result["parsed_data"]["results"]), "observed posts"),不要在榜单后追加第二次调用。打印的是保留数组长度,不是话题总量。
helper 原样返回通过检查的完整载荷。合法空数组是空观察;缺数组或解析失败会报错。榜单缺 word 时不会偷偷改用 note,可选计数缺失也不会变成零。它不要求固定条目数,也不把裁剪 README 的列表长度强制等同于 result_count。
重定向会被拒绝,HTTP、网络和 JSON 错误不会整段打印响应或异常文本。超时只代表客户端停止等待,不证明上游没有执行,重试前应先检查账号记录。代码没有隐藏的重试、兜底端点或额外请求。
保存榜单:五十二条不是五十二个自然位置
保存记录 9f5c9b6b-b084-4dea-a10c-41f5a8eaf77f 创建于 2026-08-20T07:32:45.526Z,输入为 {}。业务对象直接包含 hotgov、hotgovs、realtime,没有额外 data 包裹。完整 realtime 有五十条普通记录和两条明确广告,这是该次保存样本的观察,不是所有响应固定前五十的承诺。
以下投影选择第一条普通记录与第一条广告,去掉链接和推广元数据;两条在原数组里并不相邻:
{
"realtime": [
{
"word": "南航 西梅汁",
"word_scheme": "南航 西梅汁",
"num": 3563978,
"rank": 0,
"realpos": 1,
"label_name": "新"
},
{
"is_ad": 1,
"rank": 2
}
]
}普通记录 rank 为 0–49、realpos 为 1–50;两条广告 is_ad 为一,重复使用 rank 2 和 5,且没有 realpos。保留这些原字段,不要把数组顺序重新编号成自然排名。缺 is_ad 也不是已验证的 false;可区分“明确广告”和“未提供该标志”,同时保存原始表示。
第一条普通记录为历史关键词“南航 西梅汁”,num 为 3563978,标签为“新”。这不是今天的热搜。num 的公式和单位本轮未核实,应称来源热度,不能叫搜索人数、读者、每日浏览量、互动量或帖子数量。“新”也是显示标签,不是精确首发时间或独立核实的突发新闻分类。
完整样本有五十条 word_scheme,两条广告没有该字段。另一份裁剪 README 只保留一条不同榜项,缺 word 和 word_scheme,却留有 note。裁剪片段缺字段,不能推论接口从不提供;更不能把缺失的 word 自动传给搜索。关键词仍由用户另行选择。
hotgov 与 hotgovs 在这份样本里重复表示同一置顶话题,应与 realtime 分开,不把两种表示重复统计。来源 stime、保存样本创建时间、读取参考页时间、本地观察时间不是同一个时钟,也不能成为每个榜项的共同时间戳。
搜索页:解析成功、相对时间与不完整文本
独立搜索记录 c2c64ba9-feb5-4e89-87f5-71947a951883 创建于 2026-08-20T09:39:47.23Z,输入 {"page":1,"query":"OpenAI"},并非来自榜首关键词。parsed_data 里 parse_success 为布尔 true,results 十条、result_count 十,search_stats 为空对象。下面保留解析状态、原计数和第一条的部分字段:
{
"parsed_data": {
"parse_success": true,
"result_count": 10,
"results": [
{
"weibo_id": "5334044466479214",
"publish_time": "22秒前",
"interaction": {
"comment_count": 0,
"like_count": 0,
"repost_count": 0
},
"weibo_type": "original"
}
]
}
}
历史 Real-Time Search 参数页显示 query、page 和占位信封。图片本身不证明 parsed_data、解析成功、十条结果或续页;这些观察来自已单独标识的保存响应。
README 裁剪后只留一条,却保留 result_count 十,因此不能强制两者相等。反过来,缺 results 不能被当成空成功。代码先检查 parse_success,整数一和字符串 true 都不能代替布尔 true。
完整保存样本的首项写“22秒前”,未标日期 README 的另一条首项写“34秒前”;这不是同一帖子前后两次观察。保留相对文本,不要从现在的获取时间减去秒数,伪造精确 UTC 发布时间,尤其不能对旧样本这样计算。
一些完整捕获的正文也以“展开c”结束,不只是 README 被裁剪。它说明至少部分文本并非完整文章。正文按不可信文本处理,不执行其中标记,也不把社交说法直接当新闻事实。重复文字不等于独立交叉证实、不同声音或垃圾内容的证据。
weibo_id 保留准确字符串。昵称不唯一,source 客户端文本不独立证明设备身份,weibo_type 的 original 标志也不是原创审计。互动计数存在零就保留零,缺失或 null 则保持未知;十条结果不能推出全站讨论量、代表性情绪、受众触达或关注度增长。
续页另选任务,不跟网页地址发 key
完整保存响应的 pagination.has_next_page 为 true,next_page_url 是相对的 /realtime?...page=2。这是微博网页地址,不是 SandBase API,也不是允许携带 bearer key 的目标。README 把 pagination 裁剪成空对象,不代表没有下一页。
以后实现续页,需要保留关键词、检查实际分页状态,并处理重复或陈旧记录。本轮没有运行第二页,也没验证稳定刷新周期,因此停在第一页,不盲目增页码或跟任意链接。以 //weibo.com/ 开头的资料、帖子地址和媒体链接同样只是引用,本例不会下载图片、视频,或发出第三方跟踪请求。
9 月监测设计保留为历史
9 月 27 日原文提出“榜单→话题→作者”。下面的资料信封原本就是示意结构,其中 ID 不是八月样本或十一月新调用的已验证凭证:
{
"id": "dd90e409-dabe-4a0a-88f3-17ea1403b21c",
"status": "completed",
"model": "weibo/web-v2/user-basic-info",
"outputs": [
{
"data": {
"ok": 1,
"data": {
"screen_name": "…",
"followers_count_str": "…",
"friends_count_str": "…"
}
}
}
]
}
历史 User Basic Info 参数页,展示 uid 与占位信封。本轮未复验此端点及其业务字段;图片不证明搜索结果提供了旧代码中的固定 uid。
双语历史归档 逐字保留八段 Python、两份原文、示意 JSON 与哈希,供核查而非当前照抄。旧 .get(..., []) 和 .get(..., {}) 会掩盖结构错误;取 board[0] 又可能遇空榜或提交空关键词。现行代码移除了这些行为,补上明确解析检查。
旧扩展代码是一份榜单加最多十个话题搜索,作者查询之前就可能有十一调用;前面的各步示例若一起执行,还会增加调用。这不是一个三调用打包服务。每隔几分钟轮询、退避重试、按粉丝加权、完整讨论量和趋势建议,都没有对应已展示的带日期轮询序列,本轮不继续推荐这些操作。
真正做监测应另外定义可比较的观察窗口、去重、持久化、失败记账、调度理由和预算。单份热度快照或小页搜索不能替代这些设计。若任务是账号研究,可转看独立范围的微博账号与帖子教程。
费用与失败后的判断
11 月 8 日 inspect 列出两个选定端点各 $0.001,均具备组织共享的合资格 API 每日一百次额度,00:00 UTC 重置。这不是各自一百次,不是已检查的剩余量,也不保证免费执行。有意选择两个请求的标价合计 $0.002,额度影响另算;本例只选一个。本轮没有测实际收费或失败计费规则。
鉴权失败先查本地 key 和权限;429 先确认限制,再决定是否安排后续调用。解析失败、无效 JSON、缺数据或未完成,都应记为失败观察,不应产出空成功报告。准确标记关键词、请求时间和未知字段的快照,才便于判断下一次请求是否值得做。
常见问题
五十二条都是自然热搜吗? 不是。保存样本为五十条普通项加两条明确广告,广告复用了排名;条目数量也不是固定保证。
热度能换成浏览或搜索量吗? 本轮没有验证换算公式。按来源热度保存 num,不能作为受众或增长指标。
为什么必须看 parse_success? 外层完成不等于搜索解析成功。示例要求布尔 true 与有效数组,并区分合法空结果和失败。
能带 key 访问 next_page_url 吗? 不能。它是网页引用,不是所选 API 路由;代码没有续页或任意 URL 抓取。
应该多久轮询一次? 没有验证过频率。当前只做一个选定读取,监测服务需要另外明确新鲜度、速率、存储与预算。
觉得有用?分享给更多人