Introducing new Page Insights

Today we are launching new Page Insights to help Page admins understand how their content resonates with users. Measure everything from the number of stories about a Page to how viral a specific post has become. These new metrics are available today via Insights, FQL and the Graph API. For a list of the new metrics see the Insights FQL table.

Graph API Examples

Getting Page Insights

In order to obtain Page Insights via the Graph API, you must use a Page access token, and you must have the read_insights permission. Click on the link below to see this working in the Graph API Explorer.

https://graph.facebook.com/me/accounts

In the Graph API Explorer, click the "Get Access Token" button to obtain the read_insights and manage_pages permissions (listed under "Extended Permissions"). Click "Submit" to retrieve the list of Pages that you admin now that you have a valid access token. Page access tokens for those Pages you administer should now be listed. Copy the Page access token for the Page for which you want to retrieve Insights for, and paste it into the Access Token field at the top of the Graph API Explorer. The following examples assume that you are using this Page access token to make requests.

Once you have a list of Page IDs and an access token, you can pull many of the new metrics with a single call:

https://graph.facebook.com/PAGE_ID/insights

Here's a snippet showing Page stories from the response:

{
 ...
 "name": "page_stories",
 "period": "day",
 "values": [
   {
     "value": 101,
     "end_time": "2011-10-02T07:00:00+0000"
   },
 ...
}

Reading Page posts

To see a list of your Page posts, issue an HTTP GET to:

https://graph.facebook.com/PAGE_ID/posts

The response will look something similar to the response below. Please note the post ID (in bold).

{
  "data": [
    {
      "id": "129228016794_271029229588214",
      "from": {
        "name": "U.S. Politics on Facebook",
        "category": "Website",
        "id": "129228016794"
      },
    ...
    }
    ...
  ]
}

You can now issue an HTTP GET to the [POST ID]/insights endpoints to get per post Insights:

https://graph.facebook.com/[POST ID]/insights

Here's a response for post_impressions_unique:

{
  "data": [
    {
      "id": "129228016794_271029229588214/insights/
post_impressions_unique/lifetime",
      "name": "post_impressions_unique",
      "period": "lifetime",
      "values": [
        {
          "value": 1311
        }
      ],
      "description": "Lifetime The number of 
      people who saw your Page post. (Unique Users)"
    },
    ...
  ]
}

To make more efficient calls, you can limit the metrics you retrieve to a specific time range. For example, the following Graph API call retrieves the page_storytellers for the past 28 days:

https://graph.facebook.com/129228016794/insights/page_storytellers?
since=1310972400&until=1310972400&period=days_28

{
  "data": [
    {
      "id": "129228016794/insights/page_storytellers/days_28",
      "name": "page_storytellers",
      "period": "days_28",
      "values": [
        {
          "value": 8987,
          "end_time": "2011-07-18T07:00:00+0000"
        }
       ],
       "description": "28 Day The number of people sharing 
       stories about your page. These stories include liking 
       your Page, posting to your Page's Wall, liking, 
       commenting on or sharing one of your Page posts, 
       answering a Question you posted, RSVPing to one of 
       your events, mentioning your Page, phototagging 
       your Page or checking in at your Place. (Unique Users)."
    }
   ],
   ...
}

FQL Example

The examples above are also available via FQL. To obtain unique post impressions, follow the example FQL query below. You will need to obtain the same permissions above: (read_insights and manage_pages).

SELECT metric, value FROM insights WHERE object_id=19292868552 
AND metric='page_posts_impressions_unique' 
AND end_time=end_time_date('2011-07-18') 
AND period=period('days_28')

Snippet of response:

[
  {
    "metric":"page_posts_impressions_unique",
    "value":2922074
  }
]  

For more information on all the Insights metrics, please visit our Insights documentation. Please let us know if you have any questions in the Comments below.