Listing Photos

The Listing Photos service allows data about listing photos for a specific listing to be retrieved. URIs to a variety of photo sizes are returned rather than image files.

  1. Applicable API Key Roles
  2. Authentication
  3. Available Services
    1. Get or replace/upload photos on a listing
    2. Get or replace/upload a single photo on a listing
  4. Listing Photo Response Format
  5. Upload Attribute Descriptions

Applicable API Key Roles

This service is available to API keys with private or IDX roles. Within the IDX role, both IDX and Portal permissions may access this service. Listing data is restricted based on the API key and user’s current permission level. For example, IDX API keys will only have access to IDX listings. More information about roles may be found here.

Upload services are only available to API key users with private API key roles.

Authentication

Requests must be authenticated according to these instructions or HTTP 401 (Unauthorized) will be returned.

Available Services

Get or replace/upload photos on a listing

URI: /<API Version>/listings/XX/photos

XX is a listing ID, such as 20100912153422758914000000 .

HTTP Method Description Notes
GET Gets info about photos for a specified listing. See parameters below
POST Uploads a photo See documentation below
PUT, DELETE Returns HTTP 405 (Method Not Allowed) Not implemented

GET Request

Parameters:

  • None

GET Response

This returns the Listing Photo Response Format.

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"
            }
        ]
    }
}

See the attribute descriptions for more details.

POST Response

POST requests will return the standard success/fail response with resource creation, returning the full JSON representation of the new photo, which includes the URI of the individual photo.

Get or replace/upload a single photo on a listing

URI: /<API Version>/listings/XX/photos/YY

XX is a listing ID, such as 20100912153422758914000000 .
YY is a photo ID, such as 20101222111526876245000000 .

HTTP Method Description Notes
GET Gets info about an individual photo for a specified listing. See parameters below
POST Returns HTTP 405 (Method Not Allowed) Not implemented
PUT Replaces a photo or changes the description, caption, or primary flag See documentation below
DELETE Removes a photo from a listing See documentation below

GET Request

Parameters:

  • None

GET Response

This returns the Listing Photo Response Format.

PUT Request

PUT requests are used to update data about a photo (name, caption, or primary fields) or upload a new photo. Any attributes that are desired to remain untouched should be omitted from the request. Note that sending "Primary": false will not un-mark the photo as primary; the only way to remove a primary photo is to delete all of the photos on a listing.

Note also that replacing the image file will result in a different ResourceUri to eliminate browser caching problems.

Request body:

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

See the attribute descriptions for more details.

PUT Response

PUT requests will return the standard success/fail response with resource creation, returning the full JSON representation of the new or updated photo, which includes the URI of the individual photo.

DELETE Request

To delete a photo, issue a DELETE to the photo’s ResourceUri with no parameters or request body.

DELETE Response

DELETE requests will return the standard success/fail response without resource creation.

Listing Photo Response Format

The response may include multiple photos. This example illustrates the response format for a listing with a single photo.

{
    "D": {
        "Success": true,
        "Results": [
            {
                "ResourceUri": "/vX/listings/20060412165917817933000000/photos/20080917142739989238000000",
                "Id": "20080917142739989238000000",
                "Name": "Listing Photo",
                "Caption": "",
                "UriThumb": "http:\/\/photos.flexmls.com\/demomls\/20080917142739989238000000-t.jpg",
                "Uri300": "http:\/\/photos.com\/demomls\/20080917142739989238000000.jpg",
                "Uri640": "http:\/\/resize.flexmls.com\/demomls\/640x480\/true\/20080917142739989238000000-o.jpg",
                "Uri800": "http:\/\/resize.flexmls.com\/demomls\/800x600\/true\/20080917142739989238000000-o.jpg",
                "Uri1024": "http:\/\/resize.flexmls.com\/demomls\/1024x768\/true\/20080917142739989238000000-o.jpg",
                "Uri1280": "http:\/\/resize.flexmls.com\/demomls\/1280x1024\/true\/20080917142739989238000000-o.jpg",
                "UriLarge": "http:\/\/photos.flexmls.com\/demomls\/20080917142739989238000000-o.jpg",
                "Primary": true
            }
        ]
    }
}

Attribute Descriptions

Field Description
Picture Base64 encoded representation of the image file. Required on POST, optional on PUT.
FileName Name of the file that’s being uploaded for logging and validation purposes. Required on POST, optional on PUT, but must be sent in tandem with Picture.
Primary Boolean indicating whether the current photo should be set as primary. Invalid on POST, optional on PUT.
Name A description, up to 40 characters. Required on POST, optional on PUT.
Caption A caption for the photo, up to 1000 characters. Optional; if omitted, will be blank.

Comments on this entry are closed.