neticleText Analysis API Documentation

Version History

Version Release Date Released by Description
v2.0 2019. 01. 30. Zoltán Csikós Initial version for new Spring boot foundation
v1.3 2016. 09. 15. Zoltán Csikós synonyms array can be sent via POST
v1.2 2016. 08. 15. Zoltán Csikós Enabled sending multiple synonyms at the same time for the same text
v1.1 2016. 07. 29. Zoltán Csikós input_text can be sent via POST
v1.0 2015. 06. 21. Péter Szekeres Initial internal version

Changelog

v 2.0 - 2019.01.30.

New version of the text analysis API

  • Moved project under Spring Boot framework
  • Only accepting JSON request objects in the body of the message
  • Better character handling
  • Improved error handling
  • Added functionality for exclude and filter handling
v1.3 - 2016. 09. 15.

API accepts URL encoded synonims via POST request (synonyms must be URL encoded if sent via POST).

v1.2 - 2016. 08.15.

Ability to send multiple synonyms for the analyzed text.

Result comes back from the API as an array of result objects.

v1.1 - 2016. 07. 29.

API accepts URL encoded input_text via a POST request (input_text must be url encoded if sent via POST).

Text Analysis

Description

Neticle Text Analysis provides market leading, humanly accurate sentiment and semantic analysis.

Entity oriented sentiment analysis

In a text only the phrases, entities and labels related to the set target entity are analyzed. The target is set by it's synonyms, spelling and mispellings.

Document level sentiment analysis

In a text every phrases, entities and labels are analyzed. In this case no synonyms are given as input parameter.

Attribute recognition

Service and product attributes (for example: screen, bandwidth, etc.) are recognized.

Topic recognition

Key topics (for example: 3G, mobile payment, etc.) are recognized.

Location recognition

Related locations (for example: Hungary, Pécs, etc.) are recognized.

Brand recognition

Related brands (for example: Audi, Mercedes, etc.) are recognized.

Emotion recognition

Related emotions (for example: joy, etc.) are recognized.

Person recogniton

Related persons (for example: Bill Gates, etc.) are recognized.

Organization recognition

Related organizations (for example: UNICEF, etc.) are recognized.

Event recognition

Related events (for example: festivals, conferences, etc.) are recognized.

Business topic recognition

Related business topics (for example: revenue, IPO, etc.) are recognized.

Legal topic recognition

Related legal topics (for example: lawsuit, legislation, etc.) are recognized.

Medical topic recognition

Related medical topics (for example: receipt, sympton, etc.) are recognized.

HR topic recognition

Related HR topics (for example: job, salary, etc.) are recognized.

Base URL

https://textanalysis.neticle.com/2.0/text_analysis

Request object

<>
Element Type Parameter description
language* string The language of the input text. If this parameters is empty, the API will try to identify the language based on the text and process it accordingly. If you know the language, the preferred option is to provide it to the API.

Possible values

  • bg- Bulgarian
  • de- German
  • en- English
  • ge- Georgian
  • hu- Hungarian
  • pl- Polish
  • ro- Romanian
  • ru- Russian
  • ua- Ukranian
(requiredparameter)
token* string Token received from Neticle Labs to authenticate the user.
(requiredparameter)
input* string The text to analyze.
(requiredparameter)
format string Format of the response. Currently only JSON is supported.
replaceaccent boolean If set to true, the API will remove all accents from the characters before processing.
For example it will convert the letters é á ű ó into e a u o.
lowercase boolean If set to true, the API will convert the input text to lowercase before processing.
callid string A field to be used by the client, to help tracking calls from different sources from the client's side. Length is max 255 characters.
keywords array of nested keywords Nested object array containing different keyword objects (see below), to provide keyword oriented sentiment and topic analysis that only analyze the parts related to the given keyword. If not set (or set to empty array) then the API will process a full text analysis on the provided text.

Keyword object

Element Type Description Example
id string Id of the provided keyword for easier identification of segments in the response object. keyword_1
synonyms array Synonyms are case-sensitive spellings, misspellings, synonyms of the target entity of the sentiment analysis. For example to analyze comments about the internet coverage, the following synonyms should be set: internet, Internet, INTERNET, net, Net, NET
If synonyms are set, then only the phrases and labels related to the target represented by synonyms will be recognized (aka. entity oriented sentiment analysis): I like this neighborhood, but the net is terrible.
If no synonyms are set, then the full text will be analyzed (aka. document level sentiment analysis). This version should be use only in special cases, because often gives bad results for precise analysis: I like this neighborhood, but the net is terrible.
internet, Internet, INTERNET, net, Net, NET
excludes array If the input text contains any of provided exclude words, the text won't be analyzed.
For example, when you want to analyze comments about the internet coverage with the previous synonyms you might want to skip every sentence with fish net in it, as they are probably not related to the topic.
fish, Fish, FISH
filters array If you want to narrow down a topic to a specific subtopic without changing the defined keywords, you can use filter words, that will provide a more granular way of filtering, for example you only want to analyze 3g and 4g internet coverage and not wired ones. 3g, 3G, 4g, 4G

Sample response

Response object

Element Type Description
error_code integer 0 if no error occurred, in any other case please see the errors section below.
error_message string Empty if there was no error, otherwise a written explanation of the error.
call_id string A field to be used by the client, to help tracking calls from different sources from the client's side.
input_length integer The number of characters in the received text.
total_processing_time_in_ms integer Number of milliseconds of the total processing time.
results Array of nested related entity objects The results after processing the text. If no keyword has been sent this will contain only one element. If multiple keywords are sent this will contain one text analysis result for every keyword in the same order as the keywords were sent.
The result object
Element Type Description
analyzed boolean True, if the request was analyzed successfully. If no keyword was sent then the text will always be analyzed. If the request was sent with a keyword then the text must contain at least one of the synonyms, must not contain any of the excludes, and if filters are set, must also contain at least one of the filter words. You can see what words has the system recognized in the recognized_synonyms, recognized_excludes and recognized_filters arrays.
keyword string The id from the keyword object in the request for easier identification if multiple keywords were sent.
processing_time_in_ms integer The time needed to process the request in milliseconds with full analysis if no keyword was used or with the used keyword.
opinion_index double A score that represents how positive or negative is the text. 0 means a neutral, a negative value means negative and a positive value means positive opinion.
summarized_positive_opinion_index double The summarized value of all the positive opinion indexes in the text.
summarized_negative_opinion_index double The summarized value of all the negative opinion indexes in the text.
html_formatted_text string The HTML and CSS formatted text.
If a sentence part contains a synonym it is surrounded by contain_keyword class span tag.
Recognized phrases are surrounded by polarity_item class span tags.
Recognized synonyms are surrounded by synonym class span tags.
recognized_synonyms array of strings If no keyword was sent, this list will be empty. If a keyword was provided for the analysis and the keyword had synonyms, this list will contain all the synonyms that were found in the text. If synonyms were provided but none was found, the analysis will be skipped.
recognized_excludes array of strings If no keyword was sent, this list will be empty. If a keyword was provided for the analysis and the keyword had filters, this list will contain all the filters that were found in the text. If filters were provided but none was found, the analysis will be skipped.
recognized_filters array of strings If no keyword was sent, this list will be empty. If a keyword was provided for the analysis and the keyword had filters, this list will contain all the filters that were found in the text. If filters were provided but none was found, the analysis will be skipped.
keyword_stats nested keyword stats object Contains statistics about keyword hits in the text if a keyword was provided.
recognized_negative_phrases Array of nested related entity objects Negative phrases recognized in the text.
(If a keyword was provided, only the negative phrases related to the synonyms are recognized. If no synonyms set then every negative phrase is recognized in the text.)
recognized_positive_phrases Array of nested related entity objects Positive phrases recognized in the text.
(If a keyword was provided, only the positive phrases related to the synonyms are recognized. If no synonyms set then every positive phrase is recognized in the text.)
entities Array of nested related entity objects Recognized labels and entities (topics, attributes, brands, locations, etc.
(If keywords are sent with the request then only the labels, entities and phrases related to the provided keyword are recognized. If no keywords are sent then every label, entity and phrase is recognized in the text.)
The keyword stats object
total_keyword_hit_number integer Number of how many times the provided keyword was mentioned in the input text. Every synonym hit is counted as one. If no synonym is set the result is 0.
total_synonym_hit_numbers Array of nested related entity objects Detailed list of how many times each individual synonym was mentioned in the text.
The total synonym hit number object
synonym_hit_number integer Number of how many times this synonym was mentioned in the input text. Every synonym hit is counted as one.
synonym_hit string A synonym that was at least once mentioned in the text.
The entity object
entity_name string The recognized entity.
entity_type string The recognized entity's type.
entity_opinion_index double A score that represents how positive or negative this phrase is.
mention_number integer The number of how many times this entity was mentioned together with the parent phrase/entity in the text.
mentions Array of strings The various mentions where this entity was used.
related_pos_phrases Array of nested related entity objects Other positive phrases that are related to this entity.
related_neg_phrases Array of nested related entity objects Other negative phrases that are related to this entity.
related_entities Array of nested related entity objects Other entities that are related to this entity.
The recognized positive/negative phrase object
Element Type Description
phrase string The recognized positive or negative phrase in the text.
mention_number integer The number of how many times this entity was mentioned together with the parent phrase/entity in the text.
entity_opinion_index double A score that represents how positive or negative this phrase is.
mentions Array of strings The various mentions where this related entity was used together with the parent phrase/entity.
related_pos_phrases Array of nested related entity objects Other positive phrases that are related to this positive or negative phrase.
related_neg_phrases Array of nested related entity objects Other negative phrases that are related to this positive or negative phrase.
related_entities Array of nested related entity objects Other entities that are related to this positive or negative phrase.
The related phrase object
Element Type Description
phrase string The recognized related phrase in the text.
related_mention_number integer The number of how many times this entity was mentioned together with the parent phrase/entity in the text.
mentions Array of strings The various mentions where this related entity was used together with the parent phrase/entity.
The related entity object
Element Type Description
entity_name string The recognized related entity's type.
entity_type string The recognized related entity's type.
related_mention_number integer The number of how many times this entity was mentioned together with the parent phrase/entity in the text.
mentions Array of strings The various mentions where this related entity was used together with the parent phrase/entity.

Sample response

Error codes

Neticle error code HTML error code Description
1 403 This IP has been blacklisted. Please contact us at dev at neticle dot com for further details.
2 501 This language is not implemented yet. Further details can be found on thehttps://api.neticle.comwebsite. If you would like us to implement this language, please contact us on the sales at neticle dot com email address.
3 400 Missing token parameter. This is a mandatory parameter, please always include it in the request. Further details can be found on thehttps://api.neticle.comwebsite.
4 403 This token is not valid. If you would like to renew it, please refer to thehttps://api.neticle.comwebsite or contact us at dev at neticle dot com for further details.
5 400 The input parameter is missing or empty. Please refer to thehttps://api.neticle.comwebsite for further details.
6 400 The format parameter is incorrect. For supported formats please refer to thehttps://api.neticle.comwebsite for further details.
7 400 The provided version is not supported. Please refer to thehttps://api.neticle.comwebsite for further details.