Polling for new Mentions

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:

On application start up, we want to retrieve the latest 100 mentions.
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. We also recommend that you read the section in our documentation about Mentions, in addition to this tutorial.

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:

Parameter	Value	Reasoning
`pageSize`	100	This returns 100 Mentions per request.
`page`	0	This sets the page market to the latest page, which is indexed from 0.
`orderBy`	`added`	This orders the Mentions by their `added`, which is the time the mention appears in the query
`orderDirection`	`desc`	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/1998232810/data/mentions?queryId=1999544643&startDate=2019-01-16&endDate=2019-01-17&pageSize=100&page=0&orderBy=added&orderDirection=desc'

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

{
  "results": [
    {
      "added": "2019-01-16T23:56:28.157+0000",
      ...
    },
    {
      "added": "2019-01-16T23:36:52.237+0000",
    },
    ...
  ],
  "resultsPage": 0,
  "resultsPageSize": 100,
  "resultsTotal": 55,
  "startDate": "2019-01-16T00:00:00.000+0000",
  "endDate": "2019-01-17T00:00:00.000+0000",
  "maximumIdInResult": 230465512809,
  "maximumId": 230465512809
}

Each mention in the response results will have an added field. This is the date the mention was added to the query. In your application, find the mention with the most recent added value and store it (2019-01-16T23:56:28.157+0000 in this case). You will then use it in the next call to get all new Mentions from that point onwards.

Polling for new mentions

Having read the added field from your mentions, you are now ready to request all of the Mentions that have matched your Query that have an added greater than 2019-01-16T23:56:28.157+0000. To do that, we will be using the sinceAdded parameter.

Parameter	Value	Reasoning
`sinceAdded`	2019-01-16T23:56:28.157+0000	Retrieve all Mentions that have an `added` date later than 2019-01-16T23:56:28.157+0000.

We then add this to our new request (NB the date has been URL encoded):

curl -X GET 'https://api.brandwatch.com/projects/1998232810/data/mentions?queryId=1999544643&startDate=2019-01-16&endDate=2019-01-17&pageSize=100&page=0&orderBy=added&orderDirection=desc&sinceAdded=2019-01-16T23%3A56%3A28.157%2B0000'

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.

Finding only new mentions

When a query is "backfilled" the added field will be reset for each mention. This may be useful for you, as it helps you detect if the backfill produced any different mentions you had not seen before. However if you do not want this behaviour you can apply another parameter to only return "new" mentions.

Parameter	Value	Reasoning
`sourceType`	`new`	Hide backfilled mentions and only show mentions that have been newly matched to your query

We can add that to our request like this:

curl -X GET 'https://api.brandwatch.com/projects/1998232810/data/mentions?queryId=1999544643&startDate=2019-01-16&endDate=2019-01-17&pageSize=100&page=0&orderBy=added&orderDirection=desc&sourceType=new'

This will then only return "new" mentions and not those created during a backfill.