Sign in

v1

latestOpenAPI 3.0.02026-08-061473373.5 KB
Analyze

Analyze text

Analyzes text, HTML, or a public webpage for the following features:

  • Categories
  • Classifications
  • Concepts
  • Emotion
  • Entities
  • Keywords
  • Metadata
  • Relations
  • Semantic roles
  • Sentiment
  • Syntax
  • Summarization (Experimental)

If a language for the input text is not specified with the language parameter, the service automatically detects the language.

post/v1/analyze

Request body

textstring

The plain text to analyze. One of the text, html, or url parameters is required.

htmlstring

The HTML file to analyze. One of the text, html, or url parameters is required.

urlstring

The webpage to analyze. One of the text, html, or url parameters is required.

cleanboolean

Set this to false to disable webpage cleaning. For more information about webpage cleaning, see Analyzing webpages.

xpathstring

An XPath query to perform on html or url input. Results of the query will be appended to the cleaned webpage text before it is analyzed. To analyze only the results of the XPath query, set the clean parameter to false.

fallback_to_rawboolean

Whether to use raw HTML content if text cleaning fails

return_analyzed_textboolean

Whether or not to return the analyzed text

languagestring

ISO 639-1 code that specifies the language of your text. This overrides automatic language detection. Language support differs depending on the features you include in your analysis. For more information, see Language support.

limit_text_charactersinteger

Sets the maximum number of characters that are processed by the service.

advanced_rules.modelstring

The advanced rules feature is deprecated. Existing models are supported until 24 June 2021, but after 10 June 2021, you will not be able to deploy advanced rules models to Natural Language Understanding. After 24 June 2021, advanced rules models will not run in Natural Language Understanding.

An advanced rules model ID

Example request

{
  "features": {
    "concepts": {
      "limit": 3
    },
    "emotion": {
      "targets": [
        "apples",
        "oranges"
      ]
    },
    "entities": {
      "sentiment": true,
      "limit": 1
    },
    "keywords": {
      "sentiment": true,
      "emotion": true,
      "limit": 3
    },
    "semantic_roles": {
      "keywords": true,
      "entities": true
    },
    "sentiment": {
      "targets": [
        "stocks"
      ]
    },
    "syntax": {
      "tokens": {
        "lemma": true,
        "part_of_speech": true
      },
      "sentences": true
    }
  }
}

Response

Analysis results

languagestring

Language used to analyze the text

analyzed_textstring

Text that was used in the analysis

retrieved_urlstring

URL of the webpage that was analyzed

advanced_rulesobject

The advanced rules feature is deprecated. Existing models are supported until 24 June 2021, but after 10 June 2021, you will not be able to deploy advanced rules models to Natural Language Understanding. After 24 June 2021, advanced rules models will not run in Natural Language Understanding.

Response from advanced rules analysis

Example response

{
  "advanced_rules": {
    "Country": [
      {
        "Country": {
          "text": "USA",
          "location": {
            "end": 23,
            "begin": 20
          }
        },
        "Continent": null
      }
    ]
  },
  "concepts": [
    {
      "text": "Social network service",
      "relevance": 0.92186,
      "dbpedia_resource": "http://dbpedia.org/resource/Social_network_service"
    },
    {
      "text": "Thomas J. Watson",
      "relevance": 0.871908,
      "dbpedia_resource": "http://dbpedia.org/resource/Thomas_J._Watson"
    },
    {
      "text": "Lotus Software",
      "relevance": 0.839578,
      "dbpedia_resource": "http://dbpedia.org/resource/Lotus_Software"
    }
  ],
  "entities": [
    {
      "text": "Social network service",
      "relevance": 0.92186,
      "dbpedia_resource": "http://dbpedia.org/resource/Social_network_service"
    },
    {
      "text": "Thomas J. Watson",
      "relevance": 0.871908,
      "dbpedia_resource": "http://dbpedia.org/resource/Thomas_J._Watson"
    },
    {
      "text": "Lotus Software",
      "relevance": 0.839578,
      "dbpedia_resource": "http://dbpedia.org/resource/Lotus_Software"
    }
  ],
  "keywords": [
    {
      "text": "curated online courses",
      "sentiment": {
        "score": 0.792454
      },
      "relevance": 0.864624,
      "emotion": {
        "sadness": 0.188625,
        "joy": 0.522781,
        "fear": 0.12012,
        "disgust": 0.103212,
        "anger": 0.106669
      },
      "count": 1
    },
    {
      "text": "free virtual server",
      "sentiment": {
        "score": 0.664726
      },
      "relevance": 0.864593,
      "emotion": {
        "sadness": 0.265225,
        "joy": 0.532354,
        "fear": 0.07773,
        "disgust": 0.090112,
        "anger": 0.102242
      },
      "count": 1
    }
  ],
  "categories": [
    {
      "score": 0.594296,
      "label": "/technology and computing/computing/computer software and applications"
    },
    {
      "score": 0.448495,
      "label": "/science"
    },
    {
      "score": 0.426429,
      "label": "/business and finance/industries"
    }
  ],
  "classifications": [
    {
      "class_name": "temperature",
      "confidence": 0.562519
    },
    {
      "class_name": "conditions",
      "confidence": 0.433996
    }
  ],
  "emotion": {
    "targets": [
      {
        "text": "apples",
        "emotion": {
          "sadness": 0.028574,
          "joy": 0.859042,
          "fear": 0.02752,
          "disgust": 0.017519,
          "anger": 0.012855
        }
      },
      {
        "text": "oranges",
        "emotion": {
          "sadness": 0.514253,
          "joy": 0.078317,
          "fear": 0.074223,
          "disgust": 0.058103,
          "anger": 0.126859
        }
      }
    ],
    "document": {
      "emotion": {
        "sadness": 0.32665,
        "joy": 0.563273,
        "fear": 0.033387,
        "disgust": 0.022637,
        "anger": 0.041796
      }
    }
  },
  "metadata": {
    "title": "IBM - United States",
    "publication_date": "2015-10-01T00:00:00",
    "image": "",
    "feeds": [],
    "authors": []
  },
  "relations": [
    {
      "type": "awardedTo",
      "sentence": "Leonardo DiCaprio won Best Actor in a Leading Role for his performance.",
      "score": 0.680715,
      "arguments": [
        {
          "text": "Best Actor",
          "location": [
            22,
            32
          ],
          "entities": [
            {
              "type": "EntertainmentAward",
              "text": "Best Actor"
            }
          ]
        },
        {
          "text": "Leonardo DiCaprio",
          "location": [
            0,
            17
          ],
          "entities": [
            {
              "type": "Person",
              "text": "Leonardo DiCaprio"
            }
          ]
        }
      ]
    }
  ],
  "semantic_roles": [
    {
      "subject": {
        "text": "IBM"
      },
      "sentence": "IBM has one of the largest workforces in the world",
      "object": {
        "text": "one of the largest workforces in the world"
      },
      "action": {
        "verb": {
          "text": "have",
          "tense": "present"
        },
        "text": "has",
        "normalized": "have"
      }
    }
  ],
  "sentiment": {
    "targets": [
      {
        "text": "stocks",
        "score": 0.279964,
        "label": "positive"
      }
    ],
    "document": {
      "score": 0.127034,
      "label": "positive"
    }
  },
  "summarization": {
    "text": "Today, IBM and Workday, a leading provider of enterprise applications for human resources and finance, announced a joint solution designed to help companies begin the process of safely re-opening their workplaces. Here are five key takeaways from the announcement. The two companies, which have had a partnership since 2011, announced a new solution to help businesses and communities determine when and how to safely open up their workplaces during the ongoing COVID-19 pandemic."
  }
}