Overview 

Facebook is one of the most popular social networking sites and photo sharing platforms in the world. Users add friends, post comments, and join fan pages, among other activities. Only Facebook data abiding by Facebook’s ToS is available through Gnip.

Gnip provides managed access to Facebook’s public API via the Data Collector. See below for details on the specific type of access supported, and sample payloads.

Obtaining a Facebook Access Token

To use the Facebook API, customers will need to generate an “Access Token from the Facebook developer platform.” This involves registering as a developer and creating an application.

After your application is created, Facebook will provide you with an “App ID” and an “App Secret”. Take these two values, plug them into the following command on any unix box:

 curl -F type=client_cred \
 -F client_id=app_id \
 -F client_secret=app_secret \
 https://graph.facebook.com/oauth/access_token?scope=offline_access

This will return an “Access Token” from Facebook that can be used in the Gnip UI to setup a Facebook feed, make sure to copy all of it. Once you get an access token back, it is a good idea to verify that you have copied it correctly by running the following command, and verifying that Facebook returns data rather than an error message:

 curl -v "https://graph.facebook.com/search?q=cat&type=post&limit=2&access_token=access_token"

Data Collector Streams 

FanPage Feed

Input: Fan page IDs or friendly names

Output: Public wall posts, and comments for 100 most recent posts. Access to content depends on a Facebook Access Token.

Note that some pages may not be accessible. Fan Page owners can choose to restrict API access to the data on their pages, including restricting access to users whose accounts are based in specific countries, users whose accounts are associated with a specific language, or users who are above a certain age.

In situations where API access has been restricted by the owner, the Facebook API will return an error that reads “false” which will be indicated by your Gnip stream as a 601 error in the dashboard. In order to access data for these pages using Facebook’s App-based Access token, all restrictions on the page need to be removed by the page’s owner.

Additionally, page owners may occasionally move a page to a new page ID. If this occurs, the Facebook API will return an error, which will be indicated on the “Data” tab of the Data Collector dashboard, and the Rules tab under Rules With Errors.

To see the error message for one of these IDs, insert the ID into the following URL and navigating there in a browser:

 http://graph.facebook.com/<page_ID>

The resulting error message will provide you with additional information about where to find the page, if it has moved, or that the page no longer exists. If the page does not exist, it might mean that you are entering an incorrect ID for a page that actually exists, or a page that you are correctly referencing has since been deleted.


FanPage Feed (without comments)

Input: Fan page IDs or friendly names

Output: Public wall posts. Access to content depends on a Facebook Access Token.


FanPage Metadata

Input: Fan Page IDs or user page IDs (not keywords)

Output: Daily updates on fan count, mission, and product info for pages you specify


FanPage Posts by Owner

Input: Fan Page IDs or user page IDs (not keywords)

Output: Page-owner posts for the pages you specify. Excludes comments on wall posts


FanPage Lookup

Input: Keywords

Output: A list of pages whose titles match your keyword – not the post content from those pages


FanPage Photos

Input: Fan Page IDs or user page IDs (not keywords)

Output: Public photos uploaded to the Fan Pages you specify. Comments on the photos are not included


Sample Payloads 


Best Practices 

Facebook limits the amount of data that can be extracted from the Graph API based on a combination of your IP address and Access Token. For this reason, two separate Facebook feeds, deployed on the same Gnip data collector will be viewed by the Graph API as the same entity, and will force them to compete for the same limited resources. We recommend the following practices to optimize your coverage of Facebook data:

  • Ideally, each Facebook feed should be deployed on a separate Gnip data collector to ensure that the feeds do not compete for resources from Facebook.
  • If you decide to use multiple Facebook feeds on a single Gnip data collector, you should consult with the Gnip support team to optimize the feeds and avoid being rate-limited by Facebook.