适用场景在社交媒体运营、舆情监控、内容聚合等场景中常常需要获取多个平台的热门话题。全网热搜聚合 API 将微博热搜、知乎热榜、B 站日榜、百度贴吧热议合并为一次请求降低多源数据获取的维护维护复杂度。研发人员可以在后端服务中调用该接口定时拉取数据并存入本地缓存为前端提供统一的榜单接口。接口能力边界请求方式POST接口地址https://v1.apizero.cn/api/hot-search单接口 QPS3 次/秒超出后可能返回限流错误支持平台weibo、zhihu、bilibili、tieba可通过platform参数组合每平台最大返回条数50由limit控制超时设置客户端可自定义timeout服务端无固定超时但建议设为 15 秒注意该接口为聚合类内部会并发请求各平台总体响应时间取决于最慢的平台。若某个平台不可用data.platforms下对应status会标记为failed不影响其他平台数据。请求参数与鉴权鉴权头所有请求需在 Header 中携带 API Key字段名为Authorization值为Bearer YOUR_API_KEY或直接填 API Key具体以官方文档格式为准。为保证安全建议将 Key 保存在环境变量中。请求体 (JSON)参数名类型必填默认值说明platformstring否all平台筛选可写逗号分隔列表如weibo,zhihu。取值all或weibo、zhihu、bilibili、tiebalimitnumber否10每个平台返回的条数最大 50timeoutnumber否15请求超时秒数用于客户端实现示例请求体{ platform: all, limit: 10, timeout: 15 }用 curl 快速验证在项目开始前先用 curl 验证接口是否正常工作。假设你的 API Key 已经导出为环境变量API_KEY注意替换成你自己的 Key 变量名。curl -sS \ -X POST \ -H Authorization: Bearer $API_KEY \ -H Content-Type: application/json \ -d {platform: all, limit: 10, timeout: 15} \ https://v1.apizero.cn/api/hot-search参数说明-sS静默模式仅输出响应内容。-X POST指定请求方法。-H添加请求头。-d请求体 JSON 字符串。成功时返回类似以下结构已简化{ code: 0, msg: 成功, request_id: req_abc123, data: { generated_at: 2026-05-08T13:00:0008:00, requested_platforms: [weibo,zhihu,bilibili,tieba], platforms: { weibo: { name: 微博热搜, status: success, count: 10, items: [ {rank: 1, title: 热搜标题, hot: 5234567} ] }, zhihu: { name: 知乎热榜, status: success, count: 10, items: [] } }, failed_platforms: {}, limit_per_platform: 10, total_items: 40 } }返回值字段解读字段类型说明codenumber业务状态码0 为成功msgstring提示信息request_idstring本次请求唯一标识可用于排错data.generated_atstring数据生成时间ISO8601data.requested_platformsarray本次请求传入的平台列表data.platformsobject以平台 slug 为 key 的对象每个平台包含name、status、count、itemsdata.platforms.{slug}.statusstring状态success或faileddata.platforms.{slug}.itemsarray榜单条目每个条目有rank排名、title标题、hot热度值字符串data.failed_platformsobject返回失败平台的详细信息键为平台 slugdata.limit_per_platformnumber实际使用的每平台限制条数data.total_itemsnumber成功返回的总条数各平台之和常见错误与排查401 Unauthorized检查 HTTP 头中Authorization字段是否正确。确认 API Key 是否已过期或被吊销。400 Bad Request请求体 JSON 格式错误或参数类型不匹配。例如limit传了字符串而非数字。platform值包含不支持的平台名。429 Too Many Requests请求频率超过 3 QPS建议加入本地限流或退避重试。平台 status 为 failed可能是该平台自身接口超时或出错不影响其他平台数据。可通过failed_platforms查看原因。响应中包含 unexpected platform平台名拼写错误注意大小写敏感。工程化封装注意事项当从一次性调用转向生产级封装时需要考虑以下几点1. 参数校验limit应限制在 1-50 之间且为整数。platform若逗号分隔需过滤掉空字符串和非法平台名。timeout建议设置为正整数不宜超过 30 秒。2. 错误处理与重试网络超时或 5xx 错误可重试 1-2 次使用指数退避。4xx 错误通常不应重试除 429 外。针对某个平台失败的情况可在业务层决定是否降级如只展示成功平台数据。3. 超时控制客户端 HTTP 超时应设置为timeout值加上一点余量如 5 秒。建议使用连接超时connect timeout和读取超时read timeout分开设置。4. 限流与并发单 QPS 3 次/秒若需大量请求需加令牌桶或请求队列。若一次需要多个不同参数组合如不同平台分别调用不如合并为一次all请求更高效。5. 数据缓存热门榜单更新频率高但短期变化不大可设置 1-5 分钟的本地缓存避免重复调用。缓存过期策略建议使用 TTL并考虑在缓存失效时异步刷新。6. 日志与监控记录每次请求的request_id、耗时、结果状态。对failed_platforms非空的情况发出告警便于及时介入。7. 代码封装示例伪代码import requests from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry def fetch_hot_search(api_key, platformall, limit10, timeout15): url https://v1.apizero.cn/api/hot-search headers { Authorization: fBearer {api_key}, Content-Type: application/json } payload { platform: platform, limit: limit, timeout: timeout } # 设置重试策略 session requests.Session() retries Retry(total2, backoff_factor1, status_forcelist[500, 502, 503, 504]) session.mount(http://, HTTPAdapter(max_retriesretries)) session.mount(https://, HTTPAdapter(max_retriesretries)) try: resp session.post(url, jsonpayload, headersheaders, timeouttimeout5) resp.raise_for_status() data resp.json() if data.get(code) ! 0: raise Exception(fAPI error: {data.get(msg, unknown)}) return data[data] except Exception as e: # 记录日志 print(fRequest failed: {e}) raise参考文档全网热搜聚合 API 文档原始 Markdown 文档