Statistics Display
Returns Product-based Review Statistics and Questions & Answers Statistics. This method has been optimized and is created for inline ratings display.
Only API keys on our Conversations platform are eligible to use this API version. Refer to the Platforms section of our Platform & API Concepts documentation to learn which platform your API keys are on.
Try out Statistics Display API reference here.
Examples
Demonstration purposes only. Do not reuse the API passkeys below in your application.
Requesting native review statistics for one product
https://stg.api.bazaarvoice.com/data/statistics.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=productid:data-gen-2s9kaf0ugzn0p2flzl73ahuys&stats=NativeReviews
Requesting review statistics for one product
https://stg.api.bazaarvoice.com/data/statistics.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=productid:data-gen-2s9kaf0ugzn0p2flzl73ahuys&stats=Reviews
Requesting native review and review statistics for one product
https://stg.api.bazaarvoice.com/data/statistics.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=productid:data-gen-2s9kaf0ugzn0p2flzl73ahuys&stats=Reviews,NativeReviews
Requesting native review and review statistics for multiple products
https://stg.api.bazaarvoice.com/data/statistics.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=productid:data-gen-2s9kaf0ugzn0p2flzl73ahuys,data-gen-td50ixwh9pmjispxbwtely59d,data-gen-3jxhm78sfqfy8tg5qyinqioal,data-gen-ov7cr69sakbegasbhejikf0q0&stats=NativeReviews
Requesting statistics on North American content for one product
https://stg.api.bazaarvoice.com/data/statistics.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=productid:eq:data-gen-2s9kaf0ugzn0p2flzl73ahuys&stats=NativeReviews,Reviews&filter=contentlocale:eq:en_US,es_US
Requesting questions & answers statistics for one product
All of the below examples will provide same response
https://stg.api.bazaarvoice.com/data/statistics.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=productid:data-gen-2s9kaf0ugzn0p2flzl73ahuys&stats=Questions,Answers
https://stg.api.bazaarvoice.com/data/statistics.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=productid:data-gen-2s9kaf0ugzn0p2flzl73ahuys&stats=Questions
https://stg.api.bazaarvoice.com/data/statistics.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=productid:data-gen-2s9kaf0ugzn0p2flzl73ahuys&stats=Answers
Requesting questions & answers statistics for multiple products
https://stg.api.bazaarvoice.com/data/statistics.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=productid:data-gen-2s9kaf0ugzn0p2flzl73ahuys,data-gen-td50ixwh9pmjispxbwtely59d,data-gen-3jxhm78sfqfy8tg5qyinqioal,data-gen-ov7cr69sakbegasbhejikf0q0&stats=Questions
Requesting native review, review and questions & answers statistics for one product
https://stg.api.bazaarvoice.com/data/statistics.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=productid:data-gen-2s9kaf0ugzn0p2flzl73ahuys&stats=Reviews,NativeReviews,Questions,Answers
Parameters
| Name | Description | Required | Default Value |
|---|---|---|---|
PassKey |
API key is required to authenticate API user and check permission to access particular client's data. | Yes | |
ApiVersion |
The API version, e.g. 5.4. | Yes | |
Filter |
Filter criteria for content of the query. Must be Product IDs. | Yes | |
Stats |
The type of statistics that will be calculated on included subjects. Available content types are: Reviews, NativeReviews, Questions, Answers.
Note: Provide multiple content types using comma separation |
Yes | |
Callback |
Callback function name used with JSONP. Value is a string consisting of the following characters: a-z,A-Z,0-9,_ (excluding comma). See the JSONP tutorial for more information. |
No | |
IncentivizedStats |
If set to true, displays the number of incentivized reviews for each product returned in the response within an IncentivizedReviewCount element. This parameter must be used in conjunction with the Stats parameter. |
No | false |
Filter options
- Each filter argument specifies the attribute to filter on followed by a comma-separated list of values. For instance, "Filter=ProductId:eq:Product1,Product2" returns statistics for Product1 and Product2.
- If a filter value contains a comma or a colon, that character needs to be escaped with a backslash (, or :). If a filter value contains an ampersand (&), the ampersand must be encoded in the filter value by replacing & with %26.
The following table lists the attributes available for filtering.
| Name | Description |
|---|---|
ContentLocale |
Locale of the content on which to calculate the statistics. A wildcard character "*" can be used to define the value, e.g., "en*" returns all content in English (en_US, en_CA, en_GB, etc.). The two valid operators for this filter are equals (eq) and not equals (neq). |
ProductId |
The identifier for the products that will be returned in the results. This filter is required. A limit of 100 ProductIds exists when used in the Filter.
|
Response format
This is a sample response for requesting reviews. Use the links above to see live examples.
{
"Includes": { },
"HasErrors": false,
"Offset": 0,
"TotalResults": 1,
"Locale": "en_US",
"Errors": [ ],
"Results": [
{...}
],
"Limit": 2
}
This is a sample response for requesting questions & answers. Use the links above to see live examples.
{
"Includes": { },
"HasErrors": false,
"Offset": 0,
"TotalResults": 1,
"Locale": "en_US",
"Errors": [ ],
"Results": [{
"ProductStatistics":{
"ProductId": "data-gen-2s9kaf0ugzn0p2flzl73ahuys",
"NativeReviewStatistics": { },
"ReviewStatistics": { },
"QAStatistics":{
"TotalQuestionCount": 21,
"TotalAnswerCount": 27
}
}
}
],
"Limit": 1
}
Response elements
| Name | Description |
|---|---|
Includes |
Always empty
|
HasErrors |
Boolean value indicated if one of more errors have occurred. See Errors below.
|
Offset |
Dataset offset used for pagination (passed as URL parameter in a query request). The maximum supported value is 300000.
|
TotalResults |
Total number of records matched.
|
Locale |
Indicates the language by region (language_region) associated with the client instance. This is the value used for field labels returned by the API, not the region from which the reviews originate.
|
Errors |
Error section is populated instead of other fields if there is an error with a query syntax or problem executing a query.
|
Results |
Section containing an array of primitive type object references matched by a query.
|
Limit |
The total number of results returned, specified by user in the URL using the ProductId filter parameter described above.
|
Error codes
| Value | Description |
|---|---|
ERROR_PARAM_INVALID_API_KEY |
Invalid API Key value |
ERROR_PARAM_INVALID_FILTER_ATTRIBUTE |
Invalid filter attribute name |
ERROR_PARAM_INVALID_INCLUDED |
Invalid parameter value |
ERROR_PARAM_INVALID_CALLBACK |
Invalid JsonP callback function name |
ERROR_REQUEST_LIMIT_REACHED |
Rate limiting error, i.e. too many requests per time interval |
ERROR_UNSUPPORTED |
For unsupported features, clients etc. |
ERROR_ACCESS_DENIED |
Insufficient privileges to perform the operation |
ERROR_UNKNOWN |
Unknown error (internal server error, for instance) |
By default, for all the form errors occurred during the API calls, the HTTPS response code 200 OK is returned, with the error information in the JSON response body.
curl --location 'https://stg.api.bazaarvoice.com/data/statistics.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4k&Filter=ProductId%3Adata-gen-moppq9ekthfzbc6qff3bqokie&Include=Products'
If the clients wish to receive 4xx, 5xx kind of error codes in HTTPS response, a small addition needs to be made to the api call. In the request header of the API call, add "bv-version" with value "5.4.1", this will generate appropriate 4xx, 5xx error codes in the HTTPS response. The JSON response still contains the detailed description of the error.
Example curl with header:
curl --location 'https://stg.api.bazaarvoice.com/data/statistics.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4k&Filter=ProductId%3Adata-gen-moppq9ekthfzbc6qff3bqokie&Include=Products' \
--header 'bv-version: 5.4.1'
Updated 2 months ago