Emoji API

Emoji Family is powered by our Emoji API, which you can use for free (subject to limits). On this page, we'll dive into the different ways you can use the Emoji API to view metadata about emojis and how you can use the Emoji API to add emojis to your website.

List all emojis

GET

https://www.emoji.family/api/emojis

List metadata for all emojis. The response will be large so you probably want to filter and/or search using the search parameters below.

Search parameters

groupstring

Return emojis in this group

subgroupstring

Return emojis in this subgroup

tagstring

Return emojis with this tag

searchstring

Search the emoji's annotation, subgroup, tags and shortcodes for the given string

includeVariationsboolean

Include emoji variations including skin tone and other modifiers (default is false)

Response

application/jsonhttps://www.emoji.family/api/emojis?group=smileys-emotion&search=smile

Loading...

Example

curl "https://www.emoji.family/api/emojis?search=smile&group=smileys-emotion"

Get emoji metadata

GET

https://www.emoji.family/api/emojis/emoji

Get metadata for a single emoji.

Parameters

emojistring

The emoji character (e.g. 🎉) or its hexcode (e.g. 1F389)

Errors

404Emoji not found

Response

application/jsonhttps://www.emoji.family/api/emojis/🎉

Loading...

Example

curl "https://www.emoji.family/api/emojis/🎉"

Get emoji SVG

GET

https://www.emoji.family/api/emojis/emoji/pack/svg

Get an emoji in SVG format.

Parameters

emojistring

The emoji character (e.g. 🎉) or its hexcode (e.g. 1F389)

packstring

The emoji pack you want to use, at the moment we support noto, twemoji, openmoji, blobmoji, fluent, fluentflat

Errors

404Emoji not found or pack not available

Response

image/svg+xmlhttps://www.emoji.family/api/emojis/🎉/fluent/svg

Example

curl "https://www.emoji.family/api/emojis/🎉/noto/svg" > party.svg

Get emoji PNG

GET

https://www.emoji.family/api/emojis/emoji/pack/png/size

Get an emoji in PNG format.

Parameters

emojistring

The emoji character (e.g. 🎉) or its hexcode (e.g. 1F389)

packstring

The emoji pack you want to use, at the moment we support noto, twemoji, openmoji, blobmoji, fluent, fluentflat

sizenumber

Optionally, specify the size of the PNG (default is 512)

Errors

404Emoji not found or pack not available

Response

image/pnghttps://www.emoji.family/api/emojis/🎉/fluent/png/64

Example

curl "https://www.emoji.family/api/emojis/🎉/noto/png/256" > party.png

Response schema

Both the list all emojis and get emoji metadata endpoints return emoji objects with the following fields. The list endpoint returns an array of these objects, while the metadata endpoint returns a single object.

Field	Type	Description
`emoji`	`string`	The emoji character
`hexcode`	`string`	Hexadecimal code point(s), hyphen-separated for multi-codepoint emojis
`group`	`string`	The emoji group (e.g. "smileys-emotion")
`subgroup`	`string`	The emoji subgroup (e.g. "face-smiling")
`annotation`	`string`	Human-readable name of the emoji
`tags`	`string[]`	Searchable tags associated with the emoji
`shortcodes`	`string[]`	Shortcodes like :party-popper:
`emoticons`	`string[]`	ASCII emoticons like :-)
`directional`	`boolean`	Whether the emoji has directional variants
`variation`	`boolean`	Whether this is a skin tone or other variation
`variationBase`	`string \| null`	Hexcode of the base emoji if this is a variation
`unicode`	`number`	Unicode version the emoji was introduced
`order`	`number`	Sort order within the emoji set
`skintone`	`number \| number[] \| null`	Skin tone modifier(s) if applicable
`skintoneCombination`	`string \| null`	"single", "multiple", or null
`skintoneBase`	`string \| null`	Hexcode of the non-skin-tone base emoji

The SVG and PNG endpoints return the image directly with Content-Type: image/svg+xml or Content-Type: image/png respectively.

Groups

Each emoji belongs to a group and a subgroup. Here is a breakdown of all the groups and their respective subgroups:

smileys-emotion
- face-smiling
- face-affection
- face-tongue
- face-hand
- face-neutral-skeptical
- face-sleepy
- face-unwell
- face-hat
- face-glasses
- face-concerned
- face-negative
- face-costume
- cat-face
- monkey-face
- heart
- emotion
people-body
- hand-fingers-open
- hand-fingers-partial
- hand-single-finger
- hand-fingers-closed
- hands
- hand-prop
- body-parts
- person
- person-gesture
- person-role
- person-fantasy
- person-activity
- person-sport
- person-resting
- family
- person-symbol
component
- skin-tone
- hair-style
animals-nature
- animal-mammal
- animal-bird
- animal-amphibian
- animal-reptile
- animal-marine
- animal-bug
- plant-flower
- plant-other
food-drink
- food-fruit
- food-vegetable
- food-prepared
- food-asian
- food-sweet
- drink
- dishware
travel-places
- place-map
- place-geographic
- place-building
- place-religious
- place-other
- transport-ground
- transport-water
- transport-air
- hotel
- time
- sky-weather
activities
- event
- award-medal
- sport
- game
- arts-crafts
objects
- clothing
- sound
- music
- musical-instrument
- phone
- computer
- light-video
- book-paper
- money
- mail
- writing
- office
- lock
- tool
- science
- medical
- household
- other-object
symbols
- transport-sign
- warning
- arrow
- religion
- zodiac
- av-symbol
- gender
- math
- punctuation
- currency
- other-symbol
- keycap
- alphanum
- geometric

Limits

The Emoji API is free for both personal and commercial use. However, if you are a large company or expect a high volume of traffic, please contact us to discuss your use case.