Eaternity Client API
API Endpoint
https://co2.eaternity.ch/apiThe 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). Data provided to Eaternity via this API allows for in-depth analyses and reports (more Informations on the reports).
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.
Authentication
To access the API, use Basic Authentication with your API key as the username and an empty password.
-
Example
curl -u YOUR_API_KEY: \ -H "Content-Type: application/json" \ -X GET https://co2.eaternity.ch/api/kitchens
Join us on Slack here to get in touch with our developers.
Kitchen Resources ¶
A kitchen is any place where food is prepared and or sold. It can be a restaurant, a factory, a canteen or anything similar. The kitchen resource contains all information about the kitchen, including the name, location. Kitchens are the basis basic grouping for recipes and supplies. Reports and statistics are provided on this level.
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 |
| 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 ¶
Headers
Content-Type: application/jsonBody
{
"kitchen": {
"name": "Kitchen Restaurant A",
"location": "Zurich, Switzerland",
"email": "kitchen-a@test-customer.com",
"language": "en",
"id": "kitchen-restaurant-a"
}
}Headers
Content-Type: application/json
Location: http://co2.eaternity.ch/api/kitchens/kitchen-restaurant-aBody
{
"kitchen": {
"name": "Kitchen Restaurant A",
"location": "Zurich, Switzerland",
"email": "kitchen-a@test-customer.com",
"language": "en",
"id": "kitchen-restaurant-a"
}
}Create new kitchenPOST/kitchens/
Create a kitchen without specifying a particular kitchen ID.
Headers
Content-Type: application/jsonBody
{
"kitchens": [
"kitchen-restaurant-a"
]
}Get all kitchens of this clientGET/kitchens/
A list of kitchen ids of this client (one API Key) is returned.
Kitchen ¶
Headers
Content-Type: application/jsonBody
{
"kitchen": {
"name": "Kitchen Restaurant A",
"location": "Zurich, Switzerland",
"email": "kitchen-a@test-customer.com",
"language": "en",
"id": "kitchen-restaurant-a"
}
}Get a kitchenGET/kitchens/{kitchen_id}
Get the whole kitchen resource.
- kitchen_id
string(required)the id of the kitchen.
Headers
Content-Type: application/jsonBody
{
"kitchen": {
"name": "Kitchen Restaurant A",
"location": "Zurich, Switzerland",
"email": "kitchen-a@test-customer.com",
"language": "en"
}
}Headers
Content-Type: application/json
Location: http://co2.eaternity.ch/api/kitchens/kitchen-restaurant-aBody
{
"kitchen": {
"name": "Kitchen Restaurant A",
"location": "Zurich, Switzerland",
"email": "kitchen-a@test-customer.com",
"language": "en",
"id": "kitchen-restaurant-a"
}
}Headers
Content-Type: application/json
Location: http://co2.eaternity.ch/api/kitchens/kitchen-restaurant-aBody
{
"kitchen": {
"name": "Kitchen Restaurant A",
"location": "Zurich, Switzerland",
"email": "kitchen-a@test-customer.com",
"language": "en",
"id": "kitchen-restaurant-a"
}
}Create or update a kitchenPUT/kitchens/{kitchen_id}
Update or create the kitchen with the specific id
- kitchen_id
string(required)the id of the kitchen.
Delete a kitchenDELETE/kitchens/{kitchen_id}
Deletes this kitchen from the server
- kitchen_id
string(required)the id of the kitchen.
Recipe Resources ¶
A recipe is a collection of ingredients, instructions and other information that describes how a food item sold in a restaurant is composed. It is the basis for the calculation of the CO₂-value and other indicators. The recipe resource contains all information about the recipe, including the ingredients, instructions, and other metadata.
Uniqueness of Recipes
Note that for every time, a recipe is offered in a kitchen, a new id has to be used.
Example 1:
Your business runs Kitchen A and Kitchen B. On the 1st of April, both kitchens offer pumpkin risotto, using the same ingredients. You will have to create two different recipes with two different ids.
Example 2:
Your business runs Kitchen A and Kitchen B. On the 1st of April, both kitchens offer pumpkin risotto. On the 2nd of April, Kitchen A offers pumpkin risotto again. You will have to create three different recipes with three different ids.
Sub-Recipes
In the examples above, all individual recipes may contain the identical sub-recipe pumpkin risotto as an ingredient, having the same id each time. The sub-recipe pumpkin risotto will be stored only once in the database. The drawback of reusing the id is that you will not be able to change the composition idividually without impacting all usages of the sub-recipe. So consider using individual ids for sub-recipes as well.
Make sure to that you are using the flag transient=true for the sub-recipes in any case. The sub-recipe on its own will then not be included in the monthly summary.
URL Parameters
| Parameters | Type | Description |
|---|---|---|
| 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. |
Batch Operations on Recipe Resources ¶
Batch operations allow you to create, update or delete multiple recipes at once. They are the most efficient way to work with the Eaternity API. The batch operations can check consistency in between recipes that depend on each other. For example, if you have a recipe with a sub-recipe, the batch operation will check if the sub-recipe is already in the database and will return an error if it is not. This is not possible with single requests. Batch operations are limited by the computational resources required for the calculations. We recommend a maximum of 100 recipes per request but the limit is not fixed. The server will return an error if the request is too large. The batch operations are not atomic, meaning that if one recipe fails, the others may still be processed. The response will contain the status of each recipe in the batch.
The transient parameter can be set selectively per recipe inside the batch.Transient recipes are not included in the monthly summary and do not contribute to the kitchen’s statistics. This applies for recipes that are transmitted for use as subrecipes or sent for testing purposes.
The message in the response provides more details about the failure of individual recipes.
Headers
Content-Type: application/jsonBody
[
{
"request-id": 0,
"recipe": {
"id": "internal-recipe-id3",
"transient": true,
"kitchen-id": "kitchen-restaurant-a",
"titles": [
{
"language": "en",
"value": "Mushroom gravy on pumpkin risotto"
}
],
"recipe-portions": 1,
"ingredients": [
{
"id": "internal-recipe-id1",
"type": "recipes",
"amount": 250,
"unit": "gram"
},
{
"id": "internal-recipe-id2",
"type": "recipes",
"amount": 50,
"unit": "gram"
}
]
}
},
{
"request-id": 1,
"transient": true,
"recipe": {
"id": "internal-recipe-id1",
"kitchen-id": "kitchen-restaurant-a",
"titles": [
{
"language": "en",
"value": "pumpkin risotto"
}
],
"recipe-portions": 100,
"ingredients": [
{
"id": "101",
"type": "conceptual-ingredients",
"names": [
{
"language": "en",
"value": "pumpkin"
},
{
"language": "de",
"value": "Kürbis"
}
],
"amount": 250,
"unit": "gram"
},
{
"id": "102",
"type": "conceptual-ingredients",
"names": [
{
"language": "en",
"value": "risotto rice"
}
],
"amount": 5000,
"unit": "gram",
"origin": "Italy",
"transport": "ground",
"conservation": "dried"
}
]
}
},
{
"request-id": 2,
"transient": true,
"recipe": {
"id": "internal-recipe-id2",
"kitchen-id": "kitchen-restaurant-a",
"titles": [
{
"language": "en",
"value": "Mushroom gravy"
}
],
"recipe-portions": 5,
"ingredients": [
{
"id": "103",
"type": "conceptual-ingredients",
"names": [
{
"language": "en",
"value": "Mushrooms"
}
],
"amount": 150,
"unit": "gram"
},
{
"id": "104",
"type": "conceptual-ingredients",
"names": [
{
"language": "de",
"value": "onions"
}
],
"amount": 78,
"unit": "gram"
}
]
}
},
{
"request-id": 3,
"recipe": {
"id": "menu-id1-fitness-2016-11-28",
"kitchen-id": "kitchen-restaurant-a",
"transient": false,
"menu-line-name": "Fitness",
"menu-line-id": 1,
"titles": [
{
"language": "en",
"value": "Fitness Risotto"
}
],
"recipe-portions": 1,
"date": "2016-11-28",
"ingredients": [
{
"id": "internal-recipe-id3",
"type": "recipes",
"amount": 288,
"unit": "gram"
}
]
}
}
]Headers
Content-Type: application/jsonBody
[
{
"statuscode": 200,
"message": "",
"recipe-id": "internal-recipe-id3",
"request-id": 0,
"recipe": {
"food-unit": 1.36,
"final-weight-per-portion": 300,
"indicators": {
"vita-score": {
"vita-score-points": 356.3,
"vita-score-rating": "C",
"vita-score-improvement-percentage": -4.79,
"energy-kcals": 889.16,
"nutrition-label": false,
"fruit-risk-factor-amount-gram": 0,
"fruit-risk-factor-points": 61.24,
"vegetable-risk-factor-amount-gram": 29.01,
"vegetable-risk-factor-points": 30.57,
"wholegrain-risk-factor-amount-gram": 0,
"wholegrain-risk-factor-points": 82.86,
"nuts-seeds-risk-factor-amount-gram": 0,
"nuts-seeds-risk-factor-points": 13.98,
"milk-risk-factor-amount-gram": 0,
"milk-risk-factor-points": 9.42,
"processed-meat-risk-factor-amount-gram": 0,
"processed-meat-risk-factor-points": 0,
"red-meat-risk-factor-amount-gram": 0,
"red-meat-risk-factor-points": 0,
"salt-risk-factor-amount-gram": 0.01,
"salt-risk-factor-points": 0,
"high-in-energy-risk-factor-points": 35.34,
"high-in-fat-risk-factor-points": 0,
"low-in-fat-risk-factor-points": 88.66,
"high-in-protein-risk-factor-points": 0,
"low-in-protein-risk-factor-points": 34.23
},
"environment": {
"scarce-water-liters": 0.05,
"water-footprint-rating": "A",
"water-footprint-reduction-value": 49.58,
"water-footprint-award": true,
"water-footprint-improvement-percentage": 99.9,
"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": 431,
"rating": "A",
"co2-value-improvement-percentage": 59,
"co2-value-reduction-value": 624,
"id": "internal-recipe-id3",
"kitchen-id": "kitchen-restaurant-a",
"titles": [
{
"language": "en",
"value": "Mushroom gravy on pumpkin risotto"
}
],
"servings": 1,
"recipe-portions": 1,
"ingredients": [
{
"foodUnit": 1.29,
"indicators": {
"vita-score": {
"vita-score-points": 354.93,
"vita-score-rating": "C",
"vita-score-improvement-percentage": -4.39,
"energy-kcals": 872.11,
"nutrition-label": false,
"fruit-risk-factor-amount-gram": 0,
"fruit-risk-factor-points": 61.24,
"vegetable-risk-factor-amount-gram": 11.9,
"vegetable-risk-factor-points": 30.57,
"wholegrain-risk-factor-amount-gram": 0,
"wholegrain-risk-factor-points": 82.86,
"nuts-seeds-risk-factor-amount-gram": 0,
"nuts-seeds-risk-factor-points": 13.98,
"milk-risk-factor-amount-gram": 0,
"milk-risk-factor-points": 9.42,
"processed-meat-risk-factor-amount-gram": 0,
"processed-meat-risk-factor-points": 0,
"red-meat-risk-factor-amount-gram": 0,
"red-meat-risk-factor-points": 0,
"salt-risk-factor-amount-gram": 0.01,
"salt-risk-factor-points": 0,
"high-in-energy-risk-factor-points": 32.82,
"high-in-fat-risk-factor-points": 0,
"low-in-fat-risk-factor-points": 88.66,
"high-in-protein-risk-factor-points": 0,
"low-in-protein-risk-factor-points": 35.38
},
"environment": {
"scarce-water-liters": 0.02,
"water-footprint-rating": "A",
"water-footprint-reduction-value": 47.24,
"water-footprint-award": true,
"water-footprint-improvement-percentage": 99.96,
"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"
}
},
"co2-value": 404,
"rating": "A",
"co2-value-improvement-percentage": 60,
"co2-value-reduction-value": 601,
"bar-chart": 94,
"id": "internal-recipe-id1",
"type": "recipes",
"amount": 250,
"unit": "gram",
"origin": "",
"transport": "",
"production": "",
"processing": "",
"conservation": "",
"packaging": ""
},
{
"foodUnit": 0.06,
"indicators": {
"vita-score": {
"vita-score-points": 266.22,
"vita-score-rating": "A",
"vita-score-improvement-percentage": 21.7,
"energy-kcals": 17.04,
"nutrition-label": false,
"fruit-risk-factor-amount-gram": 0,
"fruit-risk-factor-points": 61.24,
"vegetable-risk-factor-amount-gram": 17.11,
"vegetable-risk-factor-points": 0,
"wholegrain-risk-factor-amount-gram": 0,
"wholegrain-risk-factor-points": 82.86,
"nuts-seeds-risk-factor-amount-gram": 0,
"nuts-seeds-risk-factor-points": 13.98,
"milk-risk-factor-amount-gram": 0,
"milk-risk-factor-points": 9.42,
"processed-meat-risk-factor-amount-gram": 0,
"processed-meat-risk-factor-points": 0,
"red-meat-risk-factor-amount-gram": 0,
"red-meat-risk-factor-points": 0,
"salt-risk-factor-amount-gram": 0.01,
"salt-risk-factor-points": 0,
"high-in-energy-risk-factor-points": 0,
"high-in-fat-risk-factor-points": 0,
"low-in-fat-risk-factor-points": 73.86,
"high-in-protein-risk-factor-points": 24.86,
"low-in-protein-risk-factor-points": 0
},
"environment": {
"scarce-water-liters": 0.03,
"water-footprint-rating": "A",
"water-footprint-reduction-value": 2.34,
"water-footprint-award": true,
"water-footprint-improvement-percentage": 98.71,
"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"
}
},
"co2-value": 27,
"rating": "B",
"co2-value-improvement-percentage": 47,
"co2-value-reduction-value": 23,
"bar-chart": 6,
"id": "internal-recipe-id2",
"type": "recipes",
"amount": 50,
"unit": "gram",
"origin": "",
"transport": "",
"production": "",
"processing": "",
"conservation": "",
"packaging": ""
}
]
}
},
{
"statuscode": 200,
"message": "",
"recipe-id": "internal-recipe-id1",
"request-id": 1,
"recipe": {
"food-unit": 0.27,
"final-weight-per-portion": 52.5,
"indicators": {
"vita-score": {
"vita-score-points": 322.11,
"vita-score-rating": "B",
"vita-score-improvement-percentage": 5.26,
"energy-kcals": 183.14,
"nutrition-label": false,
"fruit-risk-factor-amount-gram": 0,
"fruit-risk-factor-points": 61.24,
"vegetable-risk-factor-amount-gram": 2.5,
"vegetable-risk-factor-points": 30.57,
"wholegrain-risk-factor-amount-gram": 0,
"wholegrain-risk-factor-points": 82.86,
"nuts-seeds-risk-factor-amount-gram": 0,
"nuts-seeds-risk-factor-points": 13.98,
"milk-risk-factor-amount-gram": 0,
"milk-risk-factor-points": 9.42,
"processed-meat-risk-factor-amount-gram": 0,
"processed-meat-risk-factor-points": 0,
"red-meat-risk-factor-amount-gram": 0,
"red-meat-risk-factor-points": 0,
"salt-risk-factor-amount-gram": 0,
"salt-risk-factor-points": 0,
"high-in-energy-risk-factor-points": 0,
"high-in-fat-risk-factor-points": 0,
"low-in-fat-risk-factor-points": 88.66,
"high-in-protein-risk-factor-points": 0,
"low-in-protein-risk-factor-points": 35.38
},
"environment": {
"scarce-water-liters": 0,
"water-footprint-rating": "A",
"water-footprint-reduction-value": 9.92,
"water-footprint-award": true,
"water-footprint-improvement-percentage": 99.96,
"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": 85,
"rating": "A",
"co2-value-improvement-percentage": 60,
"co2-value-reduction-value": 126,
"id": "internal-recipe-id1",
"kitchen-id": "kitchen-restaurant-a",
"titles": [
{
"language": "en",
"value": "pumpkin risotto"
}
],
"servings": 100,
"recipe-portions": 100,
"ingredients": [
{
"foodUnit": 0.19,
"indicators": {
"vita-score": {
"vita-score-points": 285.13,
"vita-score-rating": "B",
"vita-score-improvement-percentage": 16.14,
"energy-kcals": 58.55,
"nutrition-label": false,
"fruit-risk-factor-amount-gram": 0,
"fruit-risk-factor-points": 61.24,
"vegetable-risk-factor-amount-gram": 250,
"vegetable-risk-factor-points": 0,
"wholegrain-risk-factor-amount-gram": 0,
"wholegrain-risk-factor-points": 82.86,
"nuts-seeds-risk-factor-amount-gram": 0,
"nuts-seeds-risk-factor-points": 13.98,
"milk-risk-factor-amount-gram": 0,
"milk-risk-factor-points": 9.42,
"processed-meat-risk-factor-amount-gram": 0,
"processed-meat-risk-factor-points": 0,
"red-meat-risk-factor-amount-gram": 0,
"red-meat-risk-factor-points": 0,
"salt-risk-factor-amount-gram": 0.01,
"salt-risk-factor-points": 0,
"high-in-energy-risk-factor-points": 0,
"high-in-fat-risk-factor-points": 0,
"low-in-fat-risk-factor-points": 88.66,
"high-in-protein-risk-factor-points": 0,
"low-in-protein-risk-factor-points": 28.97
},
"environment": {
"scarce-water-liters": 0.41,
"water-footprint-rating": "A",
"water-footprint-reduction-value": 6.55,
"water-footprint-award": true,
"water-footprint-improvement-percentage": 94.16,
"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"
}
},
"co2-value": 25,
"rating": "A",
"co2-value-improvement-percentage": 83,
"co2-value-reduction-value": 123,
"bar-chart": 0,
"id": "101",
"type": "conceptual-ingredients",
"names": [
{
"language": "en",
"value": "pumpkin"
},
{
"language": "de",
"value": "Kürbis"
}
],
"amount": 250,
"unit": "gram",
"origin": "",
"transport": "",
"production": "",
"processing": "",
"conservation": "",
"packaging": "",
"gtin": ""
},
{
"foodUnit": 26.91,
"indicators": {
"vita-score": {
"vita-score-points": 410.79,
"vita-score-rating": "C",
"vita-score-improvement-percentage": -20.82,
"energy-kcals": 18255.85,
"nutrition-label": false,
"fruit-risk-factor-amount-gram": 0,
"fruit-risk-factor-points": 61.24,
"vegetable-risk-factor-amount-gram": 0,
"vegetable-risk-factor-points": 30.57,
"wholegrain-risk-factor-amount-gram": 0,
"wholegrain-risk-factor-points": 82.86,
"nuts-seeds-risk-factor-amount-gram": 0,
"nuts-seeds-risk-factor-points": 13.98,
"milk-risk-factor-amount-gram": 0,
"milk-risk-factor-points": 9.42,
"processed-meat-risk-factor-amount-gram": 0,
"processed-meat-risk-factor-points": 0,
"red-meat-risk-factor-amount-gram": 0,
"red-meat-risk-factor-points": 0,
"salt-risk-factor-amount-gram": 0.13,
"salt-risk-factor-points": 0,
"high-in-energy-risk-factor-points": 88.66,
"high-in-fat-risk-factor-points": 0,
"low-in-fat-risk-factor-points": 88.66,
"high-in-protein-risk-factor-points": 0,
"low-in-protein-risk-factor-points": 35.4
},
"environment": {
"scarce-water-liters": 0,
"water-footprint-rating": "A",
"water-footprint-reduction-value": 985.53,
"water-footprint-award": true,
"water-footprint-improvement-percentage": 100,
"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"
}
},
"co2-value": 8452,
"rating": "A",
"co2-value-improvement-percentage": 60,
"co2-value-reduction-value": 12504,
"bar-chart": 100,
"id": "102",
"type": "conceptual-ingredients",
"names": [
{
"language": "en",
"value": "risotto rice"
}
],
"amount": 5000,
"unit": "gram",
"origin": "Italy",
"transport": "ground",
"production": "",
"processing": "",
"conservation": "dried",
"packaging": "",
"gtin": ""
}
]
}
},
{
"statuscode": 200,
"message": "",
"recipe-id": "internal-recipe-id2",
"request-id": 2,
"recipe": {
"food-unit": 0.06,
"final-weight-per-portion": 45.6,
"indicators": {
"vita-score": {
"vita-score-points": 266.22,
"vita-score-rating": "A",
"vita-score-improvement-percentage": 21.7,
"energy-kcals": 15.54,
"nutrition-label": false,
"fruit-risk-factor-amount-gram": 0,
"fruit-risk-factor-points": 61.24,
"vegetable-risk-factor-amount-gram": 15.6,
"vegetable-risk-factor-points": 0,
"wholegrain-risk-factor-amount-gram": 0,
"wholegrain-risk-factor-points": 82.86,
"nuts-seeds-risk-factor-amount-gram": 0,
"nuts-seeds-risk-factor-points": 13.98,
"milk-risk-factor-amount-gram": 0,
"milk-risk-factor-points": 9.42,
"processed-meat-risk-factor-amount-gram": 0,
"processed-meat-risk-factor-points": 0,
"red-meat-risk-factor-amount-gram": 0,
"red-meat-risk-factor-points": 0,
"salt-risk-factor-amount-gram": 0.01,
"salt-risk-factor-points": 0,
"high-in-energy-risk-factor-points": 0,
"high-in-fat-risk-factor-points": 0,
"low-in-fat-risk-factor-points": 73.86,
"high-in-protein-risk-factor-points": 24.86,
"low-in-protein-risk-factor-points": 0
},
"environment": {
"scarce-water-liters": 0.03,
"water-footprint-rating": "A",
"water-footprint-reduction-value": 2.13,
"water-footprint-award": true,
"water-footprint-improvement-percentage": 98.71,
"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": false,
"co2-value": 24,
"rating": "B",
"co2-value-improvement-percentage": 47,
"co2-value-reduction-value": 22,
"id": "internal-recipe-id2",
"kitchen-id": "kitchen-restaurant-a",
"titles": [
{
"language": "en",
"value": "Mushroom gravy"
}
],
"servings": 5,
"recipe-portions": 5,
"ingredients": [
{
"foodUnit": 0.21,
"indicators": {
"vita-score": {
"vita-score-points": 316.19,
"vita-score-rating": "B",
"vita-score-improvement-percentage": 7,
"energy-kcals": 47.32,
"nutrition-label": false,
"fruit-risk-factor-amount-gram": 0,
"fruit-risk-factor-points": 61.24,
"vegetable-risk-factor-amount-gram": 0,
"vegetable-risk-factor-points": 30.57,
"wholegrain-risk-factor-amount-gram": 0,
"wholegrain-risk-factor-points": 82.86,
"nuts-seeds-risk-factor-amount-gram": 0,
"nuts-seeds-risk-factor-points": 13.98,
"milk-risk-factor-amount-gram": 0,
"milk-risk-factor-points": 9.42,
"processed-meat-risk-factor-amount-gram": 0,
"processed-meat-risk-factor-points": 0,
"red-meat-risk-factor-amount-gram": 0,
"red-meat-risk-factor-points": 0,
"salt-risk-factor-amount-gram": 0.02,
"salt-risk-factor-points": 0,
"high-in-energy-risk-factor-points": 0,
"high-in-fat-risk-factor-points": 0,
"low-in-fat-risk-factor-points": 63.4,
"high-in-protein-risk-factor-points": 54.72,
"low-in-protein-risk-factor-points": 0
},
"environment": {
"scarce-water-liters": 0,
"water-footprint-rating": "A",
"water-footprint-reduction-value": 7.79,
"water-footprint-award": true,
"water-footprint-improvement-percentage": 100,
"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"
}
},
"co2-value": 92,
"rating": "B",
"co2-value-improvement-percentage": 44,
"co2-value-reduction-value": 73,
"bar-chart": 76,
"id": "103",
"type": "conceptual-ingredients",
"names": [
{
"language": "en",
"value": "Mushrooms"
}
],
"amount": 150,
"unit": "gram",
"origin": "",
"transport": "",
"production": "",
"processing": "",
"conservation": "",
"packaging": "",
"gtin": ""
},
{
"foodUnit": 0.08,
"indicators": {
"vita-score": {
"vita-score-points": 277.8,
"vita-score-rating": "A",
"vita-score-improvement-percentage": 18.29,
"energy-kcals": 30.39,
"nutrition-label": false,
"fruit-risk-factor-amount-gram": 0,
"fruit-risk-factor-points": 61.24,
"vegetable-risk-factor-amount-gram": 78,
"vegetable-risk-factor-points": 0,
"wholegrain-risk-factor-amount-gram": 0,
"wholegrain-risk-factor-points": 82.86,
"nuts-seeds-risk-factor-amount-gram": 0,
"nuts-seeds-risk-factor-points": 13.98,
"milk-risk-factor-amount-gram": 0,
"milk-risk-factor-points": 9.42,
"processed-meat-risk-factor-amount-gram": 0,
"processed-meat-risk-factor-points": 0,
"red-meat-risk-factor-amount-gram": 0,
"red-meat-risk-factor-points": 0,
"salt-risk-factor-amount-gram": 0.01,
"salt-risk-factor-points": 0,
"high-in-energy-risk-factor-points": 0,
"high-in-fat-risk-factor-points": 0,
"low-in-fat-risk-factor-points": 88.66,
"high-in-protein-risk-factor-points": 0,
"low-in-protein-risk-factor-points": 21.64
},
"environment": {
"scarce-water-liters": 0.14,
"water-footprint-rating": "A",
"water-footprint-reduction-value": 2.87,
"water-footprint-award": true,
"water-footprint-improvement-percentage": 95.38,
"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"
}
},
"co2-value": 30,
"rating": "A",
"co2-value-improvement-percentage": 53,
"co2-value-reduction-value": 34,
"bar-chart": 24,
"id": "104",
"type": "conceptual-ingredients",
"names": [
{
"language": "de",
"value": "onions"
}
],
"amount": 78,
"unit": "gram",
"origin": "",
"transport": "",
"production": "",
"processing": "",
"conservation": "",
"packaging": "",
"gtin": ""
}
]
}
},
{
"statuscode": 200,
"message": "",
"recipe-id": "menu-id1-fitness-2016-11-28",
"request-id": 3,
"recipe": {
"food-unit": 1.3,
"final-weight-per-portion": 288,
"indicators": {
"vita-score": {
"vita-score-points": 351.04,
"vita-score-rating": "C",
"vita-score-improvement-percentage": -3.25,
"energy-kcals": 853.59,
"nutrition-label": false,
"fruit-risk-factor-amount-gram": 0,
"fruit-risk-factor-points": 61.24,
"vegetable-risk-factor-amount-gram": 27.85,
"vegetable-risk-factor-points": 30.57,
"wholegrain-risk-factor-amount-gram": 0,
"wholegrain-risk-factor-points": 82.86,
"nuts-seeds-risk-factor-amount-gram": 0,
"nuts-seeds-risk-factor-points": 13.98,
"milk-risk-factor-amount-gram": 0,
"milk-risk-factor-points": 9.42,
"processed-meat-risk-factor-amount-gram": 0,
"processed-meat-risk-factor-points": 0,
"red-meat-risk-factor-amount-gram": 0,
"red-meat-risk-factor-points": 0,
"salt-risk-factor-amount-gram": 0.01,
"salt-risk-factor-points": 0,
"high-in-energy-risk-factor-points": 30.08,
"high-in-fat-risk-factor-points": 0,
"low-in-fat-risk-factor-points": 88.66,
"high-in-protein-risk-factor-points": 0,
"low-in-protein-risk-factor-points": 34.23
},
"environment": {
"scarce-water-liters": 0.05,
"water-footprint-rating": "A",
"water-footprint-reduction-value": 47.6,
"water-footprint-award": true,
"water-footprint-improvement-percentage": 99.9,
"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": 414,
"rating": "A",
"co2-value-improvement-percentage": 59,
"co2-value-reduction-value": 599,
"id": "menu-id1-fitness-2016-11-28",
"kitchen-id": "kitchen-restaurant-a",
"titles": [
{
"language": "en",
"value": "Fitness Risotto"
}
],
"date": "2016-11-28",
"servings": 1,
"recipe-portions": 1,
"ingredients": [
{
"foodUnit": 1.3,
"indicators": {
"vita-score": {
"vita-score-points": 351.04,
"vita-score-rating": "C",
"vita-score-improvement-percentage": -3.25,
"energy-kcals": 853.59,
"nutrition-label": false,
"fruit-risk-factor-amount-gram": 0,
"fruit-risk-factor-points": 61.24,
"vegetable-risk-factor-amount-gram": 27.85,
"vegetable-risk-factor-points": 30.57,
"wholegrain-risk-factor-amount-gram": 0,
"wholegrain-risk-factor-points": 82.86,
"nuts-seeds-risk-factor-amount-gram": 0,
"nuts-seeds-risk-factor-points": 13.98,
"milk-risk-factor-amount-gram": 0,
"milk-risk-factor-points": 9.42,
"processed-meat-risk-factor-amount-gram": 0,
"processed-meat-risk-factor-points": 0,
"red-meat-risk-factor-amount-gram": 0,
"red-meat-risk-factor-points": 0,
"salt-risk-factor-amount-gram": 0.01,
"salt-risk-factor-points": 0,
"high-in-energy-risk-factor-points": 30.08,
"high-in-fat-risk-factor-points": 0,
"low-in-fat-risk-factor-points": 88.66,
"high-in-protein-risk-factor-points": 0,
"low-in-protein-risk-factor-points": 34.23
},
"environment": {
"scarce-water-liters": 0.05,
"water-footprint-rating": "A",
"water-footprint-reduction-value": 47.6,
"water-footprint-award": true,
"water-footprint-improvement-percentage": 99.9,
"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"
}
},
"co2-value": 414,
"rating": "A",
"co2-value-improvement-percentage": 59,
"co2-value-reduction-value": 599,
"bar-chart": 100,
"id": "internal-recipe-id3",
"type": "recipes",
"amount": 288,
"unit": "gram",
"origin": "",
"transport": "",
"production": "",
"processing": "",
"conservation": "",
"packaging": ""
}
],
"menu-line-name": "Fitness",
"menu-line-id": 1
}
}
]Create or update a batch of recipesPOST/recipes/batch?full-resource=true&indicators=true
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 is used to to attribute the impact to the respective kitchen’s statistics.
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 ids. 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.
In the following request, one menu item “Fitness Risotto” contains a single recipe “Mushroom gravy on pumpkin risotto”.
This recipe is again composed of two recipes, “pumpkin risotto” and “Mushroom gravy”. The recipes are all included in the batch.
The menu item is sold in the kitchen kitchen-restaurant-a on 2016 11 28. The id of the menu item is “menu-id1-fitness-2016-11-28” to illustrate that if a menu item is composed of identical recipes but in a different kitchen, the id of the menu item has to be different. The menu item is marked as not transient, meaning that it will be included in the monthly summary. The two recipes are transient, meaning that they will not again contribute to the monthly summary (their impact is already included in the menu item).
Headers
Content-Type: application/jsonBody
{
"recipes": [
"3948756",
"3948757",
"3948757"
]
}Headers
Content-Type: application/jsonBody
[
{
"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 recipesDELETE/recipes/batch?full-resource=true&indicators=true
Individual Recipes ¶
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. |
Headers
Content-Type: application/jsonBody
{
"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"
}
]
}
}Headers
Content-Type: application/json
Location: https://co2.eaternity.ch/api/recipes/d1ed2263-b1b2-4f50-9e9d-ba62cae81f29Body
{
"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",
"scarce-water-liters": 6,
"water-footprint-rating": "C",
"water-footprint-award": true
},
"foodUnit": 41
}
}
}Create a recipePOST/recipes
Create a recipe resource and receive the CO₂-Value and Eaternity Award. Example of a full request with all fields used:
- id
string(required)the id of the recipe.
Headers
Content-Type: application/jsonBody
{
"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",
"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 RecipeGET/recipes
Get the up-to-date CO₂-Value (and other indicators) for this recipe for the current date
Headers
Content-Type: application/jsonBody
{
"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": ""
}
]
}
}Headers
Content-Type: application/jsonBody
{
"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",
"scarce-water-liters": 6,
"water-footprint-rating": "C",
"water-footprint-award": true
},
"foodUnit": 41
}
}Update or create new recipePUT/recipes
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).
Delete the recipeDELETE/recipes
Deletes this recipe from the server
Kitchen Recipe Collection ¶
No recipe location needs to be provided.
Headers
Content-Type: application/jsonBody
{
"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": ""
}
]
}
}ed
Headers
Content-Type: application/json
Location: https://co2.eaternity.ch/api/kitchens/45674/recipes/d1ed2263-b1b2-4f50-9e9d-ba62cae81f29Body
{
"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",
"scarce-water-liters": 6,
"water-footprint-rating": "C",
"water-footprint-award": true
},
"foodUnit": 41
}
}
}Create a recipePOST/kitchens/{kitchen_id}/recipes
Create a recipe resource in a specific kitchen and receive the CO₂-Value and Eaternity Award
- kitchen_id
string(required)the id of the kitchen.
Headers
Content-Type: application/jsonBody
{
"recipes": [
"298374",
"298345",
"298454",
"298345",
"298456",
"294564"
]
}Get all recipes contained in this kitchenGET/kitchens/{kitchen_id}/recipes
A list of recipe ids is returned.
- kitchen_id
string(required)the id of the kitchen.
Kitchen Recipe ¶
Headers
Content-Type: application/jsonBody
{
"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",
"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",
"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",
"scarce-water-liters": 6.0,
"water-footprint-rating": "C",
"water-footprint-award": true
},
"foodUnit": 41.0
}
}
]
}
}Get RecipeGET/kitchens/{kitchen_id}/recipes/{recipe_id}
Get the up-to-date CO₂-Value for this recipe for the current date
- kitchen_id
string(required)the id of the kitchen.
- recipe_id
string(required)the id of the recipe.
Headers
Content-Type: application/jsonBody
{
"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": ""
}
]
}
}Headers
Content-Type: application/json
Location: https://co2.eaternity.ch/api/kitchens/45674/recipes/d1ed2263-b1b2-4f50-9e9d-ba62cae81f29Body
{
"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 a single recipePUT/kitchens/{kitchen_id}/recipes/{recipe_id}
Update or create a certain recipe with this id. The whole recipe with all ingredients must be provided again. (PUT overrides the existing resource).
- kitchen_id
string(required)the id of the kitchen.
- recipe_id
string(required)the id of the recipe.
Delete recipeDELETE/kitchens/{kitchen_id}/recipes/{recipe_id}
Deletes this recipe from the server
- kitchen_id
string(required)the id of the kitchen.
- recipe_id
string(required)the id of the recipe.
Recipe Properties ¶
Recipe Properties In Requests
| Property | Type | Description | Required |
|---|---|---|---|
| kitchen-id | string | the id of the kitchen the recipe belongs to. | yes |
| id | string | the id of the recipe. Either generated by Eaternity or supplied by the client | no |
| 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) | no; kitchen location will be used |
| servings (deprecated) | int | for how many servings the ingredients are given. | no; use ‘recipe-portions’ |
| recipe-portions | int | for how many portions the ingredients are specified. Replaces ‘servings’. | no; fallback is 1 |
| 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 |
| instructions | list of language objects | cooking instructions for the recipe in different languages (array of language objects) | 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 |
Recipe Properties In Responses only
| Property | Type | Description | Required |
|---|---|---|---|
| co2-value | int | the CO₂-Value of the whole recipe per serving in [g CO₂e / 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 | . |
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.
Ingredient Properties In 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 required. | yes |
| amount | float | amount of the ingredient in the specified unit | yes |
| unit | string | unit of the given amount of the ingredient: 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 Fisch: unboned or boned. Fisch: 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 | list of nutrient values | Structured list of the nutrients values per defined nutrient as defined below. | no |
| gtin | string | global trade item number: www.gtin.info | no |
There is a generic recommendation for the properties to be filled out, to handle the complexity of the data collection, which is to specify for ingredients if the product is air-freighted or not air-freighted, fresh, deep-frozen, dried, preserved, baked, canned, boiled, organic, Fairtrade certified, or fish from aquaculture.
Ingredient Properties In Responses only
To receive informations on the ingredients, the URL parameter full-resource must be set to true. This works for all recipe endpoints like /recipes/{id} and /recipes/batch.
| Property | Type | Description | Required |
|---|---|---|---|
| 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) |
Just like for recipes, the URL parameter indicators must be set to true to receive the indicators for the ingredients.
| Property | Type | Description | Required |
|---|---|---|---|
| indicators | dictionary | the vita and nutritional indicators described in the respective section |
The parameters of the properties origin, transport, production, processing, conservation and packaging can be set to multiple values. They need to be provided in a comma separated list.
"production": "organic, fair-trade, Max Havelaar"
The more properties are provided the more accurate are the 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 |
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 ¶
Headers
Content-Type: application/jsonBody
{ "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,
...
}
}
]
}
}Headers
Content-Type: application/json
Location: https://co2.eaternity.ch/api/kitchens/1987647/supplies/d1ed2263Body
{
"statuscode": 200,
"message": "",
"request-id": 0,
"supply-id": "d1ed2263"
}Create a supplyPOST/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.
- kitchen_id
string(required)the id of the kitchen.
Headers
Content-Type: application/jsonBody
{
"supplies": [
"d1ed2263",
"d1ed2264",
"d1ed2265",
"d1ed2268"
]
}Get all supplies in this kitchenGET/kitchens/{kitchen_id}/supplies/
Get all supplies contained in this kitchen. A list of supply ids is returned.
- kitchen_id
string(required)the id of the kitchen.
Supply ¶
Headers
Content-Type: application/jsonBody
{ "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",
"scarce-water-liters": 6.0,
"water-footprint-rating": "B",
"water-footprint-award": true
}
}
}
]
}
Get a supplyGET/kitchens/{kitchen_id}/supplies/{supply_id}?indicators=true
- kitchen_id
string(required)the id of the kitchen.
- supply_id
string(required)the id of the supply.
Headers
Content-Type: application/jsonBody
{
"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"
}
]
}
}Headers
Content-Type: application/json
Location: https://co2.eaternity.ch/api/kitchens/1987647/supplies/d1ed2263Body
{
"statuscode": 200,
"message": "",
"request-id": 0,
"supply-id": "d1ed2263"
}Update or create a supplyPUT/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.
- kitchen_id
string(required)the id of the kitchen.
- supply_id
string(required)the id of the supply.
Delete a supplyDELETE/kitchens/{kitchen_id}/supplies/{supply_id}?indicators=true
- kitchen_id
string(required)the id of the kitchen.
- supply_id
string(required)the id of the supply.
Batch operations on supply resources ¶
Headers
Content-Type: application/jsonBody
[
{
"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"
}
]
}
}
]Headers
Content-Type: application/jsonBody
[
{
"statuscode": 200,
"message": "",
"request-id": 1,
"supply-id": "d1ed2263"
},
{
"statuscode": 500,
"message": "Server Error. Just try again.",
"request-id": 2
}
]Create a batch of suppliesPOST/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).
Headers
Content-Type: application/jsonBody
{
"supplies": [
"d1ed2263",
"d1ed2267"
]
}Headers
Content-Type: application/jsonBody
[
{
"statuscode": 200,
"message": "",
"supply-id": "d1ed2263"
},
{
"statuscode": 200,
"message": "",
"supply-id": "d1ed2267"
}
]Delete a batch of suppliesDELETE/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 ¶
Headers
Content-Type: application/jsonBody
{
"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"
}Create a productPUT/products/{id}
Create or update a product.
- id
string(required)the id of the product.
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 productGET/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.
- 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 ¶
Headers
Content-Type: application/jsonBody
{
"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."
}
}
}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 forecastPOST/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.
- kitchen_id
string(required)the id of the kitchen, for which the prognosis is calculated
Forecast Results ¶
Headers
Content-Type: application/jsonBody
{
"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 forecastGET/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.
- kitchen_id
string(required)the id of the kitchen.
- prediction_id
string(required)the id of the prediction.
Update portions ¶
Headers
Content-Type: application/jsonBody
{
"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."
}
}
}Headers
Content-Type: application/jsonBody
{
"recipes": [
{
"recipe-id": "11111",
"status": "UPDATED"
},
{
"recipe-id": "22222",
"status": "NOT_FOUND"
}
]
}Update portionsPOST/prognosis/{kitchen_id}/portions
This post request updates the production-portions and sold-portions of multiple recipes.
- kitchen_id
string(required)the id of the kitchen to which the recipes belong
Advanced Information ¶
Localization
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 ids 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.
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. -
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. -
422
Request Validation Error- When the request is not valid against the schema we ask. For example you send an integer where a string was expected. -
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 does not match to the given options. Usually not dependent on the implementation but on the user input. -
612
Referenced sub-recipe is not in the database.- A referenced recipe was not provided in this or a previous request. Please provide the required recipe in advance. -
670
At least one (sub-) recipe has no ingredients.- “Something of nothing” does not work. You referenced a positive quantity of a sub-recipe that did have any quantitity itself.
Indicators 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, "indicators": { "vita-score": { "vita-score-points": 346, "vita-score-rating": "B", "vita-score-award": true, "energy-kcals": 457, "nutrition-label": true, "nutrition-rating": "A" }, "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 }, "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%] |
Vita Score
(Documentation of the Vita Score)
| Property | Type | Description |
|---|---|---|
| vita-score-points | int | The total score in points. |
| vita-score-rating | string | Rating of Vita Score: [A,B,C,D,E]. A is best, E is worst |
| vita-score-award | boolean | If the item receives the Vita Score Award. |
| energy-kcals | int | the total nutritional energy for the item in kilocalories |
| nutrition-label | boolean | whether a menu is nutritionally balanced |
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. |
Generated by aglio on 13 May 2025