Basic charts

Creating a chart out of your Mentions.

On this page we will show:

General Format

As well as retrieving pages of Mentions, you can also create charts out of them. The charts data call is in the following format:

/data/{aggregate}/{dimension1}/{dimension2}

The aggregate is. Some example aggregates are:

  • volume - The number of Mentions found.
  • sentiment - The sentiment of the Mentions.
  • pageType - The page type of the Mentions.
  • authors - The distinct authors who posted.

The two dimensions are your x and y axes on the chart. Some example dimensions are:

  • days - The days over which the Mentions were found.
  • queries - The Queries that the Mentions are located in.
  • gender - The gender of the authors.
  • location - The locations the Mentions were posted from.

For full details on the available aggregates and dimensions, see the Aggregates and dimensions page of the documentation.

Required Parameters

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

ParameterDefinitionAccepted Values
queryId / queryGroupIdThe ID of the Query or Query Group that contains the Mentions for which you'd like to see.int
(Learn how to retrieve your Query ID or Query Group ID)
startDateThe beginning of the date range that contains the Mentions."YYYY-MM-DD'T'hh:mm:ss.xxx+xxxx"
endDateThe 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

Dimension Parameters

Some dimensions support (and sometimes require) additional parameters to control how the dimension functions. An example of this is the tags dimension takes in a list of tags the user is interested in performing the breakdown by.

These additional parameters take the form of dimXArgs where X is the dimension's position in the request path (either 1 or 2).

Some dimensions also support a dimXLimit parameter, again where X is the dimension's position in the request path (either 1 or 2). For example when used with the subreddits dimension it will limit the number of top subreddits in the response.

Example Call - Volume of Mentions in a Query by Sentiment

An example call is below, which charts the volume of Mentions (the aggregate) for the Sentiment (the first dimension) broken down by the days (the second dimension):

curl -X GET 'https://api.brandwatch.com/projects/397263282/data/volume/sentiment/days?queryId=9226732&startDate=2023-05-01&endDate=2023-05-07'

The response will look like this:

{
  "aggregate": "volume",
  "dimension1": "sentiment",
  "dimension2": "days",
  "results": [
    {
      "id": "negative",
      "name": "negative",
      "data": {},
      "values": [
        {
          "id": "2016-05-05T00:00:00.000+0000",
          "name": "2016-05-05 00:00:00.0",
          "value": 12,
          "data": {}
        },
        {
          "id": "2016-05-04T00:00:00.000+0000",
          "name": "2016-05-04 00:00:00.0",
          "value": 10,
          "data": {}
        },
        {
          "id": "2016-05-02T00:00:00.000+0000",
          "name": "2016-05-02 00:00:00.0",
          "value": 10,
          "data": {}
        },
        {
          "id": "2016-05-01T00:00:00.000+0000",
          "name": "2016-05-01 00:00:00.0",
          "value": 5,
          "data": {}
        },
        {
          "id": "2016-05-06T00:00:00.000+0000",
          "name": "2016-05-06 00:00:00.0",
          "value": 10,
          "data": {}
        },
        {
          "id": "2016-05-03T00:00:00.000+0000",
          "name": "2016-05-03 00:00:00.0",
          "value": 8,
          "data": {}
        }
      ]
    },
    {
      "id": "neutral",
      "name": "neutral",
      "data": {},
      "values": [
        {
          "id": "2016-05-05T00:00:00.000+0000",
          "name": "2016-05-05 00:00:00.0",
          "value": 104,
          "data": {}
        },
        {
          "id": "2016-05-04T00:00:00.000+0000",
          "name": "2016-05-04 00:00:00.0",
          "value": 110,
          "data": {}
        },
        {
          "id": "2016-05-02T00:00:00.000+0000",
          "name": "2016-05-02 00:00:00.0",
          "value": 111,
          "data": {}
        },
        {
          "id": "2016-05-01T00:00:00.000+0000",
          "name": "2016-05-01 00:00:00.0",
          "value": 78,
          "data": {}
        },
        {
          "id": "2016-05-06T00:00:00.000+0000",
          "name": "2016-05-06 00:00:00.0",
          "value": 93,
          "data": {}
        },
        {
          "id": "2016-05-03T00:00:00.000+0000",
          "name": "2016-05-03 00:00:00.0",
          "value": 103,
          "data": {}
        }
      ]
    },
    {
      "id": "positive",
      "name": "positive",
      "data": {},
      "values": [
        {
          "id": "2016-05-05T00:00:00.000+0000",
          "name": "2016-05-05 00:00:00.0",
          "value": 16,
          "data": {}
        },
        {
          "id": "2016-05-04T00:00:00.000+0000",
          "name": "2016-05-04 00:00:00.0",
          "value": 19,
          "data": {}
        },
        {
          "id": "2016-05-02T00:00:00.000+0000",
          "name": "2016-05-02 00:00:00.0",
          "value": 16,
          "data": {}
        },
        {
          "id": "2016-05-01T00:00:00.000+0000",
          "name": "2016-05-01 00:00:00.0",
          "value": 22,
          "data": {}
        },
        {
          "id": "2016-05-06T00:00:00.000+0000",
          "name": "2016-05-06 00:00:00.0",
          "value": 14,
          "data": {}
        },
        {
          "id": "2016-05-03T00:00:00.000+0000",
          "name": "2016-05-03 00:00:00.0",
          "value": 25,
          "data": {}
        }
      ]
    }
  ]
}

Example Call - Weekly Share of Voice

It is possible to create a huge variety of charts that you can embed into your own applications. For example, given a Query Group that consists of Queries for your own brands and your competitors brands, you could create a weekly share of voice chart:

curl -X GET 'https://api.brandwatch.com/projects/1998179136/data/volume/queryGroups/weeks?queryGroupId=183104417&startDate=2016-01-01&endDate=2016-05-07'

The response will look like the following:

{
  "aggregate": "volume",
  "dimension1": "queryGroups",
  "dimension2": "weeks",
  "results": [
    {
      "id": 183104417,
      "name": "All Topics",
      "data": {},
      "values": [
        {
          "id": "2016-02-29T00:00:00.000+0000",
          "name": "2016-02-29 00:00:00.0",
          "value": 3,
          "data": {}
        },
        {
          "id": "2016-04-04T00:00:00.000+0000",
          "name": "2016-04-04 00:00:00.0",
          "value": 1200,
          "data": {}
        },
        {
          "id": "2016-04-25T00:00:00.000+0000",
          "name": "2016-04-25 00:00:00.0",
          "value": 1258,
          "data": {}
        },
        {
          "id": "2016-01-25T00:00:00.000+0000",
          "name": "2016-01-25 00:00:00.0",
          "value": 2,
          "data": {}
        },
        {
          "id": "2016-02-15T00:00:00.000+0000",
          "name": "2016-02-15 00:00:00.0",
          "value": 4,
          "data": {}
        },
        {
          "id": "2016-01-11T00:00:00.000+0000",
          "name": "2016-01-11 00:00:00.0",
          "value": 0,
          "data": {}
        },
        {
          "id": "2016-04-11T00:00:00.000+0000",
          "name": "2016-04-11 00:00:00.0",
          "value": 1447,
          "data": {}
        },
        {
          "id": "2016-03-21T00:00:00.000+0000",
          "name": "2016-03-21 00:00:00.0",
          "value": 2,
          "data": {}
        },
        {
          "id": "2016-03-07T00:00:00.000+0000",
          "name": "2016-03-07 00:00:00.0",
          "value": 5,
          "data": {}
        },
        {
          "id": "2015-12-28T00:00:00.000+0000",
          "name": "2015-12-28 00:00:00.0",
          "value": 0,
          "data": {}
        },
        {
          "id": "2016-02-01T00:00:00.000+0000",
          "name": "2016-02-01 00:00:00.0",
          "value": 2,
          "data": {}
        },
        {
          "id": "2016-01-18T00:00:00.000+0000",
          "name": "2016-01-18 00:00:00.0",
          "value": 4,
          "data": {}
        },
        {
          "id": "2016-02-22T00:00:00.000+0000",
          "name": "2016-02-22 00:00:00.0",
          "value": 2,
          "data": {}
        },
        {
          "id": "2016-03-28T00:00:00.000+0000",
          "name": "2016-03-28 00:00:00.0",
          "value": 398,
          "data": {}
        },
        {
          "id": "2016-05-02T00:00:00.000+0000",
          "name": "2016-05-02 00:00:00.0",
          "value": 911,
          "data": {}
        },
        {
          "id": "2016-01-04T00:00:00.000+0000",
          "name": "2016-01-04 00:00:00.0",
          "value": 0,
          "data": {}
        },
        {
          "id": "2016-04-18T00:00:00.000+0000",
          "name": "2016-04-18 00:00:00.0",
          "value": 1449,
          "data": {}
        },
        {
          "id": "2016-02-08T00:00:00.000+0000",
          "name": "2016-02-08 00:00:00.0",
          "value": 3,
          "data": {}
        },
        {
          "id": "2016-03-14T00:00:00.000+0000",
          "name": "2016-03-14 00:00:00.0",
          "value": 10,
          "data": {}
        }
      ]
    }
  ]
}