API Documentation

Description

The Shutterfly True Aspect Ratio Imaging Request protocol provides URL-based customization of dynamically generated jpeg images in users' albums. Accesses to other types of images (collection, progalleries, ordered, etc) are not covered by this protocol. This protocol allows customization of output resolution and 90-degree-based rotation. All customer-defined imaging enhancements (border, crop, redeye, etc.) are displayed in the resulting image, but they cannot be customized dynamically. "True aspect ratio" is the aspect ratio of the user-specified crop rectangle. If there is no user crop, the aspect ratio of the original picture is used.

Call Signature

Application ID and call signature are NOT required, and will be ignored if they are present. Please see Call Signature documentation for more details.

Resource Path

This API uses either of the following equivalent resource path elements:

/proctaserv - often paired with a Shutterfly image ID
/proctasserv - often paired with a Shutterfly image ID for security access to high resolution picture

Methods

GET - Gets jpeg image data.

Scheme

http

Host

im1.shutterfly.com

Method Endpoint example

GET http://im1.shutterfly.com/proctaserv/47b7cc00b3127cceb213456c6b6e00000087108YcsXDNiyw

Method	Endpoint example

GET	http://im1.shutterfly.com/proctaserv/47b7cc00b3127cceb213456c6b6e00000087108YcsXDNiyw

In the following Method detail sections, click on Method name to expand or collapse the detail.

Method: GET

Gets jpeg image data.

Input Parameters

Input to the /proctaserv service is specified as a url path instead of as a query parameter. The string (aka Image ID) right after the /proctaserv/ is the input to the service and used as an ID and rendering instructions for dynamic rendering.

Image ID Format

The Image ID is at least 38 characters long and contains an ID to the source image and simple rendering instructions. NOTE: Zero-based array notation used below, so for example the rotation is actually the 38th character if you count starting at 1.

id[0,34] : Shutterfly internal ID (opaque to the public)
id[35] : Image Size (customizable)
id[36] : Not used
id[37] : Rotation (customizable)
id[38,+] : Shutterfly internal ID (opaque to the public)

Image Size

The Image Size parameter allows customization of the output resolution. Based on the crop aspect ratio, the imaging system will render the jpeg to the target output resolution. The following specifies the size of the "longer" side of the output. For example, if the user's crop is in 4x6, the jpeg output will be in 800x533 (800*4/6) if image size 5 is used. If image size 9 is used, the output will be 96x64 (96*4/6). The output orientation will be based on the crop aspect ratio as well as the specified rotation.

5 : jpeg with max-dimension at 800px
6 : jpeg with max-dimension at 480px
7 : jpeg with max-dimension at 400px
8 : jpeg with max-dimension at 200px
9 : jpeg with max-dimension at 96px

/proctasserv/ resource allows to get image of the original resolution by adding parameter raw=1. Also this url should be signed via Call Signature or using special Java library. See documentation.

Rotation:

0 : no rotation
1 : 90 degree clockwise rotation
2 : 180 degree clockwise rotation
3 : 270 degree clockwise rotation

Output Parameters

Given a valid Image ID, the service will return a jpeg according to the specification. All images returned by this service are cached and the regular HTTP cache directives are honored.

Content-Type

image/jpeg

Error Codes

If there is no error, methods return HTTP status code 200 (or 201 for a create operation). See the documentation for Common Response Codes.

The following HTTP status codes are especially noteworthy:

200: OK

The normal response, even if the image was unavailable. The HTTP response body will always contain a valid jpeg. If the image was available, it is the image. If the image was unavailable, it is a jpg that displays the text "Sorry, the image is currently unavailable".

500: Internal Server Error

The Shutterfly server had an error. The call can be retried later.

Shutterfly Open API | True Aspect Ratio Imaging Request