Listings: Photos

The Listing Photos service returns data about listing photos for a specific listing to be retrieved. URIs to various photo sizes are returned rather than image files.
  1. Supported Roles
  2. Available Services
    1. Listing Photos
    2. Individual Listing Photo
    3. Restoring Deleted Photos
  3. Photo Description
  4. Expansions
  5. API Explorer

Supported Roles

Role Reads Writes
IDX Yes No
VOW Yes No
Private Yes Yes
More information about roles may be found here.

Available Services

Listing Photos

URI: /<API Version>/listings/<Listing.Id>/photos

HTTP Method Description Notes
GET Returns a list of all photos associated with the current listing
POST Uploads a photo to attach to a listing
PUT Allows the reordering of photos for a given listing
DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:
  • None

GET Response

Example:
{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/v1/listings/20060412165917817933000000/photos/20080917142739989238000000",
                "Id": "20080917142739989238000000",
                "Name": "Listing Photo",
                "Caption": "",
                "UriThumb": "http://photos.sparkplatform.com/demomls/20080917142739989238000000-t.jpg",
                "Uri300": "http://photos.sparkplatform.com/demomls/20080917142739989238000000.jpg",
                "Uri640": "http://resize.sparkplatform.com/demomls/640x480/true/20080917142739989238000000-o.jpg",
                "Uri800": "http://resize.sparkplatform.com/demomls/800x600/true/20080917142739989238000000-o.jpg",
                "Uri1024": "http://resize.sparkplatform.com/demomls/1024x768/true/20080917142739989238000000-o.jpg",
                "Uri1280": "http://resize.sparkplatform.com/demomls/1280x1024/true/20080917142739989238000000-o.jpg",
                "Uri1600": "http://resize.sparkplatform.com/demomls/1600x1280/true/20080917142739989238000000-o.jpg",
                "Uri2048": "http://resize.sparkplatform.com/demomls/2048x1536/true/20080917142739989238000000-o.jpg",
                "UriLarge": "http://photos.sparkplatform.com/demomls/20080917142739989238000000-o.jpg",
                "Primary": true
            }
        ]
    }
}

POST Request

Request body:
{
    "D": {
        "Photos": [
            {
                "Picture": "AB81959FEDAA...",
                "FileName": "GreatPic.jpg",
                "Name": "Front porch",
                "Caption": "Step onto the hand-felled timber of your new front porch for the ultimate in luxurious relaxation"
            }
        ]
    }
}

POST Response

The standard success/fail response is returned.

PUT Request

Request body:
{
    "D": {
        "Photos": [
            {"Id": "20111213041526458274000000"},
            {"Id": "20121214041526458275000000"},
            {"Id": "20130415041526458276000000"},
            {"Id": "20130516041526458277000000"}
        ]
    }
}
For the global PUT to the listing, currently only the Id attribute is accepted and is currently intended to be used for reordering photos for a listing.

PUT Response

The standard success/fail response is returned.

Individual Listing Photo

URI: /<API Version>/listings/<Listing.Id>/photos/<Id>

HTTP Method Description Notes
GET Returns the specified photo
POST Returns HTTP 405 (Method Not Allowed) Not implemented
PUT Updates an existing photo
DELETE Deletes an existing photo

GET Request

Parameters:
  • None

GET Response

See the GET response section above for the data format.

PUT Request

Response Body: See the POST response section above for the data format.
Rotation
You can rotate a photo by passing a single attribute of Rotate with a value of clockwise (90 degrees right) or counterclockwise (90 degrees left). If you are performing a rotation, you cannot update any other attributes. Below is a sample PUT request for a clockwise rotation:
{
    "D": {
        "Photos": [
            {"Rotate": "clockwise"}
        ]
    }
}

PUT Response

The standard success/fail response is returned.

DELETE Request

Primary Photo
You may not delete the primary photo for a listing unless it is the only remaining photo.
Parameters:
  • None

DELETE Response

{
    "D": {
      "Version": 1,
      "ExpiresIn": 14400
    }
}

Restoring Deleted Photos

URI: /<API Version>/listings/<Listing.Id>/photos/<Id>/versions/current

HTTP Method Description Conditional Notes
GET Returns HTTP 405 (Method Not Allowed) No Not implemented
POST Returns HTTP 405 (Method Not Allowed) No Not implemented
PUT Restores the state of a photo to a previous version No
DELETE Returns HTTP 405 (Method Not Allowed) No Not implemented

PUT Request

Request body:
{
    "D": {
      "Version": 1
    }
}

PUT Response

The standard success/fail response is returned.

Response Description

Photo Sizes
If the original size of a photo is smaller than the corresponding attribute declares, the picture linked to will be the original size rather than stretched to specified dimensions. For example, the photo referenced by Uri1280 will be 1280x1024 or smaller.
Attribute Data Type Writeable Required Description
ResourceUri Character No No The URI to the particular photo data (not the image).
Id Character No No The unique id for the photo.
Picture Character Yes POST Base64 encoded representation of the image file.
FileName Character Yes POST The name of the original file being uploaded.
Name Character Yes Yes The name of the photo. Maximum of 40 characters.
Caption Character Yes No Text intended as the photo's caption. Maximum of 1000 characters.
Rotate Character PUT No The direction to rotate the photo, either clockwise or counterclockwise.
UriThumb Character No No The URI to the thumbnail-sized image.
Uri300 Character No No
Uri640 Character No No The URI to the 640x480 image.
Uri800 Character No No The URI to the 800x600 image.
Uri1024 Character No No The URI to the 1024x768 image.
Uri1280 Character No No The URI to the 1280x1024 image.
Uri1600 Character No No The URI to the 1600x1280 image.
Uri2048 Character No No The URI to the 2048x1536 image.
UriLarge Character No No The URI to the original image.
Primary Boolean Yes No true if the photo is intended as the listing's primary photo.

Expansions

None.

API Explorer

The API Explorer does not currently support this service.