Get npm Download Statistics

Retrieve download statistics for an npm package over a specified time period.

Usage

npx tsx scripts/downloads.ts <package-name> [options]

Arguments

Argument	Required	Description
`package-name`	Yes	The exact package name (case-sensitive)

Options

Option	Description
`--period=PERIOD`	Time period: last-week, last-month, last-year (default: last-month)
`--no-cache`	Bypass cache and fetch fresh data from API

Output

Downloads for react (last-month)
--------------------------------
Period: 2023-10-01 to 2023-10-31 (31 days)
Total downloads: 15,234,567
Average per day: 491,438
Peak day: 2023-10-15 (678,234 downloads)

Script Execution (Preferred)

npx tsx scripts/downloads.ts <package-name> [options]

Options:

--period=PERIOD - Time period: last-week, last-month, last-year (default: last-month)
--no-cache - Bypass cache and fetch fresh data from API

Run from the npm-registry plugin directory: ~/.claude/plugins/cache/npm-registry/

Downloads API

GET https://api.npmjs.org/downloads/range/{period}:{package}

Parameters

Parameter	Required	Description
`period`	Yes	Time period: `last-week`, `last-month`, `last-year`, or date range (`YYYY-MM-DD:YYYY-MM-DD`)
`package`	Yes	The exact package name (case-sensitive)

Examples

Last week:

https://api.npmjs.org/downloads/range/last-week:react

Last month:

https://api.npmjs.org/downloads/range/last-month:react

Last year:

https://api.npmjs.org/downloads/range/last-year:react

Custom date range:

https://api.npmjs.org/downloads/range/2023-01-01:2023-12-31:react

Response Format

{
  "downloads": [
    {
      "downloads": 1234567,
      "day": "2023-10-01"
    }
  ],
  "start": "2023-10-01",
  "end": "2023-10-31",
  "package": "react"
}

Custom date ranges must be in ISO 8601 format (YYYY-MM-DD).

Download Trends

The data can show:

Weekly patterns - Higher weekday downloads for development tools
Release spikes - Sudden increases after major version releases
Seasonal trends - Patterns based on project cycles
Long-term growth - Overall adoption trends

Caching

Download statistics are cached for 24 hours. Historical download data doesn't change, so the cache provides the same data with better performance.

Use the --no-cache flag to bypass the cache.

Use npm-info to get package metadata alongside download stats
Use npm-search to discover packages with high download counts
Use NPMS.io for quality scores alongside download metrics

Error Handling

Package not found: Download stats are only available for published packages. Use npm-exists to verify the package exists first.

Invalid period: Ensure the period format is correct. Date ranges must use colons to separate dates from the package name.

No data: Very new packages may not have download statistics yet. Statistics are typically available within 24-48 hours of first publish.

Data Limitations

Delay: Download counts are typically 24-48 hours behind
Granularity: Data is available per day, not per hour
Scope: Counts include all download sources (npm install, CDN, mirrors)
Accuracy: Numbers are approximate and may include failed downloads

npm-downloads

Installation

Also in this package

Agent compatibility

Skill metadata

Package contents

History

SKILL.md