Getting Started

This page describes the fundamental knowledge that you need in order to use the Product Sentiment Export.

HTTPS service and data sets

The Product Sentiment Export differs from a traditional "REST" style API in that it consists of two distinct components which are described below:

HTTPS service

The HTTPS service refers to the HTTPS interface that is used to request product sentiment insights data sets. Interaction with the HTTPS service is a multi-step process that begins with requesting a resource that lists available manifest files, then requesting the desired manifest file, and finally requesting the data files as identified in the manifest file. The HTTPS service is described in greater detail in the Workflow Walk-Through tutorial.

data sets

The data sets consist of data files in a compressed format containing product sentiment insights. Data sets are requested using the HTTPS service. Unlike a traditional "REST" style API, these data sets are pre-calculated on a regular basis. Further, instead of representing a resource, each data file contains many lines of text that can be evaluated as a JSON object. Learn more about the data sets on the Reference page.

This hybrid architecture allows for speed at the cost of some flexibility. For example, we encourage you to perform multiple concurrent requests to the HTTPS service. However, because the data sets are pre-computed, the HTTPS service does not offer any filters or sorting options common to "REST" style APIs.

Environments

The Product Sentiment Export supports the following environments:

Environment Domain Description
Staging https://stg.api.bazaarvoice.com Used while developing your application.
Production https://api.bazaarvoice.com Used when your application is complete.

These environments use different API keys and as a result have independent rate limits. This allows you to develop applications using the staging environment without jeopardizing the stability of the production environment. However, both environments will return production data.

Required headers

All requests must include the following headers:

Name Description
Host Environment, staging or production, that will process the request.
X-Bazaarvoice-Passkey

The passkey key described in the Credentials section.

X-Bazaarvoice-Signature

An access signature used to verify the request. This is created by your application for each request. Refer to Creating the access signature for additional details.

X-Bazaarvoice-Timestamp

A Unix timestamp in milliseconds. Requests will be valid for 3600 seconds after the time stamp is created. Requests using an expired timestamp will return an error.

Versioning

The Product Sentiment Export exposes two version types: One for the HTTPS service and another for the data sets. This allows you to retain control over how you interact with the Product Sentiment Export and decouples your implementation from future changes to the Product Sentiment Export until you are ready to upgrade.

This table shows all versions:

Version Release Date Deprecation Date Status
HTTPS service version (identifies the structure of the URL path, query string parameters and headers)
v1 2019-02-01 TBD Latest
data sets version (identifies the structure of the data returned by the Product Sentiment Export)
v1 2019-02-01 TBD Latest

Latest

This is newest version. Feature development is focused on future versions, but we may perform backwards compatible bug fixes. New applications SHOULD use this version.

๐Ÿ“˜

On June 15th 2021, the v1 datasets were augmented to start including French/German and incentivized content. The dataset version was not incremented as this is a non-breaking change, and Client PSI Applications are expected to continue working without modifications.

If you are an existing PSI customer, minor modifications may be suitable for your applications if you want to introduce special handling of French/German or incentivized content. You also have the option of requesting the exclusion of incentivized content, and selecting which of the supported languages are included in your PSI datasets.

On July 31 2022, the v1 datasets were augmented to start including Spanish content. The dataset version was not incremented as this is a non-breaking change, and Client PSI Applications are expected to continue working without modifications.

Configuration Options

The Product Sentiment Export supports the following configuration options:

Incentivized Content

You can choose whether incentivized content is included in your datasets. Incentivized content will be included by default.

Languages

You can choose which of the supported languages are included in your datasets. The supported languages are English, Spanish, French and German. All supported languages will be included by default.

To update the values for these configuration options, please reach out to Bazaarvoice Client Care or your technical contact at Bazaarvoice.

Data update intervals

Product Sentiment Export data is available in the following intervals:

IntervalManifest designationDescription
At least monthlyfullBazaarvoice will generate data sets at least once a month for all available content. You should completely replace your data store using the latest data files as they are available. This ensures that your data store does not fall out of sync with the Bazaarvoice network.

Credentials

The following required credentials will be provided by Bazaarvoice:

Type Description
Passkey A unique per-environment identifier included with each request. You will receive two passkeys, one for staging and one for production.
Shared Secret Available along with Passkey in developer tools.Used to encrypt the access signature. Known only to you and Bazaarvoice. You will receive two secrets, one for staging and one for production.Across this documentation it is mentioned as shared secret key.