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 https://BASEURL/avatar/HASH.
  4. Put the URL into an img tag on your page. Eg. <img src="https://seccdn.libravatar.org/avatar/HASH" referrerpolicy="no-referrer">

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

Python example

Here's an example in Python:

import dns.resolver
import hashlib
import re
email = 'George@example.com'.encode('utf-8')
_, domain = email.split('@')
try:
  answers = dns.resolver.query('_avatars._tcp.' + domain, 'SRV')
  hostname = re.sub('\.$','', str(answers[0].target)) # query returns "example.com." and while http requests are fine with this, https most certainly do not consider "example.com." and "example.com" to be the same.
  port = str(answers[0].port)
  if port == '443':
    baseurl = 'https://' + hostname + '/avatar/'
  else:
    baseurl = 'http://' + hostname + ':' + port + '/avatar/'
except:
  baseurl = 'https://seccdn.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:

https://seccdn.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:

https://seccdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7?d=/static/nobody.jpg

If no image exists for the hash 40f8d096a3777232204cb3f796c577b7 then a redirection is made toward /static/nobody.jpg. Please note that due to CWE-601, redirection to external sites (eg. anything that starts with http[s]://) is prohibited. Only a few external sites are in the list of trusted sites. If you want to be added, please contact us and we will check if your request is feasible.

The default value is https://seccdn.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-bit arcade style pixel-art
  • robohash: return an image containing a random robohash
  • pagan: return an image containing a random retro adventure game character using pagan

Examples:

mm
mm		 identicon
identicon		 monsterid
monsterid		 wavatar
wavatar		 retro
retro		 robohash
robohash		 pagan
pagan

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 behavior can be triggered by providing the extra parameter forcedefault or f to the URL with a value of y:

https://seccdn.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 => https://seccdn.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.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. Eg. <img src="https://seccdn.libravatar.org/avatar/HASH" referrerpolicy="no-referrer">

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.

Secure versus non-secure requests

All non-secure requests (http://) coming to libravatar are automatically redirected to SSL (https://). However, that of course puts a bit more load on the webserver and the redirect is also needed on the client side, which of course increases the page load time. Therefore it's highly recommended to always use SSL, even if your own page doesn't use SSL. The other way round anyway doesn't work, as this will throw a warning in most (all?) browsers.