---
title: "Analyze text"
method: POST
path: "/v1/analyze"
tags: ["Analyze"]
---

# Analyze text

`POST /v1/analyze`

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](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-detectable-languages).

## Request body

- Parameters — An object containing request parameters
  - `text` string — The plain text to analyze. One of the `text`, `html`, or `url` parameters is required.
  - `html` string — The HTML file to analyze. One of the `text`, `html`, or `url` parameters is required.
  - `url` string — The webpage to analyze. One of the `text`, `html`, or `url` parameters is required.
  - `features` object, required — Specific features to analyze the document for
    - `classifications` ClassificationsOptions — Returns text classifications for the content.
      - `model` string — Enter a [custom model](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing) ID of the classifications model to be used. You can analyze tone by using a language-specific model ID. See [Tone analytics (Classifications)](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-tone_analytics) for more information.
    - `concepts` ConceptsOptions — Returns high-level concepts in the content. For example, a research paper about deep learning might return the concept, "Artificial Intelligence" although the term is not mentioned. Supported languages: English, French, German, Italian, Japanese, Korean, Portuguese, Spanish.
      - `limit` integer — Maximum number of concepts to return.
    - `emotion` EmotionOptions — Detects anger, disgust, fear, joy, or sadness that is conveyed in the content or by the context around target phrases specified in the targets parameter. You can analyze emotion for detected entities with `entities.emotion` and for keywords with `keywords.emotion`. Supported languages: English
      - `document` boolean — Set this to `false` to hide document-level emotion results
      - `targets` string[] — Emotion results will be returned for each target string that is found in the document
    - `entities` EntitiesOptions — Identifies people, cities, organizations, and other entities in the content. For more information, see [Entity types and subtypes](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-entity-type-systems). Supported languages: English, French, German, Italian, Japanese, Korean, Portuguese, Russian, Spanish, Swedish. Arabic, Chinese, and Dutch are supported only through custom models.
      - `limit` integer — Maximum number of entities to return.
      - `mentions` boolean — Set this to `true` to return locations of entity mentions
      - `model` string — Enter a [custom model](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing) ID to override the standard entity detection model
      - `sentiment` boolean — Set this to `true` to return sentiment information for detected entities
      - `emotion` boolean — Set this to `true` to analyze emotion for detected keywords
    - `keywords` KeywordsOptions — Returns important keywords in the content. Supported languages: English, French, German, Italian, Japanese, Korean, Portuguese, Russian, Spanish, Swedish.
      - `limit` integer — Maximum number of keywords to return
      - `sentiment` boolean — Set this to `true` to return sentiment information for detected keywords
      - `emotion` boolean — Set this to `true` to analyze emotion for detected keywords
    - `metadata` MetadataOptions — Returns information from the document, including author name, title, RSS/ATOM feeds, prominent page image, and publication date. Supports URL and HTML input types only.
    - `relations` RelationsOptions — Recognizes when two entities are related and identifies the type of relation. For example, an `awardedTo` relation might connect the entities "Nobel Prize" and "Albert Einstein". For more information, see [Relation types](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-relations). Supported languages: Arabic, English, German, Japanese, Korean, Spanish. Chinese, Dutch, French, Italian, and Portuguese custom models are also supported.
      - `model` string — Enter a [custom model](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing) ID to override the default model
    - `semantic_roles` SemanticRolesOptions — Parses sentences into subject, action, and object form. Supported languages: English, German, Japanese, Korean, Spanish.
      - `limit` integer — Maximum number of semantic_roles results to return
      - `keywords` boolean — Set this to `true` to return keyword information for subjects and objects
      - `entities` boolean — Set this to `true` to return entity information for subjects and objects
    - `sentiment` SentimentOptions — Analyzes the general sentiment of your content or the sentiment toward specific target phrases. You can analyze sentiment for detected entities with `entities.sentiment` and for keywords with `keywords.sentiment`. Supported languages: Arabic, English, French, German, Italian, Japanese, Korean, Portuguese, Russian, Spanish
      - `document` boolean — Set this to `false` to hide document-level sentiment results
      - `targets` string[] — Sentiment results will be returned for each target string that is found in the document
    - `summarization` SummarizationOptions — (Experimental) Returns a summary of content. Supported languages: English only. Supported regions: Dallas region only
      - `limit` integer — Maximum number of summary sentences to return
    - `categories` CategoriesOptions — Returns a hierarchical taxonomy of the content. The top three categories are returned by default. Supported languages: Arabic, English, French, German, Italian, Japanese, Korean, Portuguese, Spanish.
      - `explanation` boolean — Set this to `true` to return explanations for each categorization. **This is available only for English categories.**
      - `limit` integer — Maximum number of categories to return.
      - `model` string — (Beta) Enter a [custom model](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-customizing) ID to override the standard categories model. **This is available only for English categories.**
    - `syntax` SyntaxOptions — Returns tokens and sentences from the input text.
      - `tokens` object — Tokenization options.
        - `lemma` boolean — Set this to `true` to return the lemma for each token.
        - `part_of_speech` boolean — Set this to `true` to return the part of speech for each token.
      - `sentences` boolean — Set this to `true` to return sentence information.
  - `clean` boolean — Set this to `false` to disable webpage cleaning. For more information about webpage cleaning, see [Analyzing webpages](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-analyzing-webpages).
  - `xpath` string — An [XPath query](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-analyzing-webpages#xpath) 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_raw` boolean — Whether to use raw HTML content if text cleaning fails
  - `return_analyzed_text` boolean — Whether or not to return the analyzed text
  - `language` string — 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](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-language-support).
  - `limit_text_characters` integer — Sets the maximum number of characters that are processed by the service.
  - `advanced_rules.model` string — 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

## Response `200`

Analysis results

- AnalysisResults — Analysis results for each requested feature
  - `language` string — Language used to analyze the text
  - `analyzed_text` string — Text that was used in the analysis
  - `retrieved_url` string — URL of the webpage that was analyzed
  - `usage` object — API usage information for the request
    - `features` integer — Number of features used in the API call
    - `text_characters` integer — Number of text characters processed
    - `text_units` integer — Number of 10,000-character units processed
  - `advanced_rules` object — 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
  - `concepts` ConceptsResult[] — The general concepts referenced or alluded to in the analyzed text
    - `text` string — Name of the concept
    - `relevance` number, double — Relevance score between 0 and 1. Higher scores indicate greater relevance
    - `dbpedia_resource` string — Link to the corresponding DBpedia resource
  - `entities` EntitiesResult[] — The entities detected in the analyzed text
    - `type` string — Entity type
    - `text` string — The name of the entity
    - `relevance` number, double — Relevance score from 0 to 1. Higher values indicate greater relevance
    - `confidence` number, double — Confidence in the entity identification from 0 to 1. Higher values indicate higher confidence. In standard entities requests, confidence is returned only for English text. All entities requests that use custom models return the confidence score.
    - `mentions` EntityMention[] — Entity mentions and locations
      - `text` string — Entity mention text
      - `location` integer[] — Character offsets indicating the beginning and end of the mention in the analyzed text
      - `confidence` number, double — Confidence in the entity identification from 0 to 1. Higher values indicate higher confidence. In standard entities requests, confidence is returned only for English text. All entities requests that use custom models return the confidence score.
    - `count` integer — How many times the entity was mentioned in the text
    - `emotion` object — Emotion analysis results for the entity, enabled with the `emotion` option
      - `anger` number, double — Anger score from 0 to 1. A higher score means that the text is more likely to convey anger
      - `disgust` number, double — Disgust score from 0 to 1. A higher score means that the text is more likely to convey disgust
      - `fear` number, double — Fear score from 0 to 1. A higher score means that the text is more likely to convey fear
      - `joy` number, double — Joy score from 0 to 1. A higher score means that the text is more likely to convey joy
      - `sadness` number, double — Sadness score from 0 to 1. A higher score means that the text is more likely to convey sadness
    - `sentiment` object — Sentiment analysis results for the entity, enabled with the `sentiment` option
      - `score` number, double — Sentiment score from -1 (negative) to 1 (positive)
    - `disambiguation` object — Disambiguation information for the entity
      - `name` string — Common entity name
      - `dbpedia_resource` string — Link to the corresponding DBpedia resource
      - `subtype` string[] — Entity subtype information
  - `keywords` KeywordsResult[] — The keywords from the analyzed text
    - `count` integer — Number of times the keyword appears in the analyzed text
    - `relevance` number, double — Relevance score from 0 to 1. Higher values indicate greater relevance
    - `text` string — The keyword text
    - `emotion` object — Emotion analysis results for the keyword, enabled with the `emotion` option
      - `anger` number, double — Anger score from 0 to 1. A higher score means that the text is more likely to convey anger
      - `disgust` number, double — Disgust score from 0 to 1. A higher score means that the text is more likely to convey disgust
      - `fear` number, double — Fear score from 0 to 1. A higher score means that the text is more likely to convey fear
      - `joy` number, double — Joy score from 0 to 1. A higher score means that the text is more likely to convey joy
      - `sadness` number, double — Sadness score from 0 to 1. A higher score means that the text is more likely to convey sadness
    - `sentiment` object — Sentiment analysis results for the keyword, enabled with the `sentiment` option
      - `score` number, double — Sentiment score from -1 (negative) to 1 (positive)
  - `categories` CategoriesResult[] — The categories that the service assigned to the analyzed text.
    - `label` string — The path to the category through the multi-level taxonomy hierarchy. For more information about the categories, see [Categories hierarchy](https://cloud.ibm.com/docs/natural-language-understanding?topic=natural-language-understanding-categories#categories-hierarchy).
    - `score` number, double — Confidence score for the category classification. Higher values indicate greater confidence.
    - `explanation` object — Information that helps to explain what contributed to the categories result.
      - `relevant_text` CategoriesRelevantText[] — An array of relevant text from the source that contributed to the categorization. The sorted array begins with the phrase that contributed most significantly to the result, followed by phrases that were less and less impactful.
        - `text` string — Text from the analyzed source that supports the categorization.
  - `classifications` ClassificationsResult[] — The classifications assigned to the analyzed text.
    - `class_name` string — Classification assigned to the text.
    - `confidence` number, double — Confidence score for the classification. Higher values indicate greater confidence.
  - `emotion` object — The anger, disgust, fear, joy, or sadness conveyed by the content
    - `document` object — Emotion results for the document as a whole
      - `emotion` object — Emotion results for the document as a whole
        - `anger` number, double — Anger score from 0 to 1. A higher score means that the text is more likely to convey anger
        - `disgust` number, double — Disgust score from 0 to 1. A higher score means that the text is more likely to convey disgust
        - `fear` number, double — Fear score from 0 to 1. A higher score means that the text is more likely to convey fear
        - `joy` number, double — Joy score from 0 to 1. A higher score means that the text is more likely to convey joy
        - `sadness` number, double — Sadness score from 0 to 1. A higher score means that the text is more likely to convey sadness
    - `targets` TargetedEmotionResults[] — Emotion results for specified targets
      - `text` string — Targeted text
      - `emotion` object — The emotion results for the target
        - `anger` number, double — Anger score from 0 to 1. A higher score means that the text is more likely to convey anger
        - `disgust` number, double — Disgust score from 0 to 1. A higher score means that the text is more likely to convey disgust
        - `fear` number, double — Fear score from 0 to 1. A higher score means that the text is more likely to convey fear
        - `joy` number, double — Joy score from 0 to 1. A higher score means that the text is more likely to convey joy
        - `sadness` number, double — Sadness score from 0 to 1. A higher score means that the text is more likely to convey sadness
  - `metadata` object — Webpage metadata, such as the author and the title of the page
    - `authors` Author[] — The authors of the document
      - `name` string — Name of the author
    - `publication_date` string — The publication date in the format ISO 8601
    - `title` string — The title of the document
    - `image` string — URL of a prominent image on the webpage
    - `feeds` Feed[] — RSS/ATOM feeds found on the webpage
      - `link` string — URL of the RSS or ATOM feed
  - `relations` RelationsResult[] — The relationships between entities in the content
    - `score` number, double — Confidence score for the relation. Higher values indicate greater confidence.
    - `sentence` string — The sentence that contains the relation
    - `type` string — The type of the relation
    - `arguments` RelationArgument[] — Entity mentions that are involved in the relation
      - `entities` RelationEntity[] — An array of extracted entities
        - `text` string — Text that corresponds to the entity
        - `type` string — Entity type
      - `location` integer[] — Character offsets indicating the beginning and end of the mention in the analyzed text
      - `text` string — Text that corresponds to the argument
  - `semantic_roles` SemanticRolesResult[] — Sentences parsed into `subject`, `action`, and `object` form.
    - `sentence` string — Sentence from the source that contains the subject, action, and object
    - `subject` object — The extracted subject from the sentence
      - `text` string — Text that corresponds to the subject role
      - `entities` SemanticRolesEntity[] — An array of extracted entities
        - `type` string — Entity type
        - `text` string — The entity text
      - `keywords` SemanticRolesKeyword[] — An array of extracted keywords
        - `text` string — The keyword text
    - `action` object — The extracted action from the sentence
      - `text` string — Analyzed text that corresponds to the action
      - `normalized` string — normalized version of the action
      - `verb` SemanticRolesVerb
        - `text` string — The keyword text
        - `tense` string — Verb tense
    - `object` object — The extracted object from the sentence
      - `text` string — Object text
      - `keywords` SemanticRolesKeyword[] — An array of extracted keywords
        - `text` string — The keyword text
  - `sentiment` object — The sentiment of the content
    - `document` object — The document level sentiment
      - `label` string — Indicates whether the sentiment is positive, neutral, or negative
      - `score` number, double — Sentiment score from -1 (negative) to 1 (positive)
    - `targets` TargetedSentimentResults[] — The targeted sentiment to analyze
      - `text` string — Targeted text
      - `score` number, double — Sentiment score from -1 (negative) to 1 (positive)
  - `summarization` SummarizationResult — (Experimental) Summary of content
    - `text` string — Summary sentences of input source
  - `syntax` SyntaxResult — Tokens and sentences returned from syntax analysis.
    - `tokens` TokenResult[]
      - `text` string — The token as it appears in the analyzed text.
      - `part_of_speech` 'ADJ' | 'ADP' | 'ADV' | 'AUX' | 'CCONJ' | 'DET' | 'INTJ' | 'NOUN' | 'NUM' | 'PART' | 'PRON' | 'PROPN' | 'PUNCT' | 'SCONJ' | 'SYM' | 'VERB' | 'X' — The part of speech of the token. For more information about the values, see [Universal Dependencies POS tags](https://universaldependencies.org/u/pos/).
      - `location` integer[] — Character offsets indicating the beginning and end of the token in the analyzed text.
      - `lemma` string — The [lemma](https://wikipedia.org/wiki/Lemma_%28morphology%29) of the token.
    - `sentences` SentenceResult[]
      - `text` string — The sentence.
      - `location` integer[] — Character offsets indicating the beginning and end of the sentence in the analyzed text.

## Other responses

- `400` — Invalid request

---

[API](https://skmtc.dev/ibm/apis/natural-language-understanding.md) · [All operations](https://skmtc.dev/ibm/apis/natural-language-understanding/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/ibm/natural-language-understanding/revisions/9a693ab0d5ca/schema)