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 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:
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 |
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
%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 thejson
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:
Operator | Description | Allowable Field Types | Example |
---|---|---|---|
eq | equal to | numeric, boolean or string fields | Filter=HasComments:eq:true or Filter=rating:4 (supported for backward compatibility) |
neq | Not equal to | numeric, boolean or string fields | Filter=Rating:neq:3 |
gt | Greater than | numeric fields | Filter=Rating:gt:3 |
lt | Less than | numeric fields | Filter=Rating:lt:3 |
gte | Greater than or equal to | numeric fields | Filter=TotalFeedbackCount:gte:=7 |
lte | Less than or equal to | numeric fields | 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 usingFilter=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:
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
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
andOffset
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 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:
Content type | Name in API response |
---|---|
Reviews | ReviewStatistics |
Questions | QAStatistics |
Answers | QAStatistics |
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]
}
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 HTTPS response codes are used:
HTTP[s] 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 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.
Updated about 2 months ago