Unicorn NLP

Language Understanding APIs

Unicorn NLP

Language Understanding APIs

API Documentation (Semantic Analysis for Reviews)

API Documentation -> Semantic Analysis for Reviews (Hotel, Hostel, Apartment)


Here, we described input/output for Semantic Analysis for Hotel Reviews, Semantic Analysis for Hostel Reviews, and Semantic Analysis for Apartment Reviews. We also called it Sentiment Analysis 2.0, so if you are using an old API, the input/output description is the same.

This API is very simple to use and does not require any linguistic or machine learning skills. Reading the whole documentation should take no more than 15 mins. After that, you can start using APIs. If something is not clear, you need help or have other questions, contact us.

API is available via RapidAPI (links below), so you need to apply RapidAPI Key that you get after you sign up.
Below, you will find RapidAPI links to publicly available APIs:



API Documentation for Semantic Analysis for Reviews

Semantic Analysis API consists of only one endpoint (method) - process. It allows you to process unstructured review or other user-generated content and transform it into ready-to-use structured data (JSON with a list of categories, aspects, semantic models, general sentiment, and a semantic summary).

process(title, text) [Endpoint]

This endpoint returns all results in one output: general sentiment, aspects, categories, semantic analysis, and a semantic summary. So, you pay only once. Below, you will find the description of each field, both input, and output.


Input (POST):

[Maximum length in total: 5000 characters.]

If you have a standard format of review: "Title + Text", use title + text input fields.
If you have other formats of review: "Title + Positives/Pros + Negatives/Cons" (e.g., booking.com), read below how to use title + text input fields to process it.


How to process a review which is not in "Title+Text" format but "Title+Positives+Negatives" format.

If you have positives/negatives (pros/cons) in your reviews separately, join these fields and add additional text marks [INPUTPROS & INPUTCONS] between and use also the input field text. It is explained below on an example.

title ="Great place!";
positives/pros ="Cleaning service, location, and the staff was friendly";
negatives/cons = "price, slow check-in, poor breakfast";

text = "INPUTPROS "+positives+" INPUTCONS "+negatives;

(how the input fields will look like with example values)
title ="Great place!";
text = "INPUTPROS Cleaning service, location, and the staff was friendly INPUTCONS price, slow check-in, poor breakfast"

Example of how to process Positves & Negatives / Pros & Cons (if you have these fields stored separetely):

Example input (POST):

Let's have a look how this API will process this example text input.


Output (JSON):

Firstly, we describe the API output and what fields each section consists of and comment on results.
Secondly, we will show how the whole JSON output looks like for a given input example.

The output is divided into 5 sections:

We wanted to keep this API compatible with current technologies available (Sentiment Analysis, Aspect-based Sentiment Analysis, Keyword/Category/Topic Analysis). The first three fields (general_sentiment, categories, aspects) is a result of this and allows to provide better accuracy in current interfaces/systems compared to currently available technologies. 4th section (semantic_analysis) is a heart of Semantic Analysis and allows you to go deeper both with accuracy and resolution of the analysis. 5th section is an example of how detailed data can be used to create and aggregate information summaries out of reviews. If you need different output fields or would like to get a private customized version of this API, contact us.

Below, you will find a description of each section with examples of API output.

1. general_sentiment - what is the sentiment score of the whole review. Sentiment score range from -2 (very negative) to +2 (very positive).

Example output:

In this example, the general sentiment of the reviews (sentiment score) is 0 (neutral).

2. categories - list of all categories detected in the processed review. 0 => 1st category with details, 1 => 2nd category, etc.

Example output:

In this example, there are 2 categories: room and addons. room was 3 times present (count=3) in the processed review, addons was 2 times present (count=2). In both cases, the sentiment_score of a given categories is 0 (neutral).

3. aspects - list of all aspects detected in the processed review. 0 => 1st aspect with details, 1 => 2nd aspect, etc.

Example output:

In this example, there are 4 aspects: room, bathroom, tv, fitness.
room was 2 times present (count=2) in the processed review. bathroom, tv, fitness were 1 time present (count=1).
sentiment_score of the room is 1 (positive), of the bathroom is -2 (very negative), tv is -1 (negative), and fitness is 1 (positive).

4. semantic_analysis

Example output:

In this example, 5 semantic models were detected. Each semantic model consist of their id (id_semantic_model), name (name_semantic_model), a quick description what this model describes (description), opposite semantic model if present (id_opposite_semantic_model), category (category), aspect (aspect), feature (feature), sentiment score / polarity (polarity), and a sentence / text segment in which it was detected (segment).
Each semantic model has its category, aspect and feature. Features are grouped semantically to ease the process of aggregating the data, to ease the search process, to display it on analytical dashboards, or to display it to the user
In the 2nd detected semantic model (id_semantic_model=11, name_semantic_model="room_comfy_nice"), id_opposite_semantic_model is null. It means that in this API there is no semantic model that would be opposite in meaning, e.g., "room_uncomfy". Mainly, it is because people do not describe in reviews that the room was not comfy (it was less than 0.1% in reviews). If they write about the negative experiences of the room, they rather describe it as small, smelly, noisy, etc.

If you have some other questions regarding semantic_analysis output, need more information, or would like to modify semantic models for your needs/your data, contact us.


5. semantic_summary

Example output:

In this example, there are 5 semantic summaries.


Example of a JSON API OUTPUT of Semantic Analysis for Reviews API:

Above, we described each section of the output and displayed it in a more human-friendly form. Below, you will find the format of how our API returns JSON output. The example is the same as above.

Input (POST):

Output (JSON):

Example of a JSON API OUTPUT

{
  "general_sentiment":0,
  "categories":{
    "0":{
      "name":"room",
      "count":3,
      "sentiment_score":0},
    "1":{
      "name":"addons",
      "count":2,
      "sentiment_score":0}},
  "aspects":
    {"0":{
      "name":"room",
      "count":2,
      "sentiment_score":1},
    "1":{
      "name":"bathroom",
      "count":1,
      "sentiment_score":-2},
    "2":{
      "name":"tv",
      "count":1,
      "sentiment_score":-1},
    "3":{
      "name":"fitness",
      "count":1,
      "sentiment_score":1}},
  "semantic_analysis":{
    "0":{
      ""id_semantic_model":6,
      ""name_semantic_model":"room_hotel_quiet",
      ""description":"The room/hotel was quiet, good acoustic, little street noise, not hear any noise, well soundproofed",
      "id_opposite_semantic_model":7,
      "category":"room",
      "aspect":"room",
      "feature":"quiet",
      "polarity":1,
      "segment":"Room was nice and spacy, also very quiet"},
    "1":{
      "id_semantic_model":11,
      "name_semantic_model":"room_comfy_nice",
      "description":"The room was comfortable and cozy, ample, nice, good, room nice, good, accommodating",
      "id_opposite_semantic_model":null,
      "category":"room",
      "aspect":"room",
      "feature":"nice, comfy",
      "polarity":1,"segment":"Room was nice and spacy, also very quiet"},
    "2":{
      "id_semantic_model":61,
      "name_semantic_model":"bathroom_dirty",
      "description":"The bathroom was dirty, bathroom amenities dirty, needs cleaning, mold, mildew, gross, urine, hair, dissatisfied with the cleanliness",
      "id_opposite_semantic_model":60,
      "category":"room",
      "aspect":"bathroom",
      "feature":"dirty",
      "polarity":-2,
      "segment":"but bathroom was very dirty"},
    "3":{
      "id_semantic_model":213,
      "name_semantic_model":"tv_bad_old_poor_channels",
      "description":"TV might be old with limited channels, tv bad, not working, poor channels, no premium channels, no remote, problems with tv",
      "id_opposite_semantic_model":245,
      "category":"addons",
      "aspect":"tv",
      "feature":"bad, poor channels",
      "polarity":-1,
      "segment":"There was only 10 TV channels"},
    "4":{
      "id_semantic_model":212,
      "name_semantic_model":"fitness_center_good_great",
      "description":"The fitness center was great, gym, good, great, awesome, excellent",
      "id_opposite_semantic_model":244,
      "category":"addons",
      "aspect":"fitness",
      "feature":"great","polarity":1,
      "segment":"but the fitness was good equipped"}},
    "semantic_summary":{
      "0":"The room/hotel was quiet",
      "1":"The room was comfortable and cozy",
      "2":"The bathroom was dirty",
      "3":"TV might be old with limited channels",
      "4":"The fitness center was great"}}

What's next

Go to Rapid API and you can start using Semantic Analysis APIs today.

Other public APIs by Unicorn NLP

Contact us to prepare a custom-made API designed to your data and your needs.

Go to product sites of Semantic Analysis APIs to get more description of what it detects and what this technology can do to your business



If you have some other questions, need more information, or you need to get the On-Premise version with 0 cents / text (Big Data Compatible) of Semantic Analysis for Reviews, or other Language Understanding API for any texts, contact us.