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.

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)

Returns Product-based Review Statistics. This method has been optimized and was created for inline ratings display.

Examples

Demonstration purposes only. Do not reuse the API passkeys below in your application.

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 content type for which statistics should be included. Currently available types:

  • Reviews: returns statistics for all content, including syndicated content (if enabled on your API key).
  • NativeReviews: returns statistics only for content submitted on your site; Syndicated content and product family content are excluded.
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
}

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)