Semantria API Developer Reference

Lexalytics Semantria API Documentation Developer Hub

Welcome to the Lexalytics Semantria API Documentation developer hub. You'll find comprehensive guides and documentation to help you start working with Lexalytics Semantria API Documentation as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    
Suggest Edits

Sending one document at a time

 
post/document.[json|xml]
import semantria
session = semantria.Session(key, secret)
doc = { 
  "id" : "cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
  "text" : "A chunk of text for processing",
  "tag" : "A tag is any text (up to 50 characters) used like a marker."
}
status = self.session.queueDocument(doc, config_id="id")
POST https://api.semantria.com/document.json?config_id=cd2e7341-a3c2-4fb4-9d3a
  -779e8b0a5eff
{
  "id" : "cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
  "text" : "A chunk of text for processing",
  "tag" : "A tag is any text (up to 50 characters) used like a marker."
}
POST https://api.semantria.com/document.xml?config_id=cd2e7341-a3c2-4fb4-9d3a-
  779e8b0a5eff
<document>
   <id>cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</id>
   <text>A chunk of text for processing</text>
   <tag>A tag is any text (up to 50 characters) used like a marker.</tag>
</document>
A binary file was returned

You couldn't be authenticated

HTTP/1.0 202 Request accepted and queued for processing.

Body Params

config_id
string
required

(Optional) the configuration id

 
Suggest Edits

Sending multiple documents at a time

A batch is an array of documents, each which consists of three values: an optional unique ID, an option tag, and the text you wish to analyze.

 
post/batch.[json|xml]
import semantria
session = semantria.Session(key, secret)
session.queueBatch(   
  [
    {
  		"id" : " 6F9619FF8B86D011B42D00CF4FC964FF",
  		"text" : "A chunk of text for processing"
  		"tag" : "Any text (up to 50 characters) used like a marker."
		},
		{
  		"id" : " 9G9619RG9286NG889E2D00CF4FBI9R7F",
  		"text" : "The next chunk of text for processing"
  		"tag" : "Any text (up to 50 characters) used like a marker."
		}
	],
  config_id = "id"
)
POST https://api.semantria.com/document/batch.json?config_id=cd2e7341-a3c2-4fb4-
  9d3a-779e8b0a5eff
[
{
  "id" : " 6F9619FF8B86D011B42D00CF4FC964FF",
  "text" : "A chunk of text for processing"
  "tag" : "Any text (up to 50 characters) used like a marker."
},
{
  "id" : " 9G9619RG9286NG889E2D00CF4FBI9R7F",
  "text" : "The next chunk of text for processing"
  "tag" : "Any text (up to 50 characters) used like a marker."
}
]
POST https://api.semantria.com/document/batch.xml?config_id=cd2e7341-a3c2-4fb4-
  9d3a-779e8b0a5eff
<documents>
  <document>
    <id>6F9619FF8B86D011B42D00CF4FC964FF</id>
    <text>A chunk of text for processing</text>
    <tag>Any text (up to 50 characters) used like a marker.</tag>
  </document>
  <document>
    <id>9G9619RG9286NG889E2D00CF4FBI9R7F</id>
    <text>The next chunk of text for processing </text>
    <tag>Any text (up to 50 characters) used like a marker.</tag>
  </document>
</documents>
A binary file was returned

You couldn't be authenticated

HTTP/1.0 202 Request accepted and queued for processing. 
{ 'status': 400, 'message': 'Internal Server Error: Interceptor exception. Request body is syntactically incorrect.'
}
{'status': 401, 'message': 'Authentication failed.'}
{'status': 402, 'message': 'Request is unauthorized. Documents balance exceeded. See Verify Subscription end-point for details.'}
{'status': 402, 'message': 'Data API calls limit has been exceeded. Please contact support@semantria.com to review your limits and troubleshoot.'}
{'status': 402, 'message': 'Request is unauthorized. User license is expired.'}
{'status': 406, 'message': 'Limit of documents per batch has been exceeded.'}
ERROR: {'status': 403, 'message': 'You are trying to use configuration with the language that is forbidden for your license. Please contact Semantria support (support@semantria.com) for details.'}
ERROR: { 'status': 413, 'message' : 'Limit of characters per single document has been exceeded.')

Body Params

config_id
string
required

The configuration ID

 

Detailed analysis

Users can submit a batch of documents for Detailed analysis, but each document will still be surveyed and analyzed independently (as if they were submitted one by one).

Queue by configuration for efficiency

If submitting many documents for Detailed Mode, your analysis will be much more efficient if the whole batch is queued for the same configuration. Sorting documents into configuration-specific batches will keep your documents organized and your analysis fast.

Suggest Edits

Sending documents by job_id

A job_id is not required but can be helpful to separate out content processed via particular environments (dev vs QA) or particular job streams (historical content vs live news).

Job_id is only supported by the polling method (not callback or auto response) and if you submit via job_id, you must also retrieve by job_id. You can use only 100 unique job_ids per 24 hour period.

If you specified a job_id when submitting you must also specify a job_id when retrieving.

You can use both a config_id and a job_id in a document submission.

A batch of documents is an array of documents for processing, which each contain the following parameters: (optional) id, text, (optional) tag

 
post/batch.[json|xml]
import semantria
session = semantria.Session(key, secret)
session.queueBatch(   
  [
    {
  		"id" : " 6F9619FF8B86D011B42D00CF4FC964FF",
  		"text" : "A chunk of text for processing",
      "job_id": "TestID",
  		"tag" : "Any text (up to 50 characters) used like a marker."
		},
		{
  		"id" : " 9G9619RG9286NG889E2D00CF4FBI9R7F",
  		"text" : "The next chunk of text for processing",
      "job_id": "TestID",
  		"tag" : "Any text (up to 50 characters) used like a marker."
		}
	],
  config_id = "id"
)
POST https://api.semantria.com/document/batch.json?config_id=cd2e7341-a3c2-4fb4-
  9d3a-779e8b0a5eff
[
{
  "id" : " 6F9619FF8B86D011B42D00CF4FC964FF",
  "text" : "A chunk of text for processing",
  "tag" : "Any text (up to 50 characters) used like a marker."
},
{
  "id" : " 9G9619RG9286NG889E2D00CF4FBI9R7F",
  "text" : "The next chunk of text for processing",
  "tag" : "Any text (up to 50 characters) used like a marker."
}
]
POST https://api.semantria.com/document/batch.xml?config_id=cd2e7341-a3c2-4fb4-
  9d3a-779e8b0a5eff
<documents>
  <document>
    <id>6F9619FF8B86D011B42D00CF4FC964FF</id>
    <text>A chunk of text for processing</text>
    <tag>Any text (up to 50 characters) used like a marker.</tag>
  </document>
  <document>
    <id>9G9619RG9286NG889E2D00CF4FBI9R7F</id>
    <text>The next chunk of text for processing </text>
    <tag>Any text (up to 50 characters) used like a marker.</tag>
  </document>
</documents>
A binary file was returned

You couldn't be authenticated

HTTP/1.0 202 Request accepted and queued for processing. 

Body Params

config_id
string

(Optional) config ID to process content with

job_id
string

(Optional) job_id

 

Detailed analysis

Users can submit a batch of documents for Detailed analysis, but each document will still be surveyed and analyzed independently (as if they were submitted one by one).

Queue by configuration for efficiency

If submitting many documents for Detailed Mode, your analysis will be much more efficient if the whole batch is queued for the same configuration. Sorting documents into configuration-specific batches will keep your documents organized and your analysis fast.

Suggest Edits

Requesting specific documents

Requesting: Asking the status (or processed results) of a specific document

 
get/document/:document_id.[json|xml]
import semantria
session = semantria.Session(key, secret)
session.getDocument(
  doc_id = "id",
  config_id = "id"
 )
GET https://api.semantria.com/document/d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff.json
A binary file was returned

You couldn't be authenticated

HTTP/1.0 200 Request accepted and served.
{
   "id" : "d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
   "config_id" : "cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
   "tag" : "Any text (up to 50 characters) used like a marker.",
   "status" : "PROCESSED",
   "source_text" : "See \"Output Data Details\" chapter.",
   "language" : "English",
   "metadata": {
        "author": "Tim Mohler, 
        "date": "20160325"
    }, 
   "language_score" : 0.6972651,
   "sentiment_score" : 0.8295653,
   "sentiment_polarity" : "positive",
   "summary" : "Summary of the document’s text.",
   "details" : [
      {
         "is_imperative" : false,
         "is_polar : false,
         "words" : [
            {
               "tag" : "NNP",
               "type" : "Noun",
               "title" : "Aaron",
               "stemmed" : "Aaron",
               "is_negated" : false,
               "sentiment_score" : 0.569
            }
         ]
      }
   ],
   "phrases" : [
      {
         "title" : "friendly",
         "sentiment_score" : -0.4,
         "sentiment_polarity" : "negative",
         "is_negated" : true,
         "negating_phrase" : "not"
		 "is_intensified": false,
		 "type : "detected",
      }
   ],
   "model_sentiment": 
	  {
		"sentiment_polarity": "neutral",
		"model_name": "default",
		"mixed_score": 0.10868213325738907,
		"negative_score": 0.18008844554424286,
		"neutral_score": 0.47879499197006226,
		"positive_score": 0.2324344366788864
	  },  
   "auto_categories" :[
      {
         "title" : "Automotive",
         "type" : "node",
         "strength_score" : 0.378,
         "categories" : [
            {
               "title" : "Moto",
               "type" : "leaf",
               "strength_score" : 0.67
            }
         ]
      }
   ],
   "themes" : [
      {
         "evidence" : 1,
         "is_about" : true,
         "strength_score" : 0.0,
         "sentiment_score" : 0.0,
         "sentiment_polarity" : "neutral",
         "title" : "republican moderates"
         "mentions" : [
            {
               "label" : "Something",
               "is_negated" : true,
               "negating_phrase" : "negator",
               "locations" : [
                  {
                     "offset" : 987,
                     "length" : 9
                  }
               ]
            }
         ]
      }
   ],
   "entities" : [
      {
         "type" : "named",
         "evidence" : 0,
         "confident" : false,
         "is_about" : true,
         "entity_type" : "Place",
         "title" : "WASHINGTON",
         "label" : "The capital of the United States of America.",
         "sentiment_score" : 1.0542796,
         "sentiment_polarity" : "positive",
         "mentions" : [
            {
               "label" : "Something",
               "is_negated" : true,
               "negating_phrase" : "negator",
               "locations" : [
                  {
                     "offset" : 987,
                     "length" : 9
                  }
               ]
            }
         ]
         "themes" : [
            {
               "evidence" : 1,
               "is_about" : true,
               "strength_score" : 0.0,
               "sentiment_score" : 0.0,
               "sentiment_polarity" : "neutral",
               "title" : "republican moderates"
               "mentions" : [
                  {
                     "label" : "Something",
                     "is_negated" : true,
                     "negating_phrase" : "negator",
                     "locations" : [
                        {
                           "offset" : 987,
                           "length" : 9
                        }
                     ]
                  }
               ]
            }
         ]
      }
   ],
   "relations" : [
      {
         "type" : "named",
         "relation_type" : "Occupation",
         "confidence_score" : 1.0,
         "extra" : "",
         "entities" : [
            {
               "title" : "head judge",
               "entity_type" : "Job Title"
            },
            {
               "title" : "John Snow",
               "entity_type" : "Person"
            }
         ]
      }
   ],
   "opinions" : [
      {
         "quotation" : "Some opinion of John Kerry about the US.",
         "type" : "named",
         "speaker" : "John Kerry",
         "topic" : "United States",
         "sentiment_score" : 0.49,
         "sentiment_polarity" : "positive"
      }
   ]
   "topics" : [
      {
         "title" : "Something",
         "type" : "concept",
         "hitcount" : 0,
         "strength_score" : 0.0,
         "sentiment_score" : 0.6133076,
         "sentiment_polarity" : "positive"
      }
   ]
}
HTTP/1.0 200 Request accepted and served.
<document>
  <config_id>cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</config_id>
  <id>d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</id>
  <tag>Any text (up to 50 characters) used like a marker.</tag>
  <status>PROCESSED</status>
  <source_text>See ”Output Data Details” chapter</source_text>
  <language>English</language>
  <language_score>0.6972651</language_score>
  <sentiment_score>0.2398756</sentiment_score>
  <sentiment_polarity>positive</sentiment_polarity>
  <summary>Summary of the document’s text.</summary>
  <details>
    <sentence>
      <is_imperative>false</is_imperative>
      <is_polar>false</is_polar>
        <words>
          <word>
            <tag>NNP</tag>
            <type>Noun</type>
            <title>Aaron</title>
            <stemmed>Aaron</stemmed>
            <is_negated>false</is_negated>
            <sentiment_score>0.569</sentiment_score>
          </word>
        </words>
      </sentence>
    </details>
    <phrases>
      <phrase>
         <title>friendly</title>
		 <sentiment_score>-0.4</sentiment_score>
         <sentiment_polarity>negative</sentiment_polarity>	
         <is_negated>true</is_negated>	
		 <negating_phrase>not</negating_phrase>
		 <is_intensified>false</is_intensified>
         <type>detected</type>
      </phrase>
    </phrases >
	<model_sentiment>
		 <sentiment_polarity>neutral</sentiment_polarity>
		 <model_name>default</model_name>
		 <mixed_score>0.10868213325738907</mixed_score>
		 <negative_score>0.18008844554424286</negative_score>
		 <neutral_score>0.47879499197006226</neutral_score>
		 <positive_score>0.2324344366788864</positive_score>
	</model_sentiment>
    <auto_categories>
      <category>
        <title>Automotive</title>
        <type>node</type>
        <strength_score>0.378</strength_score>
        <categories>
          <category>
            <title>Moto</title>
            <type>leaf</type>
            <strength_score>0.67</strength_score>
          </category>
        </categories>
      </category>
    </auto_categories>
    <themes>
      <theme>
      <evidence>1</evidence>
      <is_about>true</is_about>
      <strength_score>0.0</strength_score>
      <sentiment_score>0.0</sentiment_score>
      <sentiment_polarity>neutral</sentiment_polarity>
      &lt;title&gt;republican moderates&lt;/title&gt;
      <mentions>
        <mention>
        <label>Something</label>
        <is_negated>true</is_negated>
        <negating_phrase>negator</negating_phrase>
        <locations>
          <location>
            <offset>987</offset>
            <length>9</length>
          </location>
        </locations>
      </mention>
    </mentions>
  </theme>
</themes>

<entities>
  <entity>
    <type>named</type>
    <evidence>0</evidence>
    <confident>false</confident>
    <is_about>true</is_about>
    <entity_type>Place</entity_type>
    <title>WASHINGTON</title>
    <label>The capital of the United States of America.</label>
    <sentiment_score>1.0542796</sentiment_score>
    <sentiment_polarity>positive</sentiment_polarity>
    <mentions> <mention>
    <label>Something</label>
    <is_negated>true</is_negated>
    <negating_phrase>negator</negating_phrase>
    <locations> <location>
    <offset>987</offset>
    <length>9</length>
    </location> </locations>
    </mention> </mentions>
    <themes>
      <theme>
        <evidence>1</evidence>
        <is_about>true</is_about>
        <strength_score>0.0</strength_score>
        <sentiment_score>0.0</sentiment_score>
        <sentiment_polarity>neutral</sentiment_polarity>
        <title>republican moderates</title>
          <mentions>
            <mention>
              <label>Something</label>
              <is_negated>true</is_negated>
              <negating_phrase>negator</negating_phrase>
              <locations>
                <location>
                  <offset>987</offset>
                  <length>9</length>
                </location>
              </locations>
            </mention>
          </mentions>
        </theme>
      </themes>
    </entity>
  </entities>

  <relations>
    <relation>
      <type>named</type>
      <relation_type>Occupation</relation_type>
      <confidence_score>1.0</confidence_score>
      <extra>took</extra>
      <entities>
        <entity>
          <title>head judge</title>
          <entity_type>Job Title</entity_type>
        </entity>

        <entity>
          <title>John Snow</title>
          <entity_type>Person</entity_type>
        </entity>
      </entities>
    </relation>
  </relations>
  <opinions>
    <opinion>
      <quotation>Some opinion of John Kerry about the US.</quotation>
      <type>named</type>
      <speaker>John Kerry</speaker>
      <topic>United States</topic>
      <sentiment_score>0.49</sentiment_score>
      <sentiment_polarity>positive</sentiment_polarity>
    </opinion>
  </opinions>
    <topics>
      <topic>
        <title>Something</title>
        <hitcount>0</hitcount>
          <sentiment_score>0.6133076</sentiment_score>
          <sentiment_polarity>positive</sentiment_polarity>
          <strength_score>0.6133076</strength_score>
          <type>concept</type>
      </topic>
    </topics>
</document>

Path Params

document_id
string
required

the id of the desired document

Query Params

config_id
string

Optional if the document was processed with the default configuration. Required for non-default configurations.

 
Suggest Edits

Retrieving Documents

This call retrieves as many processed documents as fit into your maximum batch size. Note the HTTP code will not work as is because it requires a timestamp and nonce. Using our SDK will take care of this for you.

 
get/document/processed.[json | xml]
import semantria
session = semantria.Session(key, secret)
session.getProcessedDocuments(
  config_id = "id"
)
GET https://api.semantria.com/document/processed.json?config_id=cd2e7341-a3c2-4fb4-
  9d3a-779e8b0a5eff
A binary file was returned

You couldn't be authenticated

HTTP/1.0 202 Request accepted and served.
[
   {
      "id" : "d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
      "config_id" : "cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
      "tag" : "Any text (up to 50 characters) used like a marker.",
      "status" : "PROCESSED"
      //Accompanying output as described in the "Request Document" section
   },
   {
      "id" : "d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
      "config_id" : "cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
      "tag" : "Any text (up to 50 characters) used like a marker.",
      "status" : "PROCESSED"
      //Accompanying output as described in the "Request Document" section
   }
]
HTTP/1.0 202 Request accepted and served.
<documents>
  <document>
    <id>d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</id>
    <config_id>cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</config_id>
    <tag>Any text (up to 50 characters) used like a marker.</tag>
    <status>PROCESSED</status>
    <!-- Accompanying output as described in the “Request Document” section -->
  </document>
  <document>
    <id>d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</id>
    <config_id>cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</config_id>
    <tag>Any text (up to 50 characters) used like a marker.</tag>
    <status>PROCESSED</status>
    <!-- Accompanying output as described in the “Request Document” section -->
  </document>
</documents>

Query Params

config_id
string

(Optional) the configuration id

job_id
string

(Optional) the job_id

 

Batch Size Limit

By default, the server responds to retrieval requests with 100 documents per batch. To increase this limit, please contact us.

Once a document has been retrieved, it will be removed from the Semantria systems.

Suggest Edits

Canceling documents

Canceling: deleting a queued document if Semantria has not processed it yet.

 
delete/document/:document_id.[json | xml]
DELETE https://api.semantria.com/document/d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff.json
A binary file was returned

You couldn't be authenticated

HTTP/1.0 202 Request accepted and served.

Path Params

document_id
string
required

the document id

 
Suggest Edits

Retrieving Documents by job_id

If you submitted via job_id, you must also retrieve by that job_id. You cannot use a config_id when retrieving by job_id, although you can use a config_id when submitting with a job_id.

 
get/document/processed.[json | xml]
import semantria
session = semantria.Session(key, secret)
session.getProcessedDocumentsByJobId(
  job_id = "id"
)
GET https://api.semantria.com/document/processed.json?job_id=1
A binary file was returned

You couldn't be authenticated

HTTP/1.0 202 Request accepted and served.
[
   {
      "id" : "d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
      "config_id" : "cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
      "tag" : "Any text (up to 50 characters) used like a marker.",
      "status" : "PROCESSED"
      //Accompanying output as described in the "Request Document" section
   },
   {
      "id" : "d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
      "config_id" : "cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
      "tag" : "Any text (up to 50 characters) used like a marker.",
      "status" : "PROCESSED"
      //Accompanying output as described in the "Request Document" section
   }
]
HTTP/1.0 202 Request accepted and served.
<documents>
  <document>
    <id>d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</id>
    <config_id>cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</config_id>
    <tag>Any text (up to 50 characters) used like a marker.</tag>
    <status>PROCESSED</status>
    <!-- Accompanying output as described in the “Request Document” section -->
  </document>
  <document>
    <id>d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</id>
    <config_id>cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</config_id>
    <tag>Any text (up to 50 characters) used like a marker.</tag>
    <status>PROCESSED</status>
    <!-- Accompanying output as described in the “Request Document” section -->
  </document>
</documents>

Query Params

job_id
string

The job_id

 

Batch Size Limit

By default, the server responds to retrieval requests with 100 documents per batch. To increase this limit, please contact us.

Once a document has been retrieved, it will be removed from the Semantria systems.

Suggest Edits

Sending metadata with your documents

In addition to the required fields, you can also submit metadata about your content. Metadata submissions are allowed only when using the JSON format of the endpoint. No processing of the metadata elements is done by Semantria and the metadata fields will be returned to you with the document when you retrieve it.

 
post/document.json
{"id":"1234", 
 "text": "Some sample text", 
 "metadata": {"source": "twitter", "datetime": "2016-01-08T17:21:01", ...},
 }
{
 "id": "x-collection",
 "metadata": ["abc", 123],
 "tag": "my-tag",
 "documents": ["Some text", "Some other text"]
}
A binary file was returned

You couldn't be authenticated

Try the API to see results
 

The metadata field is schema less and can contain any valid JSON you wish to send. You can attach metadata to individual documents and to collections as well.

Suggest Edits

Sending a collection of documents

This method submits an array of documents to be analyzed in relation to each other and returns one output. Discovery analysis will contain a summary of sentiment, named entity extraction, themes, and categorization for all the documents in the collection.

A collection consists of an array of elements: (optional) ID, (optional) tag and an array of pieces of text.

 
posthttps:/api.semantria.com/collection.[json|xml]
import semantria
session = semantria.Session(key, secret)
session.queueCollection(
  config_id = "id",
  {
  	"id" : "6F9619FF8B86D011B42D00CF4FC964FF",
  	"tag" : "Any text (up to 50 characters) used like a marker.",
  	"documents" : [
    	"The first chunk of text for processing",
    	"Another chunk of text for processing",
    	"Third chunk of text for processing"
  	]
	}
)
POST https://api.semantria.com/collection.json?config_id=cd2e7341-a3c2-4fb4-9d3a-
  779e8b0a5eff
{
  "id" : "6F9619FF8B86D011B42D00CF4FC964FF",
  "tag" : "Any text (up to 50 characters) used like a marker.",
  "documents" : [
    "The first chunk of text for processing",
    "Another chunk of text for processing",
    "Third chunk of text for processing"
  ]
}
POST https://api.semantria.com/collection.xml?config_id=cd2e7341-a3c2-4fb4-9d3a-
          779e8b0a5eff

<collection>
  <id>6F9619FF8B86D011B42D00CF4FC964FF</id>
  <tag>Any text (up to 50 characters) used like a marker.</tag>
  <documents>
    <document>The first chunk of text for processing</document>
    <document>Another chunk of text for processing</document>
    <document>Third chunk of text for processing</document>
  </documents>
</collection>
A binary file was returned

You couldn't be authenticated

HTTP/1.0 202 Request accepted and queued for processing.

Body Params

config_id
string

(Optional) ID of config to use

 
Suggest Edits

Sending a collection by job_id

This method submits an array of documents to be analyzed in relation to each other and returns one output. Discovery analysis will contain a summary of sentiment, named entity extraction, themes, and categorization for all the documents in the collection.

A collection consists of an array of elements: (optional) ID, (optional) tag and an array of pieces of text.

You can use a job_id to separate specific environment (such as dev vs QA). Collections submitted with a job_id must be retrieved via that same job_id.

 
posthttps:/api.semantria.com/collection.[json|xml]
import semantria
session = semantria.Session(key, secret)
session.queueCollection(
  config_id = "id",
  job_id = "id"
  {
  	"id" : "6F9619FF8B86D011B42D00CF4FC964FF",
  	"tag" : "Any text (up to 50 characters) used like a marker.",
  	"documents" : [
    	"The first chunk of text for processing",
    	"Another chunk of text for processing",
    	"Third chunk of text for processing"
  	]
	}
)
POST https://api.semantria.com/collection.json?config_id=cd2e7341-a3c2-4fb4-9d3a-
  779e8b0a5eff&job_id=1
{
  "id" : "6F9619FF8B86D011B42D00CF4FC964FF",
  "tag" : "Any text (up to 50 characters) used like a marker.",
  "documents" : [
    "The first chunk of text for processing",
    "Another chunk of text for processing",
    "Third chunk of text for processing"
  ]
}
POST https://api.semantria.com/collection.xml?config_id=cd2e7341-a3c2-4fb4-9d3a-
          779e8b0a5eff

<collection>
  <id>6F9619FF8B86D011B42D00CF4FC964FF</id>
  <tag>Any text (up to 50 characters) used like a marker.</tag>
  <documents>
    <document>The first chunk of text for processing</document>
    <document>Another chunk of text for processing</document>
    <document>Third chunk of text for processing</document>
  </documents>
</collection>
A binary file was returned

You couldn't be authenticated

HTTP/1.0 202 Request accepted and queued for processing.

Body Params

config_id
string

(Optional) ID of config to use

job_id
string

(Optional) ID of job.

 
Suggest Edits

Retrieving processed discovery analyses

Retrieving: Returning any and all processed collections

 
gethttps://api.semantria.com/collection/processed.[json | xml]
import semantria
session = semantria.Session(key, secret)
session.getProcessedCollections( config_id = "id" )
GET https://api.semantria.com/collection/processed.json?config_id=cd2e7341-a3c2-
  4fb4-9d3a-779e8b0a5eff
A binary file was returned

You couldn't be authenticated

HTTP/1.0 202 Request accepted and served.
[
   {
      "id" : "d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
      "config_id" : "cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
      "tag" : "Any text (up to 50 characters) used like a marker.",
      "status" : "PROCESSED"
      //Accompanying output as described in the "Request Collection" section
   },
   {
      "id" : "s8k5441-ar62-4f24-95wt-479e845d6csf",
      "config_id" : "cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
      "tag" : "Any text (up to 50 characters) used like a marker.",
      "status" : "PROCESSED"
      //Accompanying output as described in the "Request Collection" section
   }
] 
HTTP/1.0 202 Request accepted and served.
<collections>
  <collection>
    <id>d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</id>
    <config_id>cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</config_id>
    <tag>Any text (up to 50 characters) used like a marker.</tag>
    <!- Accompanying output as described in the “Request Collection” section ->
  </collection>

  <collection>
    <id> s8k5441-ar62-4f24-95wt-479e845d6csf </id>
    <config_id>cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</config_id>
    <tag>Any text (up to 50 characters) used like a marker.</tag>
    <!- Accompanying output as described in the “Request Collection” section ->
  </collection>
</collections>

Query Params

config_id
string

return processed documents from a particular config id. If the config_id is not provided, the API uses the primary configuration id by default

document_id
string

return only the document with this ID

 
Suggest Edits

Retrieving processed discovery by job_id

If you submitted by job_id you must also retrieve by job_id.

 
gethttps://api.semantria.com/collection/processed.[json | xml]
import semantria
session = semantria.Session(key, secret)
session.getProcessedCollections( job_id = "id" )
GET https://api.semantria.com/collection/processed.json?config_id=cd2e7341-a3c2-
  4fb4-9d3a-779e8b0a5eff
A binary file was returned

You couldn't be authenticated

HTTP/1.0 202 Request accepted and served.
[
   {
      "id" : "d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
      "config_id" : "cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
      "tag" : "Any text (up to 50 characters) used like a marker.",
      "status" : "PROCESSED"
      //Accompanying output as described in the "Request Collection" section
   },
   {
      "id" : "s8k5441-ar62-4f24-95wt-479e845d6csf",
      "config_id" : "cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff",
      "tag" : "Any text (up to 50 characters) used like a marker.",
      "status" : "PROCESSED"
      //Accompanying output as described in the "Request Collection" section
   }
] 
HTTP/1.0 202 Request accepted and served.
<collections>
  <collection>
    <id>d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</id>
    <config_id>cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</config_id>
    <tag>Any text (up to 50 characters) used like a marker.</tag>
    <!- Accompanying output as described in the “Request Collection” section ->
  </collection>

  <collection>
    <id> s8k5441-ar62-4f24-95wt-479e845d6csf </id>
    <config_id>cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</config_id>
    <tag>Any text (up to 50 characters) used like a marker.</tag>
    <!- Accompanying output as described in the “Request Collection” section ->
  </collection>
</collections>

Query Params

job_id
string

return processed documents from a particular job id.

 
Suggest Edits

Requesting specific discovery analysis

Requesting: Asking the status (or processed results) of a specific collection

 
gethttps://api.semantria.com/collection/:collection_id.[json|xml]
GET https://api.semantria.com/collection/d2e7341-a3c2-4fb4-9d3a-
  779e8b0a5eff.json
A binary file was returned

You couldn't be authenticated

HTTP/1.0 200 Request accepted and served.

{
   “id” : “d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff”,
   “config_id” : “cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff”,
   “tag” : “Any text (up to 50 characters) used like a marker.,
   “status” : “PROCESSED”,
   “facets” : [
      {
         “label” : “Something”,
         “count” : 10,
         “negative_count” : 2,
         “positive_count” : 1,
         “neutral_count” : 7,
         “attributes” : [
            {
               “label” : “Attribute”,
               “count” : 5
               “mentions” : [
                  {
                     “label” : “something”,
                     “is_negated” : true,
                     “negating_phrase” : “negator”,
                     ]
                  }
               ]
            }
         ],
         “mentions” : [
            {
               “label” : “something”,
               “is_negated” : true,
                “negating_phrase” : “negator”,
            }
         ]
      }
   ],
   “themes” : [
      {
         “title” : “republican moderates”,
         “phrases_count” : 5,
         “themes_count” : 9,
         “sentiment_score” : 0.37,
         “sentiment_polarity” : “positive”,
         “mentions” : [
            {
               “label” : “republican moderates”,
               “is_negated” : true,
                “negating_phrase” : “negator”,
                “locations” : [
                   {
                      “index” : 17,
                       “offset” : 987,
                       “length” : 9
                   }
                ]
            }
         ]
      }
   ],
   “entities” : [
      {
         “title” : “WASHINGTON”,
         “label” : “The capital of the United States of America”,
         “type” : “named”,
         “entity_type” : “Place”,
         “count” : 5,
         “negative_count” : 2,
         “positive_count” : 1,
         “neutral_count” : 2,
         “mentions” : [
            {
               “label” : “WASHINGTON”,
               “is_negated” : true,
                “negating_phrase” : “negator”,
                “locations” : [
                   {
                      “index” : 17,
                       “offset” : 987,
                       “length” : 9
                   }
                ]
            }
         ]
      }
   ],
   “topics” : [
      {
         “title” : “Something”,
         “type” : “concept”,
         “hitcount” : 0,
         “sentiment_score” : 0.6133076,
         “sentiment_polarity” : “positive”
      }
   ]
}}
HTTP/1.0 200 Request accepted and served.
<collection>
   <config_id>cd2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</config_id>
   <id>d2e7341-a3c2-4fb4-9d3a-779e8b0a5eff</id>
   <tag>Any text (up to 50 characters) used like a marker.</tag>
   <status>PROCESSED</status>
   <facets>
      <facet>
         <label>Something</label>
         <count>10</count>
         <negative_count>2</negative_count>
         <positive_count>1</positive_count>
         <neutral_count>7</neutral_count>
         <attributes>
            <attribute>
               <label>Attribute</label>
               <count>5</count>
               <mentions>
                  <mention>
                     <label>something</label>
                     <is_negated>true</is_negated>
                     <negating_phrase>some</negating_phrase>
                  </mention>
               </mentions>
            </attribute>
         </attributes>
         <mentions>
            <mention>
               <label>something</label>
               <is_negated>true</is_negated>
               <negating_phrase>some</negating_phrase>
            </mention>
         </mentions>
      </facet>
   </facets>
   <themes>
      <theme>
         <title>republican moderates</title>
         <phrases_count>5</phrases_count>
         <themes_count>9</themes_count>
         <sentiment_score>0.37</sentiment_score>
         <sentiment_polarity>positive</sentiment_polarity>
         <mentions>
            <mention>
               <label>something</label>
               <is_negated>true</is_negated>
               <negating_phrase>some</negating_phrase>
               <locations>
                  <location>
                     <offset>987</offset>
                     <length>9</length>
                     <index>17</index>
                  </location>
               </locations>
            </mention>
         </mentions>
      </theme>
   </themes>
   <entities>
      <entity>
         <title>WASHINGTON</title>
         <label>The capital of the United States of America.</label>
         <type>named</type>
         <entity_type>Place</entity_type>
         <count>5</count>
         <negative_count>2</negative_count>
         <positive_count>1</positive_count>
         <neutral_count>2</neutral_count>
         <mentions>
            <mention>
               <label>something</label>
               <is_negated>true</is_negated>
               <negating_phrase>some</negating_phrase>
               <locations>
                  <location>
                     <offset>987</offset>
                     <length>9</length>
                     <index>17</index>
                  </location>
               </locations>
            </mention>
         </mentions>
      </entity>
   </entities>
   <topics>
      <topic>
         <title>Something</title>
         <hitcount>0</hitcount>
         <sentiment_score>0.6133076</sentiment_score>
         <sentiment_polarity>positive</sentiment_polarity>
         <type>concept</type>
      </topic>
   </topics>
</collection>

Path Params

collection_id
string
required

the collection's id

 
Suggest Edits

Canceling discovery analyses

Canceling: deleting a queued document if Semantria has not processed it yet.

 
deletehttps://api.semantria.com/collection/:collection_id.[json | xml]
DELETE https://api.semantria.com/collection/d2e7341-a3c2-4fb4-9d3a-
779e8b0a5eff.json
A binary file was returned

You couldn't be authenticated

HTTP/1.0 202 Request accepted and served.

Path Params

collection_id
string
required
 
Suggest Edits

Configuration Basics

 

The configuration endpoint allows you to manage your Semantria configurations. For all operations except DELETE, if you do not send in a configuration ID, the action will apply to your PRIMARY configuration. You cannot delete your PRIMARY configuration.

Each configuration has a language associated with it. This language cannot be changed once the configuration is established.

Each of the NLP outputs (such as themes, entities and so on) can be turned off by setting the corresponding output limit value to 0.

Suggest Edits

Listing existing configurations

The results listing here shows every settable option in a configuration. You do not have to submit all of these values to modify specific values of a configuration.

 
get/configurations.[json | xml]
import semantria
session = semantria.Session(key, secret)
session.getConfigurations()
https://api.semantria.com/configurations.json
 using (Session session = Session.CreateSession(consumerKey, consumerSecret, serializer))
 List<dynamic> configs = session.GetConfigurations()
A binary file was returned

You couldn't be authenticated

[
   {
      "name": "New test configuration",
	 		"language": "English",
	  	"config_id" : "",
      "is_primary" : true,
	  	"document": {
        "intentions": false,
        "concept_topics": true,
        "query_topics": true,
        "detect_language": true,
        "themes": false,
        "named_entities": true,
        "sentiment_phrases": true,
        "user_entities": true,
        "pos_types": "",
        "summary_size": 20,
        "relations" : true,
        "mentions": false,
        "opinions" : true,
        "auto_categories": true,
        "model_sentiment" : false
	  },
     "auto_response": false,
     "is_primary": false,
     "concept_topics_threshold": 0.45,
     "entities_threshold": 0,
     "collection": {
      "concept_topics": true,
      "query_topics": true,
      "named_entities": true,
      "user_entities": true,
      "mentions" : false,
      "attributes": true,
      "facets": true,
      "themes": true,
	  },
     "process_html": false,
     "alphanumeric_threshold": 30,
     "one_sentence_mode": false
    }
]
 
Suggest Edits

Creating Configurations

When creating a configuration, only a few fields are mandatory to set. These are:

--name
--is_primary
--language

The complete list of settable values, their types and defaults, are listed here: configuration values.

 
post/configurations.json
import semantria
session = semantria.Session(key,secret)
session.addConfigurations({ 
    "name" : "myConfig", 
    "auto_response" : "false" , 
    "language" : "French" , 
    "document" : 
    { 
      "detect_language" : "true" 
    }, 
    "collection" : 
    { 
      "facets_limit" : 5 
    } 
  }
                         )
POST https://api.semantria.com/configurations.json
[
   {
      "name" : "New test configuration",
      "is_primary" : true,
      "auto_response" : false,
      "language" : "English",
      "alphanumeric_threshold" : 80,
      "categories_threshold" : 0.45,
	  	"entities_threshold" : 0,
      "one_sentence_mode" : false,
      "process_html" : false,
      "callback" : "https://anyapi.anydomain.com/processed.json",
      "document" : {
         "intentions" : false,
         "pos_types" : "Noun,Verb,Adjective",
         "sentiment_phrases" : true,
         "auto_categories" : true,
         "concept_topics" : true,
         "query_topics" : true,
         "named_entities" : true,
         "user_entities" : true,
         "mentions" : false,
         "relations" : false,
         "opinions" : false,
         "themes" : false,
         "summary_size" : 0,
         "detect_language" : true
      },
      "collection" : {
         "facets" : true,
         "attributes" : true,
         "mentions" : false,
         "concept_topics" : true,
         "query_topics" : true,
         "named_entities" : true,
         "themes" : false,
				 "user_entitities" : true,
      }
   }
]
POST https://api.semantria.com/configurations.xml
<configurations>
   <configuration>
      <config_id> </config_id>
      <name>New test configuration</name>
      <is_primary>true</is_primary>
      <auto_response>false</auto_response>
      <language>English</language>
      <chars_threshold>80</chars_threshold>
	  <entities_threshold>0</entities_threshold>
      <one_sentence>false</one_sentence>
      <process_html>false</process_html>
      <callback>https://anyapi.anydomain.com/processed.json</callback>
       <document>
         <pos_types>Noun,Verb,Adjective</pos_types>
         <phrases_limit>10</phrases_limit>
         <possible_phrases_limit>10</possible_phrases_limit>
         <auto_categories_limit>5</auto_categories_limit>
         <concept_topics_limit>5</concept_topics_limit>
         <query_topics_limit>5</query_topics_limit>
         <named_entities_limit>5</named_entities_limit>
         <user_entities_limit>5</user_entities_limit>
         <entity_themes_limit>5</entity_themes_limit>
         <named_mentions_limit>0</named_mentions_limit>
         <user_mentions_limit>0</user_mentions_limit>
         <named_relations_limit>0</named_relations_limit>
         <user_relations_limit>0</user_relations_limit>
         <named_opinions_limit>0</named_opinions_limit>
         <user_opinions_limit>0</user_opinions_limit>
         <themes_limit>0</themes_limit>
         <theme_mentions_limit>0</theme_mentions_limit>
         <summary_limit>0</summary_limit>
         <detect_language>true</detect_language>
      </document>
      <collection>
         <facets_limit>15</facets_limit>
         <facet_atts_limit>5</facet_atts_limit>
         <facet_mentions_limit>0</facet_mentions_limit>
         <attribute_mentions_limit>0</attribute_mentions_limit>
         <concept_topics_limit>5</concept_topics_limit>
         <query_topics_limit>5</query_topics_limit>
         <named_entities_limit>5</named_entities_limit>
         <named_mentions_limit>0</named_mentions_limit>
         <themes_limit>0</themes_limit>
         <theme_mentions_limit>0</theme_mentions_limit>
		 <user_entities_limit>0</user_entities_limit>
		 <user_mentions_limit>0</user_mentions_limit>
      </collection>
   </configuration>
</configurations>
A binary file was returned

You couldn't be authenticated

HTTP/1.0 202 Request accepted and served.
{ 'status' : 400, 'message': 'Configurations name is empty' }
{'status' : 403, 'message' : The English language isn\'t supported by your license type. Please contact Semantria support (support@semantria.com) for details.' }
{ 'status' : 403, 'message' : 'The facets (Discovery mode) feature isn\'t supported by your license type. Please contact Semantria support (support@semantria.com) for details.' }
 
Suggest Edits

Modifying Configurations

Note a complete list of the settable values associated with configurations can be found here: configuration values. Note that when modifying a config you only need to send the values you wish to modify, you do not need to send all values.

 
put/configurations.[json | xml]
import semantria
session = semantria.Session(key,secret)
session.updateConfigurations(
  { 
    "config_id" : "id"
    "name" : "myConfig", 
    "auto_response" : "false" , 
    "language" : "French" , 
    "document" : 
    { 
      "detect_language" : "true" 
    }, 
    "collection" : 
    { 
      "facets_limit" : 5 
    } 
  }
                         )
POST https://api.semantria.com/configurations.json
[
   {
      "config_id" : "ID",
      "name" : "New test configuration",
      "is_primary" : true,
      "auto_response" : false,
      "language" : "English",
      "alphanumeric_threshold" : 80,
	  	"entities_threshold" : 0,
      "one_sentence_mode" : false,
      "process_html" : false,
      "callback" : "https://anyapi.anydomain.com/processed.json",
      "document" : {
         "pos_types" : "Noun,Verb,Adjective",
         "sentiment_phrases" : true,
         "auto_categories" : true,
         "concept_topics" : true,
         "query_topics" : true,
         "named_entities" : true,
         "user_entities" : true,
         "mentions" : false,
         "relations" : false,
         "opinions" : false,
         "themes" : false,
         "summary_size" : 0,
         "detect_language" : true
      },
      "collection" : {
         "facets" : true,
         "attributes" : true,
         "mentions" : false,
         "concept_topics" : true,
         "query_topics" : true,
         "named_entities" : true,
         "themes_limit" : false,
		     "user_entitities" : false,
      }
   }
]
POST https://api.semantria.com/configurations.xml
<configurations>
   <configuration>
      <config_id> </config_id>
      <name>New test configuration</name>
      <is_primary>true</is_primary>
      <auto_response>false</auto_response>
      <language>English</language>
      <chars_threshold>80</chars_threshold>
	  <entities_threshold>0</entities_threshold>
      <one_sentence>false</one_sentence>
      <process_html>false</process_html>
      <callback>https://anyapi.anydomain.com/processed.json</callback>
       <document>
         <pos_types>Noun,Verb,Adjective</pos_types>
         <phrases_limit>10</phrases_limit>
         <possible_phrases_limit>10</possible_phrases_limit>
         <auto_categories_limit>5</auto_categories_limit>
         <concept_topics_limit>5</concept_topics_limit>
         <query_topics_limit>5</query_topics_limit>
         <named_entities_limit>5</named_entities_limit>
         <user_entities_limit>5</user_entities_limit>
         <entity_themes_limit>5</entity_themes_limit>
         <named_mentions_limit>0</named_mentions_limit>
         <user_mentions_limit>0</user_mentions_limit>
         <named_relations_limit>0</named_relations_limit>
         <user_relations_limit>0</user_relations_limit>
         <named_opinions_limit>0</named_opinions_limit>
         <user_opinions_limit>0</user_opinions_limit>
         <themes_limit>0</themes_limit>
         <theme_mentions_limit>0</theme_mentions_limit>
         <summary_limit>0</summary_limit>
         <detect_language>true</detect_language>
      </document>
      <collection>
         <facets_limit>15</facets_limit>
         <facet_atts_limit>5</facet_atts_limit>
         <facet_mentions_limit>0</facet_mentions_limit>
         <attribute_mentions_limit>0</attribute_mentions_limit>
         <concept_topics_limit>5</concept_topics_limit>
         <query_topics_limit>5</query_topics_limit>
         <named_entities_limit>5</named_entities_limit>
         <named_mentions_limit>0</named_mentions_limit>
         <themes_limit>0</themes_limit>
         <theme_mentions_limit>0</theme_mentions_limit>
		 <user_entities_limit>0</user_entities_limit>
		 <user_mentions_limit>0</user_mentions_limit>
      </collection>
   </configuration>
</configurations>
A binary file was returned

You couldn't be authenticated

HTTP/1.0 200 Request accepted and served.
 
Suggest Edits

Cloning a configuration

This makes an exact copy of an existing configuration

 
post/configurations.[json | xml]
import semantria
session = semantria.Session(key,secret)
session.cloneConfiguration( 
  { "name" = "My new name",
    "template" = "id"
  }
)
  { "name" = "My new name",
    "template" = "id"
  }
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

template
string

enter the ID of the configuration you wish to clone

name
string

name of the new clone

 
Suggest Edits

Delete

Send a list of config IDs to be deleted

 
delete/configurations.[json | xml]
import semantria
session = semantria.Session(key, secret, use_compression = True)
session.removeConfigurations(config_id)
A binary file was returned

You couldn't be authenticated

{ 'status' : 400, 'message' : 'Configuration marked for delete does not exist.'
 
Suggest Edits

Template basics

 

Semantria comes with pre-configured templates to aid in configuration creation. A template consists of a language, API settings (such as one_sentence mode) and NLP tuning (such as pre-built query topics or sentiment phrases). Some templates are free and include basic samples of NLP tuning. Some templates are for-purchase and contain industry-specific taxonomies and sentiment dictionaries.

When creating a configuration, you can specify an ID of a template and the elements of the template will show up in the created configuration.

Templates are read-only and new templates can only be created by Semantria.

Suggest Edits

List Templates

 
get/templates.json
https://api.semantria.com/templates.json
A binary file was returned

You couldn't be authenticated

[
    {
        "auto_responding": false,
        "categories_threshold": 0.45,
        "chars_threshold": 80,
        "collection": {
            "attribute_mentions_limit": 0,
            "concept_topics_limit": 5,
            "facet_atts_limit": 5,
            "facet_mentions_limit": 0,
            "facets_limit": 15,
            "named_entities_limit": 5,
            "named_mentions_limit": 0,
            "query_topics_limit": 5,
            "theme_mentions_limit": 0,
            "themes_limit": 5,
            "user_entities_limit": 0,
            "user_mentions_limit": 0
        },
        "config_id": "0581e02fb27066ac973c182545693f3e",
        "document": {
            "auto_categories_limit": 5,
            "concept_topics_limit": 5,
            "detect_language": true,
            "entity_themes_limit": 0,
            "intentions": false,
            "model_sentiment": false,
            "named_entities_limit": 5,
            "named_mentions_limit": 0,
            "named_opinions_limit": 0,
            "named_relations_limit": 0,
            "phrases_limit": 0,
            "possible_phrases_limit": 0,
            "query_topics_limit": 5,
            "summary_limit": 3,
            "theme_mentions_limit": 0,
            "themes_limit": 5,
            "user_entities_limit": 5,
            "user_mentions_limit": 0,
            "user_opinions_limit": 0,
            "user_relations_limit": 0
        },
        "entities_threshold": 55,
        "is_primary": false,
        "language": "English",
        "modified": 0,
        "name": "default_template_config_9438637610992",
        "one_sentence": false,
        "process_html": false,
        "rights": []
    },
  {
        "auto_responding": false,
        "categories_threshold": 0.45,
        "chars_threshold": 80,
        "collection": {
            "attribute_mentions_limit": 0,
            "concept_topics_limit": 5,
            "facet_atts_limit": 5,
            "facet_mentions_limit": 0,
            "facets_limit": 15,
            "named_entities_limit": 5,
            "named_mentions_limit": 0,
            "query_topics_limit": 5,
            "theme_mentions_limit": 0,
            "themes_limit": 5,
            "user_entities_limit": 0,
            "user_mentions_limit": 0
        },
        "config_id": "cba6daae76d64cc1658593f22fa0555b",
        "document": {
            "auto_categories_limit": 5,
            "concept_topics_limit": 5,
            "detect_language": true,
            "entity_themes_limit": 0,
            "intentions": false,
            "model_sentiment": false,
            "named_entities_limit": 5,
            "named_mentions_limit": 0,
            "named_opinions_limit": 0,
            "named_relations_limit": 0,
            "phrases_limit": 0,
            "possible_phrases_limit": 0,
            "query_topics_limit": 5,
            "summary_limit": 3,
            "theme_mentions_limit": 0,
            "themes_limit": 5,
            "user_entities_limit": 5,
            "user_mentions_limit": 0,
            "user_opinions_limit": 0,
            "user_relations_limit": 0
        },
        "entities_threshold": 55,
        "is_primary": false,
        "language": "English",
        "modified": 0,
        "name": "vp: hotel, v1",
        "one_sentence": false,
        "process_html": false,
        "rights": [],
        "version": "1.3.2"
    }
]
 
Suggest Edits

Query Basics

 

You can create queries per configuration up to the limit specified in your subscription. Queries are referred to by name. Queries can be a certain number of characters long, up to the value specified in your subscription.

Suggest Edits

List queries

 
get/queries.[json | xml]
import semantria
session = semantria.Session(key, secret, use_compression = True)
session.getQueries(config_id = "id")
A binary file was returned

You couldn't be authenticated

[
   {
      "id": "ec889834-2498-4909-b90d-db93f9a06a6a", 
      "modified": 1450195636, 
      "name" : "Feature: Cloud service",
      "query" : "Amazon AND EC2 AND Cloud"
   }
]

Query Params

config_id
string

ID of configuration you wish to create queries in

 
Suggest Edits

Create Queries

Pass an object within the body of the request with a param

 
post/queries.[ json | xml]
import semantria
session = semantria.Session(key, secret, use_compression = True)
session.addQueries( 
  { 
    "name" : "Cloud Services", 
    "query" : "Amazon OR EC2 OR Cloud" 
  }, 
  config_id = "id" 
)
[
   {
      "name" : "Cloud Services",
      "query" : "Amazon OR EC2 OR Cloud"
   }
]
A binary file was returned

You couldn't be authenticated

[
    {
        "id": "3463f27c-becd-4de2-a11b-05061e040e41", 
        "modified": 1450195636, 
        "name": "Cloud Services", 
        "query": "Amazon OR EC2 OR Cloud"
    }
]
{ 'status' : 400, 'message' : 'Query "Feature: Cloud service" has an error. Error in line 1, column 4 : Syntax error Illegal character \'"<"\' found in line: line: 1, col: col: 2'
{ 'status' : 406, 'message' : 'The number of permitted queries per configuration has been reached.'
Length of query [Amazon AND (cloud OR service)] is exceeding the limit of 54 characters.

Body Params

config_id
string

ID of configuration containing queries you wish to list.

 
Suggest Edits

Update Queries

Pass a JSON-encoded object within the body of the request. A list of query, text key and value pairs. The text of the query submitted will replace an existing query.

 
put/queries.json
import semantria
session = semantria.Session(key, secret, use_compression = True)
session.updateQueries( 
  { 
    "id": "3463f27c-becd-4de2-a11b-05061e040e41",
    "name" : "Cloud Services",
    "query" : "EC2 OR \)Amazon AND cloud\)"
  }
  config_id = "id"
)
[
   {
      "id": "3463f27c-becd-4de2-a11b-05061e040e41",
      "name" : "Cloud Services",
      "query" : "EC2 OR \(Amazon AND Cloud\)"
   }
]
A binary file was returned

You couldn't be authenticated

[
    {
        "id": "3463f27c-becd-4de2-a11b-05061e040e41", 
        "modified": 1450195965, 
        "name": "Cloud Services", 
        "query": "EC2 OR \(Amazon AND Cloud\)"
    }
]

Body Params

config_id
string

ID of configuration containing queries you wish to update

 
Suggest Edits

Delete Queries

 
delete/queries.json
import semantria
session = semantria.Session(key, secret, use_compression = True)
session.removeQueries(["85d14f37-cee6-4e28-9a1d-5bb698adcfd6"], config_id = "id")
[
   "85d14f37-cee6-4e28-9a1d-5bb698adcfd6"
]
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

config_id
string

ID of the configuration holding the queries

 
Suggest Edits

Category Basics

 

You can create categories per configuration up to the limit of categories specified in your subscription. Categories are referred to by name. Categories have three values - name, weight and samples.

Suggest Edits

List Categories

 
get/categories.[json | xml]
import semantria
session = semantria.Session(key, secret, use_compression=True )
session.getCategories( config_id = "id" )
A binary file was returned

You couldn't be authenticated

[
   {
      "name" : "Feature: Cloud service",
      "weight" : 0.75,
      "samples" : [ "Amazon" , "EC2" ]
   }
 ]

Query Params

config_id
string

ID of configuration you want to list categories for

 
Suggest Edits

Create Categories

 
post/categories.[json | xml]
import semantria
session = semantria.Session(key, secret, use_compression=True )
session.addCategories( 
  {
    "name" : "Food",
    "weight" : 1,
    "samples" : "food, restaurant"
  }
  config_id = "id"
)
[  
{
    "name" : "Food",
    "weight" : 1,
    "samples" : ["food", "restaurant"]
}
]
A binary file was returned

You couldn't be authenticated

[
    {
        "id": "b09933f2-d274-4711-8ff5-2d994ce41c5a", 
        "modified": 1450197417, 
        "name": "Food", 
        "samples": [
            "food", 
            "restaurant"
        ], 
        "weight": 1.0
    }
]

Body Params

config_id
string

ID of the configuration you wish to create categories in

 
Suggest Edits

Update Categories

 
put/categories.[json | xml]
import semantria
session = semantria.Session(key, secret, use_compression=True )
session.updateCategories( 
  {
    "id":"b09933f2-d274-4711-8ff5-2d994ce41c5a",
    "name" : "Food",
    "weight" : 1,
    "samples" : "food, restaurant, wine"
  },
  config_id = "id"
)
[
  {
    "id":"b09933f2-d274-4711-8ff5-2d994ce41c5a",
    "name" : "Food",
    "weight" : 1,
    "samples" : ["food", "restaurant", "wine"]
  }
]
A binary file was returned

You couldn't be authenticated

[
    {
        "id": "b09933f2-d274-4711-8ff5-2d994ce41c5a", 
        "modified": 1450197726, 
        "name": "Food", 
        "samples": [
            "food", 
            "restaurant", 
            "wine"
        ], 
        "weight": 1.0
    }
]

Body Params

config_id
string

ID of the configuration you wish to update categories in

 
Suggest Edits

Delete Categories

Send a list of categories names to be deleted.

 
delete/categories.[json | xml]
import semantria
session = semantria.Session(key, secret, use_compression=True )
session.removeCategories( 
[ "85d14f37-cee6-4e28-9a1d-5bb698adcfd6" ],
  config_id = "id"
  )
[
"85d14f37-cee6-4e28-9a1d-5bb698adcfd6"
]
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

config_id
string

ID of the configuration you wish to update categories in

 
Suggest Edits

Taxonomy basics

Taxonomies provide a way to hierarchically arrange queries and categories in a single structure

 

Taxonomies are supported in version 4.0 and later of Semantria.

You can create one taxonomy per configuration. By default, the taxonomy can be five levels deep and contain up to the number of queries and categories allowed per config in your license.

A taxonomy node has three values - a name, an id, and whether parent matching should be enforced. The ID is set by the API when the node is created.

If enforce_parent_matching is set to true for a node, then the node will only be returned if the parent node also matches. For example, if you have:

Pets (node)

Q Pets: pet OR domestic
Dogs (node)

Q Dog: dog

and enforce_parent_matching is set to True for the node Dogs, then this document will match:

I have a pet dog

While this document:

I want a hot dog

will NOT match.

Queries and categories associated with a node must exist already in your configuration. A taxonomy is just a way of arranging these resources.

Suggest Edits

List Taxonomy

Lists the existing taxonomy structure for a given config.

 
get/taxonomy.json
import semantria
session = semantria.Session(key, secret, use_compression = True)
session.getTaxonomy(config_id = "id")
http://api.semantria.com/taxonomy.json&config_id=123
A binary file was returned

You couldn't be authenticated

[
    {
        "id": "a33ba9e0-f720-436d-833f-f8f4babe5600",
        "name": "Taste",
        "timestamp": 1441745387,
        "topics": [
            {
                "id": "a2661d73-f5f8-4c1e-8a11-a154507ac494",
                "type": "query"
            },
            {
                "id": "a8652ec0-c32b-4f09-aec5-1d652813317a",
                "type": "query"
            }
        ]
    }
]

Query Params

config_id
string

Id of config to list taxonomy for

 
Suggest Edits

Create Taxonomy

Crete a new taxonomy in a given config. Each config can have only one taxonomy defined.

 
post/taxonomy.json
import semantria
session = semantria.Session(key, secret, use_compression = True)
session.addTaxonomy( config_id = "id",
[
	{
		"name":"My Taxonomy",
		"nodes": [
			{
				"name":"Sample Node",
				"topics": [
					{
					"id": "607ce795-291f-4dd4-8745-8039f5c40b72",
					"type": "query"
					}
         ]
       }
     ]
   }
]
                    )
[
	{
		"name":"My Taxonomy",
		"nodes": [
			{
				"name":"Sample Node",
				"topics": [
					{
					"id": "607ce795-291f-4dd4-8745-8039f5c40b72",
					"type": "query"
					}
         ]
       }
     ]
   }
]
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

config_id
string

ID of config to create the taxonomy in

 
Suggest Edits

Update Taxonomy

To add nodes, or add topics to nodes, specify the relationship in the JSON you submit. You must refer to existing topics and nodes by their ID.

 
put/taxonomy.json
import semantria
session = semantria.Session(key, secret, use_compression = True)
session.updateTaxonomy( config_id = "id",
[{"id":"5a543ba8-cd7d-4af6-b69f-c99e0836de77", 
"topics":[
		{
			"id":"3fc7692e-996c-421a-a046-c8e2ff314e26", 
			"type":"QUERY"
		}]
}]
                       )
[{"id":"5a543ba8-cd7d-4af6-b69f-c99e0836de77", 
"topics":[
		{
			"id":"3fc7692e-996c-421a-a046-c8e2ff314e26", 
			"type":"QUERY"
		}]
}]
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

config_id
string

ID of config with taxonomy to update

 
Suggest Edits

Delete Taxonomy

 
delete/taxonomy.json
import semantria
session = semantria.Session(key, secret, use_compression = True)
session.deleteTaxonomy( config_id = "id")
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

config_id
string

ID of config to delete from

 
Suggest Edits

Sentiment Basics

 

Sentiment phrases can be up to three words in length, and have a weight of -2 to 2. Sentiment phrases can contain query operators and use the same syntax as regular Semantria query categories.

The sentiment of the phrase can be negated (ex: not good) or intensified (ex: very good). Semantria output will list which phrases were negated and intensified along with the negator or intensifier.

In addition, if you have mentions enabled in your configuration, you will receive the offset and byte length of each phrase.

Suggest Edits

List sentiment phrases

 
get/phrases.json
import semantria
session = semantria.Session(key, secret, use_compression=True )
session.getPhrases( config_id="id" )
A binary file was returned

You couldn't be authenticated

[
   {
      "id": "bd91d796-4ff2-41cf-9954-08c23a8ab239", 
      "modified": 1450197726,
      "name" : "excellent service",
      "weight" : 0.8
   }
]

Query Params

config_id
string

ID of configuration you wish to list sentiment phrases for

 
Suggest Edits

Create sentiment phrases

 
post/phrases.json
import semantria
session = semantria.Session(key, secret, use_compression=True )
session.addPhrases(
   {
      "name" : "excellent service",
      "weight" : 0.8
   },
  config_id = "id"
)
[
  {
			  "name": "excellent service", 
        "weight": 0.8
    }
]
A binary file was returned

You couldn't be authenticated

[
    {
        "id": "b7150c19-ed58-44f7-9801-9f70d15e375a", 
        "modified": 1450197978, 
        "name": "excellent service", 
        "weight": 0.8
    }
]

Body Params

config_id
string

ID of configuration you wish to list sentiment phrases for

 
Suggest Edits

Update sentiment phrases

 
put/phrases.json
import semantria
session = semantria.Session(key, secret, use_compression=True )
session.updatePhrases(
   {
      "id": "b7150c19-ed58-44f7-9801-9f70d15e375a",
      "name" : "excellent service",
      "weight" : 0.8
   },
  config_id = "id"
)
[
    {
        "id": "b7150c19-ed58-44f7-9801-9f70d15e375a", 
        "name": "excellent service", 
        "weight": 0.8
    }
]
A binary file was returned

You couldn't be authenticated

[
    {
        "id": "b7150c19-ed58-44f7-9801-9f70d15e375a", 
        "modified": 1450197978, 
        "name": "bad dates", 
        "weight": -0.6
    }
]

Body Params

config_id
string

ID of configuration you wish to update sentiment phrases for

 
Suggest Edits

Delete sentiment phrases

 
delete/phrases.[json | xml]
import semantria
session = semantria.Session(key, secret, use_compression=True )
session.removePhrases(
	[
  	"85d14f37-cee6-4e28-9a1d-5bb698adcfd6"
	],
  config_id = "id"
)
[
  "85d14f37-cee6-4e28-9a1d-5bb698adcfd6"
]
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

config_id
string

ID of configuration you wish to delete sentiment phrases for

 
Suggest Edits

Entity Basics

 

You can create entities up to the limit specified by your subscription. Entities have four values - name, type, label and normalized value. The name of the entity can contain a Boolean query. If it contains a query, you must preface the query definition with a + sign.

You can use these outputs to create a simple entity taxonomy. For example:

name: coke OR "coca cola"
Type: Soda
Label: Coke Products
Normalized: Coca-Cola

name: Fanta
Type: Soda
Label: Coke Products
Normalized: Fanta

name: Pepsi
Type: Soda
Label: Pepsi Products
Normalized: Pepsi-Cola

Entities also come with their own sentiment and themes. For longer content, this allows you to focus on the sentiment associated with individual brands instead of the document as a whole.

In addition, if you have mentions enabled in your configuration, you will receive the offset and byte length of each individual mention of an entity.

Suggest Edits

List Entities

 
get/entities.json
import semantria
session = semantria.Session(key, secret, use_compression=True )
session.getEntities( config_id = "id")
A binary file was returned

You couldn't be authenticated

[
   {
      "id": "68d6046b-e94e-4a1d-9d69-005bfdaea5a7",
      "modified": 0,
      "name" : "\"club chair\" OR \"task chair\" OR \"reclining chair\",
      "type" : "furniture",
      "label" : "http://en.wikipedia.org/wiki/Chair",
      "normalized" : "chair"
   }
]

Query Params

config_id
string

ID of configuration you wish to list entities for

 
Suggest Edits

Create Entities

 
post/entities.json
import semantria
session = semantria.Session(key, secret)
session.addEntities(
  config_id = "id",
  [
   {
      "name" : "\"club chair\" OR \"task chair\" OR \"reclining chair\",
      "type" : "furniture",
      "label" : "http://en.wikipedia.org/wiki/Chair",
      "normalized" : "chair"
   }
]
[
   {
      "name" : "\"club chair\" OR \"task chair\" OR \"reclining chair\",
      "type" : "furniture",
      "label" : "http://en.wikipedia.org/wiki/Chair",
      "normalized" : "chair"
   }
]
A binary file was returned

You couldn't be authenticated

[
   {
      "id": "68d6046b-e94e-4a1d-9d69-005bfdaea5a7",
      "name" : "\"club chair\" OR \"task chair\" OR \"reclining chair\",
      "type" : "furniture",
      "label" : "http://en.wikipedia.org/wiki/Chair",
      "modified": 0,
      "normalized" : "chair"
   }
]

Body Params

config_id
string

ID of configuration you wish to list entities for

 
Suggest Edits

Update Entities

 
put/entities.json
import semantria
session = semantria.Session(key, secret)
session.updateEntities(
  config_id = "id",
  [
   {
      "id": "68d6046b-e94e-4a1d-9d69-005bfdaea5a7",
      "name" : "\"club chair\" OR \"task chair\" OR \"reclining chair\",,
      "type" : "furniture",
      "label" : "http://en.wikipedia.org/wiki/Chair",
      "normalized" : "chair"
   }
]
https://api.semantria.com/entities.json?config_id=id
[
   {
      "name" : "\"club chair\" OR \"task chair\" OR \"reclining chair\",
      "type" : "furniture",
      "label" : "http://en.wikipedia.org/wiki/Chair",
      "normalized" : "chair"
   }
]
A binary file was returned

You couldn't be authenticated

  [
   {
      "id": "68d6046b-e94e-4a1d-9d69-005bfdaea5a7",
      "name" : "\"club chair\" OR \"task chair\" OR \"reclining chair\",,
      "type" : "furniture",
      "label" : "http://en.wikipedia.org/wiki/Chair",
      "modified": 1450197417, 
      "normalized" : "chair"
   }
]

Body Params

config_id
string

ID of configuration you wish to list entities for

 
Suggest Edits

Delete Entities

 
delete/entities.[json | xml]
import semantria
session = semantria.Session(key, secret)
session.removeEntities(
  config_id = "id",
  [
		"b09933f2-d274-4711-8ff5-2d994ce41c5a"
	]
)
[
 "b09933f2-d274-4711-8ff5-2d994ce41c5a"
]
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

config_id
string
 
Suggest Edits

Blacklist Basics

 

You can add as many terms to your blacklist as specified in your configuration. Blacklist items are referred to by name and are configuration-specific.

Suggest Edits

List Blacklist

 
get/blacklist.json
import semantria
session = semantria.Session(key, secret)
session.getBlacklist(
  config_id = "id"
)
https://api.semantria.com/blacklist.json?config_id="id"
A binary file was returned

You couldn't be authenticated

[
    {
        "id": "2a7d539a-bf21-470f-b522-06c10fb3b9b6", 
        "modified": 0, 
        "name": "next quarter"
    }
]

Query Params

config_id
string

Id of config you wish to see blacklist items for

 
Suggest Edits

Create Blacklist item

 
post/blacklist.json
import semantria
session = semantria.Session(key, secret)
session.addBlacklist(
  config_id = "id",
  [
    "quarter",
    "year"
  ]
)
[
	"quarter",
  "year"
]
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

config_id
string

Id of config you wish to see blacklist items for

 
Suggest Edits

Update Blacklist item

 
put/blacklist.json
import semantria
session = semantria.Session(key, secret)
session.updateBlacklist(
  config_id = "id",
  [
    "chair",
    "sofa"
]
https://api.semantria.com/blacklist.json&config_id="id"
[
   ".*@.*com",
   ".*@com\\.net",
   "http://www\\..*\\.com"
]
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

config_id
string

Id of config you wish to see blacklist items for

 
Suggest Edits

Delete Blacklist item

 
delete/blacklist.[json | xml]
import semantria
session = semantria.Session(key, secret)
session.removeBlacklist(
  config_id="id",
  [
    "chair",
    "sofa"
	]
)
https://api.semantria.com/blacklist.json&config_id="id"
[
   ".*@.*com",
   ".*@com\\.net",
   "http://www\\..*\\.com"
]
A binary file was returned

You couldn't be authenticated

Try the API to see results

Body Params

config_id
string

Id of config you wish to see blacklist items for

 
Suggest Edits

Account Management Basics

 

Semantria has graphical tools for looking at your account, such as the billing dashboard and SWEB. Those tools use these API endpoints.

The subscription endpoint returns the list of your account settings and limits as well as a list of all your configurations. This endpoint lists what features you have access to, not what features will be returned in the output. To see what features are enabled for output for a specific configuration, use the configuration endpoint.

The features endpoint returns all supported features for each language Semantria supports. Not all features might be enabled for your account, so this list might be different than what is returned by the subscription endpoint.

The statistics endpoint returns statistics about your account, such as the number of calls made, documents processed, and so on. Statistics also takes several parameters to allow you to specify the interval of time you wish to report on.

The status endpoint returns the current status of the API itself as well as version and languages.

Suggest Edits

Authentication

Authentication answers, "Are you a registered user?" through the following algorithm.

 

Note that our SDKs provide functions to take care of this for you. This is only to demonstrate what you need to do if you want to implement your own Semantria authentication code.

Authentication Algorithm

  1. Obtain User Key and Secret (we emailed it to you when you registered with Semantria. Check your junk folder if you can't find it!)
  2. Generate signature base string (with URL)
  3. Generate OAuth signature for URL
    • Encode signature base string with UTF-8 encoding. Keep encoded symbols in upper case.
    • Calculate MD5 using secret key and use it in lower case.
    • Convert signature base string and MD5 hash code of the secret into byte representations.
    • Encrypt bytes of signature base string with MD5 hash code using HMAC-SHA1 algorithm.
    • Convert result back into string form using Base64 algorithm and UTF-8 encoding.
    • Encode string with URL encoding algorithm and write as oauth_signature parameter.
  4. Create Authorization Header as shown below. Note the single Authorization HTTP header with parameters separated by commas.
  5. Combine URL and header into the request and use it for authorization for the Semantria API.

Authorization

Authorization determines whether users are allowed to do certain actions.

The Semantria API authorization model allows organized access to the API after the user is authenticated. After the user passes authentication, the Semantria authorization model allows or denies access to the user based on the user's subscription limits, account balance, account limits, configuration limits, and account expiration. If you're experiencing issues, please contact support-- they will be happy to help you out.

Authorization Header

The authentication mechanism requires a signature base string. The base string is a combination of the complete URL pertaining to the shared endpoint and certain parameters: oauth_consumer_key, a public key; oauth_nonce, a random 64-bit unsigned ASCII decimal string; oauth_signature_method, any one-way algorithm to hash URL (e.g. HMAC-SHA1); oauth_timestamp, the current time stamp in numeric form; and oauth_version, OAuth version 1.0. Add these parameters to any request URL for the Semantria API.

The target URL for retrieving the document status with signature parameters will look like this:

https://api.semantria.com/document/Q24FT98RWX45.json?oauth_consumer_key=b36eab90ec7dcd8d&
oauth_nonce=8e9a56a4c2cf47f&
oauth_signature_method= HMAC-SHA1&
oauth_timestamp=1272323042&
oauth_version=1.0

Signature base strings will be encoded with an HMAC-SHA1 hash algorithm using the MD5 checksum of the secret key. The generated hash function should be URL encoded and added as an “oauth_signature” parameter for the authorization header.

Only the license-holder and Semantria know the MD5 checksum of the secret key. Both parties can generate hash functions from the signature base string. The server runs the same process and compares the results with the hash function generated by the server's secret key. The server identifies clients with an “oauth_consumer_key” parameter in the header.

The URL encoding function must be in UTF-8 upper case hexadecimal format.

The complete authorization header will look like this:

https://api.semantria.com/subscription.json?oauth_consumer_key=XXXXX&
oauth_nonce=3931596951957366614&
oauth_signature_method=HMAC-SHA1&
oauth_timestamp=1320143435&
oauth_version=1.0

Authorization: OAuth realm=““,
   oauth_consumer_key=“XXXXX”,
   oauth_nonce=“3931596951957366614”,
   oauth_signature=“PSILFVnqdp8Nl8PpwtF%2fxeguuAQ%3d”,
   oauth_signature_method=“HMAC-SHA1”,
   oauth_timestamp=“1320143435”,
   oauth_version=“1.0”“
Suggest Edits

Subscription

The subscription endpoint allows you to see what your subscription is entitled to use in Semantria.

 
get/subscription.[ json | xml ]
import semantria
session = semantria.Session(key, secret)
session.getSubscription()
A binary file was returned

You couldn't be authenticated

{
  "name": "tim.mohler@lexalytics.com",
  "status": "active",
  "billing_settings": {
    "data_calls_limit": 10,
    "settings_calls_limit": 10,
    "polling_calls_limit": 10,
    "data_calls_limit_interval": 1,
    "settings_calls_limit_interval": 1,
    "polling_calls_limit_interval": 1,
    "docs_balance": 797674,
    "settings_calls_balance": 9,
    "polling_calls_balance": 10,
    "data_calls_balance": 10,
    "expiration_date": 1456358400000,
    "limit_type": "metered",
    "docs_suggested" : 0,
    "docs_suggsted_interval" : 0,
    "job_ids_allocated": 0, 
    "job_ids_permitted": 10,
    "app_seats_permitted": 10,
    "app_seats_allocated": 8
  },
  "basic_settings": {
    "collection_limit": 1000,
    "auto_response_batch_limit": 2,
    "configurations_limit": 100,
    "concept_topics_limit": 100,
    "query_topics_limit": 1000,
    "user_entities_limit": 1000,
    "callback_batch_limit": 100,
    "concept_topic_samples_limit": 20,
    "return_source_text": false,
    "characters_limit": 1024000,
    "blacklist_limit": 100,
    "sentiment_phrases_limit": 1000,
    "incoming_batch_limit": 100,
    "document_length" : 2048,
    "polling_batch_limit": 100,
    "summary_size_limit": 100
  },
  "feature_settings": {
    "document": {
      "concept_topics": true,
      "query_topics": true,
      "sentiment_phrases": true,
      "user_entities": true,
      "intentions": true,
      "model_sentiment": true,
      "language_detection": true,
      "named_entities": true,
      "pos_tagging": true,
      "summary": true,
      "themes": true,
      "relations": true,
      "mentions": true,
      "opinions": true,
      "auto_categories": true
    },
    "collection": {
      "concept_topics": true,
      "query_topics": true,
      "user_entities": true,
      "named_entities": true,
      "themes": true,
      "mentions": false,
      "facets": true
    },
    "html_processing": true,
    "supported_languages": "Chinese, English, French, German, Portuguese, Spanish, Italian, Korean, Arabic, Russian, Malay, Japanese, Dutch, Swedish, Norwegian, Danish"
  }
 "templates": [
            {
                "config_id": "0581e02fb27066ac973c182545693f3e", 
                "id": "def_template_id_9438637610992", 
                "is_free": true, 
                "language": "English", 
                "name": "default_template_9438637610992", 
                "type": "language-default",
  	            "version" : 1
            }, 
            {
                "config_id": "625d64573c164bccad4631aa6349ac2d", 
                "id": "default-es", 
                "is_free": true, 
                "language": "es", 
                "name": "Spanish samples", 
                "type": "language-default", 
                "version": "1"
            }, 
            {
                "config_id": "4182936a494de53e3c13ce1feab70fdc", 
                "id": "default-fr", 
                "is_free": true, 
                "language": "fr", 
                "name": "French samples", 
                "type": "language-default", 
                "version": "1"
            }, 
            {
                "config_id": "7d265f1cda6fdb90d6ad7c72a873e890", 
                "id": "default-en", 
                "is_free": true, 
                "language": "en", 
                "name": "English samples", 
                "type": "language-default", 
                "version": "1"
            }, 
            {
                "config_id": "cba6daae76d64cc1658593f22fa0555b", 
                "id": "vp-en-hotel-1", 
                "is_free": false, 
                "language": "en", 
                "name": "Hotel", 
                "type": "vertical-pack", 
                "version": "1"
            }
        ]
    }, 
}
 
Suggest Edits

Features

This method returns a list of the supported features per languages supported by the Semantria API. The language parameter is optional and if not included, the endpoint will return features for every supported language to which you have access.

 
gethttps://api.semantria.com:443/features.json?
import semantria
session = semantria.Session(key, secret)
session.getSupportedFeatures()
GET https://api.semantria.com:443/features.json?language=en
A binary file was returned

You couldn't be authenticated

[
  {
	"id": "en",
	"language": "English",
	"html_processing": true,
	"settings": {
	  "blacklist": true,
	  "user_entities": true,
	  "sentiment_phrases": true,
	  "concept_topics": true,
	  "query_topics": true
	},
	"detailed_mode": {
	  "language_detection": true,
	  "pos_tagging": true,
	  "intentions": true,
	  "mentions": true,
	  "sentiment_phrases": true,
	  "themes": true,
	  "relations": true,
	  "named_entities": true,
	  "sentiment": true,
	  "summarization": true,
	  "user_entities": true,
	  "query_topics": true,
	  "auto_categories": true,
	  "concept_topics": true,
	  "opinions": true
	},
	"discovery_mode": {
	  "named_entities": true,
	  "mentions": true,
	  "facets": true,
	  "user_entities": true,
	  "concept_topics": true,
	  "themes": true,
	  "query_topics": true,
	  "attributes": true
	}
  }
]
<supported_features>
  <features>
	<detailed_mode>
	  <language_detection>true</language_detection>
	  <pos_tagging>true</pos_tagging>
	  <intentions>true</intentions>
	  <theme_mentions>true</theme_mentions>
	  <sentiment_phrases>true</sentiment_phrases>
	  <entity_themes>true</entity_themes>
	  <themes>true</themes>
	  <entity_relations>true</entity_relations>
	  <named_entities>true</named_entities>
	  <sentiment>true</sentiment>
	  <entity_mentions>true</entity_mentions>
	  <summarization>true</summarization>
	  <user_entities>true</user_entities>
	  <queries>true</queries>
	  <auto_categories>true</auto_categories>
	  <user_categories>true</user_categories>
	  <entity_opinions>true</entity_opinions>
	</detailed_mode>
	<discovery_mode>
	  <named_entities>true</named_entities>
	  <entity_mentions>true</entity_mentions>
	  <facet_mentioins>true</facet_mentioins>
	  <facets>true</facets>
	  <user_entities>true</user_entities>
	  <theme_mentions>true</theme_mentions>
	  <user_categories>true</user_categories>
	  <themes>true</themes>
	  <queries>true</queries>
	  <facet_attributes>true</facet_attributes>
	</discovery_mode>
	<html_processing>true</html_processing>
	<id>en</id>
	<language>English</language>
	<settings>
	  <blacklist>true</blacklist>
	  <user_entities>true</user_entities>
	  <sentiment_phrases>true</sentiment_phrases>
	  <user_categories>true</user_categories>
	  <queries>true</queries>
	</settings>
  </features>
</supported_features>

Query Params

language
array of strings

The language parameter is entered as an ISO language code. It is optional and may be skipped. If no parameter is passed, Semantria will respond with a list of supported features, organized by language.

 
Suggest Edits

Statistics

Returns interval usage statistics over a date range, filtered and grouped by various options. All requests need to specify the date range with either the "interval" parameter or the "from" and "to" parameters.

From and to parameters take either UNIX epoch time or ISO formats. Interval specifies the current internal. For an interval of "day" for example, the current day will be used, and for an interval of "month" use the current month. Interval and From/To are exclusive.

 
get/statistics.json
import semantria
session = semantria.Session(key, secret)
session.getStatistics(config_id = "id", interval="week")
#Statistics for entire account for a date range
https://api.semantria.com/statistics.json?from=2016-01-01T00:00:00Z&to=2016-01-25T00:00:00Z
#Statistics for entire account for one day
https://api.semantria.com/statistics.json?interval=day
#Statistics for a single configuration for one day
https://api.semantria.com/statistics.json?interval=day&config=9f12650909332cf0389e27854d05bd75
#Statistics for entire account for one day, grouped by config, app, language per hour
https://api.semantria.com/statistics.json?interval=day&group=config,app,language,1h
A binary file was returned

You couldn't be authenticated

#Simple example from statistics?interval=week
[
    {
#Number of batches queued in the time range
        "batches_queued": 24,
#Number of data calls in the time range
        "calls_data": 24,
#Number of polling calls in the time range
        "calls_polling": 208,
#Number of settings calls in the time range
        "calls_settings": 6,
#Name of the account
        "consumer_name": "test.user@lexalytics.com",
#Number of docs that failed in the interval
        "docs_failed": 296,
#Number of docs queued in the interval
        "docs_queued": 2080,
#Last application used to access Semantria
        "latest_used_app": "Python/3.8.77/JSON",
#Total number of API calls over the interval
        "total_api_calls": 238
    }
]
#https://api.semantria/com/statistics?interval=day&group=config,6h
[
#One structure for each grouped element, in this case config
  {
        "config_id": "01b71c5e66eddef4132fa1c8e29a6327",
        "config_name": "chinese",
        "consumer_name": "test.user@lexalytics.com",
        "values": [
#One entry for each 6 hour range in the day
            {
                "batches_queued": 0,
                "calls_data": 0,
                "calls_polling": 0,
                "calls_settings": 0,
                "docs_failed": 0,
                "docs_queued": 0,
                "docs_retrieved": 0,
                "docs_successful": 0,
#Start time of the 6 hour interval
                "time": 1467849600000,
                "total_api_calls": 0
            },
            {
                "batches_queued": 0,
                "calls_data": 0,
                "calls_polling": 0,
                "calls_settings": 0,
                "docs_failed": 0,
                "docs_queued": 0,
                "docs_retrieved": 0,
                "docs_successful": 0,
                "time": 1467871200000,
                "total_api_calls": 0
            },
            {
                "batches_queued": 0,
                "calls_data": 0,
                "calls_polling": 1,
                "calls_settings": 0,
                "docs_failed": 0,
                "docs_queued": 0,
                "docs_retrieved": 0,
                "docs_successful": 0,
                "time": 1467892800000,
                "total_api_calls": 1
            },
            {
                "batches_queued": 0,
                "calls_data": 0,
                "calls_polling": 0,
                "calls_settings": 0,
                "docs_failed": 0,
                "docs_queued": 0,
                "docs_retrieved": 0,
                "docs_successful": 0,
                "time": 1467914400000,
                "total_api_calls": 0
            }
        ]
    },
    {
        "config_id": "41672c786059f8f189ed850894063108",
        "config_name": "portuguese model",
        "consumer_name": "test.user@lexalytics.com",
        "values": [
            {
                "batches_queued": 0,
                "calls_data": 0,
                "calls_polling": 0,
                "calls_settings": 0,
                "docs_failed": 0,
                "docs_queued": 0,
                "docs_retrieved": 0,
                "docs_successful": 0,
                "time": 1467849600000,
                "total_api_calls": 0
            },
            {
                "batches_queued": 0,
                "calls_data": 0,
                "calls_polling": 0,
                "calls_settings": 0,
                "docs_failed": 0,
                "docs_queued": 0,
                "docs_retrieved": 0,
                "docs_successful": 0,
                "time": 1467871200000,
                "total_api_calls": 0
            },
            {
                "batches_queued": 0,
                "calls_data": 0,
                "calls_polling": 1,
                "calls_settings": 0,
                "docs_failed": 0,
                "docs_queued": 0,
                "docs_retrieved": 0,
                "docs_successful": 0,
                "time": 1467892800000,
                "total_api_calls": 1
            },
            {
                "batches_queued": 0,
                "calls_data": 0,
                "calls_polling": 0,
                "calls_settings": 0,
                "docs_failed": 0,
                "docs_queued": 0,
                "docs_retrieved": 0,
                "docs_successful": 0,
                "time": 1467914400000,
                "total_api_calls": 0
            }
        ]
    }
  ]

Query Params

interval
string
required

(Required if no using from/to) Hour, Day, Week, Month, Year values are supported.

from
string
required

(Required if not using interval) Start time for statistics, provided in UNIX epoch or ISO date format

to
string
required

Ending time rate in UNIX epoch or ISO date format

config_id
string

Optional config to limit output, specified by ID

config_name
string

Optional config to limit output, specified by name

group
string

config, language, app, user, time intervals in ‘(0-9){1,2}(m|h|d) format

user_id
string

Optional, limits output to just the user_id specified

user_email
string

Optional, limits output to just the user email specified

app
string

Optional, limits output to just the app specified (Excel, API, etc)

 
Suggest Edits

API Status

 
get/status.json
import semantria
session = semantria.Session(key, secret)
session.getStatus()
A binary file was returned

You couldn't be authenticated

[
 {
   'api_version':  3.9,
        'service_status':  'available',
        'service_version':  '3.9.2',
        'supported_compression':  'gzip,deflate',
        'supported_encoding':  'UTF-8',
        'supported_languages':  ['English', 'French', 'Spanish', 'Portuguese', 'German',         'Chinese', 'Italian', 'Korean', 'Japanese', 'Malay', 'Arabic Premium', 'Arabic', 'Russian Premium', 'Russian', 'Dutch', 'Swedish', 'Norwegian', 'Danish', 'Turkish Premium', 'Polish Premium']
 }
]
 

Looking to integrate? Semantria's HTTP API wrappers are the most convenient way to access the Semantria API on your favorite framework. We support Java, .NET, PHP, Python, Ruby, and node.js. Our SDK libraries include Authentication, Session Manager, Serializer, Detailed analysis test app and Discovery analysis test app.

If you make an SDK for a language we don't have yet, send it to us! We will happily give you data-processing credit in return.

Semantria SDKs are also on GitHub.

Java

37 KB

.NET

93 KB

PHP

16 KB

Python

32 KB

Ruby

15 KB

JavaScript

18 KB

Node.js

153 KB

Suggest Edits

API Limits

Semantria comes with default values and limits for most features. The user can change many limits on their end-- check the Basic Mode and Discovery Mode Quick References for those-- but other limits must be changed upon request. This section details Semantria API's default limits, additional features, and license expiration.

 

Transactions

Transactions are the number of documents (tweets, articles, etc) you send to the API for analysis. Examples:

  • 100 articles = 100 transactions
  • 300 tweets = 300 transactions

Different accounts have different transaction limits. To view your number of available transactions, go to the Dashboard.

Limits

The limits listed below are for the Starter edition. Each configuration has default limits on analysis settings that can be modified by request. To make changes to any limits, do not hesitate to email us.

Character limits

Any character limits listed below refer to single byte characters.

Number of configurations per account

varies

Names of blacklists, configurations, categories, SBPs, entities

50 characters

Number of blacklisted items

100

Number of categories

100

Number of samples per category

20

Number of entities

1000

Number of queries

100

Query text character count

1500 characters

NEAR count per query

5

NEAR operator distance

10

Number of sentiment-bearing phrases

1000

Document ID character count

36 characters

Max document size

2048 characters

Max incoming/outgoing batch size (Detailed Mode)

100 documents / batch

Max analysis size (Discovery Mode)

1000 documents / analysis

Data calls (calls which POST data to Semantria)

10 calls/second

Settings Calls (calls which alter your configuration settings)

10 calls/second

Polling Calls (calls GET'ing processed data)

10 calls/second

Suggest Edits

Security Model

 

Semantria uses a signature algorithm for sending requests. There is a set of an API key and secret as authenticators for each license. Other web services like Amazon Web Services, XML Digital Signatures and OAuth also use these to authenticate. Authentication occurs every time the user sends a request to the Semantria API.

  • Semantria uses a cryptographic hash function with a customer key and secret to create a signature for each request.
  • All incoming and outgoing data passes through a secure HTTPS connection with a 256-bit SSL encryption and is encrypted at all times.
  • Semantria protects the user from credential theft by storing a unique token generated from the real keys instead of storing the user's key and secret. The client-side application uses the authenticators to generate and pass this unique token for authorization.
  • Any data sent to the server or processed results are removed 24 hours after it has been generated (so do not use Semantria as a server for storing data).
  • Once a user registers and receives his keys, Semantria does not have access to the keys anymore. We have no way of resending the keys and no way of accessing the account using the keys; this keeps everything secure. Semantria can only verify whether keys are valid.
  • Users can regenerate their keys via the Semantria Dashboard.
Suggest Edits

Detailed API Output Explanation

 

Detailed Mode Output

Detailed Mode performs analysis on individual documents. In the Semantria API the user can customize almost every part of the analysis; from constraining the number of results for each category to defining the parts of speech which the server will detect, the user can configure Detailed Mode to suit your needs in document sentiment analysis. In this section, we provide a quick reference for customizable options and parameters for POS tagging, as well as a detailed explanation of Detailed Mode's output.

Line-by-line Term Explanation

This output is from analyzing the text below. Take note that it has been abbreviated is some spots for clarity.

Recently a toy catalog went out. If you did not get one you are SOL. I just called the corporate and they were mailed at random and put only in certain news papers. You can not get them at the store or ask corporate to send you one. There were some really good coupons like this week 25% off one toy. There was a different coupon each week. I think that this is so wrong. I for one have a target card just for Christmas shopping and would have loved those coupons. And since I have a card I would think a catalog should have been sent to me. Guess who will not be shopping at Target this year!

{
	# This array shows all the auto categories (wikipedia categories) found in the text
	"auto_categories": [{ 
			# These are the categories within the auto category. Note that not all auto categories will have categories
			"categories": [{
					"sentiment_polarity": "neutral",
					"sentiment_score": 0.4875,
					"strength_score": 0.5772358,
					"title": "Bonds",
					"type": "info"
				}, {
					"sentiment_polarity": "neutral",
					"sentiment_score": 0.4875,
					"strength_score": 0.523945,
					"title": "Discount_stores",
					"type": "info"
				}, {
					"sentiment_polarity": "neutral",
					"sentiment_score": 0.4875,
					"strength_score": 0.5088412,
					"title": "Government_bonds",
					"type": "info"
				}, {
					"sentiment_polarity": "neutral",
					"sentiment_score": 0.4875,
					"strength_score": 0.46849313,
					"title": "Private_currencies",
					"type": "info"
				}
			],
			# This is the sentiment polarity for the auto category
			"sentiment_polarity": "neutral",
			# This is the sentiment score for the auto category
			"sentiment_score": 0.4875,
			# This is the relevance score for the auto category
			"strength_score": 0.8387881,
			# This is the title of the auto category
			"title": "Business",
			# This is the type of auto category - node for a category that can contain other categories (as this example does), leaf for categories at the end of the tree
			"type": "node"
		}
	],
	# This is the ID of the config used to process the data
	"config_id": "486e1e63-2748-4a38-a457-862d92219fec",
	# This array give the details of the document. Each element in the array is a sentence. Only a single sentence from the example text is shown here due to length. 
	"details": [{
			# If the sentence is imperative or not
			"is_imperative": false,
			# If the sentence should carry sentiment
			"is_polar": true,
			# This array lists all of the words in the sentence
			"words": [{
					# Was the word negated by a negator
					"is_negated": false,
					# Sentiment score for the word
					"sentiment_score": 0.0,
					# Stemmed form of the word
					"stemmed": "recent",
					# Part of speech tag. See http://dev.lexalytics.com/wiki/pmwiki.php?n=Main.POSTags for all tags
					"tag": "RB",
					# Actual word
					"title": "Recently",
					# Normalized part of speech tag
					"type": "Adjective"
				}, {
					"is_negated": false,
					"sentiment_score": 0.0,
					"stemmed": "a",
					"tag": "DT",
					"title": "a",
					"type": "Determiner"
				}, {
					"is_negated": false,
					"sentiment_score": 0.0,
					"stemmed": "toy",
					"tag": "NN",
					"title": "toy",
					"type": "Noun"
				}, {
					"is_negated": false,
					"sentiment_score": 0.0,
					"stemmed": "catalog",
					"tag": "NN",
					"title": "catalog",
					"type": "Noun"
				}, {
					"is_negated": false,
					"sentiment_score": 0.0,
					"stemmed": "go",
					"tag": "VBD",
					"title": "went",
					"type": "Verb"
				}, {
					"is_negated": false,
					"sentiment_score": 0.0,
					"stemmed": "out",
					"tag": "RP",
					"title": "out",
					"type": "Misc"
				}, {
					"is_negated": false,
					"sentiment_score": 0.0,
					"stemmed": ".",
					"tag": ".",
					"title": ".",
					"type": "Symbol"
				}
			]
		}, {
			# Other sentences omitted for length
		}
	],
	# This array lists all entities found
	"entities": [{
			# Did the entity match the optional confidence query
			"confident": true,
			# What type of entity is it
			"entity_type": "Company",
			# How much sentiment evidence is there?
			"evidence": 1,
			# Was this entity a focus of the text?
			"is_about": false,
			# The label of the entitiy. This can be overridden in user-defined entities.
			"label": "Company",
			# Array of actual mentions of the entity.
			"mentions": [{
					# Was the entity negated ?
					"is_negated": false,
					# Actual word found in text
					"label": "Target",
					# Locations info can be ued for hit-highlighting.
					"locations": [{
							"length": 6,
							"offset": 582
						}
					]
				}
			],
			# Sentiment for the entity in words
			"sentiment_polarity": "neutral",
			# Sentiment for the entity as a float
			"sentiment_score": 0.0,
			# This entity does not have themes, but if it did this is where you would see the themes associated with the entity
			"themes": [{
					# Amount of sentiment evidence for this theme
					"evidence": ###,
					# Is this theme a focus of the text?
					"is_about" : (true or false),
					# Array of actual mentions of the theme
					"mentions": [{
							"is_negated": (true or false),
							"label": "",
							"locations": [{
									"length": ###,
									"offset": ###
								}
							],
							 # If an object is negated, the negating phrase
							"negating_phrase": ""
						}
					],
					# Normalized(lower - cased stemmed)version of the theme
					"normalized": "",
					# Sentiment for the theme in words
					"sentiment_polarity": "",
					# Sentiment for the theme in a float
					"sentiment_score": ###,
					# Stemmed version of the theme
					"stemmed": "",
					# Relevancy of the theme to the entity
					"strength_score": ###,
					# Actual words of the theme
					"title": ""
				},
				 # More themes would be found here
			],
			# Entity name
			"title": "Target",
			# Named entities are automatically discovered, user-entities are defined
			"type": "named"
		}
	],
	# The relations array lists the relationships found in the text. None were found in this example so the below array is an empty example
	"relations": [{
			 # Named relations are auto-discovered
			"type": "",
			 # the words triggering the relationship
			"extra": "",
			 # The entities involved in the relationship
			"entities": [{
					"title": "",
					"entity_type": ""
				}
			],
			 # Type of relationship
			"relation_type": "",
			"confidence_score": ###
		}
	],
	# ID of the document
	"id": "5c8-0001",
	# The intentions portion of the results. Note that intentions are only offered in English
	"intentions": [{
			# Phrase showing intent
			"evidence_phrase": "can not get",
			# Intention type
			"type": "quit",
			# The what of the intent
			"what": "them",
			# The who of the intent
			"who": "You"
		}, {
			"evidence_phrase": "did not get",
			"type": "quit",
			"what": "one you",
			"who": "If you"
		}
	],
	# Language of document
	"language": "English",
	# Confidence in the language
	"language_score": 0.16480173,
	# Any metadata passed to Semantria would be displayed here. This example did not use metadata
	"metadata": {
	},
	# This dictionary lists the model-based sentiment scores. There were no model-based sentiment scores in this example so the below is intentionally empty 
	"model_sentiment": {
		 # likelihood the document had a mixed sentiment score
		"mixed_score": ###,
		 # Model name.Semantria ships with a defaultmodel.
		"model_name": "",
		 # Likelihood the document had a negative score
		"negative_score": ###,
		 # Likelihood the document had a neutral score
		"neutral_score": ###,
		 # Likelihood the document had a neutral score
		"positive_score": ###,
		 # Most likely sentiment polarity in words
		"sentiment_polarity": ""
	},
	# This array lists all sentiment phrases found in the text.
	"phrases": [ {
			# Whether the phrase was intensified
			"is_intensified": false,
			# Whether the phrase was negated
			"is_negated": false,
			# length of phrase in bytes
			"length": 5,
			# beginning position of phrase in bytes
			"offset": 449,
			# Phrase sentiment in words
			"sentiment_polarity": "positive",
			# Phrase sentiment in float
			"sentiment_score": 0.565,
			# Actual phrase
			"title": "loved",
			# Whether detected or possible
			"type": "detected"
		}, {
			"sentiment_polarity": "neutral",
			"title": "been sent",
			# Semantria's suggestions of possible sentiment phrases to add to custom configuration
			"type": "possible"
		}, {
			"sentiment_polarity": "neutral",
			"title": "certain news",
			"type": "possible"
		}, {
			"sentiment_polarity": "neutral",
			"title": "different coupon",
			"type": "possible"
		}, {
			"sentiment_polarity": "neutral",
			"title": "not be",
			"type": "possible"
		}, {
			"sentiment_polarity": "neutral",
			"title": "not get",
			"type": "possible"
		}, {
			"sentiment_polarity": "neutral",
			"title": "not get",
			"type": "possible"
		}, {
			"is_intensified": false,
			"is_negated": false,
			"length": 11,
			"offset": 251,
			"sentiment_polarity": "neutral",
			"sentiment_score": 0.41,
			"title": "really good",
			"type": "detected"
		}, {
			"is_intensified": false,
			"is_negated": false,
			"length": 8,
			"offset": 366,
			"sentiment_polarity": "neutral",
			"sentiment_score": -0.4,
			"title": "so wrong",
			"type": "detected"
		}
	],
	# Sentiment of document in words
	"sentiment_polarity": "neutral",
	# Sentiment of document as float
	"sentiment_score": 0.19166666,
	# Source text
	"source_text": "Recently a toy catalog went out. If you did not get one you are SOL. I just called\n the corporate and they were mailed at random and put only in certain news papers. You can\n not get them at the store or ask corporate to send you one. There were some really good\n coupons like this week 25% off one toy. There was a different coupon each week. I think\n that this is so wrong. I for one have a target card just for Christmas shopping and would\n have loved those coupons. And since I have a card I would think a catalog should have\n been sent to me. Guess who will not be shopping at Target this year!",
	# Semantria status of document
	"status": "PROCESSED",
	# Summary of document
	"summary": "Recently a toy catalog went out... I just called the corporate and they were mailed at random and put only in certain news papers... There were some really good coupons like this week 25% off one toy... ",
	# Array of themes relevant at a document level
	"themes": [{
			# Amount of sentiment evidence for this theme
			"evidence": 7,
			# Was this theme a focus of the text
			"is_about": false,
			# Array of actual mentions of the theme
			"mentions": [{
					# Was the mention negated
					"is_negated": false,
					# Actual mention
					"label": "different coupon",
					# Mention location can be used for hit-highlighting
					"locations": [{
							"length": 16,
							"offset": 316
						}
					]
				}
			],
			# Normalized version of theme
			"normalized": "different coupon",
			# Sentiment for theme in words
			"sentiment_polarity": "neutral",
			# Sentiment fpr theme in a float
			"sentiment_score": 0.41,
			# Stemmed version of the theme
			"stemmed": "different coupon",
			# Relevancy of the theme
			"strength_score": 1.25,
			# Actual words of the theme
			"title": "different coupon"
		}, {
			"evidence": 7,
			"is_about": true,
			"mentions": [{
					"is_negated": false,
					"label": "good coupons",
					"locations": [{
							"length": 13,
							"offset": 258
						}
					]
				}
			],
			"normalized": "good coupon",
			"sentiment_polarity": "positive",
			"sentiment_score": 2.58,
			"stemmed": "good coupon",
			"strength_score": 1.5833334,
			"title": "good coupons"
		}, {
			"evidence": 4,
			"is_about": false,
			"mentions": [{
					"is_negated": false,
					"label": "target card",
					"locations": [{
							"length": 11,
							"offset": 393
						}
					]
				}
			],
			"normalized": "target card",
			"sentiment_polarity": "positive",
			"sentiment_score": 0.565,
			"stemmed": "target card",
			"strength_score": 0.2,
			"title": "target card"
		}, {
			"evidence": 4,
			"is_about": true,
			"mentions": [{
					"is_negated": false,
					"label": "toy catalog",
					"locations": [{
							"length": 11,
							"offset": 11
						}
					]
				}
			],
			"normalized": "toy catalog",
			"sentiment_polarity": "neutral",
			"sentiment_score": 0.205,
			"stemmed": "toy catalog",
			"strength_score": 0.33333334,
			"title": "toy catalog"
		}
	],
	# This array lists topics discovered in the text. Topics include queries and concept topics (also known as user categories). This example only hit on a query so the below shows the query topic output.
	"topics": [{
			# The number of query terms that hit in the document
			"hitcount": 2,
			# The ID of the query
			"id": "4c640e2e-6e0f-44f9-a6c6-eca67f3962f3",
			# An array listing the term hits
			"mentions": [{
					# Whether the term was negated
					"is_negated": false,
					# The term that hit
					"label": "think",
					# An array of locations of the term
					"locations": [{
							# The length in bytes of the term
							"length": 5,
							# The offset in bytes from the beginning of the document for the hit
							"offset": 346
						}, {
							"length": 5,
							"offset": 502
						}
					]
				}
			],
			# The sentiment polarity of the query
			"sentiment_polarity": "neutral",
			# The sentiment score of the query as a float
			"sentiment_score": 0.0,
			# The name of the query
			"title": "Customer Service",
			# The type of topic. This can be concept or query
			"type": "query"
		}
	]
}

Detailed mode limits apply to both document mode and source mode of analysis. All limits have integer values of 0 to 20. Setting a limit to a score of 0 signifies zero interest in the output and will prevent the result for that parameter from appearing in the dataset.

Detailed Mode output explanation

Semantria provides the user with a wealth of information in its sentiment analysis and data processing; sometimes it can be kind of hard to wade through. Here is a quick reference detailing everything the Semantria API will return to the user in Detailed Analysis Mode.

Each document will have an id and each configuration has a unique config_id. The user can add tags and view the status of the document ("queued," "processed" or "failed"). Semantria API will produce a job_id of the associated job, a summary of the document text, the language of the source text (and the language score, the percentage of the best language match among detected languages), and the sentiment_score and sentiment_polarity.

In detailed analysis of individual sentences, the API will return boolean values for is_imperative and is_polar. Imperative sentences, representing an action item, will be set to true. is_polar represents Semantria's guess as to whether the writer of the sentence meant to convey sentiment. For instance, "Good morning all" is a non-polar sentence despite containing a sentiment word of "good."

The API will return a list of words grouped by the parent sentence. Each word will have a tag, POS type, title, stemmed form of the word, and sentiment_score.

Semantria API will generate auto_categories; each category will have a title, type ("node"/root or "leaf"/nested value), strength_score (how much the category matches with document content), and categories, an array of sub-categories (if any exist).

phrases are a list of sentiment-bearing phrases from the document. Each will have a title, sentiment_score, sentiment_polarity (negative, positive, or neutral), is_negated (whether the phrase has been negated), negating_phrase (if one exists), is_intensified, intensifying_phrase (if one exists), and type (either "possible" or "detected").

The Semantria API returns the themes of the document. Each has the title, main theme (is_about), the normalized form of the theme, the stemmed form of the theme, an evidence score, strength_score within the document, and sentiment_polarity. The API will return mentions of the theme: expandable, which is the text of the theme mention, is_negated, negating_phrase, and locations-- the list of coordinates of the mentions found within the document. offset is the number of bytes offset in the original text before the start of the mention, and length is the length of the mention in bytes.

The API returns entities with similar parameters to themes. Entities have additional parameters of type (either "named" or "user"), confident (whether the confidence queries matched for this entity), and the entity_type (Company, Person, Place, etc.). It will also return a list of themes related to this entity.

Semantria API returns relations, which represent a connection between one or more Entities. These have a type (named or user value), relation_type (such as quotation), confidence_score, and extra of the parent relationship.

The API will also return a list of opinions extracted from the source text. Each will have a quotation, type (the type of entity extracted-- named or user value), speaker, topic, sentiment_score and sentiment_polarity.

Finally, Semantria API gives a list of topics, each with a title, type, hitcount, strength_score, sentiment_score, sentiment_score and topics (a list of sub-topics, if they exist).

API Options

Option
Description
Default

auto_response

Defines whether or not the service should respond with processed results on each incoming analytics document or discovery analysis request (more info).

False

is_primary

Identifies whether the current configuration is primary or not.

False

chars_threshold

Defines whether or not the service should respond with processed results on each incoming analytics document or discovery mode request.

80

one_sentence

Leads the service to clean HTML tags before processing.

False

process_html

Leads the service to clean HTML tags before processing.

False

language

Defines target language that will be used for task processing.

English

callback

Defines a callback URL for automatic data responding (more info).

Empty

Suggest Edits

Discovery Output Explanation

 

Discovery Mode Output

Semantria’s Discovery Mode provides you with a bird's eye view of your content after the sentiment has been analyzed. In this mode you can discover the top entities, themes, facets, topics, and overarching sentiment count of your group of documents. Semantria does the counting and rollup for you. This can be a good way to get on overview of what is in your data without having to put it into another tool to aggregate the output.

Discovery Mode output explanation

In Discovery mode, sentiment average is not supported. Instead, the positive, negative, and neutral counts available for facets are analogous to the positive/negative ratio; these show how many mentions of each type were in the text with respect to a certain facet.

Like in Detailed Mode, Discovery Analysis Output will have an analysis id, config_id, job_id, tag and status. The analysis will also return themes, entities and topics.

Discovery Mode Analysis returns the facets extracted from all documents in the batch of discovery analysis. Each facet has a label (the text of the facet), count (number of occurrences), negative_count (number of negative occurrences), netural_count, positive_count, and mentions.Each mention will have a label, an indicator, and negating_phrase. The API will also return attributes associated with the facet with accompanying labels, counts and mentions.

Users have the option for the Semantria API to return the original source document in addition to the processed results. This is useful for multi-level integrations. The option can be switched on and off on upon request.

This analysis can give you insight into problem areas within your business. With Discovery Mode you can see which of your hotel branches is underperforming or which competing brand is generating the most buzz on Twitter. Additionally, you can see the reasons behind the positive and negative feedback and quickly use that information to improve. You can also use your Discovery data to create charts and tables so that you can understand your data from a quick glance.

When sending a collection of texts (e.g. a set of 1,000 tweets) to Semantria, all content is analyzed simultaneously. All recurring mentions of an entity or theme are counted and available to you. In Discovery Mode our Excel Add-In will only display facets, attributes, and sentiment count due to Excel limitations, but Semantria is doing more work behind the curtain.

For example, when running Discovery Mode on a collection that contains the sentence “My waiter was rude!” Semantria will identify the word “waiter” as a facet and search for it throughout the rest of the texts. The attributes associated with “waiter” found within the collection are then consolidated so you will know how many people share the same feelings towards the waiter.

Suggest Edits

Error Codes

You can see detailed examples under the endpoint operation pages.

 

200 Server request correct and accepted. The server responds with data according to the document sent and the configuration of the auto response feature.

202 Server request correct and accepted. Server doesn’t respond with any data and just serves the request.

400 Wrong request format. Server responds with details.

401 Authentication failed.

402 Request is unauthorized. The number of calls limit has been reached or the license is expired.

403 Request is forbidden. Server responds with details.

404 No documents or collections with the provided unique configuration ID were found on the server.

406 Batch, collection or other configuration limits reached. Server responds with details.

413 Character limit for single document exceeded.

500 Server side issue. Server may respond with the details in response body.

Suggest Edits

License Expiration

 
  • A trial account will expire after 15 days by default
  • For subscription accounts, there is a sliding expiration: account will expire after a certain period of inactivity
  • Legacy accounts expire after one year

Your license expiration is usually set to the last day of your subscription's validity. The account will go offline at midnight GMT at the end of the last day of the term. When a license expires, Semantria will return a 402 HTTP status and send an email to the email address used when registering with Semantria.

A trial account can be converted to a non-expiring paid subscription by contacting our sales team at sales@lexalytics.com.

Suggest Edits

Checking Supported Features by Language

This method returns a list of the supported features per languages supported by the Semantria API. If no parameter is passed, Semantria will respond with a list of supported features, organized by language.

 
get/features.[json | xml]
GET https://api.semantria.com/features.json?language=en
A binary file was returned

You couldn't be authenticated

HTTP/1.0 200 Request accepted and served.
[
  {
	"id": "en",
	"language": "English",
	"html_processing": true,
	"settings": {
	  "blacklist": true,
	  "user_entities": true,
	  "sentiment_phrases": true,
	  "user_categories": true,
	  "queries": true
	},
	"detailed_mode": {
	  "language_detection": true,
	  "pos_tagging": true,
	  "intentions": true,
	  "theme_mentions": true,
	  "sentiment_phrases": true,
	  "entity_themes": true,
	  "themes": true,
	  "entity_relations": true,
	  "named_entities": true,
	  "sentiment": true,
	  "entity_mentions": true,
	  "summarization": true,
	  "user_entities": true,
	  "queries": true,
	  "auto_categories": true,
	  "user_categories": true,
	  "entity_opinions": true
	},
	"discovery_mode": {
	  "named_entities": true,
	  "entity_mentions": true,
	  "facet_mentioins": true,
	  "facets": true,
	  "user_entities": true,
	  "theme_mentions": true,
	  "user_categories": true,
	  "themes": true,
	  "queries": true,
	  "facet_attributes": true
	}
  }
]
HTTP/1.0 200 Request accepted and served.
<supported_features>
  <features>
	<detailed_mode>
	  <language_detection>true</language_detection>
	  <pos_tagging>true</pos_tagging>
	  <intentions>true</intentions>
	  <theme_mentions>true</theme_mentions>
	  <sentiment_phrases>true</sentiment_phrases>
	  <entity_themes>true</entity_themes>
	  <themes>true</themes>
	  <entity_relations>true</entity_relations>
	  <named_entities>true</named_entities>
	  <sentiment>true</sentiment>
	  <entity_mentions>true</entity_mentions>
	  <summarization>true</summarization>
	  <user_entities>true</user_entities>
	  <queries>true</queries>
	  <auto_categories>true</auto_categories>
	  <user_categories>true</user_categories>
	  <entity_opinions>true</entity_opinions>
	</detailed_mode>
	<discovery_mode>
	  <named_entities>true</named_entities>
	  <entity_mentions>true</entity_mentions>
	  <facet_mentioins>true</facet_mentioins>
	  <facets>true</facets>
	  <user_entities>true</user_entities>
	  <theme_mentions>true</theme_mentions>
	  <user_categories>true</user_categories>
	  <themes>true</themes>
	  <queries>true</queries>
	  <facet_attributes>true</facet_attributes>
	</discovery_mode>
	<html_processing>true</html_processing>
	<id>en</id>
	<language>English</language>
	<settings>
	  <blacklist>true</blacklist>
	  <user_entities>true</user_entities>
	  <sentiment_phrases>true</sentiment_phrases>
	  <user_categories>true</user_categories>
	  <queries>true</queries>
	</settings>
  </features>
</supported_features>

Query Params

language
string

ISO language code