commit 39c7f613313d4eaaa54d34b5f4128b4fcb478111 Author: Karsten Loesing karsten.loesing@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@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@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> +