stats api

David E. Wheeler edited this page Mar 23, 2017 · 7 revisions

Statistics API

  • Name: stats
  • Returns: application/json
  • URI Template Variables: {stats}
  • Availability: Mirror Server, API Server

Returns JSON containing PGXN statistics. There are a number of different statistics available, specified via the {stats} URI Template variable. The available stats are:

Each is discussed in detail below. The data served by the API Server is identical to that served by the Mirror API.

dist

The structure returned for the dist statistics is contained in a single JSON object with the following keys:

Key Type Description
count Number A count of all distributions on the network.
releases Number A count of all releases of all distributions on the network.
recent Array A list of the 56 most recent releases on the network.

recent

The values stored in the recent array are Objects describing distribution releases. They are listed in chronological order and contain the following keys:

Key Type Description
dist String The name of the distribution.
version SemVer The semantic version of this release of the distribution.
abstract String A brief description of the distribution.
date Date The date the release was uploaded to PGXN.
user String The nickname of the user who uploaded this release of the distribution.
user_name String The full name of the user who uploaded this release of the distribution.

extension

The structure returned for the extension statistics is contained in a single JSON object with the following keys:

Key Type Description
count Number A count of all extensions on the network.
recent Array A list of the 56 most recent extension releases on the network.

recent

The values stored in the recent array are Objects describing distribution releases. They are listed in chronological order and contain the following keys:

Key Type Description
extension String The name of the extension.
ext_version SemVer The semantic version of the extension provided by the distribution.
dist String The name of the distribution providing the extension.
version SemVer The semantic version of this release of the distribution.
abstract String A brief description of the extension.
date Date The date the release was uploaded to PGXN.
user String The nickname of the user who uploaded this release of the distribution.
user_name String The full name of the user who uploaded this release of the distribution.

tag

The structure returned for the tag statistics is contained in a single JSON object with the following keys:

Key Type Description
count Number A count of all extensions on the network.
popular Array A list of the 56 most-used tags.

popular

The values stored in the popular array are Objects describing the tags most commonly associated with distributions, listed in order with the most-used tag at the top. They contain the following keys:

Key Type Description
tag String The name of the extension.
dists Number The number of distributions with which the tag is associated.

user

The structure returned for the user statistics is contained in a single JSON object with the following keys:

Key Type Description
count Number A count of all users registered with the network.
prolific Array A list of the users with the most distributions.

prolific

The values stored in the prolific array are Objects describing the users who have released the most distributions on the network. They are listed in order with the user with the most releases at the top, and contain the following keys:

Key Type Description
nickname String The nickname of the user.
name String The full name of the user.
dists Number The number of distributions released by the user.
releases Number The number of distribution releases the user has made.

summary

This file simply returns a list of counts of objects on the network. It contains a single JSON object with the following keys:

Key Type Description
dists Number A count of all distributions on the network.
releases Number A count of all distribution releases on the network.
extensions Number A count of all extensions on the network.
users Number A count of all users registered with the network.
tags Number A count of all tags used by distributions on the network.
mirrors Number A count of all registered network mirrors.

Perl Example

Assuming you have retrieved the JSON document from the index API and stored the data in the $table hash, you can fetch the dist stats JSON like so:

use URI::Template;
use HTTP::Tiny;
use JSON;
my $tmpl = URI::Template->new($table->{stats});
my $uri = $tmpl->process({ stats => 'dists' });

my $req  = HTTP::Tiny->new;
my $res  = $req->get('https://master.pgxn.org' . $uri);
my $dist = decode_json $res->{content};