NAV
shell python java

Introduction

Welcome to the Symanto API! You can use our API to access the API endpoints, which can get insight on text using our AI technology.

We have language binding in Shell. You can view code examples in the dark area to the right.

Authentication

Make sure to replace opensesame with your API key.

Symanto API uses API keys to allow access to the API. You can register a new Symanto API key at our developer portal.

Symanto API expects for the API key to be included in all API requests to the server in a header that looks like the following:

x-api-key: opensesame

Text Analysis

Personality Traits

curl -X POST "https://api.symanto.net/personality" 
-H "accept: application/json" 
-H "Content-Type: application/json" 
-H "x-api-key: opensesame" 
-d "[{\"id\":1,\"text\":\"I love the service\",\"language\":\"en\"}]"
import requests

url = "https://api.symanto.net/personality"

payload = "[{ \"id\": \"1\", \"text\": \"I love the service\", \"language\": \"en\" }]"
headers = {
    "x-api-key": "opensesame",
    "Content-Type": "application/json"
}
response = requests.request("POST", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create("[ { \"id\": \"1\", \"text\": \"I love the service\", \"language\": \"en\" }]", mediaType);
Request request = new Request.Builder()
    .url("https://api.symanto.net/personality")
    .method("POST", body)
    .addHeader("x-api-key","opensesame")
    .build();
Response response = client.newCall(request).execute();

The above command returns JSON structured like this:

[
    {
        "id": "1",
        "predictions": [
            {
                "prediction": "emotional",
                "probability": 0.9997281432151794
            }
        ]
    }
]

Predict the personality traits to understand how the author of the written text makes decisions, whether they are Emotional (relationship-oriented, focusing on social values and empathy) or Rational (objective and pragmatic, focusing on facts and logical deduction).

Supported Languages: [ ar, de, en, es, fr, it, nl, pt, ru, tr, zh ]

Returned labels: [emotional, rational]

HTTP Request

POST https://api.symanto.net/personality

Query Parameters

Parameter Type Default Description
all bool false returns all predictions, not only the most probable one

REQUEST BODY SCHEMA : application/json

An array of max 32 items is allowed.

Parameter Type Optionality Description
id string Optional id of the post
text string Required the text to analyse
language string Required language_code of the text

Communication Style

curl -X POST "https://api.symanto.net/communication" 
-H "accept: application/json" 
-H "Content-Type: application/json" 
-H "x-api-key: opensesame" 
-d "[{\"id\":1,\"text\":\"I love the service\",\"language\":\"en\"}]"
import requests

url = "https://api.symanto.net/communication"

payload = "[{ \"id\": \"1\", \"text\": \"I love the service\", \"language\": \"en\" }]"
headers = {
    "x-api-key": "opensesame",
    "Content-Type": "application/json"
}
response = requests.request("POST", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create("[ { \"id\": \"1\", \"text\": \"I love the service\", \"language\": \"en\" }]", mediaType);
Request request = new Request.Builder()
    .url("https://api.symanto.net/communication")
    .method("POST", body)
    .addHeader("x-api-key","opensesame")
    .build();
Response response = client.newCall(request).execute();

The above command returns JSON structured like this:

[
  {
    "id": "1",
    "predictions": [
      {
        "prediction": "self-revealing",
        "probability": 0.9997937083244324
      }
    ]
  }
]

Detect the communication purpose and style of the text. The style includes: - self-revealing (sharing one's one experience and opinion) - fact-oriented (focusing on factual information, objective observations or statements) - information-seeking (posing questions) - action-seeking (aiming to trigger someone's action by giving recommendation, requests or advice).

Supported Languages: [ ar, de, en, es, fr, it, nl, pt, ru, tr, zh ]

Returned labels: [action-seeking, fact-oriented, information-seeking, self-revealing]

HTTP Request

POST https://api.symanto.net/communication

Query Parameters

Parameter Type Default Description
all bool false returns all predictions, not only the most probable one

REQUEST BODY SCHEMA : application/json

An array of max 32 items is allowed.

Parameter Type Optionality Description
id string Optional id of the post
text string Required the text to analyse
language string Required language_code of the text

Emotion Analysis

curl -X POST "https://api.symanto.net/emotion" 
-H "accept: application/json" 
-H "Content-Type: application/json" 
-H "x-api-key: opensesame" 
-d "[{\"id\":1,\"text\":\"I love the service\",\"language\":\"en\"}]"
import requests

url = "https://api.symanto.net/emotion"

payload = "[{ \"id\": \"1\", \"text\": \"I love the service\", \"language\": \"en\" }]"
headers = {
    "x-api-key": "opensesame",
    "Content-Type": "application/json"
}
response = requests.request("POST", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create("[ { \"id\": \"1\", \"text\": \"I love the service\", \"language\": \"en\" }]", mediaType);
Request request = new Request.Builder()
    .url("https://api.symanto.net/emotion")
    .method("POST", body)
    .addHeader("x-api-key","opensesame")
    .build();
Response response = client.newCall(request).execute();

The above command returns JSON structured like this:

[
    {
        "id": "1",
        "predictions": [
            {
                "prediction": "joy",
                "probability": 0.619248952716589
            }
        ]
    }
]

Detect the emotion expressed in the text.

Supported language codes are: [ de, en, es ]

Retrieved emotions can be any of: [anger, joy, love, sadness, surprise]

HTTP Request

POST https://api.symanto.net/emotion

Query Parameters

Parameter Type Default Description
all bool false returns all predictions, not only the most probable one

REQUEST BODY SCHEMA : application/json

An array of max 512 items is allowed.

Parameter Type Optionality Description
id string Optional id of the post
text string Required the text to analyse
language string Required language_code of the text

Sentiment Analysis

curl -X POST "https://api.symanto.net/sentiment" 
-H "accept: application/json" 
-H "Content-Type: application/json" 
-H "x-api-key: opensesame" 
-d "[{\"id\":1,\"text\":\"I love the service\",\"language\":\"en\"}]"
import requests

url = "https://api.symanto.net/sentiment"

payload = "[{ \"id\": \"1\", \"text\": \"I love the service\", \"language\": \"en\" }]"
headers = {
    "x-api-key": "opensesame",
    "Content-Type": "application/json"
}
response = requests.request("POST", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create("[{\"id\": \"1\", \"text\": \"I love the service\", \"language\": \"en\" }]", mediaType);
Request request = new Request.Builder()
    .url("https://api.symanto.net/sentiment")
    .method("POST", body)
    .addHeader("x-api-key","opensesame")
    .build();
Response response = client.newCall(request).execute();

The above command returns JSON structured like this:

[
  {
    "id": "1",
    "predictions": [
      {
        "prediction": "positive",
        "probability": 0.8465812802314758
      }
    ]
  }
]

Detect the text-level sentiment from a piece of text.

Supported Languages: [en, de, es]

Returned labels: [positive, negative, unrecognized]

HTTP Request

POST https://api.symanto.net/sentiment

Query Parameters

Parameter Type Default Description
all bool false returns all predictions, not only the most probable one

REQUEST BODY SCHEMA : application/json

An array of max 32 items is allowed.

Parameter Type Optionality Description
id string Optional id of the post
text string Required the text to analyse
language string Required language_code of the text

Topic Sentiment Extraction

curl -X POST "https://api.symanto.net/topic-sentiment" 
-H "accept: application/json" 
-H "Content-Type: application/json" 
-H "x-api-key: opensesame" 
-d "[{\"id\":1,\"text\":\"Hello I love the service\",\"language\":\"en\"}]"
import requests

url = "https://api.symanto.net/topic-sentiment"

payload = "[{ \"id\": \"1\", \"text\": \"Hello I love the service\", \"language\": \"en\" }]"
headers = {
    "x-api-key": "opensesame",
    "Content-Type": "application/json"
}
response = requests.request("POST", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create("[{ \"id\": \"1\", \"text\": \"Hello I love the service\",\"language\": \"en\"} ]", mediaType);
Request request = new Request.Builder()
    .url("https://api.symanto.net/topic-sentiment")
    .method("POST", "opensesame")
    .addHeader("x-api-key","opensesame")
    .build();
Response response = client.newCall(request).execute();

The above command returns JSON structured like this:

[
    {
        "id": "1",
        "text": "Hello I love the service",
        "language": "en",
        "topicSentiments": [
            {
                "topic": {
                    "start": 3,
                    "end": 5,
                    "topic": "Service",
                    "text": "the service",
                    "category": "Service General"
                },
                "sentiment": {
                    "start": 2,
                    "end": 3,
                    "text": "love",
                    "positive": true,
                    "scale": 1.0
                },
                "sentence": "love the service"
            }
        ],
        "sentiments": [
            {
                "start": 2,
                "end": 3,
                "text": "love",
                "positive": true,
                "scale": 1.0,
                "category": "",
                "parentCategory": ""
            }
        ],
        "topics": [
            {
                "start": 3,
                "end": 5,
                "topic": "Service",
                "text": "the service",
                "category": "Service General"
            }
        ]
    }
]

Detects topics, topic category of each topic, and then analyzes the sentiment towards each of the topics mentioned.

Supported Languages: [en, de]

HTTP Request

POST https://api.symanto.net/topic-sentiment

Query Parameters

Parameter Default Description
domain - Provide analysis domain for domain-specific extraction (optional)

Available domains

Enum Description
"Ecom" Use this domain to retrieve insights about experience, product and service.
"Employee" Use this domain to retrieve insights about associates, communication, culture, development & resources, leadership & planning, overall perception, pay & benefits, role, treatment and work environment.

REQUEST BODY SCHEMA : application/json

An array of max 64 items is allowed. Only the first 2000 characters from each text will be analyzed.

Parameter Type Optionality Description
id string Optional id of the post
text string Required the text to analyse
language string Required language_code of the text

Language Detection

curl -X POST "https://api.symanto.net/language-detection" 
-H "accept: application/json" 
-H "Content-Type: application/json" 
-H "x-api-key: opensesame" 
-d "[{\"id\":1,\"text\":\"Hello I love the service\"}]"
import requests

url = "https://api.symanto.net/language-detection"

payload = "[{\"id\": \"1\",\"text\": \"Hello I love the service\"}]"
headers = {
    "x-api-key": "opensesame",
    "Content-Type": "application/json"
}
response = requests.request("POST", url, headers=headers, data=payload)
OkHttpClient client = new OkHttpClient().newBuilder().build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create("[ { \"id\": \"1\", \"text\": \"Hello I love the service\" }]", mediaType);
Request request = new Request.Builder()
    .url("https://api.symanto.net/language-detection")
    .method("POST", body)
    .addHeader("x-api-key","opensesame")
    .build();
Response response = client.newCall(request).execute();

The above command returns JSON structured like this:

[
    {
        "id": "1",
        "detected_language": "en"
    }
]

Identify the language of the input text.

Returned labels: language_code of the detected language

HTTP Request

POST https://api.symanto.net/language-detection

REQUEST BODY SCHEMA : application/json

An array of max 64 items is allowed.

Parameter Type Optionality Description
id string Optional id of the post
text string Required the text to analyse

Errors

Symanto API uses the following error codes:

Error Code Meaning
400 Bad Request -- Your request is invalid.
401 Unauthorized -- Your API key is wrong.
403 Forbidden -- You don't have permission to access this object.
404 Not Found -- The specified object could not be found.
405 Method Not Allowed -- You tried to access an object with an invalid method.
406 Not Acceptable -- You requested a format that isn't json.
422 Validation Error.
429 Too Many Requests.
500 Internal Server Error -- We had a problem with our server. Try again later.
503 Service Unavailable -- We're temporarily offline for maintenance. Please try again later.