✕

for developers

☰
REST API
Components
Mobile SDKs
Guides
Developer tools
Give Feedback

REST API

Overview

The Gravatar Public API allows developers to retrieve Gravatar profile information. This documentation will help you understand how to integrate with the API to perform operations related to user profiles.

To create an application and API key, visit the Gravatar Developer Dashboard.

Creating 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
Creating an API Key in the developers portal

Base URL

All API requests are made to the following base URL:

https://api.gravatar.com/v3

Rate Limits

The Profiles API is free to use, and its rate limits are customizable based on your needs. While the default limits below are set to prevent misuse, allowing you to begin testing the API right away, you can apply for much higher limits to accommodate specific usage requirements for no additional costs. Simply reach out to us and describe your usecase and needs.

Default rate limits:

Unauthenticated requests are limited to 100 per hour.

Authenticated requests are limited to 1000 per hour.

You will see error code 429 for too many requests.

ℹ️ Take into account that Avatars API requests do not count towards the limits mentioned above. These limits only apply to the Profiles endpoint.

If you reach this limit and your application needs higher limits, please contact us here.

Authentication

Some endpoints require 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.

Using an API key is always recommended, and will give you:

  • Higher rate limits (1000 vs 100 requests per hour)
  • Access to additional endpoints, including
    • Links,
    • Registration and last edit timestamps,
    • Contact info,
    • Payment and wallet info,
    • and Gallery images

API Methods

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:
    • Full profile information is available only in authenticated requests.

Get Inferred Interests by Identifier

Experimental

Description: Returns a list of inferred interests based on known and public information about the profile.

Path Parameters:

  • profileIdentifier (string, required)

Output: Array of Interest

Schemas

CryptoWalletAddress

A crypto currency wallet address the user accepts.

Properties:

label (string, required): – The label for the crypto currency.
Example: “ETH“

address (string, required): – The wallet address for the crypto currency.
Example: “0xABC123...“

GalleryImage

A gallery image a user has uploaded.

Properties:

url (string, required): – The URL to the image.
Example: “https://0.gravatar.com/userimage/5/04bbd674f72c703f6335e2e7a00acc9a“

alt_text (string, optional): – The image alt text.
Example: “A beautiful sunset“

Interest

An interest the user has added to their profile.

Properties:

id (integer, required): – The unique identifier for the interest.
Example: “1“

name (string, required): – The name of the interest.
Example: “photography“

Language

The languages the user knows. This is only provided in authenticated API requests.

Properties:

code (string, required): – The language code.
Example: “en“

name (string, required): – The language name.
Example: “English“

is_primary (boolean, required): – Whether the language is the user’s primary language.
Example: “True“

order (integer, required): – The order of the language in the user’s profile.
Example: “1“

Link

A link the user has added to their profile.

Properties:

label (string, required): – The label for the link.
Example: “Personal Website“

url (string, required): – The URL to the link.
Example: “https://example.com“

Profile

A user’s profile information.

Properties:

hash (string, required): – The SHA256 hash of the user’s primary email address.
Example: “31c5543c1734d25c7206f5fd591525d0295bec6fe84ff82f946a34fe970a1e66“

display_name (string, required): – The user’s display name. This is the name that is displayed on their profile.
Example: “Alex Morgan“

profile_url (string, required): – The full URL for the user’s profile.
Example: “https://gravatar.com/example“

avatar_url (string, required): – The URL for the user’s avatar image if it has been set.
Example: “https://0.gravatar.com/avatar/33252cd1f33526af53580fcb1736172f06e6716f32afdd1be19ec3096d15dea5“

avatar_alt_text (string, required): – The alt text for the user’s avatar image if it has been set.
Example: “Alex Morgan's avatar image. Alex is smiling and standing in beside a large dog who is looking up at Alex.“

location (string, required): – The user’s location.
Example: “New York, USA“

description (string, required): – The about section on a user’s profile.
Example: “I like playing hide and seek.“

job_title (string, required): – The user’s job title.
Example: “Landscape Architect“

company (string, required): – The user’s current company’s name.
Example: “ACME Corp“

verified_accounts (array of VerifiedAccount, required): – A list of verified accounts the user has added to their profile. This is limited to a max of 4 in unauthenticated requests.

pronunciation (string, required): – The phonetic pronunciation of the user’s name.
Example: “Al-ex Mor-gan“

pronouns (string, required): – The pronouns the user uses.
Example: “She/They“

timezone (string, optional): – The timezone the user has. This is only provided in authenticated API requests.
Example: “Europe/Bratislava“

languages (array of Language, optional): – The languages the user knows. This is only provided in authenticated API requests.

first_name (string, optional): – User’s first name. This is only provided in authenticated API requests.
Example: “Alex“

last_name (string, optional): – User’s last name. This is only provided in authenticated API requests.
Example: “Morgan“

is_organization (boolean, optional): – Whether user is an organization. This is only provided in authenticated API requests.
Example: “False“

header_image (string, optional): – The header image used in the main profile card.
Example: “url('https://gravatar.com/userimage/209234789/cdebd0ed415kfa2g562ba5c34b1570c2') no-repeat 50% 1% / 100%“

background_color (string, optional): – The profile background color.
Example: “rgb(33, 0, 166)“

links (array of Link, optional): – A list of links the user has added to their profile. This is only provided in authenticated API requests.

interests (array of Interest, optional): – A list of interests the user has added to their profile. This is only provided in authenticated API requests.

payments (object, optional): – The user’s public payment information. This is only provided in authenticated API requests.

contact_info (object, optional): – The user’s contact information. This is only available if the user has chosen to make it public. This is only provided in authenticated API requests.

gallery (array of GalleryImage, optional): – Additional images a user has uploaded. This is only provided in authenticated API requests.

number_verified_accounts (integer, optional): – The number of verified accounts the user has added to their profile. This count includes verified accounts the user is hiding from their profile. This is only provided in authenticated API requests.
Example: “3“

last_profile_edit ([‘string’, ‘null’], optional): – The date and time (UTC) the user last edited their profile. This is only provided in authenticated API requests.
Example: “2021-10-01T12:00:00Z“

registration_date ([‘string’, ‘null’], optional): – The date the user registered their account. This is only provided in authenticated API requests.
Example: “2021-10-01T12:00:00Z“

VerifiedAccount

A verified account on a user’s profile.

Properties:

service_type (string, required): – The type of the service.
Example: “tumblr“

service_label (string, required): – The name of the service.
Example: “Tumblr“

service_icon (string, required): – The URL to the service’s icon.
Example: “https://gravatar.com/icons/tumblr-alt.svg“

url (string, required): – The URL to the user’s profile on the service.
Example: “https://example.tumblr.com/“

is_hidden (boolean, required): – Whether the verified account is hidden from the user’s profile.
Example: “False“

Versioning

This API adheres to semantic versioning. The current version is 3.0.0.

Last updated on: