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

Options

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

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"
}

| last-month | Past 30 days | | last-year | Past 365 days | | YYYY-MM-DD:YYYY-MM-DD | Custom date range |

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.

Related

• •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