Getting started

Welcome to Gravatar! This guide will help you get started integrating Gravatar into your applications. Whether you’re looking to simplify and personalize user onboarding, enrich user profiles, or both, this guide will walk you through the basics of working with Gravatar’s APIs and tools.

What is Gravatar?

Gravatar (Globally Recognized Avatar) is a service that allows users to create profiles linked to their email addresses. These profiles are used across millions of sites, providing consistent avatars and user identity for more than 70 million users worldwide. The Gravatar API is completely open and free to use, making it accessible for developers and organizations of all sizes.

Key Benefits

All of these benefits are achieved simply by users providing their email address – no additional registration process required!

• Learn instantly about your user: Gravatar solves the Cold Start Problem – with sharing their email address, Gravatar users share a full profile with you. Retrieve user profile data and avatars for more than 70 million users. Access rich profile data including display names, avatars, locations, biographies, interests, verified social media accounts, and more.
• Simplified User Onboarding: Users don’t need to repeatedly fill out profile forms across different services. Get higher profile completion rates by leveraging existing data rather than requiring users to create new profiles.
• Personalized User Experience: Optimize user interactions based on profile data, especially during the critical onboarding process. Use Gravatar’s interest data to power recommendation engines and content personalization from day one.
• Continuously updated profiles: Users maintain uniform identity across all Gravatar-enabled platforms, with profile changes staying in sync everywhere.
• Reduced Development Overhead (Profile as a Service): Implement avatars and profiles with minimal development effort. Gravatar eliminates the need to build and maintain your own user profile management systems. Allow users to upload, edit and manage avatar images and profile information on your site (with Gravatar Quick Editor) or in your apps (with Android, iOS SDKs).
• Minimal Development Effort: There is nothing to lose. You can use Gravatar as a fallback option or for user data pre-fill – no strings attached, and its free.
• We don’t go anywhere: Gravatar is around since 2007.

Quick Start

Step 1: Register and set up your account

To start using Gravatar’s developer tools, you’ll first need to create a Gravatar account if you don’t already have one. Once registered, you can manage your own Gravatar profile and explore how the profile data system works.

Step 2: Create an API key

You can create the API Key as follows:

1. Login in to your Gravatar account (or the Gravatar account you want to use to generate the key)
2. Navigate to the Developer Dashboard
3. Tap on Create New Application
4. Fill the required data and follow the flow

Gravatar is using Bearer Tokens. Include your API key in the Authorization header of your requests.

Step 3: Create identifier – email hash

The email hash is the foundation of all Gravatar functionality. It serves as the universal identifier for accessing both avatars and profile data. Email, the ultimate username!

// CRITICAL: Generate the SHA256 hash correctly for all Gravatar operations
function getGravatarHash(email) {
  // Trim and lowercase the email - BOTH steps are required
  email = email.trim().toLowerCase();
  
  // Create SHA256 hash (using a crypto library)
  const hash = crypto.createHash('sha256').update(email).digest('hex');
  
  return hash;
}

// This single hash is used for BOTH avatars AND profile data
const hash = getGravatarHash('user@example.com');

Step 4: Integrate Gravatar into your application

All API requests are made to the following base URL: https://api.gravatar.com/v3

Gravatar provides APIs and SDKs for multiple platforms including iOS, Android, and web applications. Here’s how you can integrate it:

• Avatar Integration: Looking to add only avatars to your website or app, use our simple Avatar API. Use the email hash to construct avatar URLs:

// Avatar URL using the same email hash
const avatarUrl = `https://0.gravatar.com/avatar/${hash}`;

// Usage in HTML
// <img src="https://0.gravatar.com/avatar/84059b07d4be67b806386c0aad8070a23f18836bbaae342275dc0a83414c32ee" alt="User avatar" />

• Profile Integration: Use our REST API to fetch rich Gravatar profile data. Our Gravatar profile pages implement this same API. Customize profile designs for your applications. It’s simple.

const hash = getGravatarHash('user@example.com');
const profileUrl = `https://api.gravatar.com/v3/profiles/${hash}`;

// With authentication (recommended)
fetch(profileUrl, {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
})
.then(response => response.json())
.then(profile => console.log(profile));

• Mobile Integration: Utilize our iOS and Android SDKs to integrate Gravatars into your mobile apps. These SDKs support loading user avatars, adding profile cards, and more.

Tutorial

Let’s try this out! Ready to dive into a React tutorial for creating a Gravatar profile integration?