Overview

When using the Bazaarvoice Conversations API a 'display request' is a request that returns user-generated content (UGC) intended for display in your application. A display request is accomplished by performing an HTTPS GET request that includes a content type, an API version and your API Passkey.

GET https://stg.api.bazaarvoice.com/data/[ContentType].json?ApiVersion=[LatestApiVersion]&Passkey=[YourApiKey]

Additionally, the Conversations API supports the following display features:

• Filtering
• Sorting
• Free text searches
• Pagination
• Including related content
• Cross domain requests
• Real time statistics
• Localization

Continue reading to learn about each of these features and see examples of how they are used.

Content types

All display requests to the Bazaarvoice platform will be of a particular content type.

GET https://stg.api.bazaarvoice.com/data/reviews.json

Review is the most common content type, but there are others. The table below shows the API endpoint for each content type. Click on an endpoint to see examples, options, and error codes:

Display Request Format

The same general request format applies to queries for all data types.

https://[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.
• 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
• 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.

Filtering

Display requests can be filtered based on a variety of attributes using the Filter parameter. The general pattern for filtering is demonstrated below:

Filter=Attribute:operator:Value

A request can be filtered against multiple attributes by using multiple filter parameters:

Filter=Attribute1:operator:Value&Filter=Attribute2:operator:Value

And against multiple values by using a comma-separated list of values:

Filter=Attribute:operator:Value1,Value2,ValueN

The available filter attributes vary depending on content type. Refer to the reference documentation for the relevant content type to see a list of available filter attributes.

The following table identifies the filter operators:

📘

'Equal to' short hand

Any filter without an operator will be treated as if eq had been used. Therefore, Filter=Attribute:Value is the same as using Filter=Attribute:eq:Value.

Sorting

The response to a display request can be ordered based on a variety of attributes using the Sort parameter. The general pattern for sorting is demonstrated below:

Sort=Attribute:direction

Multi-attribute sorting is also supported by using a comma-separated list of sort attributes:

Sort=Attribute1:direction,Attribute2:direction

The available sort attributes vary depending on content type. Refer to the reference documentation for the relevant content type to see a list of available sort attributes.

Direction will be asc for ascending results or desc for descending results. The following table shows how sort order works with several different attribute categories.

Full text search

All user-generated content can be searched using the Search parameter. Results will be ranked by the relevance to the query. The most relevant results will be towards the top and less relevant results will be towards the bottom. Due to the algorithmic nature of the query processing, you should not expect to be able to predict the exact order of results.

Searching supports locale specific stemming, meaning that a search for cat will also return cats, althought results with cats may be lower in the response than results with cat.

Search=cat

Similarly, search text in quotes will return results with an exact match ordered towards the top of the results.

Search="dish soap"

Full text search does not support wildcard characters.

The following list describes the default fields that are searched for each content type:

Pagination

Pagination is the process of dividing a total results set into smaller subsets for display in a user-interface.

The Bazaarvoice platform calculates a total result set each time a request is made using the Conversations API. The total result set can be paginated using the Limit and Offset parameters. Limit controls the count of results that will be returned in response to a request up to a maximum of 100. Offset identifies the position within the total result to start returning results. By combining these two parameters it is possible to iterate through a total result set.

The following combination of Limit and Offset will return 10 reviews, starting with the 10th review, representing the second page of results:

Limit=10&Offset=10

❗️

Limit and Offset are intended for use with organic traffic only (users manually clicking links). Any other usage will cause performance degradation and may result in restrictions or limitations on API usage.

Refer to the Pagination tutorial for more in-depth documentation.

Including related content

The Conversations API can return additional content type data that is related to the primary content type of the request. For example, you can request questions and include their related answers. This is accomplished using the Include parameter:

Include=Answers&Filter=ProductId:1000001

More than one content type may be included by separating them with a comma:

Include=ContentType1,ContentType2,ContentTypeN

The included content will be returned in a separate object from the primary content. Each item of primary content will include a list of included content IDs, allowing you to associate them together:

  {
      "HasErrors": false,
      "Includes": {
          "Answers": {
              "16389": {...},
              "16390": {...},
              "16391": {...}
          },
          ...
      },
      ...
      "Results": [
          {
              "QuestionSummary": "Test question ...",
              "Id": "14898",
              "AnswerIds": [
                  "16391",
                  "16390",
                  "16389"
              ],
              ...
          }
      ],
      ...
  }
  

To successfully use includes you must understand that the included content is calculated based on the primary content that is actually returned by a particular request. In the example above, answers 16389, 16390 and 16391 are returned because they are associated with question 14898. Had question 14898 not been in the response, then neither would those answers.

The content types which may be included vary depending on the primary content type being requested. Refer to the reference documentation for the relevant content type to see a list of available options.

You may perform the following actions on included content:

reviews.json?Include=Comments&Filter_Comments=IsFeatured:eq:True

reviews.json?Include=Comments&Sort_Comments=SubmissionTime:desc

reviews.json?Include=Comments&Limit_Comments=10

products.json?Include=Reviews&Search_Reviews=dryer

reviews.json?Include=Comments&Search=dryer&Search_Comments=best

Cross-domain requests

The Conversations API supports requests using CORS (Cross Origin Resource Sharing) and JavaScript Object Notation with Padding (JSONP).

CORS

To use CORS, be sure your requests are compatible with the requirements for "Simple" CORS, including:

• Use the HTTPS GET or POST methods
• Do not use custom, forbidden, or unsafe headers

Refer to the CORS tutorial to learn more about using CORS with the Conversations API.

JSONP

To perform a display request that returns JSONP, add the callback parameter with a value that is the name of your JSON handling function. The resulting JSON response will be "wrapped" inside that function.

• Without callback function: {"Results":{"Products":{"AAA":{"id":"AAA"}}}}
• With callback function 'myCallbackFunc': myCallbackFunc( {"Results":{"Products":{"AAA":{"id":"AAA"}}}} );

The following example demonstrates the Callback parameter:

Callback=myCallbackFunc

Refer to the JSONP tutorial to learn more about using JSONP with the Conversations API.

Real-time statistics

Any request to products.json or any request that includes Products can use the Stats parameter to add statistics for the product to the response. If you include more filters in your request aside from the product ID and want to limit the statistics to the filtered results, use FilteredStats instead of Stats.

products.json

products.json?Stats={ContentType}

Include=Products

reviews.json?ApiVersion=[LatestApiVersion]&Passkey=[YourApiKey]&Filter=ProductId:test1&Include=Products&
Stats={ContentType}

Statistics can be calculated on the following content types:

You can include more than one content type by separating them with a comma:

products.json?Stats=Reviews,Questions

📘

Not the same as statistics.json

Use statistics.json when you want to include overall rating on a large number of products at one time. For example, on a category page or search result page. The Stats parameter is intended for displaying detailed statistics on product pages.

Localization

The Bazaarvoice platform supports multiple locales which are identified using the language_COUNTRY format. For example, the locale code fr_CA identifies the French language as spoken in Canada.

Bazaarvoice hosted labels

The language used for field labels returned by display requests can be controlled with the Locale parameter. In the following example labels will be returned in Canadian French:

Locale=fr_CA

Filtering user submitted content

User submitted content (Reviews, Questions, etc) can be filtered based on locale using the ContentLocale filter. In the following example, only content associated with fr_CA will be returned:

Filter=ContentLocale:fr_CA

Character encoding

The Bazaarvoice platform returns content encoded in UTF-8.

Refer to the Internationalization tutorial for more in-depth documentation.

Response Format for Display

{  
    "Results": \[  
           {  
               "[NAME]": "[VALUE]"  
                ...  
           },  
           ...  
    ],  
    "Includes": {  
           "[TYPE]": {  
               "[ID]": {  
                   "[NAME]": "[VALUE]"  
                   ...  
               }  
           }  
    },  
    "HasErrors": [TRUE|FALSE]  
    "Offset": [OFFSET]  
    "LIMIT": [LIMIT]  
    "TotalResults": [TOTAL_RESULTS]  
}

Response Format for Errors

{  
    "Error": {  
        "Code": "[ERROR_CODE]",  
        "Message": "[ERROR_MESSAGE]"  
    }  
}

The following HTTPS response codes are used:

The following error codes are used:

Response with header "bv-version: 5.4.1"

🚧

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/reviews.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4k&Filter=ProductId%3Adata-gen-moppq9ekthfzbc6qff3bqokie&Include=Products&Stats=Reviews'

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/reviews.json?apiversion=5.4&passkey=caB45h2jBqXFw1OE043qoMBD1gJC8EwFNCjktzgwncXY4k&Filter=ProductId%3Adata-gen-moppq9ekthfzbc6qff3bqokie&Include=Products&Stats=Reviews' \
--header 'bv-version: 5.4.1'

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.