🚧
Only API keys on our Conversations PRR 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

Returns Product data.

Examples

🚧
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=kuy3zj9pr3n7i0wxajrzj04xo>

Request a product by ID

https://stg.api.bazaarvoice.com/data/products.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&filter=id:test1

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=kuy3zj9pr3n7i0wxajrzj04xo&Filter=id:test1&stats=reviews

Request all products sorted by ascending ID value

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

Request all products in a given category

https://stg.api.bazaarvoice.com/data/products.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&filter=CategoryId:eq:testcategory1011

Products text search

https://stg.api.bazaarvoice.com/data/products.json?apiversion=5.4&passkey=kuy3zj9pr3n7i0wxajrzj04xo&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.

Note that full text searching on products is no longer automatically enabled when an API key is created. To enable full text search, the ClientConfiguration.xml file must be edited or the functionality must be enabled through the KMS.

Parameters

Name	Description	Required	Default Value
`ApiVersion`	The API version, e.g. 5.4.	Yes
`[FORMAT]`	Response format ( xml This feature will not be available or will behave differently in future versions of the Conversations API. Click for more information. or 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, or ).	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. Note: This invalidates sort options due to the fact that search takes precedence in returned data.	No
`Search_[Type]`	Searching option for included content followed by full-text search string. See the Conversations API page for examples of searching for included data. Note: This invalidates sort options due to the fact that search takes precedence in returned data.	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.
Time-based filters can be used for LastAnswerTime, LastQuestionTime, LastReviewTime. Dates in time-based filters are calculated as the number of seconds since January 1, 1970, 00:00:00 UTC. In a future version, we will be adding support for comparing date/time string values. The following example returns content that had its last review posted on November 9, 2009: &filter=LastReviewTime:gt:1257746400&filter=LastReviewTime:lt:1257832800

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.
`LastAnswerTime`	The Submission Time of the latest Answer that was submitted on a Product.
`LastQuestionTime`	The Submission Time of the latest Question that was submitted on a Product.
`LastReviewTime`	The Submission Time of the latest Review that was submitted on a Product.
`Name`	Product Name.
`RatingsOnlyReviewCount`	The number of ratings-only Reviews written for the Product.
`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.

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.
`LastAnswerTime`	The Submission Time of the latest Answer that was written for a Question on the Product.
`LastQuestionTime`	The Submission Time of the latest Question that was written for the Product.
`LastReviewTime`	The Submission Time of the latest Review that was written on the Product.
`Name`	Product Name.
`RatingsOnlyReviewCount`	The number of ratings-only Reviews written for the Product.
`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 an example response requesting products by ID, returning review statistics, and limiting the response to 1 entry:

{
    "Includes": { },
    "HasErrors": false,
    "Offset": 1000,
    "TotalResults": 7732,
    "Locale": "en_US",
    "Errors": [ ],
    "Results": [
        {
            "Name": "Thalgo L'Oceane Vitality Vial",
            "Brand": {
                "Name": "Thalgo",
                "Id": "21aiy3i7d33y9svmo5ovmhjx0"
            },
            "Attributes": {
                "Department": {
                     "Values": [
                           {
                                "Value": "5",
                                "Locale": null
                            }
                        ],
                            "Id": "Department"
                 }
             },
            "Description": "Helps improve the body's vitality.",
            "QuestionIds": [ ],
            "BrandExternalId": null,
            "ProductPageUrl": "http://www.skinstore.com/p-9618-thalgo-loceane-vitality-vial.aspx",
            "CategoryId": "33",
            "ReviewIds": [ ],
            "AttributesOrder": [
                 "Department"
            ],
            "ImageUrl": "http://skincare-img.skinstore.com/resources/dynamic/store/indexImages/TH141-vitality-vials.jpg",
            "Id": "9618",
            "ReviewStatistics": {
                "AverageOverallRating": 5,
                "OverallRatingRange": 5,
                "TotalReviewCount": 1
                "RatingDistribution": [
                    {
                        "Count": 1,
                        "RatingValue": 2
                    },
                    {
                        "Count": 2,
                        "RatingValue": 3
                    }
                    {
                        "Count": 3,
                        "RatingValue": 5
                    }
               ]
                "SecondaryRatingsAveragesOrder": [
                    "Design",
                    "Price",
                    "RatingDimension3"
               ],
                "SecondaryRatingsAverages": {
                        "RatingDimension3": {
                        "Id": "RatingDimension3",
                        "AverageRating": 1
                        },
                    "Price": {
                        "Id": "Price",
                         "AverageRating": 2
                   },
                   "Design": {
                         "Id": "Design",
                         "AverageRating": 3
                   },
                }
            }
        }
    ],
    "Limit": 1
 
}

Sample response for Errors:

{
    "Error": {
        "Code": "[ERROR_CODE]",
        "Message": "[ERROR_MESSAGE]"
    }
}

Response elements

Name	Description
`Data`	Section containing all the data matched by a query grouped by content/subject type. Within each data section there is a map of objects keyed by ids
`Errors`	Error section is populated instead of other fields if there is an error with a query syntax or problem executing a query.
`Limit`	The total number of results returned, specified by user in the URL. Defaults to 10 and has a maximum of 100.
`Offset`	Dataset offset used for pagination (passed as URL parameter in a query request). The maximum supported value is 300000.
`Results`	Section containing an array of primitive type object references matched by a query.
`TotalResults`	Total number of records matched.

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.

Product Display

🚧
Only API keys on our Conversations PRR 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

Examples

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

Request all products

Request a product by ID

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

Request all products sorted by ascending ID value

Request all products in a given category

Products text search

Parameters

Filter options

Sort options

Response format

Response elements

Error codes

🚧Only API keys on our Conversations PRR 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

Examples

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

Request all products

Request a product by ID

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

Request all products sorted by ascending ID value

Request all products in a given category

Products text search

Parameters

Filter options

Sort options

Response format

Response elements

Error codes

🚧
Only API keys on our Conversations PRR 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

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