Skip to content

Property Images

Jump to bottom
Alex Wyett edited this page Apr 8, 2016 · 12 revisions

Within a property object, you will find an ordered array of property images.

"images": [
        {
            "filename": "filename1.png",
            "url": "http://carltonsoftware.apiary.io/image/original/1x1/filename1.png",
            "alt": "Mouse Cottage - blue front door",
            "title": "Mouse Cottage",
            "width": "640",
            "height": "480"
        },
        {
            "filename": "filename2.png",
            "url": "http://carltonsoftware.apiary.io/image/original/1x1/filename2.png",
            "alt": "Mouse Cottage - courtyard garden",
            "title": "Mouse Cottage garden",
            "width": "480",
            "height": "640"
        }
    ],

Resizing and cropping images

By default the URL contained within each image object points to the highest resolution version of the image stored by the API. By adjusting the URL however, it is possible to get the API to resize and crop images to dimensions that suit your use. Listed below are the different types

Basics

All requests to the image generator take the following format:

http://<APIROOT>/image/{type}/{width}x{height}/{filename}

Original

The original image type returns the highest resolution image available.

http://<APIROOT>/image/original/1x1/{filename}

Note that the 'width' and 'height' fields are ignored

Fixed width

The fixed width image type scales the image so that the width of the image is a set length. To return an image that is 400px wide, you would use the following:

http://<APIROOT>/image/width/400x1/{filename}

The 'normal' image type is an alias of fixed width images.

Fixed height

The fixed height image type scales the image so that the height of the image is a set length. To return an image that is 550px tall, you would use the following:

http://<APIROOT>/image/height/1x550/{filename}

Note that the 'width' field is ignored.

Square

The square image type scales the image so that both the height and width of the image are a specified length. To return an image that is 500px wide and 300px tall, you would use the following.

http://<APIROOT>/image/square/500x300/{filename}

Note that using this image type can result in distorted images.

Original:

Original Image

Resized Image:

Resized Image

Smart square

The smart square image type scales the image so that both the height and width of the image are a specified length. This image type avoids the distortion issue associated with the 'square' image type by cropping any overlap from the image, before resizing it.

http://<APIROOT>/image/tocc/500x300/{filename}

Original:

Original Image

Resized Image:

Resized Image

Caching

Generated images are cached on the API for a period of time, but we strongly recommend you perform your own caching in order to optimize the user experience for your customers.

It's worth noting that every time an image changes on the api, its filename also changes (see the prefix on each filename). To cache your images all thats required is a quick existance check, if the file exists, serve it from disk, otherwise serve it from the api and save it to disk.

Clone this wiki locally