Semantria API / Release notes

4.2 (6-4-2016)


You will need to modify your application if it updates configurations via the /configurations endpoint. To maintain backwards compatibility, make sure you pass a version header of 4.0 or earlier

/configurations key changes

Top level changes

  • config_id renamed to id for consistency with other endpoints
  • chars_threshold renamed to alphanumeric_threshold for clarity
  • categories_threshold renamed to concept_topics_threshold for consistency with core Salience output
  • one_sentence renamed to one_sentence_mode for consistency
  • summary_limit renamed to summary_size for clarity

Document section changes

  • auto_categories limit renamed to auto_categories and is now a boolean
  • phrases_limit and possible_phrases_limit collapsed into sentiment_phrases and is now a boolean
  • themes_limit and entity_themes_limit collapsed into themes and is now a boolean
  • theme_mentions_limit, user_mentions_limit and named_mentions_limit collapsed into mentions and is now a boolean
  • named_entities_limit renamed to named_entities and is now a boolean
  • user_entities_limit renamed to user_entities and is now a boolean
  • named_opinions_limit and user_opinions_limit collapsed into opinions and is now a boolean
  • named_relations_limit and user_relations_limit collapsed into relations and is now a boolean
  • query_topics_limit renamed to query_topics and is now a boolean

Collection section changes

  • themes_mention_limit, facets_mention_limit, attributes_mention_limit, named_mentions_limit and user_mentions_limit collapsed into mentions and is now boolean
  • facets_limit renamed to facets and is now boolean
  • facet_atts_limit renamed to attributes and is now boolean
  • named_entities_limit renamed to named_entities and is now boolean
  • user_entities_limit renamed to user_entities and is now boolean
  • query_topics_limit renamed to query_topics and is now boolean
  • concept_topics_limit renamed to concept_topics and is now boolean

/subscription key changes

basic_settings changes

  • output_data_limit renamed to summary_size_limit for clarity
  • categories_limit renamed to concept_topics_limit for consistency with core Salience output
  • entities_limit renamed to user_entities_limit for clarity
  • phrases_limit renamed to sentiment_phrases_limit for clarity
  • batch_limit renamed to incoming_batch_limit for clarity
  • auto_response_limit renamed to auto_response_batch_limit for clarity
  • processed_batch_limit renamed to polling_batch_limit for clarity

    billing_settings changes

  • priority field removed
  • limit_type removed
  • docs_limit removed
  • docs_limit_interval removed
  • docs_suggested removed
  • docs_suggested_interval removed

feature_settings changes

  • sentiment_phrases and phrases_detection collapsed into sentiment_phrases
  • themes and entity themes collapsed into themes
  • named_relations and user_relations collapsed into relations

/features key changes

settings changes

  • user_categories renamed to concept_topics
  • queries renamed to query_topics

detailed_mode changes

  • themes and entity themes collapsed into themes
  • theme_mentions and entity_mentions collapsed into mentions
  • entity_relations renamed to relations
  • entity_opinions renamed to opinions

discovery mode changes

  • facet_attributes renamed to attributes
  • facet_mentions, theme_mentions, and entity_mentions collapsed into mentions
  • user_categories renamed to concept_topics
  • queries renamed to query_topics

New Features

  • added mentions to query topic output with byte and offset location

4.1 (3-26-2016)


You will need to modify your application if it consumes the statistics endpoint.

Statistics endpoint documentation

New Features

  • Brand new statistics API (old one will be deprecated)
  • Re-worked /statistics end-point. Removed collections level stats, renamed fields.
  • Added Metadata feature with an ability to pass free-form JSON metadata through the server.
  • Added Job ID related fields to /subscription end-point. There are permitted and allocated Job Id fields.

4.0 (12-12-2015)


This is a backwards-incompatible update for query syntax and resource updates through the API. To maintain backwards compatibility, pass a version of 3.9 in the header

New Languages

  • Added Turkish and Hebrew as premium options. Disabled for all existing customers.

New Features

  • Added support for taxonomy structures
  • Unique IDs for user-created resources (queries, phrases, categories)
  • Full REST compliance for update of existing resources
  • Sentiment tuning for premium languages

Industry Pack Updates

  • First release of Airlines industry pack
  • Free trial editions of the Hotels and Restaurants industry packs

Bug fixes

  • Incorrect usage stats under very heavy load

3.9.2 (10-24-2015)

New Languages

  • Added Polish as a premium option. Disabled for all existing customers.

New Features

  • Support for Industry Packs (Hotels, Restaurants)

3.9.2 (08-11-2015)

New Languages

  • Limited Swedish support added for Excel and Advanced users (document-level sentiment and queries only).
  • Limited Danish support added for Excel and Advanced users (document-level sentiment and queries only).
  • Limited Norwegian support added for Excel and Advanced users (document-level sentiment and queries only).

3.9 (05-27-2015)


This update maintains backward-compatibility but does augment the detailed analysis output with new fields for model-based sentiment under ModelSentiment. Currently, custom models can only be created with the help of Semantria Professional Services. Contact for a quote.

New Languages

  • Limited Arabic support added for Excel, Growth, and Advanced users (document-level sentiment and queries only).
  • Limited Russian support added for Excel, Growth, and Advanced users (document-level sentiment and queries only).

New features

  • New model-based (machine learning) sentiment analysis for documents in detailed analysis mode.


  • Improved accuracy of "One sentence" mode
  • Concept topics are now limited to 5 per document
  • Themes are now sorted by themes count in Discovery analysis output

Bug Fixes

  • Fixed incorrect Themes count in Discovery output
  • Fixed values for Phrases count and Themes count for themes of Discovery analysis mode
  • Fixed normalized entities containing white-spaces reported within double quotes
  • Fixed issue with mentions and hashtags breaking queries
  • Fixed usage statistics for documents delivered via callback service
  • Fixed blacklist not applied for entities and auto-categories in Russian and Arabic

3.8 (02-18-2015)

New languages

  • Added Dutch language for selected subscribers. Disabled for all existing customers.

New features

  • Added "entities_threshold" option on Configuration level for managing of entities reporting threshold based on engine’s confidence.
  • Introduced the new /features end-point that exposes the supported features per the languages offered by Semantria. The API automatically allows / denies the setting of certain limits on the configuration level according to the supported features.
  • Introduced a new approach for limiting the frequency of allowed API calls. Currently we limit data calls only by the balance. Configuration and polling API calls are limited by the transport API calls limit. In the new version we limit the number of data API calls per second and divide the transport API calls limit by the polling and settings limits. This keeps configuration API calls from interfering with data API calls.
  • Introduced "normalized" and "stemmed" forms for themes output in Detailed and Discovery analysis modes.
  • Added user entities output in Discovery analysis mode. The output is limited by the new "user_entities_limit" and "user_mentions_limit".

Fixed bugs

  • Fixed bug with inappropriately long caching of configuration permissions on API side.
  • Fixed bug where usage of double quotes with @mentions and #hashtags resulted in invalid queries.

3.75 (12-24-2014)

New features

  • Introduced Intentions feature. Switched off by default and will be available only for API Advanced users.
  • Added “Categories threshold” option to configuration. The option defines the minimum score of user categories to be reported in the output.
  • Introduced user-level permissions on API side. Now an account administrator can create new users and give users different permissions for API usage.

Fixed bugs

  • Fixed bug with negative balance. A user with 0 balance was not able to use the API but the counter went negative.
  • Fixed bug with non-removable queries prefixed with a space in the title.
  • Fixed bug with nested queries when Semantria didn’t report them if more than 10 queries joined into a root one.
  • Fixed bug with @mentions and #hashtags in queries. Composite tokens were not handled properly.
  • Fixed bug with wrong language after configuration cloning through “template” field.
  • Fixed bug with auto-categories output on non-English languages. Auto-categories are only supported in English so no output should be present for non-English languages

3.7 (10-10-2014)

New languages

  • Japanese (all features but auto-categories)
  • Malay (all features but auto-categories and user categories)
  • Arabic (Limited features)

New features

  • Added intensifiers for sentiment-bearing phrases output
  • Added option to stem facets in discovry analysis (Semantria will collapse room and rooms into room)
  • Entity stemming when boolean logic is used


  • Analysis failure when tag or id fields contained special characters
  • Enhanced error reporting if document failed or API call forbidden based on subscription type
  • JSON validation mechanism before returning analysis results back to client
  • Adding of empty user entities, queries, user categories
  • Inability to add normalized form with empty spaces for user entities definition

3.5.5 (04-02-2014)

New languages

  • Korean (all features but auto-categories)
  • Italian (all features but auto-categories)

New features

  • Option to override native sentiment dictionary
  • Option to flatten all uppercase characters (to avoid uppercase words being recognized as proper nouns)
  • Option to overlap user entities when user defines several entities with the same name but with a different logic: Semantria will only report the last hit
  • Option to use use anaphora resolution for named entities extraction
  • Option to stem queries in query-based categorization: Semantria will stem query terms
  • Option to fail on long sentences: Semantria will postpone long sentences (> 1000 words) without punctuation during analysis


  • Duplicated API settings (entities, categories, queries, etc) when large amount of resources
  • Wrong offset for multi-byte characters reported for mentions of all output types
  • Incorrect values of language_score properties returned by Semantria for language detection
  • Request timeout when queuing large batches containing multi-byte characters
  • Inability to use punctuation marks within query terms during query-driven entities definition
  • Wrong content-type header sent by callback service along with the data
  • Adding of punctuation marks in normalized form during query-driven entities definition

3.5.1 (10-10-2013)


  • Introduced support for Chinese. All Lexalytics Salience features for Chinese language, except for opinions and relationships, are now supported by Semantria.
  • HTML processing is now supported out of the box. Switch on HTML processing in Semantria configuration and Semantria will clean out HTML tags from content automatically.
  • Introduction of Auto-Categories feature for Basic Mode. Based on Lexalytics’ Salience Concept Topics, Auto-Categories are generated automatically based on the Wikipedia taxonomy (720+ nodes)
  • Added Mentions output for Themes and Entities of collection processing mode (Semantria Discovery Mode). Limits for both Theme and Entity mentions can be configured through configuration (Discovery Mode section).
  • Added “Normalized” field to custom entities configuration through the API. Normalized field allows different entity names to be normalized into a common one (i.e. Big Blue, Intelligent Business Machines, and IBM to IBM).
  • Introduced query grammar for entities configuration. Now, entities extraction can be controlled by Boolean syntax (for example IBM = IBM OR “I.B.M. OR “Big Blue” OR “Intelligent Business Machines").
  • Added Tag field to the incoming/outgoing documents. It can be used as free text marker that Semantria will return back to the user.
  • Added “Is inverted” marker to words returned by POS tagging feature. Marker indicates whether word is a part of sentiment inverting construction like a negator.
  • Added “Label” field to the Topics (concept/query) output for both Basic and Discovery modes. Label can contains any descriptive information about topic, same as Semantria Named Entities.
  • Enhanced “Location” output for Discovery mode. Now it returns not only index number of the document where entity was mentioned, but byte offset and its length as well.


  • Fixed bug with wrong Location offset for Mentions in the content with multi-byte symbols.
  • Fixed bug preventing limits for any output data in a configuration to be more than 20. New API allows any limits to be set on demand and doesn’t reset it on configuration update.
  • Fixed bug with incorrect evidence values for Themes and Entities. Now it’s spread between 1 and 7 and doesn’t remain 4 or 7 all time.

3.1 (04-06-2013)


  • Mentions for named and user entities, and document and entity themes. Similar to facets, mentions will be genuine, not normalized, forms of entities and themes from the text.
  • Opinions for named and user entities. Opinions are people’s subjective quotations regarding topics within the text.
  • Label fields for named and user entities. This field contains auxiliary information on certain entities. Labels will be available as an additional field for the entities output and as an additional field for entities definition through the entities configuration end-point.
  • Concept grammar verification for category samples. Semantria now allows query definitions within categories for higher categorization precision.
  • “language_score” property for language detection. A numerical representation of the engine’s confidence in correct language detection.
  • Fixed many known bugs.

3.0.2 (02-04-2013)


  • Mentions for attributes for collection processing mode. Mentions are non-normalized attributes that were originally mentioned in the text along with the facet. Mentions allows the API users to return back to the exact documents where the extracted attribute was mentioned.
  • Semantria now generates 5 configurations for every new registration out of the box. There are 5 configurations for all available languages with the sample Categories, Queries, Entities and Sentiment-bearing phrases.
  • Added possibility of adjust low-level analysis patterns per available customer’s configurations. This makes Semantria a completely flexible solution that can be adjusted per customer needs on demand.
  • Fixed all known bugs.

3.0.1 (26-02-2013)


  • Mentions feature for collection processing mode. Mentions are non-normalized facets that were originally mentioned in the text. Mentions allows the API users to return back to the exact documents where the extracted facet was mentioned.
  • Fixed all known bugs related to the newest API 3.0 release.

3.0 (14-02-2013)


  • Completely new infrastructure that brings performance to the new level and doesn’t depend on frequent configuration switching.
  • New billing approach that offers feature-driven packages instead of balance-driven packages of API 2.x.
  • Parts of speech tagging of whole text, which is a low-level analysis output.
  • Relationships detection between the entities. Feature is available for named and user entities.
  • Language detection feature. Semantria doesn’t analyze text on detected language but rather just responds with the detected language name.
  • Sentiment-bearing phrases detection. Now Semantria is capable of suggesting to the user which phrases from initial text may effect sentiment results.
  • Statistics API end-point, which offers complete statistical information of API usage per configuration and as a whole.
  • Added sentiment polarity along with the sentiment score. API responds with the verbal sentiment representation.
  • Reworked configuration API. The “update” approach rejected in favor of separate API calls.
  • GZip and Deflate HTTP compression for outgoing data.
  • Added possibility of responding with the original text along with the analysis result.
  • Fixed many known and reported bugs.
  • Reworked all API SDK’s according to best practices related to the language they are written for. Note:SDKs designed for API 2.x will still use the API 2.0 infrastructure. To use API 3.0's new infrastructure, client-side endpoints must update to SDKs designed for API 3.x.

2.1 (18-09-2012)


  • User Entities adjustment API, which allows customers to teach the engine their own entities.
  • Introduces Sentiment-bearing phrases adjustment API for adjusting sentiment detection algorithm.
  • Added phrases output for the document processing mode. Phrases are the part of speech patterns, which includes nouns.
  • Added Themes, Entities and Topics output for collection and document processing modes.
  • Fixed many known and reported bugs.
  • Added C++ and JavaScript SDKs. Python SDK is divided for Python 2.x and Python 3.x versions.

2.0 (26-03-2012)


  • Configurations, which are virtual accounts layered under one user license.
  • Collection processing mode, which processes one batch of documents as one request.
  • Multilingual analysis support for English, French and Spanish languages.
  • Categories and Queries configurations for concept and query topics adjustments.
  • Added concept and query topics output, which are the results of Categories and Queries based categorization.
  • Added facets and attributes output for collection processing mode.
  • Added new properties for Themes, Entities and Document objects.
  • Fixed many known and reported bugs.
  • Added Python, PHP, Ruby and Apex SDKs.

1.0 (20-10-2011)


  • Initial Semantria API release. Only document processing mode available.
  • REST API with XML and JSON data formats support.
  • Overall sentiment score for the documents.
  • Named entities extraction.
  • Document-level and entity-level themes extraction.
  • Blacklist API for filtering of unnecessary output from analysis results.
  • Net and Java SDKs.

Or call us at 1-800-377-8036