search_tweets: Get tweets data on statuses identified via search query.

Description

Returns Twitter statuses matching a user provided search query.

search_tweets2 Passes all arguments to search_tweets. Returns data from one OR MORE search queries.

Usage

search_tweets(
  q,
  n = 100,
  type = c("mixed", "recent", "popular"),
  include_rts = TRUE,
  geocode = NULL,
  since_id = NULL,
  max_id = NULL,
  parse = TRUE,
  token = NULL,
  retryonratelimit = NULL,
  verbose = TRUE,
  ...
)
search_tweets2(...)

Value

List object with tweets and users each returned as a data frame.

A tbl data frame with additional "query" column.

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" 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\"".

Some other useful query tips:

Exclude retweets via "-filter:retweets"
Exclude quotes via "-filter:quote"
Exclude replies via "-filter:replies"
Filter (return only) verified via "filter:verified"
Exclude verified via "-filter:verified"
Get everything (firehose for free) via "-filter:verified OR filter:verified"
Filter (return only) tweets with links to news articles via "filter:news"
Filter (return only) tweets with media "filter:media"

n

Desired number of results to return. Results are downloaded in pages when n is large; the default value will download a single page. Set n = Inf to download as many results as possible.

The Twitter API rate limits the number of requests you can perform in each 15 minute period. The easiest way to download more than that is to use retryonratelimit = TRUE.

You are not guaranteed to get exactly n results back. You will get fewer results when tweets have been deleted or if you hit a rate limit. You will get more results if you ask for a number of tweets that's not a multiple of page size, e.g. if you request n = 150 and the page size is 200, you'll get 200 results back.

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".

since_id

Supply a vector of ids or a data frame of previous results to find tweets newer than since_id.

max_id

Supply a vector of ids or a data frame of previous results to find tweets older than max_id.

parse

If TRUE, the default, returns a tidy data frame. Use FALSE to return the "raw" list corresponding to the JSON returned from the Twitter API.

token

Use this to override authentication for a single API call. In many cases you are better off changing the default for all calls. See auth_as() for details.

retryonratelimit

If TRUE, and a rate limit is exhausted, will wait until it refreshes. Most Twitter rate limits refresh every 15 minutes. If FALSE, and the rate limit is exceeded, the function will terminate early with a warning; you'll still get back all results received up to that point. The default value, NULL, consults the option rtweet.retryonratelimit so that you can globally set it to TRUE, if desired.

If you expect a query to take hours or days to perform, you should not rely solely on retryonratelimit because it does not handle other common failure modes like temporarily losing your internet connection.

verbose

Show progress bars and other messages indicating current progress?

...

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

Twitter API documentation recommends limiting searches to 10 keywords and operators. Complex queries may also produce API errors preventing recovery of information related to the query. It should also be noted Twitter's search API does not consist of an index of all Tweets. At the time of searching, the search API index includes between only 6-9 days of Tweets.

References