Display Fundamentals

This tutorial explains Conversations API display request fundamentals.

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 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 typeDisplay Endpoint
Reviewreviews.json
Review Commentreviewcomments.json
Questionquestions.json
Answeranswers.json
Authorsauthors.json
Productproducts.json
Categorycategories.json
Statisticsstatistics.json

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

OperatorDescriptionAllowable Field TypesExample
eqequal tonumeric, boolean or string fieldsFilter=HasComments:eq:true or Filter=rating:4(supported for backward compatibility)
neqNot equal tonumeric, boolean or string fieldsFilter=Rating:neq:3
gtGreater thannumeric fieldsFilter=Rating:gt:3
ltLess thannumeric fieldsFilter=Rating:lt:3
gteGreater than or equal tonumeric fieldsFilter=TotalFeedbackCount:gte:=7
lteLess than or equal tonumeric fieldsFilter=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.

OrderDescriptionExample
Time
ascOldest to newestSort=SubmissionTime:asc
descNewest to oldestSort=SubmissionTime:desc
Integer
ascLowest to highestSort=Rating:asc
descHighest to lowestSort=Rating:desc
Boolean
ascFalse to trueSort=HasComments:asc
descTrue to falseSort=HasComments:desc
Alphabetical
ascA to ZSort=UserLocation:asc
descZ to ASort=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:

Products
  • External ID
  • Product name
  • Product brand
  • Product description
  • Category name
  • Category hierarchy names
Categories
  • External ID
  • Category name
  • Category hierarchy names
Questions

❗️

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
Reviews
  • Title
  • Text
  • Photo caption
  • Video caption
  • Tags (e.g., pros, cons)
  • Context data values (e.g., age, gender)
  • Additional fields
Answers
  • Text
  • Photo caption
  • Video caption
  • Tags (e.g., pros, cons) PRR
  • Context data values (e.g., age, gender) PRR
  • Additional fields PRR
Comments Includes Review and comments.
  • Title
  • Text
  • Photo caption PRR
  • Video caption PRR

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:

Filtering

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
Sorting

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
Limiting

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 recognise it.

Searching

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 typeName in API response
ReviewsReviewStatistics
QuestionsQAStatistics
AnswersQAStatistics

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]  
}
ElementDescription
IncludesThis 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.
ResultsThis is the main results section. This section is an sorted array of Objects of the primary Content/Subject Type.
OffsetData Offset used for pagination (passed as URL parameter in a query request, defaults to 0).
LimitThe maximum number of objects returned.
TotalResultsThe 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 codeError
200The 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.
400Error processing request - error response returned.
500Errors 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 CodeError meaning
ERROR_PARAM_INVALID_API_KEYInvalid API Key value
ERROR_PARAM_INVALID_INCLUDEDInvalid "include" parameter value
ERROR_PARAM_INVALID_FILTER_ATTRIBUTEInvalid filter attribute name
ERROR_PARAM_INVALID_SORT_ATTRIBUTEInvalid sort attribute name
ERROR_PARAM_INVALID_OFFSETInvalid offset value
ERROR_PARAM_INVALID_LIMITInvalid limit value
ERROR_PARAM_INVALID_LOCALEInvalid locale code
ERROR_REQUEST_LIMIT_REACHEDRate limiting error, i.e. too many requests per time interval
ERROR_PARAM_INVALID_CALLBACKInvalid JsonP callback function name
ERROR_UNSUPPORTEDFor unsupported features, clients etc.
ERROR_ACCESS_DENIEDInsufficient privileges to perform the operation
ERROR_UNKNOWNUnknown error (internal server error, for instance)

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.