Sentiment Analysis Response [2.1]

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.

JSON
XML

{
  "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"?>
<?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>

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.

Response

Response

Response output

Did you know...?

Sentence object

Sentence object

Segment object

Segment object

Polarity term object

Polarity term object

Entity/concept object

Entity/concept object

Response examples