Search form

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

(+ show- hide)

This document lists changes between Conversations API versions.

⚠
The following changelogs reference features which are only available to clients on our Conversations PRR platform. Refer to Conversations PRR Only Features for more information.

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
    All content is now searchable. For a list of all the fields that are searched for any given content type, see full text searching documentation on the API Basics page.
  • 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 family 
    http://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
    API version 5.3
    API version 5.4
    API version 5.3
    API version 5.4
  • 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.
    API version 5.2
    API version 5.3
    API version 5.2
    API version 5.3
  • 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.
    API version 5.2
    API version 5.3
  • 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.
    Syndication enabled
    Syndicated disabled

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.
    API version 5.0
    API version 5.1
    API version 5.0
    API version 5.1
  • 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 code 
    http://stg.api.bazaarvoice.com/data/reviews.json?apiversion=5.1&passkey=kuy3zj9pr3n7i0wxajrzj04xo&filter=ModeratorCode:IU
    Filters results for moderated code and while displaying the codes 
    http://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.
    API version 4.9
    API version 5.0
    API version 4.9
    API version 5.0
  • 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.
    API version 4.9
    API version 5.0
    API version 4.9
    API version 5.0
  • "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.
    API version 4.9
    API version 5.0
  • 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.
    API version 4.9
    API version 5.0
    API version 4.9
    API version 5.0
  • 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 locales 
    http://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.
    API version 4.9
    API version 5.0
    API version 4.9
    API version 5.0
  • 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 or filter=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