Introduction

Custom Question Filter is a feature in Conversations API that allows shoppers to find most relevant reviews according to the past answers to the Review form questions. This is a great way for shoppers to focus on reviews written by other shoppers who share common intent, preference or characteristics.

Configuring Custom Questions

Configuring questions on your review submission form is the first step to build a Custom Question Filter. Bazaarvoice offers various types of question types to be configured in Configuration Hub - single choice, multiple choice, free text or in the form of ratings. Click Adding or customizing submission form questions to know more.

Following three question types are in scope of Custom Question Filter-

Context Data Value (CDV) or Dropdown Select are single choice questions to receive a single response for the question.
Tag Groups are multiple choice questions to receive more than one response for the question.
Secondary Ratings/Slider allows you to collect responses in the form of a rating scale.

Creating Custom Question Filters and Filtering Reviews

The response schema of the reviews API remains the same. The response will now return additional statistics in the ReviewStatistics and/or FilteredReviewStatistics section. Please refer to Review Display for more information on Reviews.json.

For the questions you configure, you will receive following additional attributes in the API response

Count of how many consumers have chosen a particular answer option, i.e., the number of reviews it occurs
Localized Labels to match your localization needs

Context Data Values/Dropdown Select

1.Creating Filter on Context Data

Context Data Value statistics are included with include=products&Stats=Reviews in the API request. If there are no reviews for any answer choice, it will be skipped.

Sample API Request to Create a Filter

https://[stg].api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey={PassKey}&Filter=productId:{ProductID}&Include=products&Stats=reviews

Sample API Response

Includes": {
 "Products": {
         …
          "ReviewStatistics": {
            "ContextDataDistribution": {
                SkinType": {
                    "Id": "SkinType",
                    "Values": [
                        {
                        "Count": 60,
                        "Value": "Normal"
                        "ValueLabel": "Normal"
                        },
                        {
                        "Count": 267,
                        "Value": "Combination"
                        "ValueLabel": "Combination"
                        },
                        {
                        "Count": 131,
                        "Value": "DrySkinFace"
                        "ValueLabel": "Dry Skin Face"
                        },
                        {
                        "Count": 260,
                        "Value": "DrySkinBody"
                        "ValueLabel": "Dry Skin Body"
                        },
                        {
                        "Count": 29,
                        "Value": "Oily"
                        "ValueLabel": "Oily"
                        },
                        {
                        "Count": 114,
                        "Value": "Sensitive"
                        "ValueLabel": "Sensitive"
                        }
                        ],
                        "Label": "Skin Type"
                            },
                            …
                            },
                            …
                        }
                    …
                }
            …
        }
    …

2. Filtering Reviews On Content

You can filter the reviews for any specific ‘Context Data Value’ using Filter=ContextDataValue_[Id]:eq:[Value].

In the above sample response, [Id]=SkinType and [Value]= Normal, Combination, DrySkinFace, DrySkinBody, Oily, Sensitive.

To know more on Filter Options, click here.

Sample API Request to filter reviews

https://[stg].api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey={PassKey}&Filter=ProductId:{ProductID}&Include=products&Stats=reviews&Filter=ContextDataValue_SkinType:eq:Oily

The response schema of the reviews API remains the same. The response will now return the filtered reviews specific to the chosen Context Data Value. Please refer to Review Display for more information on Reviews.json

API Response schema(JSON format)

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

Key	Value
ID	ID of the question
Label	Label of the Question to be used for displaying purpose. This will be localized.
Values	Array of Answer choices for the question.
Value	ID of the Answer choice.
Value Label	Label of the Answer choice to be used for displaying purpose. This will be localized.
Count	Number of reviews with the particular Answer choice.

Tag Groups

1. Creating Filter on Tag Group

Tag Group statistics is a flag based feature. They are included in the API response with include=products&Stats=Reviews&TagStats=true in the request. If there are no reviews for any answer choice, it will be skipped.

NOTE : ⏰ Only the top 10 tags will be returned in descending order of reviews associated with the tags/answer choices.

Sample API request to create filter

https://[stg].api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey={PassKey}&Filter=productId:{ProductID}&Include=products&Stats=reviews&TagStats=true

Sample API Response

Includes": {
    "Products": {
         …
        "ReviewStatistics": {
           "TagDistribution": {
               "Pro": {
                   "Id": "Pro",
                       "Values": [
                           {
                           "Value": "dry skin",
                           "Count": 715
                               },
                           {
                           "Value": "healthy aging",
                           "Count": 478
                               },
                           {
                           "Value": "cracked, chafed skin",
                           "Count": 469
                           },
                           {
                           "Value": "itchy skin",
                           "Count": 450
                           },
                           {
                           "Value": "Rough & Bumpy skin",
                           "Count": 360
                           },
                           {
                           "Value": "eczema-prone skin",
                           "Count": 281
                           },
                           {
                           "Value": "sun protection",
                           "Count": 221
                           },
                           {
                           "Value": "acne-prone skin",
                           "Count": 200
                           },
                           {
                           "Value": "psoriasis-prone skin",
                           "Count": 162
                           }
                           ]
                           "Label": "Pro"
                           }
                        },
                     }
                  …
                 }
             }
	...

2. Filtering reviews on Tag Group

You can filter the reviews for any specific 'Tag Group' using Filter=Tag_[TAG_NAME]:eq:[TAG_VALUE]

In the above sample response, [TAG_NAME]=Pro, and [TAG_VALUE]= dry skin; healthy aging; cracked, chafed skin; itchy skin; Rough & Bumpy skin; etc.

To know more on Filter Options, click here

Sample API Request to filter reviews

https://[stg].api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey={PassKey}&Filter=productId:{ProductID}&Include=products&Stats=reviews&TagStats=true&Filter=Tag_Pro:eq:dry%20skin

The response schema of the reviews API remains the same. The response will now return the filtered reviews specific to the chosen Tag Group. Please refer to Review Display for more information on Reviews.json.

API Response Schema (JSON format)

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

Key	Value
ID	ID of the question
Label	Label of the Question to be used for displaying purpose. This will be localized.
Values	Array of Answer choices for the question.
Value	Label of the Answer choice to be used as an identifier and for displaying purpose. This will be localized.
Count	Number of reviews with the particular Answer choice.

Secondary Ratings or Slider

1.Creating filter on Secondary Rating/Slider

Secondary Ratings or Slider statistics is a flag based feature. They are included in the API response with include=products&Stats=Reviews&SecondaryRatingStats=true in the request. If there are no reviews for any answer choice, it will be skipped.

Sample API Request to Create Filter

https://[stg].api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey={PassKey}&Filter=productId:{ProductID}&Include=products&Stats=reviews&SecondaryRatingStats=true

Sample API Response

Includes": {
 "Products": {
    …
    "ReviewStatistics": {
        "SecondaryRatingsDistribution": {
            "Quality": {
                Id": "Quality",
                "Values": [
                    {
                    "Value": 5,
                    "Count": 417
                    },
                    {
                    "Value": 4,
                    "Count": 63
                    },
                    {
                    "Value": 1,
                    "Count": 20
                    },
                    {
                    "Value": 3,
                    "Count": 15
                    },
                    {
                    "Value": 2,
                    "Count": 11
                    }
                    ],
            "Label": "Quality"
                },
                "Fit": {
                "Id": "Fit",
                "Values": [
                {
                    "Value": 4,
                    "Count": 240,
                    "ValueLabel": "Slightly Large"
                    },
                    {
                    "Value": 3,
                    "Count": 186,
                    "ValueLabel": "True to Size"
                    },
                    {
                    "Value": 5,
                    "Count": 122,
                    "ValueLabel": "Runs Large"
                    },
                    {
                    "Value": 1,
                    "Count": 4,
                    "ValueLabel": "Runs Small"
                    },
                    {
                    "Value": 2,
                    "Count": 2,
                    "ValueLabel": "Slightly Small"
                    }
                    ],
                    "Label": "Overall fit"
                    },
                    …
                }
            …
 
            "SecondaryRatingsAverages": {
                "Fit": {
                    "Id": "Fit",
                    "AverageRating": 3.8555956678700363,
                    "DisplayType": "SLIDER",
                    "ValueRange": 5,
                    "MaxLabel": "Runs Large",
                    "MinLabel": "Runs Small",
                    "Label": "Overall fit",
                    "ValueLabel": [
                        "Runs Small",
                        "Slightly Small",
                        "True to Size",
                        "Slightly Large",
                        "Runs Large"
                        ]
                        },
            "Quality": {
                "Id": "Quality",
                "AverageRating": 4.608365019011407,
                "ValueRange": 5,
                "DisplayType": "NORMAL",
                "MaxLabel": null,
                "MinLabel": null,
                "Label": "Quality"
                }
            },
        …
    }
…

2. Filtering Reviews on Secondary Rating/Slider

Further, you can filter the reviews for any specific 'Secondary Rating' using Filter=SecondaryRating_[Id]:eq:Value

In the above sample response, [Id]=Quality, Fit, and [Value]=1, 2, 3, 4, 5

NOTE: ⏰ All advanced operators can be used for secondary ratings comparisons. Example: eq, lte, gte, lt, gt

To know more on Filter Options, click here.

Sample API Request to filter reviews

https://[stg].api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey={PassKey}&Filter=productId:{ProductID}&Include=products&Stats=reviews&SecondaryRatingStats=true&Filter=SecondaryRating_Quality:gte:3

The response schema of the reviews API remains the same. The response will now return the filtered reviews specific to the chosen Secondary Rating.Please refer to Review Display for more information on Reviews.json.

API Response schema(JSON format)

Key	Value
ID	ID of the question
Label	Label of the Question to be used for displaying purpose. This will be localized.
Values	Array of Answer choices for the question.
Value	ID of the Answer choice.
Value Label	Label of the Answer choice to be used for displaying purpose. This will be localized. Only present for Slider.
Count	Number of reviews with the particular Answer choice.

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, HasErrors=True. We do this so that applications using JSONP can access the error.

More troubleshooting tips here
More on errors here

Appendix

An Example in French

https://[stg].api.bazaarvoice.com/data/reviews.json?apiversion=5.4&passkey={PassKey}&Filter=productId:{ProductID}&Include=products&Stats=reviews&SecondaryRatingStats=true

"ReviewStatistics": {
        "ContextDataDistributionOrder": [
        "LengthOfOwnership",
        "HauteurDeLaPersonne",
        "Poids"
        ],
          "ContextDataDistribution": {
            "LengthOfOwnership": {
              "Id": "LengthOfOwnership",
              "Values": [
                {
                "Count": 13,
                "Value": "1week",
                "ValueLabel": "1 semaine"
                },
                {
                "Count": 20,
                "Value": "1month",
                "ValueLabel": "1 mois"
                }
                ],
              "Label": "J'ai ce produit depuis environ"
            },
            "HauteurDeLaPersonne": {
              "Id": "HauteurDeLaPersonne",
              "Values": [
                {
                  "Count": 10,
                  "Value": "de155A159Cm",
                  "ValueLabel": "de 155 à 159 cm"
                },
                {
                  "Count": 12,
                  "Value": "de160A164Cm",
                  "ValueLabel": "de 160 à 164 cm"
                },
                {
                  "Count": 18,
                  "Value": "de165A169Cm",
                  "ValueLabel": "de 165 à 169 cm"
                },
                {
                  "Count": 6,
                  "Value": "de170A174Cm",
                  "ValueLabel": "de 170 à 174 cm"
                }
              ],
            "Label": "Taille:"
            },
            "Poids": {
              "Id": "Poids",
              "Values": [
                {
                  "Count": 14,
                  "Value": "de50A54Kg",
                  "ValueLabel": "de 50 à 54 kg"
                },
                {
                  "Count": 12,
                  "Value": "de55A59Kg",
                  "ValueLabel": "de 55 à 59 kg"
                },
                {
                  "Count": 8,
                  "Value": "de70A74Kg",
                  "ValueLabel": "de 70 à 74 kg"
                }
              ],
            "Label": "Poids:"
            }
          },
…
 
"SecondaryRatingsDistributionOrder": [
        "Value",
        "Styleduproduit",
        "Matire",
        "Fit_22"
        ],
    "SecondaryRatingsDistribution": {
            "Fit_22": {
            "Id": "Fit_22",
            "Values": [
            {
                "Value": 3,
                "Count": 12,
                "ValueLabel": "Normalement"
                },
                {
                "Value": 4,
                "Count": 12,
                "ValueLabel": "Un peu grand"
                },
                {
                "Value": 5,
                "Count": 10,
                "ValueLabel": "Trop grand"
                }
              ],
        "Label": "Comment taille ce produit ?"
            },
            "Styleduproduit": {
              "Id": "Styleduproduit",
              "Values": [
                {
                "Value": 5,
                "Count": 13
                },
                {
                "Value": 4,
                "Count": 10
                }
                ],
        "Label": "Style du produit"
            },
            "Matire": {
            "Id": "Matire",
            "Values": [
            {
            "Value": 5,
            "Count": 3
            },
            {
            "Value": 4,
            "Count": 6
            }
            ],
            "Label": "Matière"
                },
                "Value": {
                "Id": "Value",
                "Values": [
                {
                "Value": 5,
                "Count": 4
                },
                {
                "Value": 4,
                "Count": 1
                }
                ],
        "Label": "Rapport qualité-prix"
            }
          },
         …
 
          "SecondaryRatingsAveragesOrder": [
            "Value",
            "Styleduproduit",
            "Matire",
            "Fit_22"
          ],
          "SecondaryRatingsAverages": {
            "Value": {
              "Id": "Value",
              "AverageRating": 4.8,
              "DisplayType": "NORMAL",
              "MaxLabel": null,
              "ValueRange": 5,
              "MinLabel": null,
              "Label": "Rapport qualité-prix"
            },
            "Styleduproduit": {
              "Id": "Styleduproduit",
              "AverageRating": 4.75,
              "DisplayType": "NORMAL",
              "MaxLabel": null,
              "ValueRange": 5,
              "MinLabel": null,
              "Label": "Style du produit"
            },
            "Matire": {
              "Id": "Matire",
              "AverageRating": 4.75,
              "DisplayType": "NORMAL",
              "MaxLabel": null,
              "ValueRange": 5,
              "MinLabel": null,
              "Label": "Matière"
            },
            "Fit_22": {
              "Id": "Fit_22",
              "AverageRating": 3.8,
              "DisplayType": "SLIDER",
              "ValueRange": 5,
              "MaxLabel": "Grand",
              "MinLabel": "Petit",
              "Label": "Comment taille ce produit ?",
              "ValueLabel": [
                "Trop petit",
                "Un peu petit",
                "Normalement",
                "Un peu grand",
                "Trop grand"
              ]
            }
          },
…