Introduction

About emojidex

emojidex is the worlds first emoji-as-a-service provider as well as an extremely Open Source friendly set of tools and assets. We appreciate your interest in emojidex and want you to know that the vast majority of profit from emojidex are used to support a variety of Open Source software projects, educational material development and scientific / engineering projects. By using emojidex in your project you are helping support Open Source, global education, and a variety of good and interesting scientific and engineering causes.

This Document (Fixes/Ammendments)

The source for this document can be found here.
Amemendments and fixes are welcome! Please either fork/fix/push/pull requet or submit an issue on github if you find anything lacking or requiring a cleaner/better explanation.

The emojidex Service

emojidex is primarily based around the emojidex service. This service offers an API with listing, search and registration services. Some services require a token to access [registration for example] or for certain types of access [search with over 100 results per page and other queries that could be overused]. These limitations are only to prevent abuse or overuse of the system.

emojidex Tools and Clients

emojidex offers a set of clients and tools that can be found in the emojidex organization on github. The core tool and model for emojidex is the emojidex gem for Ruby. This is the basis of not only online and backend tools but also the majority of the tools for emojidex such as the converter and the desktop client/editor. For Java/Android there's emojidex android.

emojidex on a Web Site

The emojidex Coffee client is a front end client and tool set, developed in Coffee Script, and distributed as a jQuery plug-in. Using emojidex to automatically convert emoji character codes on your web site and use emoji assets in or as widgets, and to enter and parse text with emoji is made as easy as simple as possible. All emoji are obtained from the content delivery network for the emojidex Service so you don't need to cache any emoji on your server or worry about any assets or images on your own server.

API

This documentation covers access and usage of emojidex service utilizing the API and CDN.

HTTP Requests

https://www.emojidex.com/api/v1

The API must always be called through HTTPS/SSL. This is to prevent leaking of user auth tokens and generally to keep as much information as to how users use emojidex as private as possible.

HTTP Verbs

Throughout most of the API different actions are mapped to different HTTP verbs, such as GET, PUT, POST, DELETE. You MUST be aware of what verb you are using to make an API request, as most of the time only one HTTP verb will perform the task you want in your query.

Transport Data Types

The emojidex API currently provides data to and from all endpoints in either standard JSON or MessagePack format. JSON being such a such a standardized and universally accepted format is of course the default, but we strongly encourage you to implement with MessagePack as all communication between your app and the emojidex server will be lighter and faster. MessagePack is already included as default in all of our clients other than emojidex-web, and in that case only because we didn't want to increase the processing burden and initial load of the script. To use MessagePack in your own client, simply pass requests with the Accept header set to "application/msgpack":
Accept: application/msgpack And if your transactor happens to not be sending/receiving UTF-8 by default, we would of course recommend adding: Charset: UTF-8 just in case.

Specific examples will not be given in MessagePack here as it is not easily readable, but if you wanted to execute any of the Shell/CURL examples in this documentation with MessagePack then simply add -H "Charset: UTF-8" -H "Accept: application/msgpack" after the -L switch. For example curl -X GET -L -H "Charset: UTF-8" -H "Accept: application/msgpack"\ https://www.emojidex.com/api/v1/emoji -o emoji.msgpack would obtain the index in MessagePack and save it to a file named "emoji.msgpack".

Clients

Client origin/sources:

https://curl.haxx.se

https://github.com/emojidex/emojidex

https://github.com/emojidex/libemojidex

https://github.com/emojidex/emojidex-web-client

// Java client is a JNI interface to the C++ libemojidex
https://github.com/emojidex/libemojidex

Client acquisition:

# Use the command line client for CURL, which should be included in any Linux distrobution and OS-X
#   by default. For Windows, or if your distrobution does not include CURL, look here:
#   https://curl.haxx.se/download.html

# Install the emojidex ruby gem:
gem install emojidex
# Or add the following to your Gemfile before bundling:
gem 'emojidex'

// Clone with Git, build libs yourself, see the link in acquisition above for instructions

// Available on NPM, see: https://www.npmjs.com/package/emojidex-client
// Require directly from the CDN: http://cdn.emojidex.com/scripts/javascript/emojidex-client.min.js
// Obtain from the "dist" directory of the repository:
//   https://github.com/emojidex/emojidex-web-client/tree/master/dist/js

// npm:
npm install emojidex

// yarn:
yarn add emojidex

// Clone with Git, build jar yourself, see the link in acquisition above for instructions

Client usage:

# Simply type the CURL command in a terminal:
curl

# Most methods are available from the client.
# For specific functionality require the specific module.
require 'emojidex/client'

// Generally you'll want the client provided with libemojidex.
// Assuming you've vendorized emojidex and have the headers under an "emojidex" folder:
#include <emojidex/client>

/* Obtaining from the CDN:
    <script src="https://cdn.emojidex.com/scripts/javascript/emojidex.min.js"></script>
*/

// Most of the functionality is consolidated in the Client.
// Specific functionality can be accessed by importing specific modules.
import com.emojidex.libemojidex.Emojidex.Client;

Clients are provided for all the langauges selectable on the right (and more). Please select the tab for the language you wish to use to find information on how to obtain and utilize the client.

Authentication

Token acquisition/Login:

curl -X GET www.emojidex.com/api/v1/users/authenticate -d email=whoever@emojidex.com -d password=********
# or
curl -X GET www.emojidex.com/api/v1/users/authenticate -d username=WhoEver -d password=********
# or
curl -X GET www.emojidex.com/api/v1/users/authenticate -d user=whoever@emojidex.com -d password=********
# or
curl -X GET www.emojidex.com/api/v1/users/authenticate -d user=WhoEver -d password=********

require 'emojidex/service/user'

user = Emojidex::Service::User.new
user.login('MeMeMe', '******')

#include <emojidex/service/user>

Emojidex::Service::User user;
user.login("MyUser", "my-password");

emojidex = new EmojidexClient({
  // wait initialization
  onReady: (EC) => {
    emojidex.User.login({'authtype': 'plain', 'username': 'MeMeMe', 'password': '******'});
  }
});

import com.emojidex.libemojidex.Emojidex.Service.User;

User user = new User();
user.login("MeMeMe", "******");

Token authentication/Authentication:

curl -X GET www.emojidex.com/api/v1/users/authenticate -d username=MeMeMe -d token=0123456789abcdef

require 'emojidex/service/user'

user = Emojidex::Service::User.new
user.authorize('MeMeMe', '0123456789abcdef')

#include <emojidex/service/user>

Emojidex::Service::User user;
user.authorize("MyUser", "0123456789abcdef");

// type plain:
emojidex.User.login({'authtype': 'plain', 'username': 'MeMeMe', 'password': '******'});

// type token:
emojidex.User.login({'authtype': 'token', 'username': 'MeMeMe', 'auth_token': '******'});

// type basic:
emojidex.User.login({'basic': 'plain', 'user': 'username-or-email', 'password': '******'});

import com.emojidex.libemojidex.Emojidex.Service.User;

User user = new User();
user.authorize("MeMeMe", "0123456789abcdef");

When authentication / confirmation succeeds something like the following JSON is returned:

{"auth_status":"verified","auth_user":"MyUserName","auth_token":"0123456789abcdef",
  "pro":false,"pro_exp":null,"premium":true,"premium_exp":"2016-10-22T15:18:33.926+00:00", "r18":false}

When authentication fails the follwing JSON is returned:

{"auth_status":"unverified","auth_token":null}

Auth Tokens

Each user is granted an auth token which gives them access to their own personal resources. Each user account is granted one and only one token which can be used by multiple clients, does not expire, but can be refreshed/changed.

Tokens are returned as a response from a valid authorization request. Users can view, re-set, or revoke their auth token from the User Details section after they log in to the emojidex web site. Auth tokens can not be changed through the API. As a single auth token is granted per user and shared between apps, the revocation or re-generation of a token will require re-acquisition in all clients. Not all API calls require authentication, but all API calls can and should be performed with authentication tokens included when a token is available.

Authenticating / Obtaining a user auth token from the API

You can authenticate through the API using a username and password or e-mail and password. It is also possible to check authentication and update user details using the username and token. To authenticate you must make a call to /api/v1/users/authenticate with an appropriate combination of the following parameters:

Parameters

Name	Type	Description
username	string	The username registered to the user (paired with password or token)
email	string	The e-mail address of the user (paired with password)
user	string	The username or e-mail address of the user (paired with password)
password	string	The password of the user (paired with username or e-mail)
token	string	The authentication token (paired with username)

Upon a successful authentication request the following information will be returned:

Return Data

┏auth_status: the status code of the authorization ("verified" or "unverified")
┣auth_user: the username of the account just verified
┣auth_token: the auth token for this account
┣pro: true or false value specifying if pro status is currently active
┣pro_exp: expiration date of current or previous pro status (null if never active)
┣premium: true or false value specifying if premium status is currently active
┣premium_exp: expiration date of current or previous premium status (null if never active)
┗r18: true or false value specifying if user wants to view R-18 content

emoji Seeds / Static Collections

Get all UTF [standrd] emoji

curl -X GET https://www.emojidex.com/api/v1/utf_emoji

require "emojidex/data/emoji/utf"

utf = Emojidex::Data::UTF.new

#include <emojidex/service/indexes>
#include <emojidex/data/collection>

Emojidex::Service::Indexes idx;
Emojidex::Data::Collection utf = idx.utfEmoji();

emojidex.Indexes.static(['extended_emoji'], 'en', emoji_data => {
  console.log(emoji_data)
})

import com.emojidex.libemojidex.Emojidex.Service.Indexes;
import com.emojidex.libemojidex.Emojidex.Data.Collection;

Indexes idx = new Indexes();
Collection utf = idx.utfEmoji();

Get all emojidex brand Extended emoji

curl -X GET https://www.emojidex.com/api/v1/extended_emoji

require "emojidex/data/emoji/extended"

extended = Emojidex::Data::Extended.new

#include <emojidex/service/indexes>
#include <emojidex/data/collection>

Emojidex::Service::Indexes idx;
Emojidex::Data::Collection extended = idx.extendedEmoji();

emojidex.Indexes.static(['extended_emoji'], 'en', emoji_data => {
  console.log(emoji_data)
})

Get all UTF [standard] emoji with Japanese codes

curl -X GET https://www.emojidex.com/api/v1/utf_emoji -d locale=ja

require "emojidex/data/emoji/utf"

utf = Emojidex::Data::UTF.new({locale: 'ja'})

#include <emojidex/service/indexes>
#include <emojidex/data/collection>

Emojidex::Service::Indexes idx;
Emojidex::Data::Collection utf = idx.utfEmoji('ja');

emojidex.Indexes.static(['utf_emoji'], 'ja', emoji_data => {
  console.log(emoji_data)
})

Get all emojidex brand Extended emoji with Japanese codes

curl -X GET https://www.emojidex.com/api/v1/extended_emoji -d locale=ja

require "emojidex/data/emoji/extended"

utf = Emojidex::Data::Extended.new({locale: 'ja'})

#include <emojidex/service/indexes>
#include <emojidex/data/collection>

Emojidex::Service::Indexes idx;
Emojidex::Data::Collection utf = idx.extendedEmoji('ja');

emojidex.Indexes.static(['extended_emoji'], 'ja', emoji_data => {
  console.log(emoji_data)
})

Get moji code indexes

curl -X GET https://www.emojidex.com/api/v1/moji_codes

require "emojidex/service/indexes"

codes = Emojidex::Service::Indexes.moji_codes

#include <emojidex/service/indexes>
#include <emojidex/data/moji_codes>

Emojidex::Service::Indexes idx;
Emojidex::Data::MojiCodes mc = idx.mojiCodes();

emojidex.Data.storage.hub_cache.emojidex.moji_codes

The returned data contains three major indexes.

/* ... indicates truncation, the actual data does not have a ... */
{
  /* useful for REGEX checking/filtering */
  "moji_string":"⛲⛳⛺⛽✅✉✌〽️...",
  /* useful for manual scanning */
  "moji_array":["️1️⃣","️2️⃣","️3️⃣","️4️⃣","️5️⃣","️6️⃣","️7️⃣","️8️⃣", ...],
  /* useful for mapping characters to short codes or for a very basic index */
  "moji_index":{"⛲":"fountain","⛳":"golf","⛺":"tent","⛽":"fuelpump", ...}
}

Get moji code indexes with Japanese codes

curl -X GET https://www.emojidex.com/api/v1/moji_codes -d locale=ja

require "emojidex/service/indexes"

codes = Emojidex::Service::Indexes.moji_codes({locale: 'ja'})

#include <emojidex/service/indexes>
#include <emojidex/data/moji_codes>

Emojidex::Service::Indexes idx;
Emojidex::Data::MojiCodes mc = idx.mojiCodes("ja");

emojidex = new EmojidexClient({
  locale: 'ja'
});

// after initialization
emojidex.Data.storage.hub_cache.emojidex.moji_codes

Generally you'll want to have a selection of emoji available immediately. Usually that will at least consist of the standardized UTF/Unicode emoji. A semi-static index is available at api/v1/utf_emoji . If you only need the codes, a combined string for regex filtering, or an index of character code to emoji short code, these all come in the data available from api/v1/moji_codes . The emojidex branded extended emoji are also available from api/v1/extended_emoji. All of these end points are compatible with the locale option.

Moji Code Data
Moji code [character code] data is a set of three consolidated lists of characters and short codes. It's accessable from /api/v1/moji_codes and the only argument is the locale (defaults to 'en').

Parameters

Name	Type	Description
locale	string	the locale/languge code (EG: "ja" or "en")

Return Data

┏moji_string: a string of character codes, with multi-chracter compound codes coming before others
┣moji_array[]: an array of character codes, with multi-chracter compound codes coming before others
┗moji_index{}: a localized hash index of character code keys with emoji code values

UTF and Extended Sets
To get a full (non-paginated) set of standard UTF emoji (emoji standardized or in the proposal phase for Unicode) or Extended emojidex original emoji. Call to either api/v1/utf_emoji or api/v1/extended_emoji for UTF or Extended emoji. Both sets offer localized versions in default English or Japanese.

Parameters

Name	Type	Description
locale	string	the locale/languge code (EG: "ja" or "en")
detailed	bool	returns extra information such as upstream asset checksums[md5] when true

Return Data

An array of emoji in the format of:
┏code: the :code: of the emoji
┣moji: the character code of the emoji (null when emoji is not a standard character)
┣unicode: the unicode ID of the emoji (null when emoji is not a standard character)
┣category: the category the emoji is contained in
┣tags[]: an array of tags the emoji is registered under (an empty array [] if none)
┣link: a URL associated with the emoji (null when no link is registered or active)
┣base: the code of the emoji this emoji is based off of (code of this emoji if not a variant)
┣variants[]: an array of variants of this emoji
┗score: the score of the emoji

emoji Information

Get information on the "sushi" emoji

GET /emoji/sushi

curl -X GET https://www.emojidex.com/api/v1/emoji/sushi

require "emojidex/service/search"

em = Emojidex::Service::Search.find('sushi')

#include <emojidex/service/search>
#include <emojidex/data/emoji>

Emojidex::Service::Search search;
Emojidex::Data::Emoji = search.find('sushi')

emojidex.Search.search(search_word, result_emoji => {
  console.log(result_emoji);
});

Information about the "sushi" emoji is retruned:

{"code":"sushi","moji":"🍣","unicode":"1f363","category":"food","tags":[]}

To get information about a particular emoji simply query they /emoji/(emoji code) endpoint, replacing (emoji code) with the emoji code you want the information about.

Parameters

Name	Type	Description
detailed	bool	returns extra information such as upstream asset checksums[md5] when true

Return Codes

HTTP	Message
200	emoji information
404	{"status":"emoji not found"}

Return Data

┏code: the :code: of the emoji
┣moji: the character code of the emoji (null when emoji is not a standard character)
┣unicode: the unicode ID of the emoji (null when emoji is not a standard character)
┣category: the category the emoji is contained in
┣tags[]: an array of tags the emoji is registered under (an empty array [] if none)
┣link: a URL associated with the emoji (null when no link is registered or active)
┣base: the code of the emoji this emoji is based off of (code of this emoji if not a variant)
┣variants[]: an array of variants of this emoji
┣score: the score of the emoji
┣r18: specifies if the emoji contains adult/vulgar content (requires account with R-18 enabled)
┣customizations: specifies overlays to customize the emoji
┣combinations: specifies combinations this emoji can be used in
┣created_at: !Pro/Premium only! creation/registration date in UTC format
┗favorited: !Pro/Premium only! amount of active favorites (users who have this emoji favorited)

emoji Index

GET /emoji

curl -X GET https://www.emojidex.com/api/v1/emoji

require "emojidex/service/indexes"

emoji_collection = Emojidex::Service::Indexes.emoji

#include <emojidex/service/indexes>
#include <emojidex/data/collection>

Emojidex::Service::Indexes idx;
Emojidex::Data::Collection emoji_collection = idx.emoji();

emojidex.Indexes.index((result_emoji) => {
  console.log(result_emoji);
});

GET /emoji detailed=true

curl -X GET https://www.emojidex.com/api/v1/emoji -d detailed=true

require "emojidex/service/indexes"

emoji_collection = Emojidex::Service::Indexes.emoji(true)

#include <emojidex/service/indexes>
#include <emojidex/data/collection>

Emojidex::Service::Indexes idx;
Emojidex::Data::Collection emoji_collection = idx.emoji(DEFAULT_PAGE, DEFAULT_LIMIT, true);

emojidex.Indexes.index((result_emoji) => {
  console.log(result_emoji);
}, {'detailed': true});

GET /emoji limit=50 page=2

curl -X GET https://www.emojidex.com/api/v1/emoji -d page=2 -d limit=50

require "emojidex/service/indexes"

emoji_collection = Emojidex::Service::Indexes.emoji(false, 50, 2)

#include <emojidex/service/indexes>
#include <emojidex/data/collection>

Emojidex::Service::Indexes idx;
Emojidex::Data::Collection emoji_collection = idx.emoji(2, 50);

emojidex.Indexes.index((result_emoji) => {
  console.log(result_emoji);
}, {'page': 2, 'limit': 50});

Gets a general index of emoji, sorted by score.

Parameters

Name	Type	Description
category	string	the category code (EG: "faces" or "food") you wish to limit the index to
limit	integer	amount of emoji to return per page
page	integer	page number
detailed	bool	returns extra information such as upstream asset checksums[md5] when true
sort	string	[Pro only] determines the sort order of the emoji returned.

Sort Types

Sort Code	Effect
score	(Default) Organizes results with higher scores first.
unpopular	The opposite of score - results are organized with lowest score first.
newest	Newer emoji are returned first.
oldest	Older emoji are returned first.
liked	emoji favorited by more users are returned first.
unliked	emoji favoreted by fewer users are returned first.
shortest	emoji with shorter emoji codes are returned first.
longest	emoji with longer emoji codes are returned first.

Return Data

┏emoji[]: an array of emoji
┃┣code: the :code: of the emoji
┃┣moji: the character code of the emoji (null when emoji is not a standard character)
┃┣unicode: the unicode ID of the emoji (null when emoji is not a standard character)
┃┣category: the category the emoji is contained in
┃┣tags[]: an array of tags the emoji is registered under (an empty array [] if none)
┃┣link: a URL associated with the emoji (null when no link is registered or active)
┃┣base: the code of the emoji this emoji is based off of (code of this emoji if not a variant)
┃┣variants[]: an array of variants of this emoji
┃┗score: the score of the emoji
┗meta{}: meta data about this collection
　┣count: the count of emoji [limit] contained in this response
　┣total_count: the total count emoji in this collection available on the server
　┗page: the current page of the collection

Newest emoji

GET /newest

curl -X GET https://www.emojidex.com/api/v1/newest -d auth_token=1234567890abcdef

require "emojidex/service/indexes"

# If the user has logged in before
newest = Emojidex::Service::Indexes.newest()
# Or to manually pass a token
newest = Emojidex::Service::Indexes.newest(false, Emojidex::Defaults.limit, 0, 'MeMeMe', '1234567890abcdef')

#include <emojidex/service/indexes>
#include <emojidex/data/collection>

Emojidex::Service::Indexes idx;
Emojidex::Data::Collection newest_collection = idx.newest("1234567890abcdef");

// this feature is need authorization.
emojidex.Indexes.newest((result_emoji) => {
  console.log(result_emoji);
});

Gets a general index of emoji sorted by registration date.

Parameters

Name	Type	Description
auth_token	string	a user auth token. User must be pro or premium to access this resource
category	string	the category code (EG: "faces" or "food") you wish to limit the index to
limit	integer	amount of emoji to return per page
page	integer	page number
detailed	bool	returns extra information such as upstream asset checksums[md5] when true

Return Codes

HTTP	Message
200	a page of an emoji collection
401	{"status":"resource requires authorization"}
402	{"status":"resource limited to premium/pro users"}

Return Data

Popular emoji

GET /popular

curl -X GET https://www.emojidex.com/api/v1/popular -d auth_token=1234567890abcdef

require "emojidex/service/indexes"

# If the user has logged in before
popular = Emojidex::Service::Indexes.popular()
# Or to manually pass a token
popular = Emojidex::Service::Indexes.popular(false, Emojidex::Defaults.limit, 0, 'MeMeMe', '1234567890abcdef')

#include <emojidex/service/indexes>
#include <emojidex/data/collection>

Emojidex::Service::Indexes idx;
Emojidex::Data::Collection popular_collection = idx.popular("1234567890abcdef");

// this feature is need authorization.
emojidex.Indexes.popular((result_emoji) => {
  console.log(result_emoji);
});

Gets a general index of emoji sorted by popularity (times favorited).

Parameters

Name	Type	Description
auth_token	string	a user auth token. User must be pro or premium to access this resource
category	string	the category code (EG: "faces" or "food") you wish to limit the index to
limit	integer	amount of emoji to return per page
page	integer	page number
detailed	bool	returns extra information such as upstream asset checksums[md5] when true

Return Status

HTTP	Message
200	a page of an emoji collection
401	{"status":"resource requires authorization"}
402	{"status":"resource limited to premium/pro users"}

Return Data

Name	Type	Description
limit	integer	amount of categories to return per page
page	integer	page number
locale	string	language for category names currently only "en" [default] and "ja" are supported

Search for emoji

Search for emoji with code containing "heart"

curl -X GET https://www.emojidex.com/api/v1/search/emoji -d code_cont=heart

require "emojidex/service/search"

res = Emojidex::Service::Search.term('heart')

emojidex.Search.search(search_word, result_emoji => {
  console.log(result_emoji);
})

Search for emoji with code starting with "heart"

curl -X GET https://www.emojidex.com/api/v1/search/emoji -d code_sw=heart

require "emojidex/service/search"

res = Emojidex::Service::Search.starting('heart')

emojidex.Search.starting(search_word, result_emoji => {
  console.log(result_emoji);
})

Search for emoji with code ending with "heart"

curl -X GET https://www.emojidex.com/api/v1/search/emoji -d code_ew=heart

require "emojidex/service/search"

res = Emojidex::Service::Search.ending('heart')

emojidex.Search.ending(search_word, result_emoji => {
  console.log(result_emoji);
})

Search for emoji with codes containing "heart" in the category "faces"

curl -X GET https://www.emojidex.com/api/v1/search/emoji -d code_cont=heart -d categories\[\]=faces

require "emojidex/service/search"

res = Emojidex::Service::Search.advanced('heart', ['faces'])

emojidex.Search.advanced({"heart", [], ['faces']}, result_emoji => {
  console.log(result_emoji);
});

Search for emoji with codes containing "heart" in either the category "faces" or "abstract"

curl -X GET https://www.emojidex.com/api/v1/search/emoji -d code_cont=heart -d categories\[\]=faces -d categories\[\]=abstract

require "emojidex/service/search"

res = Emojidex::Service::Search.advanced('heart', ['faces', 'abstract'])

emojidex.Search.advanced({"heart", [], ['faces', 'abstract']}, result_emoji => {
  console.log(result_emoji);
});

Search for emoji with tag "weapon"

curl -X GET https://www.emojidex.com/api/v1/search/emoji -d tags\[\]=weapon

require "emojidex/service/search"

res = Emojidex::Service::Search.tags(['weapon'])

emojidex.Search.tags(["weapon"], result_emoji => {
  console.log(result_emoji);
});

Search for emoji where code contains "rifle", has the tag "weapon", and is in category "tools"

curl -X GET https://www.emojidex.com/api/v1/search/emoji -d code_cont=rifle -d tags\[\]=weapon -d categories\[\]=tools

require "emojidex/service/search"

res = Emojidex::Service::Search.advanced('rifle', ['tools'], ['weapon'])

emojidex.Search.advanced({"rifle", ['weapon'], ['tools']}, result_emoji => {
  console.log(result_emoji);
});

The basis for emoji searches is search by emoji code. Searches can be performed for codes that contain a term, start with a term, or end with a term. Alternatively, you can serch for tags, or you can combine a code search with tags to restrict search results to emoji containging the term which also have the tags specified. Additionally, searches can be restricted to one or more categories, where results will only be emoji present in the categories specified. In general, more tags specified means a more specific search with fewer results. And, in general, the more categories specified the more generalized the search and therefore more results. When no categories or tags are specified the search will not be restricted to any categories or tags and will return all results for the term specified.

The API endpoint for searches is /search/emoji.

Predicates Predicates are added to the code field to specify the search type, such as "[q][code_cont]" to "query for codes which contain" the specified term.

Predicate	Meaning	Description
cont	Contains	Contains the search term somewhere in the code.
sw	Starts With	Code starts with the term.
ew	Ends With	Code ends with the term.

Search Fields

Name	Description
code	Code search. Can use predicates.
tags[]	An array of tags to search by or to limit results to.
categories[]	An array of categories to limit the search domain.

Parameters

Name	Type	Description
limit	integer	amount of emoji to return per page
page	integer	page number
detailed	bool	returns extra information such as upstream asset checksums[md5] when true
sort	string	[Pro only] determines the sort order of the emoji returned.

Sort Types

Sort Code	Effect
score	(Default) Organizes results with higher scores first.
unpopular	The opposite of score - results are organized with lowest score first.
newest	Newer emoji are returned first.
oldest	Older emoji are returned first.
liked	emoji favorited by more users are returned first.
unliked	emoji favoreted by fewer users are returned first.
shortest	emoji with shorter emoji codes are returned first.
longest	emoji with longer emoji codes are returned first.

Return Data

User emoji

Get emoji for the user "Zero"

curl -X GET https://www.emojidex.com/api/v1/users/Zero/emoji

require 'emojidex/service/indexes'

zeros_emoji = Emojidex::Service::Indexes.user_emoji('zero')

emojidex.Indexes.user("Zero");

Get emoji for the user "絵文字"

curl -X GET https://www.emojidex.com/api/v1/users/絵文字/emoji

require 'emojidex/service/indexes'

emojidex_ja_emoji = Emojidex::Service::Indexes.user_emoji('絵文字')

emojidex.Indexes.user("絵文字", result_emoji => {
  console.log(result_emoji);
});

Returns a collection

{"emoji":[{"code":"幻","moji":null,"unicode":null,"category":"abstract","tags":[],"link":null,
"base":"幻","variants":["幻","幻(白)"],"score":0},{"code":"pink poo","moji":null,
"unicode":null,"category":"abstract","tags":[],"link":null,"base":"pink_poo",
"variants":["pink_poo"],"score":340}],"meta":{"count":2,"total_count":2,"page":1}}

You can get all emoji registered by a specific user.
Some special user accounts exist from which you can get the current UTF index, emojidex original extended emoji, etc. These accounts are as follows:

emoji: All UTF/Unicode emoji with English emoji codes
emojidex: All emojidex original extended emoji with English emoji codes
絵文字: UTF/Unicode emoji with Japanese emoji codes
絵文字デックス: emojidex original extended emoji with Japanese emoji codes

However, this information can also be obtained from the emoji Seed paths in one call without pagination (see above).

Parameters

Name	Type	Description
limit	integer	amount of emoji to return per page
page	integer	page number
detailed	bool	returns extra information such as upstream asset checksums[md5] when true

Return Data

Favorites

Get favorites:

curl -X GET https://www.emojidex.com/api/v1/users/favorites -d auth_token=1234567890abcdef

require 'emojidex/service/user'

user = Emojidex::Service::User.new()

# Log in/authorize of not already

user.sync_favorites

user.favorites # .favorites will contain favorites

// favorites should be pre-cached on login/initialization
emojidex.User.Favorites.all()

// you can actively obtain favorites from the server
emojidex.User.Favorites.get();

{"emoji":[{"code":"falafel","moji":null,"unicode":null,"category":"food","tags":[],"link":null,
"base":"falafel","variants":["falafel"],"score":100}],
"meta":{"count":1,"total_count":1,"page":1}}

Add an emoji to favorites:

curl -X POST https://www.emojidex.com/api/v1/users/favorites -d auth_token=1234567890abcdef -d emoji_code=zebra

require 'emojidex/service/user'

user = Emojidex::Service::User.new()

# Log in/authorize of not already

user.add_favorite('zebra')

emojidex.User.Favorites.set("zebra");

{"code":"falafel","moji":null,"unicode":null,"category":"food","tags":[],"link":null,
"base":"falafel","variants":["falafel"],"score":106}

Remove an emoji from favorites:

curl -X DELETE https://www.emojidex.com/api/v1/users/favorites -d auth_token=1234567890abcdef -d emoji_code=zebra

require 'emojidex/service/user'

user = Emojidex::Service::User.new()

# Log in/authorize of not already

user.remove_favorite('zebra')

emojidex.User.Favorites.unset("zebra");

{"code":"falafel","moji":null,"unicode":null,"category":"food","tags":[],"link":null,
"base":"falafel","variants":["falafel"],"score":6}

Favorites can only be accessed with a token. This resource requires authentication.

Obtaining favorites:
You can obtain favorites by performing a GET on the users/favorites endpoint with a valid auth_token.

Parameters

Name	Type	Description
limit	integer	amount of emoji to return per page
page	integer	page number
detailed	bool	returns extra information such as upstream asset checksums[md5] when true

Return Status

HTTP	Message
200	an array of user favorites
401	{"status":"wrong authentication token"}

Return Data

Adding a Favorite:
You can add an emoji to a users favorites by performing a POST against the users/favorites endpoint with a valid auth_token and the emoji_code.

When a favorite is successfully added an HTTP return code of 201 with updated emoji information in the message body.

To prevent adding multiple entries of the same emoji an HTTP status of 202 with a JSON string {"status":"emoji already in user favorites"} will be returned. Check either the HTTP stats code or for this string so you don't accidentally duplicate the entry in your data set.

Parameters

Name	Type	Description
auth_token	string	the auth token of the user whos favorites you wish to append to
emoji_code	string	the code of the emoji you wish to append to the users favorites

Return Status

HTTP	Message
201	up to date details for the given emoji
202	{"status":"emoji already in user favorites"}
401	{"status":"wrong authentication token"}

Return Data

Removing a Favorite You can remove an emoji from a users favorites by performing a DELETE against the users/favorites endpoint with a valid auth_token and the emoji_code.

When a favorite is successfully removed an HTTP return code of 200 with the emoji information in the body will be returned. You can use this information to cross check your local data and remove the emoji from the data set [though this is really only usefull if you have asyncronous or event driven code].

When a favorite is already remove an HTTP status of 202 with a JSON string {"status":"emoji not in user favorites"} will be returned.

Parameters

Name	Type	Description
auth_token	string	the auth token of the user whos favorites you wish to remove from
emoji_code	string	the code of the emoji you wish to remove from the users favorites

Return Status

HTTP	Message
201	up to date details for the given emoji
202	{"status":"emoji not in user favorites"}
401	{"status":"wrong authentication token"}

Return Data

History

Get history:

curl -X GET https://www.emojidex.com/api/v1/users/history -d auth_token=1234567890abcdef

require 'emojidex/service/user'

user = Emojidex::Service::User.new()

# Log in/authorize of not already

user.sync_history()

user.history # .history will contain the history array

// history is pre-cached on login/initialization
emojidex.User.History.all()

// you can active obtain history from the server
emojidex.User.History.get();

A successful request will return a history array and meta info.

{"history":[{"emoji_code":"falafel","times_used":6,"last_used":"2015-12-21T14:16:58.603+00:00"},
{"emoji_code":"sushi","times_used":4,"last_used":"2015-12-21T14:16:49.708+00:00"}],
"meta":{"count":2,"total_count":2,"page":1}}

Add an emoji to history:

curl -X POST https://www.emojidex.com/api/v1/users/history -d auth_token=1234567890abcdef -d emoji_code=zebra

require 'emojidex/service/user'

user = Emojidex::Service::User.new()

# Log in/authorize of not already

user.add_history('zebra')

emoji.User.History.set("zebra");

A successful registration will return the updated history entry:

{"emoji_code":"zebra","times_used":1,"last_used":"2015-11-30T04:18:23.647+00:00"}

History can only be accessed with a token. This resource requires authentication.

Obtaining history:
You can obtain history by performing a GET on the users/history endpoint with a valid auth_token.

Parameters

Name	Type	Description
auth_token	string	the auth token of the user whos history you wish to obtain
limit	integer	amount of emoji to return per page
page	integer	page number

Return Status

HTTP	Message
201	an array containing emoji codes and times and dates used
401	{"status":"wrong authentication token"}

Return Data

┏history[]: an array containing emoji codes and times and dates used
┃┣emoji_code: the :code: of the emoji
┃┣times_used: the total number of times used by this users
┃┗last_used: the :code: of the emoji
┗meta{}: meta data about the history array
　┣count: the count of history items [limit] contained in this response
　┣total_count: the total count of entries in this users history
　┗page: the current page of history

Adding to history:
Whenever a user uses an emoji you should append to their history by performing a POST on the users/history endpoint with the auth_token of the user and the emoji_code of the emoji being added.

Parameters

Name	Type	Description
auth_token	string	the auth token of the user whos history you wish to append to
emoji_code	string	the code of the emoji you wish to append to the users history

Return Status

HTTP	Message
200	an updated history entry for only the emoji appended
401	{"status":"wrong authentication token"}
422	{"status":"invalid emoji code"}

Return Data

┏emoji_code: the :code: of the emoji
┣times_used: the total number of times used by this users
┗last_used: the :code: of the emoji

Following / Followers

Get a list of the users you are following:

curl -X GET https://www.emojidex.com/api/v1/users/following -d auth_token=1234567890abcdef

# TODO

A successful request will retrun an array of user names:

{"following":["emojidex","Zero"]}

Add a user to your Following list:

curl -X POST https://www.emojidex.com/api/v1/users/following -d auth_token=1234567890abcdef -d username=emojidex

# TODO

A successful request will retrun the user name for confirmation:

{"username":"emojidex"}

Remove a user from your following list:

curl -X DELETE https://www.emojidex.com/api/v1/users/following -d auth_token=1234567890abcdef -d username=emojidex

# TODO

A successful request will retrun the user name for confirmation:

{"username":"emojidex"}

Get a list of users that are following you (Pro/Premium only):

curl -X GET https://www.emojidex.com/api/v1/users/followers -d auth_token=1234567890abcdef

# TODO

A successful request will retrun an array of user names:

{"followers":["emojidex","Zero"]}

By querying the /api/v1/users/following endpoint you can get a list of the user names of the users you are following. If you are a Premium or Pro user you can also access a list of users who are following you.

Following

You can list, add, or remove users you are following.

List of users you are following.

Parameters

Name	Type	Description
auth_token	string	user auth token

Return Status

HTTP	Message
200	a list of the users you are following
401	{"status":"wrong authentication token"}

Return Data

・following[]: an array of the users you are following (an empty array [] if none)

Followers

List of users who are following you (Premium or Pro accounts only).

Parameters

Name	Type	Description
auth_token	string	user auth token

Return Status

HTTP	Message
200	a list of the users who are following you
401	{"status":"wrong authentication token"}
402	{"status":"resource limited to premium/pro users"}

Return Data

・followers[]: an array of the users who are following you (an empty array [] if none)

Assets

Assets [CDN] Address

https://cdn.emojidex.com

Asset Formats

All assets come in Frame Animated SVG and Animated PNG. Assets without animation will be regular SVG or PNG. To generate Frame Animated SVG we recommend Phantom SVG. To generate Animated PNG we recommend apngasm.

Asset Access / Layout

Get the 32px PNG image for :blush:

https://cdn.emojidex.com/emoji/px32/blush.png

Get the SVG image for :blush:

https://cdn.emojidex.com/emoji/blush.svg

Assets can be found on the Content Delivery Network under structured directories.

Each emoji asset is composed of the emoji code, with spaces represented as underscores. For example, the emoji code "blush" would have PNG images named "blush.png".

All emoji on www.emojidex.com can be found under /emoji, with the root /emoji containing SVG images:
https://cdn.emojidex.com/emoji/blush.svg

PNG images come in a variety of sizes:
json { ldpi: 13, mdpi: 18, hdpi: 27, xhdpi: 36, xxhdpi: 54, xxxhdpi: 72, px8: 8, px16: 16, px32: 32, px64: 64, px128: 128, px256: 256, px512: 512, hanko: 90, seal: 320 }
Each emoji size is squared (wide emoji coming soon!). An emoji in a particular size is always guarnteed to have the height specified for its size. For example, LDPI emoji are always 13px high.

display	size	address
	ldpi	https://cdn.emojidex.com/emoji/ldpi/blush.png
	mdpi	https://cdn.emojidex.com/emoji/mdpi/blush.png
	hdpi	https://cdn.emojidex.com/emoji/hdpi/blush.png
	xhdpi	https://cdn.emojidex.com/emoji/xhdpi/blush.png
	xxhdpi	https://cdn.emojidex.com/emoji/xxhdpi/blush.png
	xxxhdpi	https://cdn.emojidex.com/emoji/xxxhdpi/blush.png
	px8	https://cdn.emojidex.com/emoji/px8/blush.png
	px16	https://cdn.emojidex.com/emoji/px16/blush.png
	px32	https://cdn.emojidex.com/emoji/px32/blush.png
	px64	https://cdn.emojidex.com/emoji/px64/blush.png
	px128	https://cdn.emojidex.com/emoji/px128/blush.png
	px256	https://cdn.emojidex.com/emoji/px256/blush.png
(image too big, click here to see)	px512	https://cdn.emojidex.com/emoji/px512/blush.png
	hanko	https://cdn.emojidex.com/emoji/hanko/blush.png
(image too big, click here to see)	seal	https://cdn.emojidex.com/emoji/seal/blush.png

In general small text will usually be best with an emoji size of about ldpi and web text will be around mdpi . Thicker text readable on handsets will usually be around hdpi . Android developers will note the naming conventions coincide with standard asset quality naming conventions; they are in fact sized to be compatible with Android standard sizing. iOS and other platforms should find this sizing convention entirely compatible with native sizing guidelines.

non-inline emoji / emoji as Media Assets

Looking at the sizing chart you will notice the "hanko" and "seal" sizes. Hanko「はんこ」(Japanese for "stamp") is a mid-sized asset perfect for "stamping" on images or adding into multimedia and non-text content. It may also be used as a smaller sized asset for messaging clients.

The "seal" size is made specifically for messaging clients and social media feeds to be sent as individual images in timelines or as individual messages. It will perfectly occupy the width of most messaging clients or social media feeds without distortion or any degrade in quality.

Introduction

About emojidex

This Document (Fixes/Ammendments)

The emojidex Service

emojidex Tools and Clients

emojidex on a Web Site

API

HTTP Requests

HTTP Verbs

Transport Data Types

Clients

Authentication

Auth Tokens

Authenticating / Obtaining a user auth token from the API

emoji Seeds / Static Collections

emoji Information

emoji Index

Newest emoji

Popular emoji

Categories

Search for emoji

User emoji

Favorites

History

Following / Followers

Following

Followers

Assets

Assets [CDN] Address

Asset Formats

Asset Access / Layout

non-inline emoji / emoji as Media Assets