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 Graph API is named after the idea of a "social graph" — a representation of the information on Facebook. It's composed of:
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.
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...
... is equivalent to performing this cURL request:
curl -i -X GET \ "https://graph.facebook.com/facebook/picture ?redirect=false"
We cover this fully in our Using the Graph API guide, but in general you:
Almost all requests are passed to the
graph.facebook.com host URL. The single exception is video uploads, which use
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:
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
curl -i -X GET \ "https://graph.facebook.com/your-facebook-user-id/photos ?access_token=your-access-token"
Some nodes allow you to update fields with
POST operations. For example, you could update your
curl -i -X POST \ "https://graph.facebook.com/your-facebook-user-id ?firstname.lastname@example.org &access_token=your-access-token"
To run the above query, you will need to request an access token with the
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.
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.
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.