API Endpoints

Complete reference for Gravatar API v3 endpoints and usage patterns.

Base URL

https://api.gravatar.com/v3

Authentication

Use Bearer token authentication for richer profile data and higher profile API limits:

Authorization: Bearer YOUR_API_KEY

Profile Endpoints

Get Profile by Identifier

Retrieve a user’s profile using their email hash or profile URL slug.

Endpoint: GET /profiles/{profileIdentifier}

Authentication:

Public: Limited profile data
Bearer Token: Full profile data (recommended)

Parameters:

profileIdentifier (required): SHA256 hash of email or profile URL slug

Response Codes:

200 OK: Successfully retrieved profile
404 Not Found: Profile not found
429 Too Many Requests: Rate limit exceeded

Example Request

# With authentication
curl -X GET "https://api.gravatar.com/v3/profiles/99511d6010af8c574c31f94e1b327bba5e25086dd7b92a4b6f3e132b579cc8d1" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "hash": "99511d6010af8c574c31f94e1b327bba5e25086dd7b92a4b6f3e132b579cc8d1",
  "profile_url": "https://gravatar.com/examplefork",
  "avatar_url": "https://0.gravatar.com/avatar/99511d6010af8c574c31f94e1b327bba5e25086dd7b92a4b6f3e132b579cc8d1",
  "avatar_alt_text": "User's avatar",
  "display_name": "Example",
  "pronouns": "He/Him",
  "location": "E.G.",
  "job_title": "Chief",
  "company": "EG Inc",
  "description": "Sorry, this is not my name. Just an example, you know."
}

QR Code URLs

Generate QR Code

Generate a QR code for a user’s profile.

URL Pattern: GET /{sha256_hash}.qr

Authentication: Public (no authentication required)

Parameters:

sha256_hash (required): SHA256 hash of email or profile URL slug

Query Parameters:

size (optional): Size of QR code in pixels (default: 80)
s (optional): Alias for size
version (optional): QR code style (1: standard, 3: modern dots)
utm_medium (optional): UTM medium parameter
utm_campaign (optional): UTM campaign parameter
type (optional): Center icon type (user, gravatar, none)

Response Codes:

200 OK: QR code image (PNG format)
429 Too Many Requests: Rate limit exceeded
500 Internal Server Error: Server error

Example Request

curl -X GET "https://gravatar.com/99511d6010af8c574c31f94e1b327bba5e25086dd7b92a4b6f3e132b579cc8d1.qr?size=300&type=user&version=3"

Avatar URL Construction

While not API endpoints, avatar URLs follow a predictable pattern:

Basic Avatar URL

https://0.gravatar.com/avatar/{hash}?parameters

URL Parameters

Parameter	Description	Default
`s` or `size`	Avatar size in pixels	80
`d` or `default`	Default avatar type	mp
`r` or `rating`	Maximum rating level	g
`f` or `forcedefault`	Force default image	y

Default Avatar Options

404 - Return a 404 error
mp - Mystery person silhouette
identicon - Geometric pattern based on hash
monsterid - Generated monster
wavatar - Generated faces
retro - 8-bit arcade-style
robohash - Generated robot
blank - Transparent PNG

Example Avatar URLs

# Basic avatar
https://0.gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109

# With parameters
https://0.gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109?s=200&r=pg&d=identicon

# Force default
https://0.gravatar.com/avatar/27205e5c51cb03f862138b22bcb5dc20f94a342e744ff6df1b8dc8af3c865109?f=y

Embed a Gravatar profile card through the oEmbed endpoint.

Endpoint: GET /oembed

Parameters:

url (required): Gravatar profile URL, such as https://gravatar.com/{username}

Example Request

curl "https://api.gravatar.com/v3/oembed?url=https%3A%2F%2Fgravatar.com%2Fmatt"

Data Formats

Gravatar profiles can be requested in multiple formats:

JSON Format

Append .json to profile URLs:

https://gravatar.com/99511d6010af8c574c31f94e1b327bba5e25086dd7b92a4b6f3e132b579cc8d1.json

JSONP Support: Add a callback parameter:

https://gravatar.com/99511d6010af8c574c31f94e1b327bba5e25086dd7b92a4b6f3e132b579cc8d1.json?callback=processProfile

XML Format

Append .xml to profile URLs:

https://gravatar.com/99511d6010af8c574c31f94e1b327bba5e25086dd7b92a4b6f3e132b579cc8d1.xml

PHP Serialized Format

Append .php to profile URLs:

https://gravatar.com/99511d6010af8c574c31f94e1b327bba5e25086dd7b92a4b6f3e132b579cc8d1.php

VCF/vCard Format

Append .vcf to profile URLs:

https://gravatar.com/99511d6010af8c574c31f94e1b327bba5e25086dd7b92a4b6f3e132b579cc8d1.vcf

Markdown Format

Append .md to profile URLs:

https://gravatar.com/99511d6010af8c574c31f94e1b327bba5e25086dd7b92a4b6f3e132b579cc8d1.md

Rate Limiting

Default Rate Limits

Authentication	Profile Requests per Hour
API Key	1,000
Unauthenticated	100

Avatar image requests do not count toward these profile endpoint limits.

Rate Limit Headers

All API responses include rate limit information:

X-RateLimit-Limit: Total requests allowed in current period
X-RateLimit-Remaining: Remaining requests in current period
X-RateLimit-Reset: Unix timestamp when the limit resets

Handling Rate Limits

// Check rate limits from response headers
const response = await fetch('https://api.gravatar.com/v3/profiles/hash', {
  headers: {
    Authorization: `Bearer ${apiKey}`,
  },
});

const rateLimit = {
  limit: response.headers.get('X-RateLimit-Limit'),
  remaining: response.headers.get('X-RateLimit-Remaining'),
  reset: response.headers.get('X-RateLimit-Reset'),
};

if (rateLimit.remaining === '0') {
  const resetTime = parseInt(rateLimit.reset!) * 1000;
  const waitTime = resetTime - Date.now();

  if (waitTime > 0) {
    console.log(`Rate limit reached. Waiting ${waitTime}ms...`);
    await new Promise((resolve) => setTimeout(resolve, waitTime));
  }
}

Error Handling

Error Response Format

All API errors follow a consistent format:

{
  "error": "Error message description",
  "code": "error_code"
}

Common Error Codes

HTTP Status	Error Code	Description	Solution
400	`uncropped_image`	Image is not square	Crop image to 1:1 ratio
400	`unsupported_image`	File format not supported	Use JPG, PNG, or GIF
401	-	Authentication failed	Check API key
403	`insufficient_scope`	Token lacks permissions	Request proper scopes
404	`disabled`	Profile is disabled	No solution
429	`rate_limit_exceeded`	Too many requests	Implement backoff
500	-	Server error	Retry with backoff

Error Handling Best Practices

import { GravatarError } from 'astro-gravatar';

try {
  const profile = await getProfile('user@example.com', { apiKey });
  return profile;
} catch (error) {
  if (error instanceof GravatarError) {
    switch (error.code) {
      case 'rate_limit_exceeded':
        // Implement exponential backoff
        await new Promise((resolve) => setTimeout(resolve, 5000));
        return getProfile('user@example.com', { apiKey });

      case 'disabled':
        // Profile is disabled, use fallback
        return createFallbackProfile();

      default:
        console.error('Gravatar API Error:', error.message);
        throw error;
    }
  }
  throw error;
}

SDK and Tool Integration

astro-gravatar Integration

import { getProfile, buildAvatarUrl } from 'astro-gravatar';

// Get profile with API key
const profile = await getProfile('user@example.com', {
  apiKey: import.meta.env.GRAVATAR_API_KEY,
});

// Build avatar URL
const avatarUrl = buildAvatarUrl('user@example.com', {
  size: 200,
  rating: 'pg',
  default: 'identicon',
});

OpenAPI Specification

The complete API specification is available at:

https://api.gravatar.com/v3/openapi

Useful Resources

GitHub Repositories: https://github.com/Automattic/gravatar
Developer Dashboard: https://gravatar.com/developers
API Console: https://gravatar.com/developers/console
Status Page: https://automatticstatus.com/

Security Best Practices

Never expose API keys in client-side code
Store API keys in environment variables
Use HTTPS for all API requests
Implement rate limiting on your side
Validate email addresses before hashing
Cache responses to reduce API calls
Use exponential backoff for retries
Monitor rate limit headers in responses

Next Steps

Authentication Guide - Set up API keys
Component Reference - Learn component APIs
Performance Guide - Optimize API usage

API Endpoints

Base URL

Authentication

Profile Endpoints

Get Profile by Identifier

Example Request

Example Response

QR Code URLs

Generate QR Code

Example Request

Avatar URL Construction

Basic Avatar URL

URL Parameters

Default Avatar Options

Example Avatar URLs

Profile Card Embeds

oEmbed Profile Card

Example Request

Data Formats

JSON Format

XML Format

PHP Serialized Format

VCF/vCard Format

Markdown Format

Rate Limiting

Default Rate Limits

Rate Limit Headers

Handling Rate Limits

Error Handling

Error Response Format

Common Error Codes

Error Handling Best Practices

SDK and Tool Integration

astro-gravatar Integration

OpenAPI Specification

Useful Resources

Security Best Practices

Next Steps