Products

The Product API calculates environmental impact for packaged retail products based on their mandatory ingredient and nutrient declarations.

Overview

Use the Product API to:

• Calculate CO2 footprint for retail products using ingredient declarations
• Assess packaged foods based on nutrient information
• Get environmental ratings for consumer products

Coordination Required

We only recommend using the Product Resources in tight coordination with the Eaternity team, as the calculations require additional supervision. Products are processed asynchronously — the API parses the ingredient declaration and builds a recipe-like structure to serve the usual indicators.

Product vs Recipe

Products are for retail items with ingredient declarations on their packaging (e.g., packaged carrot puree). The API parses the declaration text to derive composition. Recipes are for meals prepared in kitchens where you know the exact ingredients and amounts.

Product Properties

Request Properties

Property	Type	Required	Description
id	String	Yes	Your unique product identifier
gtin	String	Best practice	Global Trade Item Number (www.gtin.info)
names	Array	Yes	Product name as array of language objects: [{"language": "de", "value": "Karottenpuree"}]
amount	Float	Best practice	Amount of the product in the specified unit. Default: 100
unit	String	No	Unit: kg, gram, or liter. Default: gram
producer	String	Best practice	The producer or brand of the product
date	String	No	Production date for seasonal calculations. Format: YYYY-MM-DD
ingredients-declaration	String	Yes	List of ingredients as declared on packaging (in German). The API parses this text to determine product composition.
nutrient-values	Object	Yes	Nutrient values per 100g as declared on packaging (see Reference)
origin	String	Best practice	Production location: postal address or country
transport	String	Best practice	Means of transport: air or ground
production	String	Best practice	Production method: standard, greenhouse, organic, fair-trade, farm, wild-caught, sustainable-fish
processing	String	No	Processing level: raw, unboned, boned, skinned, beheaded, fillet, cut, boiled, peeled
conservation	String	Best practice	Storage method: fresh, frozen, dried, conserved, canned, boiled-down
packaging	String	No	Packaging type: none, plastic, paper, pet, tin, alu, glas, cardboard, tetra

Request Example

{
  "id": "180320201",
  "date": "2020-02-02",
  "gtin": "00123456789023",
  "names": [
    {
      "language": "de",
      "value": "Karottenpuree"
    }
  ],
  "amount": 20,
  "unit": "gram",
  "producer": "hipp",
  "ingredients-declaration": "Karotten, Tomaten",
  "nutrient-values": {
    "energy-kcal": 200,
    "fat-gram": 12.3,
    "saturated-fat-gram": 2.5,
    "carbohydrates-gram": 8.4,
    "sucrose-gram": 3.2,
    "protein-gram": 2.2,
    "sodium-chloride-gram": 0.3
  },
  "origin": "paris, frankreich",
  "transport": "ground",
  "production": "standard",
  "processing": "raw",
  "conservation": "fresh",
  "packaging": "none"
}

Async Processing

Products are processed asynchronously:

1. Create a product via PUT /products/{id} — returns 202 Accepted
2. Retrieve results via GET /products/{id}:
   • Returns 601 with message "This product has not yet been processed." if still processing
   • Returns 202 with full results once processing is complete

Response Properties

Property	Type	Description
names	Array	Product names as array of language objects
id	String	Product identifier
co2-value	Integer	CO₂ emissions in grams CO₂e for the specified amount
rating	String	CO₂ rating (A-E). A is best, E is worst.
eaternity-award	Boolean	true if the product is climate friendly
co2-value-improvement-percentage	Float	Comparison of this product's CO₂ footprint per food unit to the average
co2-value-reduction-value	Float	Grams of CO₂ saved compared to an average product providing the same nutritional value
foodUnit	Float	Nutritional value of the product for the given amount
amount	Float	Product amount
gtin	String	Global Trade Item Number
unit	String	Unit of measurement
date	String	Production date
info-text	String	Notes on the calculation (e.g., "No cooking date was provided.")
ingredients-declaration	String	The original ingredient declaration text
ingredients	Array	Parsed ingredients with individual ratings and CO₂ values
nutrient-values-estimated-per-specified-amount	Object	Backend-estimated nutrient values scaled to the specified amount (when nutrient-values=true parameter is set)
indicators	Object	Environmental indicators (when indicators=true parameter is set)

Response Example

{
  "names": [
    {
      "language": "de",
      "value": "Karottenpuree"
    }
  ],
  "id": "180320201",
  "co2-value": 478,
  "co2-value-improvement-percentage": -41.0,
  "co2-value-reduction-value": -140.0,
  "foodUnit": 0.3,
  "amount": 20,
  "gtin": "00123456789023",
  "unit": "gram",
  "info-text": "No cooking date was provided.",
  "eaternity-award": true,
  "rating": "A",
  "date": "2020-02-02",
  "ingredients-declaration": "Karotten, Tomaten",
  "ingredients": [
    {
      "id": "FoodServiceb7a7f176-690b-11ea-9516-ae471177f174",
      "names": [
        {
          "language": "de",
          "value": "Karotten"
        }
      ],
      "amount": 100.0,
      "unit": "gram",
      "origin": "",
      "transport": "",
      "gtin": "",
      "rating": "A",
      "bar-chart": 100,
      "co2-value": 32,
      "foodUnit": 0.11
    }
  ]
}

Endpoints

📄️ Create or update a product

Create or update a retail food product.

📄️ Get a product

Retrieve a product with calculated CO₂ values.