✕

for developers

☰
REST API
Components
Mobile SDKs
Guides
Developer tools
Give feedback

Profiles

The Gravatar Public API lets developers retrieve Gravatar profile information. This guide shows you how to access this user profile data. This data is openly-accessible using a similar process to requesting images.

Profile as a Service

Imagine you sign up for a new service and go to your profile, only to find it already fully set up for you. Your avatar, bio, and social media links are all there.

The Gravatar API allows you to populate a complete user profile for your users based on Gravatar data the moment they sign up and provide their email address. All while you have full control over front-end design and user data. Our API allows you to save user data in your database for any other use or functionality in your app.

How It Works

Gravatar uses a simple, straightforward mechanism based on email hashes to fetch profile data:

  1. User Shares Email: A user shares their email address with your service.
  2. Email Hashing: Your application creates a SHA256 hash of the user’s email address. This hash is used to construct a URL that links to their Gravatar.
  3. Get Gravatar Profile Data: Use this URL to fetch the user’s profile data for your application. Display profile data inside your service or use the data to personalize user experience through a recommendation engine, or any other custom interaction – up to you.

Profile Requests

Base URL

All API requests are made to the following base URL:

https://api.gravatar.com/v3

Authentication

The API uses Bearer tokens to authenticate requests, which should be included in the Authorization header of the request. To get an API Key for authorization, visit the Gravatar Developer Dashboard.

Get Profile by Identifier

Retrieve a user’s profile by an identifier such as the SHA256 hash of an email address or a profile URL slug.

  • URL: /profiles/{profileIdentifier}
  • Method: GET
  • URL Parameters:
    • profileIdentifier [required]: The identifier for the profile, which can be a SHA256 hash of the email or a Gravatar profile URL slug (ie. gravatar.com/slug).
  • Headers:
    • Authorization [optional]: Bearer token for authenticated requests.
  • Success Response:
    • Code: 200 OK
    • Content: A JSON object containing the user’s profile details (see Profile schema).
  • Error Responses:
    • Code: 404 Not Found – No profile found for the given identifier.
    • Code: 429 Too Many Requests – API rate limit exceeded.
    • Code: 500 Internal Server Error – An error occurred on the server.
  • Sample Call:
curl -X GET "https://api.gravatar.com/v3/profiles/{profileIdentifier}" -H "Authorization: Bearer $GRAVATAR_API_KEY"
  • Notes: Profile requests will only resolve for the hash of the primary address on an account. Users may have multiple email addresses on a single account, so while a Gravatar image request may return a result, a profile request for the same hash may not.

Data Specifications

See all the details here. Gravatar offers a machine-readable OpenAPI Specification (OAS) for version 3.0.0, available at: https://api.gravatar.com/v3/openapi

Data Formats

Profile data may be requested in different data formats for simpler programmatic access. The following formats are supported:

  1. JSON
  2. XML
  3. PHP
  4. VCF/vCard
  5. QR Code

Embedding profile cards

Integrate a Gravatar profile card into your website using the /oembed API endpoint, directly embedding an <iframe>, or using the Gravatar Enhanced Plugin for WordPress.

Embedding via /oembed API Endpoint

You can use the /oembed API to embed a profile card on any website. For more information about how oEmbed works, you can visit oEmbed.com.

API Endpoint:

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

Parameters:

  • url (required): The Gravatar profile URL you want to embed.
    • Example format:
      • https://gravatar.com/{USERNAME}
      • https://es.gravatar.com/{USERNAME}, https://zh-TW.gravatar.com/{USERNAME}, etc.
    • Example request URL:
      • https://api.gravatar.com/v3/oembed?url=https%3A%2F%2Fgravatar.com%2Fmatt

API Response:

{
    "version": "1.0",
    "type": "rich",
    "title": "Gravatar Profile Card",
    "width": 415,
    "height": 228,
    "maxwidth": 415,
    "maxheight": 228,
    "html": "<iframe src=\"https://gravatar.com/username.card\" width=\"415\" height=\"228\" style=\"border:0; margin:0; padding:0;\"></iframe>",
    "provider_name": "Gravatar",
    "provider_url": "https://gravatar.com",
    "cache_age": 3600
}

Embedding via <iframe>

For a quick solution, you can embed the profile card using an <iframe>.

Example:

<iframe src="https://gravatar.com/{USERNAME}.card" width="415" height="228" style="border:0; margin:0; padding:0;"></iframe>

Note: The size of the Gravatar profile card is 415px by 228px (including the shadow effect). Ensure the iframe size matches or exceeds these dimensions.

Embedding with Gravatar Enhanced Plugin for WordPress

For WordPress websites, use the Gravatar Enhanced Plugin to automatically embed a profile card when a valid Gravatar profile URL is provided.

Last updated on: