API Output Term Explanation

Detailed Mode Output

Detailed Mode performs analysis on individual documents. In the Semantria API the user can customize almost every part of the analysis; from constraining the number of results for each category to defining the parts of speech which the server will detect, the user can configure Detailed Mode to suit your needs in document sentiment analysis. In this section, we provide a quick reference for customizable options and parameters for POS tagging, as well as a detailed explanation of Detailed Mode's output.

Line-by-line Term Explanation

Output Definition Configuration limits
Document Analytic Data
id (string) Unique document identifier. Can be up to 36 alphanumeric characters
tag (string) Any text of up to 50 characters used like a marker. Returned, if was defined in incoming object.
config_id (string) Unique configuration identifier. Usually 36 alphanumeric characters
status (string) Status of the document
job_id (string) Identifies the specific job that a document belongs to. This can be used for organizing documents on the client side.
source_text (string) Original source text passed by client for this document
summary (string) A summary of the document text summary_limit
language (string) Determined language of source text
language_score (double) The percentage score of the best match of language among detected languages
sentiment_score (double) A sentiment analysis of the document text
sentiment_polarity (string) Verbal representation of sentiment score. Can be "negative", "positive" or "neutral"
intentions (array[Intentions]) Returns sentiment-bearing phrases of the document.
details (array[Details]) Returns sentences from the original document with POS tags within
auto_categories (array[AutoCategory]) Auto-generated categories applicable for the document auto_categories_limit
phrases (array[Phrase]) Returns sentiment-bearing phrases of the document phrases_limit, possible_phrases_limit
themes (array[Theme]) Returns themes of the document themes_limit
entities (array[Entity]) Returns the named entities and user defined entities from the text named_entities_limit, user_entities_limit
relations (array[Relation]) Returns relations which represent a connection between one or more Entity objects named_relations_limit, user_relations_limit
opinions (array[Opinion]) Returns the list of opinions extracted from the source text named_opinions_limit, user_opinions_limit
topics (array[Topic]) Returns the concept and query defined topics determined for the text concept_topics_limit, query_topics_limit
Details
is_imperative (boolean) Represents whether sentence (group of words) is imperative or not
is_polar (boolean) Represents whether or not sentence content contains sentiment polarity
words (array[Word]) Returns list of words grouped by the parent sentence
Word
title (string) The category title, which is its label in the text
tag (string) POS marker of the word.
type (string) Type of category; can be either "node" (root level) or "leaf" (nested) value
stemmed (string) The stemmed form of the word.
is_negated (boolean) A flag indicating if the token is or is part of a sentiment inverting construction such as a negator.
sentiment_score (float) The sentiment score associated with the word.
AutoCategory auto_categories_limit
title (string) The category title, which is its label in the text
type (string) Type of category; can be either "node" (root level) or "leaf" (nested) value
strength_score (double) Strength of the category matches with the document content
categories (array[SubCategory]) List of sub-categories of the current category if applicable
SubCategory
title (string) The category title, which is its label in the text
type (string) Type of category; can be either "node" (root level) or "leaf" (nested) value
sentiment_score (double) Strength of the category matches with the document content
Phrase phrases_limit, possible_phrases_limit
title (string) The text of the sentiment-bearing phrase
type (string) The sentiment score associated with the word
sentiment_score (double) The sentiment score associated with this phrase
sentiment_polarity (string) Verbal representation of sentiment score. Can be "negative", "positive" or "neutral"
intentions (Array[intentions]) Returns intentions list detected by the engine
is_negated (boolean) Specifies whether the phrase has been negated or not
negating_phrase (string) If the phrase has been negated, this gives the negating phrase
is_intensified (boolean) Specifies whether the phrase has been intensified or not
intensifying_phrase (string) If the phrase has been intensified, this gives the intensifying phrase
Intention
type (string) The classification of the intention detected (buy, quit, etc.)
who (string) The author of the intention (if detected).
what (string) The object of the intention (if detected)
evidence_phrase (string) The phrase which expressed the intention
Theme themes_limit, theme_mentions_limit
title (string) The text of the document theme
normalized (string) Normalized form of the document theme
stemmed (string) Stemmed form of the document theme
evidence (integer) A measure of the content on which the sentiment score for the theme is based
is_about (boolean) An indicator specifying whether theme is the main theme of the document
strength_score (double) A measure of the strength of the theme within the document
sentiment_score (double) The sentiment score for the document theme
sentiment_polarity (string) Verbal representation of sentiment score. Can be "negative", "positive" or "neutral"
mentions (array[Mention]) Returns genuine forms of themes mentioned across the documents theme_mentions_limit
Mention
label (string) The text of the theme mention theme_mentions_limit
is_negated (boolean) Indicates whether the mention has been negated or not
negating_phrase (string) If the mention has been negated, this gives the negating phrase
locations (array[Location]) List of coordinates of the mentions found within the document
Location
offset (integer) The amount of bytes offset in the original text before the start of the mention
length (integer) The length of the mention in bytes
Entity named_entities_limit, user_entities_limit
type (string) Type of the entity: either named entity or user entity
evidence (integer) A measure of how much evidence the sentiment score was based on
confident (boolean) An indicator specifying whether or not the confidence queries matched for this entity
is_about (boolean) Specifies whether the document is about this entity
entity_type (string) Type of the entity (Company, Person, Place, Product, etc.)
title (string) Normalized entity title based on existing entity normalization rules
label (string) Descriptive label for the entity, if applicable
sentiment_score (double) Sentiment related to the entity
sentiment_polarity (string) Verbal representation of sentiment score. Can be "negative", "positive" or "neutral"
mentions (array[Mention]) Returns genuine forms of entities mentioned across the documents named_mentions_limit, user_mentions_limit
themes (array[Theme]) Returns list of themes related to this entity entity_themes_limit
Relation named_relations_limit, user_relations_limit
type (string) Type of relation according to extracted entities named_relations_limit, user_relations_limit
relation_type (string) A label describing the nature of the relationship
confidence_score (float) A measure of confidence in the relationship extraction
extra (string) Extra information that has been extracted about the relationship
entities (array[RelationEntity]) Returns entities which presents parent relationship
Relation Entity
title (string) Normalized entity title based on existing entity normalization rules
entity_type (string) Type of the entity (Company, Person, Place, Product, etc.)
Opinion named_opinions_limit, user_opinions_limit
quotation (string) The text of the expressed opinion
type (string) Type of opinion according to extracted entity named_opinions_limit, user_opinions_limit
speaker (float) An entity title identifying the author of the opinion
topic (string) An entity title identifying the subject of the opinion, if applicable
sentiment_score (double) The sentiment score associated with the opinion
sentiment_polarity (string) Verbal representation of sentiment score. Can be "negative", "positive" or "neutral"
Topic concept_topics_limit, query_topics_limit
title (string) The topic title, which is its label in the text
type (string) Type of the topic; can be either "concept" or "query" concept_topics_limit, query_topics_limit
hitcount (integer) Number of query terms that are hit within the document based on query topic
strength_score (float) Strength of the concept topic matches with the document content
sentiment_score (double) The sentiment score for document content associated with the query topic
sentiment_polarity (string) Verbal representation of sentiment score. Can be "negative", "positive" or "neutral"
topics (array[Topic]) List of sub topics if exists

Our fully functional API console offers more explanations and a chance to play with the Semantria API in a browser.

API Console

Detailed Mode limits

Option Description Default
concept_topics_limit Limits the number of concept topics with which the service responds. 5
query_topics_limit Limits the number of query topics with which the service responds. 5
auto_categories_limit Limits the number of auto categories with which the service responds. 5
named_entities_limit Limits the number of named entities with which the service responds. 5
user_entities_limit Limits the number of named entities with which the service responds. 5
entity_themes_limit Limits the number of entity themes with which the service responds. 0
named_mentions_limit Limits the number of named entity-related mentions. 0
user_mentions_limit Limits the number of user entity-related mentions. 0
themes_limit Limits the number of document themes with which the service responds. 5
theme_mentions_limit Limits the number of document and entity related theme mentions. 0
named_relations_limit Limits the number of named entity relations with which the service responds. 0
user_relations_limit Limits the number of user entity relations with which the service responds. 0
named_opinions_limit Limits the number of named entity opinions with which the service responds. 0
user_opinions_limit Limits the number of concept topics with which the service responds. 0
phrases_limit Limits the number of sentiment-bearing phrases for document. 0
possible_phrases_limit Limits the number of possible phrases that affect sentiment score (Semantria's algorithms sometimes detect possible sentiment-bearing phrases absent from the sentiment-bearing dictionary. Users must add these as user phrases to use them.) 0
pos_types Defines parts of speech with which the server will respond. Empty
summary_limit Limits the number of sentences for the document summary feature.We recommend 3, but it depends on document length. 3
detect_language Switches on language detection feature. True

Detailed mode limits apply to both document mode and source mode of analysis. All limits have integer values of 0 to 20. A score of 0 signifies zero interest in the output and will prevent the result for that parameter from appearing in the dataset.

Detailed Mode output explanation

Semantria provides the user with a wealth of information in its sentiment analysis and data processing; sometimes it can be kind of hard to wade through. Here is a quick reference detailing everything the Semantria API will return to the user in Detailed Analysis Mode.

Each document will have an id and each configuration has a unique config_id. The user can add tags and view the status of the document ("queued," "processed" or "failed"). Semantria API will produce a job_id of the associated job, a summary of the document text, the language of the source text (and the language score, the percentage of the best language match among detected languages), and the sentiment_score and sentiment_polarity. For refreshers on what these terms mean, visit the Technology page.

In detailed analysis of individual sentences, the API will return boolean values for is_imperative and is_polar. The API will return a list of words grouped by the parent sentence. Each word will have a tag, POS type, title, stemmed form of the word, and sentiment_score.

Semantria API will generate auto_categories; each category will have a title, type ("node"/root or "leaf"/nested value), strength_score (how much the category matches with document content), and categories, a list of sub-categories (if any exist).

phrases are a list of sentiment-bearing phrases from the document. Each will have a title, sentiment_score, sentiment_polarity (negative, positive, or neutral), is_negated (whether the phrase has been negated), negating_phrase (if one exists), is_intensified, intensifying_phrase (if one exists), and type (either "possible" or "detected").

The Semantria API returns the themes of the document. Each has the title, main theme (is_about), the normalized form of the theme, the stemmed form of the theme, an evidence score, strength_score within the document, and sentiment_polarity. The API will return mentions of the theme: expandable, which is the text of the theme mention, is_negated, negating_phrase, and locations-- the list of coordinates of the mentions found within the document. offset is the number of bytes offset in the original text before the start of the mention, and length is the length of the mention in bytes.

The API returns entities with similar parameters to themes. Entities have additional parameters of type (either "named" or "user"), confident (whether the confidence queries matched for this entity), and the entity_type (Company, Person, Place, etc.). It will also return a list of themes related to this entity.

Semantria API returns relations, which represent a connection between one or more Entities. These have a type (named or user value), relation_type (expandable), confidence_score, extraentities of the parent relationship.

The API will also return a list of opinions extracted from the source text. Each will have a quotation, type (the type of entity extracted-- named or user value), speaker, topic, sentiment_score and sentiment_polarity.

Finally, Semantria API gives a list of topics, each with a title, type, hitcount, strength_score, sentiment_score, sentiment_score and topics (a list of sub-topics, if they exist).

Discovery Mode Output

Semantria’s Discovery Mode provides you with a bird's eye view of your content after the sentiment has been analyzed. In this mode you can discover the top entities, themes, facets, topics, and overarching sentiment count of your group of documents.

Line-by-line Term Explanation

Output Definition Configuration limits
Detailed Analysis Data
id (string) Unique collection identifier. Can be up to 36 alphanumeric characters
config_id (string) Unique configuration identifier. Can be up to 36 alphanumeric characters
tag (string) Any text of up to 50 characters used like marker
job_id (string) Identifies the job that a document belongs to, can be used for ordering documents on the client side
status (string) Status of the collection
summary (string) Contains the reason if a collection has been marked as FAILED during analysis.
facets (array[Facet]) Returns the facets extracted across all documents in the collection facets_limit
themes (array[Theme]) Returns themes across the documents themes_limit
entities (array[Entity]) Returns the named entities and user defined entities from the text named_entities_limit
topics (array[Topic]) Returns the concept and query defined topics determined for the tex
Facet facets_limit, facet_atts_limit, facet_mentions_limit
label (string) The text of the facet
count (integer) The count of occurrences of the facet in the text
negative_count (integer) The count of negative occurrences of the facet across the documents
positive_count (integer) The count of positive occurrences of the facet across the documents
neutral_count (integer) The count of neutral occurrences of the facet across the documents
attributes (array[Attribute]) Returns the attributes associated with this facet facet_atts_limit
mentions (array[Mention]) Returns genuine forms of facet mentioned across the documents facet_mentions_limit
Attribute facet_atts_limit, attribute_mentions_limit
label (string) The text of the attribute
count (integer) The count of occurrences of the attribute across the documents
mentions (array[Mention]) Returns genuine forms of attribute mentioned across the documents attribute_mentions_limit
Mentionattribute_mentions_limit
label (string) The text of the attribute mention
is_negated (boolean) Indicates whether or not the mention has been negated
negating_phrase (string) If the mention has been negated, this gives the negating phrase
locations (array[Location]) List of coordinates of the mentions found within the collection
Location
index (integer) Document index within collection where the mention appeared
offset (integer) The amount of bytes offset in the original text before the start of the mention
length (integer) The length of the mention in bytes
Theme themes_limit, theme_mentions_limit
sentiment_polarity (string) Verbal representation of sentiment score. Can be "negative", "positive" or "neutral"
themes_count (integer) Count of themes across the documents that got rolled into this one themes_limit
phrases_count (integer) Count of sentiment-bearing phrases was used in calculating theme's sentiment
sentiment_score (double) Sentiment score for theme’s sentences across the documents
title (string) The text of the theme across the documents
mentions (array[Mention]) Returns the concept and query defined topics determined for the text theme_mentions_limit
Entity named_entities_limit
title (string) Normalized form of the entity. It is the normalized entity title
label (string) Descriptive label for the entity, if applicable
type (string) Type of the entity; can be either “named” or “user” (reserved for future usage) named_entities_limit
entity_type (string) Type of the entity (Company, Person, Place, Product, etc.)
count (integer) The count of occurrences of the entity across the documents
negative_count (integer) The count of negative occurrences of the entity across the documents
positive_count (integer) The count of positive occurrences of the entity across the documents
neutral_count (integer) The count of neutral occurrences of the entity across the documents
mentions (array[Mention]) Returns the genuine forms of entity mentioned across the documents named_mentions_limit
Topic concept_topics_limit, query_topics_limit
title (string) The topic title, which is its label in the text
type (string) Type of the topic; can be either "concept" or "query" concept_topics_limit, query_topics_limit
hitcount (integer) The number of documents within the collection that match the topic
sentiment_score (double) The sentiment score for documents content associated with the topic
sentiment_polarity (string) Verbal representation of sentiment score. Can be "negative", "positive" or "neutral"
topics (array[Topic]) List of sub topics if exists

Our fully functional API console offers more explanations and a chance to play with the Semantria API in a browser.

API Console

Discovery mode limits

Option Discription Default
facets_limit Limits the number of facets which will be responded from the server. 15
facet_atts_limit Limits the number of facets which will be responded from the server. 5
facet_mentions_limit Limits the number of mentions of facet responded from the server. 0
attribute_mentions_limit Limits the number of mentions of attribute responded from the server. 0
concept_topics_limit Limits the number of concept topics responded from the service. 5
query_topics_limit Limits the number of query topics responded from the service. 5
named_entities_limit Limits the number of named entities responded from the service. 5
named_mentions_limit Limits the number of mentions of theme responded from the server. 0
themes_limit Limits the number of themes responded from the service. 5
theme_mentions_limit Limits the number of entity mentions responded from the server. 0
user_entities_limit Limits the number of user entities responded from the server. 0
user_mentions_limit Limits the number of user entity mentions responded from the server. 0

Discovery Mode output explanation

In Discovery mode, sentiment average is not supported. Instead, the positive, negative, and neutral counts available for facets are analogous to the positive/negative ratio; these show how many mentions of each type were in the text with respect to a certain facet.

Like in Detailed Mode, Discovery Analysis Output will have an analysis id, config_id, job_id, tag and status. The analysis will also return themes, entities and topics.

Discovery Mode Analysis returns the facets extracted from all documents in the batch of discovery analysis. Each facet has a label (the text of the facet), count (number of occurrences), negative_count (number of negative occurrences), netural_count, positive_count, and mentions.Each mention will have a label, an indicator, and negating_phrase. The API will also return attributes associated with the facet with accompanying labels, counts and mentions.

Users have the option for the Semantria API to return the original source document in addition to the processed results. This is useful for multi-level integrations. The option can be switched on and off on upon request.

This analysis can give you insight into problem areas within your business. With Discovery Mode you can see which of your hotel branches is underperforming or which competing brand is generating the most buzz on Twitter. Additionally, you can see the reasons behind the positive and negative feedback and quickly use that information to improve. You can also use your Discovery data to create charts and tables so that you can understand your data from a quick glance.

When sending a collection of texts (e.g. a set of 1,000 tweets) to Semantria, all content is analyzed simultaneously. All recurring mentions of an entity or theme are counted and available to you. In Discovery Mode our Excel Add-In will only display facets, attributes, and sentiment count due to Excel limitations, but Semantria is doing more work behind the curtain.

For example, when running Discovery Mode on a collection that contains the sentence “My waiter was rude!” Semantria will identify the word “waiter” as a facet and search for it throughout the rest of the texts. The attributes associated with “waiter” found within the collection are then consolidated so you will know how many people share the same feelings towards the waiter.

API Options

Option Description Default
auto_response Defines whether or not the service should respond with processed results on each incoming analytics document or discovery analysis request (more info). False
is_primary Identifies whether the current configuration is primary or not. False
chars_threshold Defines whether or not the service should respond with processed results on each incoming analytics document or discovery mode request. 80
one_sentence Leads the service to clean HTML tags before processing. False
process_html Leads the service to clean HTML tags before processing. False
language Defines target language that will be used for task processing. English
callback Defines a callback URL for automatic data responding (more info). Empty

USA/Canada: 1-877-570-1840