api.md

+You should probably just use one of the available [libraries or plugins](libraries), but here is a description of the API.
+
+# Simple API
+
+There are 4 steps for displaying Libravatar-hosted images into your application:
+
+
+1. Create a hash from the user's email address:
+   a. Lowercase the email address.
+   b. Compute a MD5 or SHA256 hash of it.
+2. Discover the avatar server base URL:
+   a. Use DNS-based server discovery as described in *Federated Servers*.
+   b. If no server was found, fall back to `cdn.libravatar.org` (or `seccdn.libravatar.org` for HTTPS).
+3. Create a URL like `http://BASEURL/avatar/HASH`.
+4. Put the URL into an `img` tag on your page.
+
+
+## Python example
+Here's an example in Python:
+
+    import hashlib
+    email = 'George@example.com'.encode('utf-8')
+    hash = hashlib.md5(email.strip().lower()).hexdigest()
+
+which gives us a hash of <tt>40f8d096a3777232204cb3f796c577b7</tt> and therefore the following image tag:
+
+    <img src="https://seccdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7" alt="avatar of george@example.com"/>
+
+It will render as follows:
+![George@example.com](https://seccdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7)
+
+
+# Options
+
+## Picture size
+
+The default size for images is **80x80** pixels, however you can change it by providing an extra parameter to the URL:
+
+    http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=100
+
+The <tt>s</tt> or <tt>size</tt> is the size (height and width are the same) of the image in pixels. Acceptable values range from **1** to **512**.
+
+## Default URL for missing images
+
+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:
+
+    http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?d=http://example.com/nobody.jpg
+
+The <tt>d</tt> or <tt>default</tt> parameter defaults to the Libravatar logo, but a few other special values are available:
+
+* <tt>**404**</tt>: return a 404 error (file not found) instead of an image
+* <table><tr>
+  <td align="center">![mm](https://seccdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=80&d=mm)
+  <br><tt>**mm**</tt></td>
+  <td align="center">![identicon](https://seccdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=80&d=identicon)
+  <br><tt>**identicon**</tt></td>
+  <td align="center">![monsterid](https://seccdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=80&d=monsterid)
+  <br><tt>**monsterid**</tt></td>
+  <td align="center">![wavatar](https://seccdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=80&d=wavatar)
+  <br><tt>**wavatar**</tt></td>
+  <td align="center">![retro](https://seccdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=80&d=retro)
+  <br><tt>**retro**</tt></td>
+  </tr></table>
+
+Note that if an image is not found in the Libravatar database and the hash algorithm used was **MD5**, then Libravatar will first redirect to Gravatar in case the image exists there. Then it will honour the <tt>default</tt> parameter.
+
+# For Gravatar users
+
+As you can see, our API is heavily based on the [Gravatar API](http://en.gravatar.com/site/implement/). If your application or website already supports [Gravatar](http://www.gravatar.com) switching to the basic Libravatar service is just a matter or changing the base URL:
+
+    http://www.gravatar.com/avatar => http://cdn.libravatar.org/avatar
+
+or if you are using the HTTPS version of the service:
+
+    https://secure.gravatar.com/avatar => https://seccdn.libravatar.org/avatar
+
+Note that Libravatar does **not** support the <tt>rating</tt> (or simply <tt>r</tt>) parameter since we require all images to be G-rated.
+
+# Federated servers
+
+In order to support domain name owners who choose to [run their own instances](running your own) of Libravatar, you must perform a DNS query to lookup the appropriate base URL for each domain (the domain is extracted from email addresses or OpenID URLs).
+
+DNS host names:
+
+* HTTP
+  * `SRV _avatars._tcp.EMAILDOMAIN`
+* HTTPS
+  * `SRV _avatars-sec._tcp._tcp.EMAILDOMAIN`
+
+
+You will probably want to use an [existing library](libraries) for this, but here's how to do that DNS lookup on a UNIX command line:
+
+    $ dig +short SRV _avatars._tcp.example.com
+    0 0 80 avatars.example.com.
+
+We also provide a [domain check tool](https://www.libravatar.org/tools/check_domain) to help in your testing.
+
+Notes for advanced users / library authors:
+
+* Libravatar clients only consider servers listed in the highest SRV priority.
+* They do however honour relative weights.
+* SRV records are cached for at least 1 day (or more if the TTL is greater than 1 day).
+* **Make sure you sanitize the results you get from the DNS resolver** (see [Perl](https://github.com/schwern/gravatar-url/commit/14b0c613f434d2513f8f4609a17aff4fe31c17ea) and [Python](http://bazaar.launchpad.net/~libravatar/pylibravatar/trunk/revision/5) examples).
+
+# HTTPS support
+
+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.
+
+To do so, simply use this base URL:
+
+    https://seccdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7
+
+When looking up the base URL to use via DNS, replace <tt>\_avatars._tcp.example.com</tt> with:
+
+    _avatars-sec._tcp.example.com
+
+# OpenID support
+
+In addition to email addresses, Libravatar allows users to associate photos to their OpenIDs.
+
+The same 5 steps apply:
+
+1. Take a user's OpenID URL as entered by them.
+2. Convert the **protocol and hostname parts** of the URL to lowercase. e.g. HTTP://UserName:Password@EXAMPLE.COM/ID/Bob => http://UserName:Password@example.com/ID/Bob
+3. Compute the hash (using the **SHA256 hash algorithm only**).
+4. Turn the image into a URL by prefixing it with the Libravatar base URL.
+5. Put the image into an <tt>img</tt> tag on your page.
+
+Therefore, if you don't have an email address for some of your users but you do have OpenID URLs, here is sample Python code to produce a hash for them:
+
+    import hashlib
+    from urlparse import urlsplit, urlunsplit
+
+    openid = 'http://example.com/id/john'
+    url = urlsplit(openid.strip())
+    if url.username:
+        password = url.password or ''
+        netloc = url.username + ':' + password + '@' + url.hostname
+    else:
+        netloc = url.hostname
+    lowercase_url = urlunsplit((url.scheme.lower(), netloc, url.path, url.query, url.fragment))
+    hash = hashlib.sha256(lowercase_url).hexdigest()
+
+# Testing tool
+
+We provide a [check tool](https://www.libravatar.org/tools/check) to help developers test their implementations and compare their results.