Graph API

Overview

The Graph API is the primary way to get data into and out of the Facebook platform. It's an HTTP-based API that apps can use to programmatically query data, post new stories, manage ads, upload photos, and perform a wide variety of other tasks.

The Basics

The Graph API is named after the idea of a "social graph" — a representation of the information on Facebook. It's composed of:

  • nodes — basically individual objects, such as a User, a Photo, a Page, or a Comment
  • edges — connections between a collection of objects and a single object, such as Photos on a Page or Comments on a Photo
  • fields — data about an object, such as a User's birthday, or a Page's name

Typically you use nodes to get data about a specific object, use edges to get collections of objects on a single object, and use fields to get data about a single object or each object in a collection.

HTTP

The Graph API is HTTP-based, so it works with any language that has an HTTP library, such as cURL and urllib. This means you can use the Graph API directly in your browser. For example, requesting this URL in your browser...

https://graph.facebook.com/facebook/picture?redirect=false

... is equivalent to performing this cURL request:

curl -i -X GET \
 "https://graph.facebook.com/facebook/picture
    ?redirect=false"

Structure

We cover this fully in our Using the Graph API guide, but in general you:

  • use nodes to get data about individual objects
  • use edges to get collections of objects connected to a node, or to publish objects to those collections
  • use fields to specify which data you want included in responses

Host URL

Almost all requests are passed to the graph.facebook.com host URL. The single exception is video uploads, which use graph-video.facebook.com.

Object IDs

Nodes are individual objects, each with a unique ID, so to get information about a node you directly query its ID. For example, every Facebook Page or User account has an ID that allows you to query information about that Page or User:

curl -i -X GET \
  "https://graph.facebook.com/object-id
    ?access_token=your-access-token"

You probably noticed the access_token parameter and placeholder value in the cURL request above. Most Graph API requests require an access token. You eventually must learn how access tokens work by reading our access token documentation, but for now, all you need to know is:

  • almost all Graph API requests require an access token of some kind, and
  • the easiest way to get access tokens for your app is to implement Facebook Login

To run the examples below you will need to get an access token with the needed permissions. Get access tokens for each request as well as your Facebook User ID using the Graph API Explorer tool.

Object Fields and Edges

If you want to get specific data (called fields) about a node, you can include the fields parameter and specify which fields you want returned in the response. A quick check of the User node reference reveals that one of the fields you can get when reading a User object is the name field, which is your name. Here's what that query would look like:

curl -i -X GET \
  "https://graph.facebook.com/your-facebook-user-id
    ?fields=name
    &access_token=your-access-token"

Most nodes have edges, which can return collections of objects connected to that node. To query an edge, you use both the node ID and the edge name. One of the edges listed in the User node reference is the photos edge, which returns all of the photo objects . So, to get all of the photos owned by you, you query the node's photos edge:

curl -i -X GET \
  "https://graph.facebook.com/your-facebook-user-id/photos
     ?access_token=your-access-token"

To run the above query, you will need to request an access token with user_photos permission. Get one using the Graph Explorer tool.

Some nodes allow you to update fields with POST operations. For example, you could update your email field like this:

curl -i -X POST \
  "https://graph.facebook.com/your-facebook-user-id
    ?email=you@your-email.com
    &access_token=your-access-token"

To run the above query, you will need to request an access token with the email permission.

Finally, you can usually delete a node by performing a DELETE operation on the object ID:

curl -i -X DELETE \
  "https://graph.facebook.com/object-id
    ?access_token=your-access-token"

NOTE: Running the above command will delete your Facebook User Account.

Versions

The Graph API has multiple versions. You can read more about versioning in our App Version guide, but here we'll explain how you make a call to a specific version.

It's really simple — just add the letter v followed by the version number to the start of the request path. For example, here's a call to version 2.9:

curl -i -X GET \
  "https://graph.facebook.com/v2.9/your-facebook-user-id/photos
    ?access_token=your-access-token"

If you do not include a version number we will default to the oldest available version, so it's best to include the version number in your requests.

The Graph API changelog lists all available versions and our Reference docs allow you to filter content by version.

Next Steps

Now let's look at Using The Graph API to see some more elaborate requests and their responses, and to see what other actions you can perform with the Graph API.