Comment Display
Returns comments posted on reviews.
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 Comment 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 Display tutorials.
Demonstration purposes only. Do not reuse the API passkeys below in your application.
Requesting all comments for a particular review
This returns comments posted on the specified review.
https://stg.api.bazaarvoice.com/data/reviewcomments.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=reviewid:16970457
Requesting a particular review comment
This returns specified comment posted on a review.
https://stg.api.bazaarvoice.com/data/reviewcomments.json?ApiVersion=5.4&PassKey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&Filter=Id:338201
Advanced comment request
This request illustrates using multiple filters (just add another &filter=[filter] section), requesting additional content (include=[content]), sorting (sort=[attribute]:[order]), limiting the result count and requesting the second page of results.
https://stg.api.bazaarvoice.com/data/reviewcomments.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4&filter=productid:data-gen-3jxhm78sfqfy8tg5qyinqioal&include=authors,products,categories&sort=totalpositivefeedbackcount:desc&limit=4&offset=4
Multiple values can be provided in comma-separated form, such as the included content types of authors, reviews, products and categories related to the comments.
Requesting all native (non-syndicated) review comments
Native (non-syndicated) content only. Continue reading for more details.
https://stg.api.bazaarvoice.com/data/reviewcomments.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4
Requests for this content type that do not include a ProductId
, AuthorId
, CategoryAncestorId
, SubmissionId
, or Comment Id
filter will only work with API keys that are configured to exclude syndicated content.
We recommend using our Displayable Content Export service to download all of your native and syndicated content. If you still prefer the Conversations API, then you may contact our support team to have your Conversations API keys re-configured.
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 | |
Attributes |
Attributes to be included when returning content. For example, if includes are requested along with the &attributes=ModeratorCodes parameter, both the includes and the results will contain moderator codes. In order to filter by ModeratorCode, you must request the ModeratorCodes attribute parameter. | No | |
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 from other products in the same family as the requested product. For example, &filter=productid:eq:1101&excludeFamily=truelimits returned 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 will be returned. |
No | false |
Filter |
Filter criteria for primary content of the query. Multiple filter criteria are supported. | No | |
Include |
Related subjects to be included in the response. Can be one or more (comma-separated) of Reviews, Products, Categories, or Authors. | No | |
Limit |
Max number of records returned. An error is returned if the value passed exceeds 100. | 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 |
Sort |
Sort criteria for Comments. Multi-attribute sorting is supported. |
No | Sorted by SubmissionTime if not specified |
Filter options
- Each filter argument specifies the attribute to filter on followed by a comma-separated list of values. For instance, "Filter=TotalFeedbackCount:eq:3,4" will match all content with TotalFeedbackCount values equal to 3 OR 4.
- Advanced operators can be used to define filters. For instance, "Filter=TotalFeedbackCount:lte:10" will match all content with a rating value less than or equal to 10. 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=TotalFeedbackCount:gt:10&Filter=IsFeatured:true" will match all featured content with a TotalFeedbackCount value of greater than 10.
- Time-based filters can be used for SubmissionTime, LastModificationTime and LastModeratedTime. 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 was submitted on November 9, 2009: &filter=SubmissionTime:gt:1257746400&filter=SubmissionTime:lt:1257832800
The following table lists the attributes available for filtering.
Name | Description |
---|---|
Id |
The identifier of the content/subject type.
|
AuthorId |
The identifier of the author who wrote the content.
|
CampaignId |
The identifier of the Campaign associated with the content
|
CategoryAncestorId |
The identifier of the product category ancestor. Syndicated content will not be returned when using this filter.
|
ContentLocale |
Locale of the content to display. If this filter is not defined, all content regardless of its locale is returned. To return specific content by locale, define the value in the filter. 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.) or you can use a single ContentLocale code (e.g., “fr_FR”). ContentLocale codes are case-sensitive.
|
IsFeatured |
Boolean flag indicating whether content is featured
|
IsSyndicated |
Boolean flag that allows you to select whether to return syndicated or non-syndicated comments. If IsSyndicated:eq:true, the response only returns syndicated content and a SyndicationSource block with the details of where the syndication is coming from. If IsSyndicated:eq:false, the response only return native (non-syndicated) content. Note: The API key must be configured to show syndicated content.
|
LastModeratedTime |
The date/time of the latest moderation of the content. See the Introduction for an example of using advanced operators for filtering.
|
LastModificationTime |
The date/time of the latest modification of the content. See the Introduction for an example of using advanced operators for filtering.
|
ModeratorCode |
String value indicating the moderator code for rejected content, e.g., &Filter=ModeratorCode:eq:CR returns UGC that contains the CR (Competitor Reference) code. Multiple codes can be entered in a comma-delimited list, e.g., &Filter=ModeratorCode:eq:CS,IU returns UGC with either the CS (Customer Service Complaint) or the IU (Inappropriate/Unusable Content) code. For a list of all Moderator Codes, see the Conversations API page. Note that the ModeratorCodes attribute parameter must be explicitly requested in order to use this filter. See the Parameters section above.
|
ProductId |
The identifier of the product
|
ReviewId |
The identifier of the Review
|
SubmissionId |
Submission identifier assigned to the content when it was initially submitted
|
SubmissionTime |
The submission date/time of the content. See the Introduction for an example of using advanced operators for filtering.
|
TotalFeedbackCount |
Number of feedbacks received
|
TotalNegativeFeedbackCount |
Number of negative feedbacks received
|
TotalPositiveFeedbackCount |
Number of positive feedbacks received
|
UserLocation |
Location of the author
|
Sort options
- Sort criteria is specified as :asc for ascending and :desc for descending
- Multi-attribute sorting is supported by using a comma separated list of sort criteria for a content/subject type. For instance Sort=TotalFeedbackCount:desc,TotalPositiveFeedbackCount:asc sorts by number of feedbacks received descending, then number of positive feedbacks received ascending
The following table lists the attributes that are available for sorting.
Name | Description |
---|---|
Id |
The identifier of the content/subject type.
|
AuthorId |
The Identifier of the author who wrote the content
|
CampaignId |
The identifier of the Campaign associated with the content
|
ContentLocale |
Locale value of the content
|
IsFeatured |
Boolean flag indicating whether content is featured
|
IsSyndicated |
Boolean flag indicating whether the content has been syndicated.
|
LastModeratedTime |
The date/time of the latest moderation of the content
|
LastModificationTime |
The date/time of the latest modification of the content
|
ProductId |
The identifier of the product
|
ReviewId |
The identifier of the Review
|
SubmissionId |
Submission identifier assigned to the content when it was initially submitted
|
SubmissionTime |
The submission date/time of the content
|
TotalFeedbackCount |
Number of feedbacks received
|
TotalNegativeFeedbackCount |
Number of negative feedbacks received
|
TotalPositiveFeedbackCount |
Number of positive feedbacks received
|
UserLocation |
Location of the author
|
Response format
This is a sample response for requesting review comments. 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_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. |
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/reviewcomments.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/reviewcomments.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4k&Filter=ProductId%3Adata-gen-moppq9ekthfzbc6qff3bqokie&Include=Products' \
--header 'bv-version: 5.4.1'
Updated about 2 months ago