Base Request
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:
http://www.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:
http://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50
When wrapped in an IMG tag, that URL will produce:
<img src="http://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:
http://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50.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):
http://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50?s=200
You may request images anywhere from 1px up to 512px, 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 (perhaps your logo, a funny face, whatever), then 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="http://www.gravatar.com/avatar/00000000000000000000000000000000?d=http%3A%2F%2Fexample.com%2Fimages%2Favatar.jpg" />
To URL-encode a string in PHP, you can use something like this:
1 echo urlencode( 'http://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.
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
- mm: (mystery-man) 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
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.
http://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50?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= orrating= 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:
http://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50?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:
http://www.gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50?s=200&r=pg&d=404
Secure Requests
If you’re displaying Gravatars on a page that is being served over SSL (e.g. the page URL starts with HTTPS), then you’ll want to serve your Gravatars via SSL as well, otherwise you’ll get annoying security warnings in most browsers. To do this, simply change the URL for your Gravatars so that is starts with:
https://secure.gravatar.com/...
Everything else is the same as above (all the same options work), just make sure that the URL starts out like this.