Socialwg/Social API/Facebook API

From W3C Wiki


Facebook API doesn't support all the functionality available from graphic interface. API documentation very often states: "You cannot publish/delete ??? using the Graph API."


Facebook provides tool to explore its Graph API

Nodes, Edges, Fields

The Graph API is named after the idea of a 'social graph' - a representation of the information on Facebook composed of nodes, edges and fields. In some cases node can have field and edge with the same name eg. like which as field stores number of likes and as edge links to array of likes. At the same time an event has attending_count field and attending edge.


Basically "things" such as a User, a Photo, a Page, a Comment.

  • Each node has a unique id, in some cases an ID has another ID as its first half firstId_secondId (eg. comments)
  • Some nodes also have username, which one can use in place of id eg. elf.pavlik, polyeconomy


The connections between those "things", such as a Page's Photos, or a Photo's Comments.

  • Sometimes some edges point to specializations of another edge. for example Group members & admins
  • In other cases it uses two steps edge, for example User events/declined where events itself doesn't point to a node with ID (see examples)
  • Event: picture, attending, maybe, declined, noreply, invited, feed, photos, videos
  • Post: likes, comments, shareposts, insights, attachments
  • Group: members, admins,
  • User: ..., events, events/attending, events/maybe, events/not_replied, events/declined, events/created, ...


Info about those "things", such as the birthday of a User, or the name of a Page

node's ID
node's Facebook URL

elf Pavlik: reminds me of discussions about @id and url in

By default API doesn't return all the fields available for requested node. To select only some of the available fields one can pass them as arguments. It also supports nesting via edges eg.

   ?fields=albums.limit(5){name, photos.limit(2){name, picture, tags.limit(2)}},posts.limit(5)
  • fields: name
  • edges: albums, photos, tags, posts

move to Socialig/Vocabulary_TF

  • rsvp_status: attending, unsure, declined, not_replied
  • backdated_time_granularity(photo): year, month, day, hour, min, none
  • type (album): app, cover, profile, mobile, wall, normal, album
  • auth_referral_default_activity_privacy (app): SELF, EVERYONE, ALL_FRIENDS, NONE
  • auth_referral_response_type (app): code, token
  • list_type (friendlist): close_friends, acquaintances, restricted, user_created, education, work, current_city, family
  • order (object/comments): chronological, ranked
  • filter(object/comments): toplevel, stream
  • price_range(price_range): $ (0-10), $$ (10-30), $$$ (30-50), $$$$ (50+), Unspecified
  • status_type(post): mobile_status_update, created_note, added_photos, added_video, shared_story, created_group, created_event, wall_post, app_created_story, published_story, tagged_in_photo, approved_friend
  • type (post): link, status, photo, video

Collections and paging

HTTP verbs

  • GET - read
  • POST - create and update
  • DELETE - delete

To support clients that do not support all HTTP methods, you can alternatively issue a POST request to an endpoint with the additional argument method=delete to override the HTTP method.


To get this information, add metadata=1 to the Graph API request. It includes connections, fields and type

    "name": {node-name},
    "metadata": {
       "connections": {
          "feed": "",
          "picture": "",
       "fields": [
           "name": "id",
           "description": "The user's Facebook ID. No `access_token` required. `string`."
       "type": "user"

In some cases it returns more information then documented on !!! eg. /{event-id}/admins


A profile can be a User, a Page, a Group, an Event. The profile object is used within the Graph API to refer to the generic type that includes all of these other objects. The individual reference docs for each profile type should be used instead.
A user represents a person on Facebook.
Friend List
A friend list - an object which refers to a grouping of friends created by someone or generated automatically for someone (such as the "Close Friends" or "Acquaintances" lists).
Represents a Facebook group.
This represents a Facebook Page.
Represents a Facebook event.
An individual entry in a profile's feed. The profile could be a user, page, app, or group.
This represents a milestone on a Facebook Page.
A status message in a profile's feed.
A link shared on a wall.
Represents an individual photo on Facebook.
Represents a photo album.
An individual video on Facebook.
A comment can be made on various types of content on Facebook. Most Graph API nodes have a /comments edge that lists all the comments on that object.
An individual message in the Facebook messaging system.
A Facebook Messages conversation between a person and a Facebook Page.
A Facebook app. Apps are created, maintained and deleted in the app dashboard.

Page Categories

Page can have one category and multiple subcategories. From one of those groupings:

  • Local Busines or Place
  • Company, Organization or Institution
  • Brand or Product
  • Artist, Band or Public Figure
  • Entertainment
  • Cause or Community

detailed categories on Socialig/Research/Facebook/Categories


actions (object[])
The action links attached to the post. Action links are any other links shown below the feed story beside Like and Comment.
name (string)
The name or label of the action link.
link (string)
The URL of the action link itself.


     "id": "SOME_FB_ID", 
     "actions": [
         "name": "Comment", 
         "link": ""
         "name": "Like", 
         "link": ""

NOTE: somehow actions seem not to provide proper URI to perform them, for example above actual endpoints:

  • like: POST
  • comment: POST


available search types: user, page, event, group, place, location, placetopic, ad_*

TODO: find out about Facebook Graph Search



Common Scenarios

Are two people Facebook friends?

 /{user-a-id}/friends/{user-b-id} - this API Read modifier will let you check via API.

Does someone like a Facebook Page?

 /{user-id}/likes/{page-id} - this API Read modifier will let you check via API.

Publishing new Status Updates

 /{user-id}/feed for people on Facebook.
 /{page-id}/feed for Facebook Pages.

Uploading Photos and Creating Photo Albums

 /{user-id}/albums to create empty photo albums for people.
 /{user-id}/photos to add individual photos for people.
 /{page-id}/albums to create empty photo albums for Facebook Pages.
 /{page-id}/photos to add individual photos for Facebook Pages.
 /{album-id}/photos to add photos to an existing album for people or for Pages.

Sharing Links

 /{user-id}/feed for people on Facebook, using the link field.
 /{page-id}/feed for Facebook Pages, using the link field.

Responding to Events

 /{event-id}/attending to say the person is attending.
 /{event-id}/maybe to say the person might attend.
 /{event-id}/declined to say the person has declined to attend.

Example JSON

  "message": "Have you ever wondered what other songs used the same chord progression? This is kind of an amazing site that will tell you:",
  "created_time": "2015-09-30T04:59:59+0000",
  "updated_time": "2015-09-30T04:59:59+0000",
  "coordinates": {
  "application": {
    "link": "",
    "name": "",
    "id": "163993483698061"
  "from": {
    "name": "Aaron Parecki",
    "id": "11500459"
  "id": "11500459_10102200453435586",

See Also