Graph API Explorer Guide

This guide demonstrates the basics of getting information from Facebook and posting information to Facebook using the Graph API.

Prerequisites


Overview

The Graph API Explorer is an app that allows you to explore Facebook's Social Graph. Get data (User information, comments, photos), post to User Timelines and Pages, and test with your app. Get code examples of actions you have tested.


Action Overview

All requests you perform will require three things:


Reading Data from Facebook

The First Query

When you open the Graph API Explorer it loads with the latest version of the Graph API and a default GET request:

GET /me?fields=id,name

This query searches me, the User node, for your Facebook User id and name. This information is public; part of your public profile.

To run this GET request, select a User acccess token from the Get Token dropdown.

Click the Get Access Token button without checking any boxes (more on adding permissions in the next example). An access token's default permissions give access to public profile information.

Continue as You and click Submit. The explorer returns the response in the pane below the query.


More User Data

In the first example you retrieved public data about you. Now, get private data about you such as your birthday and about me information.

Access Token: Because you are asking for private information you will need to get a User access token with select permissions. Click Get Token and select user_about_me and user_birthday in the Select Permissions popup.

FB Login is required to get access tokens. When sending your app for review only include those permissions which are required for your app. Asking for extra permissions will result in a denial.

Click Get Access Token and Continue as You.

Add New Fields: If you're new to the Graph API you may not be familiar with the User node fields. Click on the + of the + Search for a field in the Node panel to see and select new fields.

Once you have learned some of the fields you can add them directly to the request path.

The request path is set to: GET /me?fields=id,name,about,birthday

Submit your request.

If you haven't filled out the About Me field on Facebook, the field will be grayed-out in the Node panel and no "about" line will be returned in the response.

Want to see a list of fields available to a node? Look at a node's metadata from the explorer.

Set your request to: GET /me?metadata=1

This will return the field name, description, and type.

Getting a Code Sample

You've tested the code above and it returns the results you need. Use the Get Code button below the response pane for Android, iOS, JavaScript, PHP, or cURL example code.

Inserting this example code directly into yours will not result in functional code. Use these code examples to help build the code you need for your app.


Get Photo Albums

Let's request your photo albums. Add the albums field to your request. In this example we've removed the about, birthday, id, and name fields.

Set your request to: GET /me?fields=albums

Hit Submit.

Uh oh, you only received id information and the albums field in the node panel is grayed out. This can happen when no data is available, the user does not have this information filled out, or a permissions issue when your access token doesn't contain the needed permissions to access this data. Fortunately, the explorer may be able to help. Click the 1 Debug Message (Show) link above the response pane to see why this data might be missing.

You need a new access token with a new permission, user_photos. Click Get Token and get a user access token. Notice the permissions from your last request are still selected. It is recommended that you only select the permissions needed for your request. In this example, you only need user_photos so Clear the permissions and select user_photos. Now rerunning the request returns your photo albums.

If you are in doubt about the level of permissions or type of access token, click the circle icon in the access token box. This box shows the app making the request, the user making the request, the validity of the token, the expiration time, and the scope.

Pagination

While this request has limited the number of items shown in the response pane you can still access the other albums using cursor-based pagination. Notice at the bottom of the request we have a field called paging with a cursors and next field. Cursors are used to mark the beginning and end of the information returned. Clicking the link given in the next field shows the next 5 albums.

By clicking the next and previous links you can view all the albums in smaller chunks without having to run multiple requests. Be careful, cursors will change over time so don't rely on these in your code.

Let's find photos during a certain time period using time-based pagination. For this exercise get photos that have been posted to your Newsfeed, either by you or your friends, or photos you have been tagged in and set the query to search from Septemeber 1, 2017 (posted since 1504224000) to September 30, 2017 (posted until 1506729600). Because photos is an edge the request syntax changes.

Set your request to: GET /me/photos?since=1504224000&until=1506729600

Your user access token is still valid since it has user_photos permission.

Only the photos from the month of September are returned. Learn more about pagination.


Field Expansion

Applying a Limit

If you've been on Facebook for a long time, you might have so many albums it's a bit too much information. Let's limit the number of albums returned to 5. To do this add .limit(5) to the query.

Set your request to: GET /me?fields=albums.limit(5)

Nested Requests

As you know albums are made of many photos each with its own metadata. Photos will have an id, created_time, and sometimes a name. Use field expansion to get this data but again let's limit to 2 photos per album to keep the items returned to a minimum.

Set your request to: GET me?fields=albums{name,photos}

The access token you used in the last query should have the needed user_photo permissions so all you should need to do is submit the query.

Again, you'll see cursor-based pagination since many of the albums contain many photos. You can use the cursor links to view more photos of an album.

Let's get crazy and add limits to both albums and photos. Try modifying the request path to return only 5 albums and 2 photos from each album. Remember from the above example, modifiers will be next to the object they are modifying, i.e., album.limit(5).


Creating Data on Facebook

Post a Comment to your Timeline

Access Token: You will need to give the explorer permission to publish to your Timeline. Click Get Token and select the publish_actions permission.

Select the level of privacy of this post: Public, Friends, Only me, Custom.

Switch from GET to POST in the request path.

  • Set your request to: POST /me/feed

  • Click the Add a Field link below the query box.

    • Add the message field with a value of Hello from the Graph API Explorer!

The response will be the post_id. The post_id consists of your user_id appended with an underscore and integer.

Check the update in the explorer. Click the post_id from the response which will move it to the query box. Switch to GET and get a new access token with user_posts permissions. The response will be the created_time, the message, and post_id.

Check the update in your Newsfeed. The update will show the message as well as the app that was used to post it.

Remember, you can get the code of this session to use within your code.


Post a Photo

For this exercise you will need an image url with an image that is less than 4 MB and is a JPG, PNG, GIF or TIFF files.

Set your request to: POST /me/photos where me is your user_id.

Add the url field and value. I'm also adding caption for fun.

Access token with publish_actions permissions.

The request looks like: POST me/photos url=https://www.facebook.com/images/fb_icon_325x325.png caption=Having fun with the Graph API!

The response returns the photo_id and the post_id. Check it out in your Newsfeed as well as well as the explorer.


Post a Comment on a Page

Page ID: Using the /me/accounts request from above to get the page_id of the page you want to comment on. Click on the page id in the response to move the id to the request path box.

Access Token: For this request you will need a page access token. Click Get Token, get a user access token and select the publish_actions permission. Now, use the Get Token dropdown to select the Page you want the access token to apply to.

Switch from GET to POST in the request box.

Set your request to: POST /page_id/feed

Add your message:

The response returned is the page post_id.


Updating Facebook Infomation

Let's update the first post we sent to your Newsfeed.

Access Token: Get an access token with publish_actions permissions if you don't already have one.

Get the post_id: From that first post response, click on the id link. This moves the id to the request path and automatically runs a GET request.

Change to POST: Add the message field and type a new message.

If the post was updated a successful response will be shown.

In most instances the app performing the update must be the app that created the object to be updated.


Deleting from Facebook

Let's say you have an app that allows users to delete posts from their Timeline. Test this app in the explorer.

First, select the app to perform the deletion from the Application dropdown. In this example we are using the Graph API Explorer.

Find the post to be deleted. Create a get request with a user access token with user_posts permissions.

Next, click on the post_id returned in the request to move it to the request path box. Get a new user access token with publish_actions and change the action to DELETE. Submit the request.

The response:

In most instances the app performing the deletion must be the app that created the object to be deleted.


Pages

To run these examples you will need to own or have a role on a Facebook page. If you don't feel free to create one.

Listing Pages

Let's list all the pages you own or on which you have a role. For this request you will need a user access token with manage_page or pages_show_list permissions. Then, you add the accounts edge to the me request.

Set your request to: GET /me/accounts

The response will include information about the page category, the name of the page, the page id, and the permissions you have on that page.

Page count

Let's get a count of all the objects on the accounts edge.

Set your request to: GET /me/accounts?summary=total_count

After clicking submit, scroll down to the bottom of the response pane to view the count. Uh oh, the Debug Message appeared even though the response shows the requested data.

Remember, some data will not be returned even if you have the needed permissions. If the data involves another person, their privacy settings take precedence over access tokens.

Post to a Page

To post to a page's feed, you will need a page access token with either publish_actions permission, or manage_pages and publish_pages as an admin with sufficient administrative permission. To get a page access token with the needed permissions first select Get User Access Token and select manage_pages and publish_pages. Then, from the Get Token dropdown select the page where you want to post. This gives you a page access token for that page.

Click on the page id from the previous request. This moves the id to the request path.

Set your request to: POST /page_id/feed

Add a Field where message has a value of Hello Page!. Submit the request. A successful response shows the post id of the message posted to the page.

Click on the Access Token circle icon to see information about the page access token.