Skip to content
🐦 R client for interacting with Twitter's [stream and REST] APIs
R
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Update and rename blank.yml to fork-testing.yml Sep 5, 2019
R Add friends and lookup_users fixes Nov 4, 2019
data spell check (woof), renamed files, and compressed pkg data Nov 1, 2017
docs Change version number Oct 21, 2019
inst Fix pandoc rendering Oct 21, 2019
man change Github links to point to ropensci Oct 21, 2019
pkgdown Add reviewers and update pkg docs Aug 26, 2019
revdep udpate docs May 16, 2019
src
tests Reply to reviewers Sep 5, 2019
tools/readme
vignettes Fix pandoc rendering Oct 21, 2019
.Rbuildignore add codemeta.json to buildignore Oct 21, 2019
.gitattributes Create .gitattributes Sep 29, 2018
.gitignore Update auth vignette and add code of conduct Sep 5, 2019
.travis.yml fedora fix failed May 16, 2019
CODE_OF_CONDUCT.md Update auth vignette and add code of conduct Sep 5, 2019
DESCRIPTION Increment version number Oct 21, 2019
LICENSE documented examples Jul 31, 2016
NAMESPACE add search_30day for premium API May 14, 2019
NEWS.md
README.Rmd Add joss paper badge Oct 24, 2019
README.md Add joss paper badge Oct 24, 2019
_pkgdown.yml ropensci links Oct 21, 2019
codecov.yml
codemeta.json Fix refs and dois in paper.bib Oct 22, 2019
cran-comments.md update CRAN comments May 16, 2019
paper.bib Fix dois Oct 22, 2019
paper.md Fix bibref in paper.md Oct 22, 2019
rtweet.Rproj ropensci links Oct 21, 2019

README.md

rtweet

Build Status CRAN status Coverage Status DOI Project Status: Active – The project has reached a stable, usable state and is being actively developed. Downloads Downloads lifecycle DOI

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.

Task rtweet twitteR streamR RTwitterAPI
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.
Task rstats2twitter user-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.

ropensci_footer

You can’t perform that action at this time.