Sentiment Analysis API Documentation

Sentiment Analysis API Implementation instructions

Sentiment Analysis API, used for detection of the sentiment of a message, uses a JSON-based RPC format and can be accessed trough GET and POST interfaces over the world wide web. The API endpoint is located at: 

http://api.ai-applied.nl/api/sentiment_api/

Note: All API functionality can be tested for free using "DEMO_ACCOUNT" as API key.

The API call can be passed in a JSON format using the POST of GET command: 

request={
"data":{
"api_key":"your_api_key",
"call":{
"return_original":false,
"classifier":"default",
"data":[
{
"text":"your_text",
"language_iso":"iso_639_3_language",
"id":0
}
]
}

The API call contains the following parameters:

 

ParameterObligatoryDescription
dataYestransport container for the API call
api_keyYesyour key for the use of this API
callYesthe API call information container
return_originalNoreturn full posted messages (true) together with the language annotation or only the message id's (false) annotated with language
classifierNospecifies which classifier to use. Sentiment Analysis API offers two standard classifiers, "default" and "subjective". The "default" classifier provides a two-class classification ("positive"/"negative"), while the "subjective" classifier provides the "neutral" class as well (experimental functionality). In addition, it is possible to use custom classifiers, tailored to your purposes - contact us for more information. If this value is not provided, "default" classifier is used.
dataYesa list of JSON-dictionary formatted messages, or a link to a data source API returning such formatted messages (see API nesting documentation)

All messages passed in the final data parameter need to be JSON formatted like the following example:

{
"text":"Some message text",
"language_iso":"iso_639_3_language",
"id":some_id
}

Every message  consists of the following parameters:

 

ParameterObligatoryDescription
textYesThe message text as a string
idYesa unique message ID as a string or an integer
language_isoYesspecifying the language of this individual message in a ISO-639-3 format as a string. ISO-639-3 codes for the supported languages are:

  • eng for English
  • nld for Dutch
  • deu for German
  • fra for French
  • spa for Spanish
  • ita for Italian
  • rus for Russian

  • While the appropriate languages can be provided to the Sentiment Analysis API by you, the user, if you do not have this information available you can also use our Language Detection API to perform automatic language annotations for you. It is possible to do language annotation and demographics analysis in one pass using our API nesting method

    NOTE: All Ai Applied API's are much more efficient in BATCH PROCESSING mode than when processing one message at the time. We encourage the sending of up to 20.000 messages at a time for processing, as larger batches incur additional bonuses in processing speed per message.

     

    Sample call and response interpretation

     

    This example requests from the Sentiment Analysis API the annotation of three messages in different languages for their sentiment. You can copy-paste the code below into your browser URL bar, or click here, to view the API response:

     

    http://api.ai-applied.nl/api/sentiment_api/?request={
    "data":{
    "api_key":"DEMO_ACCOUNT",
    "call":{
    "return_original":true,
    "classifier":"subjective",
    "data":[
    {
    "text":"sometimes you get nicely surprised from unexpected sources",
    "language_iso":"eng",
    "id":1
    },
    {
    "text":"Nou... dat is slecht. :(",
    "language_iso":"nld",
    "id":2
    },
    {
    "text":"Hast du heute schon die Zeitung gelesen?",
    "language_iso":"deu",
    "id":3
    }
    ]
    }
    }
    }

    This call returns the following JSON formatted message: 

    {
    "status":1,
    "id":null,
    "response":{
    "data":[
    {
    "language_iso":"deu",
    "text":"Hast du heute schon die Zeitung gelesen?",
    "confidence_sentiment":0.9999999999999967,
    "id":3,
    "sentiment_class":"neutral"
    },
    {
    "language_iso":"nld",
    "text":"Nou... dat is slecht. :(",
    "confidence_sentiment":0.706430044378566,
    "id":2,
    "sentiment_class":"negative"
    },
    {
    "language_iso":"eng",
    "text":"sometimes you get nicely surprised from unexpected sources",
    "confidence_sentiment":0.47548059078354354,
    "id":1,
    "sentiment_class":"positive"
    }
    ],
    "description":"OK: Call processed.",
    "success":true
    }
    }

    Following parameters in API reply belong to the transport layer, and can be stripped away in case of success:  

    ParameterDescription
    statushas value 1 if the transport of the message has been conducted succesfully trough all systems
    ida optional callback parameter that can be ignored for this API
    responsecontains the response from the API classifiers

    The "response" parameter contains this API's reply and consists of the following subparameters:

    ParameterDescription
    successindicates whether the API call has been completed with success (==true), or has failed (==false)
    descriptiongives a description of the API call's success or failure as a string
    datacontains a list of sentiment annotated texts provided by the API in a JSON format

    All messages returned in the data parameter are JSON formatted like the following example:

    {
    "language_iso":"eng",
    "confidence_sentiment":0.47548059078354354,
    "text":"sometimes you get pleasantly surprised from unexpected sources",
    "id":1,
    "sentiment_class":"positive"
    }

    When the "return_original" parameter is set to true in the API call, the returned messages contain all parameters provided to the API in the call in addition to the annotation parameters. If the "return_original" parameter is set to false in the API call, only the following annotation parameters are returned: 

    ParameterDescription
    sentiment_classthe sentiment class extracted from text. Depending on the classifier used, this class can be "positive", "negative", "neutral" or "unknown" if the message itself was in a unsupported language.
    confidence_sentimentthe confidence the API has in it's judgement about the detected sentiment class

     

    The results obtained from the Sentiment Analysis API can also be used as a part of further message processing by our API's, such as the Demographics API.

    If you need more assistance with the implementation of this API, please don't hesitate to comment below, or contact us for assistance!