Produkte
Ein Produkt ist ein Artikel, den Sie als fertige Ware einkaufen oder verkaufen: ein verpacktes Produkt, eine zugekaufte Fertigkomponente, ein Artikel aus dem Katalog eines Lieferanten. Seine Zusammensetzung stammt meist aus der Zutatenliste auf der Verpackung.
Sie speichern es einmal unter Ihrer eigenen id und lesen seinen berechneten Fussabdruck zurück. Ein gespeichertes Produkt kann auch in einem Rezept verwendet werden – referenzieren Sie es mit type: "products".
Ein Produkt speichern
PUT /products/{id}, mit Ihrer eigenen id in der URL. Die Response enthält bereits die fertige Berechnung – ein zweiter Request ist nicht nötig.
{
"id": "carrot-puree-500g",
"gtin": "00123456789023",
"names": [{"language": "de", "value": "Karottenpüree"}],
"amount": 500,
"unit": "gram",
"producer": "ACME Foods",
"ingredients-declaration": "Karotten, Wasser, Salz",
"nutrient-values": {
"energy-kcal": 35,
"fat-gram": 0.2,
"protein-gram": 0.9,
"carbohydrates-gram": 7.5
}
}
Die ingredients-declaration sagt uns, woraus das Produkt tatsächlich besteht. Senden Sie sie deshalb immer mit, wenn die Verpackung eine hat. Ohne sie wird das Produkt allein anhand seines Namens erkannt.
Um einen Katalog hochzuladen, verwenden Sie POST /products/batch. Jedes Produkt wird einzeln verarbeitet und erhält einen eigenen Eintrag in der Response. Ein Produkt, das nicht berechnet werden kann, hält die übrigen also nicht auf. Ordnen Sie die Einträge Ihrem Request über product-id zu oder über die mitgesendete request-id.
Nach dem Hochladen halten Sie Ihre lokale Kopie mit GET /products?updated-since aktuell – siehe Daten aktuell halten.
Daten aktuell halten
Die von uns berechneten Werte sind nicht eingefroren. Sie werden mit der Zeit besser – eine Zutat wird genauer zugeordnet, Hintergrunddaten werden aktualisiert. Ein Produkt, das Sie vor Monaten hochgeladen haben, kann heute einen besseren CO₂-Wert haben.
GET /products gibt die ids Ihrer Produkte zurück. Ergänzen Sie updated-since mit dem Datum Ihrer letzten Synchronisation, dann erhalten Sie nur die Produkte, die sich erneut abzurufen lohnen:
GET /products?updated-since=2026-07-01
{
"products": ["carrot-puree-500g", "tomato-sauce-400g"]
}
Das sind: die Produkte, die Sie geändert haben, die noch nie berechneten und jene, deren Werte sich verschoben haben können, weil sich etwas verbessert hat, worauf sie beruhen. Rufen Sie jedes mit GET /products/{id} ab. Ein über POST /products/batch hochgeladenes Produkt verhält sich in diesem Feed genau wie eines, das mit einem einzelnen PUT hochgeladen wurde.
Ein gemeinsamer ID-Namensraum
Produkte und gewöhnliche Zutaten teilen sich einen einzigen id-Namensraum: Eine id gehört entweder einem Produkt oder einer Zutat, nie beiden zugleich. GET /products/{id} gibt zurück, was die id gerade belegt, und das Feld type sagt Ihnen, was es ist:
type | Was die id belegt |
|---|---|
products | Ein Produkt. Es ändert sich nur über die Produkt-Endpoints. |
conceptual-ingredients | Eine gewöhnliche Zutat. Ein Rezept oder Einkauf definiert sie, und jedes Rezept und jeder Einkauf kann sie ändern. |
Ein Rezept oder Einkauf, der eine id sendet, ändert die gewöhnliche Zutat unter dieser id, nie ein Produkt. Um ein Produkt unter einer id zu speichern, die bereits eine gewöhnliche Zutat belegt, setzen Sie convert-ingredient-to-product=true.
Produkt-Eigenschaften
Request-Eigenschaften
| Eigenschaft | Typ | Pflicht | Beschreibung |
|---|---|---|---|
id | String | Ja | Ihre eindeutige Produkt-ID |
names | Array | Ja | Produktname als Array von Sprachobjekten: [{"language": "de", "value": "Karottenpüree"}] |
ingredients-declaration | String | Empfohlen | Zutatenliste wie auf der Verpackung deklariert. Wird ausgewertet, um zu bestimmen, woraus das Produkt besteht. |
nutrient-values | Object | Empfohlen | Nährwerte pro 100g wie auf der Verpackung deklariert (siehe Referenz) |
gtin | String | Empfohlen | Global Trade Item Number (www.gtin.info) |
amount | Float | Empfohlen | Menge des Produkts in der angegebenen Einheit. Ohne Angabe gilt der Fussabdruck für ein Kilogramm. |
unit | String | Nein | Einheit: kg, gram oder liter. Standard: gram |
producer | String | Empfohlen | Hersteller oder Marke des Produkts |
date | String | Nein | Produktionsdatum für saisonale Berechnungen. Format: YYYY-MM-DD |
origin | String | Empfohlen | Produktionsort: Postadresse oder Land |
transport | String | Empfohlen | Transportmittel: air oder ground |
production | String | Empfohlen | Produktionsweise: standard, greenhouse, organic, fair-trade, farm, wild-caught, sustainable-fish |
processing | String | Nein | Verarbeitungsstufe: raw, unboned, boned, skinned, beheaded, fillet, cut, boiled, peeled |
conservation | String | Empfohlen | Konservierungsart: fresh, frozen, dried, conserved, canned, boiled-down |
packaging | String | Nein | Verpackungsart: none, plastic, paper, pet, tin, alu, glas, cardboard, tetra |
Response-Eigenschaften
Das Produkt wird unter product zurückgegeben, zusammen mit einem statuscode, der angibt, ob es berechnet werden konnte.
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
statuscode | Integer | 200, wenn das Produkt berechnet wurde. Siehe Statuscodes. |
message | String | Erklärt den statuscode, wenn er nicht 200 ist |
product-id | String | Die ID des Produkts, zu dem dieser Eintrag gehört |
product | Object | Das Produkt und seine berechneten Werte (unten) |
| Eigenschaft | Typ | Beschreibung |
|---|---|---|
id | String | Produkt-ID |
type | String | products (schreibgeschützt) oder conceptual-ingredients (jedes Rezept darf sie überschreiben) |
names | Array | Produktnamen als Array von Sprachobjekten |
co2-value | Integer | CO₂-Emissionen in Gramm CO₂e für die angegebene amount (siehe Hinweis unten) |
rating | String | CO₂-Bewertung (A-E). A ist am besten, E am schlechtesten. |
eaternity-award | Boolean | true, wenn das Produkt klimafreundlich ist |
co2-value-improvement-percentage | Float | Vergleich des CO₂-Fussabdrucks dieses Produkts pro Food Unit mit dem Durchschnitt |
co2-value-reduction-value | Float | Eingesparte Gramm CO₂ im Vergleich zu einem durchschnittlichen Produkt mit gleichem Nährwert |
food-unit | Float | Nährwert des Produkts für die angegebene amount |
amount | Float | Produktmenge, aus Ihrem Request zurückgegeben |
unit | String | Masseinheit |
gtin | String | Global Trade Item Number |
date | String | Produktionsdatum |
ingredients-declaration | String | Der ursprüngliche Text der Zutatenliste (wenn ingredients-declaration=true gesetzt ist) |
nutrient-values-estimated-per-specified-amount | Object | Vom Backend geschätzte Nährwerte, skaliert auf die angegebene Menge (wenn nutrient-values=true gesetzt ist) |
indicators | Object | Umweltindikatoren (wenn indicators=true gesetzt ist) |
co2-value und food-unit werden für die amount (und unit) in Ihrem Request berechnet – die zehnfache Menge ergibt den zehnfachen Fussabdruck. 500 gram und 0.5 kilogram ergeben dasselbe Resultat. Senden Sie keine Menge, gilt der Fussabdruck für ein Kilogramm.
Wenn Sie das Produkt stattdessen in einem Rezept referenzieren, skaliert die amount auf dieser Rezeptzeile – die eigene amount des Produkts wird nicht übernommen.
Response-Beispiel
{
"statuscode": 200,
"message": "",
"request-id": 0,
"product-id": "carrot-puree-500g",
"product": {
"food-unit": 0.62,
"eaternity-award": true,
"co2-value": 77,
"rating": "A",
"co2-value-improvement-percentage": 84,
"co2-value-reduction-value": 403,
"id": "carrot-puree-500g",
"gtin": "00123456789023",
"names": [{"language": "de", "value": "Karottenpüree"}],
"amount": 500.0,
"unit": "gram",
"producer": "ACME Foods",
"origin": "",
"transport": "",
"production": "",
"processing": "",
"conservation": "",
"packaging": "",
"type": "products"
}
}
Statuscodes
Neben den üblichen Statuscodes verwenden Produkte:
| Code | Bedeutung | Was zu tun ist |
|---|---|---|
| 612 | Das referenzierte Produkt existiert nicht | Speichern Sie zuerst das Produkt und senden Sie dann das Rezept |
| 613 | Ein Schreibvorgang, den ein Produkt nicht akzeptiert – entweder hat ein Rezept versucht, unter der id eines Produkts eine Zutat zu definieren, oder ein Schreibvorgang für ein Produkt würde eine bestehende Zutat umwandeln | Referenzieren Sie das Produkt mit type: "products", statt es zu definieren. Um eine Zutat bewusst umzuwandeln, ergänzen Sie convert-ingredient-to-product=true. |
Randnotiz: Produkte und Zutaten
Ein Produkt und eine Zutat beschreiben dasselbe: ein Lebensmittel mit Name, Menge und Attributen wie Herkunft, Produktionsweise und Konservierung. Sie unterscheiden sich darin, wie sie gespeichert werden. Ein Produkt wird einmal unter seiner eigenen id gespeichert und ändert sich nur über die Produkt-Endpoints. Eine Zutat wird innerhalb eines Rezepts oder eines Einkaufs definiert.
Endpoints
📄️ List products
Returns the ids of all products stored for your account.
📄️ Create or update a batch of products
Create or update many products in a single request - the recommended way to upload a product
📄️ Create or update a product
Create or update a single product. The response already contains the finished calculation, so
📄️ Get a product
Retrieve a product together with its calculated values.
📄️ Delete a product
Delete a product. Like the read, this also resolves an ordinary ingredient stored under this