DocumentationForumShowcaseBlog
The new Graph API attempts to drastically simplify the way developers read and write data to Facebook. It presents a simple, consistent view of the Facebook social graph, uniformly representing objects in the graph (e.g., people, photos, events, and fan pages) and the connections between them (e.g., friend relationships, shared content, and photo tags).
Every object in the social graph has a unique ID. You can fetch the data associated with an object by fetching https://graph.facebook.com/ID. For example, the official page for the Facebook Platform has id 19292868552, so you can fetch the object at https://graph.facebook.com/19292868552:
{
"name": "Facebook Platform",
"type": "page",
"website": "http://developers.facebook.com",
"username": "platform",
"founded": "May 2007",
"company_overview": "Facebook Platform enables anyone to build...",
"mission": "To make the web more open and social.",
"products": "Facebook Application Programming Interface (API)...",
"fan_count": 449921,
"id": 19292868552,
"category": "Technology"
}
Alternatively, people and pages with usernames can be fetched using their username as an ID. Since "platform" is the username for the page above, https://graph.facebook.com/platform will return what you expect. All responses are JSON objects.
All objects in Facebook can be accessed in the same way:
All of the objects in the Facebook social graph are connected to each other via relationships. Bret Taylor is a fan of the Coca-Cola page, and Bret Taylor and Arjun Banker are friends. We call those relationships connections in our API. You can examine the connections between objects using the URL structure https://graph.facebook.com/ID/CONNECTION_TYPE. The connections supported for people and pages include:
We support different connection types for different objects. For example, you can get the list of all the people attending the Facebook Developer Garage at SXSW (ID #331218348435) by fetching https://graph.facebook.com/331218348435/attending.
All of the different types of objects and connections we support are included in the Graph API reference documentation.
By default, most object properties are returned when you make a query. You can choose the fields (or connections) you want returned with the "fields" query parameter. For example, this URL will only return the id, name, and picture of Ben: https://graph.facebook.com/bgolub?fields=id,name,picture
You can also request multiple objects in a single query using the "ids" query parameter. For example, the URL https://graph.facebook.com?ids=arjun,vernal returns both profiles in the same response.
The "ids" query parameter also accepts URLs. This is useful for finding IDs of URLs in the Open Graph. For example: https://graph.facebook.com/?ids=http://www.imdb.com/title/tt0117500/
Additionally, there is a special identifier me which refers to the current user. So the URL https://graph.facebook.com/me returns the active user's profile.
The Graph API supports introspection of objects, which enables you to see all of the connections an object has without knowing its type ahead of time. To get this information, add metadata=1 to the object URL, and the resulting JSON will include a metadata property that lists all the supported connections for the given object. For example, you can see all the connections for the Developer Garage event above by fetching https://graph.facebook.com/331218348435?metadata=1. That outputs:
{
"name": "Facebook Developer Garage Austin - SXSW Edition",
"metadata": {
"connections": {
"feed": "http://graph.facebook.com/331218348435/feed",
"picture": "https://graph.facebook.com/331218348435/picture",
"invited": "https://graph.facebook.com/331218348435/invited",
"attending": "https://graph.facebook.com/331218348435/attending",
"maybe": "https://graph.facebook.com/331218348435/maybe",
"noreply": "https://graph.facebook.com/331218348435/noreply",
"declined": "https://graph.facebook.com/331218348435/declined"
}
}
}
The introspection feature is a useful and extensible way to find all the things your users are connected to.
The Graph API uses OAuth 2.0 for authorization. Check out the authentication guide for the details of Facebook's OAuth 2.0 implementation.
OAuth 2.0 is a simpler version of OAuth that leverages SSL for API communication instead of relying on complex URL signature schemes and token exchanges. At a high level, using OAuth 2.0 entails getting an access token for a Facebook user via a redirect to Facebook. After you obtain the access token for a user, you can perform authorized requests on behalf of that user by including the access token in your Graph API requests:
https://graph.facebook.com/220439?access_token=...
Check out the PHP example code or the Python example code on GitHub to see a complete example of obtaining an access token for the current user. The steps to obtain an access token are:
Register your application to get an app ID and secret. Your Facebook app ID is your client_id and your Facebook application secret is your client_secret.
Redirect the user to https://graph.facebook.com/oauth/authorize with your client_id and the redirect_uri. The redirect_uri parameter needs to begin with your app's URL. For instance, if your URL is http://www.example.com then your redirect URI could be http://www.example.com/oauth_redirect.
https://graph.facebook.com/oauth/authorize?
client_id=...&
redirect_uri=http://www.example.com/oauth_redirect
code, which can be exchanged for an oauth access token. Exchange it for an access token by fetching https://graph.facebook.com/oauth/access_token. Pass the exact same redirect_uri as in the previous step:https://graph.facebook.com/oauth/access_token?
client_id=...&
redirect_uri=http://www.example.com/oauth_redirect&
client_secret=...&
code=...
https://graph.facebook.com/me?access_token=...
You can impersonate pages administrated by your users by requesting the "manage_pages" extended permission.
Once a user has granted your application the "manage_pages" permission, the "accounts" connection will yield an additional access_token property for every page administrated by the current user. These access_tokens can be used to make calls on behalf of a page. The permissions granted by a user to your application will now also be applicable to their pages.
You can publish to the Facebook graph by issuing HTTP POST requests to the appropriate connection URLs above, using an application access token. For example, you can post a new wall post on Arjun's wall by issuing a POST request to https://graph.facebook.com/arjun/feed:
curl -F 'access_token=...' \
-F 'message=Hello, Arjun. I like this new API.' \
https://graph.facebook.com/arjun/feed
You can comment on or like a post by posting to https://graph.facebook.com/POST_ID/comments and https://graph.facebook.com/POST_ID/likes, respectively:
curl -F 'access_token=...' \
https://graph.facebook.com/313449204401/likes
Most write operations require extended permissions for the active user. See the authentication guide for details on how you can request extended permissions from the user during the authentication step.
We support writing the following types of objects:
| Method | Description | Arguments |
|---|---|---|
/PROFILE_ID/feed |
write to the given profile's feed/wall | message, picture, link, name, caption, description, source |
/POST_ID/comments |
comment on the given post | message |
/POST_ID/likes |
like the given post | none |
/PROFILE_ID/notes |
write a note on the given profile | message, subject |
/PROFILE_ID/links |
write a link on the given profile | link, message |
/PROFILE_ID/events |
create an event | name, start_time, end_time |
/EVENT_ID/attending |
attend the given event | none |
/EVENT_ID/maybe |
maybe attend the given event | none |
/EVENT_ID/declined |
decline the given event | none |
/PROFILE_ID/albums |
create an album | name, message |
/ALBUM_ID/photos |
upload a photo to an album | message |
The Graph API reference provides more detailed information on the supported arguments and their corresponding values.
You can post to the authenticated user's feed, links, or notes by issuing your request directly to /me/feed, /me/links, or, /me/notes, respectively. For example, this posts a message to the authenticated user's wall:
curl -F 'access_token=...' \
-F 'message=I am posting to my own feed. I am awesome.' \
https://graph.facebook.com/me/feed
You can delete objects in the graph by issuing HTTP DELETE requests to the object URLs, i.e,
DELETE https://graph.facebook.com/ID?access_token=... HTTP/1.1
To support clients that do not support all HTTP methods (like JavaScript clients), you can alternatively issue a POST request to an object URL with the additional argument method=delete to override the HTTP method. For example, you can delete a comment by issuing a POST request to https://graph.facebook.com/COMMENT_ID?method=delete.
You can delete a like by issuing a DELETE request to /POST_ID/likes (since likes don't have an ID).
You can render the current profile photo for any object by adding the suffix /picture to the object URL. For example, this will render your public profile photo:
<img src="https://graph.facebook.com/zuck/picture"/>
The same URL pattern works for all objects in the graph:
You can specify the picture size you want with the type argument, which should be one of square (50x50), small (50 pixels wide, variable height), and large (about 200 pixels wide, variable height): http://graph.facebook.com/zuck/picture?type=large.
When querying connections, there are several useful parameters that enable you to filter and page through connection data:
limit, offset: https://graph.facebook.com/me/likes?limit=3until, since (a unix timestamp or any date accepted by strtotime): https://graph.facebook.com/search?until=yesterday&q=orangeYou can search for and read users' check-ins made with Places and Places-enabled applications. Every check-in is associated with a check-in ID that represents an object in the graph. Check-ins are associated with locations represented by Facebook Pages; the location must have a Facebook Page ID, whether the Page was created on Facebook directly or using the Open Graph protocol.
To get a user's check-ins, request the user_checkins extended permission.
To see the user's friends' check-ins, request the friends_checkins extended permission.
You can GET individual check-ins by passing the check-in ID:
GET https://graph.facebook.com/[checkin_id]
Or you can GET check-in information from individual places, or users:
GET https://graph.facebook.com/[user id]/checkins
GET https://graph.facebook.com/[place page id]/checkins
You can search for recent check-ins for an authorized user and his or her friends:
GET https://graph.facebook.com/search?type=checkin&access_token=ACCESS_TOKEN
You can search over all public objects in the social graph with https://graph.facebook.com/search. The format is:
https://graph.facebook.com/search?q=QUERY&type=OBJECT_TYPE
We support search for the following types of objects:
You can also search an individual user's News Feed, restricted to that user's friends, by adding a q argument to the home connection URL:
Real-time updates provide you the ability to receive updates about all of your application's users, as their data changes. With such subscriptions, you can be confident that your cached data is correct without polling Facebook's servers, increasing the reliability of your application, and the responsiveness of your user experience.
When you register your application, you can get detailed analytics about the demographics of your users and how users are sharing from your application with Insights.
The Graph API provides programmatic access to all of this data so you can integrate Platform data into your own, custom analytics systems.
To download Insights data, you first need to obtain an OAuth access token associated with your application via the OAuth Client Credentials Flow. You can obtain an access token for your application with:
curl -F grant_type=client_credentials \
-F client_id=your_app_id \
-F client_secret=your_app_secret \
https://graph.facebook.com/oauth/access_token
Once you have your application access token, you can download analytics data for your application at:
https://graph.facebook.com/app_id/insights?access_token=...
That URL outputs all of the analytics data available via the API, including the total number of users, number of active users, and a number of other detailed metrics. For example, you can get the number of users who have seen pages shared from your site with:
https://graph.facebook.com/app_id/insights/share_views/day?access_token=...
You can use since and until to specify the time range for which you want data. Both arguments accept times in almost any valid date format:
https://graph.facebook.com/app_id/insights?access_token=...&since;=yesterday
Explore the Insights product and the base /insights URL for more a complete list of metrics available.
All of the objects, connections, and write methods supported by Facebook are documented in the Graph API reference.
