🙂  Faces Endpoints

Faces are a subset of Twemojis specifically supported by the API. To be supported, the Twemoji is broken down into discrete layers and each manually labelled as a feature.

Arguments

NameRequiredTypeDefault
index_by❌Stringlayers
include_features❌Strings (comma separated)all
include_layers❌Integers (comma separated)all
include_glyphs❌Booleantrue
include_empty_layers❌Booleanfalse
twemoji_version❌Stringlatest

Features

  1. head
  2. cheeks
  3. mouth
  4. nose
  5. eyes
  6. eyewear
  7. headwear
  8. other

Labeling

Deciding which feature to label a layer is subjective, especially with the inclusion of an other feature. For example, a layer with dimples could be commonly classified as part of the cheeks or the mouth.

It's also relevant to consider how the layer looks when combined with other Twemojis. To continue with the same example, if the layer with dimples is often hidden behind other cheeks layers when labeled as mouth, then it might be better to label it cheeks instead so it can be used more.

Layers may also be intentionally separated to create more pieces for mixing and matching. For example, eyebrows may be labeled as headwear instead of eyes because someone may want to use the eyebrows with another set of eyes, which would not be possible if the eyebrows were grouped with the eyes.

Because of these considerations, features may not be intuitive for every Twemoji you encounter and potentially not consistent when comparing between Twemojis.

If you feel strongly about changing a label, feel free to raise an issue.

Filtering

Pass in a comma-separated list to filter the output of either layers or features.

1include_features=head,eyes

1include_layers=1,2,3

Indexing

Faces can be described in terms of layers or features. The default is layers. To index by features, pass it in as as string to the index_by parameter.

Layers

Request:

1/v1/faces/1f47b

Response:

 1{
 2  ...
 3  "data": {
 4    "1f47b": {
 5      "0": "head",
 6      "1": "eyes",
 7      "2": "eyes",
 8      "3": "eyes",
 9      "4": "mouth"
10    }
11  },
12  ...
13}

Features

Request:

1/v1/faces/1f47b?index_by=features

Response:

 1{
 2  ...
 3  "data": {
 4    "1f47b": {
 5      "head": [
 6        0
 7      ],
 8      "eyes": [
 9        1,
10        2,
11        3
12      ],
13      "mouth": [
14        4
15      ]
16    }
17  },
18  ...
19}