Introduction

We're thinking about the future of the Conversations API and we want you to be prepared. Your applications will be easier to upgrade to future API releases if you avoid the features below.

The following section describes features that will either not be available in future releases of the Conversations API or its successors or continue to be available, but with different functionality and/or altered behavior.

Keyword Filter Deprecation | Transition to Product Sentiments API

The keyword Filter personalization feature, as part of Conversations API is now marked for deprecation. Clients are advised to implement the Product Sentiment API Features endpoint for retrieving product related features based on the UGC. Please refer here for the API Reference for the Product Sentiment API.

Transition to Product Sentiments API

The Product Sentiment API serves as a backend service that enables clients to retrieve top features (both best and worst), top quotes, product features, and expressions content associated with their product catalog.

It provides a backbone for building pros/cons feature lists based on client reviews, quote highlights, and keyword filtering to inform customers about product features based on customer reviews.

What is the difference?

The only change required in the impacted implementations (Using keyword Filter instead of Product Sentiments API), would be on the initial API call to retrieve the features. It is still needed to additionally pass the Feature filter in the Conversations API call to retrieve the related UGC.

While both services offer keyword/feature functionality, the Product Sentiment API appears to be a more comprehensive solution that not only identifies features but also provides sentiment analysis (pros/cons), quote highlights, and more structured product feature information.

The Product Sentiment API is designed as a dedicated service for sentiment analysis and feature extraction, whereas the Keyword Filter is a feature within the broader Conversations API.

As the Features endpoint on Conversations API is up for deprecation, we implore existing and potential clients to use the Product Sentiments API instead.

Keyword Filter vs Product Sentiments API?

The Keyword Filter in Conversations API uses Bazaarvoice Sentiment Analysis technology to extract category and product-specific keywords for any product, allowing users to filter reviews specific to any keyword.

This feature changes how shoppers find information by enabling them to focus their research on specific product characteristics.

📘

Please reach out to your Bazaarvoice representative or raise a query via Support for more details on Product Sentiments API and its supporting endpoints.

Not available in future releases

BMP image format

The Photo Upload endpoint no longers accepts BMP images.

XML content-type

🚧

Using .xml is prohibited by our Conversations API Terms of Use - 4. Requirements and has been disabled for API keys issued after August 29th, 2016.

Future releases of the Conversations API will not support returning responses formatted as XML. Instead you should use JSON or JSONP. The following examples demonstrate future compatible and incompatible requests:

Incompatible

GET https://stg.api.bazaarvoice.com/data/reviews.xml?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&
Filter=ProductId:[PRODUCT_ID]

Compatible

JSON

GET https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]
&Filter=ProductId:[PRODUCT_ID]

JSONP

GET https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]
&Filter=ProductId:[PRODUCT_ID]&callback=[CALLBACK_FUNCTION]

UGC requests that do not specify a single product id equality filter

Future Conversations API releases will be optimized to support displaying UGC about a single product on that product's PDP. As a result the API will be limited to returning content for one product per request. This applies to reviews, questions, answers and comments. The following examples demonstrate future compatible and incompatible requests:

Incompatible

GET https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]

GET https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]
&Filter=ProductId:[PRODUCT_ID-1,PRODUCT_ID-2,PRODUCT_ID-N]

Compatible

GET https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]
&Filter=ProductId:[PRODUCT_ID]

GET https://stg.api.bazaarvoice.com/data/reviews.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&
Filter=ProductId:eq:[PRODUCT_ID]

Altered functionality in future releases

Product and category requests that do not identify a product or category ID equality filter

Requesting products or categories without knowing the IDs in advance will not be supported in future releases of the Conversations API. As a result, paginating through multiple product or category result sets using Limit and Offset will also not be supported.

Bazaarvoice gets product and category information from our clients, so we expect that our clients have access to those IDs (because we get the IDs from them). If you are working on behalf of one of our clients, you should ask them to give you access to their IDs.

Incompatible

GET http://stg.api.bazaarvoice.com/data/products.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]

GET http://stg.api.bazaarvoice.com/data/products.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&
Limit=100&Offset=0

GET http://stg.api.bazaarvoice.com/data/categories.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&
Limit=100&Offset=100

compatible

GET https://stg.api.bazaarvoice.com/data/products.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&
filter=ProductId:[PRODUCT_ID]

GET https://stg.api.bazaarvoice.com/data/categories.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&
filter=CategoryId:eq:[CATEGORY_ID]

Product and category requests that identify multiple IDs are future compatible.

GET https://stg.api.bazaarvoice.com/data/products.json?apiversion=[LATEST_VERSION]&passkey=[API_KEY]&
filter=ProductId:[PRODUCT_ID-1,PRODUCT_ID-2,PRODUCT_ID-N]

Field labels removed from display responses

Newer releases of the Conversations API will not include text labels is display responses. API consumers are encouraged to create and host labels just as they would any other aspect of their user interface. The following elements will not be populated with meaningful values in upcoming API releases:

• Label
• MaxLabel
• MinLabel
• ValueLabel

In the graphic diff below, the left side shows the response from the current version of the Conversations API and the right represents the response from a newer, not yet released version.

🚧

The above diff has been ordered to make comparison easier. You should not rely on the order of elements in the API response.

If you need to use the labels hosted by Bazaarvoice, there are several future compatible options:

• Clients on our Conversations platform can look up field labels by logging into their Bazaarvoice portal, opening the Configuration Hub (Settings -> Manage Applications), selecting a deployment zone, and navigating to the "Submission Form Editor" tab.
• The submission response will continue to include labels. See the Submission Fundamentals tutorial to learn how to use the submission request to get form meta-data, including field labels.
• Contact Bazaarvoice Support to ask for the field labels.

Reduced categories.json data

Future releases of the Conversations API will return less category data than the current release. The following elements will not be populated with meaningful values in upcoming API releases:

• Attributes
• AttributesOrder
• ProductIds
• QuestionIds
• StoryIds

In the graphic diff below, the left side shows the response from the current version of the Conversations API and the right represents the response from a newer, not yet released version.

🚧

The above diff has been ordered to make comparison easier. You should not rely on the order of elements in the API response.

Limited questions and answers statistics

Future Conversations API releases will provide less detailed question and answer statistics. The following elements will not be populated with meaningful values in upcoming API releases:

• AnswerHelpfulVoteCount
• AnswerNotHelpfulVoteCount
• BestAnswerCount
• ContextDataDistribution
• ContextDataDistributionOrder
• FeaturedAnswerCount
• FeaturedQuestionCount
• FirstAnswerTime
• FirstQuestionTime
• HelpfulVoteCount
• LastAnswerTime
• LastQuestionAnswerTime
• LastQuestionTime
• QuestionHelpfulVoteCount
• QuestionNotHelpfulVoteCount
• TagDistribution
• TagDistributionOrder

In the graphic diff below, the left side shows the response from the current version of the Conversations API and the right represents the response from a newer.

🚧

The above diff has been ordered to make comparison easier. You should not rely on the order of elements in the API response.