Topics (New)

Effective topic analysis allow you to glean a quick overview of the popular topics within any conversation. Our technology makes use of the latest natural language processing (NLP) techniques to extract insightful topics from your dataset.

This endpoint matches the functionality found in the "Word Cloud" component in BCR itself.

You can also use the Brandwatch topics functionality via the Consumer Research API.

• Required Parameters
• Optional Parameters
• Example Call

Required Parameters

The topics data calls requires these fields (apart from extract these are the same as with the mentions endpoint):

Note: you can specify the time zone by replacing +xxxx with the ISO UTC offset, e.g -0500 for New York standard time. Important: The character + should be URL encoded to %2B

For the extract parameter the topic types are:

• emojis extract emojis from the text of mentions
• entities extract Entities (aka "AI Powered Keywords") from the text of mentions
• words extract frequent (or trending) words from the text of mentions
• phrases extract phrases (minimum of two word length) from the text of mentions
• people extract words/phrases that appear to refer to people (English only)
• places extract words/phrases that appear to refer to places (English only)
• organisations extract words/phrases that appear to refer to organisations (English only)

Optional Parameters

Some additional parameters that will be useful:

For the metrics parameter the allowed values are:

• volume topics will include a volume field that represents how often the topic occurs in the query (always returned as a default anyway)
• percentageVolume topics will include a percentageVolume field that is from 1-100 with the volume of the topic within the overall query
• sentiment topics will include a sentimentScorefield (-100 to 100 depending on how "negative" or "positive" the topic is) and a sentiment breakdown field (e.g. { "positive": 0, "neutral": 4, "negative": 0 })
• gender topics will include a gender breakdown field (e.g. {"male": 1, "female": 2})
• trendingtopics will include a trending field that indicates whether a topic tends to appears to be "trending" (talked about only recently). Positive values indicate it is trending and negative that is fading.
• timeSeries topics will include a timeSeries field that includes a set of data points indicating topic volume of time. The nature and number of data points will vary depending on the date range used. The data point units can be minutes, hours, days, weeks months or years

Notes

Only set the metrics parameter to values that you actually will need to use. Requesting fewer metrics will make the API call faster, so there is no point asking for metrics that will then be ignored in the response.

Also be aware that the words topics will tend to dominate your responses when ordering by volume (the default). This is because a single word will tend to appear in more mentions than a specific phrase.

Example Call

curl -X GET 'https://api.brandwatch.com/projects/162500080/data/topics?queryId=163039395&startDate=2025-06-01&endDate=2025-07-22&extract=phrases&metrics=percentageVolume,sentiment,timeSeries,trending&limit=2'

The response will look like this:

{
  "topics": [
    {
      "sentimentScore": 0,
      "percentageVolume": 14.285714285714285,
      "trending": 1.5510621240350537,
      "volume": 7,
      "label": "self-portrait drawing",
      "id": "self-portrait drawing",
      "type": "phrase",
      "sentiment": {
        "positive": 0,
        "neutral": 7,
        "negative": 0
      },
      "timeSeries": {
        "unit": "weeks",
        "values": [
          {
            "date": "2025-05-26T00:00:00.000+0000",
            "volume": 0
          },
          {
            "date": "2025-06-02T00:00:00.000+0000",
            "volume": 0
          },
          {
            "date": "2025-06-09T00:00:00.000+0000",
            "volume": 2
          },
          {
            "date": "2025-06-16T00:00:00.000+0000",
            "volume": 1
          },
          {
            "date": "2025-06-23T00:00:00.000+0000",
            "volume": 0
          },
          {
            "date": "2025-06-30T00:00:00.000+0000",
            "volume": 0
          },
          {
            "date": "2025-07-07T00:00:00.000+0000",
            "volume": 0
          },
          {
            "date": "2025-07-14T00:00:00.000+0000",
            "volume": 4
          },
          {
            "date": "2025-07-21T00:00:00.000+0000",
            "volume": 0
          }
        ]
      }
    },
    {
      "sentimentScore": 0,
      "percentageVolume": 6.122448979591836,
      "trending": 1.0838324216720436,
      "volume": 3,
      "label": "Colored Pencil",
      "id": "Colored Pencil",
      "type": "phrase",
      "sentiment": {
        "positive": 0,
        "neutral": 3,
        "negative": 0
      },
      "timeSeries": {
        "unit": "weeks",
        "values": [
          {
            "date": "2025-05-26T00:00:00.000+0000",
            "volume": 0
          },
          {
            "date": "2025-06-02T00:00:00.000+0000",
            "volume": 1
          },
          {
            "date": "2025-06-09T00:00:00.000+0000",
            "volume": 0
          },
          {
            "date": "2025-06-16T00:00:00.000+0000",
            "volume": 0
          },
          {
            "date": "2025-06-23T00:00:00.000+0000",
            "volume": 0
          },
          {
            "date": "2025-06-30T00:00:00.000+0000",
            "volume": 1
          },
          {
            "date": "2025-07-07T00:00:00.000+0000",
            "volume": 1
          },
          {
            "date": "2025-07-14T00:00:00.000+0000",
            "volume": 0
          },
          {
            "date": "2025-07-21T00:00:00.000+0000",
            "volume": 0
          }
        ]
      }
    }
  ]
}