API Reference

This page provides a complete reference for all field values, enumerations, and response structures in the Eaternity API.

Query Parameters

These parameters can be added to most API endpoints to control the response:

full-resource

Value	Default	Description
true	No	Returns complete JSON response with all fields
false	Yes	Returns minimal response (saves bandwidth)

When to use: Set full-resource=true when you need all calculated values. Use false (default) for faster responses when you only need the core metrics (rating, co2-value).

Fields included only with full-resource=true:

• Detailed ingredient breakdowns
• All nutrient values
• Improvement percentages
• Reduction values

indicators

Value	Default	Description
true	No	Includes VitaScore and environmental indicators
false	Yes	Excludes additional indicators

When to use: Set indicators=true when you need nutritional scoring (VitaScore) or environmental metrics (water footprint, rainforest, animal welfare, seasonality, local sourcing).

Additional fields when indicators=true:

• vita-score-points, vita-score-rating, vita-score-award
• water-footprint-rating, scarce-water-liters
• rainforest-label, rainforest-rating
• animal-treatment-label, animal-treatment-rating
• season-label, season-rating
• local-label, local-rating

nutrient-values

Value	Default	Description
true	No	Includes nutrient-values-estimated-per-specified-amount for each ingredient
false	Yes	Excludes nutrient value estimates

ingredients-declaration

Value	Default	Description
true	No	Includes parsed ingredients-declaration data for each ingredient
false	Yes	Excludes ingredient declaration data

return-uids

Value	Default	Description
true	No	Includes internal uid fields in response for recipes and ingredients
false	Yes	Excludes internal UIDs

transient (query parameter)

Value	Default	Description
true	No	Recipe is calculated but not permanently stored — it will not appear in monthly reports or statistics.
false	Yes	Recipe is saved normally and included in reports

transient has two meanings

As a query parameter, transient=true means the recipe is calculated but not permanently stored. As a body field in batch requests, "transient": true means the recipe is saved but excluded from the monthly summary. Both are valid for sub-recipes, test submissions, or any recipe you do not want included in reports.

---

Ingredient Field Values

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: ground

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

Default: standard

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

Default: raw

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

Default: fresh

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

Default: none

unit

The measurement unit for the ingredient amount.

Value	Description
gram	Weight in grams
liter	Volume in liters

Default: gram

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".

---

Response Fields

CO₂ Metrics

Field	Type	Description
co2-value	integer	CO₂ emissions in grams CO₂e per serving
rating	string	Climate rating from A (best) to E (worst)
eaternity-award	boolean	true if recipe is climate-friendly (rating A)
co2-value-improvement-percentage	number	Percentage better than average for this food category
co2-value-reduction-value	number	Grams of CO₂ saved compared to category average

Rating Scale

Rating	CO₂ per Portion	Description
A	≤ 400g	Excellent - Very low environmental impact
B	401-600g	Good - Low environmental impact
C	601-1000g	Average - Moderate environmental impact
D	1001-1500g	Below Average - High environmental impact
E	> 1500g	Poor - Very high environmental impact

Ingredient Response Fields

These fields are returned for each ingredient when full-resource=true:

Field	Type	Description
rating	string	CO₂ rating for this ingredient (A-E). A is best, E is worst.
co2-value	integer	Absolute CO₂ emissions for the ingredient in grams for the specified amount
co2-value-improvement-percentage	float	Comparison of this ingredient'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
bar-chart	number	Percentage contribution of this ingredient to total recipe CO₂ (0-100)
foodUnit	number	Nutritional density value used for CO₂ per nutrition calculations
nutrient-values-estimated-per-specified-amount	object	Backend-estimated nutrient values for the specified amount (when nutrient-values=true is set)

foodUnit Explained

The foodUnit represents the nutritional value of a food item, used to calculate CO₂ emissions per unit of nutrition rather than per gram. This ensures fair comparison between foods with different caloric densities.

---

Vita Score

The Vita Score rates nutritional quality on an A-E scale based on health risk factors.

Core Fields

Field	Type	Description
vita-score-points	number	Total points (lower is healthier)
vita-score-rating	string	Rating A (healthiest) to E
vita-score-award	boolean	true if recipe achieves A or B rating
energy-kcals	number	Total calories
nutrition-label	boolean	true if nutritionally balanced

Risk Factor Fields

Each risk factor has two fields: {factor}-risk-factor-amount-gram (amount) and {factor}-risk-factor-points (health impact points).

Risk Factor	Healthy Direction	Description
fruit	More is better	Fruit content
vegetable	More is better	Vegetable content
wholegrain	More is better	Whole grain content
nuts-seeds	More is better	Nuts and seeds
milk	Moderate	Dairy products
processed-meat	Less is better	Processed meat products
red-meat	Less is better	Red meat content
salt	Less is better	Sodium content

Macronutrient Risk Points

Field	Description
high-in-energy-risk-factor-points	Points for high calorie density
high-in-fat-risk-factor-points	Points for high fat content
low-in-fat-risk-factor-points	Points for insufficient fat
high-in-protein-risk-factor-points	Points for excess protein
low-in-protein-risk-factor-points	Points for insufficient protein

---

Environmental Indicators

Additional environmental impact metrics beyond CO₂. Enable with indicators=true.

All calculations use Life Cycle Assessment (LCA) methodology following ISO 14040/14044 standards, with peer-reviewed scientific data covering the complete supply chain from farm to plate.

CO₂ Interpretation

CO₂ values measure total greenhouse gas emissions in grams of CO₂-equivalent, including CO₂, methane (CH₄, 28x more potent), and nitrous oxide (N₂O, 265x more potent).

CO₂ per Portion	Category	Environmental Impact
< 400g	Excellent	Very low climate impact
400-600g	Good	Low climate impact
600-1000g	Average	Moderate climate impact
1000-1500g	Below Average	High climate impact
> 1500g	Poor	Very high climate impact

Major emission sources: Agriculture (40-70%), Animal Production (20-50%), Transport (5-15%), Processing (5-10%), Storage (2-5%).

Water Footprint

Field	Type	Description
scarce-water-liters	number	Liters of scarce water used
water-footprint-rating	string	A-E rating for water use
water-footprint-award	boolean	true for excellent water efficiency
water-footprint-improvement-percentage	number	% better than average
water-footprint-reduction-value	number	Liters saved vs average

Water per Portion	Category
< 100L	Very low
100-500L	Low
500-1000L	Moderate
1000-2000L	High
> 2000L	Very high

Animal Treatment

Assessment of animal welfare standards for animal-derived ingredients.

Rating	Description	Standards
excellent	Highest welfare standards	Free-range, organic, certified humane
good	Above-average welfare	Cage-free, enriched housing
medium	Standard practices	Conventional farming
poor	Below standard welfare	Intensive/factory farming
very-poor	Welfare concerns	Cramped conditions, no outdoor access
not-applicable	No animal products	Vegan/vegetarian items

Rainforest Impact

Risk of deforestation associated with ingredients.

Rating	Risk Level	Common Ingredients
very-low	Negligible risk	Local vegetables, grains
low	Minimal risk	Certified sustainable palm oil, cocoa
medium	Moderate risk	Some tropical fruits, nuts
high	Significant risk	Uncertified palm oil, beef from Brazil
very-high	Severe risk	Soy from deforested areas

Biodiversity Impact

Effect on ecosystems and species diversity.

Rating	Impact	Contributing Factors
very-low	Minimal impact	Organic, diverse cropping, habitat-friendly
low	Low impact	Sustainable practices, crop rotation
medium	Moderate impact	Conventional monoculture
high	Significant impact	Pesticide-intensive, habitat destruction
very-high	Severe impact	Large-scale monoculture, deforestation

Energy Consumption

Total energy use throughout the supply chain, measured in Megajoules (MJ) per portion.

Energy per Portion	Category
< 1 MJ	Very low
1-3 MJ	Low
3-6 MJ	Moderate
6-10 MJ	High
> 10 MJ	Very high

Soil Impact

Effect on soil health and degradation.

Rating	Impact	Practices
very-low	Soil building	Regenerative agriculture, no-till
low	Minimal degradation	Organic, cover crops
medium	Some degradation	Conventional farming, rotation
high	Significant degradation	Intensive monoculture, heavy tillage
very-high	Severe degradation	Erosion-prone practices

Sustainability Labels

Each indicator has a {name}-label (boolean) and {name}-rating (A-E):

Indicator	Label Meaning	What It Measures
rainforest	Deforestation-free	Avoids rainforest destruction
animal-treatment	Welfare certified	Meets animal welfare standards
season	In season	Ingredient is in season locally
local	Locally produced	Produced within region

---

Nutrient Values

The nutrient-values object supports 42 nutritional fields. All are optional - provide what you have.

Basic Macronutrients

Field	Unit	Description
energy-kcal	kcal	Energy in kilocalories
energy-kjoule	kJ	Energy in kilojoules
fat-gram	g	Total fat
saturated-fat-gram	g	Saturated fat
monounsaturated-fat-milligram	mg	Monounsaturated fat
polyunsaturated-fat-milligram	mg	Polyunsaturated fat
cholesterol-milligram	mg	Cholesterol
carbohydrates-gram	g	Total carbohydrates
sucrose-gram	g	Sugars
protein-gram	g	Protein
fibers-gram	g	Dietary fiber
water-gram	g	Water content
sodium-chloride-gram	g	Salt
alcohol-volume-percent	%	Alcohol content

Vitamins

Field	Unit	Vitamin
vitamine-a1-microgram	mcg	Vitamin A (retinol)
vitamine-b1-microgram	mcg	Vitamin B1 (thiamine)
vitamine-b2-microgram	mcg	Vitamin B2 (riboflavin)
vitamine-b6-microgram	mcg	Vitamin B6 (pyridoxine)
vitamine-b12-microgram	mcg	Vitamin B12 (cobalamin)
vitamine-c-milligram	mg	Vitamin C
vitamine-d-microgram	mcg	Vitamin D
vitamine-e-microgram	mcg	Vitamin E (tocopherol)
vitamine-h-microgram	mcg	Vitamin H (biotin)
vitamine-k-microgram	mcg	Vitamin K
beta-carotene-milligram	mg	Beta-carotene
niacin-milligram	mg	Niacin (B3)
pantohen-milligram	mg	Pantothenic acid (B5)
folic-acid-microgram	mcg	Folic acid (B9)

Minerals

Field	Unit	Mineral
sodium-milligram	mg	Sodium
potassium-milligram	mg	Potassium
chlorine-milligram	mg	Chlorine
calcium-milligram	mg	Calcium
magnesium-milligram	mg	Magnesium
phosphorus-milligram	mg	Phosphorus
iron-milligram	mg	Iron
zinc-microgram	mcg	Zinc
copper-microgram	mcg	Copper
manganese-microgram	mcg	Manganese
flouride-microgram	mcg	Fluoride
iodine-microgram	mcg	Iodine

Other Compounds

Field	Unit	Description
purine-milligram	mg	Purine content
uric-acid-milligram	mg	Uric acid

---

Recipe Special Fields

transient

Value	Description
true	Recipe excluded from monthly summaries and reports
false	Recipe included in all statistics (default)

Use cases: Set transient: true for sub-recipes (sauces, stocks, bases) that are components of other recipes, or for any recipe you do not want included in reports. Transient recipes only count toward statistics when used as ingredients in non-transient recipes.

type (Ingredient)

Value	Description
conceptual-ingredients	A regular ingredient
recipes	References another recipe as a sub-recipe

Default: conceptual-ingredients

---

Data Sources

Eaternity's calculations use data from:

Environmental Databases

• ecoinvent: Life cycle inventory database
• AGRIBALYSE: French agricultural LCA database
• WFLDB: Water Footprint Database
• Eaternity Database: Proprietary ingredient database with 50,000+ entries

Nutritional Databases

• USDA FoodData Central: US nutrient database
• Swiss Food Composition Database: Swiss nutrient data
• EuroFIR: European food information resource

Certifications & Standards

• ISO 14040/14044: LCA methodology
• ISO 14046: Water footprint
• ISO 14067: Carbon footprint of products
• PEF (Product Environmental Footprint): EU methodology