Response

The output contains information about the status of the request, the different polarities identified in the text, its subjectivity and if it contains irony marks. The information provided is the same for the different output formats and the naming convention used for all fields is lowercase_separated_by_underscore.

The following table shows the fields included in the response object.

Response output

Name Description
status

Contains information about the extraction process and whether it has finished successfully. It is formed by four different values:

  • code: a natural number that identifies the status returned.
  • msg: a string describing the status.
  • credits: contains a natural number that indicates the credits consumed in the request.
  • remaining_credits: shows the number of credits left to the user to reach the credit limit.

Out of these four fields, code and msg will always appear in the response.

You can find all the possible status codes returned by the API with an explanation and tips on how to manage them in our error codes catalog.

A request is any HTTP request done to the API to analyze less than 500 words. If the text sent is longer than that, then it will be considered that more than a request is made, more specifically, as many requests as we would need if the text were divided in chunks of 500 words.

For instance, an HTTP request with 1013 words, will count as three requests, so 3 credits will be consumed; an HTTP request with a text 25648 words long would count as 25648/500 = 51.296 => 52 credits, and so on.

Did you know...?

Only the successful requests to the API will consume credits. In other words, the credits specified in the answer will only count as credits consumed when code=0.

model

This field holds the model used in the evaluation followed by an underscore and the language in which the analysis has been carried out.

score_tag

This tag indicates the polarity found (or not found) in the element it refers to. It may apply to several elements: polarity_term, sentimented_concept, sentimented_entity, segment, sentence or the global polarity of the text.

The possible values are the following:

  • P+: strong positive
  • P: positive
  • NEU: neutral
  • N: negative
  • N+: strong negative
  • NONE: without sentiment
agreement

This field marks the agreement between the sentiments detected in the text, the sentence or the segment it refers to. It has two possible values:

  • AGREEMENT: the different elements have the same polarity.
  • DISAGREEMENT: there is disagreement between the different elements' polarity.
subjectivity

This field marks the subjectivity of the text. It has two possible values:

  • OBJECTIVE: the text does not have any subjectivity marks.
  • SUBJECTIVE: the text has subjective marks.
confidence

This field represents the confidence associated with the sentiment analysis performed on the text. Its value is an integer number in the 0-100 range.

irony

This field indicates the irony of the text. It has two possible values:

  • NONIRONIC: the text does not have ironic marks
  • IRONIC: the text has ironic marks
sentence_list

List of sentences in which the text is divided. Each sentence is represented by an element sentence.

sentimented_entity_list

This is a list of the entities identified in the text with a certain polarity. These entities are the same ones that would be detected by the Topics Extraction API, the only difference will be in the Hashtags, Cashtags and Nicknames entities. These cases, because of their special importance in social media analyses, will also include (in the cases they have it), their known subtopics. For instance, if @BBC is detected, it will apear as a nickname, but also as the entity "BBC" (a Media Company).

Each one will be represented by an element sentimented entity.

sentimented_concept_list

This is a list of the concepts identified in the text with a certain polarity. Each one will be represented by an element sentimented concept.

Sentence object

The following table contains the fields that will appear in a sentence object.

Sentence object

Name Description
text Text of the sentence.
inip Position in which the sentence begins (starting from 0).
endp Position in which the sentence ends.
bop Marks if the sentence is the of beginning of the paragraph using y or n as values.
confidence

See the explanation given in the response object.

score_tag See the explanation given in the response object.
agreement See the explanation given in the response object.
segment_list List of segments in which each sentence has been divided to perform the analysis. Each segment represents a fragment of the sentence that expresses a single opinion.Each segment element is represented by a segment object.
sentimented_entity_list This is a list of the entities identified in the sentence.
sentimented_concept_list This is a list of the concepts identified in the sentence.

Segment object

Segments are the chunks in which the text is divided to perform the sentiment analysis and that express a single opinion. The following table contains the fields that will appear in a segment object.

Segment object

Name Description
text Text of the segment.
segment_type This field indicates if the segment has been used to compute the aggregated polarity of its parent. It has two possible values:
  • main: the segment is used to compute the aggregated polarity of its parent.
  • secondary: the segment is not used used to compute the aggregated polarity of its parent.
An example would be the sentence "The handsome gentleman stole the Crown Jewels". In this case, "The handsome gentleman" will be a secondary segment of the sentence, as the polarity expressed in it won't have any weight for the aggregated polarity of the sentence it's in.
inip Position in which the segment begins (starting from 0).
endp Position in which the segment ends.
confidence See the explanation given in the response object.
score_tag See the explanation given in the response object.
agreement See the explanation given in the response object.
polarity_term_list List of words with polarity found in the segment. Each one is represented by an element polarity term.
segment_list Each segment can have another segment_list field if the sentiment analyzer detects smaller segments inside it. These segments are the smallest level of fragmentation that the system can detect. This second level of elements will only appear if necessary.
sentimented_entity_list This is a list of the entities identified in the segment but that are not affected by the polarity terms identified in it.
sentimented_concept_list This is a list of the concepts identified in the segment but that are not affected by the polarity terms identified in it.

Polarity term object

Polarity terms are the words detected in the text with a polarity associated. Polarity terms may have different polarities depending on their context: their polarity may be amplified, inverted or determined by their surrounding words. Each polarity_term will contain the following fields:

Polarity term object

Name Description
text Text of the term, including between parentheses the polarity modifiers it is affected by, and the context words used to determine its polarity. In the cases where the polarity term is formed by several words, they will be separated by underscores, '_'.
inip Position in which the polarity term begins (starting from 0).
endp Position in which the polarity term ends.
tag_stack Polarity modifiers affecting this polarity term. It appears only when verbose=y.
confidence See the explanation given in the response object.
score_tag See the explanation given in the response object.
sentimented_entity_list In the cases where they exist, this will contain a list of entities affected by the polarity term. Each element will be tagged as an sentimented entity object.
sentimented_concept_list In the cases where they exist, this will contain a list of concepts affected by the polarity term. Each element will be tagged as a sentimented concept object.

Entity/concept object

The entities and concepts that are detected in the text will appear in different elements of the output. The sentimented_entity_list and sentimented_concept_list associated to polarity terms will contain the same polarity information as the polarity term they are included in; they will also have information about the entity/concept appearance. In the case of the entities not affected by the polarity of a segment, they will also contain information about their appearance and the polarity value associated will be NONE.

Both elements have the same fields:

Entity/concept object

Name Description
form Main form of the entity/concept in the language specified in the ilang parameter.
id ID of the entity/concept. This ID will correspond to its senseID in resources (including user resources). If the entity/concept has been detected in the analysis, the ID will be specifically created for that analysis and will begin by two underscores.
variant How the entity/concept appears in the text (only in polarity_term elements).
inip Position in which the entity/concept begins, starting from 0 (only in polarity_term elements).
endp Position in which the entity/concept ends (only in polarity_term elements).
type Ontology type of the entity/concept. You can see the different types in our ontology.
score_tag See the explanation given in the response object.

As it has been mentioned before, these entities/concepts are the same ones that are detected by the Topics Extraction API, the only difference is in the Hashtags, Cashtags and Nicknames entities. These cases, because of their special importance in social media analyses, will also include (in the cases they have it), their known subtopics. For instance, if @BBC is detected, it will apear as a nickname, but also as the entity "BBC" (a Media Company).

Response examples

The format in which this information will be shown will depend on the value of the of and verbose parameters.

The following is the output that will be obtained when verbose=n.

    The restaurant was great even though it’s not near Madrid.
{
  "status": {
    "code": "0",
    "msg": "OK",
    "credits": "1"
  },
  "model": "general_en",
  "score_tag": "P+",
  "agreement": "AGREEMENT",
  "subjectivity": "OBJECTIVE",
  "confidence": "100",
  "irony": "NONIRONIC",
  "sentence_list": [
    {
      "text": "The restaurant was great even though it’s not near Madrid.",
      "inip": "0",
      "endp": "57",
      "bop": "y",
      "confidence": "100",
      "score_tag": "P+",
      "agreement": "AGREEMENT",
      "segment_list": [
        {
          "text": "The restaurant was great even though it’s not near Madrid",
          "segment_type": "main",
          "inip": "0",
          "endp": "56",
          "confidence": "100",
          "score_tag": "P+",
          "agreement": "AGREEMENT",
          "polarity_term_list": [
            {
              "text": "great",
              "inip": "19",
              "endp": "23",
              "confidence": "100",
              "score_tag": "P+",
              "sentimented_concept_list": [
                {
                  "form": "restaurant",
                  "id": "4d5e117421",
                  "variant": "restaurant",
                  "inip": "4",
                  "endp": "13",
                  "type": "Top>Location>Facility",
                  "score_tag": "P+"
                }
              ]
            }
          ],
          "sentimented_entity_list": [
            {
              "form": "Madrid",
              "id": "3d0a16c68d",
              "variant": "Madrid",
              "inip": "51",
              "endp": "56",
              "type": "Top>Location>GeoPoliticalEntity>City",
              "score_tag": "NONE"
            }
          ]
        }
      ],
      "sentimented_entity_list": [
        {
          "form": "Madrid",
          "id": "3d0a16c68d",
          "type": "Top>Location>GeoPoliticalEntity>City",
          "score_tag": "NONE"
        }
      ],
      "sentimented_concept_list": [
        {
          "form": "restaurant",
          "id": "4d5e117421",
          "type": "Top>Location>Facility",
          "score_tag": "P+"
        }
      ]
    }
  ],
  "sentimented_entity_list": [
    {
      "form": "Madrid",
      "id": "3d0a16c68d",
      "type": "Top>Location>GeoPoliticalEntity>City",
      "score_tag": "NONE"
    }
  ],
  "sentimented_concept_list": [
    {
      "form": "restaurant",
      "id": "4d5e117421",
      "type": "Top>Location>Facility",
      "score_tag": "P+"
    }
  ]
}
                

<?xml version="1.0" encoding="utf-8"?>
<response>
  <status code="0" credits="1">
    <![CDATA[OK]]>
  </status>
  <model>general_en</model>
  <score_tag>P+</score_tag>
  <agreement>AGREEMENT</agreement>
  <subjectivity>OBJECTIVE</subjectivity>
  <confidence>100</confidence>
  <irony>NONIRONIC</irony>
  <sentence_list>
    <sentence>
      <text>
        <![CDATA[The restaurant was great even though it’s not near Madrid.]]>
      </text>
      <inip>0</inip>
      <endp>57</endp>
      <bop>y</bop>
      <confidence>100</confidence>
      <score_tag>P+</score_tag>
      <agreement>AGREEMENT</agreement>
      <segment_list>
        <segment>
          <text>
            <![CDATA[The restaurant was great even though it’s not near Madrid]]>
          </text>
          <inip>0</inip>
          <endp>56</endp>
          <confidence>100</confidence>
          <score_tag>P+</score_tag>
          <agreement>AGREEMENT</agreement>
          <polarity_term_list>
            <polarity_term>
              <text>
                <![CDATA[great]]>
              </text>
              <inip>19</inip>
              <endp>23</endp>
              <confidence>100</confidence>
              <score_tag>P+</score_tag>
              <sentimented_concept_list>
                <sentimented_concept>
                  <form>
                    <![CDATA[restaurant]]>
                  </form>
                  <id>
                    <![CDATA[4d5e117421]]>
                  </id>
                  <variant>
                    <![CDATA[restaurant]]>
                  </variant>
                  <inip>4</inip>
                  <endp>13</endp>
                  <type>
                    <![CDATA[Top>Location>Facility]]>
                  </type>
                  <score_tag>P+</score_tag>
                </sentimented_concept>
              </sentimented_concept_list>
            </polarity_term>
          </polarity_term_list>
          <sentimented_entity_list>
            <sentimented_entity>
              <form>
                <![CDATA[Madrid]]>
              </form>
              <id>
                <![CDATA[3d0a16c68d]]>
              </id>
              <variant>
                <![CDATA[Madrid]]>
              </variant>
              <inip>51</inip>
              <endp>56</endp>
              <type>
                <![CDATA[Top>Location>GeoPoliticalEntity>City]]>
              </type>
              <score_tag>NONE</score_tag>
            </sentimented_entity>
          </sentimented_entity_list>
        </segment>
      </segment_list>
    </sentence>
    <sentimented_entity_list>
      <sentimented_entity>
        <id>
          <![CDATA[3d0a16c68d]]>
        </id>
        <form>
          <![CDATA[Madrid]]>
        </form>
        <type>Top>Location>GeoPoliticalEntity>City</type>
        <score_tag>NONE</score_tag>
      </sentimented_entity>
    </sentimented_entity_list>
    <sentimented_concept_list>
      <sentimented_concept>
        <id>
          <![CDATA[4d5e117421]]>
        </id>
        <form>
          <![CDATA[restaurant]]>
        </form>
        <type>Top>Location>Facility</type>
        <score_tag>P+</score_tag>
      </sentimented_concept>
    </sentimented_concept_list>
  </sentence_list>
  <sentimented_entity_list>
    <sentimented_entity>
      <id>
        <![CDATA[3d0a16c68d]]>
      </id>
      <form>
        <![CDATA[Madrid]]>
      </form>
      <type>Top>Location>GeoPoliticalEntity>City</type>
      <score_tag>NONE</score_tag>
    </sentimented_entity>
  </sentimented_entity_list>
  <sentimented_concept_list>
    <sentimented_concept>
      <id>
        <![CDATA[4d5e117421]]>
      </id>
      <form>
        <![CDATA[restaurant]]>
      </form>
      <type>Top>Location>Facility</type>
      <score_tag>P+</score_tag>
    </sentimented_concept>
  </sentimented_concept_list>
</response>
                

Check the response document DTD: XML DTD.

When verbose=y, the only change that will be seen is that fields more focused on debugging the sentiment obtained are shown. Currently this is just the tag_stack field.