Text to Emotion API

Text to Emotion API

Discover the emotions in textual messages automatically using NLP.
Free Plan $0.00 Monthly Subscribe
30 Requests / Monthly
Free for Lifetime
No Credit Card Required
Starter Plan $9.99 Monthly Subscribe
7,500 Requests / Monthly
Standard Support
Pre-trained model
No prior NLP knowledge needed
Pro Plan $29.99 Monthly Subscribe
30,000 Requests / Monthly
Standard Support
Pre-trained model
No prior NLP knowledge needed
Custom Plan Volume Monthly Contact Us
Any requests volume you need
Pre-trained model
No prior NLP knowledge needed

Human beings can easily perceive the emotions from any texts and experience it naturally. But what about the machines, are they able to detect the emotions from a text as we do? Text to Emotion API let’s you find the appropriate emotions embedded in the text data automatically using a few lines of code and a simple API.

How it works

Text to Emotion API uses complex NLP algorithms to mine underlying emotions from a given text. Basically the flow is as follows:

  • Remove the unwanted textual part from the message.
  • Perform the natural language processing techniques.
  • Bring out the well pre-processed text from the text pre-processing.
  • Find the appropriate words that express emotions or feelings.
  • Check the emotion category of each word.
  • Store the count of emotions relevant to the words found.

The output of the endpoint is a JSON dictionary with keys as emotion categories (happy, surprise, angry, sad, fear) and values as emotion scores. The score is a value between 0.00 to 1.00. The higher the value, the more likely our text to express that emotion.


For example; let’s take the following famous speech from Hamlet (W.Shakespeare). It is a complicated and emotional speech and the API is capable of showing the mixed feelings of Prince Hamlet:

To be, or not to be, that is the question:
Whether 'tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take Arms against a Sea of troubles,
And by opposing end them: to die, to sleep;

The simple cURL command to perform the text to emotion analysis is:

curl --location --request POST 'https://api.apilayer.com/text_to_emotion' \
--header 'apikey: YOUR API KEY' \
--data-raw 'To be, or not to be, that is the question:
Whether '\''tis nobler in the mind to suffer
The slings and arrows of outrageous fortune,
Or to take Arms against a Sea of troubles,
And by opposing end them: to die, to sleep;'

And the response from the API is:

    "Happy": 0.14,
    "Angry": 0.0,
    "Surprise": 0.29,
    "Sad": 0.29,
    "Fear": 0.29

More code samples (for more programming languages) are available on the Live Demo section right above.

How accurate is the API?

Human emotions are too complex for computers to identify. Even humans are easily mistaken by the speech especially when sarcasm involves. Without mimics and the background information, it is sometimes impossible to predict the emotions accurately. But text to emotion API will perform above the mentioned expectations in the most cases. Just subscribe to this API, give it a try for your use case (it is free) and see if it works for you.

Handling of Emojis

The API is able to identify the emotion from the emojis which describes human behavior. Let’s take an example:

curl --location --request POST 'https://api.apilayer.com/text_to_emotion' \
--header 'apikey: YOUR API KEY' \
--data-raw 'It\'s not funny. This must be a joke! 😡🤬'

And the response from the API is:

    "Happy": 0.33,
    "Angry": 0.67,
    "Surprise": 0.0,
    "Sad": 0.0,
    "Fear": 0.0

Textually, there is a chance of being a joke but looking at the emojis, the API correctly classifies the emotion of the text as anger.

Use cases

The API is mostly useful for the following industrial use cases:

  • Customer Engagement: The signals that will be provided by the text to emotion API can help customer services teams to understand and interact with their clients more appropriately. It helps to speed up the process of understanding customer needs and complaints.
  • Customer support with chatbots: Customer support with chatbots: Chatbots help companies to provide 24-hour support to their users. By enabling emotion detection, chatbots will be able to provide more human-like interaction which will help to increase customer satisfaction.
  • Social Media Monitoring: Keeping a close eye on the social media posts will help brands to take action before small problems happen to be a crisis.

How is Emotion Detection different from Sentiment Analysis?

Sentiment Analysis helps you to understand the polarity of a given text by labeling them as positive, negative or neutral. Emotion detection takes it to a more granular level by bringing out the real feelings that the user feels while typing their content. Anger and fear will be categorized as negative sentiment by Sentiment Analysis but they definitely require different communication approaches. Based on your needs, you can also give a look to the Sentiment Analysis API.

Text to Emotion API Reference

This API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Just Getting Started?

Check out our development quickstart guide.


Text to Emotion API uses API keys to authenticate requests. You can view and manage your API keys in the Accounts page.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All requests made to the API must hold a custom HTTP header named "apikey". Implementation differs with each programming language. Below are some samples.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.


Discover the emotions in textual messages


body (required)

Text to perform emotion analysis

Location: Body, Data Type: string

** A word enclosed with curly brackets "{ }" in the code means that it is a parameter and it should be replaced with your own values when executing. (also overwriting the curly brackets).

Below is a sample response from the endpoint

If you wish to play around interactively with real values and run code, see...

Rate Limiting

Each subscription has its own rate limit. When you become a member, you start by choosing a rate limit that suits your usage needs. Do not worry; You can upgrade or downgrade your plan at any time. For this reason, instead of starting with a larger plan that you do not need, we can offer you to upgrade your plan after you start with "free" or "gold plan" options and start using the API.

When you reach a rate limit (both daily and monthly), the service will stop responding and returning the HTTP 429 response status code (Too many requests) for each request with the following JSON string body text.

"message":"You have exceeded your daily\/monthly API rate limit. Please review and upgrade your subscription plan at https:\/\/apilayer.com\/subscriptions to continue."

A reminder email will be sent to you when your API usage reaches both 80% and 90%, so that you can take immediate actions such as upgrading your plan in order to prevent your application using the API from being interrupted.

You can also programmatically check your rate limit yourself. As a result of each request made to the APILayer, the following 4 fields provide you with all the necessary information within the HTTP Headers.

x-ratelimit-limit-month: Request limit per month
x-ratelimit-remaining-month: Request limit remaining this month
x-ratelimit-limit-day: Request limit per day
x-ratelimit-remaining-day: Request limit remaining today

You can contact our support unit if you need any assistance with your application regarding to handle the returned result by looking at the header information.

Error Codes

APILayer uses standard HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate a clientside error, which means that failed given the information provided (e.g., a missing parameter, unauthorized access etc.). Codes in the 5xx range indicate an error with APILayer's servers (normally this should'nt happen at all).

If the response code is not 200, it means the operation failed somehow and you may need to take an action accordingly. You can check the response (which will be in JSON format) for a field called 'message' that briefly explains the error reported.

Status Code Explanation
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
404 - Not Found The requested resource doesn't exist.
429 - Too many requests API request limit exceeded. See section Rate Limiting for more info.
5xx - Server Error We have failed to process your request. (You can contact us anytime)

You can always contact for support and ask for more assistance. We'll be glad to assist you with building your product.