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
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.
# token generated here: https://developers.facebook.com/tools/explorer
token <- "XXXXXXXXXXXXXX"
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.
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: FacebookPostsCollection, FacebookPagesCollection 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
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:
# Assuming fb_token is valid
# First, we build the collection of pages. Since we're not interested in pages, we download no fields for pages
fb.pages <- FacebookPagesCollection(id = c("9thcirclegames", "linuspage", fb_token, fields = "")
# Then, we pull out the last 20 posts for each page. Again, no fields here
# When you pass another collection as source parameter, you can omit the token
# (if you want to use the same, of course)
fb.posts <- FacebookPostsCollection(fb.pages, fields = "", n = 20)
# Now, we're going to get all the likes. We want 'em all
fb.likes <- FacebookLikesCollection(fb.posts, fields = "", n = Inf)
# Finally, get the users
fb.users <- FacebookUsersCollection(fb.likes, fields = c("id", "profile_type"))
You can eventually use the chain operator
%>% for a more compact and elegant code:
# Get the comments to the posts of the pages above
FacebookPostsCollection(fields = "") %>%
FacebookCommentsCollection(fields = c("id", "from.fields(id,name)", "message", "created_time"))
Please note that if you don’t specify the field argument, a default set of fields is pulled.
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:
# This returns a character vector with "9thcirclegames", "linuspage"
Watch out the memory consumption! Parent collections could be really memory consuming. Keep calm and do
Methods available for collections
|Method||Effect on collection||Note|
|||Subsetting||Filter by index or by ID, returns a Collection of the same kind|
|c||Combine||Combine elements of two or more collections. Duplicated IDs are discarded only if the have different parents.|
|as.list||Convert to a list||Return a list representation of a Collection|
|as.data.frame||Convert to a data.frame||Return a data.frame representation of a Collection|
|length||Counts the elements||Return the length of a collection|
|summary||Prints a summary||Prints a summary view of the details of a collection|
- Please report any issues or bugs.
- License: MIT
- Get citation information for
facebook.S4in R doing
citation(package = 'facebook.S4')