Analytics

Use cases

Because our APIs mirror how custom charts work on the Wonderboard, the examples below are a side-by-side comparison of how to get the same results from the dashboard and from the API.

Use this flow to get feedback count by channel for a product, or to count how many distinct channels have reviews for that product.

Follow two steps: resolve the product ID from the products endpoint, then call the analytics endpoint with that ID.

Get the product ID for the product by name and brand

Call the products endpoint with the product name and brand to retrieve the product list. From the response, take the id of the product you need (e.g. “IPL Medical HE” from brand “Philips”).

Call the analytics endpoint with the product ID

Use the product id from the previous response (e.g. 68cabf8acc9231762e05797b) in the analytics request to get the feedback count broken down by channel.

To break down by country instead, follow the same steps and use a country breakdown rather than channel.

POST /v3/analytics

Response example
{
  "data": [
    {
      "value": 147,
      "valueInfo": 56,
      "label": "amazon.com"
    },
    {
      "value": 45,
      "valueInfo": 17,
      "label": "amazon.sa"
    },
    {
      "value": 39,
      "valueInfo": 15,
      "label": "BV-philips"
    },
    {
      "value": 39,
      "valueInfo": 15,
      "label": "noon.com"
    },
    {
      "value": 16,
      "valueInfo": 6,
      "label": "extra.com"
    }
  ]
}

Why are channels and countries coming from reviews different from the ones configured in the product?

It’s a common point of confusion, but the discrepancy usually boils down to the difference between potential and actual data.

Think of it like a guest list versus the people who actually show up to the party. Here is the breakdown of why those lists don’t always match:

Configuration vs. Activity: When you configure a product, you define the scope—the full list of channels and countries you want to monitor. However, the reviews reflect reality. If a product is configured for 20 countries but has only been purchased and reviewed in 5, the analytics will only show those 5 active locations.
The Data Fetching Logic: The same two-step flow highlights this gap:
- Product Endpoint: Shows what you have “subscribed” to or configured.
- Analytics/Reviews Endpoint: Shows where feedback has actually been recorded.

In this case we want to reproduce this chart: having the feedback count broken down by time and by country, showing the feedback count for each country in a yearly timeframe and considering the feedback count as an instant count.

POST /v3/analytics

In this case we want to reproduce a report showing the pros and cons (strengths and weaknesses) broken down by topic, with the ontology type set to Property and considering only the Positive and Negative sentiment.

The available ontology types and their topic tree depend on the dictionary configured for your product. You can discover the full ontology tree by calling the GET /v3/topics endpoint with the product ID. The response returns the hierarchy of topics, their levels, and the ontology type each topic belongs to (e.g. Property, Component, Communication & Service, Topic), so you can pick the right ontology and topicLevel values for your analytics request.

POST /v3/analytics

Response example
{
  "Feedback count": [
    { "value": 12871, "valueInfo": 27, "label": "Performance", "label2": "Positive" },
    { "value": 7975, "valueInfo": 17, "label": "Design", "label2": "Positive" },
    { "value": 7171, "valueInfo": 15, "label": "Performance", "label2": "Negative" },
    { "value": 5924, "valueInfo": 12, "label": "Ease of use", "label2": "Positive" },
    { "value": 3582, "valueInfo": 7, "label": "Quality", "label2": "Negative" },
    { "value": 2439, "valueInfo": 5, "label": "Design", "label2": "Negative" },
    { "value": 1659, "valueInfo": 3, "label": "Value & price", "label2": "Positive" },
    { "value": 1259, "valueInfo": 3, "label": "Ease of use", "label2": "Negative" },
    { "value": 1242, "valueInfo": 3, "label": "Quality", "label2": "Positive" },
    { "value": 941, "valueInfo": 2, "label": "Value & price", "label2": "Negative" }
  ]
}

In the response, value is the number of feedback, valueInfo is the percentage, label is the topic, and label2 is the sentiment.

In this case we want to reproduce this chart: having the relevance broken down by topic, showing all the topics, with the ontology type set to Property and considering only the Positive and Negative sentiment.

POST /v3/analytics

In this case we want to reproduce a report that shows the Votes rating broken down by SKU and country. The response includes the votes count as well (valueInfo), so a single request gives you both metrics.

POST /v3/analytics

Response example
{
  "data": [
    {
      "value": 4.5,
      "valueInfo": 1245,
      "label": "BRI984/02",
      "label2": "United Kingdom"
    },
    {
      "value": 4.2,
      "valueInfo": 892,
      "label": "BRI984/02",
      "label2": "Germany"
    },
    {
      "value": 3.9,
      "valueInfo": 456,
      "label": "BRI932/02",
      "label2": "United Kingdom"
    },
    {
      "value": 4.1,
      "valueInfo": 310,
      "label": "BRI932/02",
      "label2": "France"
    }
  ]
}

In the response, value is the average rating, valueInfo is the votes count, label is the first breakdown (SKU), and label2 is the second breakdown (country).

Use this flow to get the Votes rating broken down by country and channel for each SKU of a product. It requires two steps: first retrieve the product’s SKU list, then call the analytics endpoint once per SKU, filtering by that SKU and breaking down by country and channel.

Retrieve the product list and its SKUs

Call the products endpoint to get the product and its SKUs.

Endpoint
GET /v3/products/

From the response, note each product’s id and skus array. You will iterate over each SKU in the next step.

A SKU is typically linked to a single product, so you won’t need more than one analytics call per SKU.

Call the analytics endpoint for each SKU

For every SKU returned in the previous step, call the analytics endpoint with the product ID, a sku filter set to that SKU, and a breakdown by country and channel.

POST /v3/analytics

Response example
{
  "data": [
    {
      "value": 4.5,
      "valueInfo": 320,
      "label": "United Kingdom",
      "label2": "amazon.co.uk"
    },
    {
      "value": 4.3,
      "valueInfo": 215,
      "label": "Germany",
      "label2": "amazon.de"
    },
    {
      "value": 4.1,
      "valueInfo": 142,
      "label": "France",
      "label2": "amazon.fr"
    }
  ]
}

In the response, value is the average rating, valueInfo is the votes count, label is the first breakdown (country), and label2 is the second breakdown (channel). Repeat this call for each SKU in the product’s skus array to build the full picture.

In this case we want to reproduce this chart, having the Votes rating KPI trend monthly.

POST /v3/analytics

Below is a typical response shape from the Analytics API for this chart.

{
  "data": [
    {
      "value": 4.3,
      "label": "2024-03-01T00:00:00.000Z"
    },
    {
      "value": 4.3,
      "label": "2024-04-01T00:00:00.000Z"
    },
    {
      "value": 4.3,
      "label": "2024-05-01T00:00:00.000Z"
    },
    {
      "value": 4.3,
      "label": "2024-06-01T00:00:00.000Z"
    },
    {
      "value": 4.3,
      "label": "2024-07-01T00:00:00.000Z"
    },
    {
      "value": 4.3,
      "label": "2024-08-01T00:00:00.000Z"
    },
    {
      "value": 4.35,
      "label": "2024-09-01T00:00:00.000Z"
    },
    {
      "value": 4.2,
      "label": "2024-10-01T00:00:00.000Z"
    },
    {
      "value": 4.2,
      "label": "2024-11-01T00:00:00.000Z"
    },
    {
      "value": 4.33,
      "label": "2024-12-01T00:00:00.000Z"
    },
    {
      "value": 4.33,
      "label": "2025-01-01T00:00:00.000Z"
    }
  ]
}

Parameters in depth

The request body combines required fields, optional filters, and per-KPI settings. Together they define:

Which segment(s) of data to use
Which KPI(s) to compute for that segment
How each KPI is broken down and sorted

Full schema and the interactive playground are on the /analytics API reference page.

ProductIds (required)

The array of product IDs for which we want to retrieve the data.

e.g. "productIds": [ "5fa3d1d497f3ead6ea0ce7e5" ]

Where do I get product IDs?

You can use the products endpoint to retrieve the product IDs available in your scope.

DataType (required)

Which dataset the query runs against (Feedback, Votes, or Prices).

e.g. "dataType": "Feedback"

Available data types are:

Feedback
Votes
Prices

Filters

The body may include a filters array using the same syntax as elsewhere in the dashboard.

e.g. "filters": [{ "name": "rating", "values": 1 }]

Learn more about filters in the filters section.

Configurations (required)

configurations is an array of one or more objects. Each object describes one KPI query against the same productIds, dataType, and filters. You can include up to five objects in the array to retrieve multiple KPIs in a single request.

Each configuration object has the following properties:

kpi: the KPI to apply to the data scope that you have selected.
breakdown: the breakdown(s) of the KPI.
options: the options to apply to the data scope that you have selected.

When you pass more than one configuration object, productIds must contain exactly one product ID (see Validation and required values).

KPI (required)

The KPI that you wish to apply to the data scope that you have selected.

e.g. "kpi": "Feedback count"

Available KPIs are:

Feedback count
Feedback rating
Votes count
Votes rating
NPS
Sentiment index
TGW
Relevance
Subratings

Each configuration object must use a distinct KPI (no duplicates in the same request). You can provide at most five configuration objects (for the same data source).

Breakdown (required)

The breakdown is an array of a maximum of two elements, describing which breakdown the KPI should consider.

e.g. "breakdown": [
    {
      "name": "channel",
      "shortlist": "TOP10"
    }
  ]

Each breakdown has the following properties:

name: the name of the property to break down.

Supported values are the usual properties: “channel”, “continent”, “country”, “feedback property”, “nps category”, “sku”, “star value”, “time”, “topic”.

Configured channelCustomFields can also be passed here like age or skin tone.

shortlist: use when you need to cap how many breakdown values are returned.

Accepted values are: All, TOP5, TOP10.

values: use when you only want certain values of the breakdown.

Pass an array of strings; each entry must be a valid value for that breakdown (for example, country names for a country breakdown).

Example for country: ["Italy", "Germany", "France"].

Current limitation

At present, only one breakdown is available for the following KPIs: Subratings and Relevance.

If the KPI selected is Subratings:

The breakdown must be subrating or time, no other breakdowns are supported
In the breakdown by time, a subrating must be selected

Options

Optional settings are passed in the options object on each configuration.

e.g. "options": { "sort": { "name": "Value", "order": "DESC" } }

Sort

Controls sort order for the result series.

e.g. "sort": { "name": "Value", "order": "DESC" }

name: Label to sort by label, or Value to sort by value
order: ASC or DESC

Sentiment

Displays series related to a specific sentiment (only available if breaking down by topic)

e.g. "sentiment": ["Positive", "Neutral"]

The admissible values are: Positive, Negative, Neutral

Timeframe

The time resolution you want the series to be aggregated with when breaking by time

e.g. "timeframe": "Month"

The admissible values are: Week, Month, Quarter, Year

Only available in a time breakdown.

Count

For a time breakdown, whether values are instant point-in-time counts or cumulative over time.

e.g. "count": "Cumulative"

The admissible values are: Instant, Cumulative

Only available in a time breakdown.

Ontology

The ontology type that should be considered. You can discover the available ontology types and their topic tree by calling the GET /v3/topics endpoint with the product ID.

e.g. "ontology": "Topic"

The admissible values are: Topic, Communication & Service, Property, Component.

Ontology option is only available in a topic breakdown if it is configured in your space data scope.

Topic Level

The level of the topic to be considered. You can discover the available topic levels by calling the GET /v3/topics endpoint with the product ID.

e.g. "topicLevel": 2

The admissible values are numbers up to the level of topic available in your dictionary

Topic level option is only available in a topic breakdown.

Validation and required values

Requests are flexible, so the API validates inputs and returns clear errors when something is missing or inconsistent.

The main rules are:

If you send more than one object in configurations, productIds must contain exactly one product ID.
The KPI must match dataType. For example, dataType: Feedback with KPI Votes count returns no data. Votes count, Votes rating, and Subratings expect dataType: Votes.
For Relevance, the endpoint returns data only if the breakdown includes topic.
The number of breakdowns must always be at maximum 2.
There can only be one breakdown for the following KPIs: Subratings, Relevance.
The options timeframe and count are only available if a breakdown by time is selected.
The options topicLevel and ontology are only available when a topic breakdown is used (including for Feedback count and Relevance).
If the KPI selected is Relevance:
- The ontology option is required and must be compliant with the dictionary.
- In the breakdown by time, you must set at least 1 topic as value and it must exist in the dictionary.
If the KPI selected is Subratings:
- The breakdown must be subrating or time, no other breakdowns are supported.
- In the breakdown by time, a subrating must be selected.

API Documentation

Token

Feedback

Votes

Page

Product

Brand

Channel

User

Analytics

Use cases

Parameters in depth

ProductIds (required)

DataType (required)

Filters

Configurations (required)

KPI (required)

Breakdown (required)

Options

Sort

Sentiment

Timeframe

Count

Ontology

Topic Level

Validation and required values

API Documentation

Token

Feedback

Votes

Page

Product

Analytics

Brand

Channel

User

​Use cases

​Parameters in depth

​ProductIds (required)

​DataType (required)

​Filters

​Configurations (required)

​KPI (required)

​Breakdown (required)

​Options

​Sort

​Sentiment

​Timeframe

​Count

​Ontology

​Topic Level

​Validation and required values

Use cases

Parameters in depth

ProductIds (required)

DataType (required)

Filters

Configurations (required)

KPI (required)

Breakdown (required)

Options

Sort

Sentiment

Timeframe

Count

Ontology

Topic Level

Validation and required values