Access to Facebook API via R

Description

This package provides a series of functions that allow R users to access Facebook's API to get information about users and posts, and collect public status updates that mention specific keywords.

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

See Also

fbOAuth, getUsers, getPost, searchFacebook, updateStatus, getFriends, getNetwork, getPage

Make an API request

Description

callAPI is an internal function to run an API request.

Usage

callAPI(url, token, api = NULL)

Arguments

Create OAuth token to Facebook R session

Description

fbOAuth creates a long-lived OAuth access token that enables R to make authenticated calls to the Facebook API. The token can be saved as a file in disk to be re-used in future sessions. This function relies on the httr package to create the OAuth token, and is a simplified version of one of its examples.

This function will automatically detect the API version for the token you create.

Usage

fbOAuth(app_id, app_secret, extended_permissions = FALSE,
  legacy_permissions = FALSE, scope = NULL)

Arguments

Details

There are two different ways of making authenticated requests. One is to obtain a temporary access token from https://developers.facebook.com/tools/explorer/, which can be used as argument in any of the functions in Rfacebook. An example is shown below.

However, this token has a 2-hour lifetime by default and after it expires, it needs to be renewed. The second alternative is to create an OAuth token. The process to create it is a bit more tedious. It is divided in three steps.

First, go to https://developers.facebook.com/apps, register as a developer and create a new app. You will also need a verified Facebook account. After that, click in "Show" under "App Secret" to find your 'App ID' and 'App Secret'.

Second, run the fbOAuth function with your "App ID" and "App Secret" as arguments. It will return a URL, which you will need to paste into the "Website with Facebook login" field in your App Settings on Facebook. Once you've done so, press Enter.

Third, after pressing Enter, R will try to open a browser window to sign the token. If everything works well, you will get a message that says you can return to R. If not, try again in a few minutes to make sure your app had its settings updated properly.

To ensure proper functioning of the "getInsights" function-family you will need to specify the exact permissions granted to your app. As this is (to our knowledge) currently not possible through the R based authentication process, please follow these steps:

-> Create App as mentioned above. 1. Open the "Graph API Explorer": https://developers.facebook.com/tools/explorer/ 2. Select your app in the upper right corner 3. Click "Get Token" -> "Get Access Token" 4. In the popup navigate to "Extended Permissions" and select "Insights" 5. Confirm 6. Ignore the following warning message ("Submit for Login Review...") and confirm again. 6. Go back to R and run fbOAuth with extended_permissions (still) set to FALSE. -> See third step for possible messages concerning token creation.

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

See Also

getUsers, getPost, searchFacebook

Examples

## Not run: 
## an example of an authenticated request after creating the OAuth token
## where app_id and app_secret are fictitious, and token is saved for
## future sessions
fb_oauth <- fbOAuth(app_id="123456789", app_secret="1A2B3C4D")
save(fb_oauth, file="fb_oauth")
load("fb_oauth")
me <- getUsers("me", token=fb_oauth)
me$username

## an example of a request using a temporary access token
	token <- "XXXXXXAAAAAAA1111"
	me <- getUsers("me", token=token)

## End(Not run)

Extract list of checkins of a Facebook friend

Description

getCheckins retrieves information about a friend's checkins

Usage

getCheckins(user, n = 10, token, tags = FALSE, api = NULL)

Arguments

Details

This function requires the use of an OAuth token with the following permissions: user_status, user_checkins, friends_status, friends_checkins

Check-in search was deprecated with version 2.0 of the Facebook Graph API.

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

See Also

getFriends

Examples

## Not run: 
 token <- 'XXXXX'
 my_checkins <- getCheckins(user="me", token=token)

## End(Not run)

Extract replies to comments on page post

Description

getCommentReplies retrieves the list of comments replying to an individual comment on a post by a public Facebook page.

Usage

getCommentReplies(comment_id, token, n = 500, replies = TRUE,
  likes = FALSE, n.likes = n, n.replies = n, api = NULL)

Arguments

Details

getCommentReplies returns a list with three components: comment, replies, and likes. First, comment contains information about the original comment: author, creation date, id, counts of likes and comments, etc. Second, replies is a data frame with information about the replies to the comment (author, message, creation time, id). Finally, likes is data frame that contains names and Facebook IDs of all the users that liked the comment.

Author(s)

Yan Turgeon

See Also

getPage, getPost

Examples

## Not run: 
## See examples for fbOAuth to know how token was created.
## Getting information about Facebook's Facebook Page
 load("fb_oauth")
 fb_page <- getPage(page="facebook", token=fb_oauth)
## Getting information and likes/comments about most recent post
 post <- getPost(post=fb_page$id[1], n=2000, token=fb_oauth)
## Downloading list of replies to first comment
 replies <- getCommentReplies(comment_id=post$comments$id[1], token=fb_oauth)

## End(Not run)

Extract list of events from a public Facebook page or group

Description

getEvents retrieves event information from a public Facebook group or page.

Usage

getEvents(page, token, api = "v2.9")

Arguments

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

See Also

getPage, fbOAuth

Examples

## Not run: 
load("fb_oauth")
## Downloading events from Playa Vista Farmers' Market
 events <- getEvents(page="playavistaFM", token=fb_oauth)

## End(Not run)

Executes a FQL query to the Facebook Graph API

Description

getFQL connects to Facebook's Graph API and executes a FQL query. See https://developers.facebook.com/docs/technical-guides/fql/ for an overview of the Facebook Query Language.

Usage

getFQL(query, token)

Arguments

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

Examples

## Not run: 
## See examples for fbOAuth to know how token was created.
## Getting list of friends of authenticated user
load("fb_oauth")
d <- getFQL("SELECT uid2 FROM friend WHERE uid1=me()", token=fb_oauth)

## End(Not run)

Extract list of friends with their information

Description

getFriends retrieves information about the user's friends.

Usage

getFriends(token, simplify = FALSE)

Arguments

Details

This function requires the use of a OAuth token with extended permissions. After the introduction of version 2.0 of the Graph API, only friends who are using the application that you used to generate the token to query the API will be returned.

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

See Also

getUsers, fbOAuth

Examples

## Not run: 
## Copy and paste token created at FB Graph API Explorer
 token <- "XXXXXX"
my_friends <- getFriends(token=token, simplify=TRUE)
## Since users are ordered by ID, this will return 10 oldest user accounts
head(my_friends, n=10)

## End(Not run)

Extract list of posts from a public Facebook group

Description

getGroup retrieves information from a public Facebook group.

Usage

getGroup(group_id, token, n = 25, since = NULL, until = NULL,
  feed = TRUE, api = NULL)

Arguments

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

See Also

getUsers, getPost, fbOAuth

Examples

## Not run: 
## Find Facebook ID for R-Users Facebook group
load("fb_oauth")
ids <- searchGroup(name="rusers", token=fb_oauth)
 ids[1,] # id = 18533493739
## Downloading posts from R-Users Facebook group
 group <- getGroup(group_id=18533493739, token=fb_oauth)
## Downloading posts from R-Users Facebook group in January 2013
 group <- getGroup(group_id=18533493739, token=fb_oauth,
	since='2013/01/01', until='2013/01/31')

## End(Not run)

Extract Insights metric from a Facebook page (admin role required)

Description

getInsights retrieves information from an owned Facebook page. Note that you must specify wich metric from insights you need and the period. To request multiple metrics at one time, pass a vector of metric names with a vector of periods of the same length. If only one period is supplied, it will apply to each metric. Please refer to Facebook's documentation for valid combinations of objects, metrics and periods.

Note that some insights require a page access token, see getPageToken

Usage

getInsights(object_id, token, metric, period = "day", parms = NA,
  version = 2.3, n = 5)

Arguments

Details

The current list of supported metrics and periods is: page_fan_adds, page_fan_removes, page_views_login, page_views_login, page_views_logout, page_views, page_story_adds, page_impressions, page_posts_impressions, page_consumptions, post_consumptions_by_type, page_consumptions, and page_fans_country.

For more information, see: https://developers.facebook.com/docs/graph-api/reference/v2.5/insights

Author(s)

Danilo Silva silvadaniloc@gmail.com Eduardo Carvalho eduardooc.86@gmail.com Andrew Geisler https://github.com/andrewgeisler

Examples

## Not run: 
## See examples for fbOAuth to know how token was created.
## Getting page impressions for Facebook's Facebook Page
## (only owner or admin of page)
 load("fb_oauth")
insights <- getInsights(object_id="20531316728", token=fb_oauth, metric='page_impressions')
## Getting post impressions for a random Facebook's page post
## (only owner or admin of page)
 insights <- getInsights(object_id='221568044327801_754789777921289', 
     token=fb_oauth, metric='post_impressions', period='days_28')
## Getting page fans for date range
## (only owner or admin of page)
insights <- getInsights(object_id='221568044327801',
    token=fb_oauth, metric=c'page_fans', period='lifetime', 
    parms='&since=2015-01-01&until=2015-01-31', version=2.5)
#' ## Getting page fans AND page impressions for date range
## (only owner or admin of page)
insights <- getInsights(object_id='221568044327801',
    token=fb_oauth, metric=c('page_fans','page_impressions'), period=c('lifetime','day'), 
    parms='&since=2015-01-01&until=2015-01-31')        
## Count of fans by country
  insights <- getInsights(object_id='221568044327801_754789777921289', 
     token=fb_oauth, metric='page_fans_country', period='lifetime')

## End(Not run)

Extract list of likes of a Facebook friend

Description

getLikes retrieves information about a friend's likes. To retrieve the number of likes for a page, use getUsers with the page IDs.

Usage

getLikes(user, n = 500, token)

Arguments

Details

This function requires the use of an OAuth token with the following permissions: user_likes, friends_likes

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

See Also

getFriends, fbOAuth

Examples

## Not run: 
 token <- 'XXXXX'
 my_likes <- getLikes(user="me", token=token)

## End(Not run)

Extract network of friends of authenticated user

Description

getNetwork retrieves the list of mutual friendships and returns the adjacency matrix or edge list for the network representing the neighborhood of the authenticated user.

Usage

getNetwork(token, format = "edgelist", verbose = TRUE)

Arguments

Details

This function requires the use of an OAuth token with extended permissions.

After the introduction of version 2.0 of the Graph API, only friends who are using the application will be returned.

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

See Also

getFriends, fbOAuth

Examples

## Not run: 
## See examples for fbOAuth to know how token was created.
## Copy and paste token created at FB Graph API Explorer
 token <- "XXXXXX"
 mat <- getNetwork(token=token, format="adj.matrix")
 library(igraph)
 network <- graph.adjacency(mat, mode="undirected")
 pdf("network_plot.pdf")
 plot(network)
 dev.off()

## End(Not run)

Download recent posts from the authenticated user's newsfeed

Description

getNewsfeed retrieves status updates from the authenticated user's News Feed

Usage

getNewsfeed(token, n = 200)

Arguments

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

See Also

fbOAuth, getPost

Examples

## Not run: 
## See examples for fbOAuth to know how token was created.
## Capture 100 most recent posts on my newsfeed
load("fb_oauth")
my_newsfeed <- getNewsfeed(token=fb_oauth, n=100)

## End(Not run)

Extract list of posts from a public Facebook page

Description

getPage retrieves information from a public Facebook page. Note that information about users that have turned on the "follow" option on their profile can also be retrieved with this function.

Usage

getPage(page, token, n = 25, since = NULL, until = NULL, feed = FALSE,
  reactions = FALSE, verbose = TRUE, api = NULL)

Arguments

Details

This function will only return information from public pages, not users with public profiles.

The since and until parameters are applied to the updated_time field in the post objects, and not the created_time. As a result, this function might return old posts that have been updated recently.

comments_count refers to the total of comments, including nested comments (replies). It might be different from the total number of comments available through the API if some comments have been deleted.

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

See Also

getUsers, getPost, fbOAuth

Examples

## Not run: 
## See examples for fbOAuth to know how token was created.
## Getting information about Facebook's Facebook Page
 load("fb_oauth")
 fb_page <- getPage(page="facebook", token=fb_oauth)
## Getting posts on Humans of New York page, including posts by others users
## (not only owner of page)
 page <- getPage(page="humansofnewyork", token=fb_oauth, feed=TRUE)
## Getting posts on Humans of New York page in January 2013
 page <- getPage(page="humansofnewyork", token=fb_oauth, n=1000,
   since='2013/01/01', until='2013/01/31')

## End(Not run)

Get a page access token

Description

Gets a page access token that can be used to e.g. get insights for a page.

Usage

getPageToken(page, token)

Arguments

Value

the page access token string

Examples

## Not run: 
## Get a normal access token with manage_pages scope
token = fbOAuth(app_id, app_secret, scope="manage_pages")
## Get a page access token for a page
page_token = getPageToken(page, token)
## Get page insights
getInsights(page, token=page_token, metric = "page_impressions")

## End(Not run)

Extract information about a public Facebook post

Description

getPost retrieves information about a public Facebook post, including list of comments and likes.

Usage

getPost(post, token, n = 500, comments = TRUE, likes = (!reactions),
  reactions = FALSE, n.likes = n, n.comments = n, n.reactions = n,
  api = NULL)

Arguments

Details

getPost returns a list with up to four components: post, likes, comments, and reactions. post contains information about the post: author, creation date, id, counts of likes, comments, and shares, etc. likes is a data frame that contains names and Facebook IDs of all the users that liked the post. comments is a data frame with information about the comments to the post (author, message, creation time, id). To download also the replies to specific comments, see getCommentReplies. Note that the total number of comments may be different from the number report in comments_count if some comments have been deleted.

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

See Also

getUsers, getPage, fbOAuth

Examples

## Not run: 
## See examples for fbOAuth to know how token was created.
## Getting information about Facebook's Facebook Page
load("fb_oauth")
fb_page <- getPage(page="facebook", token=fb_oauth)
## Getting information and likes/comments about most recent post
post <- getPost(post=fb_page$id[1], n=2000, token=fb_oauth)

## End(Not run)

Extract total count of reactions to one or more Facebook posts

Description

getReactions retrieves information from a single or multiple posts, returning the total count of reactions of each type (like, love, haha, wow, sad, angry).

Usage

getReactions(post, token, verbose = TRUE, api = NULL)

Arguments

Details

The solution implemented here is based on this Stack Overflow response: http://stackoverflow.com/questions/36930414/how-can-i-get-facebook-graph-api-reaction-summary-count-separately

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

See Also

getPage, getPost

Examples

## Not run: 
## See examples for fbOAuth to know how token was created.
## Getting information about Facebook's Facebook Page
load("fb_oauth")
fb_page <- getPage(page="facebook", token=fb_oauth)
## Getting reactions for most recent post
post <- getReactions(post=fb_page$id[1], token=fb_oauth)

## End(Not run)

Extract list of users who publicly shared a public Facebook post

Description

getShares retrieves a list of posts that correspond to shares of a post on a public Facebook page. Only public posts by users who have granted authorization to the app used to authenticate.

Usage

getShares(post, token, n = 100)

Arguments

Details

getShares returns a data frame with four variables: from_name (the name of the user who shared the post), from_id (the ID of the user who shared the post), shared_time (the time at which the post was shared), and id (the ID of the new post).

For more information on why not all shared posts are returned, see here: https://developers.facebook.com/bugs/1404733043148335/

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

See Also

getPage, getPost

Examples

## Not run: 
## See examples for fbOAuth to know how token was created.
## Getting information about Facebook's Facebook Page
load("fb_oauth")
fb_page <- getPage(page="facebook", token=fb_oauth)
## Getting shares of most recent post
shares <- getShares(post=fb_page$id[1], n=2000, token=fb_oauth)

## End(Not run)

Extract information about one or more Facebook users

Description

getUsers retrieves public information about one or more Facebook users.

After version 2.0 of the Facebook API, only id, name, and picture are available through the API. All the remaining fields will be missing.

Usage

getUsers(users, token, private_info = FALSE)

Arguments

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

See Also

getFriends, getPost, searchFacebook

Examples

## Not run: 
## See examples for fbOAuth to know how token was created.
## Getting information about the authenticated user
 load("fb_oauth")
fb <- getUsers("me", token=fb_oauth)
fb$username

## End(Not run)

Search public posts that mention a string

Description

searchFacebook retrieves public status updates that mention a given keyword

Usage

searchFacebook(string, token, n = 200, since = NULL, until = NULL)

Arguments

Details

Note: Public post search was deprecated with version 2.0 of the Facebook Graph API, and therefore this function will no longer work. For more information about these changes, go to: https://developers.facebook.com/docs/apps/changelog

The function will only work for OAuth tokens generated with version 1.0 of the API, which can no longer be created.

The search is performed also on the text of the comments too, which explains why some of the returned messages do not mention the string that is being searched.

Note that only messages up to around two weeks old or less can be returned.

Author(s)

Pablo Barbera pablo.barbera@nyu.edu

See Also

fbOAuth

Examples

## Not run: 
## Searching 100 public posts that mention "facebook"
posts <- searchFacebook( string="facebook", token=fb_oauth, n=100 )
## Searching 100 public posts that mention "facebook" from yesterday
posts <- searchFacebook( string="facebook", token=fb_oauth, n=100,
   since = "yesterday 00:00", until = "yesterday 23:59" )

## End(Not run)

Find Facebook ID of a group

Description

Use searchGroup in combination with getGroup to scrape public posts on Facebook groups.

Usage

searchGroup(name, token, api = NULL)

Arguments

Examples

## Not run: 
## Find Facebook ID for R-Users Facebook group
load("fb_oauth")
ids <- searchGroup(name="rusers", token=fb_oauth)
 ids[1,] # id = 18533493739
## Downloading posts from R-Users Facebook group
 group <- getGroup(group_id=18533493739, token=fb_oauth)
## Downloading posts from R-Users Facebook group in January 2013
 group <- getGroup(group_id=18533493739, token=fb_oauth,
	since='2013/01/01', until='2013/01/31')

## End(Not run)

Search pages that mention a string

Description

searchPages retrieves public pages that mention a given keyword

Usage

searchPages(string, token, n = 200)

Arguments

Author(s)

Pablo Barbera pablo.barbera@nyu.edu, Joel Gombin joel.gombin@gmail.com

See Also

fbOAuth, searchFacebook

Examples

## Not run: 
## See examples for fbOAuth to know how token was created.
## Searching 100 public pages that mention "facebook"
 load("fb_oauth")
pages <- searchPages( string="facebook", token=fb_oauth, n=100 )

## End(Not run)

Update Facebook status from R

Description

updateStatus sends a status update that will be displayed on the Facebook profile of the authenticated user.

Usage

updateStatus(text, token, link = NULL)

Arguments

Author(s)

Pablo Barbera pablo.barbera@nyu.edu, Zakharov Kyrylo (https://github.com/Amice13)

See Also

getUsers, getPost

Examples

## Not run: 
## See examples for fbOAuth to know how token was created.
 load("fb_oauth")
 updateStatus("this is just a test", token=fb_oauth)

## End(Not run)