watson_developer_cloud.natural_language_understanding_v1 module

Analyze various features of text content at scale. Provide text, raw HTML, or a public URL, and IBM Watson Natural Language Understanding will give you results for the features you request. The service cleans HTML content before analysis by default, so the results can ignore most advertisements and other unwanted content. You can create <a target=”_blank” href=”https://www.ibm.com/watson/developercloud/doc/natural-language-understanding/customizing.html”>custom models</a> with Watson Knowledge Studio that can be used to detect custom entities and relations in Natural Language Understanding.

class NaturalLanguageUnderstandingV1(version, url='https://gateway.watsonplatform.net/natural-language-understanding/api', username=None, password=None, iam_api_key=None, iam_access_token=None, iam_url=None)

Bases: watson_developer_cloud.watson_service.WatsonService

The Natural Language Understanding V1 service.

default_url = 'https://gateway.watsonplatform.net/natural-language-understanding/api'

analyze(features, text=None, html=None, url=None, clean=None, xpath=None, fallback_to_raw=None, return_analyzed_text=None, language=None, limit_text_characters=None, **kwargs)

Analyze text, HTML, or a public webpage.

Analyzes text, HTML, or a public webpage with one or more text analysis features. ### Concepts Identify general concepts that are referenced or alluded to in your content. Concepts that are detected typically have an associated link to a DBpedia resource. ### Emotion Detect anger, disgust, fear, joy, or sadness that is conveyed by your content. Emotion information can be returned for detected entities, keywords, or user-specified target phrases found in the text. ### Entities Detect important people, places, geopolitical entities and other types of entities in your content. Entity detection recognizes consecutive coreferences of each entity. For example, analysis of the following text would count “Barack Obama” and “He” as the same entity: “Barack Obama was the 44th President of the United States. He took office in January 2009.” ### Keywords Determine the most important keywords in your content. Keyword phrases are organized by relevance in the results. ### Metadata Get author information, publication date, and the title of your text/HTML content. ### Relations Recognize when two entities are related, and identify the type of relation. For example, you can identify an “awardedTo” relation between an award and its recipient. ### Semantic Roles Parse sentences into subject-action-object form, and identify entities and keywords that are subjects or objects of an action. ### Sentiment Determine whether your content conveys postive or negative sentiment. Sentiment information can be returned for detected entities, keywords, or user-specified target phrases found in the text. ### Categories Categorize your content into a hierarchical 5-level taxonomy. For example, “Leonardo DiCaprio won an Oscar” returns “/art and entertainment/movies and tv/movies” as the most confident classification.

Parameters:

• features (Features) – Specific features to analyze the document for.
• text (str) – The plain text to analyze.
• html (str) – The HTML file to analyze.
• url (str) – The web page to analyze.
• clean (bool) – Remove website elements, such as links, ads, etc.
• xpath (str) – XPath query for targeting nodes in HTML.
• fallback_to_raw (bool) – Whether to use raw HTML content if text cleaning

fails. :param bool return_analyzed_text: Whether or not to return the analyzed text. :param str language: ISO 639-1 code indicating the language to use in the analysis. :param int limit_text_characters: Sets the maximum number of characters that are processed by the service. :param dict headers: A dict containing the request headers :return: A dict containing the AnalysisResults response. :rtype: dict

delete_model(model_id, **kwargs)

Delete model.

Deletes a custom model.

Parameters:

• model_id (str) – model_id of the model to delete.
• headers (dict) – A dict containing the request headers

Returns:

A dict containing the InlineResponse200 response.

Return type:

dict

list_models(**kwargs)

List models.

Lists available models for Relations and Entities features, including Watson Knowledge Studio custom models that you have created and linked to your Natural Language Understanding service.

Parameters:headers (dict) – A dict containing the request headers Returns:A dict containing the ListModelsResults response. Return type:dict

class AnalysisResults(language=None, analyzed_text=None, retrieved_url=None, usage=None, concepts=None, entities=None, keywords=None, categories=None, emotion=None, metadata=None, relations=None, semantic_roles=None, sentiment=None)

Bases: object

Results of the analysis, organized by feature.

Attr str language:  (optional) Language used to analyze the text. Attr str analyzed_text:  (optional) Text that was used in the analysis. Attr str retrieved_url:  (optional) URL that was used to retrieve HTML content. Attr Usage usage:  (optional) API usage information for the request. Attr list[ConceptsResult] concepts:  (optional) The general concepts referenced or

alluded to in the specified content. :attr list[EntitiesResult] entities: (optional) The important entities in the specified content. :attr list[KeywordsResult] keywords: (optional) The important keywords in content organized by relevance. :attr list[CategoriesResult] categories: (optional) The hierarchical 5-level taxonomy the content is categorized into. :attr EmotionResult emotion: (optional) The anger, disgust, fear, joy, or sadness conveyed by the content. :attr MetadataResult metadata: (optional) The metadata holds author information, publication date and the title of the text/HTML content. :attr list[RelationsResult] relations: (optional) The relationships between entities in the content. :attr list[SemanticRolesResult] semantic_roles: (optional) The subjects of actions and the objects the actions act upon. :attr SentimentResult sentiment: (optional) The sentiment of the content.

class Author(name=None)

Bases: object

The author of the analyzed content.

Attr str name:(optional) Name of the author.

class CategoriesOptions(**kwargs)

Bases: object

The hierarchical 5-level taxonomy the content is categorized into.

class CategoriesResult(label=None, score=None)

Bases: object

The hierarchical 5-level taxonomy the content is categorized into.

Attr str label:(optional) The path to the category through the taxonomy hierarchy. Attr float score:  (optional) Confidence score for the category classification. Higher

values indicate greater confidence.

class ConceptsOptions(limit=None)

Bases: object

Whether or not to analyze content for general concepts that are referenced or alluded to.

Attr int limit:(optional) Maximum number of concepts to return.

class ConceptsResult(text=None, relevance=None, dbpedia_resource=None)

Bases: object

The general concepts referenced or alluded to in the specified content.

Attr str text:(optional) Name of the concept. Attr float relevance:  (optional) Relevance score between 0 and 1. Higher scores

indicate greater relevance. :attr str dbpedia_resource: (optional) Link to the corresponding DBpedia resource.

class DisambiguationResult(name=None, dbpedia_resource=None, subtype=None)

Bases: object

Disambiguation information for the entity.

Attr str name:(optional) Common entity name. Attr str dbpedia_resource:  (optional) Link to the corresponding DBpedia resource. Attr list[str] subtype:  (optional) Entity subtype information.

class DocumentEmotionResults(emotion=None)

Bases: object

An object containing the emotion results of a document.

Attr EmotionScores emotion:  (optional) An object containing the emotion results for

the document.

class DocumentSentimentResults(label=None, score=None)

Bases: object

DocumentSentimentResults.

Attr str label:(optional) Indicates whether the sentiment is positive, neutral, or

negative. :attr float score: (optional) Sentiment score from -1 (negative) to 1 (positive).

class EmotionOptions(document=None, targets=None)

Bases: object

Whether or not to return emotion analysis of the content.

Attr bool document:  (optional) Set this to false to hide document-level emotion

results. :attr list[str] targets: (optional) Emotion results will be returned for each target string that is found in the document.

class EmotionResult(document=None, targets=None)

Bases: object

The detected anger, disgust, fear, joy, or sadness that is conveyed by the content. Emotion information can be returned for detected entities, keywords, or user-specified target phrases found in the text.

Attr DocumentEmotionResults document:  (optional) The returned emotion results across

the document. :attr list[TargetedEmotionResults] targets: (optional) The returned emotion results per specified target.

class EmotionScores(anger=None, disgust=None, fear=None, joy=None, sadness=None)

Bases: object

EmotionScores.

Attr float anger:  (optional) Anger score from 0 to 1. A higher score means that the

text is more likely to convey anger. :attr float disgust: (optional) Disgust score from 0 to 1. A higher score means that the text is more likely to convey disgust. :attr float fear: (optional) Fear score from 0 to 1. A higher score means that the text is more likely to convey fear. :attr float joy: (optional) Joy score from 0 to 1. A higher score means that the text is more likely to convey joy. :attr float sadness: (optional) Sadness score from 0 to 1. A higher score means that the text is more likely to convey sadness.

class EntitiesOptions(limit=None, mentions=None, model=None, sentiment=None, emotion=None)

Bases: object

Whether or not to return important people, places, geopolitical, and other entities detected in the analyzed content.

Attr int limit:(optional) Maximum number of entities to return. Attr bool mentions:  (optional) Set this to true to return locations of entity

mentions. :attr str model: (optional) Enter a custom model ID to override the standard entity detection model. :attr bool sentiment: (optional) Set this to true to return sentiment information for detected entities. :attr bool emotion: (optional) Set this to true to analyze emotion for detected keywords.

class EntitiesResult(type=None, text=None, relevance=None, mentions=None, count=None, emotion=None, sentiment=None, disambiguation=None)

Bases: object

The important people, places, geopolitical entities and other types of entities in your content.

Attr str type:(optional) Entity type. Attr str text:(optional) The name of the entity. Attr float relevance:  (optional) Relevance score from 0 to 1. Higher values indicate

greater relevance. :attr list[EntityMention] mentions: (optional) Entity mentions and locations. :attr int count: (optional) How many times the entity was mentioned in the text. :attr EmotionScores emotion: (optional) Emotion analysis results for the entity, enabled with the “emotion” option. :attr FeatureSentimentResults sentiment: (optional) Sentiment analysis results for the entity, enabled with the “sentiment” option. :attr DisambiguationResult disambiguation: (optional) Disambiguation information for the entity.

class EntityMention(text=None, location=None)

Bases: object

EntityMention.

Attr str text:(optional) Entity mention text. Attr list[int] location:  (optional) Character offsets indicating the beginning and

end of the mention in the analyzed text.

class FeatureSentimentResults(score=None)

Bases: object

FeatureSentimentResults.

Attr float score:  (optional) Sentiment score from -1 (negative) to 1 (positive).

class Features(concepts=None, emotion=None, entities=None, keywords=None, metadata=None, relations=None, semantic_roles=None, sentiment=None, categories=None)

Bases: object

Analysis features and options.

Attr ConceptsOptions concepts:  (optional) Whether or not to return the concepts that

are mentioned in the analyzed text. :attr EmotionOptions emotion: (optional) Whether or not to extract the emotions implied in the analyzed text. :attr EntitiesOptions entities: (optional) Whether or not to extract detected entity objects from the analyzed text. :attr KeywordsOptions keywords: (optional) Whether or not to return the keywords in the analyzed text. :attr MetadataOptions metadata: (optional) Whether or not the author, publication date, and title of the analyzed text should be returned. This parameter is only available for URL and HTML input. :attr RelationsOptions relations: (optional) Whether or not to return the relationships between detected entities in the analyzed text. :attr SemanticRolesOptions semantic_roles: (optional) Whether or not to return the subject-action-object relations from the analyzed text. :attr SentimentOptions sentiment: (optional) Whether or not to return the overall sentiment of the analyzed text. :attr CategoriesOptions categories: (optional) Whether or not to return the high level category the content is categorized as (i.e. news, art).

class Feed(link=None)

Bases: object

RSS or ATOM feed found on the webpage.

Attr str link:(optional) URL of the RSS or ATOM feed.

class InlineResponse200(deleted=None)

Bases: object

InlineResponse200.

Attr str deleted:  (optional) model_id of the deleted model.

class KeywordsOptions(limit=None, sentiment=None, emotion=None)

Bases: object

An option indicating whether or not important keywords from the analyzed content should be returned.

Attr int limit:(optional) Maximum number of keywords to return. Attr bool sentiment:  (optional) Set this to true to return sentiment information for

detected keywords. :attr bool emotion: (optional) Set this to true to analyze emotion for detected keywords.

class KeywordsResult(relevance=None, text=None, emotion=None, sentiment=None)

Bases: object

The most important keywords in the content, organized by relevance.

Attr float relevance:  (optional) Relevance score from 0 to 1. Higher values indicate

greater relevance. :attr str text: (optional) The keyword text. :attr EmotionScores emotion: (optional) Emotion analysis results for the keyword, enabled with the “emotion” option. :attr FeatureSentimentResults sentiment: (optional) Sentiment analysis results for the keyword, enabled with the “sentiment” option.

class ListModelsResults(models=None)

Bases: object

Models available for Relations and Entities features.

Attr list[Model] models:  (optional)

class MetadataOptions(**kwargs)

Bases: object

The Authors, Publication Date, and Title of the document. Supports URL and HTML input types.

class MetadataResult(authors=None, publication_date=None, title=None, image=None, feeds=None)

Bases: object

The Authors, Publication Date, and Title of the document. Supports URL and HTML input types.

Attr list[Author] authors:  (optional) The authors of the document. Attr str publication_date:  (optional) The publication date in the format ISO 8601. Attr str title:(optional) The title of the document. Attr str image:(optional) URL of a prominent image on the webpage. Attr list[Feed] feeds:  (optional) RSS/ATOM feeds found on the webpage.

class Model(status=None, model_id=None, language=None, description=None)

Bases: object

Model.

Attr str status:  (optional) Shows as available if the model is ready for use. Attr str model_id:  (optional) Unique model ID. Attr str language:  (optional) ISO 639-1 code indicating the language of the model. Attr str description:  (optional) Model description.

class RelationArgument(entities=None, location=None, text=None)

Bases: object

RelationArgument.

Attr list[RelationEntity] entities:  (optional) Attr list[int] location:  (optional) Character offsets indicating the beginning and

end of the mention in the analyzed text. :attr str text: (optional) Text that corresponds to the argument.

class RelationEntity(text=None, type=None)

Bases: object

An entity that corresponds with an argument in a relation.

Attr str text:(optional) Text that corresponds to the entity. Attr str type:(optional) Entity type.

class RelationsOptions(model=None)

Bases: object

An option specifying if the relationships found between entities in the analyzed content should be returned.

Attr str model:(optional) Enter a custom model ID to override the default model.

class RelationsResult(score=None, sentence=None, type=None, arguments=None)

Bases: object

The relations between entities found in the content.

Attr float score:  (optional) Confidence score for the relation. Higher values

indicate greater confidence. :attr str sentence: (optional) The sentence that contains the relation. :attr str type: (optional) The type of the relation. :attr list[RelationArgument] arguments: (optional) The extracted relation objects from the text.

class SemanticRolesAction(text=None, normalized=None, verb=None)

Bases: object

SemanticRolesAction.

Attr str text:(optional) Analyzed text that corresponds to the action. Attr str normalized:  (optional) normalized version of the action. Attr SemanticRolesVerb verb:  (optional)

class SemanticRolesEntity(type=None, text=None)

Bases: object

SemanticRolesEntity.

Attr str type:(optional) Entity type. Attr str text:(optional) The entity text.

class SemanticRolesKeyword(text=None)

Bases: object

SemanticRolesKeyword.

Attr str text:(optional) The keyword text.

class SemanticRolesObject(text=None, keywords=None)

Bases: object

SemanticRolesObject.

Attr str text:(optional) Object text. Attr list[SemanticRolesKeyword] keywords:  (optional)

class SemanticRolesOptions(limit=None, keywords=None, entities=None)

Bases: object

An option specifying whether or not to identify the subjects, actions, and verbs in the analyzed content.

Attr int limit:(optional) Maximum number of semantic_roles results to return. Attr bool keywords:  (optional) Set this to true to return keyword information for

subjects and objects. :attr bool entities: (optional) Set this to true to return entity information for subjects and objects.

class SemanticRolesResult(sentence=None, subject=None, action=None, object=None)

Bases: object

The object containing the actions and the objects the actions act upon.

Attr str sentence:  (optional) Sentence from the source that contains the subject,

action, and object. :attr SemanticRolesSubject subject: (optional) The extracted subject from the sentence. :attr SemanticRolesAction action: (optional) The extracted action from the sentence. :attr SemanticRolesObject object: (optional) The extracted object from the sentence.

class SemanticRolesSubject(text=None, entities=None, keywords=None)

Bases: object

SemanticRolesSubject.

Attr str text:(optional) Text that corresponds to the subject role. Attr list[SemanticRolesEntity] entities:  (optional) Attr list[SemanticRolesKeyword] keywords:  (optional)

class SemanticRolesVerb(text=None, tense=None)

Bases: object

SemanticRolesVerb.

Attr str text:(optional) The keyword text. Attr str tense:(optional) Verb tense.

class SentimentOptions(document=None, targets=None)

Bases: object

An option specifying if sentiment of detected entities, keywords, or phrases should be returned.

Attr bool document:  (optional) Set this to false to hide document-level sentiment

results. :attr list[str] targets: (optional) Sentiment results will be returned for each target string that is found in the document.

class SentimentResult(document=None, targets=None)

Bases: object

The sentiment of the content.

Attr DocumentSentimentResults document:  (optional) The document level sentiment. Attr list[TargetedSentimentResults] targets:  (optional) The targeted sentiment to

analyze.

class TargetedEmotionResults(text=None, emotion=None)

Bases: object

An object containing the emotion results for the target.

Attr str text:(optional) Targeted text. Attr EmotionScores emotion:  (optional) An object containing the emotion results for

the target.

class TargetedSentimentResults(text=None, score=None)

Bases: object

TargetedSentimentResults.

Attr str text:(optional) Targeted text. Attr float score:  (optional) Sentiment score from -1 (negative) to 1 (positive).

class Usage(features=None, text_characters=None, text_units=None)

Bases: object

Usage information.

Attr int features:  (optional) Number of features used in the API call. Attr int text_characters:  (optional) Number of text characters processed. Attr int text_units:  (optional) Number of 10,000-character units processed.