You should probably just use one of the available libraries or plugins, but here is a description of the API.

Simple API

There are 5 steps for displaying Libravatar-hosted images into your application:

  1. Take a user's email address as entered by them.
  2. Convert the email address to lowercase.
  3. Compute the hash (using the MD5 or SHA256 hash algorithms).
  4. Turn the image into a URL by prefixing it with the base URL http://cdn.libravatar.org/avatar/.
  5. Put the image into an img tag on your page.

Here's an example in Python:

import hashlib
email = 'George@example.com'
hash = hashlib.md5(email.strip().lower()).hexdigest()

which gives us a hash of 40f8d096a3777232204cb3f796c577b7 and therefore the following image tag:

George@example.com

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).

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 SRV _avatars._tcp.example.com

; <<>> DiG 9.7.2-P3 <<>> SRV _avatars._tcp.example.com
; (1 server found)
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 14684
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;_avatars._tcp.example.com. IN  SRV

;; ANSWER SECTION:
_avatars._tcp.example.com. 86400 IN SRV 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.