Type: Package
Title: Perform and Display Google Trends Queries
Version: 1.5.1
Description: An interface for retrieving and displaying the information returned online by Google Trends is provided. Trends (number of hits) over the time as well as geographic representation of the results can be displayed.
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
BugReports: https://github.com/PMassicotte/gtrendsR/issues
URL: https://github.com/PMassicotte/gtrendsR
Depends: R (≥ 3.5.0)
LazyData: yes
Imports: ggplot2, jsonlite, anytime, curl
RoxygenNote: 7.2.0
Suggests: knitr, rmarkdown, tinytest
Encoding: UTF-8
NeedsCompilation: no
Packaged: 2022-05-23 16:15:00 UTC; filoche
Author: Philippe Massicotte [aut, cre], Dirk Eddelbuettel [aut]
Maintainer: Philippe Massicotte <pmassicotte@hotmail.com>
Repository: CRAN
Date/Publication: 2022-05-23 16:40:02 UTC

Google Trends categories.

Description

Usage

data("categories")

Format

A data frame with 1426 rows and 2 variables

Word countries ISO code.

Description

Usage

data("countries")

Format

A data frame with 117293 rows and 3 variables

References

https://www.unece.org/cefact/codesfortrade/codes_index.html

Google Trends Query

Description

The gtrends default method performs a Google Trends query for the ‘query’ argument and session ‘session’. Optional arguments for geolocation and category can also be supplied.

Usage

gtrends(
  keyword = NA,
  geo = "",
  time = "today+5-y",
  gprop = c("web", "news", "images", "froogle", "youtube"),
  category = 0,
  hl = "en-US",
  compared_breakdown = FALSE,
  low_search_volume = FALSE,
  cookie_url = "http://trends.google.com/Cookies/NID",
  tz = 0,
  onlyInterest = FALSE
)

Arguments

keyword

A character vector with the actual Google Trends query keywords. Multiple keywords are possible using gtrends(c("NHL", "NBA", "MLB", "MLS")).

geo

A character vector denoting geographic regions for the query, default to “all” for global queries. Multiple regions are possible using gtrends("NHL", c("CA", "US")).

time

A string specifying the time span of the query. Possible values are:

"now 1-H"

Last hour

"now 4-H"

Last four hours

"now 1-d"

Last day

"now 7-d"

Last seven days

"today 1-m"

Past 30 days

"today 3-m"

Past 90 days

"today 12-m"

Past 12 months

"today+5-y"

Last five years (default)

"all"

Since the beginning of Google Trends (2004)

"Y-m-d Y-m-d"

Time span between two dates (ex.: "2010-01-01 2010-04-03")

gprop

A character string defining the Google product for which the trend query if preformed. Valid options are:

  • "web" (default)

  • "news"

  • "images"

  • "froogle"

  • "youtube"

category

A character denoting the category, defaults to “0”.

hl

A string specifying the ISO language code (ex.: “en-US” or “fr”). Default is “en-US”. Note that this is only influencing the data returned by related topics.

compared_breakdown

Logical. Should compare breakdown the results by city and subregion? Can only be used if one 'geo' is used conjointly with more than one keyword. If 'TRUE', then the relative hits across the keywords will be returned. 'FALSE' by default.

low_search_volume

Logical. Should include low search volume regions?

cookie_url

A string specifying the URL from which to obtain cookies. Default should work in general; should only be changed by advanced users.

tz

A number specifying the minutes the returned dates should be offset to UTC. Note the parameter 'time' above is specified in UTC. E.g. choosing "time=2018-01-01T01 2018-01-01T03" and "tz=-120" will yield data between 2018-01-01T03 and 2018-01-01T05, i.e. data specified to be in UTC+2.

onlyInterest

If you only want the interest over time set it to TRUE.

Value

An object of class ‘gtrends’ (basically a list of data frames).

Categories

The package includes a complete list of categories that can be used to narrow requests. These can be accessed using data("categories").

Related topics

Note that *related topics* are not retrieved when more than one keyword is provided due to Google restriction.

Examples

## Not run: 

head(gtrends("NHL")$interest_over_time)
head(gtrends("NHL")$related_topics)
head(gtrends("NHL")$related_queries)

head(gtrends(c("NHL", "NFL"))$interest_over_time)

head(gtrends(c("NHL", "NFL"), geo = c("CA", "US"))$interest_over_time)

## Interest by city

gtrends(keyword = "obama", geo = "US-AL-630")

## Sport category (20)
data(categories)
categories[grepl("^Sport", categories$name), ]
gtrends(c("NHL", "NFL"), geo = c("CA", "US"), category = 20)
gtrends(geo = c("CA"), category = 20)

## Playing with time format

gtrends(c("NHL", "NFL"), time = "now 1-H") # last hour
gtrends(c("NHL", "NFL"), time = "now 4-H") # last four hours
gtrends(c("NHL", "NFL"), time = "now 1-d") # last day
gtrends(c("NHL", "NFL"), time = "today 1-m") # last 30 days
gtrends(c("NHL", "NFL"), time = "today 3-m") # last 90 days
gtrends(c("NHL", "NFL"), time = "today 12-m") # last 12 months
gtrends(c("NHL", "NFL"), time = "today+5-y") # last five years (default)
gtrends(c("NHL", "NFL"), time = "all") # since 2004

## Custom date format

gtrends(c("NHL", "NFL"), time = "2010-01-01 2010-04-03")

## Search from various Google's services

head(gtrends(c("NHL", "NFL"), gprop = "news")$interest_over_time)
head(gtrends(c("NHL", "NFL"), gprop = "youtube")$interest_over_time)

## Language settings

head(gtrends("NHL", hl = "en")$related_topics)
head(gtrends("NHL", hl = "fr")$related_topics)

## Compared breakdown
head(gtrends(keyword = c("nhl", "nba"), geo = "CA", compared_breakdown = FALSE)$interest_by_region)
head(gtrends(keyword = c("nhl", "nba"), geo = "CA", compared_breakdown = TRUE)$interest_by_region)

## End(Not run)

Plot Google Trends interest over time

Description

Plot Google Trends interest over time

Usage

## S3 method for class 'gtrends'
plot(x, ...)

Arguments

x

A gtrends object.

...

Additional parameters passed on in method dispatch. Currently not used.

Value

A ggplot2 object is returned silently.

Examples

## Not run: 
res <- gtrends("nhl", geo = c("CA", "US"))
plot(res)

## End(Not run)

If gtrends should be used behind a proxy, especially with NTLM authentication mode, you need to set the proxy parameters and credentials using "setHandleParameters" function

Description

If gtrends should be used behind a proxy, especially with NTLM authentication mode, you need to set the proxy parameters and credentials using "setHandleParameters" function

Usage

setHandleParameters(
  user = NULL,
  password = NULL,
  domain = NULL,
  proxyhost = NULL,
  proxyport = 8080,
  proxyauth = 15,
  extra_curl_opts = list()
)

Arguments

user

A string specifying your username

password

A string specifying your password

domain

A string specifying the authentication domain

proxyhost

A string specifying the Proxy host DNS or IP address

proxyport

A numeric specifying the Proxy Port : 8080 (default)

proxyauth

A numeric specifying the Proxy Authentication Method : 0 for NONE 1 for BASIC 2 for DIGEST 4 for NEGOTIATE 8 for NTLM 15 for ANY (default)

extra_curl_opts

A list of additional named options to pass into curl::handle_setopt(), e.g. list(timeout=60)

Examples

## Not run: 
library(gtrendsR)

setHandleParameters(
  user = "xxxx",
  password = "*******",
  domain = "mydomain",
  proxyhost = "10.111.124.113"
)

res <- gtrends(c("nhl", "nba"), geo = c("CA", "US"))

# include additional curl options
setHandleParameters(
  user = "xxxx",
  password = "*******",
  domain = "mydomain",
  proxyhost = "10.111.124.113",
  extra_curl_opts = list(timeout = 60)
)

## End(Not run)