gtrendsR (version 1.5.1)

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(
  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)
# }