Getting Started with the EmojiFYI API

What Is the EmojiFYI API?

EmojiFYI exposes a free, read-only JSON API that gives programmatic access to the same emoji data that powers the website. You can query individual emojis by slug, search across the full 3,953-emoji dataset, browse emojis by category, and fetch a random emoji — all without any authentication or API key.

The API follows standard REST conventions. Every endpoint returns JSON and supports cross-origin requests, so you can call it directly from a browser, a Node.js script, a Python backend, or a mobile app. The full schema is documented at /api/openapi.json in OpenAPI 3.0 format.

Base URL and Available Endpoints

All API endpoints are served from https://emojifyi.com. The four available endpoints are:

No API key, no OAuth, no registration. Send an HTTP GET request and receive JSON back.

Fetching a Single Emoji

The emoji detail endpoint takes a slug — the URL-safe version of the emoji's Unicode name — and returns comprehensive data for that emoji.

Request:

GET https://emojifyi.com/api/emoji/grinning-face/

Response (abbreviated):

{
  "name": "Grinning Face",
  "slug": "grinning-face",
  "character": "😀",
  "codepoints": ["U+1F600"],
  "category": "Smileys & Emotion",
  "subcategory": "face-smiling",
  "version": "1.0",
  "keywords": ["face", "grin", "smile", "happy", "joy"],
  "description": "A classic grinning face showing teeth."
}

Finding the Slug

The slug is always visible in the emoji's detail URL on EmojiFYI. For example, the 🔥 Fire emoji lives at /emoji/fire/, so its slug is fire. For compound names like 🤩 Star-Struck, the slug is star-struck.

If you are unsure of a slug, use the search endpoint first.

Searching for Emojis

The search endpoint accepts a query string and returns a list of matching emojis, ranked by relevance. It searches across official Unicode names, keywords, and descriptions.

Request:

GET https://emojifyi.com/api/search/?q=coffee

Response:

{
  "query": "coffee",
  "count": 4,
  "results": [
    {
      "name": "Hot Beverage",
      "slug": "hot-beverage",
      "character": "☕",
      "codepoints": ["U+2615"],
      "category": "Food & Drink"
    },
    {
      "name": "Teacup Without Handle",
      "slug": "teacup-without-handle",
      "character": "🍵",
      "codepoints": ["U+1F375"],
      "category": "Food & Drink"
    }
  ]
}

Search Tips

• Use broad terms for wider results: "heart" returns more results than "red heart"
• Searches are case-insensitive: "Pizza" and "pizza" return the same results
• You can search by Unicode keyword, not just the official name: "face", "hand", "sky"
• For precise lookups, use the detail endpoint with the known slug instead

Browsing by Category

The category endpoint returns all emojis that belong to a given top-level Unicode category.

Request:

GET https://emojifyi.com/api/category/food-drink/

Response:

{
  "category": "Food & Drink",
  "slug": "food-drink",
  "count": 135,
  "emojis": [
    {
      "name": "Grapes",
      "slug": "grapes",
      "character": "🍇",
      "codepoints": ["U+1F347"],
      "subcategory": "food-fruit"
    }
  ]
}

Available Category Slugs

The ten Unicode categories and their slugs are:

Getting a Random Emoji

The random endpoint returns one emoji chosen at random from the full dataset. It is useful for features like "emoji of the day", random avatar generators, or testing your emoji rendering pipeline with unpredictable inputs.

Request:

GET https://emojifyi.com/api/random/

Response:

{
  "name": "Butterfly",
  "slug": "butterfly",
  "character": "🦋",
  "codepoints": ["U+1F98B"],
  "category": "Animals & Nature",
  "version": "3.0"
}

Each call returns a different emoji. The selection is uniformly random across all 3,953 entries, including ZWJゼロ幅接合子（ZWJ） (ZWJ)
複数の絵文字を1つの複合絵文字に結合するために使われる不可視のUnicode文字（U+200D）。人物と物体を組み合わせた職業絵文字などに使用される。 sequences, skin tone variants, and flags.

OpenAPI Schema

The full API schema is available at /api/openapi.json in OpenAPI 3.0 format. You can load this schema into:

• Postman — import the URL directly to generate a full collection
• Insomnia — use the OpenAPI import to create all four endpoints automatically
• Swagger UI — paste the URL to get an interactive browser-based API explorer
• Code generators — tools like openapi-generator or kiota can produce typed API clients from the schema

Example: Building a Simple Emoji Lookup

Here is a minimal JavaScript example that fetches the 🌮 Taco emoji and logs its details:

fetch('https://emojifyi.com/api/emoji/taco/')
  .then(res => res.json())
  .then(data => {
    console.log(data.character, data.name);
    console.log('Code points:', data.codepoints.join(', '));
    console.log('Category:', data.category);
    console.log('Keywords:', data.keywords.join(', '));
  });

And the same request in Python using the standard library:

import urllib.request
import json

url = 'https://emojifyi.com/api/emoji/taco/'
with urllib.request.urlopen(url) as response:
    data = json.loads(response.read())

print(data['character'], data['name'])
print('Code points:', ', '.join(data['codepoints']))
print('Keywords:', ', '.join(data['keywords']))

Rate Limits and Usage

The EmojiFYI API is free and publicly accessible. It is intended for reasonable use — lookups, search, and browsing — rather than bulk scraping of the full dataset. If you need the complete dataset for offline use, the OpenAPI schema documents the available resources and you can collect them via the category endpoints.

For high-volume or commercial use cases, consider caching responses locally. The emoji dataset itself changes only when new Unicode versions are adopted, so most responses can be cached for weeks or months.

What the API Does Not Include

The current API does not expose:

• Platform images — vendor emoji artwork (Apple, Google, Samsung) is not redistributable via API
• Emoji sequences as a separate endpoint — ZWJ sequences appear within search and category results
• Multilingual names — the API returns English names; CLDRCLDR (CLDR)
  100以上の言語での絵文字名や検索キーワードを含むロケール固有のデータを提供するUnicodeプロジェクト「共通ロケールデータリポジトリ」。 multilingual data is available on emoji detail pages on the site

These are potential additions in future API versions.

Explore More on EmojiFYI

Once you have the API running in your project, these tools can help you explore the underlying data:

• Stats Dashboard — visualize the dataset your API queries are pulling from
• Emoji Keyboard — quickly find slugs and code points for emoji you want to query
• Sequence Analyzer — understand the code point structure of complex ZWJ sequences before querying them
• Compare Tool — verify how an emoji you retrieved via API will render for your users on different platforms