Packagecloud logo

Announcing Repository Install and Package Download Statistics

TL;DR

We just launched the API and graphs for Repository Install and Package Downloads statistics!

 

Pagination and Metadata

Pagination is handled similarly to the Package and Versions API, using the Link: response header. Metadata about the returned collection, such as Start-Date, End-Date, Total, and Per-Page, is also available in the response headers.

NOTE: The default Start-Date and End-Date for all requests is a 7 day range. See the Filtering Criteria section for how to change these values.

 

Repository Installs

Repository Installs Screenshot

Whenever a repository is installed using our scripts, metadata, such as the ip address, master_token used and distribution, is stored about that install. This metadata can be summed or retrieved using the Repository Installs API.

 

Repository Installs Sum/Count Endpoint

This endpoint returns a single total for a given criteria. There are also more specific versions of this endpoint for filtering by distribution and version.

For example to get all installs for a repository:

api/v1/repos/julio/test_repo/stats/installs/count.json

To get all ubuntu installs for a repository:

api/v1/repos/julio/test_repo/stats/installs/ubuntu/count.json

Or, to get all ubuntu/precise installs for a repository:

api/v1/repos/julio/test_repo/stats/installs/ubuntu/precise/count.json

These would all return a CountValue object:

{ "value": 513 }

 

Repository Installs Series Endpoint

This endpoint returns a time series, divided by daily, weekly, monthly, or yearly intervals.

For instance, to get the weekly series for the last 7 days of installs (the default range), you would hit:

api/v1/repos/julio/test_repo/stats/installs/series/weekly.json

Similarly, the distribution and version URL’s work for this endpoint as well:

api/v1/repos/julio/test_repo/stats/installs/ubuntu/precise/series/daily.json

For series, you get a SeriesValue object, where they keys are named after the dates of the intervals, with their value being the series result of for that interval date. Like so:

{
  "20160221Z": 22,
  "20160222Z": 21,
  "20160223Z": 29,
  "20160224Z": 19,
  "20160225Z": 30,
  "20160226Z": 38,
  "20160227Z": 40
}

 

Repository Installs Detail Endpoint

This endpoint returns a detailed access log according to a given criteria. Only available to repository owners.

The URL structure is similar to the series and sum endpoints.

api/v1/repos/julio/test_repo/stats/installs/detail.json

Distribution and version filtering also work as expected:

api/v1/repos/julio/test_repo/stats/installs/el/5/detail.json

Returns a RepositoryInstalls object that looks like:

[
  {
     "installed_at": 2015-04-12T05:36:53.000Z,
     "ip_address": "12.51.22.21",
     "hostname": "localhost.localdomain",
     "user_agent": "Ruby",
     "master_token": "default",
     "distro_version": "ubuntu/precise"
  }
]

 

Repository Install Filtering Criteria

You can combine any of the filters below to further narrow down the results you want.

  • start_date: The starting date in ISO8601, default is 7 days ago.
  • end_date: The end date in ISO8601, default is the current day.
  • master_token: The master token id or value to filter by.
  • user_agent: The user agent to filter by.

For example:

api/v1/repos/julio/test_repo/stats/installs/detail.json?start_date=20160101Z&end_date=20160301&user_agent=Ruby

Another example:

api/v1/repos/julio/test_repo/stats/installs/ubuntu/detail.json?master_token=default&user_agent=Ruby

 

Package Downloads

Package Downloads Screenshot

Each time a package is downloaded, either via the web or command line, we also store metadata about that request, such as ip address, read_token, and source. This metadata can be summed or retrieved via the Package Downloads API. These endpoint URLs mirror the structure of the Package Show API.

 

Package Downloads Sum/Count Endpoint

This endpoint returns a single total for a given criteria. Some example urls:

api/v1/repos/julio/test_repo/package/gem/my-gem/1.2.0/stats/downloads/count.json
api/v1/repos/julio/test_repo/package/rpm/el/7/jake/x86_64/1.0/3.el6/stats/downloads/count.json

These return a CountValue object:

{ "value": 314 }

 

Package Downloads Series Endpoint

This endpoint returns a time series, divided by daily, weekly, monthly, or yearly intervals. Some example urls:

api/v1/repos/julio/test_repo/package/gem/my-gem/1.2.0/stats/downloads/series/daily.json
api/v1/repos/julio/test_repo/package/rpm/el/7/jake/x86_64/1.0/3.el6/stats/downloads/series/weekly.json

For series, you get a SeriesValue object, where they keys are named after the dates of the intervals, with their value being the series result of for that interval date. Like so:

{
  "20160221Z": 22,
  "20160222Z": 21,
  "20160223Z": 29,
  "20160224Z": 19,
  "20160225Z": 30,
  "20160226Z": 38,
  "20160227Z": 40
}

 

Package Downloads Detail Endpoint

This endpoint returns a detailed access log according to a given criteria. Only available to repository owners. Some example urls:

api/v1/repos/julio/test_repo/package/gem/my-gem/1.2.0/stats/downloads/detail.json
api/v1/repos/julio/test_repo/package/rpm/el/7/jake/x86_64/1.0/3.el6/stats/downloads/detail.json

Package Download Filtering Criteria

You can combine any of the filters below to further narrow down the results you want.

  • start_date: The starting date in ISO8601, default is 7 days ago.
  • end_date: The end date in ISO8601, default is the current day.
  • master_token: The master token id or value to filter by.
  • user_agent: The user agent to filter by.
  • read_token: The master token id or value to filter by.
  • source: The source of this package download, either “web” or “cli”.

For example:

api/v1/repos/julio/test_repo/package/gem/my-gem/1.2.0/stats/downloads/detail.json?start_date=20160101Z&end_date=20160301&user_agent=Ruby

 

Conclusion

Analytics and access logs for your packages and repositories can help your organization more accurately forecast and budget resources according to emerging trends within your infrastructure.

We hope you’ll enjoy the first iteration of our analytics features, stay tuned for more updates!

Check out our slack or email support@packagecloud.io if you have any questions or comments.

You might also like other posts...