Field Expansion

The Field Expansion feature of the Graph API, allows you to effectively "join" multiple graph queries into a single call.

This allows developers to nest connected objects in a Graph API call. For example, they can ask for the first N photos of the first K albums, in one call. The response maintains data hierarchy so developers do not have to weave the data together on the client like they do for multiqueries and the Graph Batch API.

This is meant as an advanced feature with no cost on the simplicity of the basic Graph API.

Previously, the only way to make a single call like this was to use the Facebook Query Language (FQL). It should be noted that while this is a powerful feature for the Graph API, there may still be cases where you will have to use FQL in order to gather the data you require.

Usage

The best way to understand Field Expansion, is to use the Graph Explorer to build the queries. You will be able to see the query being built in real-time to understand the syntax for identifiers, fields, and connections.

There are some connections like referencing built-in and custom Open Graph actions, which you'll have to manually enter into the query line in the Graph Explorer.

Examples

Example 1: Basic Limit Query

The following query will return the currently logged in user's name and birthday. Then it will query the photo object returning the last 10 pictures and ids:

GET https://graph.facebook.com/me?fields=name,birthday,photos.limit(10).fields(id, picture)

Example 2: Using Valid Parameters

Any valid parameter can be used. The videos object, for example, has a type param that can be specified as either uploaded or tagged.

Let's update the previous call to also get 10 videos in which the user is tagged:

GET https://graph.facebook.com/me?fields=name,birthday,photos.limit(10).fields(id,picture),videos.type(tagged).limit(10).fields(id, source)

Example 3: Nesting

Here's a query to get up to five albums from a user and for each album get the first two photos and people tagged in each photo:

GET https://graph.facebook.com/me?fields=albums.limit(5).fields(name, photos.limit(2).fields(name, picture, tags.limit(2)))

{
   "id": "5000388",
   "albums": {
      "data": [
         {
            "name": "My Uploads",
            "id": "167343188",
            "created_time": "2009-10-31T01:16:01+0000",
            "photos": {
               "data": [
                  {
                     "name": "Raising a Plant",
                     "picture": "https://fbcdn-photos-a.akamaihd.net/hphotos-ak-ash3/5686_10150636498189_1775439_s.jpg",
                     "id": "101363649819",
                     "created_time": "2012-06-23T06:31:53+0000"
                  },
                  {
                     "name": "Dressed up",
                     "picture": "https://fbcdn-photos-a.akamaihd.net/hphotos-ak-snc6/1392_101509832589_25596_s.jpg",
                     "id": "100989593189",
                     "created_time": "2012-06-23T01:18:07+0000",
                     "tags": {
                        "data": [
                           {
                              "id": "10000002867",
                              "name": "S\u0142awek",
                              "x": 52.9363,
                              "y": 24.4722,
                              "created_time": "2012-06-23T19:11:08+0000"
                           }
                        ]
                     }
                  }
               ],
               "paging": {
                  "next": "https://graph.facebook.com/1673988/photos?limit=2&fields=name,picture,tags.limit\u0025282\u002529&after=MTAxNTA5ODMyNOTMxODk\u00253D"
               }
            }
         },
         ...
}

Example 4: Nested Identifiers

Expansion works not only for connections, but for identifiers as well:

GET https://graph.facebook.com/<photo_id>/comments?fields=from.fields(id, name, birthday)

Example 5: Nesting Open Graph Objects

You can also retrieve built-in and custom Open Graph action data. You will have to manually enter the action since the Graph Explorer does not support the options in the drop down tool. The Graph Explorer will still execute a manually entered query.

This query will pull the last 2 articles read by your friends, displaying 10 of your friends at a time. As with any query, you must have the proper permissions. In this case, you must have the Open Graph permissions to read your friends stories through friends_actions.news

GET https://graph.facebook.com/me/friends?limit=10&fields=news.reads.limit(2)

Updated about a week ago