get_health_trends: Query the Google Trends for Health API

In gtrendshealth: Query the 'Google Trends for Health' API

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
)

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.

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.

Examples

if(Sys.getenv("GOOGLE_TRENDS_FOR_HEALTH_API_KEY")==""){
  # Set up your API if not installed
  set_gt_api_key("<your-valid-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")
)

gtrendshealth documentation built on June 17, 2025, 9:12 a.m.