mirrors api

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

Mirrors API

  • Name: mirrors
  • Returns: application/json
  • URI Template Variables: None
  • Availability: Mirror Server, API Server

Returns JSON describing all registered network mirror servers. An example:

The contents constitute a single JSON array of objects with the following keys:

Key Type Description
uri String The base URI for the mirror.
frequency String A description of the frequency of syncs from the master mirror.
location String The city/state/province/country where the mirror lives.
organization String The organization responsible for managing the mirror server.
timezone String The time zone in which the mirror server lives.
email String Email address for the organization managing the server.
bandwidth String The server's bandwidth.
src String The mirror the server mirrors from.
rsync String Public rsync address if the mirror allows other mirrors to rsync its contents.
notes String Arbitrary notes about the server.


   "uri": "http://pgxn.depesz.com/",
   "frequency": "every 6 hours",
   "location": "Nürnberg, Germany",
   "organization": "depesz Software Hubert Lubaczewski",
   "timezone": "CEST",
   "email": "depesz.com|web_pgxn",
   "bandwidth": "100Mbps",
   "src": "rsync://master.pgxn.org/pgxn/",
   "rsync": "",
   "notes": "access via http only"

Note: Email addresses returned by the mirrors API are obscured. The domain name part comes first and is separate from the username by a pipe.

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 JSON describing the network mirrors like so:

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

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