How Gravatar works

This is an overview of how sites get data from Gravatar and what’s available from the Gravatar ‘API’ (quotes theirs).

In short: Gravatar uses md5 hashes of email addresses to create links to users’ data which is stored on Gravatar. Here’s an md5 generator, you can try it out with your email address and follow along if you’d like.

The data available from Gravatar is:

1. Gravatar image
2. Gravatar profile

I’ve made an account to use in this post which has two email addresses associated with it¹. The hash of the primary email address is  240a19be07c1875584a4dcedee8a9fb6  and the md5 hash of the secondary email address is fba32ec6e5fd242e13c5b2e8471120da

Get Gravatar image

Most sites seem to just use the Gravatar image. I don’t have any data whatsoever on this, it’s simply an observation. In any case, this is how they get it.

The request url to get a user’s image looks like: https://www.gravatar.com/avatar/HASH where HASH is the md5 has of the user’s email address. So my demo account’s primary email address’s image url is https://www.gravatar.com/avatar/240a19be07c1875584a4dcedee8a9fb6 which links to this image²:

The secondary email address’s image url is https://www.gravatar.com/avatar/fba32ec6e5fd242e13c5b2e8471120da and is this image:

I haven’t attached an image to use on that email address so it goes to the default Gravatar image³. This will be more interesting when we get to the next section.

Get Gravatar profile

tl;dr:

Here’s what is shown in a Gravatar profile, broken down by “public” and “can be made private”. You can make a request to someone’s profile on the Gravatar site by using https://gravatar.com/HASH where HASH is the md5 hash of their email address. You can get a bit more data by looking at the JSON, XML or PHP endpoints — those are of the form https://gravatar.com/HASH.json etc.

Public and will show up no matter what:

• display name (defaults to preferred username)
• preferred username (can’t be changed, this is your WordPress.com username)
• hash (this may or may not be different from the request hash, it is the hash of the primary email)
• request hash (the hash used in the request url)
• user id (not used for anything)
• avatar photo of the primary email address

Can be made private by not filling out the relevant fields:

• Everything else

(I can’t be bothered writing them all out.)

Longer:

The Gravatar profile is the more interesting bit because there’s a lot here. Let’s look at the profile on the web first. Mine has the bare minimum except for:

• a different display name
• two email addresses associated with it
• an uploaded photo to used as the avatar

I’m going to use the hash the secondary email address generates, fba32ec6e5fd242e13c5b2e8471120da, which makes the request url:

https://www.gravatar.com/fba32ec6e5fd242e13c5b2e8471120da

when you click it, it redirects to:

https://en.gravatar.com/idontthinkitworkslikethat

Looking at that page, “idonthinkitworksliketthat” in the url is a url compatible version of my WordPress.com username for that account which I set when I signed up. You’ll notice that it’s not my display name — my display name is “idontthinkitworkslikethatlalala”. The display name is shown on my profile, along with an uploaded photo used as my avatar.

But that’s just my profile webpage, there’s more data available in more easily consumed formats — in particular there are JSON, XML and PHP endpoints. Requesting these endpoints is as easy as appending the extension to the request url so:

• JSON: https://www.gravatar.com/fba32ec6e5fd242e13c5b2e8471120da.json
• XML: https://www.gravatar.com/fba32ec6e5fd242e13c5b2e8471120da.xml
• PHP: https://www.gravatar.com/fba32ec6e5fd242e13c5b2e8471120da.php

For my purposes here, I’m going to look at the XML endpoint because that’ll show up best on most people’s browsers. (The information in all of them is the same.)

XML endpoint (this is an image, I can’t get the formatting right):

A reminder: all I’ve added to my profile other than the bare minimum is a different display name, another email address (in this example, it’s this email address I’m using for the hash) and a photo which is used as the main Gravatar image. So what data is in the XML response?

• id: User id (I’m assuming)
• hash: The hash of the primary email address on the account
• requestHash: The hash of the email address used to request this profile
• profileUrl: The url to which requests associated with my account get redirected
• preferredUsername: My WordPress.com and Gravatar username. Cannot be changed.
• thumbnailUrl: A link to the image I’ve uploaded to be used as my Gravatar for my primary email address, ie this link uses to build the url not as I was expecting
• photos: Information about the photo I’ve uploaded — type=thumbnail means it’s the one used as my Gravatar
• displayName: The name I’ve chosen to be displayed as my name on my Gravatar profile and elsewhere

Some notes on these:

1. If I only had one email address and used that, the requestHash would always be the same as the the hash. And if I had more than two email addresses attached to the account (not in the “contact me” section but on the page where email addresses are associated with the account), those couldn’t see each other. It’s simply that every time a secondary email address is used to request a profile, the response will return that hash as well as the hash of the primary email account.
2. I expected thumbnailUrl to be the image associated with the email address in my account but it’s not, it’s the one associated with the primary email address
3. If I hadn’t chosen a display name, this would be the same as my preferred username.
4. Anything I fill out in in the “My profile” tab of my Gravatar profile (this link is to yours) will show up in the json, xml and php responses. For an example of this see Matt Mullenweg’s xml response which is nice and full!

---

Footnotes

1. You can add an email address to your Gravatar account in the “My Gravatars” tab of your profile.
2. The url https://www.gravatar.com/avatar/HASH seems to only look at the first 32 characters of HASH (ie the length of an md5 hash) and then for the d (default image url) and s (size) query args, so if you, eg, want to add it as an image in a blog post and need an extension, it’s fine to use .jpg  (that’s what it is in fact) because the .jpg bit gets ignored.What happens if I add it as a .gif?
   Well that was using https://www.gravatar.com/avatar/240a19be07c1875584a4dcedee8a9fb6.gif as the image url and it’s included it as a jpg. So it must check to see what kind of file it actually is at some point.What if I rename a .js file as .jpg? Oh interesting. It lets me upload that. I can’t download it at all due to browser security thingies on Chrome. But getting it via curl it seems that WordPress.com allows the upload then overwrites the file with “The content of this file is dangerous” and when it’s requested, returns a 406 response code (? I’m going to leave this here now but what are we guessing, it checks the file when someone requests it? Otherwise why would you allow the upload?)
3. To attach an image to an email address, go through the “add new image” process — it’s the last page of that.