Documentation

Introduction

Emoji Info is a service that exposes emoji data in over 42 human languages as a simple JSON-based API.

See the demo to check the language codes.

Authentication

Emoji Info uses API keys to allow access to the API and expects the keys to be included in a request header that looks like the following:

X-API-Key: $API_KEY

Get all emoji data

$ curl https://v1.emoji.workers.dev/en -H "X-API-Key: $API_KEY"

The above endpoint returns a JSON object like this:

{
  "hits" : [
    {
      "emoji": "😀",
      "encoded": "%F0%9F%98%80",
      "unicode": "U+1F600",
      "title": "grinning face",
      "tags": [
        "face",
        "grin",
        "grinning face"
      ]
    },
    {
      "emoji": "😁",
      "encoded": "%F0%9F%98%81",
      "unicode": "U+1F601",
      "title": "beaming face with smiling eyes",
      "tags": [
        "beaming face with smiling eyes",
        "eye",
        "face",
        "grin",
        "smile"
      ]
    }
    ...
  ]
}

Get one emoji data

$ curl https://v1.emoji.workers.dev/en/😀 -H "X-API-Key: $API_KEY"

or

$ curl https://v1.emoji.workers.dev/en/%F0%9F%98%80 -H "X-API-Key: $API_KEY"

The above endpoints return a JSON object like this:

{
  "emoji": "😀",
  "encoded": "%F0%9F%98%80",
  "unicode": "U+1F600",
  "title": "grinning face",
  "tags": [
    "face",
    "grin",
    "grinning face"
  ]
}

Search emojis by title and tags

$ curl https://v1.emoji.workers.dev/en/search?q=$QUERY -H "X-API-Key: $API_KEY"

Search emojis by title

$ curl https://v1.emoji.workers.dev/en/search_by_title?q=$QUERY -H "X-API-Key: $API_KEY"

Search emojis by tags

$ curl https://v1.emoji.workers.dev/en/search_by_tags?q=$QUERY -H "X-API-Key: $API_KEY"

Filter response

You can filter the API response down to specific fields by adding the field name to the URL.

Get only the emoji and title fields for all emojis:

$ curl https://v1.emoji.workers.dev/en?fields=emoji,title -H "X-API-Key: $API_KEY"

Response:

{
  "hits": [
    {
      "emoji": "😀",
      "title": "grinning face"
    },
    {
      "emoji": "😁",
      "title": "beaming face with smiling eyes"
    }
    ...
  ]
}

Get only the tags field for one emoji:

$ curl https://v1.emoji.workers.dev/en/😀?fields=tags -H "X-API-Key: $API_KEY"

Response:

{
  "tags": [
    "face",
    "grin",
    "grinning face"
  ]
}

Limit the number of hits

You can limit the number of emoji data to return per request:

$ curl https://v1.emoji.workers.dev/en/search?q=$QUERY&count=$NUMBER -H "X-API-Key: $API_KEY"

API keys rotation

We recommend regenerating all your API keys at least once a year. It gives you an additional level of security in case one of your API keys leaks, is used in projects that don’t belong to you, or if you need to for compliance reasons.

API keys in mobile applications

You shouldn’t hardcode API keys in mobile applications. Instead, we recommend fetching them dynamically from your application’s back end. The reason is that users might not update your application as often as you’d want. If you need to rotate an API key that was hardcoded in your mobile application, the application stops working.

HTTP referrers restrictions

Since browsers send the Referer header with every request, you can use it to restrict the usage of your API key to your own website. This prevents another website from “stealing” your key.

Authorized HTTP referrers

On the dashboard page, you can define a list of referrers authorized to query the API with a given key. If unspecified or empty, it defaults to any referrer.

You can target referrers by matching a prefix or a suffix using the * wildcard:

  • https://emojiinfo.com/* restricts access to all referrers starting with https://emojiinfo.com.
  • *.emojiinfo.com restricts access to all referrers ending with .emojiinfo.com.
  • To allow access for the full emojiinfo.com domain, you can use *emojiinfo.com/*.
by Tsutomu Narushima