Advanced Uses

Read-After-Write

For create and update endpoints, the Graph API can immediately read a successfully published or updated object and return any fields supported by the corresponding read endpoint.

To use this feature, include a fields parameter in your request and list the fields you want returned. For example, to publish the message “Hello” to a user's feed, you could make the following request:

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=created_time,from,id,message,permalink_url

This would return the specified fields as a JSON-formatted response, like this:

{
  "created_time": "2017-04-06T22:04:21+0000",
  "from": {
    "name": "Jay P Jeanne",
    "id": "126577551217199"
  },
  "id": "126577551217199_122842541590700",
  "message": "Hello",
  "permalink_url": "https://www.facebook.com/126577551217199/posts/122842541590700",
}

Refer to each endpoint's reference documentation to see if it supports read-after-write and what fields are available.

Errors

If the read fails for any reason (for example, requesting a non-existent field), the Graph API will respond with a standard error response. In addition, the response will include an original_response property whose value will be what the endpoint normally returns upon success.

For example, this request contains an invalid field:

POST graph.facebook.com
  /126577551217199/feed?
    message=Hello&
    fields=permalink_urls

This would be the response:

{
  "error": {
    "message": "(#100) Tried accessing nonexisting field (permalink_urls) on node type (Post)",
    "type": "FacebookApiException",
    "code": 100,
    "fbtrace_id": "AzMnKh6NRKY",
    "original_response": {
      "id": "126577551217199_122842541590700"
    }
  }
}

Modifying API Requests

Some API endpoints can be used with extra parameters that will modify the request. The nature of what these modifiers do varies, so we have documented each of them separately in each of the API reference documents where appropriate. Below is a list of common modifiers that can be used with most endpoints.

Name Description Type

return_ssl_resources

Used when you require a picture to be returned over a secure connection (HTTPS) to avoid mixed content warnings in browsers.

bool

locale

Used if your app needs the ability to retrieve localized content in the language of a particular locale (when available).

Locale

Other modifiers for paging and introspection are shown below.

Nested Requests

The field expansion feature of the Graph API allows you to effectively nest multiple graph queries into a single call. Certain resources, including most of Ads API, are unable to utilize field expansion on some or all connections.

For example, in a single call, you can ask for the first N photos of the first K albums. The response maintains the data hierarchy so developers do not have to weave the data together on the client.

This is different from the batch Requests feature which allows you to make multiple, potentially unrelated, Graph API calls in a single request.

Here is the general format that field expansion takes:

GET graph.facebook.com
  /{node-id}?
    fields=<first-level>{<second-level>}

<first-level> in this case would be one or more (comma-separated) fields or edges from the parent node. <second-level> would be one or more (comma-separated) fields or edges from the first-level node.

There is no limitation to the amount of nesting of levels that can occur here. You can also use a .limit(n) argument on each field or edge to restrict how many objects you want to get.

This is easier to understand by seeing it in action, so here's an example query that will retrieve up to five albums created by someone, and the last five posts in their feed.

GET graph.facebook.com
  /me?
    fields=albums.limit(5),posts.limit(5)

We can then extend this a bit more and for each album object, also retrieve the first two photos, and people tagged in each photo:

GET graph.facebook.com
  /me?
    fields=albums.limit(5){name, photos.limit(2)},posts.limit(5)

Now we can extend it again by retrieving the name of each photo, the picture URL, and the people tagged:

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

Let's look at an example using cursor-based pagination:

GET graph.facebook.com
  /me?fields=albums.limit(5){name,photos.limit(2).after(MTAyMTE1OTQwNDc2MDAxNDkZD){name,picture,tags.limit(2)}},posts.limit(5)

You can see how field expansion can work across nodes, edges, and fields to return really complex data in a single request.

Making Large Requests

Some Graph API endpoints can take parameters that are very large. If your requests end up being larger than a couple thousand characters, you may start seeing server errors since our servers will reject very large GET requests.

As a best practice, for large requests use a POST request instead of a GET request and add a method=GET parameter. If you do this, the POST will be interpreted as if it were a GET.

Making Multiple Requests

The standard version of the Graph API is designed to make it easy to get data for an individual object and to browse connections between objects. It also includes a limited ability to retrieve data for a few objects at the same time.

If your app needs the ability to access significant amounts of data at once, or you need to make changes to several objects at once, it is often more efficient to batch your queries rather than make multiple individual HTTP requests.

To enable this, the Graph API supports a number of functions, including multiple-ID lookup and batching. Batch requests are explained in a separate guide but you can read more about multiple ID lookup below.

Multiple ID Read Requests

You can make a single GET request that retrieves multiple nodes by using the ?ids endpoint with the object IDs of those nodes. For example, to lookup the Facebook Developers page and the current session user in a single request, you could use the following Graph API call:

GET graph.facebook.com
  /?ids=platform,me

Which is equivalent to the following individual API requests:

GET graph.facebook.com
  /platform
  
GET graph.facebook.com
  /me

The returned data will look something like this:

{
  "me": {
    "id": "1234567890"
    ... // Other fields
  }, 
  "platform": {
    "id": "19292868552"
    ... // Other fields
  }
}

This can also work with edges as long as all the requested IDs have the requested edge. For example:

GET graph.facebook.com
  /photos?ids={user-id-a},{user-id-b}

Is equivalent to the following individual API requests:

GET graph.facebook.com
  /{user-id-a}/photos
  
GET graph.facebook.com
  /{user-id-b}/photos

The returned data will look something like this:

{
  "{user-id-a}": {
    "data": [
      {
        "id": "12345", 
        "picture": "{photo-url}", 
        "created_time": "2014-07-15T15:11:25+0000"
      }
      ... // More photos
    ]
  },
  "{user-id-b}": {
    "data": [
      {
        "id": "56789", 
        "picture": "{photo-url}", 
        "created_time": "2014-01-15T12:24:47+0000"
      }
      ... // More photos
    ]
  }, 
}

Note that while field filtering, field expansion, and limiting will work with these multiple-ID lookups, you will get an error if one of the objects does not have any of the requested fields. For example, if you were to lookup a Page and a User using this method, and then filter on fields=id,picture,gender the request would fail because Pages do not have a gender field.

Introspection

The Graph API supports introspection of nodes. This enables you to see all of the edges a node has without knowing its type ahead of time. To get this information, add metadata=1 to the Graph API request:

GET graph.facebook.com
  /{node-id}?
    metadata=1

The resulting JSON will include a metadata property that lists all the supported edges for the given node:

{
   "name": {node-name},
   "metadata": {
      "connections": {
         "feed": "http://graph.facebook.com/me/feed",
         "picture": "https://graph.facebook.com/me/picture",
         ....
      }
      "fields": [
        {
          "name": "id",
          "description": "The user's Facebook ID. No `access_token` required. `string`."
        },
        ....
      ],
      "type": "user"
   }
}

You can search over some public objects in the social graph with the /search endpoint. The syntax for search is:

GET graph.facebook.com/search?
    q={your-query}&
    type={object-type}

All Graph API search queries require an access token included in the request. You need a user access token to execute a search.

Available Search Types

Type Description `q` value

place

Search for a place. You can narrow your search to a specific location and distance by adding the center parameter (with latitude and longitude) and an optional distance parameter (in meters):

Name

placetopic

Returns a list of possible place Page topics and their IDs. Use with topic_filter=all parameter to get the full list.

None

ad_*

A collection of different search options that can be used to find targeting options.

See Targeting Options

Example:

GET graph.facebook.com
  /search?
    q=coffee&
    type=place&
    center=37.76,-122.427&
    distance=1000

Complex Parameters

Most param types are straightforward primitives such as string and int, but there are also list and object types that can be specified in the request.

The list type is specified in JSON syntax, for example: ["firstitem", "seconditem", "thirditem"]

The object type is also specified in JSON syntax, for example: {"firstkey": "firstvalue", "secondKey": 123}