Emoji API

Lookup#

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.emoji("rocket");
console.log(result);

{
  "emoji": "🚀",
  "name": "Rocket",
  "shortcodes": [
    ":rocket:",
    "rocket"
  ],
  "category": "Travel & Places"
}

Text and emoji presentation forms resolve to the canonical emoji. For example, ❤ resolves to ❤️. Names accept spaces, underscores and hyphens. Hex forms such as 1F680, U+1F680, and 2764-FE0F also resolve. URL-encode the entire input, including plus signs.

Use shortcode_source=cldr, github, slack, or discord to choose an alias source. CLDR uses pinned English annotation aliases, including the reviewed Emoji 18 additions. GitHub uses the Emojibase github preset. Slack uses iamcal and Discord uses joypixels. These community mappings may differ from a platform release and do not guarantee exact Slack or Discord compatibility. Existing primary names and shortcodes keep their meaning. An ambiguous additional shortcode returns 400.

Search#

Keyword and prefix search for pickers and typeahead. ?limit= caps results, default 20, max 50.

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.emoji.search("fire", { limit: 2 });
console.log(result);

{
  "q": "fire",
  "emojis": [
    {
      "emoji": "🔥",
      "name": "Fire",
      "shortcodes": [
        ":fire:",
        "fire"
      ],
      "category": "Travel & Places"
    },
    {
      "emoji": "🚒",
      "name": "Fire Engine",
      "shortcodes": [
        ":fire_engine:",
        "fire_engine"
      ],
      "category": "Travel & Places"
    }
  ]
}

Browse and filter#

Use category and subcategory to narrow the catalog. version selects the version that introduced a sequence. max_version includes sequences introduced up to that version. include_skin_tones=false keeps the base emoji in picker results. Existing search includes skin tones by default. Filters combine with q.

offset starts a page and limit defaults to 20, up to 50. Paged and filtered responses include total, the matches before pagination, and next_offset, or null at the end. Deep adds the parent base for a variant, omitted when there is no parent, and additional variants for mixed-tone choices not already listed in skins.

Use lang for translated names and keyword search. Characters, canonical identities and shortcodes stay stable. Missing translations keep the English label. Catalog downloads report the requested and resolved language, translated count, fallback count in localization.

Find emoji in text#

{"text":"Great work 👏🏽! 👏🏽 See you Friday 🎉"}

The response contains one record per unique emoji in emojis, ordered by first appearance. Each record adds positions for every occurrence. Position start and end use UTF-16 offsets with an exclusive end, matching JavaScript string slicing. Joined families, flags and mixed-tone sequences count as one emoji. Unsupported sequences are omitted as a whole. Send text in the body, up to 16,000 UTF-16 code units, matching JavaScript text.length. Each request uses one pooled request on every plan.

Convert text and shortcodes#

{"text":"Great work :rocket:! Keep :unknown_code: unchanged."}

Choose to_emoji or to_shortcodes and a required shortcode_source. The response contains converted text, unresolved tokens with their positions and reasons. Unknown, ambiguous and unavailable aliases stay literal, with a reason in unresolved. Encoding chooses an alias that resolves uniquely back to the same complete sequence. Positions always refer to the original input in UTF-16 code units. The same text limit and pooled request pricing apply.

Artwork#

Display emoji as text to use the device emoji font. For a consistent image style or graphics export, Deep includes available original SVG/PNG links from Noto, Twemoji and OpenMoji. Use deep.artwork.openmoji.svg for SVG or deep.artwork.openmoji.png["72"] for a 72×72 PNG. The same structure applies to noto and twemoji. Load the returned URL directly. Unavailable styles and formats are omitted. PNG keys are pixel sizes, not Unicode codes. URLs pin immutable artwork editions. Noto uses ParseAPI edition 18.0.0 for Google's Unicode 18 release; Twemoji and OpenMoji use their numbered releases. /emoji/metadata supplies shared credits, licences and immutable notice links. Per-image rights appear only when different from the provider.

Artwork coverage follows each source release. Noto supplies Emoji 18 SVGs, including flags with their separate source notices. Twemoji and OpenMoji currently supply Emoji 17 artwork. Preserve the individual credit and license. OpenMoji adaptations must keep CC BY-SA 4.0. Artwork attribution.

Download and work offline#

A new catalog download uses one pooled request on your existing plan. Searching and selecting from the downloaded copy use none. Refresh the file at build time or on your release schedule to adopt catalog updates. The downloaded copy stays unchanged until you replace it.

The default compact catalog includes names, keywords, tone relationships, lookup maps and data notices. Each record has the Deep fields needed for local search and tone selection. Use profile=full for artwork links and extended Unicode detail. Keep the returned profile with your snapshot.

emojis contains the downloaded records. The forms, shortcodes and legacy maps reference only those records. total is the downloaded count. scope identifies the selected filters and whether the download contains the full server inventory, which metadata describes. The same category, subcategory, version and skin-tone filters apply. Use lang for translated names and keywords with English fallbacks. Retain the data notices. Images are separate files with their own notices in metadata.artwork_sources.

Unicode's official emoji test data defines the characters and sequences. /emoji/metadata returns the source editions and notices used by this catalog.

const response = await fetch(
  'https://api.parseapi.com/emoji/catalog',
  { headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Parse-Version': '2.0.0',
  } },
);
if (!response.ok) throw new Error('Catalog download failed.');
const snapshot = await response.json();

// Store the snapshot and its notices with your application.
const canonicalHeart = snapshot.forms['❤']; // ❤️
const heart = snapshot.emojis.find(row => row.emoji === canonicalHeart);
console.log(heart.name);

With lang, search.native retains English matching alongside the translation. Send the returned ETag unchanged in If-None-Match for the same language, profile and filters. A matching 304 for catalog or metadata uses the ordinary rate limit but no pooled request, and creates no customer lookup-history entry. Completeness compares the loaded inventory to the pinned Unicode dataset.

Use the JavaScript client#

JavaScript SDK 1.10.1 includes hosted Emoji calls and an optional catalog helper for local lookup, search and parsing.

import { parseAPI } from '@parseapi/sdk';
import { EmojiCatalog } from '@parseapi/sdk/offline';

const parse = parseAPI('your-api-key');
const snapshot = await parse.emoji.catalog();
const local = new EmojiCatalog(snapshot);

local.lookup('❤');              // canonical ❤️
local.search('fire');            // ranked local results
local.browse({ category: 'Food & Drink' });
local.parse('Great work 👏🏽 👏🏽!'); // 2 occurrences, 1 unique emoji
local.convert('Hello :wave:', {
  direction: 'to_emoji', shortcodeSource: 'github',
});

// Save snapshot as JSON to reuse across app sessions.
// Local methods are synchronous and make no HTTP requests.

EmojiCatalog performs synchronous lookup, search, browsing and whole-sequence text parsing from that JSON without network requests. metadata() reports source-server evidence and scope() reports the downloaded subset.

Deep#

?deep=true Unicode detail, keywords, sourced shortcode presets, complete skin-tone variants and licensed artwork links. Included on every plan, with no additional charge.

import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.emoji("rocket", { deep: true });
console.log(result);

{
  "emoji": "🚀",
  "name": "Rocket",
  "shortcodes": [
    ":rocket:",
    "rocket"
  ],
  "category": "Travel & Places",
  "deep": {
    "codepoints": [
      "U+1F680"
    ],
    "hex": "1F680",
    "status": "fully-qualified",
    "version": "0.6",
    "keywords": [
      "rocket",
      "launch",
      "rockets",
      "space",
      "travel",
      "ship"
    ],
    "skins": [],
    "subcategory": "transport-air",
    "artwork": {
      "noto": {
        "svg": "https://cdn.parseapi.com/emoji/noto/18.0.0/1f680.svg",
        "png": {
          "32": "https://cdn.parseapi.com/emoji/noto/18.0.0/32/1f680.png",
          "72": "https://cdn.parseapi.com/emoji/noto/18.0.0/72/1f680.png",
          "128": "https://cdn.parseapi.com/emoji/noto/18.0.0/128/1f680.png",
          "512": "https://cdn.parseapi.com/emoji/noto/18.0.0/512/1f680.png"
        }
      },
      "twemoji": {
        "svg": "https://cdn.parseapi.com/emoji/twemoji/17.0.3/1f680.svg",
        "png": {
          "72": "https://cdn.parseapi.com/emoji/twemoji/17.0.3/72/1f680.png"
        }
      },
      "openmoji": {
        "svg": "https://cdn.parseapi.com/emoji/openmoji/17.0.0/1f680.svg",
        "png": {
          "72": "https://cdn.parseapi.com/emoji/openmoji/17.0.0/72/1f680.png",
          "618": "https://cdn.parseapi.com/emoji/openmoji/17.0.0/618/1f680.png"
        }
      }
    }
  }
}

Questions? Email