Text Analysis API

          Why do the hotel guests avoid that particular hotel chain? What issues do the voters have with the new bill being discussed? Is there an ad hominem attack or bigotry in the post? Tisane Labs API allows extracting actionable intelligence from text in 27 languages, tagging abuse, fine-grained sentiment, and more.

Invoke text analysis

The method analyzes input text content, returning a wealth of metadata in JSON:

  • abuse
  • aspect-based sentiment analysis
  • entities
  • topics
  • list of sentences
  • list of phrases
  • list of lexical chunks
  • grammatical tags (parts of speech++)

Segments of the response irrelevant to your application can be turned off, if required, using the settings object (described below), reducing traffic volume and complexity. If a switch or a setting is not set in the settings parameter, a default setting is used. See more details about the available attributes in the documentation for the settings parameter.

The response sections and attributes are:

  • text (string) - the original text
  • reducedOutput (boolean, optional) - if the input is too long, a special reduced outmode is activated, in which n-best interpretations and parses are no shown
  • abuse (array[object], optional) - a list of abuse instance snippets Each sentiment contains:
    • type (enum) - a type of abuse
      • Values
        • bigotry - bigotry toward an ethnic or a religious group or a minority or a gender
        • ad_hominem - attacking someone online
        • criminal_activity - planning criminal activity
        • sexual_advances - unsolicited sexual advances
        • profanity - bad language
        • generic - unclassified type of abuse
    • severity_level (enum) - how severe the abuse is
      • Values
        • low - the lowest level of abuse
        • medium - abuse of medium severity
        • high - severe abuse
        • extreme - extremely severe abuse
    • offset (number) - where the abuse snippet is located from the beginning of the sentence
    • length (number) - how long is the phrase
    • sentence_index (number) - the index of the sentence
  • sentiment_expressions (array[object], optional) - a list of sentiment expressions
    • polarity (enum) - negative or positive
      • Values
        • negative - negative sentiment
        • positive - positive sentiment
        • mixed - mixed sentiment
    • reasons (array[string]) - the reasons that the sentiment phrase targets
    • targets (array[string]) - the aspects/entities that the sentiment phrase and its sub-phrases refer to
    • offset (number) - the offset of the phrase that contains the sentiment from the beginning of the sentence
    • length (number) - the length of the phrase that contains the sentiment
    • sentence_index (number) - the index of the sentence that contains the sentiment
  • topics (array[string], optional) - a list of dominant topics in descending order (the most pertinent first)
  • entities_summary (array[object], optional) - a list of entities
    • type (enum) - the type of the entity
      • Values
        • generic - unclassified type of entity
        • person - a person
        • place - a location
        • organization - an organization or a business
        • number - a number
    • name (string) - the full name of the entity (the longest mention)
    • index (number) - the index of the entity
    • mentions (array[EntityMention]) - all the detected mentions of the entity
      • offset (number) - an offset from the beginning of the sentence where the entity is mentioned
      • length (number) - a length of the entity mention
      • sentence_index (number) - the index of the sentence that contains the sentiment
      • text (string) - the mention text, shown only if the setting snippets is set to true
  • sentence_list (array[object]) - a list of sentences
    • index (number) - the index of the sentence
    • text (string) - the original text of the sentence
    • modified_text (string, optional) - the modified text, if it was modified
    • elements (array[object]) - the words and the punctuation marks that make up the sentence
      • text (string) - the word itself
      • offset (number) - where the word is located from the beginning of the sentence
      • type (enum) - a type of the constituent
        • Values
          • word - a word or a Constituent
          • punctuation - a punctuation mark
          • numeral - a numeral
      • role (string, optional) - a semantic role of the word (agent / patient)
      • grammar (array[string], optional) - grammar features
      • style (array[string], optional) - style features
      • nbest_senses (array[WordSense]) - other word senses of the Constituent that were shortlisted
    • parses (array[object])
      • index (number) - the parse index
      • phrases (array[object]) - the phrases, arranged hierarchically
        • index (string) - the index of the phrase
        • text (string) - the phrase and its members, separated by a vertical bar. Sub-phrases are enclosed in brackets
        • type (string) - a type of the phrase (e.g. NP; for those without standard codes, sense_id will be used)
        • parent (number) - the index of the parent
        • children (array[object], optional) - sub-phrases

Try it

Request URL

Request headers

(optional)
string
Media type of the body sent to the API.
string
Subscription key which provides access to this API. Found in your Profile.

Request body

A request is made of three elements:

  • language (required) - a standard IETF tag for the language to analyze
  • content (required) - a content to analyze
  • settings (optional) - the settings to apply when analyzing
    • feature_standard (string, optional) - determines the way the features will be output. Values:
      • ud - Universal Dependencies tags (grammar features only)
      • penn - Penn treebank tags (grammar features only)
      • native - Tisane native feature codes (grammar, stylistic, and semantic features)
      • description - description of Tisane native features (grammar, stylistic, and semantic features)
    • topic_standard (string, optional) - determines the standard to use when outputting the topics: Values:
      • iptc_code - IPTC topic taxonomy code
      • iptc_description - IPTC topic taxonomy description
      • iab_code - IAB topic taxonomy code
      • iab_description - IAB topic taxonomy description
      • native - Tisane family IDs. Family information can be looked up using the Language Model API
    • abuse (boolean, optional) - instructs to output the abuse section (default: true)
    • sentiment (boolean, optional) - instructs to output the sentiment_expressions section (default: true)
    • entities (boolean, optional) - instructs to output the entities_summary section (default: true)
    • parses (boolean, optional) - instructs to output the parses section (phrases) (default: false)
    • words (boolean, optional) - instructs to output the elements section (words) (default: false)
    • snippets (boolean, optional) - instructs to output the text snippets in the abuse, sentiment, and entities sections (default: false)
    • deterministic (boolean, optional) - instructs whether to omit the n-best senses (default: false)
    • expected_domains (array[string], optional) - a list of expected domains
    • expected_hypernyms (array[string], optional) - a list of expected hypernyms
    • when (string, optional) - when the utterance was uttered (date + time)
    • format (enum, optional) - the format of the content. One of the following: unspecified / review / proofread / shortpost / longpost / dialogue.
      • Default: unspecified
      • Members
        • unspecified - no special behaviour to enforce
        • review - any kind of review. More aggressive scanning for sentiment phrases.
        • proofread - a piece that was proofread. E.g. an article in a magazine, a book, a speech, etc.
        • shortpost - a short post, e.g. tweet in social media
        • longform - a long post
        • dialogue - a part of a dialogue
    • sentiment_analysis_type (enum, optional) - (RESERVED) the type of the sentiment analysis strategy.
      • Default: products_and_services
      • Members
        • products_and_services - most common sentiment analysis of products and services
        • entity - sentiment analysis with entities as targets
        • creative_content_review - reviews of creative content
        • political_essay - political essays
    • fetch_definitions (boolean, optional) - if true, instructs to include definitions in the output (warning: slows down the application and increases the size of the response).
    • debug (boolean, optional) - if true, the process tracing is set to on.
    • paragraphs (boolean, optional) - if true, outputs paragraph information

{"language":"en", "content":"Babylonians should not be allowed at managerial positions.", "settings":{"parses":false}}

Response 200

Extract topics only:

{"language":"en", "content":"An inertial force is a force that resists a change in velocity of an object.", "settings":{}}

{
	"text": "An inertial force is a force that resists a change in velocity of an object.",
	"topics": [
		"physics"
	]
}

Code samples

@ECHO OFF

curl -v -X POST "https://api.tisane.ai/parse"
-H "Content-Type: application/json"
-H "Ocp-Apim-Subscription-Key: {subscription key}"

--data-ascii "{body}" 
using System;
using System.Net.Http.Headers;
using System.Text;
using System.Net.Http;
using System.Web;

namespace CSHttpClientSample
{
    static class Program
    {
        static void Main()
        {
            MakeRequest();
            Console.WriteLine("Hit ENTER to exit...");
            Console.ReadLine();
        }
        
        static async void MakeRequest()
        {
            var client = new HttpClient();
            var queryString = HttpUtility.ParseQueryString(string.Empty);

            // Request headers
            client.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", "{subscription key}");

            var uri = "https://api.tisane.ai/parse?" + queryString;

            HttpResponseMessage response;

            // Request body
            byte[] byteData = Encoding.UTF8.GetBytes("{body}");

            using (var content = new ByteArrayContent(byteData))
            {
               content.Headers.ContentType = new MediaTypeHeaderValue("< your content type, i.e. application/json >");
               response = await client.PostAsync(uri, content);
            }

        }
    }
}	
// // This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
import java.net.URI;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class JavaSample 
{
    public static void main(String[] args) 
    {
        HttpClient httpclient = HttpClients.createDefault();

        try
        {
            URIBuilder builder = new URIBuilder("https://api.tisane.ai/parse");


            URI uri = builder.build();
            HttpPost request = new HttpPost(uri);
            request.setHeader("Content-Type", "application/json");
            request.setHeader("Ocp-Apim-Subscription-Key", "{subscription key}");


            // Request body
            StringEntity reqEntity = new StringEntity("{body}");
            request.setEntity(reqEntity);

            HttpResponse response = httpclient.execute(request);
            HttpEntity entity = response.getEntity();

            if (entity != null) 
            {
                System.out.println(EntityUtils.toString(entity));
            }
        }
        catch (Exception e)
        {
            System.out.println(e.getMessage());
        }
    }
}

<!DOCTYPE html>
<html>
<head>
    <title>JSSample</title>
    <script src="http://ajax.googleapis.com/ajax/libs/jquery/1.9.0/jquery.min.js"></script>
</head>
<body>

<script type="text/javascript">
    $(function() {
        var params = {
            // Request parameters
        };
      
        $.ajax({
            url: "https://api.tisane.ai/parse?" + $.param(params),
            beforeSend: function(xhrObj){
                // Request headers
                xhrObj.setRequestHeader("Content-Type","application/json");
                xhrObj.setRequestHeader("Ocp-Apim-Subscription-Key","{subscription key}");
            },
            type: "POST",
            // Request body
            data: "{body}",
        })
        .done(function(data) {
            alert("success");
        })
        .fail(function() {
            alert("error");
        });
    });
</script>
</body>
</html>
#import <Foundation/Foundation.h>

int main(int argc, const char * argv[])
{
    NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
    
    NSString* path = @"https://api.tisane.ai/parse";
    NSArray* array = @[
                         // Request parameters
                         @"entities=true",
                      ];
    
    NSString* string = [array componentsJoinedByString:@"&"];
    path = [path stringByAppendingFormat:@"?%@", string];

    NSLog(@"%@", path);

    NSMutableURLRequest* _request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:path]];
    [_request setHTTPMethod:@"POST"];
    // Request headers
    [_request setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];
    [_request setValue:@"{subscription key}" forHTTPHeaderField:@"Ocp-Apim-Subscription-Key"];
    // Request body
    [_request setHTTPBody:[@"{body}" dataUsingEncoding:NSUTF8StringEncoding]];
    
    NSURLResponse *response = nil;
    NSError *error = nil;
    NSData* _connectionData = [NSURLConnection sendSynchronousRequest:_request returningResponse:&response error:&error];

    if (nil != error)
    {
        NSLog(@"Error: %@", error);
    }
    else
    {
        NSError* error = nil;
        NSMutableDictionary* json = nil;
        NSString* dataString = [[NSString alloc] initWithData:_connectionData encoding:NSUTF8StringEncoding];
        NSLog(@"%@", dataString);
        
        if (nil != _connectionData)
        {
            json = [NSJSONSerialization JSONObjectWithData:_connectionData options:NSJSONReadingMutableContainers error:&error];
        }
        
        if (error || !json)
        {
            NSLog(@"Could not parse loaded json with error:%@", error);
        }
        
        NSLog(@"%@", json);
        _connectionData = nil;
    }
    
    [pool drain];

    return 0;
}
<?php
// This sample uses the Apache HTTP client from HTTP Components (http://hc.apache.org/httpcomponents-client-ga/)
require_once 'HTTP/Request2.php';

$request = new Http_Request2('https://api.tisane.ai/parse');
$url = $request->getUrl();

$headers = array(
    // Request headers
    'Content-Type' => 'application/json',
    'Ocp-Apim-Subscription-Key' => '{subscription key}',
);

$request->setHeader($headers);

$parameters = array(
    // Request parameters
);

$url->setQueryVariables($parameters);

$request->setMethod(HTTP_Request2::METHOD_POST);

// Request body
$request->setBody("{body}");

try
{
    $response = $request->send();
    echo $response->getBody();
}
catch (HttpException $ex)
{
    echo $ex;
}

?>
########### Python 2.7 #############
import httplib, urllib, base64

headers = {
    # Request headers
    'Content-Type': 'application/json',
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.urlencode({
})

try:
    conn = httplib.HTTPSConnection('api.tisane.ai')
    conn.request("POST", "/parse?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################

########### Python 3.2 #############
import http.client, urllib.request, urllib.parse, urllib.error, base64

headers = {
    # Request headers
    'Content-Type': 'application/json',
    'Ocp-Apim-Subscription-Key': '{subscription key}',
}

params = urllib.parse.urlencode({
})

try:
    conn = http.client.HTTPSConnection('api.tisane.ai')
    conn.request("POST", "/parse?%s" % params, "{body}", headers)
    response = conn.getresponse()
    data = response.read()
    print(data)
    conn.close()
except Exception as e:
    print("[Errno {0}] {1}".format(e.errno, e.strerror))

####################################
require 'net/http'

uri = URI('https://api.tisane.ai/parse')


request = Net::HTTP::Post.new(uri.request_uri)
# Request headers
request['Content-Type'] = 'application/json'
# Request headers
request['Ocp-Apim-Subscription-Key'] = '{subscription key}'
# Request body
request.body = "{body}"

response = Net::HTTP.start(uri.host, uri.port, :use_ssl => uri.scheme == 'https') do |http|
    http.request(request)
end

puts response.body