[tor-commits] [onionoo/master] Create real home page, move protocol to own page.
karsten at torproject.org
karsten at torproject.org
Tue Jun 17 07:37:13 UTC 2014
commit 39c7f613313d4eaaa54d34b5f4128b4fcb478111
Author: Karsten Loesing <karsten.loesing at gmx.net>
Date: Tue Jun 17 09:29:44 2014 +0200
Create real home page, move protocol to own page.
---
web/css/style.css | 4 +-
web/index.html | 2092 +++--------------------------------------------------
web/protocol.html | 2003 ++++++++++++++++++++++++++++++++++++++++++++++++++
3 files changed, 2113 insertions(+), 1986 deletions(-)
diff --git a/web/css/style.css b/web/css/style.css
index 9649745..e3caa4a 100644
--- a/web/css/style.css
+++ b/web/css/style.css
@@ -1,11 +1,9 @@
body { font-family: "Open Sans","lucida grande","Segoe UI",arial,verdana,
"lucida sans unicode",tahoma,sans-serif; background: #fafafa;
font-size: 13px; line-height: 22px; color: #222; }
-h1 { font-size: 20px; font-weight: normal; text-align: center; }
h3 { color: #7D4698; position: relative }
a { color: #7D4698; text-decoration: none; font-weight: bold; }
-ul { list-style: none; padding: 0; margin: 0; }
-p { margin: 0; padding: 0; }
+p { margin: 0; padding: 10px; }
a[name] { padding: 0; margin: 0; }
.box { max-width: 850px; width: 100%; margin: 0 auto 30px auto;
padding-bottom: 30px; background: white; border: 1px solid #eee; }
diff --git a/web/index.html b/web/index.html
index 3de47bc..b6b0519 100644
--- a/web/index.html
+++ b/web/index.html
@@ -9,1990 +9,116 @@
<body>
<div class="box">
-<h3>Onionoo protocol overview</h3>
- <h4>Table of contents</h4>
- <ul>
- <li><a href="#general">General</a></li>
- <li><a href="#methods">Methods</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>
- </ul>
-
-</div>
-<div class="box">
-
-<a name="general"></a>
-<h3>General <a href="#general">#</a></h3>
-
-<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>
-
-<h4>Compression</h4>
-<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>
-
-<h4>Caching</h4>
-<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>
-
-<h4>Response codes</h4>
-<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 could not be processed either
-because the requested resource could not be found or because of bad
-syntax.
-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>
-
-<h4>Protocol changes</h4>
-<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 in
-<strong><font color="red">red</font></strong> and new parts in
-<strong><font color="blue">blue</font></strong>.
-Deprecated parts will be removed one month after their announcement.
-Let us <a href="mailto:tor-dev at lists.torproject.org">know</a> that you're
-developing a client, and we're going to inform you of upcoming protocol
-changes.
-</p>
-
-<p>The Onionoo API is described by resource types and available methods
-below.</p>
-
-</div> <!-- box -->
-
-<div class="box">
-
-<a name="methods"></a>
-<h3>Methods <a href="#methods">#</a></h3>
-
-<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>
-
-<ul class="api-urls">
-
-<li class="api-request">
-<span class="request-type">GET</span>
-<span class="request-url">https://onionoo.torproject.org/summary</span>
-<span class="request-response">returns a <a href="#summary">summary
-document</a></span>
-</li>
-
-<li class="api-request">
-<span class="request-type">GET</span>
-<span class="request-url">https://onionoo.torproject.org/details</span>
-<span class="request-response">returns a <a href="#details">details
-document</a></span>
-</li>
-
-<li class="api-request">
-<span class="request-type">GET</span>
-<span class="request-url">https://onionoo.torproject.org/bandwidth</span>
-<span class="request-response">returns a <a href="#bandwidth">bandwidth
-document</a></span>
-</li>
-
-<li class="api-request">
-<span class="request-type">GET</span>
-<span class="request-url">https://onionoo.torproject.org/weights</span>
-<span class="request-response">returns a <a href="#weights">weights
-document</a></span>
-</li>
-
-<li class="api-request">
-<span class="request-type">GET</span>
-<span class="request-url">https://onionoo.torproject.org/clients</span>
-<span class="request-response">returns a <a href="#clients">clients
-document</a></span>
-</li>
-
-<li class="api-request">
-<span class="request-type">GET</span>
-<span class="request-url">https://onionoo.torproject.org/uptime</span>
-<span class="request-response">returns a <a href="#uptime">uptime
-document</a></span>
-</li>
-
-</ul>
-
-<h4>Parameters</h4>
-<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 relays with the parameter value
-matching (part of a) nickname, (possibly $-prefixed) beginning of a
-fingerprint, or beginning of an IP address, and bridges with (part of a)
-nickname or (possibly $-prefixed) beginning of a hashed fingerprint.
-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.
-If multiple search terms are given, separated by spaces, the intersection
-of all relays and bridges matching all search terms will be returned.
-Full 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.
-</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>
-
-</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>.
-Field names are case-insensitive.
-Ascending order is the default; descending order is selected by prepending
-fields with a minus sign (<strong>-</strong>).
-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>
-
-</div> <!-- box -->
-
-<div class="box">
-<a name="summary"></a>
-<h3>Summary documents <a href="#summary">#</a>
-<span class="request-response">
-<a href="summary?limit=4">example request</a>
-</span>
-</h3>
-
-<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.
-Summary documents contain the following fields:</p>
-
-<ul class="properties">
-
-<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 summaries in this document are.
-</p>
-</li>
-
-<li>
-<b>relays</b>
-<code class="typeof">array of objects</code>
-<span class="required-true">required</span>
-<p>
-Array of relay summary objects as specified below.
-</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 summaries in this document are.
-</p>
-</li>
-
-<li>
-<b>bridges</b>
-<code class="typeof">array of objects</code>
-<span class="required-true">required</span>
-<p>
-Array of bridge summary objects as specified below.
-</p>
-</li>
-
-</ul>
-
-<h4>Relay summary objects</h4>
-
-<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>
-
-<h4>Bridge summary objects</h4>
-
-<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>
-
-</div> <!-- box -->
-
-<div class="box">
-<a name="details"></a>
-<h3>Details documents <a href="#details">#</a>
-<span class="request-response">
-<a href="details?limit=4">example request</a>
-</span>
-</h3>
-
-<p>
-Details documents are based on the network statuses published by the Tor
-directories and the server descriptors published by relays and bridges.
-Details documents contain the following fields:
-</p>
-
-<ul class="properties">
-
-<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 details in this document are.
-</p>
-</li>
-
-<li>
-<b>relays</b>
-<code class="typeof">array of objects</code>
-<span class="required-true">required</span>
-<p>
-Array of relay details objects as specified below.
-</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 details in this document are.
-</p>
-</li>
-
-<li>
-<b>bridges</b>
-<code class="typeof">array of objects</code>
-<span class="required-true">required</span>
-<p>
-Array of bridge details objects as specified below.
-</p>
-
-</li>
-
-</ul>
-
-<h4>Relay details objects</h4>
-
-<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.
-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">number</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.
-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.
-</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.
-</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.
-</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>family</b>
-<code class="typeof">array of strings</code>
-<span class="required-false">optional</span>
-<p>
-Array of fingerprints or nicknames of relays in the
-same family as this relay.
-Omitted if empty or if descriptor containing this information cannot be
-found.
-</p>
-</li>
-
-<li>
-<b>advertised_bandwidth_fraction</b>
-<code class="typeof">number</code>
-<span class="required-false">optional</span>
-<p>
-Relative advertised bandwidth of this relay compared to the total
-advertised bandwidth in the network.
-If there were no bandwidth authorities, this fraction would be a very
-rough approximation of the probability of this relay to be selected by
-clients.
-Omitted if the relay is not running, or router 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>
-
-</ul>
-
-<h4>Bridge details objects</h4>
-
-<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.
-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>pool_assignment</b>
-<code class="typeof">string</code>
-<span class="required-false">optional</span>
-<p>
-Information of the pool that BridgeDB
-assigned this bridge to, including further assignment information if
-available.
-</p>
-</li>
-
-</ul>
-
-</div> <!-- box -->
-
-<div class="box">
-<a name="history"></a>
-<h3>History objects <a href="#history">#</a></h3>
-
-<p>
-History objects are no documents by themselves, but are contained in
-subsequent documents.
-<p>
-
-<h4>Graph history objects</h4>
-
-<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>
-
-</div> <!-- box -->
-
-<div class="box">
-<a name="bandwidth"></a>
-<h3>Bandwidth documents <a href="#bandwidth">#</a>
-<span class="request-response">
-<a href="bandwidth?limit=4">example request</a>
-</span>
-</h3>
-
-<p>
-Bandwidth documents contain aggregate statistics of a relay's or
-bridge's consumed bandwidth for different time intervals.
-Bandwidth documents contain the following fields:
-</p>
-
-<ul class="properties">
-
-<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 bandwidth documents in this document are.
-</p>
-</li>
-
-<li>
-<b>relays</b>
-<code class="typeof">array of objects</code>
-<span class="required-true">required</span>
-<p>
-Array of relay bandwidth objects as specified below.
-</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 bandwidth documents in this document are.
-</p>
-</li>
-
-<li>
-<b>bridges</b>
-<code class="typeof">array of objects</code>
-<span class="required-true">required</span>
-<p>
-Array of bridge bandwidth objects as specified below.
-</p>
-</li>
-
-</ul>
-
-<h4>Relay bandwidth objects</h4>
-
-<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.
-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>
-
-<h4>Bridge bandwidth objects</h4>
-
-<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>
-
-</div> <!-- box -->
-
-<div class="box">
-<a name="weights"></a>
-<h3>Weights documents <a href="#weights">#</a>
-<span class="request-response">
-<a href="weights?limit=4">example request</a>
-</span>
-</h3>
-
-<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.
-Weights documents contain the following fields:
-</p>
-
-<ul class="properties">
-
-<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 weights documents in this document are.
-</p>
-</li>
-
-<li>
-<b>relays</b>
-<code class="typeof">array of objects</code>
-<span class="required-true">required</span>
-<p>
-Array of relay weights objects as specified below.
-</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.
-Only included for compatibility reasons with the other document types.
-</p>
-</li>
-
-<li>
-<b>bridges</b>
-<code class="typeof">array of objects</code>
-<span class="required-true">required</span>
-<p>
-Empty array of objects that would represent bridge weights documents.
-Only included for compatibility reasons with the other document types.
-</p>
-</li>
-
-</ul>
-
-<h4>Relay weights objects</h4>
-
-<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>advertised_bandwidth_fraction</b>
-<code class="typeof">object</code>
-<span class="required-false">optional</span>
-<p>
-Object containing graph history objects with relative advertised bandwidth
-of this relay compared to the total advertised bandwidth in the network.
-If there were no bandwidth authorities, this fraction would be 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>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.
-The specification of this history object is similar to that in the
-<strong>advertised_bandwidth_fraction</strong> field above.
-</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>advertised_bandwidth_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>advertised_bandwidth_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>advertised_bandwidth_fraction</strong> field above.
-</p>
-</li>
-
-</ul>
-
-</div> <!-- box -->
-
-<div class="box">
-<a name="clients"></a>
-<h3>Clients documents <a href="#clients">#</a>
-<span class="request-response">
-<a href="clients?limit=4">example request</a>
-</span>
-</h3>
-
-<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.
-Clients documents contain the following fields:
-</p>
-
-<ul class="properties">
-
-<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.
-Only included for compatibility reasons with the other document types.
-</p>
-</li>
-
-<li>
-<b>relays</b>
-<code class="typeof">array of objects</code>
-<span class="required-true">required</span>
-<p>
-Empty array of objects that would represent relay clients documents.
-Only included for compatibility reasons with the other document types.
-</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 clients documents in this document are.
-</p>
-</li>
-
-<li>
-<b>bridges</b>
-<code class="typeof">array of objects</code>
-<span class="required-true">required</span>
-<p>
-Array of bridge clients objects as specified below.
-</p>
-
-</li>
-
-</ul>
-
-<h4>Bridge clients objects</h4>
-
-<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</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.
-<font color="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.</font>
-</p>
-</li>
-
-<li>
-<b>transports</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.
-<font color="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.</font>
-</p>
-</li>
-
-<li>
-<b>versions</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.
-<font color="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.</font>
-</p>
-</li>
-
-</ul>
-
-</li>
-
-</ul>
-
-</div> <!-- box -->
-
-<div class="box">
-<a name="uptime"></a>
-<h3>Uptime documents <a href="#uptime">#</a>
-<span class="request-response">
-<a href="uptime?limit=4">example request</a>
-</span>
-</h3>
-
-<p>
-Uptime documents contain fractional uptimes of relays and bridges.
-Uptime documents contain different time intervals and are available for
-relays and bridges.
-Uptime documents contain the following fields:
-</p>
-
-<ul class="properties">
-
-<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 uptime documents in this document are.
-</p>
-</li>
-
-<li>
-<b>relays</b>
-<code class="typeof">array of objects</code>
-<span class="required-true">required</span>
-<p>
-Array of relay uptime objects as specified below.
-</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 uptime documents in this document are.
-</p>
-</li>
-
-<li>
-<b>bridges</b>
-<code class="typeof">array of objects</code>
-<span class="required-true">required</span>
-<p>
-Array of bridge uptime objects as specified below.
-</p>
-</li>
-
-</ul>
-
-<h4>Relay uptime objects</h4>
-
-<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>
-
-</ul>
-
-<h4>Bridge uptime objects</h4>
-
-<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>
+<h1><a href="index.html">Onionoo</a> —</h1>
+<h2>a Tor network status <a href="protocol.html">protocol</a></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. The following Onionoo clients
+are currently available:</p>
+<ul>
+<li><a href="https://atlas.torproject.org/">Atlas</a> is a web
+application to discover Tor relays. It provides useful
+information on how relays are configured along with graphics about
+their past.</li>
+<li><a href="https://compass.torproject.org/">Compass</a>
+is a Python script and website that extracts consensus weight
+information of currently running relays and aggregates weights of
+relays running in the same country or same autonomous system.</li>
+<li><a href="http://tor2web.org/">Tor2web</a> is a web proxy to Tor
+Hidden Services. It uses Onionoo to get the list of currently running
+Tor Exits to detect if the client is a Tor user and if so redirect
+them to the .onion address.</li>
+<li><a href="https://globe.torproject.org/">Globe</a> is a web
+application
+that allows you to search for Tor relays and bridges. It gives you a
+detailed overview of properties and configurations of a relay or
+bridge.</li>
+<li>The <a href="https://nos-oignons.net/Services/index.en.html">Nos
+oignons</a> website uses Onionoo to visualize bandwidth histories of
+their relays.</li>
+<li>The <a href="https://metrics.torproject.org/bubbles.html">metrics
+website</a> visualizes diversity of the Tor network using bubble
+graphs.</li>
+</ul>
+
+<p>The following Onionoo clients are currently unmaintained, but are
+still a good idea:</p>
+<ul>
+<li><a href="https://code.google.com/p/moniono/">mOnionO</a> is an
+Android app that lets you add your relays or bridges to your favorites
+list and keeps you always informed whether they are running or
+not.</li>
+</ul>
+
+<h2>Developing Onionoo applications</h2>
+
+<p>The project pages of the Onionoo clients listed above have further
+information for contacting the authors and contributing ideas or code.
+The authors will be happy to hear your thoughts!</p>
+
+<p>You don't find your favorite Onionoo client above? Want to
+implement your own and tell us to add it to the list? The Onionoo
+clients above are backed by a web-based
+<a href="protocol.html">protocol</a>, which
+facilitates developing new applications displaying Tor status
+information. Here are a few ideas for new Onionoo clients:</p>
+<ul>
+<li>Tor controller extension: Extend
+<a href="https://www.torproject.org/projects/vidalia.html.en">Vidalia</a> and/or
+<a href="https://www.torproject.org/projects/arm.html.en">arm</a> to look up details for the bridge
+that the user is running and display what pool the bridge is contained
+in.</li>
+<li>Social network site plugin: Add a plugin to the social network
+site of your choice to show your friends what Tor relays and bridges
+you're running and how that helps users around the world.</li>
+<li>Desktop tray icon: Write a tray icon for your favorite desktop
+environment that tells you when your relay or bridge is down and that
+displays some basic usage statistics.</li>
+<li>E-mail notification service: Improve our e-mail notification
+service <a href="https://weather.torproject.org/">Weather</a> by
+implementing its own relay search or extending it to report when a
+bridge drops off the network.</li>
+<li>Command-line tool: Implement a command-line tool that quickly
+searches a relay or bridge and prints out some status information to
+help debug problems.</li>
+<li>(Insert your idea here.)</li>
+</ul>
+
+<p>Want to help with developing the Onionoo server that provides
+Tor status data, or want to run your own Onionoo server instance? The
+Onionoo server is written in Java with a tiny portion of Java
+Servlets. Instructions for setting up the Onionoo server to fetch the
+required data from the Tor servers is described in the INSTALL file in
+the sources. For more details see the
+<a href="https://gitweb.torproject.org/onionoo.git">source code</a> and
+<a href="https://trac.torproject.org/projects/tor/query?status=!closed&component=Onionoo">issue
+tracker</a>.</p>
+
+<h2>Related projects</h2>
+
+<p>TorStatus is the name of a nowadays
+<a href="https://svn.torproject.org/svn/torstatus/trunk/">unmaintained</a>
+website that displays Tor relay information similar to
+<a href="http://atlas.torproject.org/">Atlas</a>. There are still a
+few <a href="http://torstatus.blutmagie.de/">TorStatus</a>
+<a href="https://torstatus.rueckgr.at/">websites</a>
+<a href="http://tns.hermetix.org/">running</a>.</p>
+
+<p>There's another project from summer 2011 called TorStatus which is
+a <a href="https://gitweb.torproject.org/torstatus.git">rewrite</a> of
+the original TorStatus in Python/Django. Unfortunately, it's also
+unmaintained.</p>
+
+<p>Finally, there's the
+<a href="https://consensus-health.torproject.org/">consensus-health
+page</a> which has the primary purpose of indicating problems with
+creating a network status consensus. As a side-effect this page lists
+all currently running relays and how the directory authorities voted
+on them.</p>
</div> <!-- box -->
diff --git a/web/protocol.html b/web/protocol.html
new file mode 100644
index 0000000..9972f4c
--- /dev/null
+++ b/web/protocol.html
@@ -0,0 +1,2003 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<title>Onionoo — protocol overview</title>
+<link href="css/style.css" type="text/css" rel="stylesheet">
+<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
+<link href="favicon.ico" type="image/x-icon" rel="shortcut icon">
+</head>
+<body>
+
+<div class="box">
+
+<h1><a href="index.html">Onionoo</a> —</h1>
+<h2>protocol overview</h2>
+
+ <h4>Table of contents</h4>
+ <ul>
+ <li><a href="#general">General</a></li>
+ <li><a href="#methods">Methods</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>
+ </ul>
+
+</div>
+<div class="box">
+
+<a name="general"></a>
+<h3>General <a href="#general">#</a></h3>
+
+<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>
+
+<h4>Compression</h4>
+<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>
+
+<h4>Caching</h4>
+<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>
+
+<h4>Response codes</h4>
+<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 could not be processed either
+because the requested resource could not be found or because of bad
+syntax.
+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>
+
+<h4>Protocol changes</h4>
+<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 in
+<strong><font color="red">red</font></strong> and new parts in
+<strong><font color="blue">blue</font></strong>.
+Deprecated parts will be removed one month after their announcement.
+Let us <a href="mailto:tor-dev at lists.torproject.org">know</a> that you're
+developing a client, and we're going to inform you of upcoming protocol
+changes.
+</p>
+
+<p>The Onionoo API is described by resource types and available methods
+below.</p>
+
+</div> <!-- box -->
+
+<div class="box">
+
+<a name="methods"></a>
+<h3>Methods <a href="#methods">#</a></h3>
+
+<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>
+
+<ul class="api-urls">
+
+<li class="api-request">
+<span class="request-type">GET</span>
+<span class="request-url">https://onionoo.torproject.org/summary</span>
+<span class="request-response">returns a <a href="#summary">summary
+document</a></span>
+</li>
+
+<li class="api-request">
+<span class="request-type">GET</span>
+<span class="request-url">https://onionoo.torproject.org/details</span>
+<span class="request-response">returns a <a href="#details">details
+document</a></span>
+</li>
+
+<li class="api-request">
+<span class="request-type">GET</span>
+<span class="request-url">https://onionoo.torproject.org/bandwidth</span>
+<span class="request-response">returns a <a href="#bandwidth">bandwidth
+document</a></span>
+</li>
+
+<li class="api-request">
+<span class="request-type">GET</span>
+<span class="request-url">https://onionoo.torproject.org/weights</span>
+<span class="request-response">returns a <a href="#weights">weights
+document</a></span>
+</li>
+
+<li class="api-request">
+<span class="request-type">GET</span>
+<span class="request-url">https://onionoo.torproject.org/clients</span>
+<span class="request-response">returns a <a href="#clients">clients
+document</a></span>
+</li>
+
+<li class="api-request">
+<span class="request-type">GET</span>
+<span class="request-url">https://onionoo.torproject.org/uptime</span>
+<span class="request-response">returns a <a href="#uptime">uptime
+document</a></span>
+</li>
+
+</ul>
+
+<h4>Parameters</h4>
+<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 relays with the parameter value
+matching (part of a) nickname, (possibly $-prefixed) beginning of a
+fingerprint, or beginning of an IP address, and bridges with (part of a)
+nickname or (possibly $-prefixed) beginning of a hashed fingerprint.
+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.
+If multiple search terms are given, separated by spaces, the intersection
+of all relays and bridges matching all search terms will be returned.
+Full 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.
+</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>
+
+</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>.
+Field names are case-insensitive.
+Ascending order is the default; descending order is selected by prepending
+fields with a minus sign (<strong>-</strong>).
+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>
+
+</div> <!-- box -->
+
+<div class="box">
+<a name="summary"></a>
+<h3>Summary documents <a href="#summary">#</a>
+<span class="request-response">
+<a href="summary?limit=4">example request</a>
+</span>
+</h3>
+
+<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.
+Summary documents contain the following fields:</p>
+
+<ul class="properties">
+
+<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 summaries in this document are.
+</p>
+</li>
+
+<li>
+<b>relays</b>
+<code class="typeof">array of objects</code>
+<span class="required-true">required</span>
+<p>
+Array of relay summary objects as specified below.
+</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 summaries in this document are.
+</p>
+</li>
+
+<li>
+<b>bridges</b>
+<code class="typeof">array of objects</code>
+<span class="required-true">required</span>
+<p>
+Array of bridge summary objects as specified below.
+</p>
+</li>
+
+</ul>
+
+<h4>Relay summary objects</h4>
+
+<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>
+
+<h4>Bridge summary objects</h4>
+
+<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>
+
+</div> <!-- box -->
+
+<div class="box">
+<a name="details"></a>
+<h3>Details documents <a href="#details">#</a>
+<span class="request-response">
+<a href="details?limit=4">example request</a>
+</span>
+</h3>
+
+<p>
+Details documents are based on the network statuses published by the Tor
+directories and the server descriptors published by relays and bridges.
+Details documents contain the following fields:
+</p>
+
+<ul class="properties">
+
+<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 details in this document are.
+</p>
+</li>
+
+<li>
+<b>relays</b>
+<code class="typeof">array of objects</code>
+<span class="required-true">required</span>
+<p>
+Array of relay details objects as specified below.
+</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 details in this document are.
+</p>
+</li>
+
+<li>
+<b>bridges</b>
+<code class="typeof">array of objects</code>
+<span class="required-true">required</span>
+<p>
+Array of bridge details objects as specified below.
+</p>
+
+</li>
+
+</ul>
+
+<h4>Relay details objects</h4>
+
+<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.
+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">number</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.
+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.
+</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.
+</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.
+</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>family</b>
+<code class="typeof">array of strings</code>
+<span class="required-false">optional</span>
+<p>
+Array of fingerprints or nicknames of relays in the
+same family as this relay.
+Omitted if empty or if descriptor containing this information cannot be
+found.
+</p>
+</li>
+
+<li>
+<b>advertised_bandwidth_fraction</b>
+<code class="typeof">number</code>
+<span class="required-false">optional</span>
+<p>
+Relative advertised bandwidth of this relay compared to the total
+advertised bandwidth in the network.
+If there were no bandwidth authorities, this fraction would be a very
+rough approximation of the probability of this relay to be selected by
+clients.
+Omitted if the relay is not running, or router 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>
+
+</ul>
+
+<h4>Bridge details objects</h4>
+
+<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.
+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>pool_assignment</b>
+<code class="typeof">string</code>
+<span class="required-false">optional</span>
+<p>
+Information of the pool that BridgeDB
+assigned this bridge to, including further assignment information if
+available.
+</p>
+</li>
+
+</ul>
+
+</div> <!-- box -->
+
+<div class="box">
+<a name="history"></a>
+<h3>History objects <a href="#history">#</a></h3>
+
+<p>
+History objects are no documents by themselves, but are contained in
+subsequent documents.
+<p>
+
+<h4>Graph history objects</h4>
+
+<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>
+
+</div> <!-- box -->
+
+<div class="box">
+<a name="bandwidth"></a>
+<h3>Bandwidth documents <a href="#bandwidth">#</a>
+<span class="request-response">
+<a href="bandwidth?limit=4">example request</a>
+</span>
+</h3>
+
+<p>
+Bandwidth documents contain aggregate statistics of a relay's or
+bridge's consumed bandwidth for different time intervals.
+Bandwidth documents contain the following fields:
+</p>
+
+<ul class="properties">
+
+<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 bandwidth documents in this document are.
+</p>
+</li>
+
+<li>
+<b>relays</b>
+<code class="typeof">array of objects</code>
+<span class="required-true">required</span>
+<p>
+Array of relay bandwidth objects as specified below.
+</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 bandwidth documents in this document are.
+</p>
+</li>
+
+<li>
+<b>bridges</b>
+<code class="typeof">array of objects</code>
+<span class="required-true">required</span>
+<p>
+Array of bridge bandwidth objects as specified below.
+</p>
+</li>
+
+</ul>
+
+<h4>Relay bandwidth objects</h4>
+
+<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.
+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>
+
+<h4>Bridge bandwidth objects</h4>
+
+<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>
+
+</div> <!-- box -->
+
+<div class="box">
+<a name="weights"></a>
+<h3>Weights documents <a href="#weights">#</a>
+<span class="request-response">
+<a href="weights?limit=4">example request</a>
+</span>
+</h3>
+
+<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.
+Weights documents contain the following fields:
+</p>
+
+<ul class="properties">
+
+<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 weights documents in this document are.
+</p>
+</li>
+
+<li>
+<b>relays</b>
+<code class="typeof">array of objects</code>
+<span class="required-true">required</span>
+<p>
+Array of relay weights objects as specified below.
+</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.
+Only included for compatibility reasons with the other document types.
+</p>
+</li>
+
+<li>
+<b>bridges</b>
+<code class="typeof">array of objects</code>
+<span class="required-true">required</span>
+<p>
+Empty array of objects that would represent bridge weights documents.
+Only included for compatibility reasons with the other document types.
+</p>
+</li>
+
+</ul>
+
+<h4>Relay weights objects</h4>
+
+<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>advertised_bandwidth_fraction</b>
+<code class="typeof">object</code>
+<span class="required-false">optional</span>
+<p>
+Object containing graph history objects with relative advertised bandwidth
+of this relay compared to the total advertised bandwidth in the network.
+If there were no bandwidth authorities, this fraction would be 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>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.
+The specification of this history object is similar to that in the
+<strong>advertised_bandwidth_fraction</strong> field above.
+</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>advertised_bandwidth_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>advertised_bandwidth_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>advertised_bandwidth_fraction</strong> field above.
+</p>
+</li>
+
+</ul>
+
+</div> <!-- box -->
+
+<div class="box">
+<a name="clients"></a>
+<h3>Clients documents <a href="#clients">#</a>
+<span class="request-response">
+<a href="clients?limit=4">example request</a>
+</span>
+</h3>
+
+<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.
+Clients documents contain the following fields:
+</p>
+
+<ul class="properties">
+
+<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.
+Only included for compatibility reasons with the other document types.
+</p>
+</li>
+
+<li>
+<b>relays</b>
+<code class="typeof">array of objects</code>
+<span class="required-true">required</span>
+<p>
+Empty array of objects that would represent relay clients documents.
+Only included for compatibility reasons with the other document types.
+</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 clients documents in this document are.
+</p>
+</li>
+
+<li>
+<b>bridges</b>
+<code class="typeof">array of objects</code>
+<span class="required-true">required</span>
+<p>
+Array of bridge clients objects as specified below.
+</p>
+
+</li>
+
+</ul>
+
+<h4>Bridge clients objects</h4>
+
+<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</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.
+<font color="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.</font>
+</p>
+</li>
+
+<li>
+<b>transports</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.
+<font color="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.</font>
+</p>
+</li>
+
+<li>
+<b>versions</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.
+<font color="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.</font>
+</p>
+</li>
+
+</ul>
+
+</li>
+
+</ul>
+
+</div> <!-- box -->
+
+<div class="box">
+<a name="uptime"></a>
+<h3>Uptime documents <a href="#uptime">#</a>
+<span class="request-response">
+<a href="uptime?limit=4">example request</a>
+</span>
+</h3>
+
+<p>
+Uptime documents contain fractional uptimes of relays and bridges.
+Uptime documents contain different time intervals and are available for
+relays and bridges.
+Uptime documents contain the following fields:
+</p>
+
+<ul class="properties">
+
+<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 uptime documents in this document are.
+</p>
+</li>
+
+<li>
+<b>relays</b>
+<code class="typeof">array of objects</code>
+<span class="required-true">required</span>
+<p>
+Array of relay uptime objects as specified below.
+</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 uptime documents in this document are.
+</p>
+</li>
+
+<li>
+<b>bridges</b>
+<code class="typeof">array of objects</code>
+<span class="required-true">required</span>
+<p>
+Array of bridge uptime objects as specified below.
+</p>
+</li>
+
+</ul>
+
+<h4>Relay uptime objects</h4>
+
+<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>
+
+</ul>
+
+<h4>Bridge uptime objects</h4>
+
+<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>
+
+</div> <!-- box -->
+
+</body>
+</html>
+
More information about the tor-commits
mailing list