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)

This page contains general information about the Conversations API that applies to all versions.

Versions

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 or filter=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 the json 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 the json 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 performing Action= and Action=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.