<commit_before>{% extends 'base.html' %}
{% block title %}Simple Libravatar API{% endblock title %}

{% block content %}

<h2>Simple API</h2>

<p>You should probably just use one of the available <a href="{% url libravatar.public.views.libraries %}">libraries or plugins</a>, but here is a description of the API.</p>

<p>There are 5 steps for displaying Libravatar-hosted images into your application:</p>

<ol>
<li>Take a user's email address as entered by them.</li>
<li>Convert the email address to lowercase.</li>
<li>Compute the hash (using the MD5, SHA1 or SHA256 hash algorithms).</li>
<li>Turn the image into a URL by prefixing it with the base URL <tt>http://cdn.libravatar.org/avatar/</tt>.</li>
<li>Put the image into an <tt>img</tt> tag on your page.</li>
</ol>

<p>Here's an example in Python:</p>

<blockquote><pre>import hashlib
email = '<EMAIL>'
hash = hashlib.md5(email.lower()).hexdigest()</pre></blockquote>

<p>which gives us a hash of <tt>40f8d096a3777232204cb3f796c577b7</tt> and therefore the following image tag:</p>

<p><img height="80" width="80" src="http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7"></p>

<h2>Picture size</h2>

<p>The default size for images is <b>80x80</b>, however you can change it by providing an extra parameter to the URL:</p>

<blockquote><code>http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=100</code></blockquote>

<p>The <tt>s</tt> or <tt>size</tt> is the size (height and width are the same) of the image in pixel. Acceptable values range from <b>1</b> to <b>512</b>.</p>

<h2>Default URL for missing images</h2>

<p>If you would like to specify a default "missing image" picture for email addresses which are not found in the Libravatar database, you may specify the URL of an image to redirect to:</p>

<blockquote><code>http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?d=http://example.com/nobody.jpg</code></blockquote>

<p>The <tt>d</tt> or <tt>default</tt> parameter defaults to the Libravatar logo, but a few other special values are available:</p>

<ul>
<li><tt><b>404</b></tt>: return a 404 error (file not found) instead of an image</li>
<li class="centered"><table summary=""><tr>
  <td><img height="80" width="80" src="http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=80&d=mm">
  <br><tt><b>mm</b></tt></td>
  <td><img height="80" width="80" src="http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=80&d=identicon">
  <br><tt><b>identicon</b></tt></td>
  <td><img height="80" width="80" src="http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=80&d=monsterid">
  <br><tt><b>monsterid</b></tt></td>
  <td><img height="80" width="80" src="http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=80&d=wavatar">
  <br><tt><b>wavatar</b></tt></td>
  <td><img height="80" width="80" src="http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=80&d=retro">
  <br><tt><b>retro</b></tt></td>
</tr></table></li>
</ul>

<p>Note that if an image is not found in the Libravatar database and the hash algorithm used was <b>MD5</b>, then Libravatar will first redirect to Gravatar in case the image exists there. Then it will honour the <tt>default</tt> parameter.</p>

<h2>For Gravatar users</h2>

<p>As you can see, our API is heavily based on the <a href="http://en.gravatar.com/site/implement/">Gravatar API</a>. If your application or website already supports <a href="http://www.gravatar.com">Gravatar</a>, switching to the basic Libravatar service is just a matter or changing the base URL:</p>

<blockquote><code>http://www.gravatar.com/avatar => http://cdn.libravatar.org/avatar</code></blockquote>

<p>or if you are using the HTTPS version of the service:</p>

<blockquote><code>https://secure.gravatar.com/avatar => https://seccdn.libravatar.org/avatar</code></blockquote>

<p>Note that Libravatar does <b>not</b> support the <tt>rating</tt> (or simply <tt>r</tt>) parameter since we require all images to be G-rated.</p>

<h2>Federated servers</h2>

<p>In order to support domain name owners who choose to <a href="{% url libravatar.public.views.run_your_own %}">run their own instances</a> of Libravatar, you should perform a DNS query to lookup the appropriate base URL for each domain.</p>

<p>You will probably want to use an <a href="{% url libravatar.public.views.libraries %}">existing library</a> for this, but here's how to do that DNS lookup on a UNIX command line:</p>

<pre>$ dig SRV _avatars._tcp.example.com

; <<>> DiG 9.7.2-P3 <<>> SRV _avatars._tcp.example.com
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 14684
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;_avatars._tcp.example.com.	IN	SRV

;; ANSWER SECTION:
<b>_avatars._tcp.example.com. 86400 IN	SRV 0 0 80 avatars.example.com.</b></pre>

<p>We also provide a <a href="{% url libravatar.tools.views.check_domain %}">domain check tool</a> to help in your testing.</p>

<h2>HTTPS support</h2>

<p>If your application is delivered over a secure (HTTPS) connection, you may want to use our HTTPS image servers to avoid triggering browser warnings about mixed HTTP/HTTPS content.</p>

<p>To do so, simply use this base URL:</p>

<blockquote><code>https://seccdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7</code></blockquote>

<p>When looking up the base URL to use via DNS, replace <tt>_avatars._tcp.example.com</tt> with:</p>

<blockquote><code>_avatars-sec._tcp.example.com</code></blockquote>

<h2>Testing tool</h2><commit_msg>api: note that SRV priorities are ignored but weights are honoured<commit_after>{% extends 'base.html' %}
{% block title %}Simple Libravatar API{% endblock title %}

{% block content %}

<h2>Simple API</h2>

<p>You should probably just use one of the available <a href="{% url libravatar.public.views.libraries %}">libraries or plugins</a>, but here is a description of the API.</p>

<p>There are 5 steps for displaying Libravatar-hosted images into your application:</p>

<ol>
<li>Take a user's email address as entered by them.</li>
<li>Convert the email address to lowercase.</li>
<li>Compute the hash (using the MD5, SHA1 or SHA256 hash algorithms).</li>
<li>Turn the image into a URL by prefixing it with the base URL <tt>http://cdn.libravatar.org/avatar/</tt>.</li>
<li>Put the image into an <tt>img</tt> tag on your page.</li>
</ol>

<p>Here's an example in Python:</p>

<blockquote><pre>import hashlib
email = '<EMAIL>'
hash = hashlib.md5(email.lower()).hexdigest()</pre></blockquote>

<p>which gives us a hash of <tt>40f8d096a3777232204cb3f796c577b7</tt> and therefore the following image tag:</p>

<p><img height="80" width="80" src="http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7"></p>

<h2>Picture size</h2>

<p>The default size for images is <b>80x80</b>, however you can change it by providing an extra parameter to the URL:</p>

<blockquote><code>http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=100</code></blockquote>

<p>The <tt>s</tt> or <tt>size</tt> is the size (height and width are the same) of the image in pixel. Acceptable values range from <b>1</b> to <b>512</b>.</p>

<h2>Default URL for missing images</h2>

<p>If you would like to specify a default "missing image" picture for email addresses which are not found in the Libravatar database, you may specify the URL of an image to redirect to:</p>

<blockquote><code>http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?d=http://example.com/nobody.jpg</code></blockquote>

<p>The <tt>d</tt> or <tt>default</tt> parameter defaults to the Libravatar logo, but a few other special values are available:</p>

<ul>
<li><tt><b>404</b></tt>: return a 404 error (file not found) instead of an image</li>
<li class="centered"><table summary=""><tr>
  <td><img height="80" width="80" src="http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=80&d=mm">
  <br><tt><b>mm</b></tt></td>
  <td><img height="80" width="80" src="http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=80&d=identicon">
  <br><tt><b>identicon</b></tt></td>
  <td><img height="80" width="80" src="http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=80&d=monsterid">
  <br><tt><b>monsterid</b></tt></td>
  <td><img height="80" width="80" src="http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=80&d=wavatar">
  <br><tt><b>wavatar</b></tt></td>
  <td><img height="80" width="80" src="http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=80&d=retro">
  <br><tt><b>retro</b></tt></td>
</tr></table></li>
</ul>

<p>Note that if an image is not found in the Libravatar database and the hash algorithm used was <b>MD5</b>, then Libravatar will first redirect to Gravatar in case the image exists there. Then it will honour the <tt>default</tt> parameter.</p>

<h2>For Gravatar users</h2>

<p>As you can see, our API is heavily based on the <a href="http://en.gravatar.com/site/implement/">Gravatar API</a>. If your application or website already supports <a href="http://www.gravatar.com">Gravatar</a>, switching to the basic Libravatar service is just a matter or changing the base URL:</p>

<blockquote><code>http://www.gravatar.com/avatar => http://cdn.libravatar.org/avatar</code></blockquote>

<p>or if you are using the HTTPS version of the service:</p>

<blockquote><code>https://secure.gravatar.com/avatar => https://seccdn.libravatar.org/avatar</code></blockquote>

<p>Note that Libravatar does <b>not</b> support the <tt>rating</tt> (or simply <tt>r</tt>) parameter since we require all images to be G-rated.</p>

<h2>Federated servers</h2>

<p>In order to support domain name owners who choose to <a href="{% url libravatar.public.views.run_your_own %}">run their own instances</a> of Libravatar, you should perform a DNS query to lookup the appropriate base URL for each domain.</p>

<p>You will probably want to use an <a href="{% url libravatar.public.views.libraries %}">existing library</a> for this, but here's how to do that DNS lookup on a UNIX command line:</p>

<pre>$ dig SRV _avatars._tcp.example.com

; <<>> DiG 9.7.2-P3 <<>> SRV _avatars._tcp.example.com
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 14684
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;_avatars._tcp.example.com.	IN	SRV

;; ANSWER SECTION:
<b>_avatars._tcp.example.com. 86400 IN	SRV 0 0 80 avatars.example.com.</b></pre>

<p>We also provide a <a href="{% url libravatar.tools.views.check_domain %}">domain check tool</a> to help in your testing.</p>

<p>Note for advanced users: Libravatar clients only consider at servers listed in the highest SRV priority. They do however honour relative weights.</p>

<h2>HTTPS support</h2>

<p>If your application is delivered over a secure (HTTPS) connection, you may want to use our HTTPS image servers to avoid triggering browser warnings about mixed HTTP/HTTPS content.</p>

<p>To do so, simply use this base URL:</p>

<blockquote><code>https://seccdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7</code></blockquote>

<p>When looking up the base URL to use via DNS, replace <tt>_avatars._tcp.example.com</tt> with:</p>

<blockquote><code>_avatars-sec._tcp.example.com</code></blockquote>

<h2>Testing tool</h2>
{'fraction_non_alphanumeric': 0.15843747269072794, 'fraction_numerical': 0.058725858603513065, 'mean_word_length': 5.182603997839006, 'pattern_counts': {'":': 0, '<': 409, '<?xml version=': 0, '>': 413, 'https://': 6, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5984249', 'n_tokens_mistral': 4609, 'n_tokens_neox': 4097, 'n_words': 1187}