Facebook S4 Package for R

facebook.S4 allows users to connect to Facebook throu OAuth and get different kinds of content using the Facebook Graph API and organize it in a convenient set of S4 classes called collections. This allows to chain queries in the typical graph-oriented fashion of the Facebook API.

This project started as a fork of the Rfacebook package by Pablo Barbera, but it ended up as a complete rewrite, as I needed to better exploit the graph nature of the API and since I was a bit disappointed that the original package functions were not vectorized. Still, this package uses the fbOAuth function from Rfacebook, which is simply perfect.


Since the package is not yet available on CRAN, the fastest way to install it is pulling out the code from GitHub directly using the devtools package:


Most API requests require the use of an access token.

There are two ways of making authenticated requests with facebook.S4. One option is to generate a temporary token on the Graph API Explorer. Then just copy and paste the code into the R console and save it as a string vector to be passed as the token argument to any function or Collection constructor.While really easy, however, please note that this access token will only be valid for two hours.

It is possible to generate a ‘long-lived’ token (valid for two months) using the fbOAuth function, but the process is a bit longer. For a step-by-step tutorial, check this setup tutorial.

Package structure

There are two main kinds of elements in the package:

  • The Collections – A set of S4 classes used, as the name suggests, to collect homogeneus items from Facebook. Their name is in the form of Facebook<Type>Collection (note the capital letter). Typical examples are: FacebookPostsCollectionFacebookPagesCollection and FacebookCommentsCollection.
  • The Finders – A set of functions used to search elements on Facebook or inside a collection. They usually return simple lists, but some returns Collections, too. Typical examples are facebook.search and facebook.video.formats.

A special kind of collection called FacebookMixedCollection is used when you don’t know in advance which kind of data you’ll get from Facebook. For example, when you try to get a list of participants of a conversation, which can be users or pages.

While the set of Finders is very far to be considered as complete, the set of Collections covers already almost all the typical major items used in Facebook like posts, comments, likes, groups, albums and so on.

First use: build a Facebook application

Before using this application, you need to build a Facebook application to authenticate facebook.S4 against.

Since the procedure was covered many times, I’m not going to reinvent the wheel here. This tutorial

Chaining a request

Almost all the Collections support chaining. It means, you can pass a collection as a source parameter to another one to chain complex requests. For example, let’s say we want to get informations about who put a like on the feed for a set of pages:

You can eventually use the chain operator %>% for a more compact and elegant code:

Please note that if you don’t specify the field argument, a default set of fields is pulled.

Parent collections

As said before, you can build a collection passing a list of IDs of the same kind or from another collection.

If this is the case, two additional slots of the collections will be fed:

  • parent – which the parent of the ith element of the collection (for ex. the post a comment belongs)
  • parent.collection with the generating collection you can traverse

From the previous example, this is absolutely legit:

Watch out the memory consumption! Parent collections could be really memory consuming. Keep calm and do gc()!

Methods available for collections

MethodEffect on collectionNote
[]SubsettingFilter by index or by ID, returns a Collection of the same kind
cCombineCombine elements of two or more collections. Duplicated IDs are discarded only if the have different parents.
as.listConvert to a listReturn a list representation of a Collection
as.data.frameConvert to a data.frameReturn a data.frame representation of a Collection
lengthCounts the elementsReturn the length of a collection
summaryPrints a summaryPrints a summary view of the details of a collection


  • Please report any issues or bugs.
  • License: MIT
  • Get citation information for facebook.S4 in R doing citation(package = 'facebook.S4')
Share This