Gravatar images may be requested just like a normal image, using an img tag. To get an image specific to a user, you must first calculate their email hash.
The most basic image request URL looks like this:
https://gravatar.com/avatar/HASH
where HASH is replaced with the calculated hash for the specific email address you are requesting. For example, here is my base URL:
https://gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109
When wrapped in an img tag, that URL will produce:
<img src="https://gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109" />
If you require a file-type extension (some places do) then you may also add an (optional) .jpg extension to that URL:
https://gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109.jpg
Size
By default, images are presented at 80px by 80px if no size parameter is supplied. You may request a specific image size, which will be dynamically delivered from Gravatar by using the s= or size= parameter and passing a single pixel dimension (since the images are square):
https://gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109?s=200
You may request images anywhere from 1px up to 2048px, however note that many users have lower resolution images, so requesting larger sizes may result in pixelation/low-quality images.
Default Image
What happens when an email address has no matching Gravatar image? By default, this:
If you’d prefer to use your own default image you can easily do so by supplying the URL to an image in the d= or default= parameter. The URL should be URL-encoded to ensure that it carries across correctly, for example:
<img src="https://gravatar.com/avatar/000000000000000000000000000000000000000000000000000000?d=https%3A%2F%2Fexample.com%2Fimages%2Favatar.jpg" />
To URL-encode a string in PHP, you can use something like this:
echo urlencode( 'https://example.com/images/avatar.jpg' );
When you include a default image, Gravatar will automatically serve up that image if there is no image associated with the requested email hash. There are a few conditions which must be met for default image URL:
- MUST be publicly available (e.g. cannot be on an intranet, on a local development machine, behind HTTP Auth or some other firewall etc). Default images are passed through a security scan to avoid malicious content.
- MUST be accessible via HTTP or HTTPS on the standard ports, 80 and 443, respectively.
- MUST have a recognizable image extension (jpg, jpeg, gif, png, heic)
- MUST NOT include a querystring (if it does, it will be ignored)
In addition to allowing you to use your own image, Gravatar has a number of built in options which you can also use as defaults. Most of these work by taking the requested email hash and using it to generate a themed image that is unique to that email address. To use these options, just pass one of the following keywords as the d= parameter to an image request:
- 404: do not load any image if none is associated with the email hash, instead return an HTTP 404 (File Not Found) response
- mp: (mystery-person) a simple, cartoon-style silhouetted outline of a person (does not vary by email hash)
- identicon: a geometric pattern based on an email hash
- monsterid: a generated ‘monster’ with different colors, faces, etc
- wavatar: generated faces with differing features and backgrounds
- retro: awesome generated, 8-bit arcade-style pixelated faces
- robohash: a generated robot with different colors, faces, etc
- blank: a transparent PNG image (border added to HTML below for demonstration purposes)
Force Default
If for some reason you wanted to force the default image to always load, you can do that by using the f= or forcedefault= parameter, and setting its value to y.
https://gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109?f=y
Rating
Gravatar allows users to self-rate their images so that they can indicate if an image is appropriate for a certain audience. By default, only ‘G’ rated images are displayed unless you indicate that you would like to see higher ratings. Using the r= or rating= parameters, you may specify one of the following ratings to request images up to and including that rating:
- g: suitable for display on all websites with any audience type.
- pg: may contain rude gestures, provocatively dressed individuals, the lesser swear words, or mild violence.
- r: may contain such things as harsh profanity, intense violence, nudity, or hard drug use.
- x: may contain sexual imagery or extremely disturbing violence.
If the requested email hash does not have an image meeting the requested rating level, then the default image is returned (or the specified default, as per above) To allow images rated G or PG use something like this:
https://gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109?r=pg
Combining Parameters
You may combine any and all of the above parameters to produce more complex/refined requests. For example, this URL will request a 200px by 200px Gravatar rated G or PG, defaulting to a 404 response (no image) if there is not one associated with the requested email hash:
https://gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109?s=200&r=pg&d=404
Secure Requests
As you may have noticed, all of the above example URLs start withhttps. You don’t need to do anything special to load Gravatars on a secure page, just make sure your Gravatar URLs start with https (or you can use the ‘protocol-agnostic’ approach of starting the URLs with ‘//’ which will automatically use https on a secure page, or http on an insecure one).
Special Thanks
To Scott for identicons and monsterids To Shamus for wavatars
Gravatar Developer Docs