Getting started is easy

Lymbix is pleased to offer it's sentiment technology as a service for integration with third party applications. This document covers the basic technical information on how to connect and interpret the application-programming interface (API) offered as a service.

To start using the Tone service, you will need an authentication key that you can get by clicking on the API KEYS menu. Most current version is 2.2

Note: Authentication keys do not expire.

Tonalize

back to top

The tonalize method provides article-level Lymbix sentiment data for a single article.

  • URL
  • http(s)://api.lymbix.com/tonalize
  • Headers
  • Authentication :
  • Your Lymbix authentication key (found on your 'Account Details' screen)
  • Accept :
  • This can be either application/json or application/xml to specify which type of response you’d like to receive (application dependent)
  • Version :
  • The version of the API you’d like to use.
  • Parameters
  • article
  • The text that you are going to analyse.
  • return_fields
  • The Lymbix sentiment data fields you would like returned.
  • reference_id
  • A custom tracking id you can use to track the article when you receive the response. The reference id can contain a string or a number.
Example Request
curl \
-H "AUTHENTICATION:{YOUR_AUTH_KEY}" \
-H "ACCEPT:application/json" \
-H "VERSION:2.2" \
http://api.lymbix.com/tonalize \
-d "article=He was happy and surprised instead of being an angry guy. \
            Although he wasn't too happy about it he said yes anyways! \
            What do you think of this decision? \
    &return_fields=[] \
    &reference_id=1243122"
Example Response
{
  "article":"He was happy and surprised instead of being an angry guy. 
             Although he wasn't too happy about it he said yes anyways!
             What do you think of this decision?",
  "ignored_terms":["He"],
  "affection_friendliness":2.6,
  "enjoyment_elation":4.55,
  "amusement_excitement":3.58,
  "contentment_gratitude":3.78,
  "sadness_grief":-0.24,
  "anger_loathing":-2.46,
  "fear_uneasiness":-1.28,
  "humiliation_shame":-0.12,
  "dominant_emotion":"enjoyment_elation",
  "article_sentiment": {
                          "sentiment":"Positive",
                          "score":7.8},
  "coverage":53,
  "intense_sentence": {
                         "sentence":"was happy and surprised instead of being an angry guy.",
                         "dominant_emotion":"enjoyment_elation",
                         "intensity":0.15},
  "reference_id":1243122,
  "clarity":53.91
}

Flag Response

back to top

The flag_response method allows data consumers to indicate to Lymbix that it's data for a particular phrase may be incorrect. When a phrase is flagged it goes back into our system for high priority rating.

  • URL
  • http(s)://api.lymbix.com/flag_response
  • Headers
  • Authentication :
  • Your Lymbix authentication key (found on your 'Account Details' screen)
  • Version :
  • The version of the API you’d like to use.
  • Parameters
  • phrase
  • The piece of text you you feel may be rated incorrectly
  • reference_id
  • A custom tracking id you can use to track the article when you receive the response. The reference id can contain a string or a number.
  • api_method_requested
  • The API method that was called that returned the incorrect rating
  • api_version
  • The API version that was used when you recieved the incorrect rating
  • callback_url
  • If you provide a callback_url when you flag a response, the Tone service will re-analyze the phrase you flagged and it will send a HTTP POST to the specified callback_url
Example Request
curl \ 
-H "AUTHENTICATION:{YOUR_AUTH_KEY}" \
-H "VERSION:2.2" \
http(s)://api.lymbix.com/flag_response \
-d "phrase=He was happy and surprised instead of being angry. \
           Although he wasn't too happy about it he said yes anyways! \
           What do you think of this decision? \
    &reference_id=AD1234 \
    &api_method_requested=tonalize_detailed \
    &api_version = 2.2 \
    &callback_url="
Example Response
HTTP 200/OK
Thank you for your submission
CallBack Response
callback_reference_id = "your custom tracking id"
phrase = 'He was happy and surprised instead of being angry.'
callback_response = (JSON or XML tone data received by tone service)

Tonalize Detailed

back to top

The tonalize_detailed method provides article-level Lymbix sentiment data along with a sentence by sentence sentiment data for a single article.

  • URL
  • http(s)://api.lymbix.com/tonalize_detailed
  • Headers
  • Authentication :
  • Your Lymbix authentication key (found on your 'Account Details' screen)
  • Accept :
  • This can be either application/json or application/xml to specify which type of response you’d like to receive (application dependent)
  • Version :
  • The version of the API you’d like to use.
  • Parameters
  • article
  • The text that you are going to analyse.
  • return_fields
  • The Lymbix sentiment data fields you would like returned.
  • reference_id
  • A custom tracking id you can use to track the article when you receive the response. The reference id can contain a string or a number.
Example Request
curl \
-H "AUTHENTICATION:{YOUR_AUTH_KEY}" \
-H "ACCEPT:application/json" \
-H "VERSION:2.2" \
http(s)://api.lymbix.com/tonalize_detailed \
-d "article=We’re just as proud about what we don’t do as we are of \
            what they do. We’re willing to lose some customers if it means 
            that others love our products intensely. if you had to launch 
             your business in two weeks, what would you cut \
    &return_fields=[] \
    &reference_id=1243122"
Example Response
{
  "article":"We’re just as proud about what we don’t do as we are of 
             what they do. We’re willing to lose some customers if it means that 
             others love our products intensely. if you had to launch your business 
             in two weeks, what would you cut",
  "ignored_terms":[],
  "affection_friendliness":3.3,
  "enjoyment_elation":2.17,
  "amusement_excitement":1.93,
  "contentment_gratitude":1.84,
  "sadness_grief":-0.56,
  "anger_loathing":-0.66,
  "fear_uneasiness":-1.16,
  "humiliation_shame":-0.26,
  "dominant_emotion":"affection_friendliness",
  "article_sentiment": {
                          "sentiment":"Positive",
                          "score":7.8},
  "coverage":20,
  "intense_sentence": {
                         "sentence":"Were willing to lose some customers if it means that 
                                     others love our products intensely.",
                         "dominant_emotion":"affection_friendliness",
                         "intensity":0.01},
  "clarity":58.87,     
  "reference_id":1243122,
  "sentences_data":[
                     {
                        "sentence":"We’re just as proud about what we don’t do as we
                                    are of what they do.",
                        "dominant_emotion":"anger_loathing",
                        "enjoyment_elation":0.78,
                        "amusement_excitement":0.48,
                        "contentment_gratitude":0.96,
                        "sadness_grief":-2.47,
                        "anger_loathing":-3.3,
                        "fear_uneasiness":-2.49,
                        "humiliation_shame":-1.1,
                        "affection_friendliness":0.74,
                        "sentence_sentiment": {
                                                "sentiment":"Negative",
                                                "score":7.6},
                        "ignored_terms":[],
                        "clarity":60.7,
                        "coverage":18},
					 {
                        "sentence":"We’re willing to lose some customers if it means that 
                                    others love our products intensely.",
                        "dominant_emotion":"affection_friendliness",
                        "enjoyment_elation":2.23,
                        "amusement_excitement":2.03,
                        "contentment_gratitude":1.51,
                        "sadness_grief":-0.54,
                        "anger_loathing":-0.18,
                        "fear_uneasiness":-1.6,
                        "humiliation_shame":-0.21,
                        "affection_friendliness":4.34,
                        "sentence_sentiment": {
                                                "sentiment":"Positive",
                                                "score":8.0},
                        "ignored_terms":[],
                        "clarity":69.14,
                        "coverage":32},
                     {
                        "sentence":"if you had to launch your business  in two weeks,",
                        "dominant_emotion":"contentment_gratitude",
                        "enjoyment_elation":2.8,
                        "amusement_excitement":2.3,
                        "contentment_gratitude":3.71,
                        "sadness_grief":-0.21,
                        "anger_loathing":-0.33,
                        "fear_uneasiness":-0.42,
                        "humiliation_shame":-0.19,
                        "affection_friendliness":2.75,
                        "sentence_sentiment": {
                                                "sentiment":"Positive",
                                                "score":9.1},
                        "ignored_terms":[],
                        "clarity":34.32,
                        "coverage":20},
                     {
                        "sentence":"what would you cut\"",
                        "dominant_emotion":"contentment_gratitude",
                        "enjoyment_elation":0.3,
                        "amusement_excitement":0.47,
                        "contentment_gratitude":0.66,
                        "sadness_grief":-0.05,
                        "anger_loathing":0,
                        "fear_uneasiness":-0.01,
                        "humiliation_shame":0,
                        "affection_friendliness":0.08,
                        "sentence_sentiment": {
                                                "sentiment":"Positive",
                                                "score":9.6},
                        "ignored_terms":[],
                        "clarity":20.63,
                        "coverage":10}
					]
}
		

Tonalize Multiple

back to top

The tonalize_multiple method provides article-level Lymbix sentiment data for multiple articles.

  • URL
  • http(s)://api.lymbix.com/tonalize_multiple
  • Headers
  • Authentication :
  • Your Lymbix authentication key (found on your 'Account Details' screen)
  • Accept :
  • This can be either application/json or application/xml to specify which type of response you’d like to receive (application dependent)
  • Version :
  • The version of the API you’d like to use.
  • Parameters
  • articles
  • The comma separated list of the text that you are going to analyse.
  • return_fields
  • The Lymbix sentiment data fields you would like returned.
  • reference_ids
  • A list of custom tracking ids you can use to track the article when you receive the response. The reference ids can contain a string or a number.
Example Request
curl \
-H "AUTHENTICATION:{YOUR_AUTH_KEY}" \
-H "ACCEPT:application/json" \
-H "VERSION:2.2" \
http(s)://api.lymbix.com/tonalize_multiple \
-d "articles=[\"Happy man dance\",\"Unfortunate Disaster\"] \
    &return_fields=[] \
	&reference_ids=[123,124]"
		
Example Response
[
  {
     "article":"Happy man dance",
     "ignored_terms":[],
     "affection_friendliness":1.43,
     "enjoyment_elation":3.6,
     "amusement_excitement":2.45,
     "contentment_gratitude":3.46,
     "sadness_grief":-0.14,
     "anger_loathing":-0.12,
     "fear_uneasiness":-0.24,
     "humiliation_shame":-0.11,
     "dominant_emotion":"enjoyment_elation",
     "article_sentiment": {
                             "sentiment":"Positive",
                             "score":9.5},
     "coverage":95,
     "intense_sentence": {
                            "sentence":"Happy man dance",
                            "dominant_emotion":"enjoyment_elation",
                            "intensity":0.36},
     "reference_id":123,
     "clarity":89.52},
  {
     "article":"Unfortunate Disaster",
     "ignored_terms":[],
     "affection_friendliness":0,
     "enjoyment_elation":0.29,
     "amusement_excitement":0,
     "contentment_gratitude":0.11,
     "sadness_grief":-1.28,
     "anger_loathing":-1.6,
     "fear_uneasiness":-4.53,
     "humiliation_shame":-0.48,
     "dominant_emotion":"fear_uneasiness",
     "article_sentiment": {
                             "sentiment":"Negative",
                             "score":-9.5},
     "coverage":95,
     "intense_sentence": {
                            "sentence":"Unfortunate Disaster",
                            "dominant_emotion":"fear_uneasiness",
                            "intensity":-0.45},
     "reference_id":124,
     "clarity":58.28}
]