forked from Eaternity/eaternity-api
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathapiary.apib
1809 lines (1561 loc) · 79.6 KB
/
apiary.apib
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
FORMAT: 1A
HOST: https://co2.eaternity.ch/api/
# Eaternity Database (EDB) 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](http://www.eaternity.org/foodprint/)). It further delivers reports with sophisticated and easy to understand statistics, graphs and analysis ([more Informations on the reports](http://www.eaternity.org/app/report)).
The Eaternity Database API is a [RESTful](http://en.wikipedia.org/wiki/Representational_State_Transfer) 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.
### Terms & Conditions
By accessing the APIs, you accept the Eaternity's [Terms & Conditions](http://www.eaternity.org/legal). 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](https://www.eaternity.org/assets/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'`
We can recommend using [Postman](https://www.getpostman.com) for testing.
For this purpose we provide some sample request in a public Postman Collection, that you find here: [https://app.getpostman.com/run-collection/51358cb9f878e2d2260d](https://app.getpostman.com/run-collection/51358cb9f878e2d2260d)
Or you can check out the examples below.
Join us on Slack [here](https://eaternity-edb-api-slack-invite.herokuapp.com) to get in touch with our developers.
### 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](http://www.loc.gov/standards/iso639-2/php/code_list.php) 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](https://regexr.com/3mho5): [-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 [here](https://drive.google.com/drive/folders/0B0PtIxbyLjvFRWFaSDFNcXRXeHM?usp=sharing).
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.
* 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.
## 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](http://www.eaternity.org/foodprint/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](http://www.eaternity.org/foodprint/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.|
##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 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](http://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||
|indicators|dictionary|the vita and nutritional indicators described above||
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|
# Group 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 [/kitchens/]
### Create new kitchen [POST]
+ Request (application/json)
{ "kitchen": {
"name": "police canteen",
"location": "zurich, switzerland",
"email": "[email protected]",
"language": "en"
}
}
+ Response 201 (application/json)
+ Headers
Location: https://co2.eaternity.ch/api/kitchens/198764
+ Body
{ "kitchen": {
"id": "198764",
"name": "police canteen",
"location": "zurich, switzerland",
"email": "[email protected]",
"language": "en"
}
}
### Get all kitchens of this client [GET]
A list of kitchen ids of this client (one API Key) is returned.
+ Response 200 (application/json)
{
"kitchens": [ "45674","42344","42233","48855" ]
}
## Kitchen [/kitchens/{kitchen_id}]
### Get a kitchen [GET]
Get the whole kitchen resource.
+ Response 200 (application/json)
{ "kitchen": {
"id": "198764",
"name": "police canteen",
"location": "zurich, switzerland",
"email": "[email protected]",
"language": "en"
}
}
### Create or update a kitchen [PUT]
Update or create the kitchen with the specific id
+ Request (application/json)
{ "kitchen": {
"name": "police canteen",
"location": "zurich, switzerland",
"email": "[email protected]",
"language": "en"
}
}
+ Response 201 (application/json)
+ Headers
Location: https://co2.eaternity.ch/api/kitchens/198764
+ Body
{ "kitchen": {
"id": "198764",
"name": "police canteen",
"location": "zurich, switzerland",
"email": "[email protected]",
"language": "en"
}
}
### Delete a kitchen [DELETE]
Deletes this kitchen from the server
+ Response 204
# Group 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 not be permanently 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. |no. use 'recipe-portions'.|
|recipe-portions|int|for how many portions the ingredients are specified. Replaces 'servings'.|no|
|planned-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|
|**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 co2 saved by serving this recipe instead of serving the amount of an average product that provides the same nutritional value||
|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 [/recipes]
### Create a recipe [POST]
Create a recipe resource and receive the CO₂-Value and Eaternity Award. Example of a full request with all fields used:
+ Request (application/json)
{
"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,
"instructions": [
{
"language": "de",
"value": "Den Karottenkuchen im Ofen backen und noch warm geniessen."
},
{
"language": "en",
"value": "Bake the carrot cake in the oven and enjoy while still hot."
}],
"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"
}
]
}
}
+ Response 200 (application/json)
+ Headers
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",
"vita-score-award": true,
"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.0
},
}
}
## Recipe [/recipes/{id}?indicators=true]
### Get Recipe [GET]
Get the up-to-date CO₂-Value (and other indicators) for this recipe for the current date
+ Response 200 (application/json)
{
"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",
"vita-score-award": true,
"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.0
},
"titles": [
{
"language": "de",
"value": "Kürbisrisotto"
},
{
"language": "en",
"value": "Pumpkin Risotto"
}],
"author": "Eckart Witzigmann",
"date": "2013-10-14",
"location": "Zürich Schweiz",
"servings": 140,
"instructions": [
{
"language": "de",
"value": "Den Karottenkuchen im Ofen backen und noch warm geniessen."
},
{
"language": "en",
"value": "Bake the carrot cake in the oven and enjoy while still hot."
}],
"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.00,
"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.00,
"co2-value": 75
}
]
}
}
### Update or create new recipe [PUT]
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).
+ Request (application/json)
{
"recipe": {
"titles": [
{
"language": "de",
"value": "Kürbisrisotto"
}],
"author": "Eckart Witzigmann",
"date": "2013-10-14",
"location": "Zürich Schweiz",
"servings": 140,
"instructions": [
{
"language": "de",
"value": "Den Karottenkuchen im Ofen backen und noch warm geniessen."
},
{
"language": "en",
"value": "Bake the carrot cake in the oven and enjoy while still hot."
}],
"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": ""
}
]
}
}
+ Response 200 (application/json)
{
"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",
"vita-score-award": true,
"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
}
}
### Delete the recipe [DELETE]
Deletes this recipe from the server
+ Response 204
## Kitchen Recipe Collection [/kitchens/{kitchen_id}/recipes]
No recipe location needs to be provided.
### Create a recipe [POST]
Create a recipe resource in a specific kitchen and receive the CO₂-Value and Eaternity Award
+ Request (application/json)
{
"recipe": {
"titles": [
{
"language": "de",
"value": "Kürbisrisotto"
}],
"author": "Eckart Witzigmann",
"date": "2013-10-14",
"location": "Zürich Schweiz",
"servings": 140,
"instructions": [
{
"language": "de",
"value": "Den Karottenkuchen im Ofen backen und noch warm geniessen."
},
{
"language": "en",
"value": "Bake the carrot cake in the oven and enjoy while still hot."
}],
"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": ""
}
]
}
}
+ Response 200 (application/json)
ed
+ Headers
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",
"indicators": {
"vita-score": {
"vita-score-points": 346,
"vita-score-rating": "B",
"vita-score-award": true,
"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.0
}
}
}
### Get all recipes contained in this kitchen [GET]
A list of recipe ids is returned.
+ Response 200 (application/json)
{
"recipes": [ "298374","298345","298454","298345","298456","294564" ]
}
## Kitchen Recipe [/kitchens/{kitchen_id}/recipes/{recipe_id}]
### Get Recipe [GET]
Get the up-to-date CO₂-Value for this recipe for the current date
+ Response 200 (application/json)
{
"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,
"instructions": [
{
"language": "de",
"value": "Den Karottenkuchen im Ofen backen und noch warm geniessen."
},
{
"language": "en",
"value": "Bake the carrot cake in the oven and enjoy while still hot."
}],
"indicators": {
"vita-score": {
"vita-score-points": 346,
"vita-score-rating": "B",
"vita-score-award": true,
"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",
"vita-score-award": true,
"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",