Ingredients

Recipes, supplies and products are lists of ingredients. All three use the same ingredient object, described on this page.

• A recipe lists its ingredients under ingredients. See Recipes.
• A supply lists the delivered articles under ingredients. See Supplies.
• A product is an ingredient you store once and reference from many recipes. See Products.

Topic	Section
Example	Ingredient Schema
Fields you must send	Required Properties
Fields that improve the result	Optional Core Properties
Allowed values: origin, transport, production, processing, conservation, packaging, unit	Ingredient Field Values
Define or reference an ingredient	Ingredient Types
What comes back per ingredient	Ingredient Response Fields
How names are matched	Ingredient Matching

Ingredient Schema

{
  "id": "tomatoes-001",
  "names": [
    {"language": "en", "value": "Cherry Tomatoes"},
    {"language": "de", "value": "Kirschtomaten"}
  ],
  "amount": 200,
  "unit": "gram",
  "origin": "Italy",
  "transport": "ground",
  "production": "organic",
  "conservation": "fresh",
  "packaging": "plastic",
  "producer": "BioFarm AG"
}

Required Properties

Property	Type	Required	Description
id	String	Yes	Unique ingredient identifier within recipe (max 255 chars)
names	Array	Yes	Ingredient name in at least one language, as array of language objects: [{"language": "en", "value": "..."}]. Used for database matching.
amount	Float	Yes	Quantity of ingredient (must be > 0)
unit	String	Yes	Measurement unit (gram or liter)

Optional Core Properties

Reduce Ambiguity

To reduce ambiguity and minimize manual follow-ups, we strongly recommend specifying certain ingredient attributes even if technically optional. These include indicators such as air-freighted, fresh, deep-frozen, dried, preserved, baked, canned, boiled, organic, Fairtrade certified, and aquaculture-sourced (for fish). Providing this data up front helps prevent incorrect assumptions and eliminates the need for iterative clarification.

Property	Type	Default	Description
type	String	conceptual-ingredients	Whether this line defines an ingredient or references one that is already stored. See Ingredient Types.
loss-in-percent-of-amount	Float	-	Food loss as percentage of the ingredient amount (0–100), for example through peeling, trimming, or spoilage. The environmental impact is calculated for the full specified amount, while only the remaining net amount (amount × (1 − loss / 100)) counts towards the recipe's weight and nutrient values. Preferred over adjusting the recipe weight field for modeling losses.
origin	String	-	Origin of the ingredient: postal address or country
transport	String	-	Means of transport from origin to kitchen: air or ground
production	String	-	Production method: standard, greenhouse, organic, fair-trade, farm, wild-caught, sustainable-fish
processing	String	-	Processing level: raw. Meat/fish: unboned, boned. Fish: skinned, beheaded, fillet. Vegetables/fruits: cut, boiled, peeled.
conservation	String	-	Conservation method: fresh, frozen, dried, conserved, canned, boiled-down
packaging	String	-	Packaging type: none, plastic, paper, pet, tin, alu, glas, cardboard, tetra
producer	String	-	Producer or brand of the product. Especially important for combined products (products with multiple ingredients).
gtin	String	-	Global Trade Item Number (barcode) for packaged products
ingredients-declaration	String	-	Ingredient list as declared on packaged foods
nutrient-values	Object	-	Structured nutrient values per 100g (see Reference)

Allowed values, defaults and multiple values per field: Ingredient Field Values.

Ingredient Field Values

The attributes below describe where an ingredient comes from and how it is produced, processed, conserved and packed. They are optional, but each one makes the result more precise.

origin

Where the ingredient was produced. This drives transport-distance and seasonality calculations.

Format	Example	Description
Country	"Italy"	Country of production
Postal address	"8005 Zurich, Switzerland"	Specific location for precise transport distances

Default: If omitted, a representative origin is estimated from the ingredient and the kitchen location.

transport

How the ingredient is transported from origin to the kitchen.

Value	Description	CO₂ Impact
ground	Road, rail, or ship transport	Lower
air	Air freight	Higher (10-50x ground)

Default: none. If omitted, the transport mode is estimated from origin and destination.

production

The production method used to grow or produce the ingredient.

Value	Description
standard	Conventional farming/production
greenhouse	Grown in heated greenhouse
organic	Certified organic production
fair-trade	Fair trade certified
farm	Small-scale farm production
wild-caught	Wild-caught (seafood)
sustainable-fish	Sustainably certified fishing

processing

The level of processing applied to the ingredient.

Value	Description
raw	Unprocessed, whole ingredient
unboned	With bones (meat/fish)
boned	Bones removed
skinned	Skin removed
beheaded	Head removed (fish)
fillet	Filleted (meat/fish)
cut	Cut into pieces
boiled	Pre-cooked by boiling
peeled	Outer layer removed

conservation

How the ingredient is preserved/stored.

Value	Description	Energy Impact
fresh	No preservation, short shelf life	Lowest
frozen	Frozen storage	Higher (cold chain)
dried	Dehydrated	Low
conserved	Preserved (salt, sugar, etc.)	Low
canned	Sealed in cans	Medium
boiled-down	Reduced/concentrated	Medium

packaging

The packaging material used.

Value	Description
none	No packaging (bulk)
plastic	Plastic packaging
paper	Paper/cardboard
pet	PET plastic bottles
tin	Tin cans
alu	Aluminum
glas	Glass containers
cardboard	Cardboard boxes
tetra	Tetra Pak cartons

unit

The measurement unit for the ingredient amount.

Value	Description
gram	Weight in grams
liter	Volume in liters

Unit Conversion

Always convert to grams or liters:

• 1 kg = 1000 grams
• 1 ml = 0.001 liters
• 1 oz ≈ 28.35 grams
• 1 cup ≈ 240 ml = 0.24 liters

Multi-Value Fields

The origin, transport, production, processing, conservation, and packaging fields accept comma-separated values when multiple apply. For example: "production": "organic, fair-trade".

Ingredient Types

Every ingredient has a type. It decides what the ingredient refers to — and whether saving the recipe also writes the object that id names.

type	Refers to	Saving the recipe writes that object?	If the id does not exist
conceptual-ingredients (default)	an ingredient defined inline	Yes — created, or overwritten for every recipe already using that id	It is created
recipes	a stored recipe (a sub-recipe)	No	612
products	a stored product	No	612 (incl. an id that is only an ingredient)

// DEFINE an ingredient, here and now (default)
{
  "id": "rice-001",
  "type": "conceptual-ingredients",
  "names": [{"language": "en", "value": "Risotto rice"}],
  "amount": 200,
  "unit": "gram"
}

// REFERENCE a stored recipe (sub-recipe)
{
  "id": "tomato-sauce-001",
  "type": "recipes",
  "amount": 150,
  "unit": "gram"
}

// REFERENCE a stored product -- no name needed, just the id and how much goes in
{
  "id": "carrot-puree-500g",
  "type": "products",
  "amount": 300,
  "unit": "gram"
}

Only conceptual-ingredients writes: reuse an id with it and your data replaces whatever was there, for every recipe using that id. For an article you reuse, store it once as a product and reference it instead.

Ingredient Response Fields

See Ingredient Response Fields.

Ingredient Matching

The API uses fuzzy matching to identify ingredients in Eaternity's database of 50,000+ entries.

How Matching Works:

1. Name normalization: Removes special characters, normalizes spelling
2. Database search: Searches 50,000+ ingredient entries
3. Similarity scoring: Calculates match confidence (0-100%)
4. Best match selection: Returns highest-confidence match
5. Fallback: Uses generic category if no close match found

Improving Match Quality:

• Use specific names: "Parmesan Cheese" instead of "Cheese"
• Include preparation method: "Fresh Cherry Tomatoes" instead of "Tomatoes"
• Specify cut or form: "Beef Sirloin Steak" instead of "Beef"
• Add brand via producer field for packaged items