Graph API Version

User Photos

Photos for a person.

Reading

Photos the person is tagged in or has uploaded

Uploaded Photos

By default reading from the photos edge includes all photos a person has been tagged in.

When you read a person's Photos you can also include an optional type parameter with the value uploaded to get only the list of photos that a person has uploaded:

GET /{user-id}/photos?type=uploaded

You can also use this form to add the type, but the type=uploaded form is preferred:

GET /{user-id}/photos/uploaded

Permissions

  • Any valid access token for any photo with public privacy settings.
  • For any photos uploaded by someone, and any photos in which they have been tagged - A user access token for that person with user_photos permission.
Graph API Explorer
GET /v2.7/{user-id}/photos HTTP/1.1
Host: graph.facebook.com
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'GET',
  '/{user-id}/photos'
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/{user-id}/photos",
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/{user-id}/photos",
    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:@"/{user-id}/photos"
                                      parameters:params
                                      HTTPMethod:@"GET"];
[request startWithCompletionHandler:^(FBSDKGraphRequestConnection *connection,
                                      id result,
                                      NSError *error) {
    // Handle the result
}];

Parameters

NameDescription
type
enum{tagged, uploaded}
Default value: tagged

Allows you to query which type of photos to return

Fields

Reading from this edge will return a JSON formatted result:

{ "data": [], "paging": {} }

data

A list of Photo nodes.

paging

For more details about pagination, see the Graph API guide.

Validation Rules

ErrorDescription
100Invalid parameter

Creating

Uploading Photos

There are two separate ways of publishing photos to Facebook:

1: Attach the photo as multipart/form-data. The name of the object doesn't matter, but historically people have used source as the parameter name for the photo. How this works depends on the SDK you happen to be using to do the post.

2: Use a photo that is already on the internet by publishing using the url parameter:

POST /v2.7/me/photos HTTP/1.1
Host: graph.facebook.com

url=%7Bimage-url%7D
/* PHP SDK v5.0.0 */
/* make the API call */
$request = new FacebookRequest(
  $session,
  'POST',
  '/me/photos',
  array (
    'url' => '{image-url}',
  )
);
$response = $request->execute();
$graphObject = $response->getGraphObject();
/* handle the result */
/* make the API call */
FB.api(
    "/me/photos",
    "POST",
    {
        "url": "{image-url}"
    },
    function (response) {
      if (response && !response.error) {
        /* handle the result */
      }
    }
);
Bundle params = new Bundle();
params.putString("url", "{image-url}");
/* make the API call */
new GraphRequest(
    AccessToken.getCurrentAccessToken(),
    "/me/photos",
    params,
    HttpMethod.POST,
    new GraphRequest.Callback() {
        public void onCompleted(GraphResponse response) {
            /* handle the result */
        }
    }
).executeAsync();
FBSDKSharePhotoContent *content = [[FBSDKSharePhotoContent alloc] init];
// image is a UIImage.
content.photos = @[[FBSDKSharePhoto photoWithImage:image userGenerated:YES]];
[FBSDKShareAPI shareWithContent:content delegate:self];

There is no way to publish more than one photo in the same graph API call.

Permissions

  • A user access token with publish_actions permission can be used to publish new photos.
You can make a POST request to photos edge from the following paths:
When posting to this edge, a Photo will be created.

Parameters

NameDescription
aid
string

Legacy album ID. Deprecated

Deprecated
allow_spherical_photo
boolean
Default value: false

Indicates that we should allow this photo to be treated as a spherical photo. This will not change the behavior unless the server is able to interpret the photo as spherical, such as via Photosphere XMP metadata. Regular non-spherical photos will still be treated as regular photos even if this parameter is true.

application_id
non-empty string

iTunes App ID. This is used by the native Share dialog that's part of iOS

audience_exp
boolean
Default value: false

Audience exp

backdated_time
datetime

A user-specified creation time for this photo

backdated_time_granularity
enum{year, month, day, hour, min, none}
Default value: none

Use only the part of the backdated_time parameter to the specified granularity

caption
UTF-8 string

The description of the photo

Supports Emoji
composer_session_id
string

Composer session ID

feed_targeting
feed target

Object that controls News Feed targeting for this post. Anyone in these groups will be more likely to see this post. People not in these groups will be less likely to see this post, but may still see it anyway. Any of the targeting fields shown here can be used, but none are required. feed_targeting applies to Pages only.

countries
list<string>

Values for targeted countries. You can specify up to 25 countries. Use ISO 3166 format codes.

regions
list<unsigned int32>

Values for targeted regions. Use type of adregion to find Targeting Options and use the returned key to specify. For example:

search/?type=adregion&q=California
cities
list<unsigned int32>

Values for targeted cities. Use type of adcity to find Targeting Options and use the returned key to specify.

zipcodes
list<string>
locales
list<string>

Values for targeted locales. Use type of adlocale to find Targeting Options and use the returned key to specify.

age_min
unsigned int32

Must be 13 or higher. Default is 0.

age_max
unsigned int32

Maximum age.

genders
list<unsigned int32>

Target specific genders. 1 targets all male viewers and 2 females. Default is to target both.

college_years
list<unsigned int32>

Array of integers. Represent graduation years from college.

education_statuses
list<unsigned int32>

Array of integers which represent current educational status. Use 1 for high school, 2 for undergraduate, and 3 for alum (or localized equivalents).

interested_in
list<unsigned int32>

Indicates targeting based on the 'interested in' field of the user profile. You can specify an integer of 1 to indicate male, 2 indicates female. Default is all types. Please note 'interested in' targeting is not available in France due to local laws.

relationship_statuses
list<unsigned int32>

Array of integers for targeting based on relationship status. Use 1 for single, 2 for 'in a relationship', 3 for married, and 4 for engaged. Default is all types.

interests
list<unsigned int32>

One or more IDs of pages to target fans of pages.Use type of page to get possible IDs as find Targeting Options and use the returned id to specify.

relevant_until
unsigned int32

Specify time when story becomes irrelevant to show.

full_res_is_coming_later
boolean
Default value: false

Full res is coming later

is_explicit_location
boolean

Is this an explicit location?

is_explicit_place
boolean

If set to true, the tag is a place, not a person

manual_privacy
boolean
Default value: false

Manual privacy

message
UTF-8 string

Deprecated. Please use the caption param instead.

DeprecatedSupports Emoji
name
UTF-8 string

Deprecated. Please use the caption param instead.

DeprecatedSupports Emoji
no_story
boolean

If set to true, this will suppress the News Feed story that is automatically generated on a profile when people upload a photo using your app. Useful for adding old photos where you may not want to generate a story

offline_id
unsigned int32
Default value: 0

Offline ID

og_action_type_id
numeric string or integer

The Open Graph action type

og_icon_id
numeric string or integer

The Open Graph icon

og_object_id
OG object ID or URL string

The Open Graph object ID

og_phrase
string

The Open Graph phrase

og_set_profile_badge
boolean
Default value: false

Flag to set if the post should create a profile badge

og_suggestion_mechanism
string

The Open Graph suggestion

place
place tag

Page ID of a place associated with the photo

privacy
Privacy Parameter

Determines the privacy settings of the photo. If not supplied, this defaults to the privacy level granted to the app in the Login dialog. This field cannot be used to set a more open privacy setting than the one granted

profile_id
int

Deprecated. Use target_id instead

Deprecated
published
boolean
Default value: true

Set to false if you don't want the photo to be published immediately

qn
string

Photos waterfall ID

scheduled_publish_time
unsigned int32

Time at which an unpublished post should be published. Applies to Pages only

spherical_metadata
JSON object

A set of params describing an uploaded spherical photo. This field is not required; if it is not present we will try to generate spherical metadata from the metadata embedded in the image. If it is present, it takes precedence over any embedded metadata. See Google Photo Sphere spec for more info on the meaning of the params: https://developers.google.com/streetview/spherical-metadata

ProjectionType
string
Required
CroppedAreaImageWidthPixels
integer
Required
CroppedAreaImageHeightPixels
integer
Required
FullPanoWidthPixels
integer
Required
FullPanoHeightPixels
integer
Required
CroppedAreaLeftPixels
integer
Required
CroppedAreaTopPixels
integer
Required
PoseHeadingDegrees
float
PosePitchDegrees
float
PoseRollDegrees
float
InitialViewHeadingDegrees
float
InitialViewPitchDegrees
float
InitialViewRollDegrees
float
PreProcessCropLeftPixels
integer
PreProcessCropRightPixels
integer
sponsor_id
numeric string or integer

Facebook Page id that is tagged as sponsor in the photo post

tags
list<Object>

Tags on this photo

x
float

The x-axis offset for the tag

y
float

The y-axis offset for the tag

tag_uid
int

The user_id of the tagged person

tag_text
string

Text associated with the tag

target_id
int

Don't use this. Specifying a target_id allows you to post the photo to an object that's not the user in the access token. It only works when posting directly to the /photos endpoint. Instead of using this parameter you should be using the edge on an object directly, like /page/photos.

targeting
target

Allows you to target posts to specific audiences. Applies to Pages only

countries
list<string>

Values for targeted countries. You can specify up to 25 countries. Use ISO 3166 format codes.

regions
list<unsigned int32>

Values for targeted regions. Use type of adregion to find Targeting Options and use the returned key to specify. For example:

search/?type=adregion&q=California
cities
list<unsigned int32>

Values for targeted cities. Use type of adcity to find Targeting Options and use the returned key to specify.

zipcodes
list<string>

Values for targeted zipcodes. Use type of adzipcode to find Targeting Options and use the returned key to specify.

locales
list<string>

Values for targeted locales. Use type of adlocale to find Targeting Options and use the returned key to specify.

excluded_countries
list<string>

Values for excluded countries. You can specify up to 25 countries. Use ISO 3166 format codes.

excluded_regions
list<unsigned int32>

Values for excluded regions. Use type of adregion and list of GLOBAL to find Targeting Options and use the returned key to specify. For example:

search/?type=adregion&q=California&list=GLOBAL
excluded_cities
list<unsigned int32>

Values for excluded cities. Use type of adcity to find Targeting Options and use the returned key to specify.

excluded_zipcodes
list<string>

Values for excluded zipcodes. Use type of adzipcode to find Targeting Options and use the returned key to specify.

excluded_locales
list<string>
timezones
list<unsigned int32>

ID for the timezone. See here.

age_min
unsigned int32

Must be 13 or higher. Default is 0.

age_max
unsigned int32

Maximum age.

genders
list<unsigned int32>

Target specific genders. 1 targets all male viewers and 2 females. Default is to target both.

url
string

The URL of a photo that is already uploaded to the Internet. You must specify this or a file attachment

Return Type

Struct {
id: numeric string,
post_id: token with structure: Post ID,
}

Validation Rules

ErrorDescription
100Invalid parameter
2010Photos calls have been temporarily disabled for this application
240Desktop applications cannot call this function for other users
121Invalid photo id
506Duplicate status message
122Invalid vault image id
123Invalid sync object uuid
120Invalid album id

Updating

You can't perform this operation on this endpoint.

Deleting

You can't perform this operation on this endpoint.