Introduction

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",
   "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 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:

* Users: https://graph.facebook.com/btaylor (Bret Taylor)
* Pages: https://graph.facebook.com/cocacola (Coca-Cola page)
* Events: https://graph.facebook.com/251906384206 (Facebook Developer Garage Austin)
* Groups: https://graph.facebook.com/2204501798 (Emacs users group)
* Applications: https://graph.facebook.com/2439131959 (the Graffiti app)
* Status messages: https://graph.facebook.com/367501354973 (A status message from Bret)
* Photos: https://graph.facebook.com/98423808305 (A photo from the Coca-Cola page)
* Photo albums: https://graph.facebook.com/99394368305 (Coca-Cola's wall photos)
* Profile pictures: http://graph.facebook.com/750068429/picture (your profile picture)
* Videos: https://graph.facebook.com/614004947048 (A Facebook tech talk on Tornado)
* Notes: https://graph.facebook.com/122788341354 (Note announcing Facebook for iPhone 3.0)
* Checkins: https://graph.facebook.com/414866888308 (Check-in at a pizzeria)

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.

Authorization

The Graph API as such allows you to easily access all public information about an object. For example, https://graph.facebook.com/btaylor (Bret Taylor) returns all the public information about Bret. For example a user's first name, last name and profile picture are publicly available.

To get additional information about a user, you must first get their permission. At a high level, you need to get an access token for the Facebook user. After you obtain the access token for the 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=...

For example https://graph.facebook.com/btaylor?access_token=... (Bret Taylor) returns additional information about Bret Taylor.

The Graph API uses OAuth 2.0 for authorization. Please read the authentication and authorization guide which provides details of Facebook's OAuth 2.0 implementation, how to request permissions from a user and obtain an access token.

Getting an access token for a user with no extended permissions allows you to access the information that the user has made available to everyone on Facebook. If you need specific information about a user, like their email address or work history, you must ask for the specific extended permissions. You can learn about permissions you need, to access each property and connection of an object from the Graph API reference documentation.
Page impersonation

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.
Authenticating as an Application

To make administrative calls that do not require an active user (for example, retrieving analytics data or test users) you need to obtain an access token for your application. Read more about how to get an application access token here.

Reading

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.
Selection

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.
Pictures

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/750068429/picture"/>

The same URL pattern works for all objects in the graph:

* People: http://graph.facebook.com/750068429/picture
* Events: http://graph.facebook.com/331218348435/picture
* Groups: http://graph.facebook.com/69048030774/picture
* Pages: http://graph.facebook.com/DoloresPark/picture
* Applications: http://graph.facebook.com/2318966938/picture
* Photo Albums: http://graph.facebook.com/platform/picture

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/750068429/picture?type=large.
Paging

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=3
* until, since (a unix timestamp or any date accepted by strtotime): https://graph.facebook.com/search?until=yesterday&q=orange

Introspection

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

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.

Searching

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:

* All public posts: https://graph.facebook.com/search?q=watermelon&type=post
* People: https://graph.facebook.com/search?q=mark&type=user
* Pages: https://graph.facebook.com/search?q=platform&type=page
* Events: https://graph.facebook.com/search?q=conference&type=event
* Groups: https://graph.facebook.com/search?q=programming&type=group
* Places: https://graph.facebook.com/search?q=coffee&type=place&center=37.76,122.4...
* Checkins: https://graph.facebook.com/search?type=checkin

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:

* News Feed: https://graph.facebook.com/me/home?q=facebook

Publishing

You can publish to the Facebook graph by issuing HTTP POST requests to the appropriate connection URLs, using an access token on behalf of the user or an application access token (for Open Graph Pages). 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 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	create a new post on 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
/PROFILE_ID/checkins	create a checkin at a location represented by a page	coordinates, place, message

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

Deleting

You can delete objects in the graph by issuing HTTP DELETE requests to the object URLs, i.e,

DELETE <a href="https://graph.facebook.com/ID?access_token=" title="https://graph.facebook.com/ID?access_token=">https://graph.facebook.com/ID?access_token=</a>... 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).

Analytics

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 application 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.

Forum

User login

Facebook Graph API Overview