Name: Emoji Search API: Keyword, Shortcode and Category Lookup
Brand: tidydata
SKU: api-tidydata-emoji-search
Availability: InStock
Author: API Market

TidyData

# Emoji Search API

## Overview

The Emoji Search API covers the full Emoji 17 set, 1,949 emojis, with five GET endpoints. /v1/emoji/search ranks emojis for a keyword by matching names, shortcodes and keywords. /v1/emoji/{emoji} returns the details for one emoji, which you can identify by the character itself, its hexcode (1F525) or a shortcode (:fire:). /v1/emoji/categories lists the categories with a count for each, /v1/emoji/category/{name} lists the emojis in one category, and /v1/emoji/random returns a random selection, optionally limited to a category.

Each emoji record includes the character, hexcode, name, keyword list, category and subcategory, Unicode version, a skin tone flag, shortcodes and the HTML entity, and the single emoji endpoint also returns codepoints in U+ notation. Names and keywords are localized in English, Spanish, German, French, Italian and Portuguese through the locale parameter. It suits developers building emoji pickers, autocomplete in chat and editors, social media tools, bots and accessibility features that need a readable name for each emoji. Data is from Emojibase (MIT) and buyers only need the x-api-market-key header.

## Features

*   **5 endpoints**: Keyword search, single emoji details, category list, emojis by category and random emojis.
*   **Emoji 17 coverage**: All 1,949 emojis with names, keywords, category, subcategory, Unicode version and skin tone flag.
*   **Flexible lookup**: Find one emoji by the character, its hexcode (1F525) or a shortcode (:fire:).
*   **6 languages**: Set locale to en, es, de, fr, it or pt for localized names and keywords.
*   **Developer friendly fields**: Shortcodes, HTML entities and codepoints are returned ready to use in markup and chat apps.
*   **Ranked search with limits**: Search results are ranked by name, shortcode and keyword matches, with limit from 1 to 100.
*   **10 requests per second**: All plans allow up to 10 requests per second, suitable for live autocomplete.

## Use Cases

*   **Emoji pickers and autocomplete**: Chat apps and text editors can suggest emojis as users type a word or a :shortcode:.
*   **Social media tools**: Scheduling and caption tools can turn post keywords into matching emojis.
*   **Accessibility**: Apps can show or read out the emoji name for screen reader users.
*   **Localized apps**: Products serving Spanish, German, French, Italian or Portuguese users can search with native keywords.
*   **Games and bots**: Discord or Slack bots and casual games can pull random emojis, optionally from one category.

## API Documentation

### Base URL

All requests go through the API.market gateway at this base URL:

```
https://prod.api.market/api/v1/tidydata/emoji-search
```

### Authentication

Every request needs your API.market key in the `x-api-market-key` header:

```
x-api-market-key: YOUR_API_KEY
```

Replace `YOUR_API_KEY` with your actual API key.

### Endpoints

#### 1. Search emojis by keyword

Returns emojis ranked by how well their name, shortcodes and keywords match the q keyword, with a count and full record for each. Use locale to search in another language and limit (1 to 100) to cap results.

**Method:** `GET`

**Endpoint:** `/v1/emoji/search`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `q` | query | Keyword | string | Yes | - | - |
| `locale` | query | en, es, de, fr, it or pt | string | No | - | - |
| `limit` | query | 1-100 | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/emoji-search/v1/emoji/search?q=laugh&locale=en&limit=20" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "query": "laugh",
  "locale": "en",
  "count": 6,
  "results": [
    {
      "emoji": "🤣",
      "hexcode": "1F923",
      "name": "rolling on the floor laughing",
      "keywords": [
        "crying",
        "face",
        "floor"
      ],
      "category": "smileys & emotion",
      "subcategory": "smiling",
      "unicodeVersion": 3,
      "skinTones": false,
      "shortcodes": [
        ":rofl:"
      ],
      "htmlEntity": "&#x1F923;"
    },
    {
      "emoji": "😀",
      "hexcode": "1F600",
      "name": "grinning face",
      "keywords": [
        "cheerful",
        "cheery",
        "face"
      ],
      "category": "smileys & emotion",
      "subcategory": "smiling",
      "unicodeVersion": 1,
      "skinTones": false,
      "shortcodes": [
        ":grinning:"
      ],
      "htmlEntity": "&#x1F600;"
    },
    {
      "emoji": "😄",
      "hexcode": "1F604",
      "name": "grinning face with smiling eyes",
      "keywords": [
        "eye",
        "eyes",
        "face"
      ],
      "category": "smileys & emotion",
      "subcategory": "smiling",
      "unicodeVersion": 0.6,
      "skinTones": false,
      "shortcodes": [
        ":smile:"
      ],
      "htmlEntity": "&#x1F604;"
    }
  ],
  "attribution": "Emoji data: Emojibase (MIT)"
}
```

#### 2. Get emoji details

Returns the full record for one emoji, including codepoints, given the emoji character, its hexcode such as 1F525 or a shortcode such as :fire:.

**Method:** `GET`

**Endpoint:** `/v1/emoji/{emoji}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `emoji` | path | Emoji character, hexcode (1F525) or shortcode (:fire:) | string | Yes | - | - |
| `locale` | query | en, es, de, fr, it or pt | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/emoji-search/v1/emoji/search?q=laugh&locale=en&limit=20" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "query": "laugh",
  "locale": "en",
  "count": 6,
  "results": [
    {
      "emoji": "🤣",
      "hexcode": "1F923",
      "name": "rolling on the floor laughing",
      "keywords": [
        "crying",
        "face",
        "floor"
      ],
      "category": "smileys & emotion",
      "subcategory": "smiling",
      "unicodeVersion": 3,
      "skinTones": false,
      "shortcodes": [
        ":rofl:"
      ],
      "htmlEntity": "&#x1F923;"
    },
    {
      "emoji": "😀",
      "hexcode": "1F600",
      "name": "grinning face",
      "keywords": [
        "cheerful",
        "cheery",
        "face"
      ],
      "category": "smileys & emotion",
      "subcategory": "smiling",
      "unicodeVersion": 1,
      "skinTones": false,
      "shortcodes": [
        ":grinning:"
      ],
      "htmlEntity": "&#x1F600;"
    },
    {
      "emoji": "😄",
      "hexcode": "1F604",
      "name": "grinning face with smiling eyes",
      "keywords": [
        "eye",
        "eyes",
        "face"
      ],
      "category": "smileys & emotion",
      "subcategory": "smiling",
      "unicodeVersion": 0.6,
      "skinTones": false,
      "shortcodes": [
        ":smile:"
      ],
      "htmlEntity": "&#x1F604;"
    }
  ],
  "attribution": "Emoji data: Emojibase (MIT)"
}
```

#### 3. List categories

Returns every emoji category with the number of emojis in it. Use it to build category tabs in a picker.

**Method:** `GET`

**Endpoint:** `/v1/emoji/categories`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `locale` | query | en, es, de, fr, it or pt | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/emoji-search/v1/emoji/categories?locale=en" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "locale": "en",
  "categories": [
    {
      "name": "smileys & emotion",
      "count": 171
    },
    {
      "name": "people & body",
      "count": 388
    },
    {
      "name": "components",
      "count": 9
    }
  ]
}
```

#### 4. List emojis in a category

Returns the emojis in the named category. Through API.market, use a single word category name such as activities, objects, symbols, flags or components.

**Method:** `GET`

**Endpoint:** `/v1/emoji/category/{name}`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `name` | path | Category name | string | Yes | - | - |
| `locale` | query | en, es, de, fr, it or pt | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/emoji-search/v1/emoji/category/activities?locale=en" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "category": "activities",
  "count": 85,
  "emojis": [
    {
      "emoji": "🎃",
      "hexcode": "1F383",
      "name": "jack-o-lantern",
      "keywords": [
        "celebration",
        "halloween",
        "jack"
      ],
      "category": "activities",
      "subcategory": "events & holidays",
      "unicodeVersion": 0.6,
      "skinTones": false,
      "shortcodes": [
        ":jack_o_lantern:"
      ],
      "htmlEntity": "&#x1F383;"
    },
    {
      "emoji": "🎄",
      "hexcode": "1F384",
      "name": "Christmas tree",
      "keywords": [
        "celebration",
        "christmas",
        "tree"
      ],
      "category": "activities",
      "subcategory": "events & holidays",
      "unicodeVersion": 0.6,
      "skinTones": false,
      "shortcodes": [
        ":christmas_tree:"
      ],
      "htmlEntity": "&#x1F384;"
    },
    {
      "emoji": "🎆",
      "hexcode": "1F386",
      "name": "fireworks",
      "keywords": [
        "boom",
        "celebration",
        "entertainment"
      ],
      "category": "activities",
      "subcategory": "events & holidays",
      "unicodeVersion": 0.6,
      "skinTones": false,
      "shortcodes": [
        ":fireworks:"
      ],
      "htmlEntity": "&#x1F386;"
    }
  ]
}
```

#### 5. Get random emojis

Returns between 1 and 50 random emojis set by count, optionally restricted to one category. Useful for games, placeholders and bots.

**Method:** `GET`

**Endpoint:** `/v1/emoji/random`

**Parameters:**

| Name | In | Description | Type | Required | Default | Max Value |
|---|---|---|---|---|---|---|
| `count` | query | 1-50 | string | No | - | - |
| `category` | query | Optional category | string | No | - | - |
| `locale` | query | en, es, de, fr, it or pt | string | No | - | - |

**Example Request:**

```bash
curl -X GET "https://prod.api.market/api/v1/tidydata/emoji-search/v1/emoji/random?count=3&category=&locale=en" \
  -H "x-api-market-key: YOUR_API_KEY"
```

**Example Response (200 OK, abridged):**

```json
{
  "count": 3,
  "emojis": [
    {
      "emoji": "🐒",
      "hexcode": "1F412",
      "name": "monkey",
      "keywords": [
        "animal",
        "banana"
      ],
      "category": "animals & nature",
      "subcategory": "mammals",
      "unicodeVersion": 0.6,
      "skinTones": false,
      "shortcodes": [
        ":monkey:"
      ],
      "htmlEntity": "&#x1F412;"
    },
    {
      "emoji": "🔲",
      "hexcode": "1F532",
      "name": "black square button",
      "keywords": [
        "black",
        "button",
        "geometric"
      ],
      "category": "symbols",
      "subcategory": "shapes & colors",
      "unicodeVersion": 0.6,
      "skinTones": false,
      "shortcodes": [
        ":black_square_button:"
      ],
      "htmlEntity": "&#x1F532;"
    },
    {
      "emoji": "🎸",
      "hexcode": "1F3B8",
      "name": "guitar",
      "keywords": [
        "instrument",
        "music",
        "strat"
      ],
      "category": "objects",
      "subcategory": "musical instruments",
      "unicodeVersion": 0.6,
      "skinTones": false,
      "shortcodes": [
        ":guitar:"
      ],
      "htmlEntity": "&#x1F3B8;"
    }
  ]
}
```

## Status Codes

| Code | Status | Description |
|---|---|---|
| 200 | OK | The request succeeded and the result is in the response body. |
| 400 | Bad Request | A required parameter is missing or a value is invalid. The body explains the problem. |
| 401 | Unauthorized | The `x-api-market-key` header is missing, invalid or expired. |
| 403 | Forbidden | Your subscription does not include this endpoint. |
| 404 | Not Found | The requested item or path does not exist. |
| 429 | Too Many Requests | You went over 10 requests per second or used up your plan quota. |
| 500 | Internal Server Error | Something failed while processing the request. Retry after a short delay. |

## Rate Limits

Every plan allows 10 requests per second. The Pro plan includes 25,000 calls a month and the Ultra plan 150,000; when a monthly quota is used up, further calls return `429 Too Many Requests` until the next billing period. The pay-as-you-go plan has no quota and bills US$0.0005 per successful call. If you receive a `429`, back off before retrying and honour any `Retry-After` header.

## FAQ

**How do I look up a single emoji?**

Call /v1/emoji/{emoji} with the emoji character, its hexcode (for example 1F525) or a shortcode (for example :fire:). All three return the same record, including codepoints.

**Which categories can I use with /v1/emoji/category/{name}?**

The categories endpoint returns: smileys & emotion, people & body, components, animals & nature, food & drink, travel & places, activities, objects, symbols and flags. Through API.market, names that contain spaces or "&" (for example "food & drink") currently fail at the gateway with a 400 "API Path invalid" error. Single word categories work: components, activities, objects, symbols and flags. For the other categories, use search or filter the results of other calls by the category field.

**Which languages are supported?**

English, Spanish, German, French, Italian and Portuguese. Set locale to en, es, de, fr, it or pt; it applies to search, details, categories, category listing and random.

**How many results can a search return?**

Set limit between 1 and 100. The response includes a count of the results returned. For random emojis, count can be 1 to 50.

**Which emoji version and data source does it use?**

It covers Emoji 17 (1,949 emojis) using data from Emojibase, released under the MIT license. Search and detail responses include an attribution field.

**How much does it cost?**

There is no free plan. Pay as you go costs US$0.0005 per call with no monthly fee. Pro is US$4.99 per month for 25,000 calls and Ultra is US$14.99 per month for 150,000 calls. Every plan allows 10 requests per second.

## Contact Us

If you have any questions or need assistance, you can reach out to us through the embedded chat on the bottom right corner of the page or send an email to hello@magicapi.com.


Emoji search API with Emoji 17 data. Search by keyword, look up by character, hexcode or :shortcode:, list categories and get random emojis in 6 languages.