Conversations API: Retrieve and submit consumer-generated content (CGC), and retrieve your product catalog and statistics about your CGC.
Overview
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
This page contains general information about the Conversations API that applies to all versions.
Versions
-
Version 5.4 (Conversations)
The latest API version for clients on our Conversations platform. Refer to Platforms to learn more.
-
Version 5.4 (PRR)
The latest API version for clients on our PRR platform. Refer to Platforms to learn more.
CGC Content Types
The Conversations API allows display access to the following:
- Content types
- Reviews
- Review Comments
- Questions
- Answers
- Subject types
- Products
- Product Categories
- Content Authors
The API allows submission to the following:
- Content types
- Reviews
- Review Comments
- Questions
- Answers
- Photos
- Videos PRR
Display Request Format
The same general request format applies to queries for all data types.
http://[stg.]api.bazaarvoice.com/data/[TYPE].[FORMAT] ?passkey=[yourPassKey] &ApiVersion=[latestApiVersion] &Include=[TYPE],...,[TYPE] &Filter=[ATTRIBUTE_NAME]:[ATTRIBUTE_VALUE],...,[ATTRIBUTE_VALUE]* &Filter_[TYPE]=[ATTRIBUTE_NAME]:[ATTRIBUTE_VALUE],...,[ATTRIBUTE_VALUE]* &Sort=[ATTRIBUTE_NAME]:[asc|desc],...,[ATTRIBUTE_NAME]:[asc|desc] &Sort_[TYPE]=[ATTRIBUTE_NAME]:[asc|desc],...,[ATTRIBUTE_NAME]:[asc|desc] &Search=[SEARCH_TEXT] &Search_[TYPE]=[SEARCH_TEXT] &Offset=[OFFSET_VALUE] &Limit=[LIMIT_VALUE] &Limit_[TYPE]=[TYPE_LIMIT_VALUE] &Callback=[CALLBACK_FUNCTION_NAME]
While querying for Products, Categories, and Authors, an additional parameter is supported
&Stats=[TYPE],...,[TYPE]
Display Parameter Notes
- The parameter names and values are all case-insensitive
- Commas or colons within a filter value must be escaped with a backslash (\, or \:) and that backslash must be percent encoded. For example, when percent encoded
would be
%5C
- Ampersands (&) within a filter value must be percent encoded. For example, when percent encoded
&
would be%26
- Any date/time returned by the API is displayed in Coordinated Universal Time (UTC) format
- Advanced operators are supported on filters. The following table lists the supported operators and describes their usage:
Operator Description Allowable Field Types Example gt
greater than (>) numeric fields filter=rating:gt:4
gte
greater than or equal to (>=) numeric fields filter=rating:gte:4
lt
less than (<) numeric fields filter=rating:lt:4
lte
less than or equal to (<=) numeric fields filter=rating:lte:4
eq
equal to (==) numeric, boolean or string fields filter=rating:eq:4
orfilter=rating:4
(supported for backward comapatibility)neq
not equal to (!=) numeric, boolean or string fields filter=rating:neq:4
- The REQUIRED parameter
TYPE
is used to specify the Object (Content/Subject/Author) type to be returned, where TYPE = reviews|questions|answers||comments|authors|products|categories - The REQUIRED parameter
FORMAT
is used to specify the response format, where FORMAT = json|xml - The OPTIONAL parameter
Callback
is only available for thejson
response format. See Cross-domain requests section below for more details. - The parameters, responses, and error codes for each Object are listed on the Object's spec page.
Submission Request Format
The same general request format applies to queries for all data types.
API endpoint:
http://[stg.]api.bazaarvoice.com/data/submit[TYPE].[FORMAT]
POST body (basic example for reviews):
?PassKey=[yourKey] &ApiVersion=[latestApiVersion] &ProductId=[productId] &Action=[action] &Rating=[rating] &ReviewText=[reviewText] &Title=[title] &UserNickname=[nickname]
Submission Parameter Notes
- The parameter names and values are all case-insensitive
- The REQUIRED parameter
TYPE
is used to specify the content type to be submitted, where TYPE = review|question|answer||reviewcomment| - The REQUIRED parameter
FORMAT
is used to specify the response format, where FORMAT = json|xml - The parameters, responses, and error codes for each TYPE are listed on each TYPE's spec page
- The OPTIONAL parameter
Callback
is only available for preview requests (using HTTP GET) and using thejson
response format. See Cross-domain requests section below for more details. - The
Action
parameter combined with HTTP GET or POST determines the how the Bazaarvoice platform will respond:Action Description HTTP Method Action=
Response represents fields necessary to create a submission form. The Action
parameter is optional for this operation.GET, POST Action=Preview
Used to validate a submission. Response will include errors on failure. Data will not be stored. GET, POST Action=Submit
On success data will be stored and response will include a submission ID. On failure response will contain errors. POST Action=Submit
may occur without first performingAction=
andAction=Preview
.
Response Formats
Response Format for Display
{ "Results": [ { "[NAME]": "[VALUE]" ... }, ... ], "Includes": { "[TYPE]": { "[ID]": { "[NAME]": "[VALUE]" ... } } }, "HasErrors": [TRUE|FALSE] "Offset": [OFFSET] "LIMIT": [LIMIT] "TotalResults": [TOTAL_RESULTS] }
Element | Description |
---|---|
Includes | This section contains all the included Content/Subjects matched by the query. The data is grouped by Content/Subject type. Within each data section (e.g. "Reviews") there is a map of Objects keyed by Object Id. |
Results | This is the main results section. This section is an sorted array of Objects of the primary Content/Subject Type. |
Offset | Data Offset used for pagination (passed as URL parameter in a query request, defaults to 0). |
Limit | The maximum number of objects returned. |
TotalResults | The total number of records that match the query. |
Response Format for Errors
{ "Error": { "Code": "[ERROR_CODE]", "Message": "[ERROR_MESSAGE]" } }
The following HTTP response codes are used:
HTTP response code | Error |
---|---|
200 |
The API was able to return a response. To support JSONP we always try to return a 200 when possible. Be sure to check the response body to ensure the data you expect is present. |
400 |
Error processing request - error response returned. |
500 |
Errors in the 500 range typically indicate an unexpected server error. Please try again in a few moments and if the error still persists contact us for help. |
The following error codes are used:
Error Code | Error meaning |
---|---|
ERROR_PARAM_INVALID_API_KEY |
Invalid API Key value |
ERROR_PARAM_INVALID_INCLUDED |
Invalid "include" parameter value |
ERROR_PARAM_INVALID_FILTER_ATTRIBUTE |
Invalid filter attribute name |
ERROR_PARAM_INVALID_SORT_ATTRIBUTE |
Invalid sort attribute name |
ERROR_PARAM_INVALID_OFFSET |
Invalid offset value |
ERROR_PARAM_INVALID_LIMIT |
Invalid limit value |
ERROR_PARAM_INVALID_LOCALE |
Invalid locale code |
ERROR_REQUEST_LIMIT_REACHED |
Rate limiting error, i.e. too many requests per time interval |
ERROR_PARAM_INVALID_CALLBACK |
Invalid JsonP callback function name |
ERROR_UNSUPPORTED |
For unsupported features, clients etc. |
ERROR_ACCESS_DENIED |
Insufficient privileges to perform the operation |
ERROR_UNKNOWN |
Unknown error (internal server error, for instance) |
Response Format for Submission
{ "[CONTENT_TYPE]":{ "[NAME]":"[VALUE]", ... }, "Data":{ "Field":{ "[FIELD_NAME]":{ "[FIELD_ATTRIBUTE_NAME]":"[FIELD_ATTRIBUTE_VALUE]", ... }, ... }, "Group":{ "[GROUP_NAME]":{ "[GROUP_ATTRIBUTE_NAME]":"GROUP_ATTRIBUTE_VALUE", ... "SubElements":[ { "Type":"[GROUP_SUBELEMENT_TYPE]", "ID":"[GROUP_SUBELEMENT_VALUE]" }, ... ] }, ... } }, "FormErrors": { "FieldErrors": { "[FIELD_ID]" : "[ERROR_MESSAGE]", ... } }, "Form":[ { "Type":"[TYPE]", "ID":"[ID]" }, ... ], "TypicalHoursToPost":[TYPICAL_HOURS_TO_POST] }
Element | Description |
---|---|
CONTENT_TYPE | Review, Question, Answer, , or Comment. This section contains minimal information about the content being submitted.It contains the basic attributes as Name-Value pairs. |
Data | The Data section contains all the fields and groups that can be submitted. Within each data section (i.e. "Field" or "Group") there is a map of objects keyed by object's id. |
Field | A list of standalone fields e.g. userlocation. The existence of fields is client-configured. Refer to the Input Types tutorial for more information.
|
Group | A list of groups of related fields. The existence of field groups is client-configured. |
Subelements | This section exists for Groups that contain nested groups. |
Form | A list of the fields and groups that are supported for this submission. |
FormErrors | This section exists if there are any errors related to the fields being submitted. e.g. missing fields that are required, invalid values, etc. |
TypicalHoursToPost | The minimum number of hours that it will take for the submitted content to be moderated and available for display. |
Moderator Codes for Content
When content is moderated, specific codes are applied to the content. Starting with version 5.1, you can filter your query using the ModeratorCode
filter option. The following standard moderator codes are supported:
- CR (Competitor Reference)
- CS (Customer Service Complaint)
- DBA (Directing Business Away)
- FL (Content in a Foreign Language)
- GIU (Generally Inappropriate Comments)
- IMG (Inappropriate Image)
- INT (Product Accolades)
- LI (Liability Concerns)
- NCR (Neutral Competitor Reference)
- PC (Promotions and Sales)
- PD (Reviewer claims Product Description is somehow inaccurate)
- PF (Product Flaw)
- PII (Personally Identifiable Information)
- PLI (Potential Danger - Liability)
- PRF (Profanity)
- PRI (Price Reference)
- PS (Product Suggestion)
- PUX (Lack of Product Experience)
- RET (Retailer Mention)
- RW (Restricted Words)
- SI (Shipping Issues)
- SPM (Spam or Duplicate Content)
- SR (Staff Rejection)
- UA (Underaged User)
- URL (Presence of URL)
- VAC (Vacuous)
- WP (Wrong Product)
There may also be client-specific codes that can be queried. Refer the Conversations Knowledge base for more information on content moderation.