gtrends: 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(query, geo, cat, gprop, session, ...)
# S3 method for default
gtrends(query = "", geo = "", cat = "0", gprop = c("",
  "news", "images", "froogle", "youtube"), session, res = c(NA, "1h", "4h",
  "1d", "7d"), start_date = as.Date("2004-01-01"),
  end_date = as.Date(Sys.time()), ...)
# S3 method for gtrends
summary(object, ...)
# S3 method for gtrends
plot(x, type = c("trend", "geo"), which = 5, ind = 1L,
  ...)
# S3 method for gtrends
as.zoo(x, ...)

Arguments

query

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")).

cat

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

gprop

A character string defining the Google product for which the trend query if preformed. Valid options are “” (empty string - web search), “news”, “images”, “froogle” and “youtube”. Default is “”.

session

A valid session which can be created via gconnect. Users can either supply an explicit handle, or rely on the helper function .getDefaultConnection() to retrieve the current connection handle.

...

Additional parameters passed on in method dispatch.

res

Resolution of the trending data to be returned. One of c("1h", "4h", "1d", "7d"). If res is provided, then start_date and end_date parameters are ignored. See Query resolution for more information.

start_date

Starting date using yyyy-mm-dd format. Must be greater than 2004-01-01.

end_date

Starting date using yyyy-mm-dd format. Must be before than current date.

object

A gtrends object

type

A character variable selecting the type of plot; permissible values are ‘trends’ (which is also the default), ‘geo’.

which

Block number containing the geographical data to plot.

ind

A integer selecting the result set in case of multiple search terms.

Value

An object of class ‘gtrends’ which is list with six elements containing the results.

When type is equal to ‘trends’, the resulting ggplot2 object is returned silently.

Query resolution

By default, Google returns weekly information when the requested data spans a period greater than three months. It is also possible to obtain daily and hourly information. However, these are only available for a certain period prior to the current date.

For instance, 1h, 7h, 1d and 7d denote trends data for the last 1 hour, last four hours, last day and last seven day respectively. Using one of the above res will return the corresponding hourly data.

Note that data requested for a beriod between one and three months will be returned daily. For a period greater than three months, data will be always returned weekly.

Examples

Run this code

# NOT RUN {
session <- gconnect("usr@gmail.com", "psw")

gtrends(c("NHL", "NBA", "MLB", "MLS"))

gtrends("NHL", geo = c("CA", "US"))

# Search only for the sport category.
gtrends("NHL", geo = c("CA", "US"), cat = "0-20")

# Trends between 2015-01-01 and 2015-03-01 in Sweeden. Will be daily data.
gtrends("NHL", geo = c("SE"), start_date = "2015-01-01", end_date = "2015-03-01")

# Trends between 2015-01-01 and 2015-04-01 in Sweeden. Will be weekly data.
gtrends("NHL", geo = c("SE"), start_date = "2015-01-01", end_date = "2015-04-01")

# Last 4 hours trends
gtrends("NHL", geo = c("CA"), res = "4h")

# Last 7 days trends
gtrends("NHL", geo = c("CA"), res = "7d")

# Using categories

data("categories")
categories[grepl("music", categories$name, ignore.case = TRUE), ]

gtrends(cat = "1087")
# }
# NOT RUN {
data("sport_trend")
plot(sport_trend)
# }