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:
- WebP images are served as they are (no scaling, blur or rotation).
- Thumbnails (
t) larger than 150 KB are recompressed even without scaling parameters. bs.clean,bs.statsandbs.debugare server maintenance switches — don't use them.
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
- The server caches fetched and scaled images on disk; repeated calls with the same type, id and scaling are cheap. Scaling variants are cached separately, so stick to a few sizes.
- Clients get
Cache-Control: max-age=4 days, or 60 days whenh=is given. The standard components therefore always pass the object's image hash ashand a fixed scaling. - When the shop changes an image, its hash in the API object changes → new URL → fresh image.
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
- Always request a size. Unscaled originals are often several MB; the proxy only scales when you ask for it.
- Use
tfor lists andbfor detail views; checkthumbnailCode/imageCodefirst to avoid needless 404 placeholders. - Pass
h=<hash>for long caching — and nothing else that changes per request, or you defeat both caches. - datanature images are licensed for items the shop sells, nothing else.
- The proxy serves through the shop's domain with CORS headers; don't copy images to your own server, the source may change or be withdrawn.