Display Fundamentals

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.

This tutorial explains Conversations API display request fundamentals.

Overview

When using the Bazaarvoice Conversations API a 'display request' is a request that returns consumer generated content (CGC) intended for display in your application. A display request is accomplished by performing an HTTP 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:

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:

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

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

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 HTTP 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

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.

Next

• ← Platform & API Concepts
• Submission Fundamentals →