# Emoji API
> A complete emoji database in one fast API. Search roughly 1,870 emojis by name, keyword, alias or tag, look up a single emoji by its alias (like rocket or :fire:) or by the emoji character itself, browse any of the nine Unicode categories, or get random emojis (optionally from a category). Every emoji comes with its name, category, aliases, search tags, Unicode code points and the version it was introduced in. Built on the open GitHub gemoji dataset and served entirely in-memory, so responses are instant and the service is always available. Ideal for chat and messaging apps, emoji pickers and search, social and content tools, games and fun widgets.

## 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/emoji-api/..."
```

## Pricing
- **Free** (Free) — 5,000 calls/Mo, 3 req/s
- **Basic** ($5/Mo) — 150,000 calls/Mo, 12 req/s
- **Pro** ($14/Mo) — 1,000,000 calls/Mo, 30 req/s
- **Mega** ($38/Mo) — 6,000,000 calls/Mo, 80 req/s

## Endpoints

### Emoji

#### `GET /v1/category` — Emojis by category (or list categories)

**Parameters:**
- `name` (query, optional, string) — Category name (omit to list all with counts) Example: `Food & Drink`
- `limit` (query, optional, string) — 1-1000 (default 100) Example: `100`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/emoji-api/v1/category?name=Food+%26+Drink&limit=100"
```

**Response:**
```json
{
    "data": {
        "count": 100,
        "emojis": [
            {
                "name": "grapes",
                "tags": [],
                "emoji": "🍇",
                "aliases": [
                    "grapes"
                ],
                "category": "Food & Drink",
                "codepoints": "U+1F347",
                "unicode_version": "6.0"
            },
            {
                "name": "melon",
                "tags": [],
                "emoji": "🍈",
                "aliases": [
                    "melon"
                ],
                "category": "Food & Drink",
                "codepoints": "U+1F348",
                "unicode_version": "6.0"
            },
            {
                "name": "watermelon",
                "tags": [],
                "emoji": "🍉",
                "aliases": [
                    "watermelon"
                ],
                "category": "Food & Drink",
                "codepoints": "U+1F349",
                "unicode_version": "6.0"
            },
            {
                "name": "tangerine",
                "tags": [],
                "emoji": "🍊",
                "aliases": [
                    "tangerine",
                    "orange",
                    "mandarin"
                ],
                "category": "Food & Drink",
                "codepoints": "U+1F34A",
                "unicode_version": "6.0"
            },
            {
                "name": "lemon",
             
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/emoji` — Lookup one emoji

**Parameters:**
- `alias` (query, required, string) — Alias (e.g. rocket, :fire:) or the emoji character Example: `rocket`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/emoji-api/v1/emoji?alias=rocket"
```

**Response:**
```json
{
    "data": {
        "name": "rocket",
        "tags": [
            "ship",
            "launch"
        ],
        "emoji": "🚀",
        "aliases": [
            "rocket"
        ],
        "category": "Travel & Places",
        "codepoints": "U+1F680",
        "unicode_version": "6.0"
    },
    "meta": {
        "timestamp": "2026-05-30T18:16:51.273Z",
        "request_id": "079ab25b-0562-4028-812a-e771a9f75ce9"
    },
    "status": "ok",
    "message": "Emoji retrieved",
    "success": true
}
```

#### `GET /v1/random` — Random emojis

**Parameters:**
- `count` (query, optional, string) — 1-50 (default 1) Example: `3`
- `category` (query, optional, string) — Limit to a category

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/emoji-api/v1/random?count=3"
```

**Response:**
```json
{
    "data": {
        "count": 3,
        "emojis": [
            {
                "name": "chains",
                "tags": [],
                "emoji": "⛓️",
                "aliases": [
                    "chains"
                ],
                "category": "Objects",
                "codepoints": "U+26D3 U+FE0F",
                "unicode_version": "5.2"
            },
            {
                "name": "Libra",
                "tags": [],
                "emoji": "♎",
                "aliases": [
                    "libra"
                ],
                "category": "Symbols",
                "codepoints": "U+264E",
                "unicode_version": ""
            },
            {
                "name": "woman vampire",
                "tags": [],
                "emoji": "🧛‍♀️",
                "aliases": [
                    "vampire_woman"
                ],
                "category": "People & Body",
                "codepoints": "U+1F9DB U+200D U+2640 U+FE0F",
                "unicode_version": "11.0"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-05-30T18:16:51.332Z",
        "request_id": "66a1c1f1-8ac9-444b-8da9-0e64d9380692"
    },
    "status": "ok",
    "message": "Random emojis retrieved",
    "success": true
}
```

#### `GET /v1/search` — Search emojis

**Parameters:**
- `q` (query, required, string) — Name, keyword, alias or tag Example: `happy`
- `limit` (query, optional, string) — 1-200 (default 30) Example: `30`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/emoji-api/v1/search?q=happy&limit=30"
```

**Response:**
```json
{
    "data": {
        "count": 4,
        "query": "happy",
        "emojis": [
            {
                "name": "grinning face",
                "tags": [
                    "smile",
                    "happy"
                ],
                "emoji": "😀",
                "aliases": [
                    "grinning"
                ],
                "category": "Smileys & Emotion",
                "codepoints": "U+1F600",
                "unicode_version": "6.1"
            },
            {
                "name": "grinning face with big eyes",
                "tags": [
                    "happy",
                    "joy",
                    "haha"
                ],
                "emoji": "😃",
                "aliases": [
                    "smiley"
                ],
                "category": "Smileys & Emotion",
                "codepoints": "U+1F603",
                "unicode_version": "6.0"
            },
            {
                "name": "grinning face with smiling eyes",
                "tags": [
                    "happy",
                    "joy",
                    "laugh",
                    "pleased"
                ],
                "emoji": "😄",
                "aliases": [
                    "smile"
                ],
                "category": "Smileys & Emotion",
                "codepoints": "U+1F604",
                "unicode_version": "6.0"
            },
            {
                "name": "grinning squinting face
…(truncated, see openapi.json for full schema)
```


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