npm 下载榜数据接口

2026-11-11 起由 CDN 直出。本端点的规范地址是 https://cdn.dsh.so//data/npm-downloads.json,字节由 Cloudflare R2 直出。https://www.dsh.so/DATA_PATH 仍可访问,但只是一条指向同一对象的 307——新代码请直接用 CDN 地址。(浏览器提示:CDN 按桶的 CORS 规则走,只放行 www.dsh.so / dsh.so 两个来源;curl 与服务端客户端不受影响。)

一次请求返回 DSH 插件的 npm 周下载前 100 名——与首页「本周 npm 下载」榜单同一口径,按 npm 官方 last-week(滚动 7 天)窗口下载量降序排列。week 与 total 是合计:npm 官方 + npmmirror 国内镜像两路各自独立计数的下载量之和,每条另有 official / mirror 明细。

接口地址
URL说明更新
https://cdn.dsh.so/data/npm-downloads.json前 100 名排名——当前 last-week 窗口内下载量最高的 100 个插件,每个插件一条。week / total 为 npm 官方 + npmmirror 镜像的合计。随部署重建;官方数值取自最近一次每日 npm 快照,镜像数值取自最近一次镜像采集
https://cdn.dsh.so/data/npm-downloads.schema.json本接口数据格式对应的 JSON Schema。稳定

JSON 接口支持跨域读取:Access-Control-Allow-Origin: *,无需 API Key 或注册。

响应字段
字段类型语义
generatedAtstring (ISO)构建时间戳——缓存副本请一并保留
snapshotDatestring (YYYY-MM-DD) | nullweek 数值来自哪一份 npm 快照;无快照时为 null(此时 items 为空)
windowobjectdays: 7(npm 官方 last-week 滚动窗口)、start / end(YYYY-MM-DD)——end 即 snapshotDate。该窗口只描述 week 的官方一路;同一字段的镜像一路来自比官方新约 5 天的窗口(见 sources.mirror)
sourcesobjectofficial / mirror,各含 provider、api、semantics——合计数字背后的两路计数来源
scopeobject收录口径:listableOnly(仅站内列表口径)、ecosystemAppsExcluded(排除生态应用)、newlyIndexedExcludedDays: 7(窗口内新入库不上榜)
countnumber榜单条目数(≤ limit)
limitnumber100——本接口只提供前 100 名
items[]array榜单条目,按 week 降序(字段见下)
items[].ranknumber名次(1–100)
items[].idstring插件 id(与 plugins.json 的 id、详情页 slug 一致)
items[].namestring展示名
items[].packageNamestring下载量统计所用的 npm 包名
items[].weeknumber合计周下载 = npm 官方 last-week 滚动 7 天窗口 + npmmirror 镜像窗口(比官方新约 5 天)。滚动窗口跨快照日期互相重叠——不要把不同快照的 week 相加。分解见 official.week / mirror.week
items[].totalnumber | null合计累计下载 = 官方累计 + 镜像累计,两路各自由「初值 + 逐日累加」得到(官方窗口约 18 个月、镜像 2 年,合计是两路各自口径的累计之和);两路都没有初值时为 null——绝不报 0 冒充。分解见 official.total / mirror.total
items[].officialobject{ week, total }——本条目的 npm 官方(registry.npmjs.org)一路;缺数据记 null(绝不记 0)
items[].mirrorobject{ week, total }——本条目的 npmmirror(registry.npmmirror.com)镜像一路。镜像是自己的一路独立计数(不是官方数据代理,两路相加不是对同一批事件的重复计数),窗口比官方新约 5 天;镜像方没有公开计数口径声明,镜像计数口径由镜像方定义。null = 镜像 404 / 尚未采集,绝不记 0
items[].starsnumberGitHub 星数
items[].urlstring插件详情页绝对地址
licenseobject出处与引用条款——聚合自公开 npm registry,引用需注明来源

诚实原则:本接口与首页榜单共用同一派生层(src/data/trending.ts),两处永远一致。窗口内新入库的插件不上榜——新条目的下载量是「刚被发现」而非本周真实热度;生态应用(不能作为插件安装)同样排除。镜像一路同守「诚实缺席」:拿不到就是 null 而不是 0,合计值只有在两路都拿不到时才是 null。

使用方式

获取前 100 名排名(或在浏览器直接打开 https://cdn.dsh.so/data/npm-downloads.json):

curl https://cdn.dsh.so/data/npm-downloads.json

接口固定只输出前 100 名。单插件详情(验证等级、安全、安装方式)用 id 关联 /plugins-index.json 或 /plugin/@作者/插件名.json。

榜单随部署重建,数据来自 dsh.so 流水线每日采集的 npm 官方 Downloads API 快照与 npmmirror 镜像快照。字段只增不删:既有字段不会移除或改名。可免费引用,需注明来源 dsh.so;新增字段见 更新日志。

这页有帮助吗?