At Facebook's core is the social graph; people and the connections they have to everything they care about. The Graph API presents a simple, consistent view of the Facebook social graph, uniformly representing objects in the graph (e.g., people, photos, events, and 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 access the properties of an object by requesting 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",
"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)...",
"likes": 449921,
"id": 19292868552,
"category": "Technology"
}
Alternatively, people and pages with usernames can be accessed 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?access_token=....
All of the different types of objects and connections we support are included in the Graph API reference documentation. The easiest way to get started is to check out the Graph API Explorer.
The Graph API allows you to easily access all public info about an object, however to get additional info beyond that, you must first get a user's permission. This is done using Facebook Login by authenticating the User and then asking them to authorize the app. The Graph API uses the open standard OAuth 2.0 for authorization. Read more about the concepts of Facebook Login or get started on implementing it using our Technical Guides.
The Graph API allows you to read properties and connections of the Facebook social graph. You can use the API to read specific fields, get pictures of any object, introspect an object for metadata and get real-time updates on any changes.
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.
When retrieving Posts via the /home, /feed, or /posts connection, you can restrict the results to only those with a location attached by adding with=location
to the URL parameters:
https://graph.facebook.com/me/home?with=location
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/0/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), normal
(100 pixels wide, variable height), and large
(about 200 pixels wide, variable height): http://graph.facebook.com/0/picture?type=large.
If you need a picture to be returned over a secure connection, you can set the return_ssl_resources
argument to 1
: http://graph.facebook.com/0/picture?return_ssl_resources=1.
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=orangeTo see all options in detail, please visit the Pagination documentation
All date fields are returned as ISO-8601 formatted strings. You can optionally override the date format by specifying a "date_format" query parameter. The accepted format strings are identical to those accepted by the php date function. For example, http://graph.facebook.com/platform/feed?date_format=U returns the Platform page's feed, with unixtime-formatted dates.
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.
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.
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:
access_token
)center
parameter (with latitude and longitude) and an optional distance
parameter: q=
parameter.)type=location
and add the center
and distance
parameters: https://graph.facebook.com/search?type=location¢er=37.76,-122.427&distance=1000type=location
and specify the ID of the place
. For example for Posts at Facebook HQ, use: https://graph.facebook.com/search?type=location&place=166793820034304You can restrict the fields returned by these searches using the ?fields=
URL parameter, in the same way you can when reading other objects. For example, to get only the names of events, you can do the following:
Some fields such as id
, and start_time
for events, are always returned.
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:
Note: /me/home
retrieves an outdated view of the News Feed. This is currently a known issue and we don't have any near term plans to bring them back up into parity.
When searching for public posts or posts on the user's News Feed, you can page over the results by using the since
, until
and limit
parameters. since
and until
both accept a unix timestamp. When paging back in time, you should use until
in conjunction with limit
where until
is the unixtime value of the created_time
field in the last object returned by your previous query. When paging forward in time you should set since
to be the unixtime value of the created_time
field in the first object returned by your previous query. Please note, you can only search about 1 to 2 weeks back in the News Feed.
You can publish to the Facebook graph by issuing HTTP POST requests to the appropriate connection URLs, using an 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
The Graph API reference provides more detailed information on the supported arguments and their corresponding values.
You can comment on or like any object that has a /comments
or /likes
connection by posting to https://graph.facebook.com/OBJECT_ID/comments
and https://graph.facebook.com/OBJECT_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 |
Publish a new post on the given profile's feed/wall | message , picture , link , name , caption , description , source , place , tags |
/OBJECT_ID/comments |
Comment on the given object (if it has a /comments connection) |
message |
/OBJECT_ID/likes |
Like the given object (if it has a /likes connection) |
none |
/PROFILE_ID/notes |
Publish a note on the given profile | message , subject |
/PROFILE_ID/links |
Publish a link on the given profile | link , message , picture , name , caption , description |
/PROFILE_ID/events |
Create an event | name , start_time , end_time |
/EVENT_ID/attending |
RSVP "attending" to the given event | none |
/EVENT_ID/maybe |
RSVP "maybe" to the given event | none |
/EVENT_ID/declined |
RSVP "declined" to the given event | none |
/PROFILE_ID/albums |
Create an album | name , message |
/ALBUM_ID/photos |
Upload a photo to an album | message , source , place (multipart/form-data) |
/PROFILE_ID/checkins |
Create a checkin at a location represented by a Page | coordinates , place , message , tags |
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 /OBJECT_ID/likes
(since likes don't have an ID).
When you register your app, 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 app 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 impressions of your app's canvas page:
https://graph.facebook.com/app_id/insights/application_canvas_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, the base /insights
URL, and the Insights documentation for more information.
If your app needs the ability to access significant amounts of data or make changes to several objects at once, it is more efficient to combine these operations than to make multiple HTTP requests.
To batch requests, please refer to our documentation.
If your app needs the ability to retrieve localized content in the language of a particular locale, add the locale
parameter.
https://graph.facebook.com/...?access_token=...&locale=LOCALE
The locales that Facebook supports are available in an XML file. For more information on locales, check out the Internationalization documentation.
How to use App and Game Groups.
If your application needs the ability to access significant amounts of data in a single go - or you need to make changes to several objects at once, it is often more efficient batch your queries rather than make multiple individual HTTP requests. To enable this, the Graph API support Batching. Batching allows you to pass instructions for several operations in a single HTTP request.
Graph API Field Expansion
Paging through Graph API results
Permissions to access GRAPH API fields and connections.
Using pictures with the Graph API
The Graph API supports realtime updates to enable your app using Facebook to subscribe to changes in data from Facebook. Your app caches data and receives updates, rather than polling Facebook’s servers. Caching data and using this API can improve the reliability of your app and decrease its load times.
Instance for an achievement for a user.
A photo album
An application registered on Facebook Platform
A checkin made through Facebook Places or the Graph API.
A Comment on a Graph API object
A website domain within the Graph API
Errors using the Graph API
A Facebook event
A Facebook friend list
A Facebook group
Statistics about applications, pages, or domain.
A shared link
A message in a thread
A Facebook Note
An Offer published by a page.
An order object associated with Facebook Credits.
A Facebook Page
An individual photo within an album
An individual entry in a profile's feed
A question asked by a user, as represented in the Graph API.
An option allowed as an answer to a question.
A review for an application
A status message on a user's wall
A message thread
A user profile.
An individual video