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

---

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

---

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 or B)
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	Description	Typical CO₂ Range
A	Excellent - very low emissions	< 500g CO₂e
B	Good - below average emissions	500-1000g CO₂e
C	Average emissions	1000-1500g CO₂e
D	Above average emissions	1500-2500g CO₂e
E	High emissions	> 2500g CO₂e

Ranges are approximate and vary by food category.

Ingredient Response Fields

Field	Type	Description
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

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

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

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 (use for sub-recipes)
false	Recipe included in all statistics (default)

Use case: Set transient: true for sub-recipes (sauces, stocks, bases) that are components of other recipes. They 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