Photo object

Article
03/30/2015

The Photo object contains info about a user's photos on Microsoft OneDrive.

The Live SDK REST API supports creating, reading, updating, and deleting Photo objects. Use the wl.photos scope to read Photo objects. Use the wl.contacts_photos scope to read any albums, photos, videos, and audio that other users have shared with the user. Use the wl.skydrive_update scope to create, update, or delete Photo objects.

Valid object paths

/PHOTO_ID

A Photo object can be returned as part of /ALBUM_ID/files, /ALBUM_ID/photos, /FOLDER_ID/files, /me/skydrive/files, /me/skydrive/shared/photos, or USER_ID/skydrive/files.

Structures

The Photo object contains the following structures.

Structure	Type	R/W	Description
data	array	R	An array of Photo objects, when a collection of objects is returned.
id	string	R	The Photo object's ID.
from	object	R	Info about the user who uploaded the photo.
name (from object)	string	R	The name of the user who uploaded the photo. Part of the from object.
id (from object)	string	R	The ID of the user who uploaded the photo. Part of the from object.
name	string	R/W	The file name of the photo. Required.
description	string/null	R/W	A description of the photo, or null if no description is specified.
parent_id	string	R	The ID of the folder where the item is stored.
size	number	R	The size, in bytes, of the photo.
comments_count	number	R	The number of comments associated with the photo.
comments_enabled	true/false	R	A value that indicates whether comments are enabled for the photo. If comments can be made, this value is true; otherwise, it is false.
tags_count	number	R	The number of tags on the photo.
tags_enabled	true/false	R	A value that indicates whether tags are enabled for the photo. If users can tag the photo, this value is true; otherwise, it is false.
is_embeddable	true/false	R	A value that indicates whether this photo can be embedded. If this photo can be embedded, this value is true; otherwise, it is false.
picture	string	R	A URL of the photo's picture.
source	string	R	The download URL for the photo. Important: This value is not persistent. Use it immediately after making the request, and avoid caching.
upload_location	string	R	The URL to upload photo content hosted in OneDrive. This value is returned only if the wl.skydrive scope is present.
images	array	R	Info about various sizes of the photo.
height (images array)	number	R	The height, in pixels, of this image of this particular size.
width (images array)	number	R	The width, in pixels, of this image of this particular size.
source (images array)	string	R	A URL of the source file of this image of this particular size.
type (images array)	string	R	The type of this image of this particular size. Valid values are: full (maximum size: 2048 2048 pixels) normal (maximum size 800 800 pixels) album (maximum size 176 176 pixels) small (maximum size 96 96 pixels)
link	string	R	A URL of the photo, hosted in OneDrive.
when_taken	string/null	R	The date, in ISO 8601 format, on which the photo was taken, or null if no date is specified.
height	number	R	The height, in pixels, of the photo.
width	number	R	The width, in pixels, of the photo.
type	string	R	The type of object; in this case, "photo".
location	object	R	The location where the photo was taken. Note that the location object is not available for shared photos.
latitude (location object)	double	R	The latitude portion of the location where the photo was taken, expressed as positive (north) or negative (south) degrees relative to the equator.
longitude (location object)	double	R	The longitude portion of the location where the photo was taken, expressed as positive (east) or negative (west) degrees relative to the Prime Meridian.
altitude (location object)	double	R	The altitude portion of the location where the photo was taken, expressed as positive (above) or negative (below) values relative to sea level, in units of measurement as determined by the camera.
camera_make	string	R	The manufacturer of the camera that took the photo.
camera_model	string	R	The brand and model number of the camera that took the photo.
focal_ratio	double	R	The f-number that the photo was taken at.
focal_length	double	R	The focal length that the photo was taken at, typically expressed in millimeters for newer lenses.
exposure_numerator	double	R	The numerator of the shutter speed (for example, the "1" in "1/15 s") that the photo was taken at.
exposure_denominator	double	R	The denominator of the shutter speed (for example, the "15" in "1/15 s") that the photo was taken at.
shared_with	object	R	The object that contains permissions info for the photo.
access (shared_with object)	string	R	Info about who can access the photo. The options are: People I selected, Just me, Everyone (public), Friends, My friends and their friends, and People with a link. The default is Just me.
created_time	string	R	The time, in ISO 8601 format, at which the photo was created.
updated_time	string	R	The time, in ISO 8601 format, at which the photo was last updated.

Examples

The following is an example of a collection of Photo objects. (For brevity, only the first object is shown.)

{
   "data": [
      {
         "id": "file.de57f4126ed7e411.DE57F4126ED7E411!128", 
         "from": {
            "name": "Nuno Bento", 
            "id": "de57f4126ed7e411"
         }, 
         "name": "Maui-2012_0034.JPG", 
         "description": null, 
         "parent_id": "folder.de57f4126ed7e411.DE57F4126ED7E411!126", 
         "size": 561683, 
         "comments_count": 1, 
         "comments_enabled": true, 
         "tags_count": 0, 
         "tags_enabled": true,
         "is_embeddable": true, 
         "picture": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:Thumbnail", 
         "source": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:HighRes", 
         "upload_location": "https://apis.live.net/v5.0/file.de57f4126ed7e411.DE57F4126ED7E411!128/content/", 
         "images": [
            {
               "height": 450, 
               "width": 600, 
               "source": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:WebReady", 
               "type": "normal"
            }, {
               "height": 132, 
               "width": 176, 
               "source": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:MobileReady", 
               "type": "album"
            }, {
               "height": 72, 
               "width": 96, 
               "source": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:Thumbnail", 
               "type": "thumbnail"
            }, {
               "height": 1200, 
               "width": 1600, 
               "source": "http://storage.live.com/s1pKk5vzd-gdPanbzKYhB0nQGn8wGq5DSgqvrgIHU1NTXA4e2-spGkAhQjW1d9pcgKAGLB4NsEsSvDoREmdx5w-JiFrinEJJuEoz08Ws_IFupkX2bPSvy5qmths9ijwvDrXi1OBCWk9GW9Kt-qNNOAA9g/Maui09_0034.JPG:HighRes", 
               "type": "full"
            }
         ], 
         "link": "https://skydrive.live.com/redir.aspx?cid\u003dde57f4126ed7e411\u0026page\u003dview\u0026resid\u003dDE57F4126ED7E411!128\u0026parid\u003dDE57F4126ED7E411!126", 
         "when_taken": "2008-03-24T23:41:53+0000", 
         "height": 1200, 
         "width": 1600, 
         "type": "photo",
         "location": {
             "latitude": 47.65316, 
             "longitude": -122.135911,
             "altitude": 43
         }, 
         "camera_make": "MyManufacturer",
         "camera_model": "MyModel",
         "focal_ratio": 2.8,
         "focal_length": 3.85,
         "exposure_numerator": 1,
         "exposure_denominator": 15, 
         "shared_with": {
            "access": "Everyone (public)"
         }, 
         "created_time": "2012-12-03T18:14:03+0000", 
         "updated_time": "2012-12-03T18:31:01+0000"
      }, {
         ...
      }
   ]      
}

To get a collection of Photo objects by using the Live SDK REST API, make a GET request to /ALBUM_ID/files.

Note

You can also get a collection of Photo objects by calling either /ALBUM_ID/photos, or /FOLDER_ID/photos.

Note

To display a photo, call /PHOTO_ID/picture. To display a photo of a specific image size, follow /PHOTO_ID/picture with ?type= and one of the following: thumbnail, small, album, normal, or full. The default is normal. The following is an example of a call that displays a thumbnail image.

https://apis.live.net/v5.0/PHOTO_ID/picture?type=thumbnail&access_token=ACCESS_TOKEN

In the preceding examples, replace ALBUM_ID and PHOTO_ID with the target album or photo ID.

To create a new Photo resource, you can make either aPUT request with the photo in the body or a POST request with the photo in a multipart form body. For POST, make a POST request to the /UPLOAD_LOCATION for the target folder or a POST request to/FOLDER_ID. You must format the request as a multipart/form-data media type as described in RFC 2388. You must specify the Content-Type as multipart/form-data, and specify the boundary like this.

Content-Type: multipart/form-data; boundary=AaB03x

Provide the item to upload on a multipart section, and the name of the photo as the value of the filename parameter of the Content-Disposition header, as shown here.

Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="file"; filename="hovering_orbs.jpg"
Content-Type: image/jpeg

...contents of hovering_orbs.jpg...
--AaB03x--

Note

The boundary value (shown here as "AaB03x") can be any arbitrary string value.

Only one multipart section per request is supported. For a PUT request, leave the Content-Type blank and put the contents of the file in the request body.

Upon successful creation, the location header points to the location for the newly created photo, and the response body contains the following properties.

{
   "id": "ID of the new photo",
   "name": "The file's name and file extension",
   "source": "URL where the photo can be downloaded from"
}

You can upload a photo to an existing resource in any of the following ways.

Make a PUT request to /UPLOAD_LOCATION/FILE_NAME for the folder you would like to upload to.
Make a PUT request to /FOLDER_ID/files/FILE_NAME.
Make a PUT request to /ALBUM_ID/files/FILE_NAME.
Make a PUT request to /UPLOAD_LOCATION for the file to update.
Make a PUT request to /PHOTO_ID/content.

By default, if an uploaded photo is larger than 2048 2048 pixels in size, OneDrive automatically attempts to shrink it to fit within this 2048 2048-pixel size constraint. To override this behavior, set the downsize_photo_uploads query-string parameter to false for example, /FOLDER_ID/files?downsize_photo_uploads=false for POST or /FOLDER_ID/files/FILENAME?downsize_photo_uploads=false for PUT.

To update the properties for a Photo resource, make a PUT request to /PHOTO_ID, and specify the changes in the request body, as shown here.

{
   "name": "fast-moving_orbs.jpg"
   "description": "Fast moving objects."
}

To delete a photo, make a DELETE request to /PHOTO_ID.

To move a photo, make a MOVE request to /PHOTO_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

To copy a photo, make a COPY request to /PHOTO_ID or /FOLDER_ID, and specify the ID of the destination folder in the request body, as shown here.

{
   "destination": "FOLDER_ID"
}

For PUT and POST requests, you can use the overwrite query string parameter to indicate whether the request should fail if the resource already exists, as shown here. Optionally you can specify an overwrite query-string parameter value of ChooseNewName if you want to upload a duplicate copy of the file but let OneDrive choose the uploaded file's new file name. Note that MOVE and COPY do not support overwriting at this time.

overwrite=true
overwrite=false
overwrite=ChooseNewName

If the value of the overwrite query string parameter is set to true, and the file exists, it is overwritten. If the value is set to false, the file is not overwritten, and a resource_already_exists error is returned. If no overwrite query string parameter is specified, the default value is true.

Remarks

Photos that are uploaded to OneDrive through the API are limited to a maximum resolution of 2048 x 2048 pixels. Any photo over that resolution is scaled proportionally to fit within a maximum size of 2048 x 2048 pixels.

Photo object

Valid object paths

Structures

Examples

Remarks

See also

Additional resources