Conversations API: Retrieve and submit consumer-generated content (CGC), and retrieve your product catalog and statistics about your CGC.
Changelogs
The Conversations API lets you programmatically retrieve and submit Bazaarvoice Conversations data for use in your applications. To learn more, go to the Conversations API documentation home page.
Contents
This document lists changes between Conversations API versions.
v5.4 (Conversations)
Refer to 5.4 Conversations PRR & 5.4 Conversations to learn more about the two 5.4 API versions
Platform | Conversations |
---|---|
Released | 2016-08-29 |
-
XML response type no longer supported
All requests must use.json
. -
No "bulk requests" when syndication in enabled
If syndication is enabled on a key, requests using that key must always pass a single ProductId, ReviewId, AuthorId, or AncestorCategoryId as appropriate. -
Added properties to products.json response
"active": true|false
"disabled": true|false
-
New search engine
Search results will be faster, more useful, and may not be identical to search performed in previous versions. -
Legacy features
All features documented at Legacy Platform Features are no longer supported. -
Review search
Will only work with requests filtered by one product ID. -
Fixed duplicate badging issue
In cases where content and author have the same badge, only one badge will be returned. -
Reduced Question & Answer stats response
The left side of the graphic diff below shows the response from the previous version of the API and the right shows the current response.⚠The above diff has been ordered to make comparison easier. You should not rely on the order of elements in the API response. -
Removed support for following fields, filters and sorts
Search_[INCLUDE_TYPE]
filter=HasComments
sort=HasComments
filter=ProductBrandId
Search
Search_[CONTENT_TYPE]
Stats
filter=StoryId
sort=StoryId
Search_[CONTENT_TYPE]
filter=AdditionalField_[DIMENSION_ID]
sort=AdditionalField_[DIMENSION_ID]
filter=CategoryId
sort=CategoryId
filter=ContextDataValue_[DIMENSION_ID]
sort=ContextDataValue_[DIMENSION_ID]
filter=HasBrandAnswers
sort=HasBrandAnswers
filter=HasTags
sort=HasTags
filter=HasVideos
sort=HasVideos
filter=ProductBrandId
filter=Tag_[TAG_NAME]
sort=Tag_[TAG_NAME]
Search
Search_[CONTENT_TYPE]
filter=AdditionalField_[DIMENSION_ID]
sort=AdditionalField_[DIMENSION_ID]
filter=Affiliation
sort=Affiliation
filter=CategoryId
sort=CategoryId
filter=ContextDataValue_[DIMENSION_ID]
sort=ContextDataValue_[DIMENSION_ID]
filter=HasVideos
sort=HasVideos
filter=LastAnswerTime
sort=LastAnswerTime
filter=LastCommentTime
sort=LastCommentTime
filter=LastReviewTime
sort=LastReviewTime
filter=LastQuestionTime
sort=LastQuestionTime
filter=LastStoryTime
sort=LastStoryTime
filter=TotalCommentCount
sort=TotalCommentCount
filter=TotalStoryCount
sort=TotalStoryCount
Search_[CONTENT_TYPE]
filter=LastAnswerTime
sort=LastAnswerTime
filter=LastCommentTime
sort=LastCommentTime
filter=LastReviewTime
sort=LastReviewTime
filter=LastQuestionTime
sort=LastQuestionTime
filter=RatingsOnlyReviewCount
sort=RatingsOnlyReviewCount
filter=TotalStoryCount
sort=TotalStoryCount
Include
Limit_[CONTENT_TYPE]
Search
Search_[CONTENT_TYPE]
Stats
filter=LastAnswerTime
sort=LastAnswerTime
filter=LastQuestionTime
sort=LastQuestionTime
filter=LastStoryTime
sort=LastStoryTime
filter=TotalAnswerCount
sort=TotalAnswerCount
filter=TotalQuestionCount
sort=TotalQuestionCount
filter=TotalStoryCount
sort=TotalStoryCount
v5.4 (PRR)
Refer to 5.4 Conversations PRR & 5.4 Conversations to learn more about the two 5.4 API versions
Platform | PRR |
---|---|
Released | 2013-01-14 |
- Submission forms pre-filled for non-anonymous users
When submitting content, the values of all known submission fields are now returned in the submission response fields. This only affects submissions where the user is not anonymous and the user/userid parameter is provided with the GET request. -
Full text search on all UGC and on includes
The following content types were added to the existing search capabilities:- reviews
- answers
- comments (story and review)
- stories
-
Product family queries
When filtering by product id, all content from that product's product family is also returned by default. There is a new excludeFamily parameter that you can set to not return product family content. For examples and full documentation, see the Product Display method page.Filtered results excluding reviews for others products in the familyhttp://stg.api.bazaarvoice.com/data/products.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&filter=id:test1&excludeFamily=true&include=reviews
- Photo upload accepts URLs
The uploadphoto endpoint now accepts HTTP URLs of images in addition to locally stored photos from the client side. For examples and full documentation, see the Photo Submission method page. - Brightcove Smart Player Javascript integration
Brightcove videos can be loaded in a variety of ways. The information necessary to load these videos in the browser is now returned in the Videos block of the response elements. See the API Basics page for details on the new response items that were added to support Brightcove videos. -
Story rating field exposed in the response
The story display response has a new block called "StoryRating" that contains two fields:- Average score - average of the rating feedback score displayed for each story ID
- Range - range of the average score
-
Special product attributes exposed in the response
The product display response has new fields for each of the following five product attributes:- EANs
- UPCs
- ISBNs
- ModelNumbers
- ManufacturerPartNumbers
-
New filtering capabilities
The following new filters are available:- Affiliation badge filter on reviews
- Brand answer filters on questions and answers
- Product brand ID filter for reviews, stories, and questions
- Product brand ID filter for products
- Content locale filter inline ratings (statistics.json)
http://stg.api.bazaarvoice.com/data/answers.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&Filter:affiliation:staff
http://stg.api.bazaarvoice.com/data/questions.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&Filter=HasBrandAnswers:false
http://stg.api.bazaarvoice.com/data/answers.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&Filter=IsBrandAnswer:true
http://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&Include=Products&filter=productbrandid:neq:bazaarvoice
http://stg.api.bazaarvoice.com/data/products.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&filter=brandid:eq:null
http://stg.api.bazaarvoice.com/data/statistics.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&filter=productid:eq:test1&stats=NativeReviews,Reviews&filter=contentlocale:eq:en_US,es_MX,en_CA
v5.3 (PRR)
Platform | PRR |
---|---|
Released | 2012-08-03 |
- Hosted authentication - email
Hosted email authentication can be used during submission to confirm the identity of a content submitter. When submitting content for the first time, a user receives an email containing a link. When the link is clicked, the user is directed to a landing page that calls back to the API to confirm their identity. This call results in the generation of an encrypted user token that can be used in subsequent submission calls. Depending on your configuration, the submitter's content might not be accepted until the confirmation call is submitted. In order to use this feature, you must have hosted authentication enabled for your submission process. If you need more information, read the "Bazaarvoice hosted authentication reference guide" and the submission method documentation for details on the required parameters. - Feedback submission for comments
Feedback submission for review comments and story comments is now supported in addition to the existing support for feedback submission on reviews, questions, answers, and stories. For complete documentation, see the Feedback Submission method page. -
RatingDistribution and SecondaryRatingsAverages added to review statistics
New RatingDistribution and SecondaryRatingsAverages blocks have been added to the ReviewStatistics block. You can now see the distribution of ratings for each product, which allows you to construct a rating histogram. You can also see the average rating of your secondary rating dimensions for reviews in relation to products and authors. -
Error codes added to form errors
The API response has been updated to return error codes in addition to the existing error message for all form errors. A complete listing of the error codes can be found in each submission method. -
Syndication attribution on reviews
All reviews have an "isSyndicated" field set to true or false. If the review is syndicated, a SyndicationSource block is displayed with details of where the review is being syndicated from. Syndicated content can only be returned if the API key is configured to show syndicated content.
v5.2 (PRR)
Platform | PRR |
---|---|
Released | 2012-06-01 |
- Helpfulness and inappropriate feedback
Submission of helpfulness votes and inappropriate feedback can now be done through the API. The response for the user-generated content has also been updated to display the actual inappropriate feedback and total vote and feedback counts. In order for inappropriate feedback to be populated, the API key must be updated. - Implicit default ContentLocale filter removed
There is no longer any implicit ContentLocale filter if none is specified as an argument. If no filter is provided, all content will be returned, regardless of what locale the content is in. There is a default locale defined for every API key. Prior to version 5.2, if the locale parameter was used, it caused an implied ContentLocale filter to be used. Note that version 5.2 does not change the behavior of explicitly supplied ContentLocale filters. In addition, you can now ask for labels in any locale and specify a different content locale. Therefore, if you request a locale of en_US and a ContentLocale of fr_FR, you get English labels and French content. - Product and category attributes
Products and categories now have a new attributes field populated. This field contains a map of attributes provided to Bazaarvoice from a product feed import. - Hosted video submission and display
Video elements of all content now contain URLs that can be used to embed the video into an HTML page. Bazaarvoice provides boilerplate HTML tags for use with embedding these videos. For more information, see the API Basics page. - Inline ratings data
A new method has been created to provide a quick way to access inline ratings data for products. For complete documentation, see the Statistics Display method page.
v5.1 (PRR)
Platform | PRR |
---|---|
Released | 2012-02-14 |
-
ReviewStats
Review statistics for Products now returns ReviewStats, which account for product family data in the statistics calculations. Prior to version 5.1, the ReviewStats were returning NativeStats, which do not take product families into account. -
Moderator Codes
Moderator codes (content codes) can now be explicitly requested and filtered. A new filter (ModeratorCode) has been added and can accept any moderator code values. For a list of all moderator codes, see the API Reference section. In addition, a new value for the attribute parameter (ModeratorCodes) has been added. Filtered results will be returned if only the filter is added. Including the ModeratorCodes attribute along with the filter will both filter the results and expose the moderated codes.Filters results for moderated codehttp://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.1&passkey=kuy3zj9pr3n7i0wxajrzj04xo&filter=ModeratorCode:IU
Filters results for moderated code and while displaying the codeshttp://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.1&passkey=kuy3zj9pr3n7i0wxajrzj04xo&filter=ModeratorCode:IU&attributes=ModeratorCodes
- Wildcard character in ContentLocale filter
The ContentLocale filter now accepts the asterisk (‘*’) as a wildcard character. This wildcard character represents zero or more characters. Adding the wildcard enables filtering for multiple locales without requiring each one to be listed. For example, &Filter=ContentLocale:eq:en* would return all the English locales (en_US, en_CA, en_GB, etc.). When the ContentLocale filter is set to the wildcard character, it is the equivalent of requesting all locales. It is important to note that the value of the filter cannot start with a wildcard filter. For example, &Filter=ContentLocale:eq:*_US is not a valid filter. - IP address in Content Display
When the API key is configured to allow access to IP addresses, you will either get the IP address back or null inside the IpAddress element. If you are interested in getting access to IP address within an application, contact technical support.
v5.0 (PRR)
Platform | PRR |
---|---|
Released | 2011-10-11 |
- Results XML changes
In the XML response, the Results element has dropped the list of containing element (Reviews/Comments/Stories) and now includes the content elements directly. -
SecondaryRatings changed
SecondaryRatings/RatingValue is renamed to SecondaryRatings/SecondaryRating. SecondaryRating/Rating is renamed to SecondaryRating/Value. SecondaryRating/Label is renamed to SecondaryRating/ValueLabel. SecondaryRating/Label1 is renamed to SecondaryRating/MinLabel. SecondaryRating/Label2 is renamed to SecondaryRating/MaxLabel. SecondaryRating/Label is now returned as the label of the SecondaryRating dimension. The JSON response returns a Map of SecondaryRating elements instead of an array. - ContextDataValues changed
Context Data Values are flipped inside-out and flattened in the XML format. The JSON format includes label information. -
Badges changed
Badge/Name is renamed to Badge/Id and Badges are returned as a map instead of an array in JSON. -
"Order" arrays in JSON response included
For each "Lists" of elements that are returned as a map instead of an array in JSON (Includes/*, ContextDataValues, AdditionalFields, SecondaryRatings, TagDimensions, ...) an array with the same name as the map with "Order" added as a suffix is returned with the original order of the elements in the list. - Nulls in the JSON responses
The JSON response now returns a value for all fields possible. If a value is not explicitly set, a null value is returned ([] for JSON array types, {} for JSON object types, null for primitive types). - Submission format changed
The XML format has been flattened to match the JSON format more closely. -
UserNickname returned for Reviews
UserNickname is now returned for Reviews. -
DisplayLocale is renamed to ContentLocale
When querying for content (Reviews, Stories, Questions, Answers, ReviewComments, StoryComments) the default behavior in 5.0 (4.9 remains unchanged) is to now return only content in the locale requested (default or specified). This can be overriden to return content for a specific locale by using the contentlocale filter attribute. The special value "all" for the contentlocale filter returns content in all locales. *Note that Authors the behavior remains unchanged and all Authors are returned by default, regardless of their locale.Returns content for all localeshttp://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.0&passkey=kuy3zj9pr3n7i0wxajrzj04xo&filter=ContentLocale:all
Returns content for 'en_US'http://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.0&passkey=kuy3zj9pr3n7i0wxajrzj04xo&filter=ContentLocale:en_US
Returns content for locales not equal to 'en_US'http://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.0&passkey=kuy3zj9pr3n7i0wxajrzj04xo&filter=ContentLocale:neq:en_US
Returns content for default local, in this case 'en_US'http://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.0&passkey=kuy3zj9pr3n7i0wxajrzj04xo
- Locale parameter now available
Both query and submission API now accept the new 'locale' top-level parameter to get Labels, Configuration, Product Attributes, Category Attributes in that locale. Note that the particular locale has to have been configured or the response will be ERROR_PARAM_INVALID_LOCALE - User token no longer needed for submission
The cleartext user id parameter ("userid") can be used to as part of submission. -
Campaign ID is now returned in repsonses
Campaign ID is now returned as part of the XML/JSON response for all appropriate content types. -
Advanced Operators
Advanced operators are supported. The following is a list of the supported operators (gt, gte, lt, lte, eq, and neq)http://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.0&passkey=kuy3zj9pr3n7i0wxajrzj04xo&Filter=ProductId:1000001&Filter=Rating:lt:3
Operator Description Allowable Field Types Example gt
greater than (>) numeric fields filter=rating:gt:4
gte
greater than or equal to (>=) numeric fields filter=rating:gte:4
lt
less than (<) numeric fields filter=rating:lt:4
lte
less than or equal to (<=) numeric fields filter=rating:lte:4
eq
equal to (==) numeric, boolean or string fields filter=rating:eq:4
orfilter=rating:4
(supported for backward comapatibility)neq
not equal to (!=) numeric, boolean or string fields filter=rating:neq:4
- More filter and sort fields
Additional filters and sorts is now supported for "Tags", "Secondary Ratings", "Additional Fields", "Campaign ID", "TimeStamps"
v4.9 (PRR)
Platform | PRR |
---|---|
Released | 2011-08-0 |
The 4.9 release is considered the first release out of BETA. There are too many API changes to document them all. The following are some of the more significant changes from the previous development release.
- Renamed "Data" element to "Includes"
To be more consistent with the name of the "includes" request parameter, we are renamed the "data" response element to "includes" and denormalized the results section of the response. - Renamed various fields
To be more consistent we have renamed various fields to conform to our naming convention. - IsFeatured returned for supported content types
IsFeatured is now returned for Answers, Questions and Stories - ProductReferences renamed
ProductReferences are renamed to ProductRecommendationIds and now only includes the Id for the products being recommended instead of the entire Product Definition inline. - Tags content was flattened
Responses in tags content was shortened - RatingValues renamed
RatingValues renamed to SecondaryRatings and structure flattened - Submission Fields renamed
Submission fields were renamed to match query response fields and to conform to our naming convention - Display Code removed from URL
The display code is no longer part of the Data API URL. - Comment URL Changes
Comments are now accessible as either Review Comments or Story Comments. This changed on the query URL changes, the submission URL changes, and the media upload URL