Simple API

There are 4 steps for displaying Libravatar-hosted images into an 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 the ยง Federated Servers section.
    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.

A collection of libraries or plugins implementing these steps are available.

Python example

Here's an example in Python:

import dns.resolver
import hashlib
email = 'George@example.com'.encode('utf-8')
_, domain = email.split('@')
try:
  answers = dns.resolver.query('_avatars._tcp.' + domain, 'SRV')
  baseurl = 'http://' + str(answers[0].target) + '/avatar/'
except:
  baseurl = http://cdn.libravatar.org/avatar/
hash = hashlib.md5(email.strip().lower()).hexdigest()
print baseurl + hash

Options

Picture size

The default size for images is 80x80 pixels, however it can be changed by providing the extra parameter size or s to the URL:

http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?s=100

Acceptable values range from 1 to 512. Invalid input such as non-integer or out-of-range values will be ignored.

Default URL for missing images

When an image is requested for an email address without a Libravatar account a default is substituted. This behaviour can be overridden by providing the extra parameter default or d to the URL:

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

If no image exists for the hash 40f8d096a3777232204cb3f796c577b7 then a redirection is made toward http://example.com/nobody.jpg.

The default value is http://cdn.libravatar.org/nobody.png.

A few special values are also allowed:

  • 404: return a 404 error (file not found) instead of an image
  • mm or mp: return an image containing a simple, fixed silhouette of a person
  • identicon: return an image containing a random geometric pattern
  • monsterid: return an image containing a random monsterid
  • wavatar: return an image containing a random wavatar
  • retro: return an image containing a random retro-looking, 8-bits arcade style pixel-art
  • robohash: return an image containing a random robohash

Examples:

mm
mm
identicon
identicon
monsterid
monsterid
wavatar
wavatar
retro
retro

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 default parameter.

Sub-option for d=robohash

If the default parameter is robohash then a special sub-option can be used to specify which set of images to use. This option is the parameter robohash. Accepted values are set1, set2 and set3. Any other value will be ignored. It can not be used in combination with another default value.

Force default

It is sometimes interesting to test the default option, even for hashes with matching avatars. This behaviour can be triggered by providing the extra parameter forcedefault or f to the URL with a value of y:

http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?d=retro&f=y

Any other value will be ignored.

For Gravatar users

This API mimics closely the Gravatar API. If an application or website already supports Gravatar then 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 for HTTPS version of the service:

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

Note that Libravatar does not support the rating (or simply r) parameter since it requires all images to be G-rated. If set, this parameter will be ignored.

Federated servers

It is important to start with a DNS query to lookup the appropriate base URL for a domain instead of directly using Libravatar's base URL as it allows to support domain name owners who choose to run their own instances.

DNS host names:

  • HTTP
    • SRV _avatars._tcp.EMAILDOMAIN
  • HTTPS
    • SRV _avatars-sec._tcp._tcp.EMAILDOMAIN

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.

Notes for advanced users / library authors:

  • Libravatar clients MUST only consider servers listed in the highest SRV priority.
  • They MUST honour relative weights.
  • SRV records are cached for at least 1 day (or more if the TTL is greater than 1 day).
  • Results returned by the DNS resolver MUST be sanitized (see Perl and Python examples).

HTTPS support

For applications using secure (HTTPS) connections it is preferable to use the 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 _avatars._tcp.example.com 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 img tag on your page.

Therefore, if the email address of some user is missing but his OpenID URLs is known then a hash can be generated:

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

A domain check tool is also available to help testing Libravatar integration or library development.