search_tweets
Percentile
Get tweets data on statuses identified via search query..
Usage
search_tweets(q, n = 100, type = "recent", include_rts = TRUE, geocode = NULL, max_id = NULL, parse = TRUE, token = NULL, retryonratelimit = FALSE, verbose = TRUE, ...)
search_tweets2(...)
Arguments
- q
Query to be searched, used to filter and select tweets to return from Twitter's REST API. Must be a character string not to exceed maximum of 500 characters. Spaces behave like boolean "AND" operator. To search for tweets containing at least one of multiple possible terms, separate each search term with spaces and "OR" (in caps). For example, the search
q = "data science"looks for tweets containing both "data" and "science" anywhere located anywhere in the tweets and in any order. When "OR" is entered between search terms,
query = "data OR science", Twitter's REST API should return any tweet that contains either "data" or "science." It is also possible to search for exact phrases using double quotes. To do this, either wrap single quotes around a search query using double quotes, e.g.,
q = '"data science"'or escape each internal double quote with a single backslash, e.g.,
q = "\"data science\"".
- n
Integer, specifying the total number of desired tweets to return. Defaults to 100. Maximum number of tweets returned from a single token is 18,000. To return more than 18,000 tweets, users are encouraged to set
retryonratelimitto TRUE. See details for more information.
- type
Character string specifying which type of search results to return from Twitter's REST API. The current default is
type = "recent", other valid types include
type = "mixed"and
type = "popular".
- include_rts
Logical, indicating whether to include retweets in search results. Retweets are classified as any tweet generated by Twitter's built-in "retweet" (recycle arrows) function. These are distinct from quotes (retweets with additional text provided from sender) or manual retweets (old school method of manually entering "RT" into the text of one's tweets).
- geocode
Geographical limiter of the template "latitude,longitude,radius" e.g.,
geocode = "37.78,-122.40,1mi".
- max_id
Character string specifying the [oldest] status id beyond which search results should resume returning. Especially useful large data returns that require multiple iterations interrupted by user time constraints. For searches exceeding 18,000 tweets, users are encouraged to take advantage of rtweet's internal automation procedures for waiting on rate limits by setting
retryonratelimitargument to TRUE. It some cases, it is possible that due to processing time and rate limits, retrieving several million tweets can take several hours or even multiple days. In these cases, it would likely be useful to leverage
retryonratelimitfor sets of tweets and
max_idto allow results to continue where previous efforts left off.
- parse
Logical, indicating whether to return parsed data.frame, if true, or nested list, if false. By default,
parse = TRUEsaves users from the wreck of time and frustration associated with disentangling the nasty nested list returned from Twitter's API. As Twitter's APIs are subject to change, this argument would be especially useful when changes to Twitter's APIs affect performance of internal parsers. Setting
parse = FALSEalso ensures the maximum amount of possible information is returned. By default, the rtweet parse process returns nearly all bits of information returned from Twitter. However, users may occasionally encounter new or omitted variables. In these rare cases, the nested list object will be the only way to access these variables.
- token
OAuth token. By default
token = NULLfetches a non-exhausted token from an environment variable. Find instructions on how to create tokens and setup an environment variable in the tokens vignette (in r, send
?tokensto console).
- retryonratelimit
Logical indicating whether to wait and retry when rate limited. This argument is only relevant if the desired return (n) exceeds the remaining limit of available requests (assuming no other searches have been conducted in the past 15 minutes, this limit is 18,000 tweets). Defaults to false. Set to TRUE to automate process of conducting big searches (i.e., n > 18000). For many search queries, esp. specific or specialized searches, there won't be more than 18,000 tweets to return. But for broad, generic, or popular topics, the total number of tweets within the REST window of time (7-10 days) can easily reach the millions.
- verbose
Logical, indicating whether or not to include output processing/retrieval messages. Defaults to TRUE. For larger searches, messages include rough estimates for time remaining between searches. It should be noted, however, that these time estimates only describe the amount of time between searches and not the total time remaining. For large searches conducted with
retryonratelimitset to TRUE, the estimated retrieval time can be estimated by dividing the number of requested tweets by 18,000 and then multiplying the quotient by 15 (token reset time, in minutes).
- ...
Further arguments passed as query parameters in request sent to Twitter's REST API. To return only English language tweets, for example, use
lang = "en". For more options see Twitter's API documentation.
Details)..
Value
List object with tweets and users each returned as a data frame.
A tbl data frame with additional "query" column.
See Also
Other tweets:
get_favorites,
get_mentions,
get_timeline,
lists_statuses,
lookup_statuses,
tweets_data,
tweets_with_users
Aliases
- search_tweets
- search_tweets2
Examples
# NOT RUN { # } # NOT RUN { ## search for 1000 tweets mentioning Hillary Clinton hrc <- search_tweets(q = "hillaryclinton", n = 1000) ## data frame where each observation (row) is a different tweet hrc ## users data also retrieved. can access it via users_data() users_data(hrc) ## search for 1000 tweets in English djt <- search_tweets(q = "realdonaldtrump", n = 1000, lang = "en") ## preview tweets data djt ## preview users data users_data(djt) ## exclude retweets rt <- search_tweets("rstats", n = 500, include_rts = FALSE) ## perform search for lots of tweets rt <- search_tweets( "trump OR president OR potus", n = 100000, retryonratelimit = TRUE ) ## plot time series of tweets frequency ts_plot(rt, by = "mins") ## make multiple independent search queries ds <- Map( "search_tweets", c("\"data science\"", "rstats OR python"), n = 1000 ) ## bind by row whilst preserving users data ds <- do_call_rbind(ds) ## preview tweets data ds ## preview users data users_data(ds) # } # NOT RUN { # } # NOT RUN { ## search using multilple queries st2 <- search_tweets2( c("\"data science\"", "rstats OR python"), n = 500 ) ## preview tweets data st2 ## preview users data users_data(st2) ## check breakdown of results by search query table(st2$query) # } # NOT RUN { # }