gtrendshealth (version 1.0.0)

get_health_trends: Query the Google Trends for Health API

Description

For health research only, fetches a graph of search volumes per time within a set of restrictions. Each term will result in a timeline of search over time. Note the data is sampled and Google can't guarantee the accuracy of the numbers. This service is closed to a subset of Health researchers. The quota provision is individually maintained by the Trends team.

Usage

get_health_trends(
  terms,
  resolution,
  start,
  end,
  country = NULL,
  region = NULL,
  dma = NULL,
  key = get_gt_api_key(),
  wait = TRUE
)

Value

A data.frame with one row per term and period, with the probability of the term being included in a search, for the specified geographic restriction and dates range. The probabilities are provided by the API as values multiplied by 1e7.

Arguments

terms

Required. Search terms the user wishes to explore. Up to 30 queries can be sent. Term format can be either a query or entity (e.g. /m/0d2p9p) and can include ORs using '+' sign. Example: "/m/0d2p9p + /m/0nd4ffr + awesomeness" will return a combined timeline of the three terms (which obviously differs from "/m/0d2p9p, /m/0nd4ffr, awesomeness" that returns 3 different timelines.)

resolution

One of day, week, month, or year. Week is default for the API, but required here to protect the quotas.

start

A date object representing the start of the query period. The default for the API is 2004-01-01, but a value is required here.

end

A date object representing the start of the query period. The default for the API is today, but a value is required here.

country, region, dma

Only one field of GeoRestriction should be filled. Country format is ISO-3166-2 (2-letters), e.g. US. Region format is ISO-3166-2 (4-letters), e.g. US-NY (see more examples here: en.wikipedia.org/wiki/ISO_3166-2:US). DMA is nielsen dma id, e.g. 501 (support.google.com/richmedia/answer/2745487).

key

The API key from your Google Developer project authorized for Google Trends for Health API use, as a character. Defaults to using the API key set up for this package, if any. A key can be acquired by requesting access at https://support.google.com/trends/contact/trends_api and following the setup instructions.

wait

Wait before submitting the query, to protect the API quotas. The Google Trends for Gealth API is limited to 2 queries per second.

Examples

if(Sys.getenv("GOOGLE_TRENDS_FOR_HEALTH_API_KEY")==""){
  # Set up your API if not installed
  set_gt_api_key("")
}

# run this example if you have set up a valid API key
tryCatch({
  # Query the Google Trends for Health service
  monthly_trends <- get_health_trends(
    terms = "fever",
    resolution = "month",
    start = as.Date("2024-01-01"),
    end = as.Date("2024-12-31"),
    country = "US"
  )

  # set a date for each monthly observation
  # using the 15th of each month for the day
  monthly_trends$date <- as.Date(
    strptime(
      paste("15", monthly_trends$period),
       format = "%d %b %Y"
    )
  )

  print(monthly_trends)

  # Query the Google Trends for Health service
  daily_trends <- get_health_trends(
    terms = "fever",
    resolution = "day",
    start = as.Date("2024-01-01"),
    end = as.Date("2024-12-31"),
    country = "US"
  )

  head(daily_trends)

  # plot the time series
  plot(
    daily_trends$date, daily_trends$value, type = "l", col = "blue",
    xlab = "Date",
    ylab = "Value",
    main = "Daily and Monthly Trends for Fever"
  )
  lines(monthly_trends$date, monthly_trends$value, col = "red", lwd = 2)
  legend("topright", legend = c("Daily Trends", "Monthly Trends"),
    col = c("blue", "red"), lty = 1, lwd = c(1, 2))
}, error = function(e) cat("\nYou need to set up a valid API key")
)