{% extends "base.html" %}
{% from 'macros.html' import fmt_int, fmt_float %}

{% block api_active %}
active
{% endblock %}

{% block content %}

<div class="column-group">
  <div class="xlarge-75 large-75 small-100 bottom-space" style="padding-right:1em">
    <h1 style="margin-top: 0px; margin-bottom:1em">
      JSON API
    </h1>
    <p>This site offers a
      simple <a href="https://en.wikipedia.org/wiki/JSON">JSON</a> <a href="https://en.wikipedia.org/wiki/Application_programming_interface">API</a>
      to make it easier to write programs that interact with it.
    </p>

    <div class="ink-alert block info" role="alert">
      <h4 style="font-size: larger">Listing network entries</h4>
      <p>A list of networks can be obtained via the <span class="code"><a href="/api/nets">/api/nets</a></span> URL.
        By the default, only the list of names is retrieved.</p>
      <p>If you pass the
        option <span class="code"><a href="/api/nets?full=True">/api/nets?full=True</a></span>,
        then a dictionary with all properties for each network is
        retrieved, instead of only a list.
      </p>
      <p>You can restrict the output to a set of tags by passing
        them as arguments,
        e.g. <span class="code"><a href="/api/nets?tags=Social,Offline">/api/nets?tags=Social,Offline</a></span>.
      </p>
    </div>

    <div class="ink-alert block info" role="alert">
      <h4 style="font-size: larger">Information on single network entries</h4>
      <p>
        A dictionary with information on a particular network can be
        obtained via the
        URL <span class="code"><a href="/api/net/&lt;name&gt;">/api/net/&lt;name&gt;</a></span>,
        where <span class="code">&lt;name&gt;</span> is the network entry. For examle:
        <span class="code"><a href="/api/net/advogato">/api/net/advogato</a></span>.
      </p>
    </div>

    <div class="ink-alert block info" role="alert">
      <h4 style="font-size: larger">Downloading files</h4>
      <p>
        All network files have a predictable URL pattern in the
        form <span class="code">/net/&lt;name&gt;/files/&lt;net&gt;.gt.zst</span>,
        where <span class="code">&lt;name&gt;</span> is the network
        entry, and <span class="code">&lt;net&gt;</span> is the
        particular sub-network in the entry (in case there is a single one,
        then <span class="code">&lt;net&gt;</span> is the same
        as <span class="code">&lt;name&gt;</span>).  For
        examle: <span class="code"><a href="/net/advogato/files/advogato.gt.zst">/net/advogato/files/advogato.gt.zst</a></span>.
      </p>
    </div>

    <div class="ink-alert block info" role="alert">
      <h4 style="font-size: larger">Access from <a href="//graph-tool.skewed.de">graph-tool</a></h4>
      <p>
        This API can also be accessed conveniently from
        the <a href="//graph-tool.skewed.de">graph-tool</a> library.
      </p>
      <p>A dictionary corresponding to a particular dataset is obtained via:
{% highlight 'python' %}
import graph_tool.all as gt
gt.collection.ns_info["advogato"]
{% endhighlight %}
      <p>Individual networks can be downloaded via:
{% highlight 'python' %}
g = gt.collection.ns["advogato"]
{% endhighlight %}</p>
      <p>For datasets with multiple networks, the dictionary accepts either a slash separator or a tuple:
{% highlight 'python' %}
g = gt.collection.ns["fresh_webs/AkatoreA"]

# or equivalently:
g = gt.collection.ns[("fresh_webs", "AkatoreA")]
{% endhighlight %}</p>
      
    </div>

  </div>
</div>

{% endblock %}