Images

All images in a shop can be automatically scaled and cropped to any size (as long as it is not larger than the original image). This is achieved by adding a few parameters to the image URL.

You should almost always limit the file size - do not let your shop users download unnecessarily large images.

Starting early 2017, images will be converted to JPEG, unless they contain transparency or if they are animated. Cached images will not be re-generated unless you change the parameters. The bg parameter will enable images with transparency to be converted to JPEG as well.

Note that depending on the image source:

• The resolution might be lower than what you requested.
• The returned image might be converted from PNG or GIF to JPEG.
• The JPEG quality may be lower than what you requested.

Query parameters

Parameter	Value(s)	Description
max-width	[1..20'000]	The maximum width of the returned image in pixels.
max-height	[1..20'000]	The maximum height of the returned image in pixels.
resize	scale or crop	The resize method to use. The default value is scale.
gravity	north, south, east, west	From which side to scale if no hotspot is defined. Leaving this out defaults to center.
quality	[1..100]	The image quality.
max-size	[1...]	The maximum file size in kB).
bg	hex code	Background to fill transparent images with

max-width and max-height

Setting one or both of the max-width and max-height properties will return an image scaled proportionally to fit within those constraints. An image can be scaled down, but never scaled up.

Example

Fetch a proportionally scaled image with the maximum width of 300px

https://shop.example.com/necklace.jpg?max-width=300

If we requested necklace.jpg with max-width=600 the delivered image would be 500px wide, since that is the width of the original image.

Example

Fetch a proportionally scaled image with the maximum with of 300px and the maximum height of 300px

https://shop.example.com/necklace.jpg?max-width=300&max-height=300

resize

The default resize value is scale. To crop an image you must:

• Set both max-width and max-height.
• Set the resize query parameter to crop.

https://shop.example.com/necklace.jpg?max-width=300&max-height=200&resize=crop

gravity

gravity can be used together with resize=crop. It is only applied if the image does not have a defined hotspot.

By default (if no gravity is specified), an image is cropped from the center. By setting gravity to north, south, east or west, the image will be cropped from the top, bottom, right or left side instead.

https://shop.example.com/necklace.jpg?max-width=300&max-height=200&resize=crop&gravity=west

quality

With quality it is possible to decrease (but never increase) the image quality for JPEG images.

If no quality parameter is passed it is set to 92.

The value of quality can be seen as a recommendation to the server. Under different circumstances it can either be increased or decreased:

• Image quality will never exceed the quality of the original image.
• If a larger image is requested than what the server can deliver, the quality will be increased to compensate for the lack of pixels, but at the same time the file size will be kept at a reasonable level.

Example

Reduce the file size by setting a lower JPEG-quality

https://shop.example.com/necklace.jpg?max-width=300&max-height=300&quality=75

max-size

max-size takes a value (in kB) and scales down the image to approximately this value.

In practice, this is useful as a complement to max-width and/or max-height, especially when you don't know if the returned image can be converted to JPEG or not.

Example

The result might be an animated GIF, in which case 1200x1200px is not reasonable. Limit the file size to approximately 4MB:

https://shop.example.com/necklace.gif?max-width=1200&max-height=1200&max-size=4000

bg

bg sets a background color to fill transparency in transparent images. This effectively means that PNG will be converted to JPEG, reducing their file size.

Example

Set the background to white, so that we don't need transparency

https://shop.example.com/necklace.png?max-width=300&max-height=300&bg=FFFFFF

width and height (deprecated)

width and height are deprecated and are available for compatibility reasons only. Setting width and height is analogous to setting max-width, max-height and resize=crop, but without the possibility of using quality, gravity, resize=scale, max-size or bg.

Hotspot

An image can have a defined "hotspot". This is the part of the image that is the most important to preserve when cropping. When someone requests a cropped version of an image, we zoom in on the hotspot. We try to include the whole hotspot in the cropped image, but in a few cases this is not possible, e.g. when someone requests a very narrow image and the hotspot is very wide.

The hotspot is a rectangle of any size. The coordinates are stored in the comment metadata of the original image. The comment should be in the form WIDTHxHEIGHT+OFFSETX+OFFSETY (e.g. 800x600+50+40). If such a comment is found inside an image it is used as the hotspot. Otherwise, the whole image is taken as the hotspot (i.e. as little as possible is cropped away).

Examples

Original image: Let's say we have an original image of a necklace, with a hotspot area centered on the lower part of the image, here marked with a purple rectangle for clarity.

https://shop.example.com/necklace.jpg

Cropping: Resizing the image to 300×200 results in cropping. We achieve an effect of zooming in on the hotspot.

https://shop.example.com/necklace.jpg?max-width=300&max-height=200&resize=crop

Cropping and scaling: Resizing the image to an even smaller size, here to 200×133, results in both cropping and scaling, showing the whole hotspot part of the image but scaling it down to the requested size.

https://shop.example.com/necklace.jpg?max-width=200&max-height=133&resize=crop