---
title: "Analyze text (GET)"
method: GET
path: "/v1/analyze"
tags: ["Analyze"]
---

# Analyze text (GET)

`GET /v1/analyze`

Analyzes raw text, HTML, or a public webpage.

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).

## Query parameters

- `text` string
- `html` string
- `url` string
- `features` string[], required
- `return_analyzed_text` boolean
- `clean` boolean
- `xpath` string
- `fallback_to_raw` boolean
- `language` string
- `categories.explanation` boolean
- `categories.limit` integer
- `categories.model` string
- `classifications.model` string
- `concepts.limit` integer
- `emotion.document` boolean
- `emotion.targets` string[]
- `entities.limit` integer
- `entities.mentions` boolean
- `entities.model` string
- `entities.emotion` boolean
- `entities.sentiment` boolean
- `keywords.limit` integer
- `keywords.emotion` boolean
- `keywords.sentiment` boolean
- `relations.model` string
- `semantic_roles.limit` integer
- `semantic_roles.entities` boolean
- `semantic_roles.keywords` boolean
- `sentiment.document` boolean
- `sentiment.targets` string[]
- `syntax.tokens` boolean
- `syntax.tokens.lemma` boolean
- `syntax.tokens.part_of_speech` boolean
- `syntax.sentences` boolean
- `limit_text_characters` integer

## 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)