Eaternity API
The Eaternity Database API is a Web Service that calculates the Climate Score (CO₂ equivalents), the Vita Score and other environmental footprints of recipes, restaurants, and ingredients dynamically.
It includes daily changing information on origin, seasonality and other factors in the calculation.
This is the API for kitchens, caterers and their software. For research-grade life cycle assessment (LCA), see Choosing Your API.
Use Cases
Software partners connect to the Eaternity API in three ways. Recipe impact assessment puts the Climate Score and Vita Score of a recipe right next to it while a chef writes it. Menus carry every dish a kitchen serves, with its date, so the menu plan can show the rating and the Eaternity reports can count the dish. Supplies report what the kitchen bought, which makes its footprint more precise. Many integrations combine menus and supplies.
Each use case starts from a kitchen; the examples use kitchen-restaurant-a. Recipes, menus and supplies all carry their content as ingredients. Every ingredient field is described on one page: Ingredients.
Recipe impact assessment
A chef adjusts a recipe in the recipe-management software, and its CO₂ value updates alongside. This is the leanest integration: one request per recipe, one response with the values per portion. The response holds the Climate Score as co2-value in grams CO₂e and a rating from A to E; recipes rated A carry the Eaternity Award. With indicators=true it adds the Vita Score and the environmental indicators for water footprint, rainforest, animal treatment, season and local sourcing. For a preview that is calculated but not kept, add transient=true; see Transient Recipes.
What to send: titles, date and the ingredients, each with id, names, amount and unit. The amounts describe one portion unless recipe-portions says otherwise. Origin, transport, production and conservation of each ingredient sharpen the result; where origin and transport are missing, Eaternity estimates them.
Endpoints: PUT /kitchens/{kitchen_id}/recipes/{recipe_id} to send, GET /kitchens/{kitchen_id}/recipes/{recipe_id} to read the result again.
One portion of pasta, five ingredients:
{
"recipe": {
"kitchen-id": "kitchen-restaurant-a",
"titles": [{"language": "de", "value": "Pasta aglio e olio"}],
"date": "2026-09-16",
"location": "6500 Bellinzona, Switzerland",
"production-portions": 15,
"sold-portions": 0,
"ingredients": [
{"id": "article-101", "names": [{"language": "de", "value": "Olivenöl"}], "amount": 30, "unit": "gram"},
{"id": "article-102", "names": [{"language": "de", "value": "Nudeln"}], "amount": 100, "unit": "gram"},
{"id": "article-103", "names": [{"language": "de", "value": "Knoblauch"}], "amount": 20, "unit": "gram"},
{"id": "article-104", "names": [{"language": "de", "value": "Peperoncini"}], "amount": 5, "unit": "gram"},
{"id": "article-105", "names": [{"language": "de", "value": "Petersilie (frisch)"}], "amount": 3, "unit": "gram"}
]
}
}
Per portion: 226 g CO₂e, rating A with the Eaternity Award, Vita Score B. The ingredient list stays empty unless the request adds full-resource=true.
Response
{
"statuscode": 200,
"message": "",
"request-id": 0,
"recipe-id": "pasta-aglio-e-olio-2026-09-16",
"recipe": {
"food-unit": 1.21,
"final-weight-per-portion": 158.0,
"indicators": {
"vita-score": {
"vita-score-points": 292.83,
"vita-score-rating": "B",
"vita-score-improvement-percentage": 13.87,
"energy-kcals": 655.48,
"nutrition-label": true,
"fruit-risk-factor-amount-gram": 0.0,
"fruit-risk-factor-points": 61.24,
"vegetable-risk-factor-amount-gram": 25.0,
"vegetable-risk-factor-points": 30.57,
"wholegrain-risk-factor-amount-gram": 0.0,
"wholegrain-risk-factor-points": 82.86,
"nuts-seeds-risk-factor-amount-gram": 0.0,
"nuts-seeds-risk-factor-points": 13.98,
"milk-risk-factor-amount-gram": 0.0,
"milk-risk-factor-points": 9.42,
"processed-meat-risk-factor-amount-gram": 0.0,
"processed-meat-risk-factor-points": 0.0,
"red-meat-risk-factor-amount-gram": 0.0,
"red-meat-risk-factor-points": 0.0,
"salt-risk-factor-amount-gram": 0.02,
"salt-risk-factor-points": 0.0,
"high-in-energy-risk-factor-points": 0.81,
"high-in-fat-risk-factor-points": 61.12,
"low-in-fat-risk-factor-points": 0.0,
"high-in-protein-risk-factor-points": 0.0,
"low-in-protein-risk-factor-points": 32.83
},
"environment": {
"scarce-water-liters": 106.12,
"water-footprint-rating": "D",
"water-footprint-reduction-value": -79.67,
"water-footprint-award": false,
"water-footprint-improvement-percentage": -301.18,
"rainforest-label": true,
"rainforest-rating": "A",
"animal-treatment-label": true,
"animal-treatment-rating": "A",
"season-label": false,
"season-rating": "E",
"local-label": false,
"local-rating": "E"
}
},
"eaternity-award": true,
"co2-value": 226,
"rating": "A",
"co2-value-improvement-percentage": 76,
"co2-value-reduction-value": 713,
"id": "pasta-aglio-e-olio-2026-09-16",
"kitchen-id": "kitchen-restaurant-a",
"titles": [{"language": "de", "value": "Pasta aglio e olio"}],
"date": "2026-09-16",
"location": "6500 Bellinzona, Switzerland",
"servings": 1,
"recipe-portions": 1,
"production-portions": 15,
"sold-portions": 0,
"ingredients": []
}
}
Read on: all recipe fields in Recipes, all ingredient fields and allowed values in Ingredients, how the values come about in Climate Score and Vita Score. Articles used in many recipes can be stored once as products.
Menus for menu plan display and reporting
Kitchen ERP and menu-planning systems work one level up: they send the menu plan. Every dish a kitchen serves on a given day is a menu with its own id, sent with its kitchen-id and date. Eaternity rates it like any recipe; the menu plan, or the screens in the restaurant, show the rating; and the dish enters the kitchen's Monthly Report. Once the kitchen software reports the sold portions after close of business, the Daily Report shows the previous day.
Production and sales figures decide how much each dish weighs in the reports: sold portions first, then produced portions, then recipe portions. With those figures, menus alone are a complete basis for reporting. Components such as a sauce or a side go in as sub-recipes with "transient": true: they count only through the menu that uses them. The menu itself carries "transient": false. A menu line (menu-line-name, menu-line-id) lets a report include or leave out a whole line.
What to send: kitchen-id, id, date, titles and ingredients, plus production-portions and sold-portions. A menu without date is still calculated but stays out of the reports.
Endpoints: POST /recipes/batch for the menus and their sub-recipes in one request, GET /kitchens/{kitchen_id}/recipes/{recipe_id} to read a result again, and POST /prognosis/{kitchen_id}/portions to add sold portions later, which also feeds Forecast.
How to choose menu ids is explained in Recipe ID Uniqueness.
A menu of 300 portions of Spätzle, 249 sold. The menu references a transient sub-recipe that holds the ingredients for all 300 portions; both go in one batch:
[
{
"request-id": 0,
"transient": false,
"recipe": {
"id": "menu-2026-09-29-spaetzle",
"kitchen-id": "kitchen-restaurant-a",
"titles": [{"language": "de", "value": "Spätzle"}],
"date": "2026-09-29",
"recipe-portions": 300,
"production-portions": 300,
"sold-portions": 249,
"ingredients": [
{"id": "spaetzle-150g-vegan", "type": "recipes", "amount": 45000, "unit": "gram"}
]
}
},
{
"request-id": 1,
"transient": true,
"recipe": {
"id": "spaetzle-150g-vegan",
"kitchen-id": "kitchen-restaurant-a",
"titles": [{"language": "de", "value": "Spätzle frisch (150g) (vegan)"}],
"date": "2026-09-29",
"recipe-portions": 300,
"ingredients": [
{"id": "article-201", "names": [{"language": "de", "value": "Salz"}], "amount": 90, "unit": "gram"},
{"id": "article-202", "names": [{"language": "de", "value": "Nudeln"}], "amount": 45000, "unit": "gram"},
{"id": "article-203", "names": [{"language": "de", "value": "Muskat"}], "amount": 30, "unit": "gram"},
{"id": "article-204", "names": [{"language": "de", "value": "Rapsöl"}], "amount": 1.5, "unit": "liter"}
]
}
}
]
Each item comes back with its own statuscode, matched by request-id. The menu has 143 g CO₂e per portion:
Response
[
{
"statuscode": 200,
"message": "",
"recipe-id": "menu-2026-09-29-spaetzle",
"request-id": 0,
"recipe": {
"food-unit": 0.99,
"final-weight-per-portion": 150.00000000000003,
"eaternity-award": true,
"co2-value": 143,
"rating": "A",
"co2-value-improvement-percentage": 81,
"co2-value-reduction-value": 628,
"id": "menu-2026-09-29-spaetzle",
"kitchen-id": "kitchen-restaurant-a",
"titles": [{"language": "de", "value": "Spätzle"}],
"date": "2026-09-29",
"servings": 300,
"recipe-portions": 300,
"production-portions": 300,
"sold-portions": 249,
"ingredients": []
}
},
{
"statuscode": 200,
"message": "",
"recipe-id": "spaetzle-150g-vegan",
"request-id": 1,
"recipe": {
"food-unit": 1.02,
"final-weight-per-portion": 155.0,
"eaternity-award": true,
"co2-value": 148,
"rating": "A",
"co2-value-improvement-percentage": 81,
"co2-value-reduction-value": 649,
"id": "spaetzle-150g-vegan",
"kitchen-id": "kitchen-restaurant-a",
"titles": [{"language": "de", "value": "Spätzle frisch (150g) (vegan)"}],
"date": "2026-09-29",
"servings": 300,
"recipe-portions": 300,
"ingredients": []
}
}
]
Read on: a menu with sub-recipes several levels deep and a menu line in the Sub-Recipe Composition Example, what transient means in Transient Recipes, batch sizes in Request Size Limits, and what kitchens see in the Monthly Report.
Supplies for supply-based reports
Purchasing and merchandise-management software, or a wholesaler's order data, records what actually arrived in the kitchen. Sent as supplies, these deliveries base the kitchen's footprint in the Eaternity reports on what was bought, a more precise basis than the menus alone. Supplies work with or without recipes.
Each supply is one delivery: a supply-date and a list of articles. The response gives every article its CO₂ value and rating and the delivery its total. GTIN, origin, transport, production and conservation of each article sharpen the result.
What to send: supply-date, the date the supply counts for in reports, and the articles as ingredients with id, names, amount and unit. Optional: supplier, supplier-id, invoice-id and order-date.
Endpoints: POST /supplies/batch for many deliveries at once, with kitchen-id in each supply, or PUT /kitchens/{kitchen_id}/supplies/{supply_id} for a single one.
One delivery of two articles:
{
"supply": {
"id": "delivery-2026-07-29-0118",
"supplier": "Meat wholesaler",
"supplier-id": "supplier-001",
"order-date": "2026-07-28",
"supply-date": "2026-07-29",
"ingredients": [
{
"id": "article-301",
"names": [{"language": "de", "value": "Poulet"}],
"amount": 10000,
"unit": "gram",
"origin": "Switzerland",
"transport": "ground",
"production": "standard",
"conservation": "fresh"
},
{
"id": "article-302",
"gtin": "7612345000015",
"names": [{"language": "de", "value": "Bratwurst"}],
"amount": 10000,
"unit": "gram"
}
]
}
}
The delivery totals 162,372 g CO₂e, the sum of its two articles:
Response
{
"statuscode": 200,
"message": "",
"request-id": 0,
"supply-id": "delivery-2026-07-29-0118",
"supply": {
"food-unit": 124.1,
"final-weight-per-portion": 20000.0,
"co2-value": 162372,
"rating": "C",
"co2-value-improvement-percentage": -68,
"co2-value-reduction-value": -65738,
"kitchen-id": "kitchen-restaurant-a",
"supplier": "Meat wholesaler",
"supplier-id": "supplier-001",
"order-date": "2026-07-28",
"supply-date": "2026-07-29",
"ingredients": [
{
"foodUnit": 61.04,
"co2-value": 44566,
"rating": "B",
"co2-value-improvement-percentage": 6,
"co2-value-reduction-value": 2963,
"bar-chart": 27,
"id": "article-301",
"type": "conceptual-ingredients",
"names": [{"language": "de", "value": "Poulet"}],
"amount": 10000.0,
"unit": "gram",
"origin": "Switzerland",
"transport": "ground",
"production": "standard",
"processing": "",
"conservation": "fresh",
"packaging": ""
},
{
"foodUnit": 63.06,
"co2-value": 117806,
"rating": "D",
"co2-value-improvement-percentage": -140,
"co2-value-reduction-value": -68700,
"bar-chart": 73,
"id": "article-302",
"type": "conceptual-ingredients",
"names": [{"language": "de", "value": "Bratwurst"}],
"amount": 10000.0,
"unit": "gram",
"origin": "",
"transport": "",
"production": "",
"processing": "",
"conservation": "",
"packaging": "",
"gtin": "7612345000015"
}
],
"id": "delivery-2026-07-29-0118"
}
}
Read on: all supply fields in Supplies, all article fields and allowed values in Ingredients, and batch sizes in Request Size Limits.
Field Index
Each field links to its definition.
| Level | Fields |
|---|---|
| Recipe | id · kitchen-id · titles · date · recipe-portions · ingredients · production-portions · sold-portions · menu-line-name · menu-line-id · transient · location · weight |
| Ingredient | id · names · amount · unit · type · origin · transport · production · processing · conservation · packaging · gtin · producer · loss-in-percent-of-amount · ingredients-declaration · nutrient-values |
| Supply | id · kitchen-id · supplier · supplier-id · invoice-id · order-date · supply-date · ingredients |
| Response | co2-value · rating · eaternity-award · info-text · indicators · vita-score |
| Query parameters | full-resource · indicators · nutrient-values · transient · return-uids |
Key Features
- Climate Score: Calculate CO₂ equivalents for recipes and ingredients
- Vita Score: Nutritional quality rating (A-E scale)
- Environmental Metrics: Water footprint, rainforest impact, animal welfare, seasonality, and local sourcing ratings
- Forecast: AI-powered sales predictions for kitchens
Terms & Conditions
By accessing the APIs, you accept Eaternity's Terms & Conditions.
Authentication
- HTTP: Basic Auth
Authentication
The Eaternity API uses HTTP Basic Authentication: the API key is the username, the password stays empty. The header is Authorization: Basic <base64(apikey:)>. To request a key, write to info@eaternity.ch.
Code examples for cURL, HTTP headers, Python and JavaScript: Authentication.
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | basic |
Contact Eaternity Team: info@eaternity.ch
License Proprietary
Choosing Your API
The Eaternity APIs serve different user groups with distinct requirements.
| Feature | Eaternity API | LCA API |
|---|---|---|
| Primary Users | Restaurants, Food Manufacturers, ERP Systems | LCA Practitioners, Researchers |
| Use Case | Operational sustainability tracking | Scientific LCA research |
| Data Granularity | Recipe/menu level | Full supply chain detail |
| Batch Processing | Optimized for high volume | Optimized for precision |
Choose the Eaternity API if you are a restaurant or food service operation, integrating with ERP or food management software, tracking menu sustainability metrics, or generating environmental reports for operations.
Choose the LCA API if you are an LCA practitioner or researcher, conducting detailed supply chain analysis, requiring full lifecycle transparency, or working with research-grade environmental data.