npm热榜数据接口
2026-11-11 起由 CDN 直出。本端点的规范地址是 https://cdn.dsh.so//data/npm-popular.json,字节由 Cloudflare R2 直出。https://www.dsh.so/DATA_PATH 仍可访问,但只是一条指向同一对象的 307——新代码请直接用 CDN 地址。(浏览器提示:CDN 按桶的 CORS 规则走,只放行 www.dsh.so / dsh.so 两个来源;curl 与服务端客户端不受影响。)
一次请求返回 DSH 插件的 npm 累计下载前 100 名——全期热门口径,与本周下载榜接口互为姊妹篇。total 与 week 是合计:npm 官方 + npmmirror 国内镜像两路各自独立计数的下载量之和,每条另有 official / mirror 明细。
| URL | 说明 | 更新 |
|---|---|---|
https://cdn.dsh.so/data/npm-popular.json | npm 累计下载前 100 名,每个插件一条,按 total(npm 官方 + npmmirror 镜像合计)降序。 | 随部署重建;官方累计来自官方累计状态,镜像累计来自镜像累计状态 |
https://cdn.dsh.so/data/npm-popular.schema.json | 本接口数据格式对应的 JSON Schema。 | 稳定 |
JSON 接口支持跨域读取:Access-Control-Allow-Origin: *,无需 API Key 或注册。
| 字段 | 类型 | 语义 |
|---|---|---|
generatedAt | string (ISO) | 构建时间戳——缓存副本请一并保留 |
totalsAsOf | string (YYYY-MM-DD) | null | 上榜条目里最新的累计口径截止日;榜单为空时为 null |
sources | object | official / mirror,各含 provider、api、semantics——合计数字背后的两路计数来源 |
scope | object | 收录口径:listableOnly(仅站内列表口径)、ecosystemAppsExcluded(排除生态应用)、packagesWithBaselineOnly(只含采过累计初值的包) |
limit | number | 100——本接口只提供前 100 名 |
count | number | 榜单条目数(≤ limit) |
items[] | array | 榜单条目,按 total 降序(字段见下) |
items[].rank | number | 名次(1–100) |
items[].id | string | 插件 id(与 plugins.json 的 id、详情页 slug 一致) |
items[].name | string | 展示名 |
items[].packageName | string | 下载量统计所用的 npm 包名 |
items[].total | number | 合计累计下载 = 官方累计 + 镜像累计,两路各自由「初值 + 逐日累加」得到(官方窗口约 18 个月、镜像 2 年,合计是两路各自口径的累计之和);绝不用零散几天的和冒充。分解见 official.total / mirror.total |
items[].totalAsOf | string (YYYY-MM-DD) | null | 该合计累计值的口径截止日(官方初值日,或已累加到的最后一天;累计只来自镜像的条目取镜像口径日) |
items[].week | number | null | 合计本周下载,作全期累计的对照 = npm 官方 last-week 滚动窗口 + npmmirror 镜像窗口(比官方新约 5 天);两路都无覆盖时为 null |
items[].official | object | { week, total }——本条目的 npm 官方(registry.npmjs.org)一路;缺数据记 null(绝不记 0),官方 total 可以为 null 而合计 total 不为空(镜像一路有初值) |
items[].mirror | object | { week, total }——本条目的 npmmirror(registry.npmmirror.com)镜像一路。镜像是自己的一路独立计数(不是官方数据代理,两路相加不是对同一批事件的重复计数),窗口比官方新约 5 天;镜像累计只在有镜像初值时才累加(绝不把零散几天当成累计);镜像方没有公开计数口径声明,镜像计数口径由镜像方定义。null = 镜像 404 / 尚未采集,绝不记 0 |
items[].stars | number | GitHub 星数 |
items[].url | string | 插件详情页绝对地址 |
license | object | 出处与引用条款——聚合自公开 npm registry,引用需注明来源 |
覆盖面诚实原则:只有采过累计初值的包(官方或镜像任一路)才会出现在本接口——两路初值都没有的包是缺席,绝不报 0 冒充;下一轮累计采集覆盖到后会自动上榜。热门榜是全期口径,不做「窗口内新入库」排除——新收录条目累计天然小,排不上去。镜像一路同守此原则:拿不到记 null 而非 0,且只有存在镜像初值时才展示镜像累计。
获取下载热门前 100 名(或在浏览器直接打开 https://cdn.dsh.so/data/npm-popular.json):
本周动量口径的姊妹接口是 /data/npm-downloads.json。单插件详情(验证等级、安全、安装方式)用 id 关联 /plugins-index.json 或 /plugin/@作者/插件名.json。
榜单随部署重建,数据来自 dsh.so 流水线每日采集的 npm 官方 Downloads API 快照、npmmirror 镜像快照与两路累计累加。字段只增不删:既有字段不会移除或改名。可免费引用,需注明来源 dsh.so;新增字段见 更新日志。