Learn R Programming

⚠️There's a newer version (2.0.0) of this package.Take me there.

rtweet

R client for accessing Twitter’s REST and stream APIs. Check out the rtweet package documentation website.

Package Functionality

There are several R packages for interacting with Twitter’s APIs. See how {rtweet} compares to these others in the chart below.

TaskrtweettwitteRstreamRRTwitterAPI
Available on CRAN
Updated since 2016
Non-‘developer’ access
Extended tweets (280 chars)
Parses JSON data
Converts to data frames
Automated pagination
Search tweets
Search users
Stream sample
Stream keywords
Stream users
Get friends
Get timelines
Get mentions
Get favorites
Get trends
Get list members
Get list memberships
Get list statuses
Get list subscribers
Get list subscriptions
Get list users
Lookup collections
Lookup friendships
Lookup statuses
Lookup users
Get retweeters
Get retweets
Post tweets
Post favorite
Post follow
Post messsage
Post mute
Premium 30 day
Premium full archive
Run package tests

Responsible use

{{rtweet}} should be used in strict accordance with Twitter’s developer terms.

Installation

To get the current released version from CRAN:

## install rtweet from CRAN
install.packages("rtweet")

## load rtweet package
library(rtweet)

To get the current development version from Github:

## install remotes package if it's not already
if (!requireNamespace("remotes", quietly = TRUE)) {
  install.packages("remotes")
}

## install dev version of rtweet from github
remotes::install_github("ropensci/rtweet")

## load rtweet package
library(rtweet)

Usage

All you need is a Twitter account (user name and password) and you can be up in running in minutes!

Simply send a request to Twitter’s API (with a function like search_tweets(), get_timeline(), get_followers(), get_favorites(), etc.) during an interactive session of R, authorize the embedded rstats2twitter app (approve the browser popup), and your token will be created and saved/stored (for future sessions) for you!

API authorization

All users must be authorized to interact with Twitter’s APIs. To become authorized, simply use a function like search_tweets(), get_timeline(), get_followers(), or get_favorites() in an interactive session an authorize via web browser popup on behalf of your Twitter account!

It is no longer necessary to obtain a developer account and create your own Twitter application to use Twitter’s API. You may still choose to do this (gives you more stability and permissions; see the table at the bottom of this section), but {rtweet} should work out of the box assuming (a) you are working in an interactive/live session of R and (b) you have installed the {httpuv} package.

  • If you still want to apply for a developer account and create your own application, see the auth vignette (or the API authorization section below) for additional instructions: https://rtweet.info/articles/auth.html.
Taskrstats2twitteruser-app
Work interactively
Search/lookup tweets/users
Get friends/followers
Get timelines/favorites
Get lists/collections
Post tweets
Run package tests
Use Bearer token
Read/Write Direct Messages

Vignettes

Obtaining and using Twitter API tokens

## quick overview of rtweet functions
vignette("auth", package = "rtweet")

Quick overview of rtweet package

## quick overview of rtweet functions
vignette("intro", package = "rtweet")

Live streaming tweets data

## working with the stream
vignette("stream", package = "rtweet")

Troubleshooting common rtweet problems

## working with the stream
vignette("FAQ", package = "rtweet")

Package features

Search tweets

Search for up to 18,000 (non-retweeted) tweets containing the rstats hashtag.

## search for 18000 tweets using the rstats hashtag
rt <- search_tweets(
  "#rstats", n = 18000, include_rts = FALSE
)

Quickly visualize frequency of tweets over time using ts_plot().

## plot time series of tweets
rt %>%
  ts_plot("3 hours") +
  ggplot2::theme_minimal() +
  ggplot2::theme(plot.title = ggplot2::element_text(face = "bold")) +
  ggplot2::labs(
    x = NULL, y = NULL,
    title = "Frequency of #rstats Twitter statuses from past 9 days",
    subtitle = "Twitter status (tweet) counts aggregated using three-hour intervals",
    caption = "\nSource: Data collected from Twitter's REST API via rtweet"
  )

Twitter rate limits cap the number of search results returned to 18,000 every 15 minutes. To request more than that, simply set retryonratelimit = TRUE and rtweet will wait for rate limit resets for you.

## search for 250,000 tweets containing the word data
rt <- search_tweets(
  "data", n = 250000, retryonratelimit = TRUE
)

Search by geo-location—for example, find 10,000 tweets in the English language sent from the United States. Note: lookup_coords() requires users have a Google API key

## search for 10,000 tweets sent from the US
rt <- search_tweets(
  "lang:en", geocode = lookup_coords("usa"), n = 10000
)

## create lat/lng variables using all available tweet and profile geo-location data
rt <- lat_lng(rt)

## plot state boundaries
par(mar = c(0, 0, 0, 0))
maps::map("state", lwd = .25)

## plot lat and lng points onto state map
with(rt, points(lng, lat, pch = 20, cex = .75, col = rgb(0, .3, .7, .75)))

Stream tweets

Randomly sample (approximately 1%) from the live stream of all tweets.

## random sample for 30 seconds (default)
rt <- stream_tweets("")

Stream all geo enabled tweets from London for 60 seconds.

## stream tweets from london for 60 seconds
rt <- stream_tweets(lookup_coords("london, uk"), timeout = 60)

Stream all tweets mentioning realDonaldTrump or Trump for a week.

## stream london tweets for a week (60 secs x 60 mins * 24 hours *  7 days)
stream_tweets(
  "realdonaldtrump,trump",
  timeout = 60 * 60 * 24 * 7,
  file_name = "tweetsabouttrump.json",
  parse = FALSE
)

## read in the data as a tidy tbl data frame
djt <- parse_stream("tweetsabouttrump.json")

Get friends

Retrieve a list of all the accounts a user follows.

## get user IDs of accounts followed by CNN
cnn_fds <- get_friends("cnn")

## lookup data on those accounts
cnn_fds_data <- lookup_users(cnn_fds$user_id)
Get followers

Retrieve a list of the accounts following a user.

## get user IDs of accounts following CNN
cnn_flw <- get_followers("cnn", n = 75000)

## lookup data on those accounts
cnn_flw_data <- lookup_users(cnn_flw$user_id)

Or if you really want ALL of their followers:

## how many total follows does cnn have?
cnn <- lookup_users("cnn")

## get them all (this would take a little over 5 days)
cnn_flw <- get_followers(
  "cnn", n = cnn$followers_count, retryonratelimit = TRUE
)

Get timelines

Get the most recent 3,200 tweets from cnn, BBCWorld, and foxnews.

## get user IDs of accounts followed by CNN
tmls <- get_timelines(c("cnn", "BBCWorld", "foxnews"), n = 3200)

## plot the frequency of tweets for each user over time
tmls %>%
  dplyr::filter(created_at > "2017-10-29") %>%
  dplyr::group_by(screen_name) %>%
  ts_plot("days", trim = 1L) +
  ggplot2::geom_point() +
  ggplot2::theme_minimal() +
  ggplot2::theme(
    legend.title = ggplot2::element_blank(),
    legend.position = "bottom",
    plot.title = ggplot2::element_text(face = "bold")) +
  ggplot2::labs(
    x = NULL, y = NULL,
    title = "Frequency of Twitter statuses posted by news organization",
    subtitle = "Twitter status (tweet) counts aggregated by day from October/November 2017",
    caption = "\nSource: Data collected from Twitter's REST API via rtweet"
  )

Get favorites

Get the 3,000 most recently favorited statuses by JK Rowling.

jkr <- get_favorites("jk_rowling", n = 3000)

Search users

Search for 1,000 users with the rstats hashtag in their profile bios.

## search for users with #rstats in their profiles
usrs <- search_users("#rstats", n = 1000)

Get trends

Discover what’s currently trending in San Francisco.

sf <- get_trends("san francisco")

Post actions

  • Posting (tweeting from R console) or reading direct messages require additional permissions
  • If you’d like to post Twitter statuses, follow or unfollow accounts, and/or read your direct messages, you’ll need to create your own Twitter app
  • To create your own Twitter app, follow the instructions in the authorization vignette on obtaining and using access tokens

Contact

Communicating with Twitter’s APIs relies on an internet connection, which can sometimes be inconsistent. With that said, if you encounter an obvious bug for which there is not already an active issue, please create a new issue with all code used (preferably a reproducible example) on Github.

Copy Link

Version

Install

install.packages('rtweet')

Monthly Downloads

2,782

Version

0.7.0

License

MIT + file LICENSE

Last Published

January 8th, 2020

Functions in rtweet (0.7.0)

get_timeline

Get one or more user timelines (tweets posted by target user(s)).
get_mentions

Get mentions for the authenticating user.
get_favorites

Get tweets data for statuses favorited by one or more target users.
get_my_timeline

Get your timeline
get_friends

Get user IDs of accounts followed by target user(s).
lists_subscriptions

Get list subscriptions of a given user.
lists_subscribers

Get subscribers of a specified list.
get_followers

Get user IDs for accounts following target user.
get_tokens

Fetching Twitter authorization token(s).
lists_users

Get all lists a specified user subscribes to, including their own.
lists_members

Get Twitter list members (users on a given list).
lists_statuses

Get a timeline of tweets authored by members of a specified list.
next_cursor

next_cursor/previous_cursor/max_id
post_list

Manage Twitter lists
lookup_collections

Get collections by user or status id.
parse_stream

Converts Twitter stream data (JSON file) into parsed data frame.
get_trends

Get Twitter trends data.
invalidate_bearer

Invalidate bearer token
langs

Language codes recognized by Twitter data.
my_friendships

Lookup friendship information between users.
lat_lng

Adds single-point latitude and longitude variables to tweets data.
lookup_statuses

Get tweets data for given statuses (status IDs).
network_data

Network data
post_friendship

Updates friendship notifications and retweet abilities.
round_time

A generic function for rounding date and time values
post_follow

Follows target twitter user.
post_tweet

Posts status update to user's Twitter account
stopwordslangs

Twitter stop words in multiple languages data.
rtweet-package

rtweet: Collecting Twitter data
lookup_coords

Get coordinates of specified location.
get_retweets

Get the most recent retweets of a specific Twitter status
get_retweeters

Get user IDs of users who retweeted a given status.
stream_tweets

Collect a live stream of Twitter data.
ts_data

Converts tweets data into time series-like data object.
rate_limit

Get rate limit data for given Twitter access tokens.
lookup_users

Get Twitter users data for given users (user IDs or screen names).
read_twitter_csv

Read comma separated value Twitter data.
reexports

Objects exported from other packages
plain_tweets

Clean up character vector (tweets) to more of a plain text.
lookup_friendships

Lookup friendship information between two specified users.
ts_plot

Plots tweets data as a time series-like data object.
post_favorite

Favorites target status id.
write_as_csv

Save Twitter data as a comma separated value file.
suggested_slugs

Get user [account] suggestions for authenticating user
post_message

Posts direct message from user's Twitter account
tweet_shot

Capture an image of a tweet/thread
trends_available

Available Twitter trends along with associated WOEID.
search_30day

Search last 30day (PREMIUM)
search_fullarchive

Search fullarchive (PREMIUM)
search_users

Get users data on accounts identified via search query.
users_data

Extracts users data from tweets data object.
tweets_with_users

Parsing data into tweets/users data tibbles
search_tweets

Get tweets data on statuses identified via search query.
tweets_data

Extracts tweets data from users data object.
create_token

Creating Twitter authorization token(s).
direct_messages

Get direct messages sent to and received by the authenticating user from the past 30 days
get_collections

Get collections by user or status id.
as_screenname

Coerces user identifier(s) to be evaluated as a screen name(s).
bearer_token

Bearer token
direct_messages_received

(DEPRECATED) Get the most recent direct messages sent to the authenticating user.
do_call_rbind

Binds list of data frames while preserving attribute (tweets or users) data.
emojis

Emojis codes and descriptions data.
flatten

flatten/unflatten data frame