Eaternity Database (EDB) API

API Endpoint
https://co2.eaternity.ch/api/

The Eaternity Database API is a Web Service that calculates the Climate Score (CO₂eq), 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 (more Informations on the indicators). It further delivers reports with sophisticated and easy to understand statistics, graphs and analysis (more Informations on the reports).

The Eaternity Database API is a RESTful interface, providing programmatic access to Eaternity’s calculation algorithms, indicator systems and data collections. It provides predictable URLs for accessing resources, and uses built-in HTTP features to receive commands (GET, POST, PUT, DELETE) and return responses.

Join us on Slack here to get in touch with our developers.

Terms & Conditions

By accessing the APIs, you accept the Eaternity’s Terms & Conditions. If You are using the APIs on behalf of an entity, you represent and warrant that you have authority to bind that entity to the Terms & Conditions and by accepting the Terms, you are doing so on behalf of that entity.

Technical Specifications

Authentication

Each client gets his own unique API key, which he needs to provide to be able to talk to the Eaternity Database API. This API key is only given to clients after we have signed a contract.

To authenticate a request, clients should use the HTTPS Basic Authentication and pass the API key as the username, and an empty password. Note that the API only accepts secure connections via HTTPS with SNI (Server Name Indication). The servername is co2.eaternity.ch. Most HTTP request utilities and libraries that allow to specify a username and password will handle proper encoding of the header for you.

You can give it a try connecting to our API with this Testing API-Key (base64 encoded) on our Test-Server (test.eaternity.ch): aDRjSzR0SDBOT2c3NUhqZkszMzlLbE9scGEzOWZKenhYdw==

Try downloading the file avocado.json file and request our service with curl:

curl -i -X POST --data-binary @avocado.json --header 'authorization: Basic aDRjSzR0SDBOT2c3NUhqZkszMzlLbE9scGEzOWZKenhYdw==' --header 'Content-Type: application/json' 'https://test.eaternity.ch/api/recipes?transient=true&full-resource=true&test=random'

You can check out the examples below. Ask us, if we can provide sample request for Bruno, this is currently what we use ourselves.

Language

The API is designed such that one request may contain information about an object (e.g. a recipe or a supply) in multiple languages. Every JSON field which is subject to localization has a language array as value. One language object looks like this:

{ "language": "de", "value": "Kürbisrisotto" }

Example of recipe title language array:

"titles": [ { "language": "de", "value": "Kürbisrisotto" }, { "language": "en", "value": "Pumpkin Risotto" }]

The language field must contain one of the ISO 639-1 alpha-2 codes as a descriptor for the language you use.

Id Generation

The id’s of recipes, kitchens and supplies can be generated in two different ways. The first possibility is to create a new resource through a POST to the API, then the id is generated by Eaternity. The second possibility is to create a new resource through a PUT, providing your own id in the URL itself (e.g. /recipes/298734), then your id is used on our servers. This is the recommended approach, as it helps us coordinating your requests. The id can be any alphanumeric value following this regular expression: [-a-zA-Z0-9+&@#/%?=~|!:,.;]*[-a-zA-Z0-9+&@#/%=~|] (the allowed characters for a HTTP URL).

Notes On The Format

The API accepts JSON in requests. It returns JSON in all of its responses, including errors. Only the UTF-8 character encoding is supported for both requests and responses.

URL Parameters

Parameters Type Description
transient boolean Resources with the transient=true flag will not be saved. This is important as we do not want to include all of your recipes in our monthly summary. For example if you submit a sub-recipe, to check its co2-value, it should not be included in the statistics.
full-resource boolean Specifies whether our JSON answer will contain all fields (except the additional indicators) or a short answer. Default: false. Works recipes and supplies. This helps to save bandwidth for slow connections.
indicators boolean Specifies wether the JSON answer will contain the additional indicator fields. Default: false. Works for recipes, ingredients, and supplies. This helps to save bandwidth for slow connections and the response is generally faster.
test string Only for testing purposes. Values: random or empty. If test=random is set, all ingredients will be randomly linked to life cycle assessments (the results will be wrong!), no 601 error will occur and all the calculation results are incorrect. We provide this functionality so that api clients can test receiving a complete response. By default we need to put in manual labor to have it give back correct values, which takes time. Every ingredient has to be linked to a corresponding data field in our database, for any environmental values to be calculated.

SSL

All requests need to be encrypted through SSL. Please make sure to whitelist the latest SSL certificate from Eaternity.

You can find the latest certificates by accessing the specific domain.

We recommend to whitelist the cloudflare root certificate “cloudflare_origin_rsa.pem”, as follows all our domains and any renewal will be secured (test.eaternity.ch and co2.eaternity.ch). Be advised that if you prefer whitelisting our individual domain names (e.g.: “cloudflare-eaternity.ch-2017.crt”), you will have to renew it each year in time, to not interrupt your service.

Use Server Name Indication (SNI)

Since Eaternity uses distributed Google servers, the IP-address of the service changes and are shared between different applications.

To make SSL work for the Eaternity Database API, the desired hostname (co2.eaternity.ch) needs to be specified with every request according to the SNI-Speficiation. An example request to our service including SNI, using the -servername argument is as follows:

openssl s_client -connect co2.eaternity.ch:443 -servername eaternity.ch

Server Responses

A successful request will be prompted with either 200 - Success or 204 - No Content.

Sadly, sometimes requests to the API are not successful. Failures can occur for a wide range of reasons. In all cases, the API returns an HTTP Status Code that indicates the nature of the failure (below), with a response body in JSON format containing additional information.

  • 200 Success - If a resource was requested, it will be available at the top level of the response body.

  • 201 Created - The request was successful and a resource was created. The Location Header field indicates the URI the resource can be found.

  • 204 No Content - The request was successful and the body intentionally contains no data.

  • 400 Bad request - This occurs when the request was not sent according to the documentation. Can be either the JSON format or the content. Check the documentation and the syntax of your request and try again.

  • 401 No authorization - A valid API key was not provided with the request, so the API could not associate a client with the request. You might wish to try again and check if the key is base64 encoded.

  • 403 Forbidden - The Kitchen is not authorized to calculate environmental values of recipes. Only users that pay for the “Eaternity License” are allowed to do so. Please contact Eaternity to get an up-to-date pricing.

  • 404 Not found - Either the request method and path supplied do not specify a known action in the API, or the object specified by the request does not exist.

  • 405 Method not allowed - When the resource exists but the HTTP method verb is not allowed on this resource.

  • 500 Server error - Just try again.

  • 601 Manual matching missing - An ingredient was requested, whose id is not yet manually matched into the Eaternity Database. Retry once a day.

  • 602 No automatic match found - At least one ingredient name could not get automatically matched into the Eaternity Database. Retry once a day or try with a different ingredient name.

  • 610 Missing required property - A required resource property was not given in the request. Please provide the required field.

  • 611 Wrong property value - A resource property was not provided according to the documentation. Either the given format is wrong or the value doesn’t match to the given options. Usually not dependent on the implementation but on the user input.

  • apiResponseBlocked=1 We are currently linking the products that you sent us with our scientific data set. In order to avoid sending you incomplete results during that process, we are temporarily withholding those incomplete results. We re-evaluate this status once per month. If you want to lift that restriction early, please email us at info@eaternity.ch

Indicator Results

If requested, a collection of indicators will be added to the return JSON for Recipes, Ingredients, and Supplies. The indicators appear as follows:

  • Response 201 (application/json)

    {
      "co2-value": 765,
      "eaternity-award": false,
      "rating": "B",
      "bar-chart": 99,
      "co2-value-improvement-percentage": 34.4,
      "co2-value-reduction-value": 253.0,
      "indicators": {
          "vita-score": {
              "vita-score-points": 346,
              "vita-score-rating": "B",
              "vita-score-improvement-percentage": -2.93,
              "energy-kcals": 457,
              "nutrition-label": true,
              "nutrition-rating": "A",
              "fruit-risk-factor-amount-gram": 0.00,
              "fruit-risk-factor-points": 124.19,
              "vegetable-risk-factor-amount-gram": 0.00,
              "vegetable-risk-factor-points": 88.25,
              "wholegrain-risk-factor-amount-gram": 0.00,
              "wholegrain-risk-factor-points": 122.34,
              "nuts-seeds-risk-factor-amount-gram": 0.00,
              "nuts-seeds-risk-factor-points": 65.63,
              "milk-risk-factor-amount-gram": 0.00,
              "milk-risk-factor-points": 7.91,
              "processed-meat-risk-factor-amount-gram": 0.00,
              "processed-meat-risk-factor-points": 0.00,
              "red-meat-risk-factor-amount-gram": 0.00,
              "red-meat-risk-factor-points": 0.00,
              "salt-risk-factor-amount-gram": 1.73,
              "salt-risk-factor-points": 4.29
          },
          "environment": {
              "animal-treatment-label": true,
              "animal-treatment-rating": "A",
              "rainforest-label": false,
              "rainforest-rating": "E",
              "local-label": true,
              "local-rating": "A",
              "season-label": true,
              "season-rating": "A",
              "scarce-water-liters": 6.0,
              "water-footprint-rating": "C",
              "water-footprint-award": false,
              "water-footprint-improvement-percentage": -30.34,
              "water-footprint-reduction-value": -70.07
          },
          "foodUnit": 14.1
      }
  }

Climate Score

The CO₂eq values are given in the following unit for the different resources.

Property Type Description
co2-value int Absolute value [g CO₂e(quivalent) / serving (given or normalized)] or for the specified amount of ingredient.
rating string Rating [A,B,C,D,E]. A is best, E is worst.
eaternity-award boolean If the item receives the Climate Award.
bar-chart int How much this ingredient contributes to the total CO₂-Value of the recipe or the supply in percent [0% - 100%].
co2-value-improvement-percentage float Comparison of this recipes’s co2 footprint per food unit to the average.
co2-value-reduction-value float The amount of gramm CO₂ saved by serving this recipe instead of serving the amount of an average product that provides the same nutritional value (g).

Vita Score

(Documentation of the Health Score)

Property Type Description
vita-score-points int The total score in points.
vita-score-rating string Rating of Health Score: [A,B,C,D,E]. A is best, E is worst
vita-score-improvement-percentage float Comparison of this recipes’s Health Score to the average
energy-kcals int the total nutritional energy for the item in kilocalories
nutrition-label boolean whether a menu is nutritionally balanced
fruit-risk-factor-amount-gram float Amount of fruits in the recipe that count against the theoretical minimum risk exposure level (TMREL)
fruit-risk-factor-points float Translation of the amount into the disability-adjusted life years (DALY) lost per 100’000 people, as a point score
vegetable-risk-factor-amount-gram float Amount of fruits in the recipe that count against the theoretical minimum risk exposure level (TMREL)
vegetable-risk-factor-points float Translation of the amount into the disability-adjusted life years (DALY) lost per 100’000 people, as a point score
wholegrain-risk-factor-amount-gram float Amount of wholegrain in the recipe that count against the theoretical minimum risk exposure level (TMREL)
wholegrain-risk-factor-points float Translation of the amount into the disability-adjusted life years (DALY) lost per 100’000 people, as a point score
nuts-seeds-risk-factor-amount-gram float Amount of nuts and seeds in the recipe that count against the theoretical minimum risk exposure level (TMREL)
nuts-seeds-risk-factor-points float Translation of the amount into the disability-adjusted life years (DALY) lost per 100’000 people, as a point score
milk-risk-factor-amount-gram float Amount of milk in the recipe that count against the theoretical minimum risk exposure level (TMREL)
milk-risk-factor-points float Translation of the amount into the disability-adjusted life years (DALY) lost per 100’000 people, as a point score
processed-meat-risk-factor-amount-gram float Amount of processed meat in the recipe that count against the theoretical minimum risk exposure level (TMREL)
processed-meat-risk-factor-points float Translation of the amount into the disability-adjusted life years (DALY) lost per 100’000 people, as a point score
red-meat-risk-factor-amount-gram float Amount of red meat in the recipe that count against the theoretical minimum risk exposure level (TMREL)
red-meat-risk-factor-points float Translation of the amount into the disability-adjusted life years (DALY) lost per 100’000 people, as a point score
salt-risk-factor-amount-gram float Amount of salt in the recipe that count against the theoretical minimum risk exposure level (TMREL)
salt-risk-factor-points float Translation of the amount into the disability-adjusted life years (DALY) lost per 100’000 people, as a point score

Environmental Footprints

(Documentation of the Environmental Footprints)

Property Type Description
animal-treatment-label boolean whether the item conforms with animal welfare standards ( has an “A” rating )
animal-treatment-rating string Animal-treatment rating: [A,B,C,D,E]. A is best, E is worst
rainforest-label boolean whether the item meets the standard of avoiding deforestation ( has an “A” rating )
rainforest-rating string Rainforest rating: [A,B,C,D,E]. A is best, E is worst
local-label boolean whether the item is produced locally
local-rating string Local rating: [A,B,C,D,E]. A is best, E is worst
season-label boolean whether the item is used in season
season-rating boolean Season rating: [A,B,C,D,E]. A is best, E is worst
scarce-water-liters int the total scarce water amount for the item in Liters
water-footprint-rating string Water-use rating: [A,B,C,D,E]. A is best, E is worst
water-footprint-award boolean If the item receives the Water Footprint Award.
water-footprint-improvement-percentage float Comparison of this recipes’s water footprint per food unit to the average.
water-footprint-reduction-value float The amount of liters saved by serving this recipe instead of serving the amount of an average product that provides the same nutritional value (l).

Ingredient Properties

Each request for Recipes or Supplies contains a list of Ingredients. Each Ingredient requires at least an id, name and an amount but may contain additional specifications. Ingredients with the same id are shared between all of your Recipes as well as Supplies. There is no hard limit on the number of ingredients, but requests may time out and fail in the range of more than 25 ingredients, especially in combination with batch requests.

Property Type Description Required
id string your unique id of the ingredient yes
type string either conceptual-ingredients or recipes. conceptual-ingredients specifies a normal ingredient, recipes references to an already existing recipe. Default: conceptual-ingredients no
names list of language object full name of ingredient in different languages (array of language objects). Name in at least one language for ingredients required. Only optional for recipes. yes/no
amount float amount of the ingredient in the specified unit yes
unit string unit of the given amount of the ingredient: kg, gram or liter, default: gram no
origin string origin of the ingredient: postal address or country best practice
transport string means of transport from ”origin” to ”location” of recipe or kitchen. Values: air or ground best practice
production string production of the base material. Values: standard, greenhouse, organic, fair-trade, farm (fishes and game animals only), wild-caught (fishes and game animals only), sustainable-fish. best practice
producer string the producer or brand of the product. Especially important for combined products (products with multiple ingredients) best practice
processing string processing and convenience. Values: raw. Meat and Fish: unboned or boned. Fish: skinned, beheaded, fillet. Vegetables and Fruits: cut, boiled, peeled. no
conservation string conservation for longer storage life. Values: fresh or frozen or dried or conserved or canned or boiled-down best practice
packaging string how the product is packaged. Values: none, plastic, paper, pet, tin, alu, glas, cardboard, tetra no
ingredients-declaration string List of ingredients as declared for packaged foods. E.g.: “Hähnchenbrustfilet (53 %), Panade (28%) (Weizenmehl, Wasser, modifizierte Weizen-stärke, Weizenstärke, Speisesalz, Gewürze, Hefe), Wasser, Putenformfleisch-schinken aus Putenfleischteilen zusammengefügt (7 %) (Putenkeulenfleisch, Nitritpökelsalz (Kochsalz, Konservierungsstoff: E 250), Maltodextrin, Dextrose, Gewürzextrakte, Stabilisator: E450), Käse (7 %), Kartoffelstärke, Stabilisator: modifizierte Stärke, Salz), Speisesalz, Stärke, Maltodextrin, Milcheiweiß, Pflanzeneiweiß, Dextrose, Zucker, Gewürzextrakte, Geschmacksverstärker: E 620” no
nutrient-values object Object of the nutrients values per defined nutrient as defined below. no
gtin string global trade item number: www.gtin.info no
201 (application/json)
rating string the CO₂-ingredient rating [A,B,C,D,E]. A is best, E is worst.
bar-chart float to generate a bar chart for all ingredients of a recipe. How much this ingredient contributes to the total CO₂-value of the recipe in percent (0.00% - 100.00%)
co2-value int the absolute value of CO₂e emissions for the ingredient in [g] for the specified amount of ingredient
co2-value-improvement-percentage float Comparison of this recipes’s co2 footprint per food unit to the average
co2-value-reduction-value float The amount of gramm CO₂ saved by serving this recipe instead of serving the amount of an average product that provides the same nutritional value (g)
indicators dictionary the vita and nutritional indicators described above

The parameters of the properties origin, transport, production, processing, conservation and packaging cannot be set to multiple values.

Providing more properties will result in more accurate values. More options will be added over time. Estimations are made for missing properties.

Nutrient Values

Each request for a Ingredient may contains a list of Nutrients. Each Nutrient requires at least an amount.

Property Type Unit Description Required
energy-kcal float Kcal Der Brennwert (Energie) in Kilo-Kalorien pro 100g no
energy-kjoule float KJoule Der Brennwert (Energie) in Kilo-Joule pro 100g no
fat-gram float Fett (g) Der Gesamtfettgehalt in Gramm pro 100g no
saturated-fat-gram float gesättigte Fettsäure (g) Der Gehalt an gesättigten Fettsäuren in Gramm pro 100g no
carbohydrates-gram float Kohlehydrate (g) Der Gehalt an Kohlenhydraten in Gramm pro 100g no
sucrose-gram float Zucker (g) Der Gesamtzucker-Gehalt in Gramm pro 100g (alle Mono- und Disaccaride, ausgenommen mehrwertige Alkohole) no
protein-gram float Eiweiß (g) Der Eiweißgehalt in Gramm pro 100g no
sodium-chloride-gram float Salz (g) Der Salzgehalt in Gramm pro 100g (lt. LMIV Anhang I “Salz” = berechneter Gehalt an Salzäquivalent: Salz = Natrium x 2,5) no
monounsaturated-fat-milligram float einfach ungesättigte Fettsäure (mg) Der Gehalt an einfach ungesättigten Fettsäuren in Milligramm pro 100g no
polyunsaturated-fat-milligram float mehrfach ungesättigte Fettsäure (mg) Der Gehalt an mehrfach ungesättigten Fettsäuren in Milligramm pro 100g no
cholesterol-milligram float Cholesterin (mg) Der Cholesteringehalt in Milligramm pro 100g no
fibers-gram float Ballaststoffe (g) Der Ballaststoffgehalt in Gramm pro 100g no
water-gram float Wasser (g) Der Wassergehalt in Gramm pro 100g no
vitamine-a1-microgram float Vitamin A (μg) Der Vitamin A-Gehalt (Retinoläquivalent) in Mikrogramm pro 100g no
vitamine-b1-microgram float Vitamin B1 (μg) Der Vitamin B1-Gehalt (Thiamin) in Mikrogramm pro 100g no
vitamine-b2-microgram float Vitamin B2 (μg) Der Vitamin B2-Gehalt (Riboflavin) in Mikrogramm pro 100g no
vitamine-b6-microgram float Vitamin B6 (μg) Der Vitamin B6-Gehalt (Pyridoxin) in Mikrogramm pro 100g no
vitamine-b12-microgram float Vitamin B12 (μg) Der Vitamin B12-Gehalt (Cobalamin) in Mikrogramm pro 100g no
vitamine-c-milligram float Vitamin C (mg) Der Vitamin C-Gehalt (Ascorbinsäure) in Milligramm pro 100g no
vitamine-d-microgram float Vitamin D (μg) Der Vitamin D-Gehalt (Calciol) in Mikrogramm pro 100g no
vitamine-e-microgram float Vitamin E (μg) Der Vitamin E-Gehalt (Tocopherol) in Mikrogramm pro 100g no
vitamine-h-microgram float Vitamin H (μg) Der Vitamin H-Gehalt (Biotin) in Mikrogramm pro 100g no
vitamine-k-microgram float Vitamin K (μg) Der Vitamin K-Gehalt in Mikrogramm pro 100g no
beta-carotene-milligram float BetaCarotin (mg) Der Beta-Carotin-Gehalt in Milligramm pro 100g no
niacin-milligram float Niacin (mg) Der Vitamin B3-Gehalt (Niacinäquivalent) in Milligramm pro 100g no
pantohen-milligram float Pantothen-säure (mg) Der Pantothensäure-Gehalt (Vitamin B5) in Milligramm pro 100g no
folic-acid-microgram float Folsäure (μg) Der Folsäure-Gehalt in Mikrogramm pro 100g no
sodium-milligram float Natrium (mg) Der Natriumgehalt in Milligramm pro 100g no
potassium-milligram float Kalium (mg) Der Kaliumgehalt in Milligramm pro 100g no
chlorine-milligram float Chlor (mg) Der Chlorgehalt in Milligramm pro 100g no
calcium-milligram float Calcium (mg) Der Calciumgehalt in Milligramm pro 100g no
magnesium-milligram float Magnesium (mg) Der Magnesiumgehalt in Milligramm pro 100g no
phosphorus-milligram float Phosphor (mg) Der Phosphorgehalt in Milligramm pro 100g no
iron-milligram float Eisen (mg) Der Eisengehalt in Milligramm pro 100g no
zinc-microgram float Zink (μg) Der Zinkgehalt in Mikrogramm pro 100g no
copper-microgram float Kupfer (μg) Der Kupfergehalt in Mikrogramm pro 100g no
manganese-microgram float Mangan (μg) Der Mangangehalt in Mikrogramm pro 100g no
flouride-microgram float Fluoride (μg) Der Fluoridgehalt in Mikrogramm pro 100g no
iodine-microgram float Jod (μg) Der Jodgehalt in Mikrogramm pro 100g no
purine-milligram float Purine (mg) Der Puringehalt in Milligramm pro 100g no
uric-acid-milligram float Harnsäure (mg) Der Harnsäuregehalt in Milligramm pro 100g no
alcohol-volume-percent float Alkoholgehalt (% vol) Laut LMIV Art. 9 (1k) muss der Alkoholgehalt in Volumenprozent (% vol) angegeben werden, sobald er 1,2 %vol überschreitet. no

Kitchen Resources

A kitchen is a place with cooking, food processing and storage devices where food is prepared, processed and stored. It has its own supply and purchase management and a well defined location.

Kitchen Properties

Property Type Description Required
name string official name of the kitchen or factory yes
location string place where the kitchen is located. Address or country (arbitrary format) yes
email string email address of the kitchen where the reports are sent to no
language string language of the reports for the kitchen no
id string the id of the kitchen. Either generated by Eaternity or supplied by the client through a PUT no

Kitchen Collection

POST https://co2.eaternity.ch/api//kitchens/
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "kitchen": {
    "name": "police canteen",
    "location": "zurich, switzerland",
    "email": "test@example.com",
    "language": "en"
  }
}
Responses201
Headers
Content-Type: application/json
Location: https://co2.eaternity.ch/api/kitchens/198764
Body
{
  "kitchen": {
    "id": "198764",
    "name": "police canteen",
    "location": "zurich, switzerland",
    "email": "test@example.com",
    "language": "en"
  }
}

Create new kitchen
POST/kitchens/

Create a kitchen without specifying a particular kitchen ID.

GET https://co2.eaternity.ch/api//kitchens/
Responses200
Headers
Content-Type: application/json
Body
{
  "kitchens": [
    "45674",
    "42344",
    "42233",
    "48855"
  ]
}

Get all kitchens of this client
GET/kitchens/

A list of kitchen ids of this client (one API Key) is returned.

Kitchen

GET https://co2.eaternity.ch/api//kitchens/kitchen_id
Responses200
Headers
Content-Type: application/json
Body
{
  "kitchen": {
    "id": "198764",
    "name": "police canteen",
    "location": "zurich, switzerland",
    "email": "test@example.com",
    "language": "en"
  }
}

Get a kitchen
GET/kitchens/{kitchen_id}

Get the whole kitchen resource.

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen.

PUT https://co2.eaternity.ch/api//kitchens/kitchen_id
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "kitchen": {
    "name": "police canteen",
    "location": "zurich, switzerland",
    "email": "test@example.com",
    "language": "en"
  }
}
Responses200201
Headers
Content-Type: application/json
Location: https://co2.eaternity.ch/api/kitchens/198764
Body
{
  "kitchen": {
    "id": "198764",
    "name": "police canteen",
    "location": "zurich, switzerland",
    "email": "test@example.com",
    "language": "en"
  }
}
Headers
Content-Type: application/json
Location: https://co2.eaternity.ch/api/kitchens/198764
Body
{
  "kitchen": {
    "id": "198764",
    "name": "police canteen",
    "location": "zurich, switzerland",
    "email": "test@example.com",
    "language": "en"
  }
}

Create or update a kitchen
PUT/kitchens/{kitchen_id}

Update or create the kitchen with the specific id

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen.

DELETE https://co2.eaternity.ch/api//kitchens/kitchen_id
Responses204
This response has no content.

Delete a kitchen
DELETE/kitchens/{kitchen_id}

Deletes this kitchen from the server

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen.

Recipe Resources

The CO₂-values are given in g CO₂e for the recipe resource.

Provide the parameter transient=true in the URL if the recipe should not be considered for later statistics and reports. The resource will only be temporarily stored on our servers, no id is returned (Defaults to false).

Information on any made estimations (as well as other comments) are given in the info-text property of the recipe. Please display this information next to the CO₂-value in your interface.

Recipe Properties

Property Type Description Required
kitchen-id string the id of the kitchen the recipe belongs to. yes for the /recipes/batch resource
titles list of language object title of the recipe in different languages (array of language objects) no
author string original author of the recipe no
date yyyy-mm-dd the date the recipe is served. If no date is provided, only a rating of the recipe is returned. best practice
location string location where the recipe is cooked. Address or country (arbitrary format) yes if recipe is not provided in a kitchen
servings (deprecated) int for how many servings the ingredients are given. This value is not allowed to be “0”. no. use ‘recipe-portions’.
recipe-portions int for how many portions the ingredients are specified. Replaces ‘servings’. This value is not allowed to be “0”. no
production-portions int how many portions of the recipe are planned to be produced. no
sold-portions int how many portions of the recipe were really sold (i.e. consumed). This is used by the prognosis endpoint to predict the sales. no
ingredients list of ingredients a list of all ingredient resources in this recipe yes
menu-line-name string A descriptor for the menu line (“Menu 1”, “Garden Menu”, “Vegan Menu”) no
menu-line-id long A number to identify the menu line no
instruction string An arbitrary text you can send and receive no
Response
id string the id of the recipe. Either generated by Eaternity or supplied by the client
co2-value int the CO₂-Value of the whole recipe per serving in [g CO₂e / serving]. If no date is provided, no CO₂-Value but only the rating is returned. If no servings are given, we assume 1 serving.
co2-value-improvement-percentage float Comparison of this recipes’s co2 footprint per food unit to the average
co2-value-reduction-value float The amount of gramm CO₂ saved by serving this recipe instead of serving the amount of an average product that provides the same nutritional value (g)
info-text string notes on the calculated recipe CO₂-value, e.g. remarks when properties like origin or transport are estimated
eaternity-award boolean true if the CO₂-Value of the recipe is climate friendly, false otherwise
rating string the CO₂-recipe rating [A,B,C,D,E]. A is best, E is worst. .
indicators dictionary the vita and nutritional indicators described above .

Recipe Collection

POST https://co2.eaternity.ch/api//recipes
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "recipe": {
    "titles": [
      {
        "language": "de",
        "value": "Kürbisrisotto"
      },
      {
        "language": "en",
        "value": "Pumpkin Risotto"
      }
    ],
    "author": "Eckart Witzigmann",
    "date": "2013-10-14",
    "location": "Zürich Schweiz",
    "kitchen-id": "45674",
    "servings": 140,
    "instruction": "Den Karottenkuchen im Ofen backen und noch warm geniessen.",
    "ingredients": [
      {
        "id": "100100191",
        "type": "conceptual-ingredients",
        "names": [
          {
            "language": "de",
            "value": "Tomaten"
          },
          {
            "language": "en",
            "value": "Tomatoes"
          }
        ],
        "amount": 150,
        "unit": "gram",
        "origin": "spain",
        "transport": "air",
        "production": "greenhouse",
        "processing": "raw",
        "conservation": "fresh",
        "packaging": "plastic",
        "gtin": "00012345678905"
      },
      {
        "id": "100100894",
        "type": "conceptual-ingredients",
        "names": [
          {
            "language": "de",
            "value": "Zwiebeln"
          },
          {
            "language": "en",
            "value": "Onions"
          }
        ],
        "amount": 78,
        "unit": "gram",
        "origin": "france",
        "transport": "ground",
        "production": "organic",
        "processing": "",
        "conservation": "dried",
        "packaging": "",
        "gtin": "00012345678906"
      }
    ]
  }
}
Responses200
Headers
Content-Type: application/json
Location: https://co2.eaternity.ch/api/recipes/d1ed2263-b1b2-4f50-9e9d-ba62cae81f29
Body
{
  "recipe": {
    "id": "d1ed2263-b1b2-4f50-9e9d-ba62cae81f29",
    "co2-value": 765,
    "info-text": "Two ingredient origins have been estimated.",
    "eaternity-award": false,
    "rating": "B",
    "indicators": {
      "vita-score": {
        "vita-score-points": 346,
        "vita-score-rating": "B",
        "energy-kcals": 457,
        "nutrition-label": true
      },
      "environment": {
        "animal-treatment-label": true,
        "animal-treatment-rating": "A",
        "rainforest-label": false,
        "rainforest-rating": "E",
        "local-label": true,
        "local-rating": "A",
        "season-label": true,
        "season-rating": "A",
        "scarce-water-liters": 6,
        "water-footprint-rating": "C",
        "water-footprint-award": true
      },
      "foodUnit": 41
    }
  }
}

Create a recipe
POST/recipes

Create a recipe resource and receive the CO₂-Value and Eaternity Award. Example of a full request with all fields used:

Recipe

GET https://co2.eaternity.ch/api//recipes/id?indicators=true
Responses200
Headers
Content-Type: application/json
Body
{
  "recipe": {
    "id": "d1ed2263-b1b2-4f50-9e9d-ba62cae81f29",
    "kitchen-id": "45674",
    "co2-value": 765,
    "info-text": "Two ingredient origins have been estimated.",
    "eaternity-award": false,
    "rating": "B",
    "indicators": {
      "vita-score": {
        "vita-score-points": 346,
        "vita-score-rating": "B",
        "energy-kcals": 457,
        "nutrition-label": true
      },
      "environment": {
        "animal-treatment-label": true,
        "animal-treatment-rating": "A",
        "rainforest-label": false,
        "rainforest-rating": "E",
        "local-label": true,
        "local-rating": "A",
        "season-label": true,
        "season-rating": "A",
        "scarce-water-liters": 6,
        "water-footprint-rating": "C",
        "water-footprint-award": true
      },
      "foodUnit": 41
    },
    "titles": [
      {
        "language": "de",
        "value": "Kürbisrisotto"
      },
      {
        "language": "en",
        "value": "Pumpkin Risotto"
      }
    ],
    "author": "Eckart Witzigmann",
    "date": "2013-10-14",
    "location": "Zürich Schweiz",
    "servings": 140,
    "instruction": "Den Karottenkuchen im Ofen backen und noch warm geniessen.",
    "ingredients": [
      {
        "id": "100100191",
        "type": "conceptual-ingredients",
        "names": [
          {
            "language": "de",
            "value": "Tomaten"
          },
          {
            "language": "en",
            "value": "Tomatoes"
          }
        ],
        "amount": 150,
        "unit": "gram",
        "origin": "spain",
        "transport": "air",
        "production": "greenhouse",
        "processing": "raw",
        "conservation": "fresh",
        "packaging": "plastic",
        "rating": "b",
        "bar-chart": 31,
        "co2-value": 73
      },
      {
        "id": "100100894",
        "type": "conceptual-ingredients",
        "names": [
          {
            "language": "de",
            "value": "Zwiebeln"
          },
          {
            "language": "en",
            "value": "Onions"
          }
        ],
        "amount": 78,
        "unit": "gram",
        "origin": "france",
        "transport": "ground",
        "production": "organic",
        "processing": "",
        "conservation": "dried",
        "packaging": "",
        "rating": "c",
        "bar-chart": 69,
        "co2-value": 75
      }
    ]
  }
}

Get Recipe
GET/recipes/{id}?indicators=true

Get the up-to-date CO₂-Value (and other indicators) for this recipe for the current date

URI Parameters
HideShow
id
string (required) 

the id of the recipe.

PUT https://co2.eaternity.ch/api//recipes/id?indicators=true
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "recipe": {
    "titles": [
      {
        "language": "de",
        "value": "Kürbisrisotto"
      }
    ],
    "author": "Eckart Witzigmann",
    "date": "2013-10-14",
    "location": "Zürich Schweiz",
    "servings": 140,
    "instruction": "Den Karottenkuchen im Ofen backen und noch warm geniessen.",
    "ingredients": [
      {
        "id": "100100191",
        "type": "conceptual-ingredients",
        "names": [
          {
            "language": "de",
            "value": "Tomaten"
          }
        ],
        "amount": 150,
        "unit": "gram",
        "origin": "spain",
        "transport": "air",
        "production": "greenhouse",
        "processing": "raw",
        "conservation": "fresh",
        "packaging": "plastic"
      },
      {
        "id": "100100894",
        "type": "conceptual-ingredients",
        "names": [
          {
            "language": "de",
            "value": "Zwiebeln"
          }
        ],
        "amount": 78,
        "unit": "gram",
        "origin": "france",
        "transport": "ground",
        "production": "organic",
        "processing": "",
        "conservation": "dried",
        "packaging": ""
      }
    ]
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "recipe": {
    "id": "d1ed2263-b1b2-4f50-9e9d-ba62cae81f29",
    "co2-value": 765,
    "info-text": "Two ingredient origins have been estimated.",
    "eaternity-award": false,
    "rating": "B"
  },
  "indicators": {
    "vita-score": {
      "vita-score-points": 346,
      "vita-score-rating": "B",
      "energy-kcals": 457,
      "nutrition-label": true
    },
    "environment": {
      "animal-treatment-label": true,
      "animal-treatment-rating": "A",
      "rainforest-label": false,
      "rainforest-rating": "E",
      "local-label": true,
      "local-rating": "A",
      "season-label": true,
      "season-rating": "A",
      "scarce-water-liters": 6,
      "water-footprint-rating": "C",
      "water-footprint-award": true
    },
    "foodUnit": 41
  }
}

Update or create new recipe
PUT/recipes/{id}?indicators=true

Update or create a certain recipe with this id. The whole recipe resource with all ingredients must be provided again. (PUT overrides the existing resource).

URI Parameters
HideShow
id
string (required) 

the id of the recipe.

DELETE https://co2.eaternity.ch/api//recipes/id?indicators=true
Responses204
This response has no content.

Delete the recipe
DELETE/recipes/{id}?indicators=true

Deletes this recipe from the server

URI Parameters
HideShow
id
string (required) 

the id of the recipe.

Kitchen Recipe Collection

No recipe location needs to be provided.

POST https://co2.eaternity.ch/api//kitchens/kitchen_id/recipes
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "recipe": {
    "titles": [
      {
        "language": "de",
        "value": "Kürbisrisotto"
      }
    ],
    "author": "Eckart Witzigmann",
    "date": "2013-10-14",
    "location": "Zürich Schweiz",
    "servings": 140,
    "instruction": "Den Karottenkuchen im Ofen backen und noch warm geniessen.",
    "ingredients": [
      {
        "id": "100100191",
        "type": "conceptual-ingredients",
        "names": [
          {
            "language": "de",
            "value": "Tomaten"
          }
        ],
        "amount": 150,
        "unit": "gram",
        "origin": "spain",
        "transport": "air",
        "production": "greenhouse",
        "processing": "raw",
        "conservation": "fresh",
        "packaging": "plastic"
      },
      {
        "id": "100100894",
        "type": "conceptual-ingredients",
        "names": [
          {
            "language": "de",
            "value": "Zwiebeln"
          }
        ],
        "amount": 78,
        "unit": "gram",
        "origin": "france",
        "transport": "ground",
        "production": "organic",
        "processing": "",
        "conservation": "dried",
        "packaging": ""
      }
    ]
  }
}
Responses200

ed

Headers
Content-Type: application/json
Location: https://co2.eaternity.ch/api/kitchens/45674/recipes/d1ed2263-b1b2-4f50-9e9d-ba62cae81f29
Body
{
  "statuscode": 200,
  "message": "",
  "request-id": 0,
  "recipe-id": "d1ed2263-b1b2-4f50-9e9d-ba62cae81f29",
  "recipe": {
    "id": "d1ed2263-b1b2-4f50-9e9d-ba62cae81f29",
    "kitchen-id": "45674",
    "co2-value": 765,
    "info-text": "Two ingredient origins have been estimated.",
    "eaternity-award": false,
    "rating": "B",
    "indicators": {
      "vita-score": {
        "vita-score-points": 346,
        "vita-score-rating": "B",
        "energy-kcals": 457,
        "nutrition-label": true
      },
      "environment": {
        "animal-treatment-label": true,
        "animal-treatment-rating": "A",
        "rainforest-label": false,
        "rainforest-rating": "E",
        "local-label": true,
        "local-rating": "A",
        "season-label": true,
        "season-rating": "A",
        "scarce-water-liters": 6,
        "water-footprint-rating": "C",
        "water-footprint-award": true
      },
      "foodUnit": 41
    }
  }
}

Create a recipe
POST/kitchens/{kitchen_id}/recipes

Create a recipe resource in a specific kitchen and receive the CO₂-Value and Eaternity Award

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen.

GET https://co2.eaternity.ch/api//kitchens/kitchen_id/recipes
Responses200
Headers
Content-Type: application/json
Body
{
  "recipes": [
    "298374",
    "298345",
    "298454",
    "298345",
    "298456",
    "294564"
  ]
}

Get all recipes contained in this kitchen
GET/kitchens/{kitchen_id}/recipes

A list of recipe ids is returned.

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen.

Kitchen Recipe

GET https://co2.eaternity.ch/api//kitchens/kitchen_id/recipes/recipe_id
Responses200
Headers
Content-Type: application/json
Body
{
    "recipe": {
        "id": "d1ed2263-b1b2-4f50-9e9d-ba62cae81f29",
        "kitchen-id": "45674",
        "co2-value": 765,
        "info-text": "Two ingredient origins have been estimated.",
        "eaternity-award": false,
        "rating": "B",
        "titles": [
            {
                "language": "de",
                "value": "Kürbisrisotto"
            }],
        "author": "Eckart Witzigmann",
        "date": "2013-10-14",
        "location": "Zürich Schweiz",
        "servings": 140,
        "instruction":"Bake the carrot cake in the oven and enjoy while still hot.",
            "indicators": {
                "vita-score": {
                    "vita-score-points": 346,
                    "vita-score-rating": "B",
                    "energy-kcals": 457.0,
                    "nutrition-label": true
                },
                "environment": {
                    "animal-treatment-label": true,
                    "animal-treatment-rating": "A",
                    "rainforest-label": false,
                    "rainforest-rating": "E",
                    "local-label": true,
                    "local-rating": "A",
                    "season-label": true,
                    "season-rating": "A",
                    "scarce-water-liters": 6.0,
                    "water-footprint-rating": "C",
                    "water-footprint-award": true
                },
                "foodUnit": 41.0
            },
        "ingredients": [
            {
                "id": "100100191",
                "type": "conceptual-ingredients",
                "names":  [
                    {
                        "language": "de",
                        "value": "Tomaten"
                    }],
                "amount": 150,
                "unit": "gram",
                "origin": "spain",
                "transport": "air",
                "production": "greenhouse",
                "processing": "raw",
                "conservation": "fresh",
                "packaging": "plastic"
                "rating": "b",
                "bar-chart": 27.56,
                "co2-value": 74,
                "indicators": {
                    "vita-score": {
                        "vita-score-points": 346,
                        "vita-score-rating": "B",
                        "energy-kcals": 457.0,
                        "nutrition-label": true
                    },
                    "environment": {
                        "animal-treatment-label": true,
                        "animal-treatment-rating": "A",
                        "rainforest-label": false,
                        "rainforest-rating": "E",
                        "local-label": true,
                        "local-rating": "A",
                        "season-label": true,
                        "season-rating": "A",
                        "scarce-water-liters": 6.0,
                        "water-footprint-rating": "C",
                        "water-footprint-award": true
                    },
                    "foodUnit": 41.0
                }
            },
            {
                "id": "100100894",
                "type": "conceptual-ingredients",
                "names":  [
                    {
                        "language": "de",
                        "value": "Zwiebeln"
                    }],
                "amount": 78,
                "unit": "gram",
                "origin": "france",
                "transport": "ground",
                "production": "organic",
                "processing": "",
                "conservation": "dried",
                "packaging": "",
                "rating": "c",
                "bar-chart": 75.56,
                "co2-value": 79,
                "indicators": {
                    "vita-score": {
                        "vita-score-points": 346,
                        "vita-score-rating": "B",
                        "energy-kcals": 457.0,
                        "nutrition-label": true
                    },
                    "environment": {
                        "animal-treatment-label": true,
                        "animal-treatment-rating": "A",
                        "rainforest-label": false,
                        "rainforest-rating": "E",
                        "local-label": true,
                        "local-rating": "A",
                        "season-label": true,
                        "season-rating": "A",
                        "scarce-water-liters": 6.0,
                        "water-footprint-rating": "C",
                        "water-footprint-award": true
                    },
                    "foodUnit": 41.0
                }
            }
        ]
    }
}

Get Recipe
GET/kitchens/{kitchen_id}/recipes/{recipe_id}

Get the up-to-date CO₂-Value for this recipe for the current date

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen.

recipe_id
string (required) 

the id of the recipe.

PUT https://co2.eaternity.ch/api//kitchens/kitchen_id/recipes/recipe_id
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "statuscode": 200,
  "message": "",
  "request-id": 0,
  "recipe-id": "100100894",
  "recipe": {
    "titles": [
      {
        "language": "de",
        "value": "Kürbisrisotto"
      }
    ],
    "author": "Eckart Witzigmann",
    "date": "2013-10-14",
    "servings": 140,
    "instruction": "Den Karottenkuchen im Ofen backen und noch warm geniessen.",
    "ingredients": [
      {
        "id": "100100191",
        "type": "conceptual-ingredients",
        "names": [
          {
            "language": "de",
            "value": "Tomaten"
          }
        ],
        "amount": 150,
        "unit": "gram",
        "origin": "spain",
        "transport": "air",
        "production": "greenhouse",
        "processing": "raw",
        "conservation": "fresh",
        "packaging": "plastic"
      },
      {
        "id": "100100894",
        "type": "conceptual-ingredients",
        "names": [
          {
            "language": "de",
            "value": "Zwiebeln"
          }
        ],
        "amount": 78,
        "unit": "gram",
        "origin": "france",
        "transport": "ground",
        "production": "organic",
        "processing": "",
        "conservation": "dried",
        "packaging": ""
      }
    ]
  }
}
Responses200
Headers
Content-Type: application/json
Location: https://co2.eaternity.ch/api/kitchens/45674/recipes/d1ed2263-b1b2-4f50-9e9d-ba62cae81f29
Body
{
  "recipe": {
    "id": "d1ed2263-b1b2-4f50-9e9d-ba62cae81f29",
    "kitchen-id": "45674",
    "co2-value": 765,
    "info-text": "Two ingredient origins have been estimated.",
    "eaternity-award": false,
    "rating": "B"
  }
}

Create or update recipe
PUT/kitchens/{kitchen_id}/recipes/{recipe_id}

Update or create a certain recipe with this id. The whole recipe resource with all ingredients must be provided again. (PUT overrides the existing resource).

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen.

recipe_id
string (required) 

the id of the recipe.

DELETE https://co2.eaternity.ch/api//kitchens/kitchen_id/recipes/recipe_id
Responses204
This response has no content.

Delete recipe
DELETE/kitchens/{kitchen_id}/recipes/{recipe_id}

Deletes this recipe from the server

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen.

recipe_id
string (required) 

the id of the recipe.

Batch Operations on Recipe Resources

The full-resource url parameter is supported here as well, but just for the whole request itself and not on single recipes. The transient parameter can be set selectively on single recipes inside the batch.

The message in the response provides more details about the failure of individual recipes. Batch operations do not support an unlimited number of recipes. If a request fails repeatedly, please consider reducing the number of recipes submitted.

POST https://co2.eaternity.ch/api//recipes/batch
Requestsexample 1
Headers
Content-Type: application/json
Body
[
{
    "request-id": 1, 
    "transient": false,
    "recipe": {
        "id": "0002076208", // your unique ID!
        "menu-line-id": 19092,
        "menu-line-name": "Hit Menu Lunch",
        "recipe-portions": 1, // as your recipe is defined
        "sold-portions": 202,
        "production-portions": 212,
        "date": "2023-10-14",
        "kitchen-id": "AC432", // your unique ID!
        "ingredients": [
        {
                "id": "467", // your unique ID!
                "names": [
                    {
                        "language": "DE",
                        "value": "Quality Pfeffer weiss gemahlen 900g"
                    }
                ],
                "amount": "0.0233",
                "unit": "gram", // "EA" is not possible
                "origin": "", // please specify as available
                "transport": "", // set to "ground" for parameter no airplane
                "production": "",
                "processing": "",
                "conservation": "",
                "gtin": "00012345678905" // please specify as available
            },
            {
                "id": "0002076209",
                "amount": "0.0233",
                "unit": "gram",
                "type": "recipes" // necessary !!

            }
]
}
},
{
// This request represents a subrecipe of the previous.
// It needs to be part of the same POST request
"request-id": 2, 
    "transient": true,
    "recipe": {
        "id": "0002076209",
        "recipe-portions": 1,
        "date": "2023-10-14",
        "kitchen-id": "recipe-components", // a separate kitchen to collect recipes that were not part of the menu plan
        "ingredients": [
        {
                "id": "467",
                "names": [
                    {
                        "language": "DE",
                        "value": "Quality Pfeffer weiss gemahlen 900g"
                    }
                ],
                "amount": "0.0233",
                "unit": "gram",
                "origin": "",
                "transport": "",
                "production": "",
                "processing": "",
                "conservation": ""
            }
]
},
{
    "request-id": 3,
    "transient": false,
    "recipe": {
        "id": "d1ed2263-b1b2-4f50-9e9d-ba62cae81f29",
        "kitchen-id": "112233",
        "titles": [
            {
                "language": "de",
                "value": "Kürbisrisotto"
            }
        ],
        "instruction": "Den Karottenkuchen im Ofen backen und noch warm geniessen.",
        "servings": 10,
        "ingredients": [
            {  ...  }
        ]
  }
}
]
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "statuscode": 200,
    "message": "",
    "request-id": 1,
    "recipe": {
      "id": "0002076208",
      "kitchen-id": "C142",
      "co2-value": 765,
      "eaternity-award": false,
      "rating": "B"
    }
  },
  {
    "statuscode": 200,
    "message": "",
    "request-id": 2,
    "recipe": {
      "id": "0002076209",
      "kitchen-id": "198764",
      "co2-value": 765,
      "eaternity-award": false,
      "rating": "B"
    }
  },
  {
    "statuscode": 601,
    "message": "The ingredient 384767656 is not yet matched. Retry next day.",
    "request-id": 3
  }
]

Create or update a batch of recipes
POST/recipes/batch

Create or update a batch of recipes at once. If a recipe id is provided, the recipe is either created with this id or the existing recipe is overwritten. The status code tells the difference.

The kitchen-id may be used to store the recipe into a specific kitchen.

The additional integer request-id field enables you to track back the recipes you sent in case you don’t want to use your own id’s. Either a request id or a recipe id is required. The request-id differs from the recipe id and has just the lifetime of a single request (not stored on Eaternity’s end).

DELETE https://co2.eaternity.ch/api//recipes/batch
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "recipes": [
    "3948756",
    "3948757",
    "3948757"
  ]
}
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "statuscode": 200,
    "message": "",
    "recipe-id": "3948756"
  },
  {
    "statuscode": 200,
    "message": "",
    "recipe-id": "3948757"
  },
  {
    "statuscode": 500,
    "message": "Concurrency problem: You requested deleting this recipe several times in this batch.",
    "recipe-id": "3948757"
  }
]

Delete a batch of recipes
DELETE/recipes/batch

Supply Resources

Supplies are ordered from and delivered by a specific supplier in the supply chain. They can serve as the data pool for all the Eaternity Reports, as well as we can provide feedback on single purchases.

Supply Properties

Property Type Description Required
supplier string name of the specific supplier in the supply chain no
supplier-id string user-specified id of the supplier in the supply chain no
invoice-id string user-specified invoice number (if different from the id of the supply order) no
order-date yyyy-mm-dd the date the supply was ordered yes
supply-date yyyy-mm-dd the delivery date of the supply yes
ingredients list of ingredients a list of all ingredient resources in this supply yes
id string the id of the supply. Either generated by Eaternity or supplied by the client through a PUT no
Response
kitchen-id string the id of the kitchen the supply belongs to.
co2-value float the total CO₂-Value of the supply in [g CO₂e].
indicators dictionary the vita and nutritional indicators described above .

Supply Collection

POST https://co2.eaternity.ch/api//kitchens/kitchen_id/supplies/
Requestsexample 1
Headers
Content-Type: application/json
Body
{   "supply": {
        "supplier": "Vegetable Supplies Ltd.",
        "supplier-id": "el3i5y-2in5y-2hbllll01",
        "invoice-id": "778888800000001",
        "supply-date": "2013-06-01",
        "ingredients": [
        {
            "id": "100100191",
            "type": "conceptual-ingredients",
            "names":  [
                {
                    "language": "de",
                    "value": "Tomaten"
                }],
            "amount": 150,
            "unit": "gram",
            "origin": "spain",
            "transport": "air",
            "production": "greenhouse",
            "processing": "raw",
            "conservation": "fresh",
            "packaging": "plastic",
            "ingredients-declaration": "Hähnchenbrustfilet (53 %), Panade (28%) (Weizenmehl, Wasser, modifizierte Weizen-stärke, Weizenstärke, Speisesalz, Gewürze, Hefe), Wasser, Putenformfleisch-schinken aus Putenfleischteilen zusammengefügt (7 %) (Putenkeulenfleisch, Nitritpökelsalz (Kochsalz, Konservierungsstoff: E 250), Maltodextrin, Dextrose, Gewürzextrakte, Stabilisator: E450), Käse (7 %), Kartoffelstärke, Stabilisator: modifizierte Stärke, Salz), Speisesalz, Stärke, Maltodextrin, Milcheiweiß, Pflanzeneiweiß, Dextrose, Zucker, Gewürzextrakte, Geschmacksverstärker: E 620",
            "nutrient-values": {
               "energy-kjoule":500,
               "fat-gram":9001,
               "protein-gram": 33,
               "vitamine-k-microgram": 0.21,
               "vitamine-a1-microgram": 0.12345,
               "manganese-microgram":0,
               "fibers-gram":1111,
               ...
            }
        }
        ]
    }
}
Responses200
Headers
Content-Type: application/json
Location: https://co2.eaternity.ch/api/kitchens/1987647/supplies/d1ed2263
Body
{
  "statuscode": 200,
  "message": "",
  "request-id": 0,
  "supply-id": "d1ed2263"
}

Create a supply
POST/kitchens/{kitchen_id}/supplies/

Create a supply without specifying an id. If the request is sent with full-resource=true, then a complete response will be given, the same as the response to the GET command below. The parameter indicators=true is also supported when full-resource=true is specified.

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen.

GET https://co2.eaternity.ch/api//kitchens/kitchen_id/supplies/
Responses200
Headers
Content-Type: application/json
Body
{
  "supplies": [
    "d1ed2263",
    "d1ed2264",
    "d1ed2265",
    "d1ed2268"
  ]
}

Get all supplies in this kitchen
GET/kitchens/{kitchen_id}/supplies/

Get all supplies contained in this kitchen. A list of supply ids is returned.

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen.

Supply

GET https://co2.eaternity.ch/api//kitchens/kitchen_id/supplies/supply_id?indicators=true
Responses200
Headers
Content-Type: application/json
Body
{   "supply": {
        "id": "d1ed2263",
        "kitchen-id": "293833",
        "co2-value": 77,
        "info-text": "Two ingredient origins have been estimated.",
        "supplier": "Vegetable Supplies Ltd.",
        "supplier-id": "el3i5y-2in5y-2hbllll01",
        "supply-date": "2013-06-01",
        "ingredients": [
        {
            "id": "100100191",
            "type": "conceptual-ingredients",
            "names":  [
                {
                    "language": "de",
                    "value": "Tomaten"
                }],
            "amount": 150.0,
            "unit": "gram",
            "origin": "spain",
            "transport": "air",
            "production": "greenhouse",
            "processing": "raw",
            "conservation": "fresh",
            "packaging": "plastic",
            "gtin":"",
            "rating": "c",
            "bar-chart": 69,
            "co2-value": 79,
            "indicators": {
                "vita-score": {
                    "vita-score-points": "TBI",
                    "vita-score-rating": "TBI",
                    "energy-kcals": 457.0,
                    "nutrition-label": false,
                    "nutrition-rating": "TBI"
                },
                "environment": {
                    "animal-treatment-label": true,
                    "animal-treatment-rating": "A",
                    "rainforest-label": false,
                    "rainforest-rating": "E",
                    "local-label": true,
                    "local-rating": "TBI",
                    "season-label": true,
                    "season-rating": "TBI",
                    "scarce-water-liters": 6.0,
                    "water-footprint-rating": "B",
                    "water-footprint-award": true
                }
            }
        }
        ]
}

Get a supply
GET/kitchens/{kitchen_id}/supplies/{supply_id}?indicators=true

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen.

supply_id
string (required) 

the id of the supply.

PUT https://co2.eaternity.ch/api//kitchens/kitchen_id/supplies/supply_id?indicators=true
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "supply": {
    "supplier": "Vegetable Supplies Ltd.",
    "supplier-id": "el3i5y-2in5y-2hbllll01",
    "supply-date": "2013-06-01",
    "ingredients": [
      {
        "id": "100100191",
        "type": "conceptual-ingredients",
        "names": [
          {
            "language": "de",
            "value": "Tomaten"
          }
        ],
        "amount": 150,
        "unit": "gram",
        "price": 0.5,
        "currency": "CHF",
        "origin": "spain",
        "transport": "air",
        "production": "greenhouse",
        "processing": "raw",
        "conservation": "fresh",
        "packaging": "plastic"
      }
    ]
  }
}
Responses200
Headers
Content-Type: application/json
Location: https://co2.eaternity.ch/api/kitchens/1987647/supplies/d1ed2263
Body
{
  "statuscode": 200,
  "message": "",
  "request-id": 0,
  "supply-id": "d1ed2263"
}

Update or create a supply
PUT/kitchens/{kitchen_id}/supplies/{supply_id}?indicators=true

Update or create this supply with the specific id. The supply always needs to have an id, either a new one or an already existing one. If the request is sent with full-resource=true, then a complete response will be given, the same as the response to the GET command above. The parameter indicators=true is also supported when full-resource=true is specified.

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen.

supply_id
string (required) 

the id of the supply.

DELETE https://co2.eaternity.ch/api//kitchens/kitchen_id/supplies/supply_id?indicators=true
Responses204
This response has no content.

Delete a supply
DELETE/kitchens/{kitchen_id}/supplies/{supply_id}?indicators=true

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen.

supply_id
string (required) 

the id of the supply.

Batch operations on supply resources

POST https://co2.eaternity.ch/api//supplies/batch
Requestsexample 1
Headers
Content-Type: application/json
Body
[
  {
    "request-id": 1,
    "supply": {
      "id": "d1ed2263",
      "kitchen-id": "293833",
      "supplier": "Vegetable Supplies Ltd.",
      "supplier-id": "el3i5y-2in5y-2hbllll01",
      "supply-date": "2013-06-01",
      "ingredients": [
        {
          "id": "100100191",
          "type": "conceptual-ingredients",
          "names": [
            {
              "language": "de",
              "value": "Tomaten"
            }
          ],
          "amount": 150,
          "unit": "gram",
          "origin": "spain",
          "transport": "air",
          "production": "greenhouse",
          "processing": "raw",
          "conservation": "fresh",
          "packaging": "plastic"
        }
      ]
    }
  },
  {
    "request-id": 2,
    "supply": {
      "kitchen-id": "11122233",
      "supplier": "Vegetable Supplies Ltd.",
      "supplier-id": "el3i5y-2in5y-2hbllll01",
      "supply-date": "2013-06-06",
      "ingredients": [
        {
          "id": "100100191",
          "type": "conceptual-ingredients",
          "names": [
            {
              "language": "de",
              "value": "Tomaten"
            }
          ],
          "amount": 150,
          "unit": "gram",
          "origin": "spain",
          "transport": "air",
          "production": "greenhouse",
          "processing": "raw",
          "conservation": "fresh",
          "packaging": "plastic"
        }
      ]
    }
  }
]
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "statuscode": 200,
    "message": "",
    "request-id": 1,
    "supply-id": "d1ed2263"
  },
  {
    "statuscode": 500,
    "message": "Server Error. Just try again.",
    "request-id": 2
  }
]

Create a batch of supplies
POST/supplies/batch

Create or update a batch of supplies at once. If a supply id is provided, the supply is either created with this id or the existing supply is overwritten. The status code tells the difference. The full-resource and indicators parameters are supported.

The additional request-id field enables you to track back the supply you sent in case you don’t want to use your own id. Either a request id or a recipe id is required. The request-id differs from the supply id and has just the lifetime of a single request (not stored on Eaternity’s end).

DELETE https://co2.eaternity.ch/api//supplies/batch
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "supplies": [
    "d1ed2263",
    "d1ed2267"
  ]
}
Responses200
Headers
Content-Type: application/json
Body
[
  {
    "statuscode": 200,
    "message": "",
    "supply-id": "d1ed2263"
  },
  {
    "statuscode": 200,
    "message": "",
    "supply-id": "d1ed2267"
  }
]

Delete a batch of supplies
DELETE/supplies/batch

Product Resources for Retail

The Product resourcres are directed towards users that have limited information about a single retail food product’s composition and want to calculate indicators based on the mandatory ingredient and nutrients declaration on its packaging. We only recommend using the Product Resources in tight coordination with the team at Eaternity as the calculations require additional supervision from our team. We process it and build a recipe-like structure so we can serve the usual indicators.

Product Properties

Property Type Description Required
id string Specify your id of the product. yes
gtin string Global trade item number: www.gtin.info best practice
names List of language object full name of product in different languages (array of language objects). Name in at least one language required. yes
amount float Amount of the product in the specified unit, default: 100 best practice
unit string Unit of the given amount of the ingredient: kg, gram or liter, default: gram no
producer string The producer or brand of the product. best practice
date string Specify the production date so seasonal differences can be calculated for ingredients where this matters. Format: “YYYY-MM-DD” no
ingredients-declaration string List of ingredients in German as declared for packaged foods. E.g.: “Hähnchenbrustfilet (53 %), Panade (28%) (Weizenmehl, Wasser, modifizierte Weizen-stärke, Weizenstärke, Speisesalz, Gewürze, Hefe), Wasser, Putenformfleisch-schinken aus Putenfleischteilen zusammengefügt (7 %) (Putenkeulenfleisch, Nitritpökelsalz (Kochsalz, Konservierungsstoff: E 250), Maltodextrin, Dextrose, Gewürzextrakte, Stabilisator: E450), Käse (7 %), Kartoffelstärke, Stabilisator: modifizierte Stärke, Salz), Speisesalz, Stärke, Maltodextrin, Milcheiweiß, Pflanzeneiweiß, Dextrose, Zucker, Gewürzextrakte, Geschmacksverstärker: E 620” yes
nutrient-values object Object of the nutrients values per defined nutrient as defined below. yes
origin string Production location: postal address or country best practice
transport string Means of transport from ”origin” to ”location” of recipe or kitchen. Values: air or ground best practice
production string Values: standard, greenhouse, organic, fair-trade, farm (fishes and game animals only), wild-caught (fishes and game animals only), sustainable-fish. best practice
processing string Values: raw. Meat and Fish: unboned or boned. Fish: skinned, beheaded, fillet. Vegetables and Fruits: cut, boiled, peeled. no
conservation string Conservation for longer storage life. Values: fresh or frozen or dried or conserved or canned or boiled-down best practice
packaging string How the product is packaged. Values: none, plastic, paper, pet, tin, alu, glas, cardboard, tetra no
201 (application/json)
rating string The CO₂-ingredient rating [A,B,C,D,E]. A is best, E is worst.
bar-chart float To generate a bar chart for all ingredients of a recipe. How much this ingredient contributes to the total CO₂-value of the recipe in percent (0.00% - 100.00%)
co2-value int The absolute value of CO₂e emissions for the ingredient in [g] for the specified amount of ingredient
co2-value-improvement-percentage float Comparison of this product’s co2 footprint per food unit to the average
co2-value-reduction-value float The amount of co2 saved by serving this product instead of serving the amount of an average product that provides the same nutritional value
foodUnit float The nutrional value of this product for the given amount
indicators dictionary The vita and nutritional indicators described above

Product Collection

PUT https://co2.eaternity.ch/api//products/id
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "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"
}
Responses202
This response has no content.

Create a product
PUT/products/{id}

Create or update a product.

URI Parameters
HideShow
id
string (required) 

the id of the product.

GET https://co2.eaternity.ch/api//products/id
Responses601202
Body
"This product has not yet been processed."
Body
{
  "names": [
    {
      "language": "de",
      "value": "Karottenpuree"
    }
  ],
  "id": "180320201",
  "co2-value": 478,
  "co2-value-improvement-percentage": -41,
  "co2-value-reduction-value": -140,
  "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,
      "unit": "gram",
      "origin": "",
      "transport": "",
      "gtin": "",
      "rating": "A",
      "bar-chart": 100,
      "co2-value": 32,
      "foodUnit": 0.10978478484848483
    },
    {
      "id": "FoodServiceb7a8081e-690b-11ea-9516-ae471177f174",
      "names": [
        {
          "language": "de",
          "value": "Tomaten"
        }
      ],
      "amount": 6.938894e-22,
      "unit": "gram",
      "origin": "",
      "transport": "",
      "gtin": "",
      "rating": "B",
      "bar-chart": 0,
      "co2-value": 0,
      "foodUnit": 5.48973752311336e-25
    }
  ]
}

Receive a product
GET/products/{id}

Depending on whether the product has been processed, the response can be either of the following: A 601 Response with the message “This product has not yet been processes” or a 202 Response with the details about the processed information.

URI Parameters
HideShow
id
string (required) 

the id of the product.

Forecast Resources

A forecast of sold menu portions can be generated based on all planned recipes of a kitchen. The forecast calculation takes into account the previously supplied sales of the corresponding kitchen. For the forecast to work, we need at least 10 consecutive days with menus (including full recipes and sales data). Better is more. You will receive a warning if we have too little data for a prediction.

An example API call to create a prognosis:

curl -i -X POST "https://co2.eaternity.ch/api/prognosis/YOURKITCHENID/forecast" --header "authorization: Basic YOURKEY" --header "accept: */*" --header "Content-Type: application/json" -d "{\"date-start\":\"2019-03-04\",\"date-end\":\"2019-03-08\",\"async\":true}"

Create a new forecast

POST https://co2.eaternity.ch/api//prognosis/kitchen_id/forecast
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "date-start": "Hello, world!",
  "date-end": "Hello, world!",
  "async": true
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "date-start": {
      "type": "string",
      "description": "Specify the start date of the prognosis. Format: \"YYYY-MM-DD\"."
    },
    "date-end": {
      "type": "string",
      "description": "Specify the end date of the prognosis. Format: \"YYYY-MM-DD\"."
    },
    "async": {
      "type": "boolean",
      "description": "If true, the request returns directly a prediction_id without waiting for the calculation to finish. Default: false."
    }
  }
}
Responses201
Headers
Content-Type: application/json
Location: https://co2.eaternity.ch/api/prognosis/{kitchen_id}/forecast/{prediction_id}
Body
{
  "kitchen_id": "11122233",
  "prediction_id": "ab2k2z-7km3u-8ffzzck37",
  "status": "Hello, world!",
  "error": "Hello, world!",
  "info": [
    {
      "error": "Hello, world!",
      "warning": "Hello, world!",
      "product_id": "Hello, world!"
    }
  ],
  "predicted_sales": {
    "date-start": "Hello, world!",
    "date-end": "Hello, world!",
    "results": [
      {
        "date": "Hello, world!",
        "total-sales": {
          "portions": 1214,
          "low": 1123,
          "high": 1265
        },
        "recipes": [
          {
            "recipe-id": "111112",
            "portions": 486,
            "low": 416,
            "high": 526
          }
        ]
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kitchen_id": {
      "type": "string",
      "description": "The id of the kitchen, for which the prognosis is calculated."
    },
    "prediction_id": {
      "type": "string",
      "description": "The id of the prognosis (generated by Eaternity)."
    },
    "status": {
      "type": "string",
      "description": "The status of the prognosis (processing/done/error)."
    },
    "error": {
      "type": "string",
      "description": "An error message if the forecast calculation was not possible."
    },
    "info": {
      "type": "array",
      "description": "Showing potential warnings and errors (i.e. unmatched ingredients)."
    },
    "predicted_sales": {
      "type": "object",
      "properties": {
        "date-start": {
          "type": "string",
          "description": "The start date of the prognosis. Format: \"YYYY-MM-DD\"."
        },
        "date-end": {
          "type": "string",
          "description": "The end date of the prognosis. Format: \"YYYY-MM-DD\"."
        },
        "results": {
          "type": "array",
          "description": "Structured list of the resulting forecast grouped by day."
        }
      },
      "description": "The resulting sales forecast."
    }
  }
}

Create a forecast
POST/prognosis/{kitchen_id}/forecast

This post request will create a new forecast calculation for the kitchen. The request is kept open until the calculation is finished. Alternatively, if async: true is provided, the request returns directly a new forecast resource locator without waiting for the calculation to be finished.

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen, for which the prognosis is calculated

Forecast Results

GET https://co2.eaternity.ch/api//prognosis/kitchen_id/forecast/prediction_id
Responses201
Headers
Content-Type: application/json
Body
{
  "kitchen_id": "11122233",
  "prediction_id": "ab2k2z-7km3u-8ffzzck37",
  "status": "Hello, world!",
  "error": "Hello, world!",
  "info": [
    {
      "error": "Hello, world!",
      "warning": "Hello, world!",
      "product_id": "Hello, world!"
    }
  ],
  "predicted_sales": {
    "date-start": "Hello, world!",
    "date-end": "Hello, world!",
    "results": [
      {
        "date": "Hello, world!",
        "total-sales": {
          "portions": 1214,
          "low": 1123,
          "high": 1265
        },
        "recipes": [
          {
            "recipe-id": "111112",
            "portions": 486,
            "low": 416,
            "high": 526
          }
        ]
      }
    ]
  }
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "kitchen_id": {
      "type": "string",
      "description": "The id of the kitchen, for which the prognosis is calculated."
    },
    "prediction_id": {
      "type": "string",
      "description": "The id of the prognosis (generated by Eaternity)."
    },
    "status": {
      "type": "string",
      "description": "The status of the prognosis (processing/done/error)."
    },
    "error": {
      "type": "string",
      "description": "An error message if the forecast calculation was not possible."
    },
    "info": {
      "type": "array",
      "description": "Showing potential warnings and errors (i.e. unmatched ingredients)."
    },
    "predicted_sales": {
      "type": "object",
      "properties": {
        "date-start": {
          "type": "string",
          "description": "The start date of the prognosis. Format: \"YYYY-MM-DD\"."
        },
        "date-end": {
          "type": "string",
          "description": "The end date of the prognosis. Format: \"YYYY-MM-DD\"."
        },
        "results": {
          "type": "array",
          "description": "Structured list of the resulting forecast grouped by day."
        }
      },
      "description": "The resulting sales forecast."
    }
  }
}

Get a forecast
GET/prognosis/{kitchen_id}/forecast/{prediction_id}

This request retrieves the status (and if done the resulting predicted sales numbers) of a previously created forecast calculation.

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen.

prediction_id
string (required) 

the id of the prediction.

Update portions

POST https://co2.eaternity.ch/api//prognosis/kitchen_id/portions
Requestsexample 1
Headers
Content-Type: application/json
Body
{
  "recipes": [
    {
      "recipe-id": "Hello, world!",
      "sold-portions": 1,
      "production-portions": 1
    }
  ]
}
Schema
{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "recipes": {
      "type": "array",
      "description": "The list of recipes to update."
    }
  }
}
Responses200
Headers
Content-Type: application/json
Body
{
  "recipes": [
    {
      "recipe-id": "11111",
      "status": "UPDATED"
    },
    {
      "recipe-id": "22222",
      "status": "NOT_FOUND"
    }
  ]
}

Update portions
POST/prognosis/{kitchen_id}/portions

This post request updates the production-portions and sold-portions of multiple recipes.

URI Parameters
HideShow
kitchen_id
string (required) 

the id of the kitchen to which the recipes belong

Generated by aglio on 17 Jul 2024