Developer Network Home - Help

uploadPhotos Documentation for Yahoo! Photos Services

Version 3.0 Photos : uploadPhotos

Upload New Photos

The uploadPhotos service creates new photos in one of the user's albums. You must make the call using HTTP POST. An uploaded photo consists of:

  • Binary image file data, uploaded using multipart POST
  • Picture captions and descriptions, added to the query string

The service assigns captions and descriptions to photos according to the order in which they appear in the multipart MIME body. To create a multipart MIME request:

  • The request must have a Content-Type header, which must be of type multipart/form-data with a boundary. The boundary is a string that delimits the MIME parts. As an example, a valid Content-Type header might be: Content-Type: multipart/form-data; boundary=----UPBND-df0a35ee191e44568244d69ebb5d03c1-
  • The request should have a Content-Length header, specifying the size of the request body in bytes.
  • Each MIME part must have a Content-Disposition header with a value of form-data and subfields name and filename. A MIME part starts with the boundary string (defined in the Content-Type), followed by the Content-Disposition header, followed by the image data, and ending with another boundary string. If you do not provide the filename subfield, the Yahoo! Photos Service ignores that MIME part. Note that the name and filename subfields should have no spaces before or after the equals sign. As an example, a valid Content-Disposition header might be: Content-Disposition: form-data; name="pic0"; filename="c:\images\abcd.jpg"
  • As with all Yahoo! Photos requests that access user content, you must provide the Cookie header for Browser-Based Authentication.

Although you can upload multiple images in a single HTTP request, it is preferable to upload one image per request. For efficient batch uploads, open multiple simultaneous connections while passing in the same batch ID parameter (batch_id). The batch_id parameter specifies that these parallel connections all belong to the same batch upload.

When you upload an image file, the system stores each new image in three sizes, scaling the image automatically as needed: thumb (max 96 x 96 pixels), screen (max 480 x 480 pixels), and full (full resolution, only available for premium users). Other photo services such as listPhotos can then retrieve the URLs for each of these image sizes.

Authenticated Service

This service uses Browser-Based Authentication, Yahoo!'s generic authentication mechanism for web services that handle Yahoo! user content. Authentication requires these components:

For detailed instructions about making authenticated service calls, refer to Browser-Based Authentication.

Request URL

http://photos.yahooapis.com/V3.0/uploadPhotos

Request parameters

If you are unfamiliar with using REST to make web service calls, refer to our instructions about constructing REST queries. Note that while uploadPhotos includes the image file data in the body of the POST, all other request parameters are attached to the query string.

Parameter Required? Detail
appid Y Represents your application's unique ID.
WSSID Y Prevents replay attacks.
captionn Y, for each photo in the request A caption for the nth photo.
descn N A description for the nth photo.
tagn N A comma-separated list of tags for the nth photo.
tag N A comma-separated list of tags that apply to all photos in the request.
aid N The id of the album to which the photos are to be added.
When omitted, the photos will not belong to any specific album.
batid N A batch id to track the upload request. A batch id consists of a UNIX timestamp appended to the SessionId obtained from a call to listServices. A single batch id may be used in multiple uploadPhotos requests, but the session id will expire in five minutes.
batcount Y, when batid is present The number of photos sent in the batch.

NOTE: In addition to the appid and WSSID parameters, you must also pass an "auth cookie" into the request as an HTTP Cookie Header. For instructions about obtaining and using these components, refer to Browser-Based Authentication.

Response fields

On success, this service returns a PhotoList representing the newly uploaded photos. The schema document for this service response is located at http://photos.yahooapis.com/V3.0/uploadPhotos.xsd.

Sample response

This sample PhotoList response represents a single uploaded photo:

<?xml version="1.0" encoding="UTF-8"?>
<PhotoList xmlns="urn:yahoo:photo" photo:version="3.0" xmlns:photo="urn:yahoo:photo" xmlns:user="urn:yahoo:user" xmlns:album="urn:yahoo:photo:album" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:yahoo:photo listPhotos.xsd">
 <Photo photo:id="291944922677302275" photo:hrWidth="2592" photo:hrHeight="1944" photo:owner="sebastian">
  <Caption>
   test
  </Caption>
  <Share mode="private" adult="false" restricted="true"/>
   <CreateTime>
    2006-03-07T16:10:39Z
   </CreateTime>
   <UploadTime>
    2006-09-28T15:06:30Z
   </UploadTime>
   <ModTime>
    1969-12-31T16:00:00Z
   </ModTime>
   <ImageList>
    <Image type="screen" width="545" height="409" size="45181" format="jpg">
     http://photos.yahoo.com/users/n3lCfjzMOEcK/__sr_/e397.jpg?ph0dFHFBIOty3HlB
    </Image>
    <Image type="thumb" width="120" height="90" size="4119" format="jpg">
     http://photos.yahoo.com/users/n3lCfjzMOEcK/__tn_/e397.jpg?ph0dFHFByIR5CSsT
    </Image>
   </ImageList>
   <EXIF>
    <Camera>
     Canon. Canon PowerShot SD400.
    </Camera>
    <Aperture>
     147/32
    </Aperture>
    <Exposure>
     1/250
    </Exposure>
    <ExposureBias>
     0/3
    </ExposureBias>
    <Flash>
     89
    </Flash>
    <Date>
     2006:03:07 17:10:39.
    </Date>
    <FocalLength>
     17400/1000
    </FocalLength>
    <ZoomRatio>
     2592/2592
    </ZoomRatio>
    <Quality>
     0
    </Quality>
   </EXIF>
 </Photo>
</PhotoList>

Rate Limit

The uploadPhotos service falls under the general rate limits of Yahoo! Photos Web Services. For any particular application, there is a limit to the number of queries per IP address per day and the MB of files that can be uploaded per day. For an explanation of what happens if your application exceeds the limit during any given 24-hour period, refer to the Yahoo! Search Services page about rate limiting.

Errors

The uploadPhotos service returns the standard set of Yahoo! Photos Web Services errors.

Support & Community

The uploadPhotos service is discussed on the ydn-photos mailing list.

Copyright © 2008 Yahoo! Inc. All rights reserved.

Privacy Policy - Terms of Service - Copyright Policy - Job Openings