-
Notifications
You must be signed in to change notification settings - Fork 1
/
README.Rmd
146 lines (97 loc) · 4.99 KB
/
README.Rmd
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
---
output: github_document
---
<!-- README.md is generated from README.Rmd. Please edit that file -->
```{r, echo = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>",
fig.path = "README-"
)
```
# brandwatchR
[](https://cran.r-project.org/package=brandwatchR)
An API wrapper package for the [Brandwatch API](https://developers.brandwatch.com/docs/).
If you're like me and you just want to get your hands on lots of lovely mention data, you do that by:
- Authenticating with `bwr_auth()`
- Working out the project id you need with `bwr_projects_get()`
- Working out the id of the query you want results for with `bwr_queries_get()`.
From here, you can retrieve mentions data using `bwr_get_mentions()`, which takes the project ID and query ID as arguments.
## Install
```r
devtools::install_github("Phippsy/brandwatchR")
```
or install from CRAN, version 0.3.0
```{r message = FALSE, warning = FALSE}
install.packages('brandwatchR')
```
## Authenticate
Only username and password are mandatory.
You can optionally specify `refresh = TRUE` to force the function to obtain a new token from the API. Otherwise it will read a cached local file if available.
You can also optionally specify `cache = FALSE` if you prefer not to have your token cached locally. In this case, your token will be stored in a local environment variable and available for the current R session only.
```r
bwr_auth(un = "[email protected]",
pw = "your_password",
refresh = TRUE,
cache = TRUE)
```
## Get project info
```r
my_projects <- bwr_projects_get()
head(my_projects)
```
This will display a data frame of project information including project ID, description, creation date and more.
Read the [Brandwatch documentation for more info](https://developers.brandwatch.com/docs/retrieving-projects)
## Get queries for a project
Once you have a project ID, you can find out all the available queries in your environment. Do this using the `bwr_query_get()` function:
```r
# We arbitrarily pull the first available project ID
my_project <- bwr_projects_get()$id[1]
# Get list of queries for this project ID
my_query <- bwr_query_get(project_id = my_project)
```
This will return a data frame showing you the ID, name, created date and similar metadata for the queries in the specified project.
## Get mentions for a query
Finally, the fun stuff - we can now request all mentions for a given query, using a specified date range. We achieve that using the `bwr_mentions_get()` function.
```r
my_mentions <- bwr_mentions_get(
project_id = my_project,
query_id = my_query,
date_range = c("2018-01-01", "2018-02-01"))
```
This will return a data frame containing the mentions for your specified query. Brandwatch returns a *ton* of fields in the API response, so it's likely that you'll want to slim down the resulting data frame by using `dplyr`'s `select()` function or similar.
You can find information about the mention field definitions within [Brandwatch's API documentation](https://developers.brandwatch.com/docs/mention-metadata-field-definitions).
## All functions currently available
#### Authentication
- `bwr_auth()` authenticate
#### Projects
- `bwr_projects_get()`- get a dataframe of projects
#### Queries / mentions
- `bwr_query_get()` - get a dataframe of queries for a project
- `bwr_query_check()` - check the syntax of a query
- `bwr_query_create()` - upload a new query
- `bwr_query_delete()` - delete a specified query
- `bwr_mentions_get()` - get the mentions for a specified query
- `bwr_mentions_total()` - get the total number of mentions for a specified query or query group.
- `bwr_mentions_topics()` - get the matching topics & topic metadata for a specified query or query group.
- `bwr_mentions_topsites()` - get the top authors for a specified query or query group.
- `bwr_mentions_toptweeters()` - get the top tweeters for a specified query or query group.
##### Query filters
- `bwr_filters_get()` - Get a data frame of all parameters which can be used to filter your query
- `bwr_metrics_get()` - Get a data frame of all metrics which have limited accepted values.
##### Query Groups
- `bwr_querygrp_get()` - get the query groups for a specified project
- `bwr_querygrp_delete()` - delete a specfied query group
#### Tags
- `bwr_tag_get()` - get the tags for a specified project
- `bwr_tag_create()` - create a new tag for a specified project
- `bwr_tag_delete()` - delete a tag for a specified project
#### Categories
- `bwr_cat_get()` - get the categories for a specified project
- `bwr_cat_create()` - create a new category for a specified project
#### Rules
- `bwr_rule_get()` - get a data frame of all rules available within the specified project.
- `bwr_rule_delete()` - delete a rule for a specified project and rule id
#### Charts
- `bwr_mentions_chart()` - get a data frame of chart-ready statistics for a specified query or query group.