Neticle Wiki

Megmutatjuk mit gondol a Web!

Felhasználói eszközök

Eszközök a webhelyen


semantic_api

Semantic API v0.1

Description

An API to use Neticle Technologies' semantic and text analysis functions in a standard way.

Version History

Version Description
v0.1 Initial internal version, created by Peter Szekeres on 2014.04.07.
v0.1.3 Initial finetuned internal version, created by Peter Szekeres on 2014.12.14.
v0.1.5 Finetuned version, created by Peter Szekeres on 2015.01.25.

Text Analysis

Description

Implementing several text analysis functions within one call to reduce IO.

  • Entity oriented sentiment analysis: in a text only the phrases 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 and labels are analyzed. In this case no synonyms are given as input parameter.
  • Attribute labeling: service and product attributes (for example: screen, bandwidth, etc.) are recognized.
  • Topic labeling: key topics (for example: 3G, mobile payment, etc.) are recognized.
  • Location labeling: related locations (for example: Hungary, Pécs, etc.) are recognized.
  • Brand labeling: related brands (for example: Audi, Mercedes, etc.) are recognized.
  • Emotion labeling: related emotions (for example: joy, etc.) are recognized.
  • Person labeling: related persons (for example: Bill Gates, etc.) are recognized.
  • Organization labeling: related organizations (for example: UNICEF, etc.) are recognized.

Base URL

Parameters

http argument parameter description
langthe language of the 'input text'.

Possible values:
bg - Bulgarian
de - German
en - English
hu - Hungarian

(required parameter)
user_key name of the calling module, for example: demokey2

(required parameter)
input_text The array of raw input text or HTML formatted text to analyze.

(required parameter)
synonyms array of synonyms.

Synonyms are case-sensitive spellings, mispellings, synonyms of the target entity of the sentiment analysis. For example to analyze Audi brand the following synonyms should be set: audi, Audi, AUDI

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): These cars are cool, but I don't like that Audi.

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: These cars are cool, but I don't like that Audi.

example value:
- [„audi”, „Audi”, „AUDI”]
- AND logical operator can be set with ; mark: [„Apple;smartphone”]
- phrases can be set also: [„Paramount Channel”]

(optional parameter)
neticle_profile String parameter to set Neticle profile name for specialised lexicons. (This will be used by Neticle system only.)

(optional parameter)
labeling whether to include the recognized labels (topics, attributes, locations, brands, persons, emotions) of the 'input text' within the API response.

Possible values:
1 - enabled
0 - disabled (default)

(optional parameter)
sentiment_analysis whether to include the sentiment analysed HTML/CSS format of the 'input text' within the API response.
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.

Possible values:
1 - enabled
0 - disabled (default)

(optional parameter)
opinion_indexwhether to include the opinion index of the sentiment analysed 'input text' within the API response.

Possible values:
1 - enabled (default)
0 - disabled

(optional parameter)
stem whether to include the stemmed format of the original 'input text' within the API response.

Possible values:
1 - enabled
0 - disabled (default)

(optional parameter)
lang_check whether to check that the original 'input text' is aligned with the lang parameter.

Possible values:
1 - enabled
0 - disabled (default)

(optional parameter)
format desired API output format

Possible values:
json (default)
csv

(optional parameter)

Sample call

https://semanticapi.neticle.hu/0.1/text_analysis?lang=hu&user_key=demokey2&labeling=1&sentiment_analysis=1&opinion_index=1&stem=0&input_text=["tapasztalataim szerint, ez egy rossz autó"]&format=json&synonyms=["autó","Autó"]

Sample Java call with Apache HTTPClient

import java.io.InputStream;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.methods.PostMethod;


public class PostRequest {
    public static void main(String[] args){
        String url = "https://semanticapi.neticle.hu/0.1/text_analysis";

        try {
            HttpClient client = new HttpClient();
            PostMethod method = new PostMethod(url);

            //Add parameters
            method.addParameter("user_key", "demokey2");
            method.addParameter("lang", "hu");
            method.addParameter("format", "json");
            method.addParameter("input_text", [\"texttexttext\", \"texttextetxttext\"]);
            method.addParameter("synonyms", "[\"snyonym1\", \"synonym2\"]");
            method.addParameter("stem", "0");
            method.addParameter("sentiment_analysis", "1");
            method.addParameter("opinion_index", "1");
            method.addParameter("labeling", "0");
            method.addParameter("attribute_labeling", "0");
            method.addParameter("lang_check", "0");

            int statusCode = client.executeMethod(method);

            int statusCode = client.executeMethod(method);

            if (statusCode != -1) {
                System.out.println(method.getResponseBodyAsString());
            }

        } catch (Exception e) {
            e.printStackTrace();
        }

    }
}

Sample JQuery AJAX call

$.ajax({
     url: 'https://semanticapi.neticle.hu/0.1/text_analysis',
     async: true,
     dataType: "json",
     type: 'POST',
     contentType: 'application/x-www-form-urlencoded;charset=UTF-8',
     data: { input_text: JSON.stringify(input_text_array), lang: "hu", ... },
     success: function(data){
         //Process response JSON object
     }
     error: function(e){
         console.log('semantic api call failed: ' + e);
     }
});

Sample response

{
    "keyword_stats": {
        "total_keyword_hit_number": 1,
        "total_synonym_hit_numbers": [
            {
                "Autó": 0
            },
            {
                "autó": 1
            }
        ]
    },
    "processing_time_in_ms": 45,
    "analyzed_text_array": [
        {
            "recognized_negative_phrases": [
                "egy rossz",
                "lassú"
            ],
            "recognized_synonyms": [
                "autó"
            ],
            "recognized_positive_phrases": [
                ""
            ],
            "attribute_labels": [
                "sebesség",
                "teljesítmény"
            ],
            "location_labels": [
                ""
            ],
            "opinion_index": -4,
            "topic_labels": [
                ""
            ],
            "brand_labels": [
                ""
            ],
            "emotion_labels": [
                ""
            ],
            "analyzed_text": "tapasztalataim szerint, <span class=\"contain_keyword\">ez <span class=\"phrase_neg_lvl2 polarity_item\" title=\"-2\">egy rossz</span> teljesítményű és <span class=\"phrase_neg_lvl2 polarity_item\" title=\"-2\">lassú</span> <span class=\"synonym\">autó</span></span>",
            "organization_labels": [
                ""
            ],
            "person_labels": [
                ""
            ]
        }
  

Response explanation

Element Description
keyword_stats Number of keyword and synonym mentions.
total_keyword_hit_number Number of the target entity was mentioned in the input texts. Every synonym hit is counted. If no synonym is set the result is 0.
total_synonym_hit_numbers Number of synonym mentions by each synonym.
processing_time_in_ms The time needed to process the request.
analyzed_text_array The array of the sent texts. If multiple texts should be analyzed by the same settings, they can be sent in blocks to the server, and the results are shown for each text in this array.
recognized_negative_phrases Negative phrases recognized in the text.

(If synonyms are set, only the negative phrases related to the synonyms are recognized. If no synonyms set then every negative phrase is recognized in the text.)
recognized_synonyms Synonyms recognized in the text.
recognized_positive_phrases Positive phrases recognized in the text.

(If synonyms are set, only the positive phrases related to the synonyms are recognized. If no synonyms set then every positive phrase is recognized in the text.)
attribute_labels Recognized service and product attributes.

(If synonyms are set, only the labels related to the synonyms are recognized. If no synonyms set then every label is recognized in the text.)
location_labels Recognized locations.

(If synonyms are set, only the labels related to the synonyms are recognized. If no synonyms set then every label is recognized in the text.)
opinion_index A score that represents how positive or negative is the text. 0 means neutral opinion, while negative value means negative opinion and positive value means positive opinion.
topic_labels Recognized topics.

(If synonyms are set, only the labels related to the synonyms are recognized. If no synonyms set then every label is recognized in the text.)
brand_labels Recognized brands.

(If synonyms are set, only the labels related to the synonyms are recognized. If no synonyms set then every label is recognized in the text.)
emotion_labels Recognized emotions.

(If synonyms are set, only the labels related to the synonyms are recognized. If no synonyms set then every label is recognized in the text.)
analyzed_text 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.
organization_labels Recognized organizations.

(If synonyms are set, only the labels related to the synonyms are recognized. If no synonyms set then every label is recognized in the text.)
person_labels Recognized persons.

(If synonyms are set, only the labels related to the synonyms are recognized. If no synonyms set then every label is recognized in the text.)

Error codes

Error code Error message
1 No lang parameter set
2 Incorrect lang value
3 No user_key parameter set
4 Incorrect user_key value
5 Incorrect input_text value
6 Incorrect synonyms value
7 Incorrect labeling value
8 Incorrect sentiment_analysis value
9 Incorrect opinion_index value
10 Incorrect stem value
11 Incorrect lang_check value
12 No format parameter set
13 Incorrect format value
unknown Unknown exception

Gender By Name

Description

It predicts the gender based on a name String value.

Possible values:
-1 : female
1 : male
0 : unknown

Base URL

Parameters

http argument parameter description
langthe language of the 'input text'.

Possible values:
bg - Bulgarian
de - German
en - English
hu - Hungarian

(required parameter)
user_key name of the calling module, for example: demokey2

(required parameter)
name name to analyze

(required parameter)
format desired API output format

Possible values:
json (default)

(optional parameter)

Sample call

https://semanticapi.neticle.hu/0.1/get_gender_from_name?lang=hu&user_key=demokey2&name=Lajos&format=json

Sample Java call

import java.io.InputStream;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.methods.PostMethod;


public class PostRequest {
    public static void main(String[] args){
        String url = "https://semanticapi.neticle.hu/0.1/get_gender_from_name";
        InputStream in = null;

        try {
            HttpClient client = new HttpClient();
            PostMethod method = new PostMethod(url);

            //Add parameters
            method.addParameter("user_key", "demokey2");
            method.addParameter("lang", "hu");
            method.addParameter("name", "Lajos");
            method.addParameter("format", "json");

            int statusCode = client.executeMethod(method);

            if (statusCode != -1) {
                in = method.getResponseBodyAsStream();
            }

            System.out.println(in);

        } catch (Exception e) {
            e.printStackTrace();
        }

    }
}

Sample JQuery AJAX call

$.ajax({
     url: 'https://semanticapi.neticle.hu/0.1/get_gender_from_name',
     async: true,
     dataType: "json",
     type: 'POST',
     contentType: 'application/x-www-form-urlencoded;charset=UTF-8',
     data: { lang: "hu", name: "Lajos", user_key="demokey2", format="json" },
     success: function(data){
         //Process response JSON object
     }
     error: function(e){
         console.log('semantic api call failed: ' + e);
     }
});

Sample response

{
    "user_key": "demokey2",
    "processing_time_in_ms": 400,
    "gender": 0
}

Error codes

Error code Error message
1 No lang parameter set
2 Incorrect lang value
3 No user_key parameter set
4 Incorrect user_key value
5 No name parameter set
6 No format parameter set
7 Incorrect format value
unknown Unknown exception

Language Check

Description

It checks the language of the input text.

Possible values:
true
false

Base URL

Parameters

http argument parameter description
langthe language of the 'input text' to check.

Possible values:
bg - Bulgarian
de - German
en - English
hu - Hungarian

(required parameter)
user_key name of the calling module, for example: demokey2

(required parameter)
input_text text to analyze

(required parameter)
format desired API output format

Possible values:
json (default)

(optional parameter)

Sample call

https://semanticapi.neticle.hu/0.1/lang_check?lang=hu&user_key=demokey2&input_text=Lajos egy új autót vett&format=json

Sample Java call

import java.io.InputStream;
import org.apache.commons.httpclient.HttpClient;
import org.apache.commons.httpclient.methods.PostMethod;


public class PostRequest {
    public static void main(String[] args){
        String url = "https://semanticapi.neticle.hu/0.1/lang_check";
        InputStream in = null;

        try {
            HttpClient client = new HttpClient();
            PostMethod method = new PostMethod(url);

            //Add parameters
            method.addParameter("user_key", "demokey2");
            method.addParameter("lang", "hu");
            method.addParameter("input_text", "Lajos egy új autót vett");
            method.addParameter("format", "json");

            int statusCode = client.executeMethod(method);

            if (statusCode != -1) {
                in = method.getResponseBodyAsStream();
            }

            System.out.println(in);

        } catch (Exception e) {
            e.printStackTrace();
        }

    }
}

Sample JQuery AJAX call

$.ajax({
     url: 'https://semanticapi.neticle.hu/0.1/lang_check',
     async: true,
     dataType: "json",
     type: 'POST',
     contentType: 'application/x-www-form-urlencoded;charset=UTF-8',
     data: { lang: "hu", input_text: "Lajos egy új autót vett", user_key="demokey2", format="json" },
     success: function(data){
         //Process response JSON object
     }
     error: function(e){
         console.log('semantic api call failed: ' + e);
     }
});

Sample response

{
    "user_key": "demokey2",
    "processing_time_in_ms": 400,
    "lang": "hu",
    "lang_check": true
}

Error codes

Error code Error message
1 No lang parameter set
2 Incorrect lang value
3 No user_key parameter set
4 Incorrect user_key value
5 No name parameter set
6 No format parameter set
7 Incorrect format value
unknown Unknown exception
semantic_api.txt · Utolsó módosítás: 2015/01/25 23:16 szerkesztette: szekerespeter