API Reference

Endpoint Response Fields
Products & Hotels Endpoints
Field Name Description
id Internal Aspectiva’s product ID
name Product name
description Product description – including top pros and cons
score Overall product score based on analyzed options, reflecting the proportion of positive options. From V1.1, the number is in percentages (range 0 to 100). In V1.0, the scale is 0 to 10.
rank The position of the product in the category, when sorting by score. 1 is the top rank
sentiment The overall representative textual sentiment description of the product, picked by an algorithm based on how users expressed their opinion on the product
reviewsCount Number of reviews that the analysis is based on
positiveOpinionsCount The number of positive opinions associated with the product (an opinion is when a user expresses some sentiment about some product aspect or about the product in general
negativeOpinionsCount The number of negative opinions associated with the product (an opinion is when a user expresses some sentiment about some product aspect or about the product in general
categoryId The identifier of the category to which the product belongs. Useful an a reference in the Recommendations API
categoryName The name of the category to which the product belongs
imageUrl A URL of a product image that can be used when describing or mentioning the product
overallAspect Information about the ‘overall’ aspect that represents the analysis of general opinions about the product, not pertaining to a particular aspect
positiveAspects An array of the positive product aspects, see Aspect Model for sub-fields
negativeAspects An array of the negative product aspects, see Aspect Model for sub-fields
Aspects Endpoint
Field Name Description
id Aspect ID used to refer to the aspect
name Aspect name
score Aspect score based on analyzed opinions, reflecting the proportion of positive opinions about the aspect. From V1.1, the range is 0-100. In V1.0, the range is 0-10.
positiveSentimentExpressions A list of representative words and phrases used in the opinions to describe the aspect positively
negativeSentimentExpressions A list of representative words and phrases used in the opinions to describe the aspect negatively
mentionsCount Number of times the aspect is mentioned with an expression of opinion in the analyzed reviews
Aspect Model
Field Name Description
id Aspect ID (can be used to refer to this aspect in other endpoints)
name Aspect name
score Aspect score based on analyzed opinions, reflecting the proportion of positive opinions about the aspect. From V1.1, the range is 0-100. In V1.0, the range is 0-10.
positiveSentimentExpressions A list of representative words and phrases used in the opinions to describe the aspect positively
negativeSentimentExpressions A list of representative words and phrases used in the opinions to describe the aspect negatively
mentionsCount Number of times the aspect is mentioned with an expression of opinion in the analyzed reviews
positiveReviewsExamples Reviews snippets with positive mentions of the aspect. See Review Model for sub-fields
negativeReviewsExamples Reviews snippets with negative mentions of the aspect. See Review Model for sub-fields
Review Model
Field Name Description
text Review snippet text
author Review author
date Review publication date
url Link to the original review, if exists, or to the product page otherwise
aspectStart Offset in characters where the aspect begins (for highlighting purposes)
aspectEnd Offset in characters where the aspect ends (for highlighting purposes)
sentimentStart Offset in characters where the sentiment begins (for highlighting purposes)
sentimentEnd Offset in characters where the sentiment ends (for highlighting purposes)
Aspect Suggestions Endpoint
Field Name Description
id Aspect ID (can be used in other APIs to identify the aspect)
name Aspect name
Examples Endpoint
Field Name Description
id Aspect ID (can be used in other APIs to reference the aspect)
name Aspect name
mentions Number of times an option on the aspect is mentioned in reviews
score Aspect score based on analyzed opinions, reflecting the proportion of positive opinions about the aspect. The range is 0-100.
positive Reviews with positive aspect mentions, including sub-fields:

  • mentions – number of aspect mentions that include opinions
  • adjecitves – list of representative sentiment phrases illustrating the way reviewers expressed their opinion about the aspect
  • reviews – review text and details, see Review Model for sub-fields
negative Reviews with negative aspect mentions, including sub-fields:

  • mentions – number of aspect mentions that include opinions
  • adjecitves – list of representative sentiment phrases illustrating the way reviewers expressed their opinion about the aspect
  • reviews – review text and details, see Review Model for sub-fields
Recommendations Endpoint
Field Name Description
id Internal Aspectiva’s product ID
name Product name
score Overall product score based on analyzed options, reflecting the proportion of positive options. Range is 0 to 100.
reviewCount Number of reviews that the analysis is based on
imageUrl A URL of a product image that can be used when describing or mentioning the product
aspects Information about the requested product aspect for the current product on the recommendations list:

  • score
  • mentionsCount
  • sentimentExpressions
Error Codes
Error Code Description What To Do
400 Missing mandatory attribute Check required fields in documentation.
401 Failed to authenticate the request Check your client ID.
404 Requested resource not found Check that the product ID is correct. If so, no information is currently available for this product.