This document refers to a feature that was removed after Graph API v3.2.
Graph API Version

/{photo-id}/tags

The list of people tagged in a photo.

Reading

Graph API Explorer
GET /v6.0/{photo-id}/tags HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->get(
    '/{photo-id}/tags',
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{photo-id}/tags",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{photo-id}/tags",
    null,
    HttpMethod.GET,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{photo-id}/tags"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

  • A user access token with user_photos permission is required to see all photos that person is tagged in or has uploaded.

Fields

An array of tags:

Property NameDescriptionType

id

The ID identifying the person who was tagged.

string

name

The name of the person who was tagged.

string

created_time

The time the tags were created.

datetime

tagging_user

The person who added the tag. This will only be returned when that person is also using the app.

User

x

The x coordinate in the photo where the tag is, as a percentage offset.

float

y

The y coordinate in the photo where the tag is, as a percentage offset.

float

Publishing

You can add tags to a photo using this edge:

POST /v6.0/{photo-id}/tags HTTP/1.1
Host: graph.facebook.com

tags=%5B%7B%27tag_text%27%3A+%27Testing%27%7D%5D
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/{photo-id}/tags',
    array (
      'tags' => '[{\'tag_text\': \'Testing\'}]',
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{photo-id}/tags",
    "POST",
    {
        "tags": "[{'tag_text': 'Testing'}]"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("tags", "[{'tag_text': 'Testing'}]");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{photo-id}/tags",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"tags": @"[{'tag_text': 'Testing'}]",
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{photo-id}/tags"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

  • A user access token with publish_actions permission can be used to publish new tags.
  • The person tagged may have Tag Review enabled for their profile - if so, the tag will not appear until they confirm it manually.

Fields

NameDescriptionType

tags

A list of tagged people, or tagged text.

object[]

tag_uid

ID of the user to tag. Either this or tag_text are required.

string

tag_text

A text string to tag. Either this or tag_uid are required.

string

x

x coordinate of each tag, as a percentage offset from the left edge of the picture.

int

y

y coordinate of each tag, as a percentage offset from the top edge of the picture.

int

Response

If successful:

{
  "success": true
}

Otherwise a relevant error message will be returned.

Deleting

You cannot delete tags via the Graph API.

Updating

You can update the location of existing tags using this edge:

POST /v6.0/{photo-id}/tags HTTP/1.1
Host: graph.facebook.com

to=1234&x=70.55&y=50
/* PHP SDK v5.0.0 */
/* make the API call */
try {
  // Returns a `Facebook\FacebookResponse` object
  $response = $fb->post(
    '/{photo-id}/tags',
    array (
      'to' => 1234,
      'x' => 70.55,
      'y' => 50,
    ),
    '{access-token}'
  );
} catch(Facebook\Exceptions\FacebookResponseException $e) {
  echo 'Graph returned an error: ' . $e->getMessage();
  exit;
} catch(Facebook\Exceptions\FacebookSDKException $e) {
  echo 'Facebook SDK returned an error: ' . $e->getMessage();
  exit;
}
$graphNode = $response->getGraphNode();
/* handle the result */
/* make the API call */
FB.api(
    "/{photo-id}/tags",
    "POST",
    {
        "to": 1234,
        "x": 70.55,
        "y": 50
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putInt("to", 1234);
params.putDouble("x", 70.55);
params.putInt("y", 50);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{photo-id}/tags",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
// For more complex open graph stories, use `FBSDKShareAPI`
// with `FBSDKShareOpenGraphContent`
NSDictionary *params = @{
  @"to": @1234,
  @"x": @70.55,
  @"y": @50,
};
/* make the API call */
FBSDKGraphRequest *request = [[FBSDKGraphRequest alloc]
                               initWithGraphPath:@"/{photo-id}/tags"
                                      parameters:params
                                      HTTPMethod:@"POST"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Permissions

  • A user access token with publish_actions permission can be used to update tags.

Fields

NameDescriptionType

to

ID of the user whose tag you want to update.

string

x

x coordinate of tag, as a percentage offset from the left edge of the picture.

float

y

y coordinate of tag, as a percentage offset from the top edge of the picture.

float

Response

If successful:

{
  "success": true
}

Otherwise a relevant error message will be returned.