The Graph API is the primary way to get data into and out of the Facebook platform. It's a low-level 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&access_token={valid-access-token-goes-here}"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:
The pseudo-code request/response examples throughout our Graph API documentation will not explicitly reference an access token, but you should assume that an access token was included in the request in order to have received a response.
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, the official Facebook Page has the ID 20531316728. You query it directly by using its ID:
GET graph.facebook.com /20531316728
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 Page node reference reveals that one of the fields you can get when reading a Page object is the cover field, which is the Page's cover photo. Here's what that query would look like:
GET graph.facebook.com /20531316728?fields=cover
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 Page node reference is the photos edge, which returns all of the Photo objects owned by the Page. So, to get all of the photos owned by the Facebook page, you query the node's photos edge:
GET graph.facebook.com /20531316728/photos
Some nodes allow you to update fields with POST operations. For example, if you were an Admin of the Facebook Page you could update its description field like this:
POST graph.facebook.com /20531316728?description=The%20OFFICIAL%20Facebook%20Page
Edges often allow you to publish new objects to the node's collections by performing POST operations. Here's how you could publish a photo to the collection of photos owned by the Facebook Page:
POST graph.facebook.com /20531316728/photos
Of course, publishing an object to a collection typically requires additional fields about that object, such as a photo's URL, or a title, or description. Edge reference documentation indicates which fields are required and which are optional.
Finally, you can usually delete a node by performing a DELETE operation on the object ID:
DELETE graph.facebook.com /20531316728
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:
GET graph.facebook.com /v2.9/20531316728/photos
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.