# Gravatar API
> Turn an email address into its Gravatar avatar and public profile. Pass an email and the service normalises it, computes the MD5 and SHA-256 hashes Gravatar uses, builds a ready-to-use avatar URL, checks whether a custom Gravatar actually exists, and fetches the public profile when present — display name, username, profile URL, location, about text, linked accounts and photos. A dedicated avatar endpoint builds just the image URL with full options: size (1-2048), a default image (identicon, monsterid, robohash, retro, mp, blank, 404, or your own URL), rating and force-default. Ideal for user-profile enrichment, comment systems, contact cards, team pages and onboarding — showing a real avatar from nothing but an email. A Gravatar lookup — distinct from deterministic avatar/identicon generation (avatar), which renders a brand-new image from a seed rather than fetching the avatar a person actually chose. No upstream key, no cache.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/gravatar-api/..."
```

## Pricing
- **Free** (Free) — 2,120 calls/Mo, 2 req/s
- **Starter** ($6/Mo) — 41,000 calls/Mo, 8 req/s
- **Pro** ($20/Mo) — 216,000 calls/Mo, 20 req/s
- **Mega** ($53/Mo) — 820,000 calls/Mo, 50 req/s

## Endpoints

### Gravatar

#### `GET /v1/avatar` — Build the avatar URL

**Parameters:**
- `email` (query, required, string) — Email address Example: `test@example.com`
- `size` (query, optional, string) — Avatar size 1-2048 Example: `200`
- `default` (query, optional, string) — identicon, monsterid, robohash, retro, mp, 404, blank

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gravatar-api/v1/avatar?email=test%40example.com&size=200"
```

**Response:**
```json
{
    "data": {
        "email": "test@example.com",
        "hash_md5": "55502f40dc8b7c769880b10874abc9d0",
        "avatar_url": "https://gravatar.com/avatar/55502f40dc8b7c769880b10874abc9d0?s=200",
        "hash_sha256": "973dfe463ec85785f5f95af5ba3906eedb2d931c24e69824a89ea65dba4e813b"
    },
    "meta": {
        "timestamp": "2026-06-01T23:40:42.451Z",
        "request_id": "fcae90cb-c82c-487a-b875-7cabe4b03f09"
    },
    "status": "ok",
    "message": "Avatar URL built",
    "success": true
}
```

#### `GET /v1/lookup` — Avatar + existence + profile

**Parameters:**
- `email` (query, required, string) — Email address Example: `beau@dentedreality.com.au`
- `size` (query, optional, string) — Avatar size 1-2048
- `default` (query, optional, string) — Default image style

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gravatar-api/v1/lookup?email=beau%40dentedreality.com.au"
```

**Response:**
```json
{
    "data": {
        "email": "beau@dentedreality.com.au",
        "profile": {
            "about": "Lead of WooCommerce, at Automattic. Previously Jetpack, WordPress.com and more. I've been building the web for over 20 years.",
            "photos": [
                "https://0.gravatar.com/avatar/22bd03ace6f176bfe0c593650bcf45d8"
            ],
            "accounts": [
                {
                    "url": "https://x.com/beaulebens",
                    "name": "twitter"
                },
                {
                    "url": "https://www.linkedin.com/in/beaulebens",
                    "name": "linkedin"
                },
                {
                    "url": "https://github.com/beaulebens",
                    "name": "github"
                },
                {
                    "url": "https://instagram.com/beaulebens",
                    "name": "instagram"
                }
            ],
            "location": "Golden, CO",
            "username": "beau",
            "thumbnail": "https://0.gravatar.com/avatar/22bd03ace6f176bfe0c593650bcf45d8",
            "profile_url": "https://gravatar.com/beau",
            "display_name": "Beau Lebens"
        },
        "hash_md5": "205e460b479e2e5b48aec07710c08d50",
        "avatar_url": "https://gravatar.com/avatar/205e460b479e2e5b48aec07710c08d50",
        "has_avatar": true,
        "has_profile": true,
        "hash_sha256": "a919f0e9932ec2c866cf67ec327efb57b47ff3085acd375529af076d1ac56f27"
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Defaults & size range

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/gravatar-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Turn an email address into its Gravatar avatar and public profile. /v1/lookup?email=user@example.com normalises the address, computes the MD5 and SHA-256 hashes Gravatar uses, builds the avatar URL, checks whether a custom Gravatar actually exists (has_avatar), and fetches the public profile when present — display name, username, profile URL, location, about, linked accounts and photos. /v1/avatar builds just the avatar URL with options: size (1-2048), a default image (identicon, monsterid, robohash, retro, mp, 404, blank or your own https URL), forcedefault and rating. Computation is local; the lookup makes live calls to gravatar.com. Ideal for user-profile enrichment, comment systems, contact cards and onboarding — showing a real avatar from an email. A Gravatar lookup — distinct from deterministic avatar/identicon generation (avatar), which makes a new image from a seed rather than fetching a person's chosen Gravatar. No key, no cache.",
        "endpoints": [
            "/v1/lookup",
            "/v1/avatar",
            "/v1/meta"
        ],
        "size_range": [
            1,
            2048
        ],
        "default_images": [
            "404",
            "mp",
            "identicon",
            "monsterid",
            "wavatar",
            "retro",
            "robohash",
            "blank"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T23:40:43.567Z",
        "request_id": "f322b5c4-c322-417d-a957-
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/gravatar-api
OpenAPI spec: https://www.oanor.com/api/gravatar-api/openapi.json