API

From Facebook Developer Wiki

Jump to: navigation, search

The article contains extended documentation about the Facebook API. With the API, you can add social context to your application by utilizing profile, friend, Page, group, photo, and event data.

Contents

REST Interface

The API uses a REST-like interface. This means that our Facebook method calls are made over the internet by sending HTTP GET or POST requests to the Facebook API REST server . Nearly any computer language can be used to communicate over HTTP with the REST server.

Note: If you manually form your HTTP POST requests to Facebook, you must include the request data in the POST body. In addition, you should include a Content-Type: header of application/x-www-form-urlencoded.

API Results and Localization

API results get returned in localized formatting, when such formats exist (for example, the user's gender). Namely, all requests made through restserver.php will obey the following:

  1. If the current user is browsing Facebook in a non-US English locale, then the results of the API queries will return the user's locale only if your application has been listed as "published" from the Translations Admin Panel (http://www.facebook.com/translations/admin/dashboard.php?app=<appID>), or if they are allowed to see translations in progress for your application (see Translating Platform Applications for details). Otherwise, it will be returned with US English formatting.
  2. If the user is in the US English locale, results will be returned as expected.
  3. Both 1+2 can be optionally overridden, by adding the &locale parameter to either the GET or POST params for a restserver.php request. For a list of valid locales, please check Facebook Locales.

API Methods

admin.getAllocation
Returns the current allocation limit for your application for the specified integration point.
admin.getAppProperties
Returns values of properties for your applications from the Facebook Developer application.
admin.getMetrics
Returns specified metrics for your application, given a time period.
admin.getRestrictionInfo
Returns the demographic restrictions for the application.
admin.setAppProperties
Sets values for properties for your applications in the Facebook Developer application.
admin.setRestrictionInfo
Sets the demographic restrictions for the application.
admin.banUsers
Prevents users from accessing an application's canvas page and its forums.
admin.unbanUsers
Unbans users previously banned with admin.banUsers.
admin.getBannedUsers
Returns the list of users who have been banned from the application.
application.getPublicInfo
Returns public information about a given application (not necessarily your own).
auth.createToken
Creates an auth_token to be passed in as a parameter to login.php and then to auth.getSession after the user has logged in.
auth.expireSession
Expires the session indicated in the API call, for your application.
auth.getSession
Returns the session key bound to an auth_token, as returned by auth.createToken or in the callback URL.
auth.promoteSession
Returns a temporary session secret associated to the current existing session, for use in a client-side component to an application.
auth.revokeAuthorization
If this method is called for the logged in user, then no further API calls can be made on that user's behalf until the user decides to authorize the application again.
auth.revokeExtendedPermission
Removes a specific extended permission that a user explicitly granted to your application.
batch.run
Execute a list of individual API calls in a single batch.
comments.add (BETA)
Adds a comment for a given xid on behalf of a user. Calls with a session secret may only act on behalf of the session user.
comments.get
Returns all comments for a given xid posted through fb:comments. This method is a wrapper for the FQL query on the comment FQL table.
comments.remove (BETA)
Removes a comment for a given xid by comment_id. Calls with a session secret may only act on behalf of the session user.
connect.getUnconnectedFriendsCount
Returns the number of friends of the current user who have accounts on your site, but have not yet connected their accounts. (for [{Facebook Connect]]).
connect.registerUsers
Creates an association between an existing user account on your site and that user's Facebook account, provided the user has not connected accounts before (for Facebook Connect).
connect.unregisterUsers
Unregisters a previously registered account (using connect.registerUsers). You should call this method if the user deletes his or her account on your site. (for Facebook Connect).
data.getCookies (BETA)
Returns all cookies for a given user and application.
data.setCookie (BETA)
Sets a cookie for a given user and application.
events.cancel
Cancels an event. The application must be an admin of the event.
events.create
Creates an event on behalf of the user if the application has an active session; otherwise it creates an event on behalf of the application.
events.edit
Edits an existing event. The application must be an admin of the event.
events.get
Returns all visible events according to the filters specified.
events.getMembers
Returns membership list data associated with an event.
events.invite
Lets your application invite users to an event.
events.rsvp
Sets the attendance option for the current user.
fbml.deleteCustomTags
Deletes one or more custom tags you previously registered for the calling application with fbml.registerCustomTags.
fbml.getCustomTags
Returns the custom tag definitions for tags that were previously defined using fbml.registerCustomTags.
fbml.refreshImgSrc
Fetches and re-caches the image stored at the given URL.
fbml.refreshRefUrl
Fetches and re-caches the content stored at the given URL.
fbml.registerCustomTags
Registers custom tags you can include in your that applications' FBML markup. Custom tags consist of FBML snippets that are rendered during parse time on the containing page that references the custom tag.
fbml.setRefHandle
Associates a given "handle" with FBML markup so that the handle can be used within the fb:ref FBML tag.
fql.query
Evaluates an FQL (Facebook Query Language) query.
fql.multiquery
Evaluates a series of FQL (Facebook Query Language) queries in one call and returns the data at one time.
friends.areFriends
Returns whether or not each pair of specified users is friends with each other.
friends.get
Returns the identifiers for the current user's Facebook friends.
friends.getAppUsers
Returns the identifiers for the current user's Facebook friends who have authorized the specific calling application.
friends.getLists
Returns the identifiers for the current user's Facebook friend lists.
friends.getMutualFriends
Returns the identifiers for the requested users' Mutual Facebook friends.
groups.get
Returns all visible groups according to the filters specified.
groups.getMembers
Returns membership list data associated with a group.
intl.getTranslations (BETA)
Returns an array of strings from your application that you submitted for translation. This call returns the original native strings, the best (or all) translations of native strings into a given locale, whether the string has been approved, and by whom.
intl.uploadNativeStrings
Lets you insert text strings into the Facebook Translations database so they can be translated.
links.get (BETA)
Returns all links the user has posted on their profile through your application.
links.post (BETA)
Lets a user post a link on their Wall through your application.
liveMessage.send (BETA)
Sends a "message" directly to a user's browser, which can be handled in FBJS.
message.getThreadsInFolder (BETA)
Returns all of a user's messages and threads from the Inbox.
notes.create (BETA)
Lets a user write a Facebook note through your application.
notes.delete (BETA)
Lets a user delete a Facebook note that was written through your application.
notes.edit (BETA)
Lets a user edit a Facebook note through your application.
notes.get (BETA)
Returns a list of all of the visible notes written by the specified user.
notifications.get
Returns information on outstanding Facebook notifications for current session user.
notifications.getList (BETA)
Returns all the current session user's notifications, as well as data for the applications that generated those notifications.
notifications.markRead (BETA)
Marks one or more notifications as read.
notifications.send
Sends a notification to a set of users.
notifications.sendEmail
Sends an email to the specified users who have the application.
pages.getInfo
Returns all visible pages to the filters specified.
pages.isAdmin
Checks whether the logged-in user is the admin for a given Page.
pages.isAppAdded
Checks whether the Page has added the application.
pages.isFan
Checks whether a user is a fan of a given Page.
photos.addTag
Adds a tag with the given information to a photo.
photos.createAlbum
Creates and returns a new album owned by the current session user.
photos.get
Returns all visible photos according to the filters specified.
photos.getAlbums
Returns metadata about all of the photo albums uploaded by the specified user.
photos.getTags
Returns the set of user tags on all photos specified.
photos.upload
Uploads a photo owned by the current session user and returns the new photo.
profile.getFBML
Gets the FBML that is currently set for a user's profile.
profile.getInfo
Returns the specified user's application info section for the calling application.
profile.getInfoOptions
Returns the options associated with the specified field for an application info section.
profile.setFBML
Sets the FBML for a user's profile, including the content for both the profile box and the profile actions.
profile.setInfo
Configures an application info section that the specified user can install on the Info tab of her profile.
profile.setInfoOptions
Specifies the objects for a field for an application info section.
sms.canSend
Determines whether a user has enabled SMS for the application. (Mobile applications only)
sms.send
Sends a given text message (SMS) to the user. (Mobile applications only)
status.get (BETA)
Returns the user's current and most recent statuses.
status.set (BETA)
Updates a user's Facebook status through your application. This is a streamlined version of users.setStatus.
stream.addComment (BETA)
This method adds a comment to a post that was already published to a user's Wall.
stream.addLike (BETA)
This method lets a user add a like to any post the user can see. A user can like each post only once.
stream.get (BETA)
This method returns an object (in JSON-encoded or XML format) that contains the stream from the perspective of a specific viewer -- a user or a Facebook Page.
stream.getComments (BETA)
This method returns all comments associated with a post in a user's stream. This method returns comments only if the user who owns the post (that is, the user published the post to his or her profile) has authorized your application.
stream.getFilters (BETA)
This method returns any filters a user has specified for his or her home page stream.
stream.publish (BETA)
This method publishes a post into the stream on the user's Wall and News Feed. This post also appears in the user's friends' streams (their News Feeds).
stream.remove (BETA)
This method removes a post from a user's Wall. The post also gets removed from the user's and the user's friends' News Feeds. Your application may only remove posts that were created through it.
stream.removeComment (BETA)
This method removes a comment from a post.
stream.removeLike (BETA)
This method removes a like a user added to a post.
users.getInfo
Returns a wide array of user-specific information for each user identifier passed, limited by the view of the current user.
users.getLoggedInUser
Gets the user ID (uid) associated with the current session.
users.getStandardInfo
Returns an array of user-specific information for use by the application itself.
users.hasAppPermission
Checks whether the user has opted in to an extended application permission.
users.isAppUser
Returns whether the user (either the session user or user specified by UID) has authorized the calling application.
users.isVerified (BETA)
Returns whether the user is a verified Facebook user.
users.setStatus
Updates a user's Facebook status.
video.getUploadLimits (BETA)
Returns the file size and length limits for a video that the current user can upload through your application.
video.upload
Uploads a video owned by the current session user and returns the video.

Additional APIs and Other Documentation

API Categories

External Links

Deprecated API Methods

Admin.getDailyMetrics
This method is deprecated. Please use Admin.getMetrics instead.
fbml.uploadNativeStrings
This method is deprecated. Please use intl.uploadNativeStrings instead.
feed.publishActionOfUser
This method is deprecated. Please use stream.publish, FB.Connect.streamPublish, and Facebook.streamPublish instead.
feed.publishStoryToUser
This method is deprecated. Please use stream.publish, FB.Connect.streamPublish, and Facebook.streamPublish instead.
feed.deactivateTemplateBundleByID
This method is deprecated. Please use stream attachments instead of templates.
feed.getRegisteredTemplateBundleByID
This method is deprecated. Please use stream attachments instead of templates.
feed.getRegisteredTemplateBundles
This method is deprecated. Please use stream attachments instead of templates.
feed.publishTemplatizedAction
This method is deprecated. Please use stream.publish, FB.Connect.streamPublish, and Facebook.streamPublish instead.
feed.publishUserAction
This method is deprecated. Please use stream.publish, FB.Connect.streamPublish, and Facebook.streamPublish instead.
feed.registerTemplateBundle
This method is deprecated. Please use stream attachments instead of templates.
marketplace.createListing
This method is deprecated. Create or modify a listing in Marketplace.
marketplace.getCategories
This method is deprecated. Returns all the Marketplace categories.
marketplace.getListings
This method is deprecated. Return all Marketplace listings either by listing ID or by user.
marketplace.getSubCategories
This method is deprecated. Returns the Marketplace subcategories for a particular category.
marketplace.removeListing
This method is deprecated. Remove a listing from Marketplace.
marketplace.search
This method is deprecated. Search Marketplace for listings filtering by category, subcategory and a query string.
users.isAppAdded
This method is deprecated. Please use users.isAppUser instead.
Retrieved from "http://wiki.developers.facebook.com/index.php/API"
reference