piwheels

JSON API

piwheels.org provides a JSON API for information about packages we host.

Package information

Package information can be found at piwheels.org/project/<package>/json, e.g. piwheels.org/project/numpy/json. This data includes information about every released version of the package, the status of any build attempts made by piwheels, which ABIs and platforms we have built files for, and information about these files, including filename, filesize, hash, build duration and any apt dependencies.

The project pages themselves (e.g. piwheels.org/project/numpy) are made up from a subset of the data in this JSON file, and additional data is available to that shown on those pages. It is also useful to be able to access the data for a package in a structured way from within a program, as well as the human readable method via the project page.

Schema of the JSON data for a project:

{
 'package': <str>,
 'summary': <str>,
 'pypi_url': <str>,
 'piwheels_url': <str>,
 'releases': {
    <str>: {
       'skip_reason': <str>,
       'prerelease': True|False,
       'released': <str YYYY-MM-DD HH:MM:SS>,
       'yanked': True|False,
       'files': {
          <str>: {
             'filesize': <int>,
             'apt_dependencies': [<str>, ...],
             'filehash': <str>,
             'platform': <str>,
             'builder_abi': <str>,
             'file_abi_tag': <str>
          }
       }
    }
 }
}

Example usage from a Python script:

import requests

url = "https://www.piwheels.org/project/numpy/json"
package = requests.get(url).json()

for version, release in package['releases'].items():
  print(version, release['released'])

import requests

url = "https://www.piwheels.org/project/numpy/json"
package = requests.get(url).json()

for version, info in package['releases'].items():
  if info['files']:
      print('{}: {} files'.format(version, len(info['files'])))
  else:
      print('{}: No files'.format(version))

Note that we intend to maintain the API structure, and to only add fields, not remove or change fields. In the unlikely event of compatibility changes in future.

Also note that packages and versions can be deleted, and can be recreated, so it's inadvisable to expect such data not to change. Similarly, piwheels builds can be deleted and rebuilt.

Download stats

Basic package download stats (total, and last 30 days) are provided separately at piwheels.org/packages.json. (We strongly recommend not opening this link in a web browser - it's very large).

Example usage from a Python script:

import requests

url = "https://www.piwheels.org/packages.json"
packages = requests.get(url).json()
packages = {
  pkg: (d_month, d_all)
  for pkg, d_month, d_all, *_ in packages
}

package = 'numpy'
d_month, d_all = packages[package]

print(package, "has had", d_month, "downloads in the last month")
print(package, "has had", d_all, "downloads in total")

Note the *_ assignment is optional here but protects against any additional fields being added in future.