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
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.jsonTo get all ubuntu installs for a repository:
api/v1/repos/julio/test_repo/stats/installs/ubuntu/count.jsonOr, to get all ubuntu/precise installs for a repository:
api/v1/repos/julio/test_repo/stats/installs/ubuntu/precise/count.jsonThese 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.jsonSimilarly, the distribution and version URL’s work for this endpoint as well:
api/v1/repos/julio/test_repo/stats/installs/ubuntu/precise/series/daily.jsonFor 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.jsonDistribution and version filtering also work as expected:
api/v1/repos/julio/test_repo/stats/installs/el/5/detail.jsonReturns 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=RubyAnother example:
api/v1/repos/julio/test_repo/stats/installs/ubuntu/detail.json?master_token=default&user_agent=Ruby
Package Downloads
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.jsonapi/v1/repos/julio/test_repo/package/rpm/el/7/jake/x86_64/1.0/3.el6/stats/downloads/count.jsonThese 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.jsonapi/v1/repos/julio/test_repo/package/rpm/el/7/jake/x86_64/1.0/3.el6/stats/downloads/series/weekly.jsonFor 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.jsonapi/v1/repos/julio/test_repo/package/rpm/el/7/jake/x86_64/1.0/3.el6/stats/downloads/detail.jsonPackage 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.
