← API Index

Provide images for items and groups

The shop system typically stores one URL per image and serves the image through its proxy, scaled and cached (see file-proxy for the fetching side). This document is about the other direction: how an image URL gets attached to an item or a navigation level in the first place.

Every Item can carry a thumbnail (list view), a big image (detail view) and up to nine extra images (gallery). Navigation levels — Group, subgroup, Rubric (price list) and Navigation entries — carry a small and a big image each. The API objects only tell you that an image exists (thumbnailCode, imageCode, imageCount, the image hash of a group); whether it does is decided by the sources below.

copying image data

Image files have to be stored somewhere; that is always a place "in the internet". So yu have to copy the file (e.g. from your camera) to a so-called web-space.

FTP, WebDAV or other protocols

These terms describe methods, to move a image file to such a place. Note that adresses and advice opjn how to do this differ, depending on your provider or tools. But in any case, the date that you transfer needs to be available using a regular http(s)-Web URL. After you transferred your image, always check that it is reachable using a web address.

Shop internal

if we are not talking about thousands of product images, you may use the internal storage of the shop systems admin area (Inhalte). After you upload it there, you are presented a web address that you can use with methods

  1. or 5) below.

The image file sources, in order of precedence

# Source Items Groups & navigation
1 Image mapping (shop setting) ✓ ✓
2 URL entered in PCG ✓ ✓
3 Automatic lookup on your webspace ✓ –
4 Shared product databases (oekobox, datanature, ecoinform) ✓ –
5 Generated images – ✓

A mapping entry wins over everything. Among the automatic sources the first one that finds an image wins, and an image that was found once is kept — a later run only fills gaps, it never removes an image (exceptions: PCG clears its URL, or an authoritative ecoinform record says so).

1. Enter the URL in the PCG backend

The simplest way, and the one that works for every entity. In the PCG item record there are two fields, one for the big image and one for the thumbnail; groups, subgroups, price lists and navigation entries have the same pair. Put the full, publicly reachable URL there (https://www.myfarm.example/img/123.jpg). PCG transfers it with the next item update, and the shop picks it up immediately.

2. Automatic lookup on your own webspace

For shops with many items it is easier to drop files into a folder on the shop operator's own webspace (typically by FTP) and let the shop find them. Two settings in the shop admin, group Data Enrichment, define where to look:

Setting Finds
Image Server URL Pattern (big image) — German Bild-Url-Abruf (Großes Bild) the big image, and extra images if {3} is used
Image URL Pattern — German Bild-Url-Abruf (Kleines Bild) the thumbnail

Each setting is a URL pattern with placeholders; several patterns can be given, comma separated, and are tried in order:

Placeholder Replaced by Example pattern
{0} the item id https://www.myfarm.example/img/{0}.jpg → .../img/123.jpg
{1} the item name https://www.myfarm.example/img/{1}.jpg → .../img/Apfelsaft.jpg
{2} the item's EAN https://www.myfarm.example/img/ean/{2}.png → .../ean/4012345678901.png
{3} the item id, plus _1 … _9 for the extra images https://www.myfarm.example/img/{3}.jpg

Rules:

When the lookup runs:

3. Several images per item: the {3} placeholder

If the pattern for the big image contains {3} instead of {0}, the shop also looks for extra images. For item 123 and the pattern https://www.myfarm.example/img/{3}.jpg it checks

.../img/123_1.jpg
.../img/123_2.jpg
...
.../img/123_9.jpg

and stops at the first file that is missing. The number of files found is published as imageCount in the Item object; the images themselves are fetched as b1.px … b9.px (see file-proxy). The primary big image is still 123.jpg (the plain id).

Don't forget:

4. Shared product databases

For branded goods the shop can take images from shared product databases: the platform's own item pool (matched by EAN), datanature (matched by EAN or the datanature id entered in PCG) and ecoinform (EAN or ecoinform id; requires the shop's ecoinform key). Which of them are consulted, and in which order, is the setting info source in the shop admin; ecoinform and datanature need a contract and are licensed for items the shop actually sells, nothing else.

These databases only fill gaps, so a good EAN on the item is all you need. They provide the primary big image and thumbnail, not extra images.

5. Image mapping: the manual override

The setting image mapping in the shop admin is a text block, one entry per line, that overrides the image of any object — items as well as groups, navigation entries, producers and so on — before any other logic is consulted:

# object code + id, then the URL, separated by a space
g123 https://www.myfarm.example/img/groups/vegetables-small.jpg
h123 https://www.myfarm.example/img/groups/vegetables-big.jpg
t4711 https://cdn.supplier.example/pics/4711-thumb.png

# variables
$base=https://www.myfarm.example/img
b4711 ${base}/4711-detail.jpg

# rewrite a fragment in ALL image URLs, e.g. after moving the webspace
!http://old-host.example/images/ https://www.myfarm.example/img/

The object codes are the proxy type codes (t item thumbnail, b item big image, b1…b9 extra images, g/h group small/big, s/u subgroup, r/v price list, m/n navigation, …), listed in file-proxy. Lines starting with # are comments.

Use it for the odd exception — a seasonal picture, a group image the backend can't hold, a supplier picture you don't want to download — and for the ! rewrite after a server move. It is not meant to maintain hundreds of items; use the webspace lookup for that. The mapping is cached for up to a day on the server; a change may take that long to show.

This feature is useful also for external agencies, that can not sit in front af a backend PCG: give them Webadmin-Role in PCG, so they can manage the images without big coordination.

6. Generated images for navigation levels

If the setting AI image generation for navigation is switched on, a group, subgroup, price list or navigation entry without an image gets one generated from its name and description (the prompt is configurable). The result is stored in the shop's content area, where it can be deleted to trigger a new attempt with a changed prompt. Items are never generated.

Play with the Prompt in the system setup - this is a fast way to make your shop attractive even if not (all) images the navigation levels are ready!

Image format and size

The proxy scales every image down to what the frontend asks for, so the source only needs to be good — not small. Recommended:

Recommendation
Shape Square (1:1). Thumbnails in lists, cart and app tiles are (typically) square; a non-square source is letter-boxed with a background colour or cropped by the frontend. Big images may be 4:3, but square is the safe choice for both.
Resolution Rather more pixels than less: 1200×1200 for the big image and the extra images is a good target; the thumbnail may be the same file. Anything below ~400×400 looks blurry on a phone.
File type JPEG for photos, PNG for graphics with transparency or text. Prefer both over WebP: WebP is served as it is — not scaled, not rotated, not blurred — so every client downloads the full file. GIF works but is limited to 256 colours.
File size Not more than 200 KB per file. Compress JPEGs at quality 80–85; very large originals (several MB) are fetched slowly, cached in full and may be refused above a limit. A thumbnail above 150 KB is recompressed by the server anyway.
Colour sRGB; embedded CMYK or exotic colour profiles come out wrong.
Orientation Save the image upright. EXIF rotation is honoured, but not every editor writes it.

Lower case file extensions matching the content (.jpg for JPEG) avoid surprises with the content type check.

Changing an image

The shop and the browsers cache aggressively (see file-proxy). When you replace a file under the same name, the new picture appears after the next item update from PCG or after "clear cache" in the shop admin (for one item or the whole shop); the image hash in the API changes with it, so API clients get a new URL automatically. When you replace it under a new name, update the URL in PCG, or just drop the old file and let the lookup find the new one on the next run.

Don't forget

Ideas