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.
Photo Uploads
See the Photo Uploads documentation to see the preferred method for uploading, and attaching, a new photo to a listing.
Supported Roles
| Role | Reads | Writes | Notes |
|---|---|---|---|
| IDX | Yes | No | |
| Public | Yes | No | |
| VOW | Yes | No | |
| Portal | Yes | No | |
| Private | Yes | Yes |
More information about roles may be found here.
Available Services
Listing Photos
/<API Version>/listings/<Listing.Id>/photos
/<API Version>/listings/incomplete/<IncompleteListing.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 reordering of photos or batch updates for photo Privacy values |
|
| 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/1600x1200/true/20080917142739989238000000-o.jpg",
"Uri2048": "http://resize.sparkplatform.com/demomls/2048x1600/true/20080917142739989238000000-o.jpg",
"UriLarge": "http://photos.sparkplatform.com/demomls/20080917142739989238000000-o.jpg",
"Primary": true,
"Tags": {"Room": ["Living"]}
}
]
}
}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:
For the global PUT to the listing, if only the Id attribute is provided, the photos will be reordered for
the listing. Otherwise, if Privacy is passed along with the Id, the specified records will have their
Privacy attribute updated.
These two operations will not be performed at the same time.
Reordering
{
"D": {
"Photos": [
{"Id": "20111213041526458274000000"},
{"Id": "20121214041526458275000000"},
{"Id": "20130415041526458276000000"},
{"Id": "20130516041526458277000000"}
]
}
}Batch Privacy Updates
Maximum of 50 records allowed in a single request.
{
"D": {
"Photos": [
{"Id": "20111213041526458274000000", "Privacy": "Private"},
{"Id": "20121214041526458275000000", "Privacy": "Private"}
]
}
}PUT Response
The standard success/fail response is returned.
Individual Listing Photo
/<API Version>/listings/<Listing.Id>/photos/<Id>
/<API Version>/listings/incomplete/<IncompleteListing.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 one or more existing photos. | Extra photos may be appended by <Id> to the URI so long as they are delimited by commas. A maximum of 50 photos may be removed at once. |
GET Request
Parameters:
- None
GET Response
See the GET response section above for the data format.
PUT Request
The PUT request supports the following operations for manipulating a photo, each of these operations must be performed independently in separate requests.
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"}
]
}
}Order:
You can reorder a single photo in the overall photo set by passing the Order attribute. The value must be greater than 0, and any number higher than the size of the photo set will bump the photo to the last position. Below is a sample PUT request to move a photo to the beginning:
{
"D": {
"Photos": [
{"Order": 1}
]
}
}Update:
See the POST request section above for the data format.
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.
Multiple Photos
Versioning is not supported when deleting multiple photos. Photos deleted in bulk cannot be restored.
Parameters:
- None
DELETE Response
{
"D": {
"Version": 1,
"ExpiresIn": 14400
}
}Restoring Deleted Photos
/<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.
Photos 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 |
|---|---|---|---|---|
Id |
Character | No | No | The unique id for the photo. |
ResourceUri |
Character | No | No | The URI to the particular photo data (not the image). |
Picture |
Character | Yes | POST | Base64 encoded representation of the image file. Not present when retrieving photo data. |
FileName |
Character | Yes | POST | The name of the original file being uploaded. Not present when retrieving photo data. |
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. |
Privacy |
Character | Yes | No | Either Public or Private (default: Public). This is the desired privacy level of the photo, and is used to determine the CurrentPrivacy attribute. |
CurrentPrivacy |
Character | No | No | Either Public or Private. Private photos will only be available to FBS products, and will only be available for private roles. Use this attribute to determine the active privacy level of the photo. |
Rotate |
Character | PUT | No | The direction to rotate the photo, either clockwise or counterclockwise. Not present when retrieving photo data. |
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 1600x1200 image. |
Uri2048 |
Character | No | No | The URI to the 2048x1600 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. |
Tags |
JSON Object | No | No | The possible tags, and tag groups, are defined in the
photos metadata resource. This is the only attribute that can be used
when
filtering the Photos expansion.
|
Expansions
None.