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.

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 data about Content Authors.

Examples

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

Requesting all authors

Requesting all authors who have written a review that has been recommended

Requesting all authors who have written 20 or more comments

Requesting an author by ID

You can request for multiple authors by Id, by separating the Ids with a comma. e.g. filter=id:1234,4567,3456.

Requesting an author by ID along with questions and reviews written by Author, sorted by submission time

The Reviews and Questions written by the Author can be filtered, sorted, and limited by specifying limit_reviews, limit_questions, sort_reviews, sort_questions, filter_reviews, filter_questions etc.

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
Filter Filter criteria for primary content of the query. Multiple filter criteria are supported. No
Filter_[TYPE] Filter criteria for a included content or subject type. TYPE can be Reviews, Questions, Answers, or Comments. Multiple filter criteria are supported for each content type. No
IncentivizedStats If set to true, displays the number of incentivized reviews written by each author 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 Content types written by the author to be included (e.g. Questions, Reviews, Answers, or Comments). Subject types like Products and Categories can also be specified. No
Limit Max number of records returned. An error is returned if the value passed exceeds 100. No 10
Limit_[TYPE] Limit option for a included content. TYPE can be Reviews, Questions, Answers or Comments. 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
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] Sort criteria for a included content. TYPE can be Reviews, Questions, Answers or Comments. No
Stats

The content types for which statistics should be calculated for the author. 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=ModeratorCode:eq:LI,PD" will match all content with moderation code values of LI (Liability Concern) or PD (Product Description Inaccurate).
  • Advanced operators can be used to define filters. For instance, "Filter=TotalReviewCount:gte:10" will match all content with a TotalReviewCount value of greater 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=ContextDataValue_gender:eq:female&Filter=ContextDataValue_age:eq:21to34" will match all content written by women between the ages of 21 and 34.
  • 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 Author.
AdditionalField_[FIELD_NAME]
Additional field to filter by, e.g., filter=AdditionalField_[FIELD_NAME]:eq:[FIELD_VALUE]
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]
The context data value for the content. DIMENSION_EXTERNAL_ID can be age, gender, etc. e.g. filter=contextdatavalue_age:under21
HasPhotos
Boolean flag indicating whether the Author profile has photos.
HasVideos
Boolean flag indicating whether the Author profile has videos. For more information on inserting the returned VideoUrl into HTML, see the Conversations API page.
LastAnswerTime
The Submission Time of the latest Answer written by the Author.
LastCommentTime
The Submission Time of the latest Comment that was written by the Author.
LastModeratedTime
The date/time of the latest moderation of the content. See the Introduction for an example of using advanced operators for filtering.
LastReviewTime
The Submission Time of the latest Review written by the Author.
LastQuestionTime
The Submission Time of the latest Question written by the Author.
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.
SubmissionTime
The submission date/time of the content. See the Introduction for an example of using advanced operators for filtering.
TotalAnswerCount
The number of Answers written by the Author.
TotalCommentCount
The number of Comments written by the Author.
TotalQuestionCount
The number of Questions written by the Author.
TotalReviewCount
The number of Reviews written by the Author.
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=TotalReviewCount:desc,Id:asc sorts the authors, first by their total review count (most to least), then if there are authors with the same number of reviews, the authors are sorted alphabetically by ID.

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

Name Description
Id
The identifier of the Author.
AdditionalField_[FIELD_NAME]
Additional field to sort by, e.g., sort=AdditionalField_[FIELD_NAME]:desc
ContentLocale
Locale value of the content
ContextDataValue_[DIMENSION_EXTERNAL_ID]
The context data value for the content. DIMENSION_EXTERNAL_ID can be age, gender, etc. e.g. sort=contextdatavalue_age:desc
HasPhotos
Boolean flag indicating whether the Author profile has photos.
HasVideos
Boolean flag indicating whether the Author profile has videos. For more information on inserting the returned VideoUrl into HTML, see the Conversations API page.
LastAnswerTime
The Submission Time of the latest Answer written by the Author.
LastCommentTime
The Submission Time of the latest Comment that was written by the Author.
LastModeratedTime
The date/time of the latest moderation of the content
LastReviewTime
The Submission Time of the latest Review written by the Author.
LastQuestionTime
The Submission Time of the lastest Question written by the Author.
SubmissionTime
The submission date/time of the content
TotalAnswerCount
The number of Answers written by the Author.
TotalCommentCount
The number of Comments written by the Author.
TotalQuestionCount
The number of Questions written by the Author.
TotalReviewCount
The number of Reviews written by the Author.
UserLocation
Location of the author

Response format

This is an example response for a query listing Authors limiting the results to 1 entry and including statistics (average overall rating, rating distribution, secondary ratings averages, etc.) for reviews written by this author.

{
    "Includes": { },
    "HasErrors": false,
    "Offset": 0,
    "TotalResults": 36053,
    "Locale": "en_US",
    "Errors": [ ],
    "Results": [
        {
            "AdditionalFieldsOrder": [ ],
            "Avatar": { },
            "Photos": [ ],
            "ContextDataValues": {
                "age": {
                    "Value": "under21",
                    "ValueLabel": ""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
                },
            }
            "SecondaryRatingsOrder": [ ],
            "UserNickname": "bfggbbd",
            "ProductRecommendationIds": [ ],
            "AdditionalFields": { },
            "SubmissionTime": "2012-03-01T05:58:03.000-00:00",
            "ModerationStatus": "APPROVED",
            "ReviewIds": [ ],
            "Id": "zzl7lx3wm8",
            "CommentIds": [ ],
            "SecondaryRatings": { },
            "LastModeratedTime": "2012-03-01T06:00:47.000-00:00"
        }
    ],
    "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_SORT_ATTRIBUTE

Invalid sort attribute name

ERROR_UNKNOWN

Unknown error (internal server error, for instance)

ERROR_UNSUPPORTED

For unsupported features, clients etc.