If you run a facebook page or have a facebook app, Facebook collects oodles of data about who uses your app or page, when, and how. Facebook provides some pretty good analytics tools on their insights page, but there is always a need to get data out of facebook and into another database for corporate reporting (perhaps for ROI, or creating integrated reports across multiple social platforms). Facebook provides two APIs for this task. The Graph API and FQL. This post focuses on FQL.
FQL allows you to pass a SQL-like query to facebook in the querystring and it returns you an xml document with your data:
SELECT metric, value FROM insights WHERE object_id=PAGE OR APP YOU WANT DATA ABOUT AND metric='page_impressions' AND end_time=end_time_date('2011-06-26') AND period=period('month')
Object_Id represents the page or app you are getting data for. This ID will be in the URL of the page when you visit it, if you are having trouble finding it.
This will query will return an XML document:
<fql_query_response xmlns="http://api.facebook.com/1.0/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" list="true"> <insights> <metric>page_impressions</metric> <value>76</value> </insights> </fql_query_response>
But before you can run any queries for that page, you must be granted permission by the page’s owner. To do this, you must have create a facebook app on https://developers.facebook.com/apps. After doing so, you will be assigned an App Id and an App Secret token, which you will need later.
Then, you will need the admin user of the page or app (this might be you) to visit:
https://www.facebook.com/dialog/oauth?client_id=YOUR CLIENT ID&redirect_uri=YOUR WEBSITE URL&scope=read_insights&state=new
The scope param allows you to specify which permissions you need for your app. Right now all I care about is reading insights, but you might want to post to the users wall, or read the friend lists, etc.
When the user visits the above URL, they will be prompted to log in to Facebook if they are not already, and then they will be prompted to allow your app to access the data we are requesting. Then they will be redirected to the page you specified in the querystring. When they are redirected, there will be a new CODE param in the querystring. You need to extract that param and pass it to the below URL to complete authentication:
https://graph.facebook.com/oauth/access_token?client_id=YOUR APP ID&redirect_uri=SAME URL AS ABOVE&client_secret=YOUR APP SECRET&code=THE CODE YOU JUST RECEIVED
Note that you must supply the exact same URL in the second request that you did in the first. If all goes well, this second request will return:
Then making FQL queries is easy. You need to pass this as a parameter along with your query:
https://api.facebook.com/method/fql.query?access_token=ACCESS TOKEN YOU RECEIVED
This will return the xml document above. You can use different periods, different end times, and different metrics to get all of the data you require. For a full list of metrics available (there are a lot), check out https://developers.facebook.com/docs/reference/fql/insights/.