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:
where HASH is replaced with the calculated hash for the specific email address you are requesting. For example, here is my base URL:
When wrapped in an
IMG tag, that URL will produce:
<img src="https://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50" />
If you require a file-type extension (some places do) then you may also add an (optional)
.jpg extension to that URL:
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
size= parameter and passing a single pixel dimension (since the images are square):
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.
What happens when an email address has no matching Gravatar image? By default, this:
If you'd prefer to use your own default image (perhaps your logo, a funny face, whatever), then you can easily do so by supplying the URL to an image in the
default= parameter. The URL should be URL-encoded to ensure that it carries across correctly, for example:
<img src="https://www.gravatar.com/avatar/00000000000000000000000000000000?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)
If for some reason you wanted to force the default image to always load, you can do that by using the
forcedefault= parameter, and setting its value to
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
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 hardcore 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:
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:
As you may have noticed, all of the above example URLs start with HTTPS. 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).
To Shamus for wavatars