--- agentTools: projectIndex: https://developers.brandwatch.com/llms.txt --- # Basic charts Creating a chart out of your Mentions. On this page we will show: * [General Format of a Charts Call](https://developers.brandwatch.com/docs/basic-charts#general-format) * [Required Parameters](https://developers.brandwatch.com/docs/basic-charts#required-parameters) * [Example Call - Volume of Mentions in a Query by Sentiment](https://developers.brandwatch.com/docs/basic-charts#example-call-volume-of-mentions-in-a-query-by-sentiment) * [Example Call - Weekly Share of Voice](https://developers.brandwatch.com/docs/basic-charts#example-call-weekly-share-of-voice) ## 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 the data added together on the chart. 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](https://developers.brandwatch.com/docs/chart-dimensions-and-aggregates) page of the documentation. ## Required Parameters The charts data call has the same three required parameters as the Mentions call: [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Definition", "h-2": "Accepted Values", "0-0": "`queryId` / `queryGroupId`", "0-1": "The ID of the Query or Query Group that contains the Mentions for which you'd like to see.", "0-2": "int (can be specified multiple times) \n(Learn how to retrieve your [Query ID](https://developers.brandwatch.com/docs/retrieving-queries) or [Query Group ID](https://developers.brandwatch.com/docs/retrieving-query-groups))", "1-0": "`startDate`", "1-1": "The beginning of the date range that contains the Mentions.", "1-2": "\"YYYY-MM-DD'T'hh:mm:ss.xxx+xxxx\"", "2-0": "`endDate`", "2-1": "The end of the date range that contains the Mentions.", "2-2": "\"YYYY-MM-DD'T'hh:mm:ss.xxx+xxxx\"" }, "cols": 3, "rows": 3, "align": [ "left", "left", "left" ] } [/block] **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=n` parameter, again where X is the dimension's position in the request path (either 1 or 2). This will return only the top `n` values for the dimension. ## 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 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: ```json { "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 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: ```json { "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": {} } ] } ] } ```