Neticle Wiki

Megmutatjuk mit gondol a Web!

Felhasználói eszközök

Eszközök a webhelyen


semantic_api_v0.1

Különbségek

A kiválasztott változat és az aktuális verzió közötti különbségek a következők.

Összehasonlító nézet linkje

semantic_api_v0.1 [2015/06/21 11:44] (aktuális)
szekerespeter létrehozva
Sor 1: Sor 1:
 +====== 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 ====
 +
 +https://​semanticapi.neticle.hu/​0.1/​text_analysis
 +
 +==== Parameters ====
 +
 +
 +^ http argument ​     ^ parameter description ​      ^
 +| lang|the 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_index|whether 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 ====
 +
 +<​code>​
 +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ó"​]
 +</​code>​
 +
 +==== Sample Java call with Apache HTTPClient ====
 +
 +<​code>​
 +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();​
 +        }
 +
 +    }
 +}
 +</​code>​
 +
 +==== Sample JQuery AJAX call ====
 +
 +<​code>​
 +$.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);
 +     }
 +});
 +</​code>​
 +
 +==== Sample response ====
 +
 +<​code>​
 +{
 +    "​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":​ [
 +                ""​
 +            ]
 +        }
 +  ​
 +</​code>​
 +
 +==== 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 ====
 +
 +https://​semanticapi.neticle.hu/​0.1/​get_gender_from_name
 +
 +==== Parameters ====
 +
 +^ http argument ​     ^ parameter description ​      ^
 +| lang|the 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 ====
 +
 +<​code>​
 +https://​semanticapi.neticle.hu/​0.1/​get_gender_from_name?​lang=hu&​user_key=demokey2&​name=Lajos&​format=json
 +</​code>​
 +
 +==== Sample Java call ====
 +
 +<​code>​
 +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();​
 +        }
 +
 +    }
 +}
 +</​code>​
 +
 +==== Sample JQuery AJAX call ====
 +
 +<​code>​
 +$.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);
 +     }
 +});
 +</​code>​
 +
 +==== Sample response ====
 +
 +<​code>​
 +{
 +    "​user_key":​ "​demokey2",​
 +    "​processing_time_in_ms":​ 400,
 +    "​gender":​ 0
 +}
 +</​code>​
 +==== 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 ====
 +
 +https://​semanticapi.neticle.hu/​0.1/​lang_check
 +
 +==== Parameters ====
 +
 +^ http argument ​     ^ parameter description ​      ^
 +| lang|the 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 ====
 +
 +<​code>​
 +https://​semanticapi.neticle.hu/​0.1/​lang_check?​lang=hu&​user_key=demokey2&​input_text=Lajos egy új autót vett&​format=json
 +</​code>​
 +
 +==== Sample Java call ====
 +
 +<​code>​
 +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();​
 +        }
 +
 +    }
 +}
 +</​code>​
 +
 +==== Sample JQuery AJAX call ====
 +
 +<​code>​
 +$.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);
 +     }
 +});
 +</​code>​
 +
 +==== Sample response ====
 +
 +<​code>​
 +{
 +    "​user_key":​ "​demokey2",​
 +    "​processing_time_in_ms":​ 400,
 +    "​lang":​ "​hu",​
 +    "​lang_check":​ true
 +}
 +</​code>​
 +==== 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_v0.1.txt · Utolsó módosítás: 2015/06/21 11:44 szerkesztette: szekerespeter