## Basic charts Creating a chart out of your Mentions. ### 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}` 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: | 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 | | startDate | The beginning of the date range that contains the Mentions | "YYYY-MM-DD'T'hh:mm:ss:xx.xx+xxxx" | | endDate | The end of the date range that contains the Mentions. | "YYYY-MM-DD'T'hh:mm:ss:xx.xx+xxxx" | ### 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): ```bash curl -X GET 'https://api.brandwatch.com/projects/397263282/data/volume/sentiment/days?queryId=9226732&startDate=2016-05-01&endDate=2016-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: ```bash 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": {} } ] } ] } ```