You should probably just use one of the available libraries or plugins, 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:
    1. Lowercase the email address.
    2. Compute a MD5 or SHA256 hash of it.
  2. Discover the avatar server base URL:
    1. Use DNS-based server discovery as described in Federated Servers.
    2. 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 40f8d096a3777232204cb3f796c577b7 and therefore the following image tag:

<img src="http://cdn.libravatar.org/avatar/40f8d096a3777232204cb3f796c577b7" alt="avatar of george@example.com"/>

It will render as follows: George@example.com

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 s or size 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 d or default parameter defaults to the Libravatar logo, but a few other special values are available:

  • 404: return a 404 error (file not found) instead of an image
  • 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.

For Gravatar users

As you can see, our API is heavily based on the Gravatar API. If your application or website already supports Gravatar 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 rating (or simply r) 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 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 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 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 and Python 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 _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 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 to help developers test their implementations and compare their results.