Skip to content

Developmint/npm-stats-api

Repository files navigation

Fetch stats for your NPM packages

Latest Version on Packagist Software License Build Status Quality Score Total Downloads

This package makes it easy to retrieve stats for packages hosted on npmjs.com

PS: It's heavily inspired by the packagist-api package made from Spatie

Installation

You can install the package via composer:

composer require developmint/npm-stats-api

Usage

You must pass a Guzzle client to the constructor of Developmint\NpmStats\NpmStats.

$client = new \GuzzleHttp\Client();

$npmStats = new \Developmint\NpmStats\NpmStats($client);

Get stats for a package of your choice

$npmStats->getStats('jquery');

Get stats with a period of your choice

Use a constant provided by the NpmStats class to get stats for the last day, week, month, year or in total.

$npmStats->getStats('jquery', NpmStats::LAST_DAY);

You can also pass in specific dates

$npmStats->getStats('jquery', '2017-01-01');

Or even ranges

$npmStats->getStats('jquery', '2014-02-07:2014-02-14');

The output will be already decoded from json:

array(4) {
  ["downloads"]=>
  int(198672)
  ["start"]=>
  string(10) "2017-10-10"
  ["end"]=>
  string(10) "2017-10-10"
  ["package"]=>
  string(6) "jquery"
}

Get stats with a period of your choice as range

You can also get the stats as a range, means the downloads split up per day:

$npmStats->getStats('jquery', NpmStats::LAST_WEEK, true);

And this would be the result of that call:

array(4) {
  ["start"]=>
  string(10) "2017-10-04"
  ["end"]=>
  string(10) "2017-10-10"
  ["package"]=>
  string(6) "jquery"
  ["downloads"]=>
  array(7) {
    [0]=>
    array(2) {
      ["downloads"]=>
      int(200678)
      ["day"]=>
      string(10) "2017-10-04"
    }
    [1]=>
    array(2) {
      ["downloads"]=>
      int(195593)
      ["day"]=>
      string(10) "2017-10-05"
    }
    [2]=>
    array(2) {
      ["downloads"]=>
      int(172132)
      ["day"]=>
      string(10) "2017-10-06"
    }
    [3]=>
    array(2) {
      ["downloads"]=>
      int(51068)
      ["day"]=>
      string(10) "2017-10-07"
    }
    [4]=>
    array(2) {
      ["downloads"]=>
      int(46892)
      ["day"]=>
      string(10) "2017-10-08"
    }
    [5]=>
    array(2) {
      ["downloads"]=>
      int(171920)
      ["day"]=>
      string(10) "2017-10-09"
    }
    [6]=>
    array(2) {
      ["downloads"]=>
      int(198672)
      ["day"]=>
      string(10) "2017-10-10"
    }
  }
}

Get bulk stats

Of course you can retrieve up to 128 packages as a bulk query. Simply separate them with a command and you are good to go.

$npmStats->getStats('vue,express', NpmStats::LAST_WEEK);

But beware! This only works in point mode, not in range mode.

$npmStats->getStats('vue,express', NpmStats::LAST_WEEK, true);
//Won't work

Anyway, the output will look similar to the normal point mode output:

array(2) {
  ["vue"]=>
  array(4) {
    ["downloads"]=>
    int(3980980980098089080980983)
    ["package"]=>
    string(5) "vue"
    ["start"]=>
    string(10) "2017-10-10"
    ["end"]=>
    string(10) "2017-10-10"
  }
  ["express"]=>
  array(4) {
    ["downloads"]=>
    int(818264)
    ["package"]=>
    string(7) "express"
    ["start"]=>
    string(10) "2017-10-10"
    ["end"]=>
    string(10) "2017-10-10"
  }
}

More in-depth info about the NPM stats API

You can find a detailed explanation about how the stats API of NPM works in this repository README file

Limits of the API

The official limits are:

  • Bulk queries: 128 packages at a time and at most 365 days of data
  • All other queries: limited to at most 18 months of data
  • Earliest date available: January 10, 2015

Changelog

Please see CHANGELOG for more information what has changed recently.

Testing

$ composer test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email support@developmint.de instead of using the issue tracker.

Credits

License

The MIT License (MIT). Please see License File for more information.