[tor-commits] [metrics-web/master] Add onionoo.html from onionoo.git (723e71a).
karsten at torproject.org
karsten at torproject.org
Thu Jul 6 12:46:42 UTC 2017
commit 09e27d6d85ccb1a9f65aefa2b9c764112cbc2dee
Author: Karsten Loesing <karsten.loesing at gmx.net>
Date: Sat Mar 18 21:31:39 2017 +0100
Add onionoo.html from onionoo.git (723e71a).
---
website/src/main/resources/web/onionoo.html | 2249 +++++++++++++++++++++++++++
1 file changed, 2249 insertions(+)
diff --git a/website/src/main/resources/web/onionoo.html b/website/src/main/resources/web/onionoo.html
new file mode 100644
index 0000000..d8fe74a
--- /dev/null
+++ b/website/src/main/resources/web/onionoo.html
@@ -0,0 +1,2249 @@
+<!DOCTYPE HTML>
+<html lang="en" style="min-height:100%;">
+<head>
+
+ <title>Onionoo</title>
+
+ <meta charset="utf-8">
+ <link href="images/favicon.ico" type="image/x-icon" rel="shortcut icon">
+
+ <!-- yes, we're handheld friendly :) -->
+ <meta name="HandheldFriendly" content="True">
+ <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
+ <meta name="apple-mobile-web-app-capable" content="yes">
+
+ <!-- icons for mobile devices -->
+ <link rel="apple-touch-icon" href="images/apple-touch-icon-152x152.png">
+ <link rel="shortcut icon" href="images/android-icon.png" sizes="196x196">
+ <meta name="msapplication-square70x70logo" content="images/smalltile.png">
+ <meta name="msapplication-square150x150logo" content="images/mediumtile.png">
+ <meta name="msapplication-wide310x150logo" content="images/widetile.png">
+ <meta name="msapplication-square310x310logo" content="images/largetile.png">
+
+ <!-- jQuery -->
+ <script src="js/jquery-3.1.1.min.js"></script>
+
+ <!-- Bootstrap -->
+ <link rel="stylesheet" href="css/bootstrap.min.css">
+ <script src="js/bootstrap.min.js"></script>
+
+ <!-- Fonts -->
+ <link rel="stylesheet" href="css/font-awesome.min.css">
+ <link rel="stylesheet" href="fonts/source-sans-pro.css">
+
+ <!-- custom styles and javascript -->
+ <link rel="stylesheet" href="css/style.css">
+ <script src="js/script.js"></script>
+
+</head>
+
+<body class="noscript" style="background-image:url(images/ajax-loader.gif);background-repeat:no-repeat;background-position:center center;">
+
+<!-- Using evil inline stylesheets to hide the FOUC for slow connections... -->
+
+<div id="wrapper" style="display:none;">
+
+
+<!-- backToTop-Button and Anchor -->
+<noscript>
+<div class="topButton" style="display:block;"><a href="#top"><i class="fa fa-chevron-up" aria-hidden="true"></i></a></div>
+</noscript>
+<script type="text/javascript">
+document.write('<div class="topButton" style="display:none;"><a href="#top"><i class="fa fa-chevron-up" aria-hidden="true"></i></a></div>');
+</script>
+<a id="top"></a>
+
+
+
+<!-- secondary navigation -->
+<nav class="navbar navbar-default navbar-secondary">
+ <div class="container-fluid visible-xs">
+ <input type="checkbox" id="navbar-toggle-checkbox">
+ <div class="navbar-header">
+ <label for="navbar-toggle-checkbox" type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-secondary" aria-expanded="false">
+ <span class="sr-only">Toggle navigation</span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ <span class="icon-bar"></span>
+ </label>
+ <a class="navbar-brand visible-xs" href="/"><img src="images/onionoo-wordmark-white.png" width="221" height="40" alt="Onionoo"></a>
+ </div>
+ <!-- Collect the nav links, forms, and other content for toggling -->
+ <div class="collapse navbar-collapse" id="bs-example-navbar-secondary">
+ <ul class="nav navbar-nav navbar-right">
+
+
+ <!-- secondary navigation items -->
+ <li><a href="#general">General</a></li>
+ <li><a href="#versions">Protocol versions</a></li>
+ <li><a href="#methods">Methods</a></li>
+ <li><a href="#responses">Responses</a></li>
+ <li><a href="#summary">Summary documents</a></li>
+ <li><a href="#details">Details documents</a></li>
+ <li><a href="#history">History objects</a></li>
+ <li><a href="#bandwidth">Bandwidth documents</a></li>
+ <li><a href="#weights">Weights documents</a></li>
+ <li><a href="#clients">Clients documents</a></li>
+ <li><a href="#uptime">Uptime documents</a></li>
+ <li><a href="#examples">Example usage</a></li>
+ <!-- /secondary navigation items -->
+
+ </ul>
+ </div><!-- /.navbar-collapse -->
+
+ </div>
+</nav>
+<!-- /secondary navigation -->
+
+
+
+<!-- page header for every single page -->
+<div class="page-header hidden-xs">
+ <a href="/"><img src="images/tor-logo-weiss.png" width="162" height="100" alt="" id="onionoo-logo"></a>
+ <span style="display:inline-block;width:20px;"></span>
+ <a href="/"><img src="images/onionoo-wordmark-white.png" width="221" height="40" alt="Onionoo" id="onionoo-wordmark"></a>
+ <div>
+ <p>
+ <i>The Tor network status protocol providing the<br>
+ data for other applications and websites.</i>
+ </p>
+ </div>
+ <div class="clearfix"></div>
+</div>
+<!-- /page header -->
+
+
+
+
+
+ <div class="container">
+
+
+<br><br>
+
+
+
+ <div class="jumbotron">
+ <div class="text-center">
+ <h2>
+ The Tor network status protocol
+ </h2>
+ <p>Onionoo is a web-based protocol to learn about currently running
+ Tor relays and bridges. Onionoo itself was not designed as a service
+ for human beings—at least not directly. Onionoo provides the
+ data for other applications and websites which in turn present Tor
+ network status information to humans. </p>
+ <a class="btn btn-primary btn-lg" style="margin: 10px" href="#protocol"><i class="fa fa-chevron-right" aria-hidden="true"></i> Tell me more!</a>
+
+ </div><!-- text-center -->
+
+
+ </div><!-- jumbotron -->
+
+
+
+
+
+
+<br>
+
+
+
+
+
+<br>
+<a id="protocol"></a>
+
+ <!-- floating anchor box -->
+ <div class="col-md-4 pull-right hidden-xs" style="padding:1.2em 0 0 2em;">
+ <div class="list-group">
+ <h3>Table of contents</h3>
+ <a class="list-group-item" href="#general">General</a>
+ <a class="list-group-item" href="#versions">Protocol versions</a>
+ <a class="list-group-item" href="#methods">Methods</a>
+ <a class="list-group-item" href="#responses">Responses</a>
+ <a class="list-group-item" href="#summary">Summary documents</a>
+ <a class="list-group-item" href="#details">Details documents</a>
+ <a class="list-group-item" href="#history">History objects</a>
+ <a class="list-group-item" href="#bandwidth">Bandwidth documents</a>
+ <a class="list-group-item" href="#weights">Weights documents</a>
+ <a class="list-group-item" href="#clients">Clients documents</a>
+ <a class="list-group-item" href="#uptime">Uptime documents</a>
+ <a class="list-group-item" href="#examples">Example usage</a>
+ </div>
+ </div>
+
+
+<h1>The Tor network status protocol <a href="#protocol" class="anchor">#</a></h1>
+
+<a id="general"></a><br>
+<h2>General <a href="#general" class="anchor">#</a></h2>
+
+<p>
+The Onionoo service is designed as a RESTful web service.
+Onionoo clients send HTTP GET requests to the Onionoo server which
+responds with JSON-formatted replies.
+Onionoo clients and their developers should follow a few rules:
+</p>
+
+<br>
+
+<h3>Compression</h3>
+<p>
+Clients should include an <strong>"Accept-Encoding:
+gzip"</strong> header in their requests and handle gzip-compressed
+responses.
+Only requests starting at a certain size will be compressed by the
+server.
+</p>
+
+<br>
+
+<h3>Caching</h3>
+<p>Clients should make use of the <strong>"Last-Modified"</strong>
+header of responses and include that timestamp in a
+<strong>"If-Modified-Since"</strong> header of subsequent requests.
+</p>
+
+<br>
+
+
+
+<div class="clearfix"></div>
+
+
+<h3>Response codes</h3>
+<p>
+Clients should handle response codes by
+distinguishing between client and server errors, and if there's a problem,
+informing their users about the kind of problem.
+The following response codes are used:
+</p>
+
+<ul class="properties">
+
+<li>
+<b>200 OK</b>
+<p>
+The request was processed successfully.
+</p>
+</li>
+
+<li>
+<b>304 Not Modified</b>
+<p>
+Server data has not changed since the
+<strong>"If-Modified-Since"</strong> header included in the request.
+</p>
+</li>
+
+<li>
+<b>400 Bad Request</b>
+<p>
+The request for a known resource could not be processed because of bad
+syntax.
+This is most likely a client problem.
+</p>
+</li>
+
+<li>
+<b>404 Not Available</b>
+<p>
+The request could not be processed because the requested resource could
+not be found.
+This is most likely a client problem.
+</p>
+</li>
+
+<li>
+<b>500 Internal Server Error</b>
+<p>
+There is an unspecific problem with
+the server which the service operator may not yet be aware of.
+Please check if there's already a bug report for this problem, and if not,
+file one.
+</p>
+</li>
+
+<li>
+<b>503 Service Unavailable</b>
+<p>
+The server is temporarily down for
+maintenance, or there is a temporary problem with the server that the
+service operator is already aware of.
+Only file a bug report if this problem persists.
+</p>
+</li>
+
+</ul>
+
+
+<a id="versions"></a><br>
+<h2>Protocol versions <a href="#versions" class="anchor">#</a></h2>
+<p>
+There are plenty of reasons why we may have
+to change the protocol described here.
+Clients should be able to handle all valid JSON responses, ignoring
+unknown fields and not breaking horribly in case of missing fields.
+Protocol changes will be announced here by writing deprecated API parts with
+the label <span class="label label-warning">deprecated</span> and new parts
+with the label <span class="label label-primary">new</span>.
+Deprecated parts will be removed one month after their announcement.
+</p>
+
+<p>All responses contain a <strong>"version"</strong> string that
+indicates whether clients can parse the document or not.
+Version strings consist of a major and a minor version number.
+The major version number is raised when previously required fields are
+dropped or turned into optional fields, when request parameters or
+response documents are removed, or when there are structural changes.
+The minor version number is raised when new fields, request parameters, or
+response documents are added or optional fields are dropped.
+If clients support the same major version given in a response but only a
+lower minor version, they should be able to parse the document but may not
+understand all fields.
+If clients support a lower major version, they should not attempt to parse
+a document, because there may be backward-incompatible changes.</p>
+
+<p>Responses may also contain the optional
+<strong>"next_major_version_scheduled"</strong> field that announces when
+the next major version is scheduled to be deployed.
+Clients should inform their users that they should upgrade to the next
+major protocol version before the provided date.</p>
+
+<p>The following versions have been used in the past six months or are
+scheduled to be deployed in the next months:</p>
+
+<ul>
+<li><strong>1.0</strong>: First assigned version number on August 31,
+2014.</li>
+<li><strong>1.1</strong>: Added optional "next_major_version_scheduled"
+field on September 16, 2014.</li>
+<li><strong>1.2</strong>: Added qualified search terms to "search"
+parameter on October 17, 2014.</li>
+<li><strong>2.0</strong>: Extended search parameter to base64-encoded
+fingerprints on November 15, 2014.</li>
+<li><strong>2.1</strong>: Removed optional "advertised_bandwidth_fraction"
+field from details documents and optional "advertised_bandwidth" and
+"advertised_bandwidth_fraction" fields from weights documents on November
+16, 2014.</li>
+<li><strong>2.2</strong>: Removed optional "pool_assignment" field and
+added "transports" field to bridge details documents on December 8,
+2014.</li>
+<li><strong>2.3</strong>: Added optional "flags" field to uptime
+documents on March 22, 2015.</li>
+<li><strong>2.4</strong>: Added optional "effective_family" field to
+details documents on July 3, 2015.</li>
+<li><strong>2.5</strong>: Added optional "measured" field to details
+documents on August 13, 2015.</li>
+<li><strong>2.6</strong>: Added optional "alleged_family" and
+"indirect_family" fields and deprecated optional "family" field in details
+documents on August 25, 2015.</li>
+<li><strong>3.0</strong>: Extended search parameter to match any 4 hex
+characters of a space-separated fingerprint on November 15, 2015.</li>
+<li><strong>3.1</strong>: Removed optional "family" field on January 18,
+2016.</li>
+<li><strong>3.2</strong>: Extended order parameter to "first_seen" and
+added response meta data fields "relays_skipped", "relays_truncated",
+"bridges_skipped", and "bridges_truncated" on January 27, 2017.</li>
+<li><strong>4.0</strong>: Extended search parameter to not require
+leading or enclosing square brackets around IPv6 addresses anymore on
+February 28, 2017.</li>
+</ul>
+
+
+
+<a id="methods"></a><br>
+<h2>Methods <a href="#methods" class="anchor">#</a></h2>
+
+<p>
+The following methods each return a single document containing zero or
+more objects of relays and/or bridges.
+By default, all relays and bridges are included that have been running in
+the past week.
+</p>
+
+<div class="responsive-table">
+ <table class="table table-striped">
+ <thead>
+ <tr>
+ <th class="method">Method</th>
+ <th class="url">URL</th>
+ <th class="description">Description</th>
+ </tr>
+ </thead>
+ <tbody>
+ <tr>
+ <td data-title="Method" >GET</td>
+ <td data-title="URL" >https://onionoo.torproject.org/summary</td>
+ <td data-title="Description" >returns a <a href="#summary">summary document</a></td>
+ </tr>
+ <tr>
+ <td data-title="Method" >GET</td>
+ <td data-title="URL" >https://onionoo.torproject.org/details</td>
+ <td data-title="Description" >returns a <a href="#details">details document</a></td>
+ </tr>
+ <tr>
+ <td data-title="Method" >GET</td>
+ <td data-title="URL" >https://onionoo.torproject.org/bandwidth</td>
+ <td data-title="Description" >returns a <a href="#bandwidth">bandwidth document</a></td>
+ </tr>
+ <tr>
+ <td data-title="Method" >GET</td>
+ <td data-title="URL" >https://onionoo.torproject.org/weights</td>
+ <td data-title="Description" >returns a <a href="#weights">weights document</a></td>
+ </tr>
+ <tr>
+ <td data-title="Method" >GET</td>
+ <td data-title="URL" >https://onionoo.torproject.org/clients</td>
+ <td data-title="Description" >returns a <a href="#clients">clients document</a></td>
+ </tr>
+ <tr>
+ <td data-title="Method" >GET</td>
+ <td data-title="URL" >https://onionoo.torproject.org/uptime</td>
+ <td data-title="Description" >returns an <a href="#uptime">uptime document</a></td>
+ </tr>
+
+ </tbody>
+ </table>
+</div>
+
+
+
+<h3>Parameters</h3>
+<p>
+Each of the methods can be parameterized to select only a subset of relay
+and/or bridge documents that are currently running or that have been
+running in the past week.
+(The <strong>fingerprint</strong> parameter is special here, because it
+allows selecting a specific relay or bridge, regardless of whether it has
+been running in the past week.)
+If multiple parameters are specified, they are combined using a logical
+AND operation, meaning that only the intersection of relays and bridges
+matching all parameters is returned.
+If the same parameter is specified more than once, only the first
+parameter value is considered.
+</p>
+
+<ul class="properties">
+
+<li>
+<b>type</b>
+<p>
+Return only relay (parameter value
+<strong>relay</strong>) or only bridge documents (parameter value
+<strong>bridge</strong>).
+Parameter values are case-insensitive.
+</p>
+</li>
+
+<li>
+<b>running</b>
+<p>
+Return only running (parameter value
+<strong>true</strong>) or only non-running relays and/or bridges
+(paramter value
+<strong>false</strong>).
+Parameter values are case-insensitive.
+</p>
+</li>
+
+<li>
+<b>search</b>
+<p>
+Return only (1) relays with the parameter value matching (part of a)
+nickname, (possibly $-prefixed) beginning of a hex-encoded fingerprint,
+any 4 hex characters of a space-separated fingerprint, beginning of a
+base64-encoded fingerprint without trailing equal signs, or beginning of
+an IP address (possibly enclosed in square brackets in case of IPv6),
+(2) bridges with (part of a) nickname or (possibly
+$-prefixed) beginning of a hashed hex-encoded fingerprint, and (3) relays
+and/or bridges matching a given qualified search term.
+Searches by relay IP address include all known addresses used for onion
+routing and for exiting to the Internet.
+Searches for beginnings of IP addresses are performed on textual
+representations of canonical IP address forms, so that searches using CIDR
+notation or non-canonical forms will return empty results.
+Searches are case-insensitive, except for base64-encoded fingerprints.
+If multiple search terms are given, separated by spaces, the intersection
+of all relays and bridges matching all search terms will be returned.
+Complete hex-encoded fingerprints should always be hashed using SHA-1,
+regardless of searching for a relay or a bridge, in order to not
+accidentally leak non-hashed bridge fingerprints in the URL.
+Qualified search terms have the form "key:value" (without double quotes)
+with "key" being one of the parameters listed here except for "search",
+"fingerprint", "order", "limit", "offset", and "fields", and "value" being
+the string that will internally be passed to that parameter.
+</p>
+</li>
+
+<li>
+<b>lookup</b>
+<p>
+Return only the relay with the parameter
+value matching the fingerprint or the bridge with the parameter value
+matching the hashed fingerprint.
+Fingerprints should always be hashed using SHA-1, regardless of looking up
+a relay or a bridge, in order to not accidentally leak non-hashed bridge
+fingerprints in the URL.
+Lookups only work for full fingerprints or hashed fingerprints consisting
+of 40 hex characters.
+Lookups are case-insensitive.
+</p>
+</li>
+
+<li>
+<b>fingerprint</b>
+<p>
+Return only the relay with the parameter value matching the fingerprint
+or the bridge with the parameter value matching the hashed fingerprint.
+Fingerprints must consist of 40 hex characters, case does not matter.
+This parameter is quite similar to the <strong>lookup</strong> parameter
+with two exceptions:
+(1) the provided relay fingerprint or hashed bridge fingerprint <i>must
+not</i> be hashed (again) using SHA-1;
+(2) the response will contain any matching relay or bridge regardless of
+whether they have been running in the past week.
+</p>
+</li>
+
+<li>
+<b>country</b>
+<p>
+Return only relays which are located in the
+given country as identified by a two-letter country code.
+Filtering by country code is case-insensitive.
+</p>
+</li>
+
+<li>
+<b>as</b>
+<p>
+Return only relays which are located in the
+given autonomous system (AS) as identified by the AS number (with or
+without preceding "AS" part).
+Filtering by AS number is case-insensitive.
+</p>
+</li>
+
+<li>
+<b>flag</b>
+<p>
+Return only relays which have the
+given relay flag assigned by the directory authorities.
+Note that if the flag parameter is specified more than once, only the
+first parameter value will be considered.
+Filtering by flag is case-insensitive.
+</p>
+</li>
+
+<li>
+<b>first_seen_days</b>
+<p>
+Return only relays or bridges which
+have first been seen during the given range of days ago.
+A parameter value "x-y" with x <= y returns relays or bridges that have
+first been seen at least x and at most y days ago.
+Accepted short forms are "x", "x-", and "-y" which are interpreted as
+"x-x", "x-infinity", and "0-y".
+</p>
+</li>
+
+<li>
+<b>last_seen_days</b>
+<p>
+Return only relays or bridges which
+have last been seen during the given range of days ago.
+A parameter value "x-y" with x <= y returns relays or bridges that have
+last been seen at least x and at most y days ago.
+Accepted short forms are "x", "x-", and "-y" which are interpreted as
+"x-x", "x-infinity", and "0-y".
+Note that relays and bridges that haven't been running in the past week
+are not included in results, so that setting x to 8 or higher will lead to
+an empty result set.
+</p>
+</li>
+
+<li>
+<b>contact</b>
+<p>
+Return only relays with the parameter value
+matching (part of) the contact line.
+If the parameter value contains spaces, only relays are returned which
+contain all space-separated parts in their contact line.
+Only printable ASCII characters are permitted in the parameter value,
+some of which need to be percent-encoded (# as %23, % as %25, & as
+%26, + as %2B, and / as %2F).
+Comparisons are case-insensitive.
+</p>
+</li>
+
+<li>
+<b>family</b>
+<p>
+Return only the relay whose fingerprint matches the parameter value and
+all relays that this relay has listed in its family by fingerprint and
+that in turn have listed this relay in their family by fingerprint.
+If relays have listed other relays in their family by nickname, those
+family relationships will not be considered, regardless of whether they
+have the Named flag or not.
+The provided relay fingerprint must consist of 40 hex characters where
+case does not matter, and it must not be hashed using SHA-1.
+Bridges are not contained in the result, regardless of whether they define
+a family.
+</p>
+</li>
+
+</ul>
+
+<p>
+Response documents can be reduced in size by requesting only a subset
+of contained fields.
+</p>
+
+<ul class="properties">
+
+<li>
+<b>fields</b>
+<p>
+Comma-separated list of fields that will be
+included in the result.
+So far, only top-level fields in relay or bridge objects of details
+documents can be specified, e.g.,
+<strong>nickname,hashed_fingerprint</strong>.
+If the fields parameter is provided, all other fields which are not
+contained in the provided list will be removed from the result.
+Field names are case-insensitive.
+</p>
+</li>
+
+</ul>
+
+<p>
+Relay and/or bridge documents in the response can be ordered and
+limited by providing further parameters.
+If the same parameter is specified more than once, only the first
+parameter value is considered.
+</p>
+
+<ul class="properties">
+
+<li>
+<b>order</b>
+<p>
+Re-order results by a comma-separated list
+of fields in ascending or descending order.
+Results are first ordered by the first list element, then by the second,
+and so on.
+Possible fields for ordering are: <strong>consensus_weight</strong> and
+<strong>first_seen</strong>.
+Field names are case-insensitive.
+Ascending order is the default; descending order is selected by prepending
+fields with a minus sign (<strong>-</strong>).
+Field names can be listed at most once in either ascending or descending
+order.
+Relays or bridges which don't have any value for a field to be ordered by
+are always appended to the end, regardless or sorting order.
+The ordering is defined independent of the requested document type and
+does not require the ordering field to be contained in the document.
+If no <strong>order</strong> parameter is given, ordering of results is
+undefined.
+</p>
+</li>
+
+<li>
+<b>offset</b>
+<p>
+Skip the given number of relays and/or
+bridges.
+Relays are skipped first, then bridges.
+Non-positive <strong>offset</strong> values are treated as zero and don't
+change the
+result.
+</p>
+</li>
+
+<li>
+<b>limit</b>
+<p>
+Limit result to the given number of
+relays and/or bridges.
+Relays are kept first, then bridges.
+Non-positive <strong>limit</strong> values are treated as zero and lead
+to an empty
+result.
+When used together with <strong>offset</strong>, the offsetting step
+precedes the
+limiting step.
+</p>
+</li>
+
+</ul>
+
+
+<a id="responses"></a><br>
+<h2>Responses <a href="#responses" class="anchor">#</a></h2>
+
+<p>Responses all have the same structure, regardless of requested
+method and provided parameters.
+Responses contain the following fields:</p>
+
+<ul class="properties">
+
+<li>
+<b>version</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+Onionoo protocol version string.
+</p>
+</li>
+
+<li>
+<b>next_major_version_scheduled</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+UTC date (YYYY-MM-DD) when the next major protocol version is scheduled to
+be deployed.
+Omitted if no major protocol changes are planned.
+</p>
+</li>
+
+<li>
+<b>relays_published</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+UTC timestamp (YYYY-MM-DD hh:mm:ss) when the last known relay network
+status consensus started being valid.
+Indicates how recent the relay objects in this document are.
+</p>
+</li>
+
+<li>
+<b>relays_skipped <span class="label label-primary">new</span></b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Number of skipped relays as requested by a positive "offset" parameter
+value.
+Omitted if zero.
+<span class="blue">Added on January 27, 2017.</span>
+</p>
+</li>
+
+<li>
+<b>relays</b>
+<code class="typeof">array of objects</code>
+<span class="required-true">required</span>
+<p>
+Array of relay objects as specified below.
+</p>
+</li>
+
+<li>
+<b>relays_truncated <span class="label label-primary">new</span></b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Number of truncated relays as requested by a positive "limit"
+parameter value.
+Omitted if zero.
+<span class="blue">Added on January 27, 2017.</span>
+</p>
+</li>
+
+<li>
+<b>bridges_published</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+UTC timestamp (YYYY-MM-DD hh:mm:ss) when
+the last known bridge network status was published.
+Indicates how recent the bridge objects in this document are.
+</p>
+</li>
+
+<li>
+<b>bridge_skipped <span class="label label-primary">new</span></b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Number of skipped bridges as requested by a positive "offset"
+parameter value.
+Omitted if zero.
+<span class="blue">Added on January 27, 2017.</span>
+</p>
+</li>
+
+<li>
+<b>bridges</b>
+<code class="typeof">array of objects</code>
+<span class="required-true">required</span>
+<p>
+Array of bridge objects as specified below.
+</p>
+</li>
+
+<li>
+<b>bridges_truncated <span class="label label-primary">new</span></b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Number of truncated bridges as requested by a positive "limit"
+parameter value.
+Omitted if zero.
+<span class="blue">Added on January 27, 2017.</span>
+</p>
+</li>
+
+</ul>
+
+
+<a id="summary"></a><br>
+<h2>Summary documents <a href="#summary" class="anchor">#</a>
+<span class="request-response">
+<a href="summary?limit=4">example request</a>
+</span>
+</h2>
+
+<p>Summary documents contain short summaries of relays with nicknames,
+fingerprints, IP addresses, and running information as well as bridges
+with hashed fingerprints and running information.</p>
+
+<h3>Relay summary objects</h3>
+
+<p>
+Relay summary objects contain the following key-value pairs:
+</p>
+
+<ul class="properties">
+
+<li>
+<b>n</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+Relay nickname consisting of 1–19 alphanumerical characters.
+Omitted if the relay nickname is <strong>"Unnamed"</strong>.
+</p>
+</li>
+
+<li>
+<b>f</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+Relay fingerprint consisting of 40 upper-case hexadecimal characters.
+</p>
+</li>
+
+<li>
+<b>a</b>
+<code class="typeof">array of strings</code>
+<span class="required-true">required</span>
+<p>
+Array of IPv4 or IPv6 addresses where the relay accepts
+onion-routing connections or which the relay used to exit to the Internet
+in the past 24 hours.
+The first address is the primary onion-routing address that the relay used
+to register in the network, subsequent addresses are in arbitrary order.
+IPv6 hex characters are all lower-case.
+</p>
+</li>
+
+<li>
+<b>r</b>
+<code class="typeof">boolean</code>
+<span class="required-true">required</span>
+<p>
+Boolean field saying whether this relay was listed as
+running in the last relay network status consensus.
+</p>
+</li>
+
+</ul>
+
+<h3>Bridge summary objects</h3>
+
+<p>
+Bridge summary objects contain the following key-value pairs:
+</p>
+
+<ul class="properties">
+
+<li>
+<b>n</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+Bridge nickname consisting of 1–19 alphanumerical characters.
+Omitted if the bridge nickname is <strong>"Unnamed"</strong>.
+</p>
+</li>
+
+<li>
+<b>h</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+SHA-1 hash of the bridge fingerprint consisting of 40
+upper-case hexadecimal characters.
+</p>
+</li>
+
+<li>
+<b>r</b>
+<code class="typeof">boolean</code>
+<span class="required-true">required</span>
+<p>
+Boolean field saying whether this bridge was listed as
+running in the last bridge network status.
+</p>
+</li>
+
+</ul>
+
+
+<a id="details"></a><br>
+<h2>Details documents <a href="#details" class="anchor">#</a>
+<span class="request-response">
+<a href="details?limit=4">example request</a>
+</span>
+</h2>
+
+<p>
+Details documents are based on network statuses published by the Tor
+directories, server descriptors published by relays and bridges, and data
+published by Tor network services TorDNSEL and BridgeDB.
+Details documents use the most recently published data from these sources,
+which may lead to contradictions between fields based on different sources
+in rare edge cases.
+</p>
+
+<h3>Relay details objects</h3>
+
+<p>
+Relay details objects contain the following key-value pairs:
+</p>
+
+<ul class="properties">
+
+<li>
+<b>nickname</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+Relay nickname consisting of 1–19 alphanumerical characters.
+Omitted if the relay nickname is <strong>"Unnamed"</strong>.
+</p>
+</li>
+
+<li>
+<b>fingerprint</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+Relay fingerprint consisting of 40 upper-case
+hexadecimal characters.
+</p>
+</li>
+
+<li>
+<b>or_addresses</b>
+<code class="typeof">array of strings</code>
+<span class="required-true">required</span>
+<p>
+Array of IPv4 or IPv6 addresses and TCP ports
+or port lists where the relay accepts onion-routing connections.
+The first address is the primary onion-routing address that the relay used
+to register in the network, subsequent addresses are in arbitrary order.
+IPv6 hex characters are all lower-case.
+</p>
+</li>
+
+<li>
+<b>exit_addresses</b>
+<code class="typeof">array of strings</code>
+<span class="required-false">optional</span>
+<p>
+Array of IPv4 or IPv6 addresses that the
+relay used to exit to the Internet in the past 24 hours.
+IPv6 hex characters are all lower-case.
+Only those addresses are listed that are different from onion-routing
+addresses.
+Omitted if array is empty.
+</p>
+</li>
+
+<li>
+<b>dir_address</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+IPv4 address and TCP port where the relay
+accepts directory connections.
+Omitted if the relay does not accept directory connections.
+</p>
+</li>
+
+<li>
+<b>last_seen</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+UTC timestamp (YYYY-MM-DD hh:mm:ss) when this
+relay was last seen in a network status consensus.
+</p>
+</li>
+
+<li>
+<b>last_changed_address_or_port</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+UTC timestamp (YYYY-MM-DD
+hh:mm:ss) when this relay last stopped announcing an IPv4 or IPv6 address
+or TCP port where it previously accepted onion-routing or directory
+connections.
+This timestamp can serve as indicator whether this relay would be a
+suitable fallback directory.
+</p>
+</li>
+
+<li>
+<b>first_seen</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+UTC timestamp (YYYY-MM-DD hh:mm:ss) when this
+relay was first seen in a network status consensus.
+</p>
+</li>
+
+<li>
+<b>running</b>
+<code class="typeof">boolean</code>
+<span class="required-true">required</span>
+<p>
+Boolean field saying whether this relay was listed as
+running in the last relay network status consensus.
+</p>
+</li>
+
+<li>
+<b>hibernating</b>
+<code class="typeof">boolean</code>
+<span class="required-false">optional</span>
+<p>
+Boolean field saying whether this relay indicated that it is hibernating
+in its last known server descriptor.
+This information may be helpful to decide whether a relay that is not
+running anymore has reached its accounting limit and has not dropped out
+of the network for another, unknown reason.
+Omitted if either the relay is not hibernating, or if no information is
+available about the hiberation status of the relay.
+</p>
+</li>
+
+<li>
+<b>flags</b>
+<code class="typeof">array of strings</code>
+<span class="required-false">optional</span>
+<p>
+Array of relay flags that the directory authorities
+assigned to this relay.
+May be omitted if empty.
+</p>
+</li>
+
+<li>
+<b>country</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+Two-letter lower-case country code as found in a
+GeoIP database by resolving the relay's first onion-routing IP address.
+Omitted if the relay IP address could not be found in the GeoIP
+database.
+</p>
+</li>
+
+<li>
+<b>country_name</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+Country name as found in a GeoIP database by
+resolving the relay's first onion-routing IP address.
+Omitted if the relay IP address could not be found in the GeoIP
+database, or if the GeoIP database did not contain a country name.
+</p>
+</li>
+
+<li>
+<b>region_name</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+Region name as found in a GeoIP database by
+resolving the relay's first onion-routing IP address.
+Omitted if the relay IP address could not be found in the GeoIP
+database, or if the GeoIP database did not contain a region name.
+</p>
+</li>
+
+<li>
+<b>city_name</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+City name as found in a
+GeoIP database by resolving the relay's first onion-routing IP address.
+Omitted if the relay IP address could not be found in the GeoIP
+database, or if the GeoIP database did not contain a city name.
+</p>
+</li>
+
+<li>
+<b>latitude</b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Latitude as found in a GeoIP database by resolving
+the relay's first onion-routing IP address.
+Omitted if the relay IP address could not be found in the GeoIP
+database.
+</p>
+</li>
+
+<li>
+<b>longitude</b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Longitude as found in a GeoIP database by
+resolving the relay's first onion-routing IP address.
+Omitted if the relay IP address could not be found in the GeoIP
+database.
+</p>
+</li>
+
+<li>
+<b>as_number</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+AS number as found in an AS database by
+resolving the relay's first onion-routing IP address.
+AS number strings start with "AS", followed directly by the AS number.
+Omitted if the relay IP address could not be found in the AS
+database.
+</p>
+</li>
+
+<li>
+<b>as_name</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+AS name as found in an AS database by resolving the
+relay's first onion-routing IP address.
+Omitted if the relay IP address could not be found in the AS
+database.
+</p>
+</li>
+
+<li>
+<b>consensus_weight</b>
+<code class="typeof">number</code>
+<span class="required-true">required</span>
+<p>
+Weight assigned to this relay by the
+directory authorities that clients use in their path selection algorithm.
+The unit is arbitrary; currently it's kilobytes per second, but that might
+change in the future.
+</p>
+</li>
+
+<li>
+<b>host_name</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+Host name as found in a reverse DNS lookup of the
+relay IP address.
+This field is updated at most once in 12 hours, unless the relay IP
+address changes.
+Omitted if the relay IP address was not looked up or if no lookup request
+was successful yet.
+</p>
+</li>
+
+<li>
+<b>last_restarted</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+UTC timestamp (YYYY-MM-DD hh:mm:ss) when the
+relay was last (re-)started.
+Missing if router descriptor containing this information cannot be
+found.
+</p>
+</li>
+
+<li>
+<b>bandwidth_rate</b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Average bandwidth
+in bytes per second that this relay is willing to sustain over long
+periods.
+Missing if router descriptor containing this information cannot be
+found.
+</p>
+</li>
+
+<li>
+<b>bandwidth_burst</b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Bandwidth in bytes
+per second that this relay is willing to sustain in very short intervals.
+Missing if router descriptor containing this information cannot be
+found.
+</p>
+</li>
+
+<li>
+<b>observed_bandwidth</b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Bandwidth
+estimate in bytes per second of the capacity this relay can handle.
+The relay remembers the maximum bandwidth sustained output over any ten
+second period in the past day, and another sustained input.
+The "observed_bandwidth" value is the lesser of these two numbers.
+Missing if router descriptor containing this information cannot be
+found.
+</p>
+</li>
+
+<li>
+<b>advertised_bandwidth</b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Bandwidth in bytes per second that this
+relay is willing and capable to provide.
+This bandwidth value is the minimum of <strong>bandwidth_rate</strong>,
+<strong>bandwidth_burst</strong>, and <strong>observed_bandwidth</strong>.
+Missing if router descriptor containing this information cannot be
+found.
+</p>
+</li>
+
+<li>
+<b>exit_policy</b>
+<code class="typeof">array of strings</code>
+<span class="required-false">optional</span>
+<p>
+Array of exit-policy lines.
+Missing if router descriptor containing this information cannot be
+found.
+May contradict the <strong>"exit_policy_summary"</strong> field in a rare
+edge case: this happens when the relay changes its exit policy after the
+directory authorities summarized the previous exit policy.
+</p>
+</li>
+
+<li>
+<b>exit_policy_summary</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+Summary
+version of the relay's exit policy containing a dictionary with either an
+"accept" or a "reject" element.
+If there is an "accept" ("reject") element, the relay accepts (rejects)
+all TCP ports or port ranges in the given list for most IP addresses and
+rejects (accepts) all other ports.
+May contradict the <strong>"exit_policy"</strong> field in a rare edge
+case: this happens when the relay changes its exit policy after the
+directory authorities summarized the previous exit policy.
+</p>
+</li>
+
+<li>
+<b>exit_policy_v6_summary</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+Summary version of the relay's IPv6 exit policy containing a dictionary
+with either an "accept" or a "reject" element.
+If there is an "accept" ("reject") element, the relay accepts (rejects)
+all TCP ports or port ranges in the given list for most IP addresses and
+rejects (accepts) all other ports.
+Missing if the relay rejects all connections to IPv6 addresses.
+May contradict the <strong>"exit_policy_summary"</strong> field in a rare
+edge case: this happens when the relay changes its exit policy after the
+directory authorities summarized the previous exit policy.
+</p>
+</li>
+
+<li>
+<b>contact</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+Contact address of the relay operator.
+Omitted if empty or if descriptor containing this information cannot be
+found.
+</p>
+</li>
+
+<li>
+<b>platform</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+Platform string containing operating system and Tor
+version details.
+Omitted if empty or if descriptor containing this information cannot be
+found.
+</p>
+</li>
+
+<li>
+<b>recommended_version</b>
+<code class="typeof">boolean</code>
+<span class="required-false">optional</span>
+<p>
+Boolean field saying whether the Tor software version of this relay is
+recommended by the directory authorities or not.
+Omitted if either the directory authorities did not recommend versions, or
+the relay did not report which version it runs.
+</p>
+</li>
+
+<li>
+<b>effective_family</b>
+<code class="typeof">array of strings</code>
+<span class="required-false">optional</span>
+<p>
+Array of $-prefixed fingerprints of relays that are in an effective,
+mutual family relationship with this relay.
+These relays are part of this relay's family and they consider this relay
+to be part of their family.
+Omitted if empty or if descriptor containing this information cannot be
+found.
+</p>
+</li>
+
+<li>
+<b>alleged_family</b>
+<code class="typeof">array of strings</code>
+<span class="required-false">optional</span>
+<p>
+Array of $-prefixed fingerprints of relays that are not in an effective,
+mutual family relationship with this relay.
+These relays are part of this relay's family but they don't consider this
+relay to be part of their family.
+Omitted if empty or if descriptor containing this information cannot be
+found.
+</p>
+</li>
+
+<li>
+<b>indirect_family</b>
+<code class="typeof">array of strings</code>
+<span class="required-false">optional</span>
+<p>
+Array of $-prefixed fingerprints of relays that are not in an effective,
+mutual family relationship with this relay but that can be reached by
+following effective, mutual family relationships starting at this relay.
+Omitted if empty or if descriptor containing this information cannot be
+found.
+</p>
+</li>
+
+<li>
+<b>consensus_weight_fraction</b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Fraction of this relay's consensus weight compared to the sum of all
+consensus weights in the network.
+This fraction is a very rough approximation of the probability of this
+relay to be selected by clients.
+Omitted if the relay is not running.
+</p>
+</li>
+
+<li>
+<b>guard_probability</b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Probability of this relay to be selected for the guard position.
+This probability is calculated based on consensus weights, relay flags,
+and bandwidth weights in the consensus.
+Path selection depends on more factors, so that this probability can only
+be an approximation.
+Omitted if the relay is not running, or the consensus does not contain
+bandwidth weights.
+</p>
+</li>
+
+<li>
+<b>middle_probability</b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Probability of this relay to be selected for the middle position.
+This probability is calculated based on consensus weights, relay flags,
+and bandwidth weights in the consensus.
+Path selection depends on more factors, so that this probability can only
+be an approximation.
+Omitted if the relay is not running, or the consensus does not contain
+bandwidth weights.
+</p>
+</li>
+
+<li>
+<b>exit_probability</b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Probability of this relay to be selected for the exit position.
+This probability is calculated based on consensus weights, relay flags,
+and bandwidth weights in the consensus.
+Path selection depends on more factors, so that this probability can only
+be an approximation.
+Omitted if the relay is not running, or the consensus does not contain
+bandwidth weights.
+</p>
+</li>
+
+<li>
+<b>measured</b>
+<code class="typeof">boolean</code>
+<span class="required-false">optional</span>
+<p>
+Boolean field saying whether the consensus weight of this relay is based
+on a threshold of 3 or more measurements by Tor bandwidth authorities.
+Omitted if the network status consensus containing this relay does not
+contain measurement information.
+</p>
+</li>
+
+</ul>
+
+<h3>Bridge details objects</h3>
+
+<p>
+Bridge details objects contain the following key-value pairs:
+</p>
+
+<ul class="properties">
+
+<li>
+<b>nickname</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+Bridge nickname consisting of 1–19
+alphanumerical characters.
+Omitted if the bridge nickname is <strong>"Unnamed"</strong>.
+</p>
+</li>
+
+<li>
+<b>hashed_fingerprint</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+SHA-1 hash of the bridge fingerprint
+consisting of 40 upper-case hexadecimal characters.
+</p>
+</li>
+
+<li>
+<b>or_addresses</b>
+<code class="typeof">array of strings</code>
+<span class="required-true">required</span>
+<p>
+Array of sanitized IPv4 or IPv6 addresses and
+TCP ports or port lists where the bridge accepts onion-routing
+connections.
+The first address is the primary onion-routing address that the bridge
+used to register in the network, subsequent addresses are in arbitrary
+order.
+IPv6 hex characters are all lower-case.
+Sanitized IP addresses are always in <strong>10/8</strong> or
+<strong>[fd9f:2e19:3bcf/48]</strong> IP networks and are only useful to
+learn which
+IP version the bridge uses and to detect whether the bridge changed its
+address.
+Sanitized IP addresses always change on the 1st of every month at 00:00:00
+UTC, regardless of the bridge actually changing its IP address.
+TCP ports are not sanitized.
+</p>
+</li>
+
+<li>
+<b>last_seen</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+UTC timestamp (YYYY-MM-DD hh:mm:ss) when this
+bridge was last seen in a bridge network status.
+</p>
+</li>
+
+<li>
+<b>first_seen</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+UTC timestamp (YYYY-MM-DD hh:mm:ss) when this
+bridge was first seen in a bridge network status.
+</p>
+</li>
+
+<li>
+<b>running</b>
+<code class="typeof">boolean</code>
+<span class="required-true">required</span>
+<p>
+Boolean field saying whether this bridge was listed
+as running in the last bridge network status.
+</p>
+</li>
+
+<li>
+<b>flags</b>
+<code class="typeof">array of strings</code>
+<span class="required-false">optional</span>
+<p>
+Array of relay flags that the bridge authority
+assigned to this bridge.
+May be omitted if empty.
+</p>
+</li>
+
+<li>
+<b>last_restarted</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+UTC timestamp (YYYY-MM-DD hh:mm:ss) when the
+bridge was last (re-)started.
+Missing if router descriptor containing this information cannot be
+found.
+</p>
+</li>
+
+<li>
+<b>advertised_bandwidth</b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Bandwidth in bytes per second that this
+bridge is willing and capable to provide.
+This bandwidth value is the minimum of <strong>bandwidth_rate</strong>,
+<strong>bandwidth_burst</strong>, and <strong>observed_bandwidth</strong>.
+Missing if router descriptor containing this information cannot be
+found.
+</p>
+</li>
+
+<li>
+<b>platform</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+Platform string containing operating system and Tor
+version details.
+Omitted if not provided by the bridge or if descriptor containing this
+information cannot be found.
+</p>
+</li>
+
+<li>
+<b>transports</b>
+<code class="typeof">array of strings</code>
+<span class="required-false">optional</span>
+<p>
+Array of (pluggable) transport names supported by this bridge.
+</p>
+</li>
+
+</ul>
+
+
+<a id="history"></a><br>
+<h2>History objects <a href="#history" class="anchor">#</a></h2>
+
+<p>
+History objects are no documents by themselves, but are contained in
+subsequent documents.
+<p>
+
+<h3>Graph history objects</h3>
+
+<p>
+Graph history objects contain the following fields:
+</p>
+
+<ul class="properties">
+
+<li>
+<b>first</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+UTC timestamp (YYYY-MM-DD hh:mm:ss) of the first data point, or more
+specifically the interval midpoint of the first interval.
+</p>
+</li>
+
+<li>
+<b>last</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+UTC timestamp (YYYY-MM-DD hh:mm:ss) of the last data point, or more
+specifically the interval midpoint of the last interval.
+</p>
+</li>
+
+<li>
+<b>interval</b>
+<code class="typeof">number</code>
+<span class="required-true">required</span>
+<p>
+Time interval between two data points in seconds.
+</p>
+</li>
+
+<li>
+<b>factor</b>
+<code class="typeof">number</code>
+<span class="required-true">required</span>
+<p>
+Factor by which subsequent data values need to be multiplied to obtain
+original values.
+The idea is to reduce document size while still providing sufficient
+detail for very different data scales.
+</p>
+</li>
+
+<li>
+<b>count</b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Number of provided data points, included mostly for debugging purposes.
+Can also be derived from the number of elements in the subsequent array.
+</p>
+</li>
+
+<li>
+<b>values</b>
+<code class="typeof">array of numbers</code>
+<span class="required-true">required</span>
+<p>
+Array of normalized values between 0 and 999.
+May contain null values.
+Contains at least two subsequent non-null values to enable drawing of line
+graphs.
+</p>
+</li>
+
+</ul>
+
+
+<a id="bandwidth"></a><br>
+<h2>Bandwidth documents <a href="#bandwidth" class="anchor">#</a>
+<span class="request-response">
+<a href="bandwidth?limit=4">example request</a>
+</span>
+</h2>
+
+<p>
+Bandwidth documents contain aggregate statistics of a relay's or
+bridge's consumed bandwidth for different time intervals.
+Bandwidth documents are only updated when a relay or bridge publishes a
+new server descriptor, which may take up to 18 hours during normal
+operation.
+</p>
+
+<h3>Relay bandwidth objects</h3>
+
+<p>
+Relay bandwidth objects contain the following key-value pairs:
+</p>
+
+<ul class="properties">
+
+<li>
+<b>fingerprint</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+Relay fingerprint consisting of 40 upper-case
+hexadecimal characters.
+</p>
+</li>
+
+<li>
+<b>write_history</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+Object containing graph history objects with written bytes for different
+time periods.
+Keys are string representation of the time period covered by the graph
+history object.
+Keys are fixed strings <strong>"3_days"</strong>,
+<strong>"1_week"</strong>, <strong>"1_month"</strong>,
+<strong>"3_months"</strong>, <strong>"1_year"</strong>, and
+<strong>"5_years"</strong>.
+Keys refer to the last known bandwidth history of a relay, not to the time
+when the bandwidth document was published.
+A graph history object is only contained if the time period it covers is
+not already contained in another graph history object with shorter time
+period and higher data resolution.
+Similarly, a graph history object is excluded if the relay did not provide
+bandwidth histories on the required level of detail.
+The unit is bytes per second.
+Contained graph history objects may contain null values if the relay did
+not provide any bandwidth data or only data for less than 20% of a given
+time period.
+</p>
+</li>
+
+<li>
+<b>read_history</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+Object containing graph history objects with read bytes for different time
+periods.
+The specification of graph history objects is similar to those in the
+<strong>write_history</strong> field.
+</p>
+</li>
+
+</ul>
+
+<h3>Bridge bandwidth objects</h3>
+
+<p>
+Bridge bandwidth objects contain the following key-value pairs:
+</p>
+
+<ul class="properties">
+
+<li>
+<b>fingerprint</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+SHA-1 hash of the bridge fingerprint consisting
+of 40 upper-case hexadecimal characters.
+</p>
+</li>
+
+<li>
+<b>write_history</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+Object containing graph history objects with written bytes for different
+time periods.
+The specification of graph history objects is similar to those in the
+<strong>write_history</strong> field of <strong>relays</strong>.
+</p>
+</li>
+
+<li>
+<b>read_history</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+Object containing graph history objects with read bytes for different time
+periods.
+The specification of graph history objects is similar to those in the
+<strong>write_history</strong> field of <strong>relays</strong>.
+</p>
+</li>
+
+</ul>
+
+
+<a id="weights"></a><br>
+<h2>Weights documents <a href="#weights" class="anchor">#</a>
+<span class="request-response">
+<a href="weights?limit=4">example request</a>
+</span>
+</h2>
+
+<p>
+Weights documents contain aggregate statistics of a relay's probability
+to be selected by clients for building paths.
+Weights documents contain different time intervals and are available for
+relays only.
+</p>
+
+<h3>Relay weights objects</h3>
+
+<p>
+Relay weights objects contain the following key-value pairs:
+</p>
+
+<ul class="properties">
+
+<li>
+<b>fingerprint</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+Relay fingerprint consisting of 40 upper-case
+hexadecimal characters.
+</p>
+</li>
+
+<li>
+<b>consensus_weight_fraction</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+History object containing the
+fraction of this relay's consensus weight compared to the sum of all
+consensus weights in the network.
+This fraction is a very rough approximation of the probability of this
+relay to be selected by clients.
+Keys are string representation of the time period covered by the graph
+history object.
+Keys are fixed strings <strong>"1_week"</strong>,
+<strong>"1_month"</strong>, <strong>"3_months"</strong>,
+<strong>"1_year"</strong>, and <strong>"5_years"</strong>.
+Keys refer to the last known weights history of a relay, not to the time
+when the weights document was published.
+A graph history object is only contained if the time period it covers is
+not already contained in another graph history object with shorter time
+period and higher data resolution.
+The unit is path-selection probability.
+Contained graph history objects may contain null values if the relay was
+running less than 20% of a given time period.
+</p>
+</li>
+
+<li>
+<b>guard_probability</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+History object containing the probability
+of this relay to be selected for the guard position.
+This probability is calculated based on consensus weights, relay flags,
+and bandwidth weights in the consensus.
+Path selection depends on more factors, so that this probability can only
+be an approximation.
+The specification of this history object is similar to that in the
+<strong>consensus_weight_fraction</strong> field above.
+</p>
+</li>
+
+<li>
+<b>middle_probability</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+History object containing the probability
+of this relay to be selected for the middle position.
+This probability is calculated based on consensus weights, relay flags,
+and bandwidth weights in the consensus.
+Path selection depends on more factors, so that this probability can only
+be an approximation.
+The specification of this history object is similar to that in the
+<strong>consensus_weight_fraction</strong> field above.
+</p>
+</li>
+
+<li>
+<b>exit_probability</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+History object containing the probability
+of this relay to be selected for the exit position.
+This probability is calculated based on consensus weights, relay flags,
+and bandwidth weights in the consensus.
+Path selection depends on more factors, so that this probability can only
+be an approximation.
+The specification of this history object is similar to that in the
+<strong>consensus_weight_fraction</strong> field above.
+</p>
+</li>
+
+<li>
+<b>consensus_weight</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+History object containing the absolute consensus weight of this relay.
+The specification of this history object is similar to that in the
+<strong>consensus_weight_fraction</strong> field above.
+</p>
+</li>
+
+</ul>
+
+
+<a id="clients"></a><br>
+<h2>Clients documents <a href="#clients" class="anchor">#</a>
+<span class="request-response">
+<a href="clients?limit=4">example request</a>
+</span>
+</h2>
+
+<p>
+Clients documents contain estimates of the average number of clients
+connecting to a bridge every day.
+There are no clients documents available for relays, just for bridges.
+Clients documents contain different time intervals and are available for
+bridges only.
+</p>
+
+<h3>Bridge clients objects</h3>
+
+<p>
+Bridge clients objects contain the following key-value pairs:
+</p>
+
+<ul class="properties">
+
+<li>
+<b>fingerprint</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+SHA-1 hash of the bridge fingerprint consisting
+of 40 upper-case hexadecimal characters.
+</p>
+</li>
+
+<li>
+<b>average_clients</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+Object containing graph history objects with the average number of clients
+connecting to this bridge.
+Keys are string representation of the time period covered by the graph
+history object.
+Keys are fixed strings <strong>"1_week"</strong>,
+<strong>"1_month"</strong>, <strong>"3_months"</strong>,
+<strong>"1_year"</strong>, and <strong>"5_years"</strong>.
+Keys refer to the last known clients history of a bridge, not to the time
+when the clients document was published.
+A graph history object is only contained if the time period it covers
+is not already contained in another clients graph object with shorter
+time period and higher data resolution.
+The unit is number of clients.
+Contained graph history objects may contain null values if the bridge did
+not report client statistics for at least 50% of a given time period.
+Each graph history object contains the following additional key-value
+pairs:
+</p>
+
+<ul class="properties">
+
+<li>
+<b>countries <span class="label label-danger">beta</span></b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+Object containing fractions of clients by country in the considered time
+period.
+Keys are two-letter lower-case country codes as found in a GeoIP database.
+Values are numbers between 0 and 1 standing for the fraction of clients by
+country.
+A country is only included if at least 1% of clients came from this
+country.
+Omitted if the bridge did not report client statistics by country.
+<span class="red"><strong>BETA:</strong> This field breaks compatibility
+with the history objects contained in other documents pretty badly.
+It might be removed in the future without notice.</span>
+</p>
+</li>
+
+<li>
+<b>transports <span class="label label-danger">beta</span></b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+Object containing fractions of clients by transport in the considered time
+period.
+Keys are transport names, or <strong>"<OR>"</strong> for the default
+onion-routing transport protocol.
+Values are numbers between 0 and 1 standing for the fraction of clients by
+transport.
+Omitted if the bridge did not report client statistics by transport.
+<span class="red"><strong>BETA:</strong> This field breaks compatibility
+with the history objects contained in other documents pretty badly.
+It might be removed in the future without notice.</span>
+</p>
+</li>
+
+<li>
+<b>versions <span class="label label-danger">beta</span></b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+Object containing fractions of clients by IP version in the considered
+time period.
+Keys are either <strong>"v4"</strong> for IPv4 or <strong>"v6"</strong>
+for IPv6.
+Values are numbers between 0 and 1 standing for the fraction of clients by
+version.
+Omitted if the bridge did not report client statistics by IP version.
+<span class="red"><strong>BETA:</strong> This field breaks compatibility
+with the history objects contained in other documents pretty badly.
+It might be removed in the future without notice.</span>
+</p>
+</li>
+
+</ul>
+
+</li>
+
+</ul>
+
+
+<a id="uptime"></a><br>
+<h2>Uptime documents <a href="#uptime" class="anchor">#</a>
+<span class="request-response">
+<a href="uptime?limit=4">example request</a>
+</span>
+</h2>
+
+<p>
+Uptime documents contain fractional uptimes of relays and bridges.
+Uptime documents contain different time intervals and are available for
+relays and bridges.
+</p>
+
+<h3>Relay uptime objects</h3>
+
+<p>
+Relay uptime objects contain the following key-value pairs:
+</p>
+
+<ul class="properties">
+
+<li>
+<b>fingerprint</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+Relay fingerprint consisting of 40 upper-case
+hexadecimal characters.
+</p>
+</li>
+
+<li>
+<b>uptime</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+Object containing graph history objects with the fractional uptime of this
+relay.
+Keys are string representation of the time period covered by the graph
+history object.
+Keys are fixed strings <strong>"1_week"</strong>,
+<strong>"1_month"</strong>, <strong>"3_months"</strong>,
+<strong>"1_year"</strong>, and <strong>"5_years"</strong>.
+Keys refer to the last known uptime history of a relay, not to the time
+when the uptime document was published.
+A graph history object is only contained if the time period it covers is
+not already contained in another graph history object with shorter time
+period and higher data resolution.
+The unit is fractional uptime from 0 to 1.
+Contained graph history objects may contain null values if less than 20%
+of network statuses have been processed for a given time period.
+</p>
+</li>
+
+<li>
+<b>flags</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+Object containing fractional times of this relay having relay flags
+assigned.
+Keys are flag names like <strong>"Running"</strong> or
+<strong>"Exit"</strong>, values are objects similar to the
+<strong>uptime</strong> field above, again with keys like
+<strong>"1_week"</strong> etc.
+If a relay never had a given relay flag assigned, no object is included
+for that flag.
+</p>
+</li>
+
+</ul>
+
+<h3>Bridge uptime objects</h3>
+
+<p>
+Bridge uptime objects contain the following key-value pairs:
+</p>
+
+<ul class="properties">
+
+<li>
+<b>fingerprint</b>
+<code class="typeof">string</code>
+<span class="required-true">required</span>
+<p>
+SHA-1 hash of the bridge fingerprint consisting
+of 40 upper-case hexadecimal characters.
+</p>
+</li>
+
+<li>
+<b>uptime</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+Object containing uptime history objects for different time periods.
+The specification of uptime history objects is similar to those in the
+<strong>uptime</strong> field of <strong>relays</strong>.
+</p>
+</li>
+
+</ul>
+
+
+<a id="examples"></a><br>
+<h2>Example usage <a href="#examples" class="anchor">#</a>
+</h2>
+
+<p>
+The following examples illustrate how to build requests for some trivial
+and some more complex use cases.
+While Onionoo is designed mainly for developers and not end users, there
+may be cases when it's easier to quickly write a specific query Onionoo
+rather than to find an Onionoo client that provides the desired
+information.
+</p>
+
+<p>
+<code>/summary?limit=4</code>
+(<a href="/summary?limit=4">view result</a>)
+</p>
+
+<p>
+This first query returns the first four summary documents that Onionoo can
+find.
+The <code>limit</code> parameter should always be used while developing
+new queries to avoid downloading huge responses.
+</p>
+
+<p>
+<code>/summary?limit=4&search=moria</code>
+(<a href="/summary?limit=4&search=moria">view result</a>)
+</p>
+
+<p>
+The second query restricts results to relays and bridges containing the
+string "moria" in one of a few searched fields.
+</p>
+
+<p>
+<code>/details?limit=4&search=moria</code>
+(<a href="/details?limit=4&search=moria">view result</a>)
+</p>
+
+<p>
+The third query switches from the short summary documents to the longer
+details documents containing, well, more details.
+</p>
+
+<p>
+<code>/details?limit=4&search=moria&fields=nickname</code>
+(<a href="/details?limit=4&search=moria&fields=nickname">view result</a>)
+</p>
+
+<p>
+The fourth query adds the <code>fields</code> parameter which removes all
+fields except the specified ones from the result.
+This parameter is only implemented for details documents.
+</p>
+
+<p>
+<code>/details?limit=4&search=moria&fields=nickname&order=-consensus_weight</code>
+(<a href="/details?limit=4&search=moria&fields=nickname&order=-consensus_weight">view result</a>)
+</p>
+
+<p>
+The fifth query sorts results by relay consensus weight from largest to
+smallest.
+</p>
+
+<p>
+Obviously, this query can be made even more complex by adding more
+parameters, and in some cases this is necessary and useful.
+Please refer to the protocol specification for details.
+</p>
+
+
+
+</div>
+
+
+
+
+
+
+
+
+ <div class="container-fluid" id="footer">
+
+ <div class="container no-gutter">
+ <div class="col-xs-6">
+ <p>
+ © 2017 The Tor Project
+ </p>
+ </div>
+ <div class="col-xs-6">
+ <p class="pull-right">
+
+ <a href="https://metrics.torproject.org/about.html#contact">Contact</a>
+
+ </p>
+ </div>
+ </div>
+
+ <div class="container small">
+
+ <p>Data on this site is freely available under a <a href="http://creativecommons.org/publicdomain/zero/1.0/">CC0 no copyright declaration</a>: To the extent possible under law, the Tor Project has waived all copyright and related or neighboring rights in the data. "Tor" and the "Onion Logo" are <a href="https://www.torproject.org/docs/trademark-faq.html.en">registered trademarks</a> of The Tor Project, Inc.</p>
+
+ </div>
+
+ </div><!-- /footer -->
+
+
+
+</div><!-- /wrapper -->
+
+</body>
+</html>
+
More information about the tor-commits
mailing list