← API Index

Images and files: the proxy

API objects never carry image bytes (unless you ask for ?img=b64). Instead they tell you that an image exists — e.g. an Item has thumbnailCode and imageCode, a Group an image hash, an item an imageCount for extra images — and you fetch the image through the shop's proxy. The proxy looks up the object, fetches the image from wherever the shop keeps it, scales it if requested, caches the result and serves it with long cache headers. Use it for every image you show; never link the original image locations.

<base URL>/<type>.px?bs.i=<id>[&bs.w=..&bs.h=..&bs.bg=..&bs.fit=1&bs.blur=..&bs.rot=..][&h=<hash>]

Example: https://oekobox-online.eu/v3/shop/schoenegge/b.px?bs.i=123 — the big image of item 123; …/t.px?bs.i=123&bs.w=80&bs.h=80&bs.bg=ffffff — its thumbnail, scaled into 80×80 on white.

The base URL is the shop's base URL (see use-api). A shop may run a dedicated image host: if the imgproxy field of the Config object is set, use that as base for proxy calls.

Parameters

Parameter Description
bs.i Required. The object id (an integer for most types; a name or path for ab, as, eu, e*, f, fs, d*, h*). Max. 60 characters, no spaces or brackets.
bs.w, bs.h Maximum width / height in pixels. Images are only scaled down to fit, keeping the aspect ratio; giving one of them is enough.
bs.bg Background colour (6 hex digits, e.g. ffffff) used to fill the area when scaling leaves space.
bs.fit If present, the image is stretched to fill bs.w × bs.h exactly (aspect ratio not kept, may enlarge).
bs.blur Blur radius 1..50.
bs.rot Rotation in 45° steps: 1 = 45°, 2 = 90°, … 7 = 315°.
h Any cache hash, e.g. the thumbnailCode / imageCode of the object. Changes the client cache lifetime from 4 days to 60 days — use it, and change it when the object tells you the image changed.
bs.nocache Bypass the server cache for this call (no lookup, no storing). Development only.
bs.clear Remove this image from the server cache before serving. Development only.

Notes:

Type codes

Items

Code Image
t Item thumbnail (falls back to the big image if no thumbnail exists)
b Item big image (falls back to the first extra image if no primary image exists)
bt Big image, or the thumbnail if no big one exists
b1 … b9 Extra images 1..9 (imageCount tells how many exist)

Categories and navigation

Code Image
g / h Group small / big
s / u Subgroup small / big
r / v Rubric small / big
m / n Navigation entry small / big
nd Navigation level 2 entry (small)
a Assortment (abo box)
y / x Assortment group small / big

Producers, associations, labels

Code Image
p / pi Producer logo / producer big image
as / ab Association logo small / big; bs.i is the association name as delivered with the item (e.g. Bioland)
eu EU origin label (PDO, PGI, TSG); bs.i is the label name
br Bonus reward image

Content and files

Code Image
tb / ti Content article thumbnail / image
fs File from the shop's file store; bs.i is the file id. Private files are served only to operators — use the .py variant (below).
f Special files, bs.i is one of: logo (the shop's configured logo), loading (loading animation), none (the "no image" placeholder), css / css16 / css25 (the shop's external stylesheet configured for the respective template generation)

External sources

Code Image
d datanature image; bs.i is the image bioid. Use is only permitted for items the shop sells.
dp datanature default image of a product in thumbnail size; bs.i is the product bioid, optionally with v<version> appended — otherwise the latest version is used. Same permission rule.
dt datanature thumbnail by image id
hs / hb Haystack file / brand image by id
e, e1, e2, e4 Images from the ecoinform servers; bs.i is the path
e3 Path behind the shop's internally configured proxy
gt Google tag manager script by container id (served through the shop domain)

A shop operator can additionally map any <code><id> (e.g. g123) to a fixed image path in the backend setting image mapping; such mappings win over the object's own image.

Session bound calls: .py

<type>.py?bs.i=… behaves like .px but is bound to the caller's session and sent with Cache-Control: no-cache. Use it for files that depend on who is asking — private file store files (fs) for operators, or driver photos that are served blurred to drivers until they are released.

The session comes from the session cookie only (an x-oekobox-sid parameter is not taken here). Private files are read fresh on every call and never cached, on the server or in the client; without a permitted session the answer is 404.

Caching

Missing images

If the object has no image, the remote file can't be fetched, or the id is invalid, the proxy answers 404 — but with the shop's configured "missing image" placeholder (or a default one) as body for all image types, so a plain <img> never shows a broken icon. Only the f type returns an empty 404. Images that repeatedly fail to load at the source are given up after a few attempts until the shop fixes the source.

Don't forget