Introduction

Keyword Filter is a feature in Conversations API that relies on Bazaarvoice Sentiment Analysis technology to extract category and product specific keywords for any product. It then allows you to filter reviews specific to any
keyword. This feature changes the way shopper find information by allowing them to focus their research on specific product characteristics called Keywords.

Keyword Filter Functionality

There are two steps to building 'Keyword Filter' experience

1. Retrieve the list of features associated with the product to display available keywords on the Product Pages

2. Filter the reviews for any keyword to allow consumers find relevant reviews mentioning the selected keyword

Retrieve Keywords or Features

Extracted via BV sentiment analysis technology, keywords or features are category and product specific attributes describing important aspects of the product.

The features or keywords are returned in descending order of the number of reviews mentioning the feature.

API Request schema for Features endpoint:

https://[stg].api.bazaarvoice.com/data/features?passkey=[PassKey]&productId=[ProductID]&language=[Language]

Languages – English (en), French (fr), and German (de) English (en) is the default if this parameter is not provided. You cannot pass multiple languages. Locales (ex- en_US, en_CA, fr_CA) are not supported. | No

API Response schema for Features endpoint (JSON format):

The api call would return Json data with the following key-value pair. The significance of each key-value is mentioned below:

Sample request/response for features endpoint:

• Pass the ‘language’ parameter in the request indicating the desired language of the features. If ‘language’ is not provided, features will be returned in English.
• Only English (en), French (fr), and German (de) are supported.

English:

https://[stg].api.bazaarvoice.com/data/features?passkey=[PassKey]&productId=[ProductID]

{
  "HasErrors": false,
    "Errors": [],
      "Results": [
        {
          "productId": "bar",
          "language": "en",
          "features": [
            {
              "feature": "for outdoors",
              "localizedFeature": "for outdoors"
            },
            {
              "feature": "satisfaction",
              "localizedFeature": "satisfaction"
            },
            {
              "feature": "color",
              "localizedFeature": "color"
            },
            {
              "feature": "purchase",
              "localizedFeature": "purchase"
            },
            {
              "feature": "quality",
              "localizedFeature": "quality"
            }
          ]
        }
      ]
}    

French:

https://[stg].api.bazaarvoice.com/data/features?passkey=[PassKey]&productId=[ProductID]&language=fr

        {
            "HasErrors": false,
            "Errors": [],
            "Results": [
    	        {
      	        "productId": "bar",
      	        "language": "fr",
      	        "features": [
        	     {
                 "feature": "for outdoors",
          	     "localizedFeature": "pour l'extérieur"
                 },
        	     {
          	     "feature": "satisfaction",
                 "localizedFeature": "la satisfaction"
        	     },
        	     {
          	     "feature": "color",
          	     "localizedFeature": "couleur"
                 },
        	     {
          	     "feature": "purchase",
          	     "localizedFeature": "achat"
        	     },
        	     {
          	     "feature": "quality",
          	     "localizedFeature": "qualité"
        	     }
      	         ]
            }
            ]
        }

How to filter reviews for any keyword or feature?

To filter reviews for any specific feature, you need to pass an additional parameter 'feature' = [feature] in Reviews.json. Please refer Bazaarvoice DeveloperPortal for more details on Reviews.json

API Request to filter reviews for a specific feature

https://[stg].api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey=[PassKey]&filter=ProductId:[ProductId]&locale=fr_FR&feature=[feature]

Note:

• When you try to search for reviews by passing [feature] in review.json endpoint, review search results returned will be an outcome of synthesized keywords based on our internal algorithm. It's not a verbatim keyword from the review. For instance, 'drying' is a feature it could return reviews with keyword ‘flaky’ or ‘dry’.
• Locale determines the locale of your website. Please ensure you pass correct value in the locale field to maintain consistency in the results.
• Feature parameter is only available to requests filtered by one product ID.
• The above API call results and PS API call results will differ because of their differing backend computational methods.

API Response with filtered reviews

The response schema of the reviews API remains the same. The response will now
return the reviews specific to the chosen feature. Please refer Bazaarvoice Developer Portal for more information on Reviews.json

Troubleshooting

The Conversations API always returns an HTTP 200 code, even when an error has occurred. If there is an error, we will include it in the body of the response. We do this so that applications using JSONP can access the error.

More troubleshooting tips here.More on errors here.