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

Content type Display Endpoint
Review

reviews.json

Review Comment

reviewcomments.json

Question

questions.json

Answer

answers.json

Authors

authors.json

Product

products.json

Category

categories.json

Statistics

statistics.json

Stories

stories.json

Story Comment

storycomment.json

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:

Operator Description Example
eq

equal to

Filter=HasComments:eq:true
neq

Not equal to

Filter=Rating:neq:3
gt

Greater than

Filter=Rating:gt:3
lt

Less than

Filter=Rating:lt:3
gte

Greater than or equal to

Filter=TotalFeedbackCount:gte:=7
lte

Less than or equal to

Filter=SubmissionTime:lte:1468611009
'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.

Order Description Example

Time

asc

Oldest to newest

Sort=SubmissionTime:asc
desc

Newest to oldest

Sort=SubmissionTime:desc

Integer

asc

Lowest to highest

Sort=Rating:asc
desc

Highest to lowest

Sort=Rating:desc

Boolean

asc

False to true

Sort=HasComments:asc
desc

True to false

Sort=HasComments:desc

Alphabetical

asc

A to Z

Sort=UserLocation:asc
desc

Z to A

Sort=UserLocation:desc

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:

  • External ID
  • Product name
  • Product brand
  • Product description
  • Category name
  • Category hierarchy names
  • External ID
  • Category name
  • Category hierarchy names
Searching questions will also search the associated answers.
  • Title
  • Text
  • Photo caption
  • Video caption
  • Answer text (text from answers to the question)
  • Answer photo caption (text from photos from answers to the question)
  • Answer video caption (text from videos from answers to the question)
  • Product external ID
  • Product name
  • Product brand
  • Category external ID
  • Category name
  • Category hierarchy names
  • Tags (e.g., pros, cons) PRR
  • Context data values (e.g., age, gender) PRR
  • Additional fields PRR
  • Title
  • Text
  • Photo caption
  • Video caption
  • Tags (e.g., pros, cons)
  • Context data values (e.g., age, gender)
  • Additional fields
  • Text
  • Photo caption
  • Video caption
  • Tags (e.g., pros, cons) PRR
  • Context data values (e.g., age, gender) PRR
  • Additional fields PRR

Includes Review and Story comments.

  • Title
  • Text
  • Photo caption PRR
  • Video caption PRR
Stories is only available to clients on our Conversations PRR platform.
Refer to Conversations PRR Only Features for more information.
  • Title
  • Text
  • Photo caption
  • Video caption
  • Tags (e.g., pros, cons)
  • Context data values (e.g., age, gender)
  • Additional fields

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:

To apply a filter to included content use the Filter_{ContentType} parameter, replacing {ContentType} with the included content type.

In the following example, only featured comments will be returned:

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

To apply a sort to included content use the Sort_{ContentType} parameter, replacing {ContentType} with the included content type.

In the following example, the newest comments will be returned first:

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

The count of included content can specified up to a maximum value of 20 using the Limit_{ContentType} parameter, replacing {ContentType} with the included content type.

In the following example, ten comments will be returned:

reviews.json?Include=Comments&Limit_Comments=10
Paginating included content is not supported by the Conversations API. There is no Offset_{ContentType} parameter and attempting to use one will fail silently because the Conversations API does not recognize it.

Included data can be searched using the Search_{ContentType} parameter, replacing {ContentType} with the included content type.

In the following example, only products that have reviews that contain the word "dryer" will be returned:

products.json?Include=Reviews&Search_Reviews=dryer

The Search and Search_[TYPE] parameters can both be used in a single request to narrow results. For example, to search for reviews that have the word "dryer" and that have the word "best" in the included comments, use the following syntax: 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 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:

Content type Name in API response

Reviews

ReviewStatistics

Questions

QAStatistics

Answers

QAStatistics

Stories

StoryStatistics

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.

Next