NAV Navbar
Logo Qemotion API
json

Qemotion API Documentation

Quickstart

Last update: 10/08/2017
Direct to Bottom

Introduction

Welcome to the Qemotion API Documentation website!


Qemotion has built Artificial intelligence solutions to qualify the emotions, the sensations and the engagement of the speech, based upon a corpus enriched with more than several million tests on actual feedbacks. Qemotion API's have been especially released to better monitor the customer experience (CX), the employee experience, to help building better products and improve any communication interactions.


Q°emotion provides the best public APIs available to detect:

Getting started

Do not hesitate to contact us for any questions about support, or if you need specific functionalities.

Definitions and glossary

Emotional index (e-index)©

{
   (...see details below)
    },
    "emotions": {
      "eindex": 40,
      "happiness": 15,
      "surprise": 2,
      "calm": 0,
      "fear": 3,
      "sadness": 0,
      "anger": 2,
      "disgust": 0,
      "emotional_intensity_rate": 60,
      "strongest_emotion_by_sentence": [
        [
          "happiness",
          15
        ]
      ]
    }
  }
}

The e-index© is an emotional KPI invented by Qºemotion that synthetizes the main emotion felt and the corresponding intensity of the speech. The emotional index is showcased through an emotional temperature, starting from 0ºF (-20ºC) to 100ºF (+40ºC).

Practically, when you will submit a text to the API, the algorithm will detect the main emotion of the speech and define the corresponding temperature:

    *see below the list of the primary emotions according to our classification.

Examples

Sentence Emotional index
(Value in ºC)
Emotional index
(Value in ºF)
Interpretation
I would like to buy because I found this very interesting. 40ºC 100ºF Happiness
A lot of new elements in this presentation! 23ºC 63ºF Surprise
I have slept very well last night. 12ºC 53ºF Calm
After the terror attack, 22 people have been arrested in Teheran. 7ºC 53ºF Fear
So bad :((( 0ºC 30ºF Sadness
How can your service be so silly ? -12ºC 12ºF Anger
The dead corpse smells now. -20ºC 0ºF Disgust

Once calculated at verbatim/comment level, when looking at a more global level, it is very easy to consolidate the corresponding element to calculate an average situation.

Emotional intensity

Average Emotional intensity measured by words taking into account the Arousal level of the speech. Based on survey and data history, 5 levels are scored: Very low, Low, Normal, High, Very high. Ex: Low intensity means that few affective and few activated words have been used into the speech.

See below the scoring done on primary emotions.

3 interesting dimensions to measure the intensity of an emotion

Traditionally 3 dimensions are the most used in order to measure affective intensity, called PAD Model developed by Albert Mehrabian and James A. Russell (1974):

More information are available on Wikipedia: PAD Model | Valence (psychology) | Arousal

Primary emotions

Primary emotions are universal! Anyone may express emotions in his comments, feedbacks, reviews.
Based on its semantic algorithm, Q°emotion uses multiple interpretation layers to determine the emotional scoring of the analyzed speech.

Based on the PAD Model, the affective norms of the speech and data history, emotional scoring follows the following scale:

Value range Detected Emotional intensity
From 0 to 5 Very low
From 5 to 8 Low
From 9 to 14 High
15 and more Very high

Happiness

{
   (...see details below)
    },
    "emotions": {
      "eindex": 40,
      "happiness": 15,
      "surprise": 2,
      "calm": 0,
      "fear": 3,
      "sadness": 0,
      "anger": 2,
      "disgust": 0,
      "emotional_intensity_rate": 60,
      "strongest_emotion_by_sentence": [
        [
          "happiness",
          15
        ]
      ]
    }
  }
}

Surprise

Calm

Fear

Sadness

Anger

Disgust

Speech engagement©

{
  "status": {
    "code": 200,
    "message": "OK"
  },


(... see full details hereafter ...)

] ] }, "speech_engagement": { "global_engagement": "0,1", "details": { "speech_size": "0,1", "personal_involvement": "0,0", "time_orientation": [], "emotional_boost": { "boost": false, "value": "0" } } } } }

The speech engagement level is an indicator that measures the speech commitment of the transmitter, the distance between object & subject as the projection capability of the audience. Higher speech engagement is often linked with stronger emotional intensity. This engagement is calculated through 4 quantifiers : the speech size (30%), the personal commitment level (50%), the emotional intensity (10%) et the speech [time] orientation (20%).

Examples

Sentence Global engagement (in %) Value
I would like to buy because I found this very interesting. 75% or 0.75 Strong engagement of the speech linked with the length of the speech and the personal commitment of the emitter
I would like to buy. 60% or 0.6 Medium/Strong engagement of the speech due to personal commitment
The product quality is quite poor, maybe this is linked with the price of the item ? 40% or 0.4 Medium engagement of the speech only due to the relative long size of the text.
An interesting company. 25% or 0.25 Low engagement of the speech

Personal commitment level (50%)

The Personal Commitment level is the most important element among the quantifiers of the speech engagement. This quantifier is calculated after a morphosyntactic breaking down, that detect the sentence subject analysis, (1st S /1st P), the use of superlative terms, the use of action verbs, etc.

Speech size (30%)

Text size of the speech expressed from 0,3 (MAX) to 0,0 (min) according to the benchmarks defined with the customers.

Time orientation (20%)

Speech tense used into the wording, it gives an interesting information about the projection capacity of the audience. Particularly Future tense coupled with positive emotions may often be interpreted as a first good indicator for future sales.

Back to top

Endpoints

In order to Q°emotion is publishing several separate API with different features. We will describe therefore each of the APIs that can be called from separate endpoints:

TextToEmotions API

{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "content": {
    "sentence_properties": {
      "total_word_count": 5,
      "accented_punctuation": false,
      "questioning": false,
      "exclamation": true
    },
    "confidence_indicators": {
      "confidence_rate": 80,
      "sentence_number": 1,
      "total_known_word": 3,
      "performance_rate": 60
    },
    "emotions": {
      "eindex": 40,
      "happiness": 15,
      "surprise": 0,
      "calm": 0,
      "fear": 0,
      "sadness": 0,
      "anger": 0,
      "disgust": 0,
      "emotional_intensity_rate": 60,
      "strongest_emotion_by_sentence": [
        [
          "happiness",
          15
        ]
      ]
    }
  }
}

This endpoint TextToEmotions returns sentence properties and emotions of a text, a comment, a review or a feedback.

HTTP Request

GET http://api.qemotion.com/api/v1/get_emotions

Headers parameters

Header Key Required Value
Authorization true Token token=“replace_with_your_api_key”
Content-Type true application/json; charset=UTF-8
lang true en or fr
text true It’s a beautiful day today

In case you would need additional idiomas, pls. contact us. We're currently working hard to implement additional languages to this API.

status

Field name Description
code The status code of the response ( 200 = OK )
message Status response message

content => sentence_properties

Field name Description
total_word_count Detected word number
accentued_punctuation Presence of accented punctuation (ex: ‘?? or !!’)
questioning Is there a ?
exclamation Is there a !

content => confidence_indicators

Field name Description
confidence_rate Confidence rate on the emotional results
sentence_number Detected sentence number
total_known_word Known emotional word number
performance_rate Known emotional word over total word number

content => emotions

Field name Description
eindex Verbatim’s eindex value
happiness Verbatim’s happiness value
surprise Verbatim’s surprise value
calm Verbatim’s calm value
fear Verbatim’s fear value
sadness Verbatim’s sadness value
anger Verbatim’s anger value
disgust Verbatim’s disgust value
emotional_intensity_rate Verbatim’s emotional intensity rate
strongest_emotion_by_sentence Strongest emotion of each sentence

TextToEmotionsPremium API

{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "content": {
    "sentence_properties": {
      "total_word_count": 5,
      "accented_punctuation": false,
      "questioning": false,
      "exclamation": true
    },
    "confidence_indicators": {
      "confidence_rate": 80,
      "sentence_number": 1,
      "total_known_word": 3,
      "performance_rate": 60
    },
    "emotions": {
      "eindex": 40,
      "happiness": 15,
      "surprise": 0,
      "calm": 0,
      "fear": 0,
      "sadness": 0,
      "anger": 0,
      "disgust": 0,
      "emotional_intensity_rate": 60,
      "strongest_emotion_by_sentence": [
        [
          "happiness",
          15
        ]
      ]
    },
    "speech_engagement": {
      "global_engagement": "0,1",
      "details": {
        "speech_size": "0,1",
        "personal_involvement": "0,0",
        "time_orientation": [],
        "emotional_boost": {
          "boost": false,
          "value": "0"
        }
      }
    }
  }
}

This endpoint returns sentence properties, emotions and speech engagement of a text, a comment, a review or a feedback.

HTTP Request

GET http://api.qemotion.com/api/v1/get_emotions_premium

Headers parameters

Header Key Required Value
Authorization true Token token=“replace_with_your_api_key”
Content-Type true application/json; charset=UTF-8
lang true en or fr
text true It’s a beautiful day today

In case you would need additional idiomas, pls. contact us. We're currently working hard to implement additional languages to this API.

status

Field name Description
code The status code of the response ( 200 = OK )
message Status response message

content => sentence_properties

Field name Description
total_word_count Detected word number
accentued_punctuation Presence of accented punctuation (ex: ‘?? or !!’)
questioning Is there a ?
exclamation Is there a !

content => confidence_indicators

Field name Description
confidence_rate Confidence rate on the emotional results
sentence_number Detected sentence number
total_known_word Known emotional word number
performance_rate Known emotional word over total word number

content => emotions

Field name Description
eindex Verbatim’s eindex value in degree Celsius
happiness Verbatim’s happiness value (emotional intensity)
surprise Verbatim’s surprise value
calm Verbatim’s calm value
fear Verbatim’s fear value
sadness Verbatim’s sadness value
anger Verbatim’s anger value
disgust Verbatim’s disgust value
emotional_intensity_rate Verbatim’s emotional intensity rate
strongest_emotion_by_sentence Strongest emotion of each sentence

content => speech_engagement

Field name Description
global_engagement Author’s global engagement
details => speech_size Speech size mark value
details => personal_involvement Author’s persnonal involvement mark
details => time_orientation Used tenses
details => emotional_boost => boost Has an emotional boost been applied?
details => emotional_boost => value Value of the applied emotional boost

TextToSensations API (Beta)

{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "content": {
    "sentence_properties": {
      "total_word_count": 5,
      "accented_punctuation": false,
      "questioning": false,
      "exclamation": true
    },
    "confidence_indicators": {
      "confidence_rate": 80,
      "sentence_number": 1,
      "total_known_word": 3,
      "performance_rate": 60
    },
    "eindex": 40,
    "sensations": {
      "sight": 7,
      "hearing": 0,
      "taste": 0,
      "smell": 0,
      "touch": 0,
      "thermoception": 0,
      "hunger_thirst": 0,
      "pressure_stress": 0,
      "nociception": 0,
      "other": {}
    }
  }
}

This endpoint returns sentence properties and sensations of a text, a comment, a review or a feedback.

HTTP Request

GET http://api.qemotion.com/api/v1/get_sensations

Headers parameters

Header Key Required Value
Authorization true Token token=“replace_with_your_api_key”
Content-Type true application/json; charset=UTF-8
lang true en or fr
text true It’s a beautiful day today

In case you would need additional idiomas, pls. contact us. We're currently working hard to implement additional languages to this API.

status

Field name Description
code The status code of the response ( 200 = OK )
message Status response message

content => sentence_properties

Field name Description
total_word_count Detected word number
accentued_punctuation Presence of accented punctuation (ex: ‘?? or !!’)
questioning Is there a ?
exclamation Is there a !

content => confidence_indicators

Field name Description
confidence_rate Confidence rate on the emotional results
sentence_number Detected sentence number
total_known_word Known emotional word number
performance_rate Known emotional word over total word number

content => eindex

Field name Description
eindex Verbatim’s global eindex

content => sensations

Field name Description
sight Verbatim’s sight value
hearing Verbatim’s hearing value
taste Verbatim’s taste value
smell Verbatim’s smell value
touch Verbatim’s touch value
thermoception Verbatim’s thermoception value
hungert_thirst Verbatim’s hungert_thirst value
pressure_stress Verbatim’s pressure_stress value
nociception Verbatim’s nociception value
other Other sensations values

TextToSensationsPremium API (Beta)

{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "content": {
    "sentence_properties": {
      "total_word_count": 5,
      "accented_punctuation": false,
      "questioning": false,
      "exclamation": true
    },
    "confidence_indicators": {
      "confidence_rate": 80,
      "sentence_number": 1,
      "total_known_word": 3,
      "performance_rate": 60
    },
    "eindex": 40,
    "sensations": {
      "sight": 7,
      "hearing": 0,
      "taste": 0,
      "smell": 0,
      "touch": 0,
      "thermoception": 0,
      "hunger_thirst": 0,
      "pressure_stress": 0,
      "nociception": 0,
      "other": {}
    },
    "speech_engagement": {
      "global_engagement": "0,1",
      "details": {
        "speech_size": "0,1",
        "personal_involvement": "0,0",
        "time_orientation": [],
        "emotional_boost": {
          "boost": false,
          "value": "0"
        }
      }
    }
  }
}

This endpoint TextToSensationsPremium returns sentence properties, sensations and speech engagement of a text, a comment, a review or a feedback.

HTTP Request

GET http://api.qemotion.com/api/v1/get_sensations_premium

Headers parameters

Header Key Required Value
Authorization true Token token=“replace_with_your_api_key”
Content-Type true application/json; charset=UTF-8
lang true en or fr
text true It’s a beautiful day today

In case you would need additional idiomas, pls. contact us. We're currently working hard to implement additional languages to this API.

status

Field name Description
code The status code of the response ( 200 = OK )
message Status response message

content => sentence_properties

Field name Description
total_word_count Detected word number
accentued_punctuation Presence of accented punctuation (ex: ‘?? or !!’)
questioning Is there a ?
exclamation Is there a !

content => confidence_indicators

Field name Description
confidence_rate Confidence rate on the emotional results
sentence_number Detected sentence number
total_known_word Known emotional word number
performance_rate Known emotional word over total word number

content => eindex

Field name Description
eindex Verbatim’s global e-index in °C

content => sensations

Field name Description
sight Verbatim’s sight value
hearing Verbatim’s hearing value
taste Verbatim’s taste value
smell Verbatim’s smell value
touch Verbatim’s touch value
thermoception Verbatim’s thermoception value
hungert_thirst Verbatim’s hungert_thirst value
pressure_stress Verbatim’s pressure_stress value
nociception Verbatim’s nociception value
other Other sensations values

content => speech_engagement

Field name Description
global_engagement Author’s global engagement
details => speech_size Speech size mark value
details => personal_involvement Author’s persnonal involvement mark
details => time_orientation Used tenses
details => emotional_boost => boost Has an emotional boost been applied?
details => emotional_boost => value Value of the applied emotional boost

TextToEmotionsAndThematics API

{
  "status": {
    "code": 200,
    "message": "OK"
  },
  "content": {
    "sentence_properties": {
      "total_word_count": 15,
      "accented_punctuation": false,
      "questioning": false,
      "exclamation": false
    },
    "confidence_indicators": {
      "confidence_rate": 85,
      "sentence_number": 1,
      "total_known_word": 11,
      "performance_rate": 73
    },
    "emotions": {
      "eindex": 7,
      "happiness": 4,
      "surprise": 10,
      "calm": 0,
      "fear": 18,
      "sadness": 12,
      "anger": 0,
      "disgust": 0,
      "emotional_intensity_rate": 19,
      "strongest_emotion_by_sentence": [
        [
          "fear",
          18
        ]
      ]
    },
    "speech_engagement": {
      "global_engagement": "0,55",
      "details": {
        "speech_size": "0,1",
        "personal_involvement": "0,3",
        "time_orientation": [
          "present"
        ],
        "emotional_boost": {
          "boost": false,
          "value": "0"
        }
      }
    },
    "thematics": [
      {
        "thematic": "catering",
        "sub_thematic": "lunch",
        "word": "repas",
        "emotions": {
          "eindex": 7,
          "happiness": 0,
          "surprise": 10,
          "calm": 0,
          "fear": 18,
          "sadness": 0,
          "anger": 0,
          "disgust": 0,
          "emotional_intensity": 100,
          "strongest_emotion": [
            [
              "fear",
              18
            ]
          ]
        }
      },
      {
        "thematic": "staff",
        "sub_thematic": "Cabin crew",
        "word": "hôtesse",
        "emotions": {
          "eindex": 4,
          "happiness": 0,
          "surprise": 1,
          "calm": 0,
          "fear": 7,
          "sadness": 10,
          "anger": 0,
          "disgust": 0,
          "emotional_intensity": 50,
          "strongest_emotion": [
            [
              "sadness",
              10
            ]
          ]
        }
      },
      {
        "thematic": "confort à bord",
        "sub_thematic": "système de divertissement",
        "word": "écran",
        "emotions": {
          "eindex": 40,
          "happiness": 4,
          "surprise": 0,
          "calm": 0,
          "fear": 0,
          "sadness": 3,
          "anger": 0,
          "disgust": 0,
          "emotional_intensity": 28,
          "strongest_emotion": [
            [
              "happiness",
              4
            ]
          ]
        }
      }
    ]
  }
}

This is the best and most complete API to do emotional analysis on thematic of the speech!
The endpoint returns sentence properties, emotional analytics and thematics values of a text or verbatim.

HTTP Request

GET http://api.qemotion.com/api/v1/get_thematics

Important

Headers parameters

Header Key Required Value
Authorization true Token token=“replace_with_your_api_key”
Content-Type true application/json; charset=UTF-8
lang true en or fr
text true Le repas était froid, l'hôtesse n'est pas sympathique mais l’ écran était bien !
model true The name of the Thematic model (defined with us during the setup phase, see upfront)

In case you would need additional idiomas, pls. contact us. We're currently working hard to implement additional languages to this API.

status

Field name Description
code The status code of the response ( 200 = OK )
message Status response message

content => sentence_properties

Field name Description
total_word_count Detected word number
accentued_punctuation Presence of accented punctuation (ex: ‘?? or !!’)
questioning Is there a ?
exclamation Is there a !

content => confidence_indicators

Field name Description
confidence_rate Confidence rate on the emotional results (%)
sentence_number Detected sentence number
total_known_word Known emotional word number
performance_rate Known emotional word over total word number

content => eindex

Field name Description
eindex Verbatim’s global emotional index in °C

content => emotions

Field name Description
eindex Verbatim’s emotional index (e-index) value in °C
happiness Verbatim’s happiness value
surprise Verbatim’s surprise value
calm Verbatim’s calm value
fear Verbatim’s fear value
sadness Verbatim’s sadness value
anger Verbatim’s anger value
disgust Verbatim’s disgust value
emotional_intensity_rate Verbatim’s emotional intensity rate
strongest_emotion_by_sentence Strongest emotion of each sentence

content => thematics

Field name Description
thematic Main thematic name if any
sub_thematic Sub thematic name if any
sub_sub_thematic Sub sub thematic name if any
word Found thematic word
emotions see content => emotions

content => speech_engagement

Field name Description
global_engagement Author’s global engagement
details => speech_size Speech size mark value
details => personal_involvement Author’s persnonal involvement mark
details => time_orientation Used tenses
details => emotional_boost => boost Has an emotional boost been applied?
details => emotional_boost => value Value of the applied emotional boost

HTML status codes

Code Meaning
200 Query successful – Query successfully processed
404 Not Found – The function could not be found
500 Internal Server Error – We had a problem with our server. Try again later.

Back to top