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...
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"
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 graph-video.facebook.com
.
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:
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.
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.
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.
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.