Tutorial: polling for new Mentions

How to write a program that continually gets the latest mentions for your query.

A common integration use case is to continually populate a display with Mentions from a Brandwatch Query. This, for example, is something that we ourselves do in some of our Vizia tiles.

The behaviour that we want to achieve is as follows:

  1. On application start up, we want to retrieve the latest 100 mentions.
  2. At every polling interval, we want to get the latest mentions since the last time that we polled.

In this tutorial we will assume that the application has already logged in and has a token.

Getting the latest 100 mentions

When our application runs for the first time, we want to get the latest 100 mentions for our query. We use the following parameters to achieve this:




This returns 100 Mentions per request.



This sets the page market to the latest page, which is indexed from 0.



This orders the Mentions by their resourceId, which is a global counter incremented for every new Mention that we crawl.



This changes the sort direction to descending, ensuring that the newest result is returned first.

Here is the request as a cURL command.

curl -X GET https://api.brandwatch.com/projects/289733322/data/mentions?queryId=348973733&startDate=2016-05-01&endDate=2016-05-02&pageSize=100&page=0&orderBy=id&orderDirection=desc

This will return a list of Mentions, newest first. The following example response has had the Mentions removed for brevity.

  "resultsTotal": 99,
  "resultsPage": 0,
  "resultsPageSize": 100,
  "results": [...],
  "maximumId": 100057070129,
  "maximumIdInResult": 100057070129,
  "startDate": "2016-05-01T00:00:00.000+0000",
  "endDate": "2016-05-02T00:00:00.000+0000"

Each page of Mentions contains a maximumIdInResult field, which is the latest id of a Mention in your result. In your application, parse this value and store it. You will then use it in the next call to get all new Mentions from that point onwards.

Polling for new mentions

Having parsed the maximumIdInResult field, you are now ready to request all of the Mentions that have matched your Query that have an id greater than 100057070129. To do that, we will be using the sinceId parameter.




Retrieve all Mentions that have an id greater than 100057070129.

We then add this to our new request:

curl -X GET https://api.brandwatch.com/projects/289733322/data/mentions?queryId=348973733&startDate=2016-05-01&endDate=2016-05-02&pageSize=100&page=0&orderBy=id&orderDirection=desc&sinceId=100057070129

This then returns the newest 100 mentions since we last polled. Repeat this process in order to continually poll for new Mentions in your integration.

Tutorial: polling for new Mentions

How to write a program that continually gets the latest mentions for your query.