Stories is only available to clients on our Conversations PRR platform.
Refer to Conversations PRR Only Features for more information.

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 stories. Note that stories can be posted on either a Product or a Category.

Examples

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

Requesting all stories

The number of results returned in the response defaults to 10 unless specified in the 'Limit' parameter

Requesting all stories for a particular product

This returns stories posted on the specified product

Requesting all stories for a particular category

This returns stories posted on the specified category

Requesting a particular story

This returns stories with the specified ids.

Advanced Stories 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.

Multiple values can be provided in comma-separated form, such as the included content types of authors, comments, products and categories related to the stories.

Parameters

Name Description Required Default Value
ApiVersion The API version, e.g. 5.4. Yes
[FORMAT] Response format (xml or 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=true" limits 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
Filter_Comments Filtering option for Comments if they are returned (see Include). No
Limit Max number of records returned. An error is returned if the value passed exceeds 100. No 10
Limit_Comments Limit option for Comments if they are returned (see Include). Note that this limit doesn't apply to the entire set of comments returned, but to the comments for each individual story (CommentIds node). 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
Include Related subjects to be included in the response. Can be one or more (comma-separated) of Products, Categories, Authors, or Comments. No Returns only Stories if not specified
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. No 0
Search Full-text search string used to find UGC. For more information about what fields are searched by default, see Display Fundamentals.

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 Display Fundamentals 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 Stories. Multi-attribute sorting is supported. No Sorted by SubmissionTime if not specified
Sort_Comments Sorting option for Comments if they are returned (see Include). Note that this sort order doesn't apply to the entire set of comments returned, but to the comments for each individual story (CommentIds node). No
Stats

The type of statistics that will be calculated on included subjects. Available content types are: Reviews, Questions, Answers, Stories. Note: Not all statistical content types apply to every possible include.

No

Filter options

  • Each filter argument specifies the attribute to filter on followed by a comma-separated list of values. For instance, "Filter=TotalFeedbackCount:3,4" will match all content with TotalFeedbackCount values 3 OR 4.
  • Advanced operators can be used to define filters. For instance, "Filter=TotalFeedbackCount:lte:10" will match all content with a TotalFeedbackCount value of 10 or less. All advanced operators are documented on the Display Fundamentals 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:eq:true" will match all featured content with a TotalFeedbackCount value of greater than 10.
  • Time-based filters can be used for SubmissionTime 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.
AdditionalField_[FIELD_NAME] Additional field to filter by, e.g., filter=AdditionalField_[FIELD_NAME]:eq:[FIELD_VALUE]
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.
CategoryId
The identifier of the product category
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.
ContextDataValue_[dimension-external-id]
Context data value field (e.g.: ContextDataValue_Age, ContextDataValue_Gender)
HasComments
Boolean flag indicating whether content has comments
HasPhotos
Boolean flag indicating whether content has photos
HasTags
Boolean flag indicating whether content has tags
HasVideos
Boolean flag indicating whether content has videos. For more information on inserting the returned VideoUrl into HTML, see the Field Types page.
IsFeatured
Boolean flag indicating whether content is featured
IsSubjectActive
Boolean flag indicating whether the content subject is active
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 API Reference page. Note that the ModeratorCodes attribute parameter must be explicitly requested in order to use this filter. See the Parameters section above.
ProductBrandId The value of the external product brand ID. The value is case-insensitive. To return content that doesn't have a brand ID associated with it, set productbrandid:eq:null
ProductId
The identifier of the product
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.
Tag_[TAG_NAME]
The tag name to filter by, e.g., filter=tag_[TAG_NAME]:eq:[TAG_VALUE]
TotalCommentCount
Number of comments associated with the content
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 <sort option>:asc for ascending and <sort option>: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,TotalCommentCount:asc sorts by number of feedbacks received descending, then comment count ascending

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

Name Description
Id
The identifier of the content/subject type.
AdditionalField_[FIELD_NAME] Additional field to sort by, e.g., sort=AdditionalField_[FIELD_NAME]:desc
AuthorId
The Identifier of the author who wrote the content
CampaignId
The identifier of the Campaign associated with the content
CategoryId
The identifier of the product category
ContentLocale
Locale value of the content
ContextDataValue_[dimension-external-id]
Context data value field (e.g.: ContextDataValue_Age, ContextDataValue_Gender)
HasComments
Boolean flag indicating whether content has comments
HasPhotos
Boolean flag indicating whether content has photos
HasTags
Boolean flag indicating whether content has tags
HasVideos
Boolean flag indicating whether content has videos. For more information on inserting the returned VideoUrl into HTML, see the Field Types page.
IsFeatured
Boolean flag indicating whether content is featured
IsSubjectActive
Boolean flag indicating whether the content subject is active
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
SubmissionId
Submission identifier assigned to the content when it was initially submitted
SubmissionTime
The submission date/time of the content
TotalCommentCount
Number of comments associated with 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

Requesting all stories for a particular product

http://[stg.]api.bazaarvoice.com.bazaarvoice.com/data/stories.json?ApiVersion=[latestApiVersion]&PassKey=[yourKey]&Filter=ProductId:0001

{
"Includes": { },
    "HasErrors": false,
    "Offset": 600,
    "TotalResults": 2149,
    "Locale": "en_US",
    "Errors": [ ],
    "Results": [
        {
            "TagDimensions": { },
            "TagDimensionsOrder": [ ],
            "AdditionalFieldsOrder": [ ],
            "StoryText": "TEST >> STG >> 1 FF 111111111111TEST >> STG >> 1 FF 111111111111TEST >> STG >> 1 FF 111111111111TEST >> STG >> 1 FF 111111111111TEST >> STG >> 1 FF 111111111111TEST >> STG >> 1 FF 111111111111TEST >> STG >> 1 FF 111111111111TEST >> STG >> 1 FF 111111111111TEST >> STG >> 1 FF 111111111111TEST >> STG >> 1 FF 111111111111",
            "UserNickname": "tests123456",
            "Photos": [
                {
                    "Caption": "df",
                    "Sizes": {
                        "thumbnail": {
                            "Url": "http://testcustomer.ugc.bazaarvoice.com/stories/0001/146182/photoThumb.jpg",
                            "Id": "thumbnail"
                        },
                        "normal": {
                            "Url": "http://testcustomer.ugc.bazaarvoice.com/stories/0001/146182/photo.jpg",
                            "Id": "normal"
                        }
                    },
                    "SizesOrder": [
                        "thumbnail",
                        "normal"
                    ],
                    "Id": "146182"
                }
            ],
            "ContextDataValues": {
                "rcvdProductSample": {
                    "Value": "false",
                    "ValueLabel": "No",
                    "DimensionLabel": "Received Free Product",
                    "Id": "rcvdProductSample"
                }
            },
            "CategoryId": "Category1",
            "Videos": [
                {
                    "VideoHost": "www.youtube.com",
                    "Caption": "asdf",
                    "VideoThumbnailUrl": "http://img.youtube.com/vi/wXw7Yxv1IIM/0.jpg",
                    "VideoId": "wXw7Yxv1IIM",
                    "VideoUrl": "http://www.youtube.com/v/wXw7Yxv1IIM&rel=0",
                    "VideoIframeUrl": null
                }
            ],
            "ContextDataValuesOrder": [
                "rcvdProductSample"
            ],
            "LastModificationTime": "2011-05-25T05:31:00.000-00:00",
            "SubmissionId": "e7w9680cthqgujyswtzb8o2ua",
            "TotalFeedbackCount": 0,
            "TotalPositiveFeedbackCount": 0,
            "TotalInappropriateFeedbackCount": 0,
            "InappropriateFeedbackList": [ ],
            "BadgesOrder": [ ],
            "UserLocation": null,
            "Badges": { },
            "AuthorId": "ado4rlemng0",
            "IsFeatured": false,
            "ProductId": null,
            "ProductRecommendationIds": [ ],
            "Title": "TEST >> STG >> 1 FF 111111111111",
            "AdditionalFields": { },
            "CampaignId": null,
            "TotalNegativeFeedbackCount": 0,
            "SubmissionTime": "2011-03-29T04:25:22.000-00:00",
            "ContentLocale": "en_US",
            "ModerationStatus": "APPROVED",
            "TotalCommentCount": 0,
            "ClientResponses": [ ],
            "Id": "23996",
            "CommentIds": [ ],
            "LastModeratedTime": "2011-03-29T04:33:38.000-00:00"
        }
    ],
    "Limit": 1

}

Sample Format for Errors:
{
"Data":{

},
"Results":[

],
"Error":{
"Code": "[ERROR_CODE]",
"Message":"[ERROR_MESSAGE]"
},
"Offset":0,
"Limit":10
}

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).
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.