emojistry

App-friendly emoji data, search helpers, and a hosted REST API backed by Unicode emoji data.

Emojistry provides a versioned emoji registry with normalized names, codepoints, Unicode groups, app categories, keywords, skin-tone metadata, and sequence metadata.

Install

npm install emojistry

bun add emojistry

Package Usage

Use the generated registry data directly from the package:

import snapshot from "emojistry/data";
import { groupByCategory, searchEmojis } from "emojistry";

const hearts = searchEmojis(snapshot.emojis, "heart");
const faces = groupByCategory(snapshot.emojis).faces;

Find a single emoji by emoji, slug, exact name, or codepoint:

import snapshot from "emojistry/data";
import { findEmoji } from "emojistry";

const rocket = findEmoji(snapshot.emojis, "rocket");
const grinning = findEmoji(snapshot.emojis, "U+1F600");

Parse and normalize Unicode emoji-test.txt data:

import { normalizeEmojiEntries, parseEmojiTest } from "emojistry";

const source = await fetch("https://unicode.org/Public/emoji/latest/emoji-test.txt").then((res) =>
	res.text(),
);
const emojis = normalizeEmojiEntries(parseEmojiTest(source));

Data Shape

interface EmojiRecord {
	emoji: string;
	codepoints: string[];
	qualification: "fully-qualified" | "minimally-qualified" | "unqualified" | "component";
	emojiVersion: string;
	name: string;
	group: string;
	subgroup: string;
	slug: string;
	category: EmojiCategory;
	keywords: string[];
	hasSkinTone: boolean;
	isSequence: boolean;
}

REST API

Hosted API:

https://api.emojistry.kfiros.com

Endpoints

GET /health
GET /health/badge
GET /v1
GET /v1/emojis
GET /v1/emojis/:emoji-or-slug-or-codepoint
GET /v1/search?q=heart
GET /v1/categories
GET /v1/categories/:category/emojis

List endpoints support:

limit=100
offset=0

GET /v1/emojis also supports:

q=heart
category=faces
group=Smileys%20%26%20Emotion
subgroup=face-smiling

Examples

curl https://api.emojistry.kfiros.com/health

curl https://api.emojistry.kfiros.com/health/badge

curl "https://api.emojistry.kfiros.com/v1/search?q=heart&limit=3"

curl https://api.emojistry.kfiros.com/v1/emojis/grinning-face

Categories

Emojistry maps Unicode groups to app-friendly categories:

faces
people
animals-nature
food-drink
travel-places
activities
objects
symbols
flags
components
other

Development

Project setup, data generation, package publishing, and deployment notes live in docs/development.md and docs/deployment.md.

License

MIT. See LICENSE for the full license text.