首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >数据鱼API接口详解:全网热搜榜聚合

数据鱼API接口详解:全网热搜榜聚合

原创
作者头像
用户12862874
发布于 2026-11-20 21:58:30
发布于 2026-11-20 21:58:30
120
举报

接口简介

「全网热搜榜聚合」是数据鱼API平台提供的热点榜单聚合接口,Base 路径 /api/hotlist,共 7 个端点。它将微博热搜、百度热搜、抖音热点、B站热门、头条热榜、知乎热榜六个平台的榜单统一抓取、归一化为同一套字段结构(排名、标题、链接、热度值),调用方无需分别对接各平台、也无需处理各家的反爬与页面改版,只需一次请求即可拿到可直接展示或入库的榜单数据。

接口在服务端完成抓取与缓存,客户端零反爬负担。每个数据源独立缓存 10 分钟:GET 请求在缓存过期时自动实时刷新一次,刷新失败则回退旧缓存并把 stale 置为 true;聚合与搜索端点采用惰性模式,旧数据仍可用时不强制刷新,从而在保证可用性的同时避免对上游的过度请求。单源失败不影响其他源,因此多源聚合的结果可能是部分源缺失而非整体失败。

能力上分为四组:榜单读取(单源 list、多源 all、关键词 search)、元信息(sources 数据源清单、stats 缓存状态)、运维(ping 健康检查、refresh 手动刷新)。数据源固定为 weibo、baidu、douyin、bilibili、toutiao、zhihu 六个 code,未收录其他平台。

所有端点返回 JSON。除跨域预检外,所有端点均需鉴权;数据源可达性与部署服务器的网络环境有关,同一份代码在不同网络下可用源数量可能不同。

端点总览

方法

路径

说明

鉴权

GET

/api/hotlist/ping

健康检查,返回版本与服务器时间

是

GET

/api/hotlist/stats

各源缓存状态总览:状态、条数、更新时间、是否过期数据

是

GET

/api/hotlist/sources

数据源清单,含 code、名称、场景、url_param

是

GET

/api/hotlist/list

单源完整榜单,支持 limit 与 brief

是

GET

/api/hotlist/all

多源聚合,按源分组返回,limit 为每源条数

是

GET

/api/hotlist/search

跨源关键词搜索,可限定单源,最多 100 条

是

POST

/api/hotlist/refresh

手动刷新,可指定单源或全部,兼容 GET 调用

是

通用约定

  • 鉴权:通过 X-API-Key 请求头或 ?api_key= 查询参数传递全站统一 Key;缺失返回 4011,无效返回 4013。跨域预检 OPTIONS 请求不校验。
  • 响应结构:{"code": 0, "msg": "success", "data": {...}},code 非 0 时 msg 给出原因。
  • 参数错误:缺少参数返回 4001;source 未知、limit 越界、keyword 过长等取值问题返回 4002。
  • 上游异常:数据源抓取失败且无缓存可用时返回 5031;服务内部异常返回 5000。

以上为数据鱼API平台的统一响应约定,各接口错误码含义一致。

核心端点详解

单源榜单 list

取回指定平台的完整榜单。source 必填,limit 控制条数,brief 用于只要排名的轻量场景。

参数

类型

必填

默认

说明

source

string

是

—

数据源 code:weibo、baidu、douyin、bilibili、toutiao、zhihu

limit

int

否

50

返回条数,最大 100,越界返回 4002

brief

string

否

—

传 1 时列表项仅含 rank、title、hot 三个字段

返回的 data 含 source、name、updated_at(抓取时间)、stale(是否回退旧数据)、total、refreshed(本次是否执行实时刷新)与 list。列表项字段见下表。

字段

类型

说明

rank

int

排名,从 1 起

title

string

标题

url

string

原文链接

hot

int / null

热度值,平台口径,可能为空

extra

object

源特色字段,如 desc 摘要、tag 标签、author 作者

代码语言:javascript
复制
GET /api/hotlist/list?source=baidu&limit=20

多源聚合 all

一次请求取回多个平台的榜单,按源分组,适合首页热榜模块或数据大屏。

参数

类型

必填

默认

说明

limit

int

否

文档未标明

每个源返回的条数上限

返回 data.sources(本次有数据的源数量)、data.limit_per_source 与 data.boards 数组;每个 board 的结构与 list 的 data 一致,含 source、name、updated_at、stale、list。该端点走惰性模式:旧缓存仍可用时不强制刷新,因此 refreshed 通常为 false。

代码语言:javascript
复制
GET /api/hotlist/all?limit=10

跨源关键词搜索 search

在已抓取的榜单中按关键词做跨源检索,用于确认某个话题是否正在各平台发酵。

参数

类型

必填

默认

说明

keyword

string

是

—

搜索关键词,最大 32 字符,超长返回 4002

source

string

否

全部源

限定单源检索

返回 data.keyword、data.total 与 data.list;列表项在榜单字段之外增加 source、source_name 与 updated_at,便于在混合结果中标注来源。单次最多返回 100 条。搜索同样走惰性模式,结果基于各源当前缓存。

代码语言:javascript
复制
GET /api/hotlist/search?keyword=进博&source=douyin

数据与限制

  • 数据源:6 个固定 code,分别为 weibo、baidu、douyin、bilibili、toutiao、zhihu;未知 code 返回 4002。
  • 缓存:每源独立缓存 10 分钟;list 在过期时自动刷新一次,失败回退旧缓存并标记 stale。
  • 刷新模式:all 与 search 为惰性模式,旧数据可用时不强制刷新。
  • 条数:limit 默认 50、最大 100;search 结果最多 100 条;keyword 最大 32 字符。
  • 手动刷新:POST /api/hotlist/refresh 可指定 source,缺省刷新全部;同时兼容 GET,便于 crontab 定时触发。返回 refreshed_at、ok、failed 与逐源 results,单源失败体现为 results 中的 failed 状态,整体仍返回 code 0。
  • 降级:某源抓取失败且无任何缓存时,单源请求返回 5031;聚合请求中该源不出现,其余源照常返回。
  • stats 可读取各源状态与条数,status 为 ok 表示有数据,empty 表示当前无可用数据。

典型使用场景

  • 内容与运营团队在选题会上拉取多源榜单,对比同一事件在不同平台的排名差异。
  • 品牌舆情监控按关键词定时检索六个平台,命中后进入人工核验流程。
  • 数据大屏或资讯聚合页以后台定时刷新加前端读缓存的方式展示热榜,避免每次访问都触发上游抓取。
  • 榜单长期归档做趋势分析时,按固定间隔调用 list 落库,用 updated_at 与 stale 判断数据质量。

注意事项

  • hot 的数值口径由各平台定义,不同源之间不可直接比较;部分源或条目返回 null,排序与展示需自行处理空值。
  • stale=true 表示这是刷新失败后回退的旧缓存,仍可展示,但应在界面上标注数据延迟;refreshed 只反映本次请求是否触发实时刷新,不代表数据新鲜度。
  • brief=1 仅保留 rank、title、hot,若前端需要跳转链接,不要使用该模式。
  • all 的 limit 缺省值在文档中未给出,依赖默认行为时应显式传参,避免不同版本表现不一致。
  • url 指向对应平台的原始页面,其内容与可用性由上游控制;本接口只做聚合,不对榜单内容与真实性做审核。
  • 单源失败在聚合与刷新端点中不会抛错,接入方需读取 stats 或 refresh 的 results 判断哪些源当前不可用。以上行为以数据鱼API当前线上实现为准。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 接口简介
  • 端点总览
  • 通用约定
  • 核心端点详解
    • 单源榜单 list
    • 多源聚合 all
    • 跨源关键词搜索 search
  • 数据与限制
  • 典型使用场景
  • 注意事项
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档