Review Display

Returns Reviews and Rating and related data.

🚧

Only API keys on our Conversations platform are eligible to use this API version. Refer to the Platforms section of our Platform & API Concepts documentation to learn which platform your API keys are on.

Examples

The following examples demonstrate common Conversations API display requests. For a complete overview of using the Conversations API to display data, refer to the Display tutorials.

🚧

Demonstration purposes only. Do not reuse the API passkeys below in your application.

Requesting all reviews for a particular product

This example call shows how to use multiple filters. This call only returns the reviews that have comments on them. The reviews are sorted in descending order by Rating.

https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&Filter=ProductId:data-gen-moppq9ekthfzbc6qff3bqokie&Sort=Rating:desc&Limit=10

Requesting all reviews for a particular product with review statistics (inc. average rating)

This example call shows how to use the include and stats parameters to retrieve product information and review statistics (including average rating). Note: Stats=Reviews must be used in conjunction with Include=Products.

https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&Filter=ProductId:data-gen-moppq9ekthfzbc6qff3bqokie&Include=Products&Stats=Reviews

Requesting a single review by review ID for a particular product

https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=id:16970607

You can request multiple reviews by separating the review IDs with a comma.

  • e.g. filter=id:83,84,85

Requesting a single review by review ID including product information for a particular product

https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=Id:16970607&include=Products

You can request multiple pieces of information by separating them with a comma.

  • e.g. Include=products,categories,authors

Requesting 20 reviews, sorted by rating in ascending order for a particular product

https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&Filter=ProductId:data-gen-moppq9ekthfzbc6qff3bqokie&Sort=Rating:desc&Limit=20

You can sort by multiple attributes by separating them with a comma - e.g. Sort=Rating:desc,SubmissionTime:asc

Requesting reviews using a filter and returning statistics for the filtered results for a particular product

https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&Filter=ProductId:data-gen-moppq9ekthfzbc6qff3bqokie&Include=Products&FilteredStats=Reviews&Filter=HasPhotos:eq:true

You can get statistics specific to the filter applied to a request using the "&FilteredStats" parameter

Requesting all native (non-syndicated) reviews

🚧

Native (non-syndicated) content only.

https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4

Requests for this content type that do not include a ProductId, AuthorId, CategoryAncestorId, SubmissionId, or Review Id filter will only work with API keys that are configured to exclude syndicated content.

We recommend using our Displayable Content Export service to download all of your native and syndicated content. If you still prefer the Conversations API, then you may contact our support team to have your Conversations API keys re-configured.

Requesting reviews for a product that is associated with a product family

https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&Filter=ProductId:data-gen-a718alq7rap86nqc7v05h304x&include=products

The product families feature allows you to share reviews among related products. Learn more about product families at the Bazaarvoice Knowledge Base.

The parameter “include=products” will result in the API returning product information in the response. This information can be used to identify about which product a review was originally written. Use the ‘ProductId’ field on
each review to look up the relevant product information in the “Includes.Products” object.

You will notice that several reviews in the response are associated with "Product4" despite using a filter in Request for ProductId:data-gen-a718alq7rap86nqc7v05h304. That’s because these products are in a product family. The ProductId:data-gen-a718alq7rap86nqc7v05h304 and Product4 are associated with a product family and therefore returning the reviews associated with both the products.

Parameters

NameDescriptionRequiredDefault Value
ApiVersionThe API version, e.g. 5.4.Yes
[FORMAT]Response format (json)Yes
PassKeyAPI key is required to authenticate API user and check permission
to access particular client's data.
Yes
AttributesAttributes to be included when returning content. For example,
if includes are requested along with the &attributes=ModeratorCodes parameter,
both the includes and the results will contain moderator codes. In order to
filter by ModeratorCode, you must request the ModeratorCodes attribute
parameter.
No
Callback Callback function name used with JSONP. Value is a string
consisting of the following characters: a-z,A-Z,0-9,_ (excluding comma). See the JSONP tutorial
for more information.
No
ExcludeFamilyBoolean flag indicating whether to exclude content from
other products in the same family as the requested product. For example,
"&filter=productid:eq:1101&excludeFamily=true" limits returned content to just
that of product 1101 and not any of the products in the same family. If a
value is not defined, content on all products in the family will be returned.
Nofalse
FilterFilter criteria for primary content of the query. Multiple filter
criteria are supported.
No
Filter_[TYPE]Filtering option for included nested content. TYPE can be
any included nested content. i.e. Comments for Reviews.
No
FilteredStatsStatistics based on the filters used to perform queries. The
filtered statistics are returned in their own block and can be returned any
place that a regular statistics block can be currently returned. Available
content types are: Reviews, Questions, Answers. Note: FilteredStats must be
used in conjunction with "Include=Products". The filtered stats block will be
identical to a regular stats block if a filtered stat is requested but a
filter has not been specified for the particular type of stat being requested.
No
IncentivizedStatsIf set to true, displays the number of incentivized reviews for each product or author returned in the response within an IncentivizedReviewCount element. This parameter must be used in conjunction with the Include parameter to include authors or products in the response, and also with the
FilteredStats or Stats parameters to include statistics for reviews in the response.
Nofalse
IncludeRelated subjects to be included (e.g. Products, Categories,
Authors, or Comments).
No
Limit Max number of records returned. An error is returned if the value
passed exceeds 100.
No10
Limit_[TYPE]Limit option for the nested content type returned. TYPE can
be any nested content. i.e. Comments for Reviews. An error is returned if the value passed exceeds 20.
No10
Locale Locale to display Labels, Configuration, Product Attributes and
Category Attributes in. The default value is the locale defined in the display associated with the API key.
No
OffsetIndex at which to return results. By default, indexing begins at 0
when you issue a query. Using Limit=100, Offset=0 returns results 0-99. When changing this to Offset=1, results 1-100 are returned. The maximum supported value is 300000.
No0
SearchFull-text search string used to find UGC. For more information
about what fields are searched by default, see the Display Fundamentals page.
No
Sort Sort criteria for primary content type of the query. Sort order is
required (asc or desc). Multi-attribute sorting for each content/subject type is supported.
No
Sort_[TYPE]Sorting option for nested content. Sort order is required (asc
or desc). TYPE can be any nested content. i.e. Comments for Reviews.
No
StatsThe type of statistics that will be calculated on included subjects.
Available content types are: Reviews, Questions, Answers. Note: Not all statistical content types apply to every possible include.
No

Filter options

  • Each filter argument specifies the attribute to filter on followed by a comma-separated list of values. For instance, "Filter=Rating:eq:3,4" will match all reviews with rating values 3 OR 4.
  • Advanced operators can be used to define filters. For instance, "Filter=Rating:lt:3" will match all reviews with a rating value less than 3. All advanced operators are documented on the Conversations API page.
  • If a filter value contains a comma or a colon, that character needs to be escaped with a backslash (, or :). If a filter value contains an ampersand (&), the ampersand must be encoded in the filter value by replacing & with %26.
  • Multiple filters are allowed as URL parameters in which case filters are AND'ed. For instance, "Filter=Rating:gte:4&Filter=IsFeatured:eq:true" will match all featured reviews with a rating of 4-star or higher.
  • Time-based filters can be used for SubmissionTime, LastModificationTime and LastModeratedTime. Dates in time-based filters are calculated as the number of seconds since January 1, 1970, 00:00:00 UTC. In a future version, we will be adding support for comparing date/time string values. The following example returns content that was submitted on November 9, 2009: &filter=SubmissionTime:gt:1257746400&filter=SubmissionTime:lt:1257832800

The following table lists the attributes available for filtering.

NameDescription
IdThe identifier of the Review.
AdditionalField_[FIELD_NAME]Additional field to filter by, e.g., filter=AdditionalField_[FIELD_NAME]:eq:[FIELD_VALUE]
AuthorIdThe identifier of the author who wrote the content
CampaignIdThe identifier of the Campaign associated with the content
CategoryAncestorIdThe identifier of the Product Category ancestor of the Product that the Review was written on. Syndicated content will not be returned when using this filter.
ContentLocaleLocale of the content to display. If this filter is not defined, all content regardless of its locale is returned. To return specific content by locale, define the value in the filter.

A wildcard character “” can be used to define the value, e.g., “en” returns all content in English (en_US, en_CA, en_GB, etc.) or you can use a single ContentLocale code (e.g., “fr_FR”).

ContentLocale codes are case-sensitive.
ContextDataValue_[DIMENSION_EXTERNAL_ID]The context data value for the content. DIMENSION_EXTERNAL_ID can be age, gender, etc. e.g. filter=contextdatavalue_age:under21
HasMediaBoolean flag indicating whether content has either photos or videos
HasPhotosBoolean flag indicating whether content has photos
HasTagsBoolean flag indicating whether content has tags
HasVideosBoolean flag indicating whether content has videos.
HelpfulnessHelpfulness represents how helpful a review has been to consumers. The Helpfulness value takes into account several factors including feedback votes and how many approved reviews an author has written. It will be a positive decimal value between 0 - 1.0, or null if not enough data exists to calculate it.
IsFeaturedBoolean flag indicating whether content is featured
IsRatingsOnlyBoolean flag indicating whether the review was a ratings only review
IsRecommendedBoolean flag indicating whether the user would recommend this product
IsSubjectActiveBoolean flag indicating whether the content subject is active
IsSyndicatedBoolean flag that allows you to select whether to return syndicated or non-syndicated reviews. If IsSyndicated:eq:true, the response only returns syndicated content and a SyndicationSource block with the details of where the syndication is coming from. If IsSyndicated:eq:false, the response only return native (non-syndicated) content. Note: The API key must be configured to show syndicated content.
LastModeratedTimeThe date/time of the latest moderation of the content. See the Introduction for an example of using advanced operators for filtering.
LastModificationTimeThe date/time of the latest modification of the content. See the Introduction for an example of using advanced operators for filtering.
ModeratorCodeString value indicating the moderator code for content that was at one time rejected e.g., &Filter=ModeratorCode:eq:CR returns UGC that contains the CR (Competitor Reference) code. Multiple codes can be entered in a comma-delimited list, e.g., &Filter=ModeratorCode:eq:CS,IU returns UGC with either the CS (Customer Service Complaint) or the IU (Inappropriate/Unusable Content) code. For a list of all Moderator Codes, see the Conversations API page. Note that the ModeratorCodes attribute parameter should be included in the request. This will ensure the moderated code(s) for each request will be included in the response. If the ModeratorCodes attribute is missing the filter will still perform, but there is not indication of which elements have been tagged with which codes. See the Parameters section above. A more detailed discussion on how moderation works can be found here.
ProductIdThe identifier of the Product that the Review was written on.
RatingThe Review Rating, usually between 1 to 5.
SecondaryRating_[RATING_NAME]Secondary rating value to filter by, e.g., filter=SecondaryRating_Durability:gte:1. Note: All advanced operators can be used for secondary ratings comparisons.
SubmissionIdSubmission identifier assigned to the content when it was initially submitted
SubmissionTimeThe submission date/time of the content. See the Introduction for an example of using advanced operators for filtering.
Tag_[TAG_NAME]The tag name to filter by, e.g., filter=tag_[TAG_NAME]:eq:[TAG_VALUE]
TotalCommentCountThe number of comments the Review has
TotalFeedbackCountNumber of feedbacks received
TotalNegativeFeedbackCountNumber of negative feedbacks received
TotalPositiveFeedbackCountNumber of positive feedbacks received
UserLocationLocation of the author

Sort options

  • Sort order is required (asc or desc). There is no default.
  • Multi-attribute sorting is supported by using a comma separated list of sort criteria for a content/subject type. e.g. Sort=Rating:asc,SubmissionTime:desc

The following table lists the attributes that are available for sorting.

NameDescription
IdThe identifier of the content/subject type
AdditionalField_[FIELD_NAME]Additional field to sort by, e.g., sort=AdditionalField_[FIELD_NAME]:desc
AuthorIdThe Identifier of the author who wrote the content
CampaignIdThe identifier of the Campaign associated with the content
ContentLocaleLocale value of the content.
Besides asc or desc, you can also specify the order of locales with ContentLocale. You can only specify up to 5 locales. Multi-attribute sorting is not supported with this customized order. For more information, please refer to the internationalization page.
ContextDataValue_[DIMENSION_EXTERNAL_ID]The context data value for the content. DIMENSION_EXTERNAL_ID can be age, gender, etc. e.g. sort=contextdatavalue_age:desc
HasPhotosBoolean flag indicating whether content has photos
HasTagsBoolean flag indicating whether content has tags
HasVideosBoolean flag indicating whether content has videos. For more information on inserting the returned VideoUrl into HTML, see the Conversations API page.
HelpfulnessHelpfulness represents how helpful a review has been to consumers. The Helpfulness value takes into account several factors including feedback votes and how many approved reviews an author has written. It will be a positive decimal value between 0 - 1.0, or null if not enough data exists to calculate it.
IsFeaturedBoolean flag indicating whether content is featured
IsRatingsOnlyBoolean flag indicating whether the review was a ratings only review
IsRecommendedBoolean flag indicating whether the user would recommend this product.
IsSubjectActiveBoolean flag indicating whether the content subject is active
IsSyndicatedBoolean flag indicating whether the content has been syndicated.
LastModeratedTimeThe date/time of the latest moderation of the content
LastModificationTimeThe date/time of the latest modification of the content
ProductIdThe identifier of the product
RatingThe Review Rating, usually between 1 to 5
SecondaryRating_[RATING_NAME]Secondary rating value to sort by, e.g., sort=SecondaryRating_Durability:desc
SubmissionIdSubmission identifier assigned to the content when it was initially submitted
SubmissionTimeThe submission date/time of the content
TotalCommentCountNumber of comments associated with the content
TotalFeedbackCountNumber of feedbacks received
TotalNegativeFeedbackCountNumber of negative feedbacks received
TotalPositiveFeedbackCountNumber of positive feedbacks received
UserLocationLocation of the author

Response format

This is a sample response for requesting reviews. Use the links above to see live examples.

{
    "Includes": { },
    "HasErrors": false,
    "Offset": 0,
    "TotalResults": 224775,
    "Locale": "en_US",
    "Errors": [ ],
    "Results": [
        {...}
        {...}
    ],
    "Limit": 2

}

Response elements

NameDescription
IncludesIncluded results related to primary results. For example, with the request reviews.json?include=Comments, the Include node will be populated with comments associated with the reviews in the Results node.
HasErrorsBoolean value indicated if one or more errors have occurred. See Errors below.
OffsetDataset offset used for pagination (passed as URL parameter in a query request). The maximum supported value is 300,000.
TotalResultsTotal number of records matched.
LocaleIndicates the language by region (language_region) associated with the client instance. This is the value used for field labels returned by the API, not the region from which the reviews originate.
ErrorsError section is populated instead of other fields if there is an error with a query syntax or problem executing a query.
ResultsSection containing an array of primitive type object references matched by a query.
LimitThe total number of results returned, specified by the user in the URL. Defaults to 10 and has a maximum of 100.

Error codes

ValueDescription
ERROR_ACCESS_DENIEDInsufficient privileges to perform the operation
ERROR_PARAM_INVALID_API_KEYInvalid API Key value
ERROR_PARAM_INVALID_CALLBACKInvalid JsonP callback function name
ERROR_PARAM_INVALID_FILTER_ATTRIBUTEInvalid filter attribute name
ERROR_PARAM_INVALID_INCLUDEDInvalid parameter value
ERROR_PARAM_INVALID_LIMITInvalid limit value
ERROR_PARAM_INVALID_LOCALEInvalid locale code
ERROR_PARAM_INVALID_OFFSETInvalid offset value
ERROR_PARAM_INVALID_SORT_ATTRIBUTEInvalid sort attribute name
ERROR_REQUEST_LIMIT_REACHEDRate limiting error, i.e. too many requests per time interval
ERROR_UNKNOWNUnknown error (internal server error, for instance)