Product Display

Returns Product data.

🚧

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 Product Display API reference here.

Examples

The following examples demonstrate common Conversations API display requests. For a complete overview of using the Conversations API to display data, refer to the Display tutorials.

🚧

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

Request all products

https://stg.api.bazaarvoice.com/data/products.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4

Request a product by ID

🚧

product ID with special characters other than hyphens (-) and underscores (_) will return zero results.

https://stg.api.bazaarvoice.com/data/products.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=id:data-gen-2s9kaf0ugzn0p2flzl73ahuys

You can request for multiple products by ID by separating the IDs with a comma.

  • e.g. filter=id:0001,0002,0003.

Requesting a product by ID including review statistics (inc. average rating)

This example call shows how to use the stats parameters to retrieve review statistics (including average rating) for a particular product.

https://stg.api.bazaarvoice.com/data/products.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&Filter=id:data-gen-2s9kaf0ugzn0p2flzl73ahuys&stats=reviews

Request all products sorted by ascending ID value

https://stg.api.bazaarvoice.com/data/products.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&sort=Id:asc

Request all products in a given Category

https://stg.api.bazaarvoice.com/data/products.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=CategoryId:eq:data-gen-t3jxodbtmy8n9fzn1vm88yjec

Products text search

https://stg.api.bazaarvoice.com/data/products.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&search=large%20dryer

The result returns products that have both large and dryer in the external ID, product name, product brand, product description, category name, category hierarchy names.

Full text searching on products is not automatically enabled when an API key is created. Please contact our support team after you have requested API keys to enable searching.

Parameters

Name Description Required Default Value
ApiVersion The API version, e.g. 5.4. Yes
[FORMAT] Response format (json) Yes
PassKey API key is required to authenticate API user and check permission to access particular client's data. 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
ExcludeFamily Boolean flag indicating whether to exclude content (reviews, questions, etc.) from other products in the same family as the requested product. This setting only affects any nested content that is returned. For example,
&filter=productid:eq:1101&include=reviews&excludeFamily=true
limits returned review content to just that of product 1101 and not any of the products in the same family. If a value is not defined, content on all products in the family is returned.
No false
Filter Filter criteria for primary content of the query. Multiple filter criteria are supported. No
Filter_[TYPE] Filtering option for included nested content. TYPE can be any related content, i.e., Reviews, Questions, Answers, Comments, Authors, Categories. 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 FilteredStats or Stats parameters to include statistics for reviews in the response. No false
Include Related subjects to be included (e.g. Products, Categories, Authors, Reviews, Questions. No Will only return Product information
Limit Max number of records returned. An error is returned if the value passed exceeds 100. No 10
Limit_[TYPE] Limit option for the nested content type returned. TYPE can be any related content i.e.Reviews, Questions, Answers, Comments, Authors, Categories. An error is returned if the value passed exceeds 20. No 10
Locale Locale to display Labels, Configuration, Product Attributes and Category Attributes in. The default value is the locale defined in the display associated with the API key. No
Offset Index at which to return results. By default, indexing begins at 0 when you issue a query. Using Limit=100, Offset=0 returns results 0-99. When changing this to Offset=1, results 1-100 are returned. The maximum supported value is 300000. No 0
Search Full-text search string used to find UGC. For more information about what fields are searched by default, see the Conversations API page.
Results can not be sorted when using Search.
No
Sort Sort criteria for primary content type of the query. Sort order is required (asc or desc). Multi-attribute sorting for each content/subject type is supported. No
Sort_[TYPE] Sorting option for nested content. Sort order is required (asc or desc). TYPE can be any related content, i.e., Reviews, Questions, Answers, Comments, Authors, Categories. No
Stats The content types for which statistics should be calculated for the product. Available content types are: Reviews, Questions, Answers. Note: Statistics can also be calculated on includes. No

Filter options

  • Each filter argument specifies the attribute to filter on followed by a comma-separated list of values. For instance, "Filter=Id:eq:50,75" will match all Products with Id 50 OR 75.
  • Advanced operators can be used to define filters. For instance, "Filter=Id:lte:100" will match all Products with an Id value of less than or equal to 100. All advanced operators are documented on the Conversations API page.
  • 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.
  • Multiple filters are allowed as URL parameters in which case filters are AND'ed. For instance, "filter=IsActive:eq:false&filter=IsDisabled:eq:false" will match all Products that are neither Active nor Disabled.

The following table lists the attributes available for filtering.

Name Description
Id
The identifier of the content/subject type.
AverageOverallRating
The average overall rating for the reviews that were written on this Product.
CategoryAncestorId
The identifier of the Ancestor of the Product Category that the Product belongs to. Syndicated content will not be returned when using this filter.
CategoryId
The identifier of the Product Category that the Product belongs to.
IsActive
Boolean flag indicating whether the Product is Active.
IsDisabled
Boolean flag indicating whether the Product is Disabled.
Name
Product Name.
TotalAnswerCount
The number of Answers written for Questions on the Product. This does not take syndicated content into account.
TotalQuestionCount
The number of Questions written for the Product. This does not take syndicated content into account.
TotalReviewCount
The number of Reviews written for the Product. This does not take syndicated content into account.

Sort options

  • Sort order is required (asc or desc). There is no default.
  • Multi-attribute sorting is supported by using a comma separated list of sort criteria for a content/subject type.
    • e.g. sort=rating:asc,submissiontime:desc

The following table lists the attributes that are available for sorting.

Name Description
Id
The identifier of the content/subject type.
AverageOverallRating
The average overall rating for the reviews that were written on this Product. This does not take syndicated content into account.
CategoryId
The identifier of the Product Category that the Product belongs to.
IsActive
Boolean flag indicating whether the Product is Active.
IsDisabled
Boolean flag indicating whether the Product is Disabled.
Name
Product Name.
TotalAnswerCount
The number of Answers written for Questions on the Product.
TotalQuestionCount
The number of Questions written for the Product.
TotalReviewCount
The number of Reviews written for the Product. This does not take syndicated content into account.

Response format

This is a sample response for requesting reviews. Use the links above to see live examples.

{
    "Includes": { },
    "HasErrors": false,
    "Offset": 0,
    "TotalResults": 224775,
    "Locale": "en_US",
    "Errors": [ ],
    "Results": [
        {...}
        {...}
    ],
    "Limit": 2

}

Response elements

Name Description
Includes
Included results related to primary results. For example, with the request reviews.json?include=Comments, the Include node will be populated with comments associated with the reviews in the Results node.
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. Defaults to 10 and has a maximum of 100.

Error codes

Value Description
ERROR_ACCESS_DENIED

Insufficient privileges to perform the operation

ERROR_PARAM_INVALID_API_KEY

Invalid API Key value

ERROR_PARAM_INVALID_CALLBACK

Invalid JsonP callback function name

ERROR_PARAM_INVALID_FILTER_ATTRIBUTE

Invalid filter attribute name

ERROR_PARAM_INVALID_INCLUDED

Invalid parameter value

ERROR_PARAM_INVALID_LIMIT

Invalid limit value

ERROR_PARAM_INVALID_LOCALE

Invalid locale code

ERROR_PARAM_INVALID_OFFSET

Invalid offset value

ERROR_PARAM_INVALID_SEARCH_ATTRIBUTE

Invalid search attribute name or search not supported

ERROR_PARAM_INVALID_SORT_ATTRIBUTE

Invalid sort attribute name

ERROR_REQUEST_LIMIT_REACHED

Rate limiting error, i.e. too many requests per time interval

ERROR_UNKNOWN

Unknown error (internal server error, for instance)

ERROR_UNSUPPORTED

For unsupported features, clients etc.