|
|
|
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:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
# 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">
|
|
|
|
<br><tt>**mm**</tt></td>
|
|
|
|
<td align="center">
|
|
|
|
<br><tt>**identicon**</tt></td>
|
|
|
|
<td align="center">
|
|
|
|
<br><tt>**monsterid**</tt></td>
|
|
|
|
<td align="center">
|
|
|
|
<br><tt>**wavatar**</tt></td>
|
|
|
|
<td align="center">
|
|
|
|
<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. |
