ngrams {storywranglr}

Explore Twitter trends with the Storywrangler ngrams API

Description

Storywrangler's ngrams API lets you search a large historical database of Twitter data for daily usage statistics about strings of one, two, and three words (1-grams, 2-grams, and 3-grams respectively).

This function returns daily historical usage statistics for a given query over data set's entire time range.

For more details about Storywrangler, please see:

• API documentation: https://github.com/janeadams/storywrangler

• Academic paper describing uses: https://advances.sciencemag.org/content/7/29/eabe6534.full

Usage

ngrams(
  query,
  metric = c("rank", "freq"),
  language = "en",
  rt = c(FALSE, TRUE),
  fill_dates = FALSE
)

Arguments

query

Character string with the n-gram(s) to query. One, two, or three words separated by spaces will run query that string as a 1-gram, 2-gram, or 3-gram respectively. More than three space-separated words will be treated as separate queries for individual 1-grams.

metric

The measure of lexical fame to return: accepts values rank (default) and freq. Note: API returns both by default.

language

Two-letter code for the language to search. Defaults to en.

rt

Boolean for whether to include retweets.

fill_dates

Boolean, defaults to FALSE. The Storywrangler ngrams API only returns rows for dates when it detected any ngram usage. By default, this function passes along that data. If the parameter fill_dates is set to TRUE, this function adds rows with NA values for each day between the earliest and latest dates in the response. Note that this is closer to Storywrangler's behaviour if you download ngram statistics from the web interface.

Value

A tibble with the API query and response. If the API returns no data, this function returns a 0-row tibble.

Examples

## Not run: 
# Query a simple 1-gram about the populatity of potatoes
result <- ngrams("potatoes")

# Query a 2-gram about the popularity of potato chips
result <- ngrams("potato chips")

# Query *four* 1-grams related to potatoes
# Note! If there are more than 3 words, they are all treated as 1-grams
result <- ngrams("potato potahto spud taters")

## End(Not run)