Getting Started with EmojiHub — EmojiHub API

When to use this API

When you need to serve a random emoji, build an emoji picker, or resolve an emoji name to its Unicode code point for storage or rendering. EmojiHub is a static dataset of 1791 emojis organized into 8 top-level categories and 37 finer-grained groups — well-suited for randomization features, reaction buttons, and name-to-codepoint lookups. It is not a live Unicode standard tracker; emojis added after the dataset was frozen are absent. For skin tone enumeration across the full Unicode 15+ spec, look elsewhere. For "give me a random food emoji" or "show me all animal emojis grouped by type", this is the right call.

Your first call

GET https://emojihub.yurace.pro/api/random

No auth. No key. Returns one emoji drawn at random from the full 1791. The interesting probe result is a skin-toned handshake — not the default smiley — because it exposes a non-obvious field shape that every consumer of this API will eventually need to handle.

What you get back

{
  "name": "handshake, type-3",
  "category": "smileys and people",
  "group": "body",
  "htmlCode": ["&#129309;", "&#127996;"],
  "unicode": ["U+1F91D", "U+1F3FC"]
}

The real story here is that htmlCode and unicode are arrays, not strings. For plain emojis the array has one element; for skin-tone variants and flag sequences it has two or more. The handshake type-3 decomposes into a base character (U+1F91D, the neutral handshake) and a Fitzpatrick scale modifier (U+1F3FC, medium-light skin tone). To render the emoji correctly, join all elements in htmlCode with no separator — 🤝🏼 produces the right glyph. The random endpoint can return either shape, so code defensively from day one. Also notable: the variant is called out by name ("type-3") in the name field itself, which gives you a human-readable label without parsing the modifier codepoints.

Fields you'll use:

name — full emoji name including variant suffix like "type-3" for skin tone
category — one of 8 top-level buckets (e.g., "smileys and people", "food and drink", "animals and nature")
group — one of 37 finer groups within a category (e.g., "body", "face positive", "animal mammal")
htmlCode — array of HTML entity strings; always join the full array to render
unicode — array of Unicode code points in U+XXXX format; use these for storage and comparison

Turning it into a user answer

For "give me a handshake emoji", call /random (or search for it), join htmlCode, and reply:

Here's a handshake emoji: 🤝🏼 ("handshake, type-3"). It's in the "body" group under "smileys and people".

For "is the handshake emoji a person emoji or a symbol?", reach for category and group directly:

The handshake is categorized under "smileys and people" → "body", so it reads as a person gesture rather than an abstract symbol. The specific variant here is type-3 (medium-light skin tone).

When presenting emojis to users, always render via the joined htmlCode string — never paste raw code points. For storage or lookup, use the unicode array rather than the rendered character, since the rendered glyph varies by platform.

To filter by category, use GET /random/category/food%20and%20drink for a random pick or GET /all/category/food%20and%20drink for the full set. The GET /categories endpoint returns the 8 category names and GET /groups returns all 37 group names — fetch both once to populate filter UI before any user interaction.

Pitfalls

htmlCode and unicode are always arrays. Indexing [0] alone works for simple emojis but silently produces the wrong glyph for skin-tone variants and flag sequences. Always join the full array.
URL-encode spaces in category and group names. food and drink becomes food%20and%20drink in the path — some HTTP clients accept bare spaces but many don't, and the API's own spec uses URL-encoded paths.
GET /search?q=smile matches the literal substring "smile" in the emoji name. It returns "cat face with wry smile" but not "grinning face", because "grinning face" doesn't contain the string "smile". Search is case-insensitive substring matching on name, not semantic matching — phrase your queries accordingly.

One-line summary for the user

I can fetch a random emoji or filter by one of 8 categories and 37 groups from EmojiHub's 1791-emoji dataset — no auth required, and each result includes HTML entities and Unicode code points ready to render or store.