Topics

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.

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

Required Parameters

The topics data call has the same three required parameters as the Mentions call:

Parameter	Definition	Accepted Values
`queryId` / `queryGroupId`	The ID of the Query or Query Group that contains the Mentions for which you'd like to see Topics.	int (Learn how to retrieve your Query ID or Query Group ID
`startDate`	The beginning of the date range that contains the Mentions.	"YYYY-MM-DD'T'hh:mm:ss.xxx+xxxx"
`endDate`	The end of the date range that contains the Mentions.	"YYYY-MM-DD'T'hh:mm:ss.xxx+xxxx"

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

Optional Parameters

Some additional parameters that will be useful:

Parameter	Definition	Accepted Values
`orderBy`	Metric by which you wish to order the topics returned.	"volume" - the number of Mentions the topic appears in "burst" - the rate that the topic has emerged over time
`limit`	The maximum number of topics to be returned.	int
`excludeCategories`	You have the option to exclude Categories from the topics returned (this is often done in the Brandwatch Analytics UI).	TRUE, FALSE
`excludeTags`	You have the option to exclude Tags from the topics returned (this is often done in the Brandwatch Analytics UI).	TRUE, FALSE

Example Call

curl -X GET 'https://api.brandwatch.com/projects/397263282/data/volume/topics/queries?queryId=389734742&startDate=2023-05-01&endDate=2023-05-07&orderBy=burst&limit=2'

The response will look like this:

{
  "topics": [
    {
      "id": "1998640329__Lipstick",
      "label": "Lipstick",
      "volume": 3,
      "type": "topic",
      "sentiment": {
        "neutral": 1,
        "positive": 2
      },
      "sentimentScore": 116,
      "burst": 100,
      "days": [
        {
          "date": "2016-05-05T00:00:00.000+0000",
          "volume": 1
        },
        {
          "date": "2016-05-04T00:00:00.000+0000",
          "volume": 2
        },
        {
          "date": "2016-05-02T00:00:00.000+0000",
          "volume": 0
        },
        {
          "date": "2016-05-01T00:00:00.000+0000",
          "volume": 0
        },
        {
          "date": "2016-05-06T00:00:00.000+0000",
          "volume": 0
        },
        {
          "date": "2016-05-03T00:00:00.000+0000",
          "volume": 0
        }
      ],
      "pageType": {
        "blog": 0,
        "facebook": 2,
        "forum": 1,
        "general": 0,
        "image": 0,
        "instagram": 0,
        "news": 0,
        "review": 0,
        "twitter": 0,
        "video": 0
      },
      "queries": [
        {
          "id": 1998640329,
          "name": "Makeup",
          "volume": 3
        }
      ]
    },
    {
      "id": "1998640329__Rashes",
      "label": "Rashes",
      "volume": 5,
      "type": "topic",
      "sentiment": {
        "neutral": 5
      },
      "sentimentScore": 50,
      "burst": 100,
      "days": [
        {
          "date": "2016-05-05T00:00:00.000+0000",
          "volume": 2
        },
        {
          "date": "2016-05-04T00:00:00.000+0000",
          "volume": 0
        },
        {
          "date": "2016-05-02T00:00:00.000+0000",
          "volume": 0
        },
        {
          "date": "2016-05-06T00:00:00.000+0000",
          "volume": 2
        },
        {
          "date": "2016-05-01T00:00:00.000+0000",
          "volume": 0
        },
        {
          "date": "2016-05-03T00:00:00.000+0000",
          "volume": 0
        }
      ],
      "pageType": {
        "blog": 0,
        "facebook": 5,
        "forum": 0,
        "general": 0,
        "image": 0,
        "instagram": 0,
        "news": 0,
        "review": 0,
        "twitter": 0,
        "video": 0
      },
      "queries": [
        {
          "id": 389734742,
          "name": "Makeup",
          "volume": 5
        }
      ]
    }
  ]
}