Photo

An individual photo as represented in the Graph API.

To read the 'photo' object you need

• any valid access_token if it is public
• user_photos permission to access photos and albums uploaded by the user, and photos in which the user has been tagged
• friends_photos permission to access friends' photos and photos in which the user's friends have been tagged

To publish a 'photo' object you need

• a valid access token
• publish_stream permission

With that granted, you can upload a photo by issuing an HTTP POST request with the photo content and an optional description to one these to Graph API connections:

• https://graph.facebook.com/USER_ID/photos - The photo will be published to an album created for your app. We automatically create an album for your app if it does not already exist. All photos uploaded this way will then be added to this same album.

• https://graph.facebook.com/ALBUM_ID/photos - The photo will be published to a specific, existing photo album, represented by the ALBUM_ID. Regular albums have a size limit of 200 photos. Default application albums currently do not have a size limit, but please adhere to our policies to not abuse this feature.

You can also publish a photo by providing a url param with the photo's URL.

Example

A photo from a Facebook Page album:

https://graph.facebook.com/10151509108346729

---

Fields

The Photo object has the following fields.

Name	Description	Permissions	Returns
id	The photo ID	generic access_token or user_photos or friends_photos	string
from	The profile (user or page) that posted this photo	generic access_token or user_photos or friends_photos	object containing id and name fields
tags	The tagged users and their positions in this photo	generic access_token or user_photos or friends_photos	array of objects, the x and y coordinates are percentages from the left and top edges of the photo, respectively
name	The user provided caption given to this photo - do not include advertising in this field	generic access_token or user_photos or friends_photos	string
name_tags	An array containing an array of objects mentioned in the name field which contain the id, name, and type of each object as well as the offset and length which can be used to match it up with its corresponding string in the name field	generic access_token or user_photos or friends_photos	array
icon	The icon that Facebook displays when photos are published to the Feed	generic access_token or user_photos or friends_photos	string representing a valid URL
picture	The thumbnail-sized source of the photo	generic access_token or user_photos or friends_photos	string representing a valid URL
source	The source image of the photo - currently this can have a maximum width or height of 720px, increasing to 960px on 1st March 2012	generic access_token or user_photos or friends_photos	string representing a valid URL
height	The height of the photo in pixels	generic access_token or user_photos or friends_photos	number
width	The width of the photo in pixels	generic access_token or user_photos or friends_photos	number
images	The 4 different stored representations of the photo	Requires access_token	array of objects, containing height, width, and source fields
link	A link to the photo on Facebook	generic access_token or user_photos or friends_photos	string representing a valid URL
place	Location associated with a Photo, if any	generic access_token or user_photos or friends_photos	object containing id and name of Page associated with this location, and a location field containing geographic information such as latitude, longitude, country, and other fields (fields will vary based on geography and availability of information)
created_time	The time the photo was initially published	generic access_token or user_photos or friends_photos	string containing ISO-8601 date-time
updated_time	The last time the photo or its caption was updated	generic access_token or user_photos or friends_photos	string containing ISO-8601 date-time
position	The position of this photo in the album	generic access_token or user_photos or friends_photos	number

---

Connections

The Photo object has the following connections.

Name	Description	Permissions	Returns
comments	All of the comments on this photo.	any valid access_token or user_photos or friends_photos	array of objects containing id, from, message and created_time fields.
likes	Users who like this photo.	any valid access_token or user_photos or friends_photos	array of objects containing the id and name fields.
picture	The album-sized view of the photo.	any valid access_token or user_photos or friends_photos	HTTP 302 redirect to the URL of the picture
tags	The Users tagged in the photo.	any valid access_token or user_photos or friends_photos	Tags with names and IDs (if available).

comments

Create

You can write to the PHOTO_ID/comments connection to post a comment to the photo by issuing an HTTP POST request with the publish_stream permission and following parameters.

Parameter	Description	Type	Required
message	Comment text	string	yes

If the write is successful, you get the following return.

Name	Description	Type
id	The new comment ID	string

likes

Create

You can like a photo by issuing a HTTP POST request to PHOTO_ID/likes connection with the publish_stream permission. No parameters necessary.

If the write is successful, you get the following return.

Description	Type
If the like succeeded	boolean

Delete

You can unlike an photo by issuing an HTTP DELETE request to the PHOTO_ID/likes connection with the publish_stream permission.

If the delete is successful, you get the following return.

Description	Type
If the unlike succeeded	boolean

tags

Create

You can create a tag on the photo by issuing an HTTP POST request to the tags connection, PHOTO_ID/tags.

Note: This feature is intended to help users tag their friends in real photos. You should not use this feature to encourage users to tag their friends if their friends are not actually in that photo, or to tag friends in composite photos. If your app is found to be encouraging this behavior, your usage of this feature may be disabled.

You can specify which user to tag using two methods: in the URL path as PHOTO_ID/tags/USER_ID, or in a URL parameter as PHOTO_ID/tags?to=USER_ID. To add several tags at once, you can specify a tags property which contains an array of tags like so PHOTO_ID/tags?tags=[{"tag_uid":"1234"}, {"tag_uid":"12345"}]. Currently, you cannot tag a Page in a photo using this API.

Tagging a photo requires the user_photos and publish_stream permissions, publish_stream is optional - if not present, the tag will go through Tag Review of the tagged person if s/he has this privacy setting enabled. Tagging a photo supports the following parameters.

Parameter	Description	Type	Required
to	USER_ID of the User to tag; can also be provided in URL path (see above).	string	One of to or tag_text
tag_text	A text string to tag.	string	One of to or tag_text
x	x coordinate of tag, as a percentage offset from the left edge of the picture	number	no
y	y coordinate of tag, as a percentage offset from the top edge of the picture	number	no

If the write is successful, you get the following return.

Description	Type
If the update succeeded	boolean

Update

You can update the position of a tag for a particular user in the photo by issuing a HTTP POST request to /PHOTO_ID/tags/USER_ID or PHOTO_ID/tags?to=USER_ID with updated x and y coordinates.

Updating a tag on a photo requires the publish_stream permission and supports the following parameters.

Parameter	Description	Type	Required
to	USER_ID of the User to tag; can also be provided in URL path (see above).	string	yes
x	x coordinate of tag, as a percentage offset from the left edge of the picture	number	no
y	y coordinate of tag, as a percentage offset from the top edge of the picture	number	no

If the update is successful, you get the following return.

Description	Type
If the update succeeded	boolean

Delete

You can delete a tag for a particular user in the photo by issuing a HTTP DELETE request to /PHOTO_ID/tags/USER_ID or PHOTO_ID/tags?to=USER_ID.

Deleting a tag on a photo requires the publish_stream permission and supports the following parameters.

Parameter	Description	Type	Required
to	USER_ID of the User to tag; can also be provided in URL path (see above).	string	yes

If the deletion is successful, you get the following return.

Description	Type
If the deletion succeeded	boolean

How-Tos

• How to upload a photo to a user' profile (php)
• How to get access to, add new and update tags on A Photo (php)]