Type: Package
Title: 'Brandwatch' API to R
Version: 0.3.0
URL: https://github.com/Phippsy/brandwatchR
BugReports: https://github.com/Phippsy/brandwatchR/issues
Description: Interact with the 'Brandwatch' API https://developers.brandwatch.com/docs. Allows you to authenticate to the API and obtain data for projects, queries, query groups tags and categories. Also allows you to directly obtain mentions and aggregate data for a specified query or query group.
License: MIT + file LICENSE
Encoding: UTF-8
LazyData: true
RoxygenNote: 6.1.0
Depends: R (≥ 3.4.0)
Imports: httr (≥ 1.3.1), jsonlite (≥ 1.5), data.table (≥ 1.10)
Suggests: testthat
NeedsCompilation: no
Packaged: 2018-08-11 06:53:55 UTC; donal
Author: Donal Phipps [aut, cre]
Maintainer: Donal Phipps <donal.phipps@gmail.com>
Repository: CRAN
Date/Publication: 2018-08-13 14:40:16 UTC

brandwatchR: A package for retrieving data from the Brandwatch API.

Description

The brandwatchR package provides families of wrapper functions for the Brandwatch API.

Authentication

Projects

Queries / mentions

Query filters

Query Groups

Tags

Categories

Authenticate with the Brandwatch API

Description

Authenticates using specified username and password. Also caches a local version of the authentication token unless otherwise specified.

Usage

bwr_auth(un = NULL, pw = NULL, refresh = FALSE, cache = TRUE)

Arguments

un

Your Brandwatch Username

pw

Your Brandwatch Password

refresh

(Boolean) Should the token be refreshed? If no, a token will be read from a locally cached file '.bw_token' if this file is available. If no token is available, or the refresh argument is TRUE, a new token will be requested and cached from the API.

cache

(Boolean) Can the token be locally cached? If TRUE, the token will be cached in the current working directory in '.bw_token'. If FALSE, the token will be not be cached locally.

Value

Invisibly returns the string containing the token returned by Brandwatch. Your environment variable 'BW_TOKEN' will be set to the value of your authentication token.

Examples

## Not run: bwr_auth(un = 'mickey@mouse.com', pw = 'itsasmallworld')

Upload a new category to Brandwatch

Description

Refer to https://developers.brandwatch.com/docs/creating-categories for more information. Unless otherwise specified, provide a single string argument.

Usage

bwr_cat_create(project_id = NULL, name = NULL, children = NULL,
  token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project ID into which you'd like to insert a category

name

The name of the category

children

A list of lists (sorry!), each list defining the key-value pairs for name (mandatory) and id (optional) of each child subcategory.

token

The authentication token, obtained using bwr_auth()

Value

Returns a list containing the JSON response from the server.

Examples

## Not run: bwr_cat_create(project_id = 12423432,
               name = 'Quick test cat',
               children = list(list(name = 'category one', id = 234234),
                 list(name = 'category 2')))
## End(Not run)

Get a data frame of available categories for a given project

Description

See the Brandwatch documentation for more information at https://developers.brandwatch.com/docs/retrieving-categories.

Usage

bwr_cat_get(project_id = NULL, token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project id you'd like to return all available categories for. Obtain a data frame of projects using bwr_get_projects()

token

The auth token for this user, which should be generated into an environment variable using bwr_auth()

Value

Returns a dataframe of categories matching the project.

Examples

## Not run: my_categories <- bwr_cat_get(project_id = 12334534)

Get a data frame of available filters for the Brandwatch API

Description

See the Brandwatch documentation for more information at https://developers.brandwatch.com/docs/available-filters

Usage

bwr_filters_get(token = Sys.getenv("BW_TOKEN"))

Arguments

token

The auth token for this user, which should be generated into an environment variable using bwr_auth()

Value

Returns a dataframe of available filters

Examples

## Not run: my_queries <- bwr_query_get(project_id = 12334534)

Get a dataframe of chart-ready data for a specified Brandwatch query or query group

Description

For more information, please refer to https://developers.brandwatch.com/docs/chart-dimensions-and-aggregates

Usage

bwr_mentions_chart(project_id = NULL, query_id = NULL,
  querygrp_id = NULL, date_range = c(Sys.Date() - 31, Sys.Date() - 1),
  aggregate = NULL, dimension1 = NULL, dimension2 = NULL,
  filters = NULL, token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project id in which the specified query is contained. Obtain a list of project IDs using bwr_get_projects().

query_id

The query ID you'd like to see tweeter data for. Note that you can only specify a query or a query group, not both.

querygrp_id

The query group ID you'd like to see total mentions for. Note that you can only specify a query or a query group, not both.

date_range

A character vector containing 2 date values in YYYY-mm-dd format. The first value is the beginning of your desired date range and the second value is the end of the date range.

aggregate

The numeric variable which you'd like to return results for (e.g. 'volume')

dimension1

The first dimension which you'd like to split your data by (e.g. 'months')

dimension2

The second dimension which you'd like to split your data by (e.g. 'countries')

filters

(Optional) A list of key-value pairs to filter the mentions query by. Use the bwr_filters_get() function to find out all available filters.

token

The authentication token, acquired using bwr_auth()

Value

Returns a data frame (including some list-columns) of the JSON results, aggregated according to your 2 dimensions.

Examples

## Not run: my_project <- bwr_projects_get()$id[1]
my_query <- bwr_query_get(project_id = my_project)$id[1]
my_mentions_chart <- bwr_mentions_chart(project_id = my_project,
                                        query_id = my_query,
                                        date_range = c('2018-01-01', '2018-02-01'),
                                        aggregate = "month",
                                        dimension1 = "sentiment",
                                        dimension2 = "volume")
## End(Not run)

Get a list of mentions for the specified query and project

Description

Returns a data frame containing any results found for the specified query ID.

Usage

bwr_mentions_get(project_id = NULL, query_id = NULL,
  date_range = c(Sys.Date() - 31, Sys.Date() - 1), order_by = NULL,
  order_direction = NULL, filters = NULL, page = NULL,
  token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

Numeric. The project id in which the specified query is contained. Obtain a list of project IDs using bwr_get_projects().

query_id

Numeric The id of the query you'd like to run. Obtain a list of queries for any specified project using bwr_get_queries().

date_range

A character vector containing 2 date values in YYYY-mm-dd format. The first value is the beginning of your desired date range and the second value is the end of the date range.

order_by

String. (Optional) The name of the metric you'd like to order your results by.

order_direction

String. Either 'asc' or 'desc', to specify ascending or descending order.

filters

(Optional) A list of key-value pairs to filter the mentions query by. Use the bwr_filters_get() function to find out all available filters.

page

Numeric, optional. The page number for which to return results. This is needed only when R needs to iterate through multiple pages of results from the Brandwatch API. It is recommended that you keep this value set as zero.

token

The authentication token, acquired using bwr_auth(). This token will be automatically obtained from the user's environment variable 'BW_TOKEN' and does not need to be provided.

Value

Returns a data frame containing all results

See Also

bwr_auth to authenticate, bwr_projects_get for a list of project IDs, bwr_query_get for all queries available in the specified project. bwr_filters_get to get a list of available filters for the filters argument.

Examples

## Not run: my_project <- bwr_projects_get()$id[1]
my_query <- bwr_query_get(project_id = my_project)$id[1]
my_mentions <- bwr_mentions_get(project_id = my_project,
                                query_id = my_query,
                                filters = list(gender = 'female', sentiment = 'neutral'),
                                order_by = 'sentiment', order_direction = 'asc',
                                date_range = c('2018-01-01', '2018-02-01'))
## End(Not run)

Get a dataframe of top author data for a specified Brandwatch query or query group

Description

Get a dataframe of top author data for a specified Brandwatch query or query group

Usage

bwr_mentions_topauthors(project_id = NULL, query_id = NULL,
  querygrp_id = NULL, date_range = c(Sys.Date() - 31, Sys.Date() - 1),
  filters = NULL, token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project id in which the specified query is contained. Obtain a list of project IDs using bwr_get_projects().

query_id

The query ID you'd like to see author data for. Note that you can only specify a query or a query group, not both.

querygrp_id

The query group ID you'd like to see total mentions for. Note that you can only specify a query or a query group, not both.

date_range

A character vector containing 2 date values in YYYY-mm-dd format. The first value is the beginning of your desired date range and the second value is the end of the date range.

filters

(Optional) A list of key-value pairs to filter the mentions query by. Use the bwr_filters_get() function to find out all available filters.

token

The authentication token, acquired using bwr_auth()

Value

Returns a data frame (including some list-columns) of the JSON results, showing information about the top authors related to your query.

Examples

## Not run: my_project <- bwr_projects_get()$id[1]
my_query <- bwr_query_get(project_id = my_project)$id[1]
my_mentions <- bwr_mentions_topauthors(project_id = my_project,
                                       query_id = my_query,
                                       date_range = c('2018-01-01', '2018-02-01'))
## End(Not run)

Get a dataframe of topic data for a specified Brandwatch query or query group

Description

Get a dataframe of topic data for a specified Brandwatch query or query group

Usage

bwr_mentions_topics(project_id = NULL, query_id = NULL,
  querygrp_id = NULL, date_range = c(Sys.Date() - 31, Sys.Date() - 1),
  order_by = NULL, limit = NULL, exclude_categories = NULL,
  exclude_tags = NULL, filters = NULL,
  token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project id in which the specified query is contained. Obtain a list of project IDs using bwr_get_projects().

query_id

The query ID you'd like to see total mentions for. Note that you can only specify a query or a query group, not both.

querygrp_id

The query group ID you'd like to see total mentions for. Note that you can only specify a query or a query group, not both.

date_range

A character vector containing 2 date values in YYYY-mm-dd format. The first value is the beginning of your desired date range and the second value is the end of the date range.

order_by

Metric by which you wish to order the topics returned. Can be either 'volume' (the number of Mentions the topic appears in) or 'burst' (the rate that the topic has emerged over time).

limit

The maximum number of topics to be returned.

exclude_categories

You have the option to exclude Categories from the topics returned (this is often done in the Brandwatch Analytics UI).

exclude_tags

The authentication token, acquired using bwr_auth()

filters

(Optional) A list of key-value pairs to filter the mentions query by. Use the bwr_filters_get() function to find out all available filters.

token

The authentication token, acquired using bwr_auth()

Value

Returns a data frame (including some list-columns) of the JSON results, showing information about topics related to your query.

Examples

## Not run: my_project <- bwr_projects_get()$id[1]
my_query <- bwr_query_get(project_id = my_project)$id[1]
my_mentions <- bwr_mentions_topics(project_id = my_project,
                                   query_id = my_query,
                                   date_range = c('2018-01-01', '2018-02-01'))
## End(Not run)

Get a dataframe of top site data for a specified Brandwatch query or query group

Description

Get a dataframe of top site data for a specified Brandwatch query or query group

Usage

bwr_mentions_topsites(project_id = NULL, query_id = NULL,
  querygrp_id = NULL, date_range = c(Sys.Date() - 31, Sys.Date() - 1),
  filters = NULL, token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project id in which the specified query is contained. Obtain a list of project IDs using bwr_get_projects().

query_id

The query ID you'd like to see total mentions for. Note that you can only specify a query or a query group, not both.

querygrp_id

The query group ID you'd like to see total mentions for. Note that you can only specify a query or a query group, not both.

date_range

A character vector containing 2 date values in YYYY-mm-dd format. The first value is the beginning of your desired date range and the second value is the end of the date range.

filters

(Optional) A list of key-value pairs to filter the mentions query by. Use the bwr_filters_get() function to find out all available filters.

token

The authentication token, acquired using bwr_auth()

Value

Returns a data frame (including some list-columns) of the JSON results, showing information about the top sites related to your query.

Examples

## Not run: my_project <- bwr_projects_get()$id[1]
my_query <- bwr_query_get(project_id = my_project)$id[1]
my_mentions <- bwr_mentions_topsites(project_id = my_project,
                                     query_id = my_query,
                                     date_range = c('2018-01-01', '2018-02-01'))
## End(Not run)

Get a dataframe of top Tweeter for a specified Brandwatch query or query group

Description

Get a dataframe of top Tweeter for a specified Brandwatch query or query group

Usage

bwr_mentions_toptweeters(project_id = NULL, query_id = NULL,
  querygrp_id = NULL, date_range = c(Sys.Date() - 31, Sys.Date() - 1),
  filters = NULL, token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project id in which the specified query is contained. Obtain a list of project IDs using bwr_get_projects().

query_id

The query ID you'd like to see tweeter data for. Note that you can only specify a query or a query group, not both.

querygrp_id

The query group ID you'd like to see total mentions for. Note that you can only specify a query or a query group, not both.

date_range

A character vector containing 2 date values in YYYY-mm-dd format. The first value is the beginning of your desired date range and the second value is the end of the date range.

filters

(Optional) A list of key-value pairs to filter the mentions query by. Use the bwr_filters_get() function to find out all available filters.

token

The authentication token, acquired using bwr_auth()

Value

Returns a data frame (including some list-columns) of the JSON results, showing information about the top tweeters related to your query.

Examples

## Not run: my_project <- bwr_projects_get()$id[1]
my_query <- bwr_query_get(project_id = my_project)$id[1]
my_mentions <- bwr_mentions_toptweeters(project_id = my_project,
                                        query_id = my_query,
                                        date_range = c('2018-01-01', '2018-02-01'))
## End(Not run)

Get the total mentions for a specified Brandwatch query or query group

Description

Get the total mentions for a specified Brandwatch query or query group

Usage

bwr_mentions_total(project_id = NULL, query_id = NULL,
  querygrp_id = NULL, filters = NULL, date_range = c(Sys.Date() - 31,
  Sys.Date() - 1), token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project id in which the specified query is contained. Obtain a list of project IDs using bwr_get_projects().

query_id

The query ID you'd like to see total mentions for. Note that you can only specify a query or a query group, not both.

querygrp_id

The query group ID you'd like to see total mentions for. Note that you can only specify a query or a query group, not both.

filters

(Optional) A list of key-value pairs to filter the mentions query by. Use the bwr_filters_get() function to find out all available filters.

date_range

A character vector containing 2 date values in YYYY-mm-dd format. The first value is the beginning of your desired date range and the second value is the end of the date range.

token

The authentication token, acquired using bwr_auth()

Value

Returns a numeric vector of length 1 with the results.

Examples

## Not run: my_project <- bwr_projects_get()$id[1]
my_query <- bwr_queries_get(project_id = my_project)$id[1]
my_mentions <- bwr_mentions_total(
project_id = my_project,
query_id = my_query,
date_range = c('2018-01-01', '2018-02-01'))
## End(Not run)

Get a data frame of possible metric values for the Brandwatch API

Description

When examining parameters which can be used to filter a metric call, some parameters have a limited set of acceptable values. You can find out the current acceptable values using this function.

Usage

bwr_metrics_get(token = Sys.getenv("BW_TOKEN"))

Arguments

token

The auth token for this user, which should be generated into an environment variable using bwr_auth()

Details

See the Brandwatch documentation for more information at https://developers.brandwatch.com/docs/available-filters

Value

Returns a dataframe of available filters

Examples

## Not run: my_queries <- bwr_metrics_get(project_id = 12334534)

Get Brandwatch project data

Description

#' Read the Brandwatch documentation for this API call at https://developers.brandwatch.com/docs/retrieving-projects

Usage

bwr_projects_get(target = NULL, token = Sys.getenv("BW_TOKEN"))

Arguments

target

(Optional) the target for your query. If not specified, results will include all available projects for the authenticated user and all available data for each project. If 'summary', results will be a more simplified list of projects and excludes richer data such as query links.

token

The Brandwatch token, which will be automatically available via environment arguments provided you run bwr_auth() prior to any other functions.

Value

Returns a data frame of project data.

Examples

## Not run: my_projects <- bwr_get_projects(target = 'summary')

Validate a Brandwatch query

Description

Validate a Brandwatch query

Usage

bwr_query_check(query = list(), token = Sys.getenv("BW_TOKEN"))

Arguments

query

A list containing named parameters: query and language.

token

The authentication token, acquired using bwr_auth()

Value

Returns a list containing any errors or issues, if found

Examples

## Not run: any_issues <- bwr_query_check(query = list(query = 'at_mentions:huey', language = 'en'))

Upload a new query to Brandwatch

Description

Refer to https://developers.brandwatch.com/docs/creating-queries for more information. Unless otherwise specified, provide a single string argument.

Usage

bwr_query_create(project_id = NULL, type = "search string",
  languageAgnostic = FALSE, samplePercent = 100, languages = "en",
  includedTerms = NULL, name = NULL, description = "My API query",
  industry = "general", token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project ID into which you'd like to insert a query

type

The type of query (e.g. 'search string')

languageAgnostic

(Boolean) Is the query language agnostic?

samplePercent

(Numeric) The sample percent for the given query

languages

Which languages to include

includedTerms

The query syntax to be included.

name

The name of the query

description

The description of the query

industry

The industry classification

token

The authentication token, obtained using bwr_auth()

Value

Returns a list containing the JSON response from the server.

Examples

## Not run: bwr_query_create(project_id = 12423432,
                 samplePercent = 50,
                 includedTerms = 'at_mentions:mickeymouse',
                 name = 'Sample API query')
## End(Not run)

Delete a specified Brandwatch query

Description

Delete a specified Brandwatch query

Usage

bwr_query_delete(project_id, query_id, token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project ID in which the target query can be found. Obtain a data frame of project IDs using bwr_projects_get().

query_id

The ID of the query which you'd like to delete. Obtain a list of query IDs using bwr_query_get().

token

The authentication token, obtained using bwr_auth()

Value

Returns a list of the JSON response.

Examples

## Not run: bwr_query_delete(project_id = 122445, query_id = 23432424)

Get a data frame of available queries for a given project

Description

See the Brandwatch documentation for more information at https://developers.brandwatch.com/docs/retrieving-queries.

Usage

bwr_query_get(project_id = NULL, type = NULL,
  token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project id you'd like to return all available queries for. Obtain a data frame of projects using bwr_get_projects()

type

(Optional) The type of query you'd like to return. If not specified, the API will return all available queries for the given project. Currently, results don't seem to be affected by the type parameter - the API appears to return full results in all cases.

token

The auth token for this user, which should be generated into an environment variable using bwr_auth()

Value

Returns a dataframe of queries matching the project.

Examples

## Not run: my_queries <- bwr_query_get(project_id = 12334534)

Delete a specified Brandwatch query group

Description

Delete a specified Brandwatch query group

Usage

bwr_querygrp_delete(project_id = NULL, group_id = NULL,
  token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project ID in which your target query group can be found.

group_id

The query group ID which you'd like to delete. Find out the list of query groups in a given project using bwr_querygrp_get().

token

The API authentication token, obtained using bwr_auth()

Value

Returns a list of the JSON response from the server.

Examples

## Not run: kill <- bwr_querygrp_delete(project_id = 234234234, group_id = 23423423)

Get a data frame of Brandwatch query groups in the specified project

Description

Get a data frame of Brandwatch query groups in the specified project

Usage

bwr_querygrp_get(project_id = NULL, token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project ID whose query groups you'd like to return

token

The authentication token, obtained using bwr_auth()

Value

Returns a data frame of the query groups for the given project, if any exist.

Examples

## Not run: groups <- bwr_querygrp_get(project_id = 21343242)

Delete a specified Brandwatch rule

Description

Delete a specified Brandwatch rule

Usage

bwr_rule_delete(project_id, rule_id, token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project ID in which the target rule can be found. Obtain a data frame of project IDs using bwr_projects_get().

rule_id

The ID of the rule which you'd like to delete. Obtain a list of rule IDs using bwr_rule_get().

token

The authentication token, obtained using bwr_auth()

Value

Returns a list of the JSON response.

Examples

## Not run: bwr_rule_delete(project_id = 122445, rule_id = 23432424)

Get a data frame of available rules for a given project

Description

See the Brandwatch documentation for more information at https://developers.brandwatch.com/docs/retrieving-rules.

Usage

bwr_rule_get(project_id = NULL, token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project id you'd like to return all available rules for. Obtain a data frame of projects using bwr_get_projects()

token

The auth token for this user, which should be generated into an environment variable using bwr_auth()

Value

Returns a dataframe of rules matching the project. Due to the structure of the API response, some of the dataframe columns are list-columns (i.e. nested dataframes).

Examples

## Not run: my_rules <- bwr_rules_get(project_id = 12334534)

Upload a new tag to Brandwatch

Description

Refer to https://developers.brandwatch.com/docs/creating-tags for more information. Unless otherwise specified, provide a single string argument.

Usage

bwr_tag_create(project_id = NULL, name = NULL,
  token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project ID into which you'd like to insert a tag

name

The name of the tag

token

The authentication token, obtained using bwr_auth()

Value

Returns a list containing the JSON response from the server.

Examples

## Not run: bwr_tag_create(project_id = 12423432, name = 'Quick test tag')

Delete a specified Brandwatch tag

Description

Delete a specified Brandwatch tag

Usage

bwr_tag_delete(project_id, tag_id, token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project ID in which the target tag can be found. Obtain a data frame of project IDs using bwr_projects_get().

tag_id

The ID of the tag which you'd like to delete. Obtain a list of tag IDs using bwr_tag_get().

token

The authentication token, obtained using bwr_auth()

Value

Returns a list of the JSON response.

Examples

## Not run: bwr_tag_delete(project_id = 122445, tag_id = 23432424)

Get a data frame of available tags for a given project

Description

See the Brandwatch documentation for more information at https://developers.brandwatch.com/docs/retrieving-tags.

Usage

bwr_tag_get(project_id = NULL, token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project id you'd like to return all available tags for. Obtain a data frame of projects using bwr_get_projects()

token

The auth token for this user, which should be generated into an environment variable using bwr_auth()

Value

Returns a dataframe of tags matching the project.

Examples

## Not run: my_tags <- bwr_tag_get(project_id = 12334534)

Get a list of workflows for the specified query and project

Description

Refer to https://developers.brandwatch.com/docs/retrieving-workflow for more information.

Usage

bwr_wf_get(project_id = NULL, token = Sys.getenv("BW_TOKEN"))

Arguments

project_id

The project id in which the specified workflow is contained. Obtain a list of project IDs using bwr_get_projects().

token

The authentication token, acquired using bwr_auth()

Value

Returns a list containing all results

Examples

## Not run: my_project <- bwr_get_projects()$id[1]
my_workflow <- bwr_wf_get(project_id = my_project)
## End(Not run)