Ricette

La Recipe API calcola i dati di impatto ambientale di piatti, pasti e menu completi. Per ogni ricetta restituisce i valori di CO2, le valutazioni nutrizionali e l'idoneità all'Eaternity Award.

Per esempi completi di request e response, consultate gli use case Valutazione dell'impatto delle ricette e Menu per la visualizzazione del piano dei menu e i report.

Panoramica

Usate la Recipe API per:

Calcolare l'impronta di carbonio (CO2) di singoli piatti
Elaborare in batch interi menu per l'analisi ambientale
Seguire nel tempo la sostenibilità delle ricette
Ottenere l'Eaternity Award per le ricette a basso impatto
Ottenere valutazioni della qualità nutrizionale (scala A-E)
Analizzare il contributo ambientale di ogni ingrediente

Unicità dell'ID della ricetta

L'API riconosce una ricetta solo dal suo id. Il kitchen-id e la date vengono salvati con la ricetta, ma non la rendono una ricetta diversa.

Se inviate una ricetta con un id già esistente, l'API sovrascrive la ricetta salvata, compresi kitchen-id e date. Il servizio precedente scompare allora da quella cucina e da quel giorno.

La regola: usate un nuovo id ogni volta che un piatto viene servito in una cucina in un determinato giorno.

Esempio 1: la cucina A e la cucina B servono entrambe un risotto alla zucca il 1° aprile. Inviate due ricette con due id diversi, per esempio risotto-kitchen-a-2026-04-01 e risotto-kitchen-b-2026-04-01. Con un id condiviso, la seconda request sposterebbe il risotto nella cucina B e la cucina A lo perderebbe dai suoi report.

Esempio 2: la cucina A serve di nuovo il risotto il 2 aprile. Si tratta di una terza ricetta con un terzo id, per esempio risotto-kitchen-a-2026-04-02. Riutilizzare l'id del 1° aprile sposterebbe il primo servizio al 2 aprile e il 1° aprile lo perderebbe.

Un modo semplice per avere ogni volta un nuovo id: combinate il vostro numero di ricetta con la cucina e la data.

Le sotto-ricette sono l'eccezione. Una sotto-ricetta come una salsa può mantenere lo stesso id in ogni menu che la usa; vedere Sotto-ricette. Per i menu inviati per cucina e data, vedere Menu per la visualizzazione del piano dei menu e i report.

Sotto-ricette

Le ricette possono fare riferimento ad altre ricette come ingredienti tramite il campo dell'ingrediente type: "recipes". Questo permette di comporre gerarchicamente i piatti del menu a partire da sotto-ricette riutilizzabili.

Tutte le singole ricette possono contenere la stessa sotto-ricetta (ad es. il risotto alla zucca) come ingrediente, usando ogni volta lo stesso ID.

Riutilizzo dell'ID di una sotto-ricetta

Riutilizzare lo stesso ID per una sotto-ricetta ha uno svantaggio: non potete modificarne la composizione singolarmente senza influire su tutte le ricette che vi fanno riferimento. Se avete bisogno di modifiche indipendenti, usate ID distinti per le sotto-ricette.

Le sotto-ricette vengono inviate come transitorie: contano solo attraverso il menu che le usa. Vedere Ricette transitorie.

Parametri di query

Tutti gli endpoint delle ricette accettano i parametri di query full-resource, indicators, nutrient-values, ingredients-declaration, return-uids e transient. Valori e default: Parametri di query. Per transient, vedere anche Ricette transitorie.

Esempi

# Get recipe with all indicators
curl "https://co2.eaternity.ch/api/kitchens/{kitchen_id}/recipes/{recipe_id}?indicators=true" \
  -u YOUR_API_KEY:

# Preview: calculate a recipe without keeping it (transient)
curl -X POST "https://co2.eaternity.ch/api/kitchens/{kitchen_id}/recipes?transient=true" \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{"recipe": {"titles": [{"language": "en", "value": "Test"}], "date": "2024-12-16", "ingredients": [...]}}'

# Get full response with internal UIDs
curl "https://co2.eaternity.ch/api/kitchens/{kitchen_id}/recipes/{recipe_id}?full-resource=true&return-uids=true" \
  -u YOUR_API_KEY:

Parametri specifici del batch

L'endpoint /recipes/batch supporta parametri aggiuntivi:

Parametro	Tipo	Default	Descrizione
`priority`	integer	`1`	Priorità di calcolo: `0` (bassa) o `1` (alta, elaborata per prima). Usate `0` per i job in background.

Header della request

Header	Obbligatorio	Descrizione
`Content-Type`	Sì	Deve essere `application/json`
`Authorization`	Sì	Basic Auth con chiave API

Proprietà della ricetta

Ingredienti

I campi di ogni riga di ingredients sono descritti in una pagina dedicata: Ingredienti.

Schema della request

PUT /kitchens/kitchen-restaurant-a/recipes/recipe-001
{
  "recipe": {
    "kitchen-id": "kitchen-restaurant-a",
    "id": "recipe-001",
    "titles": [{"language": "en", "value": "Grilled Salmon with Vegetables"}, {"language": "de", "value": "Gegrillter Lachs mit Gemüse"}],
    "recipe-portions": 4,
    "date": "2024-12-16",
    "weight": 350,
    "ingredients": [
      {
        "id": "salmon-filet",
        "names": [{"language": "en", "value": "Salmon (farmed, fillet)"}],
        "amount": 600,
        "unit": "gram",
        "origin": "Norway",
        "transport": "air",
        "production": "standard",
        "conservation": "fresh",
        "packaging": "plastic"
      }
    ]
  }
}

Response:

{
  "statuscode": 200,
  "message": "",
  "request-id": 0,
  "recipe-id": "recipe-001",
  "recipe": {
    "food-unit": 1.06,
    "final-weight-per-portion": 350.0,
    "eaternity-award": false,
    "co2-value": 743,
    "rating": "B",
    "co2-value-improvement-percentage": 10,
    "co2-value-reduction-value": 81,
    "id": "recipe-001",
    "kitchen-id": "kitchen-restaurant-a",
    "titles": [{"language": "en", "value": "Grilled Salmon with Vegetables"}, {"language": "de", "value": "Gegrillter Lachs mit Gemüse"}],
    "date": "2024-12-16",
    "weight": 350.0,
    "servings": 4,
    "recipe-portions": 4,
    "ingredients": []
  }
}

Definizioni delle proprietà

Proprietà della request

Proprietà	Tipo	Obbligatorio	Descrizione
`kitchen-id`	String	Sì	L'ID della cucina a cui appartiene la ricetta
`id`	String	Sì	Identificatore univoco della ricetta. Per le regole vedere Unicità dell'ID della ricetta.
`titles`	Array	Sì	Titoli della ricetta come array di oggetti lingua: `[{"language": "en", "value": "..."}]`
`recipe-portions`	Float	No	Numero di porzioni per cui sono indicati gli ingredienti. Default: `1`.
`date`	ISO Date	Best practice	La data in cui la ricetta viene servita (formato: `yyyy-mm-dd`).
`ingredients`	Array	Sì	Lista di oggetti ingrediente (min. 1). Vedere Ingredienti.
`weight`	Integer	No	Peso finale della ricetta per porzione in grammi. Serve a tenere conto dell'evaporazione e delle perdite di cottura. Se assente, vale la somma dei pesi degli ingredienti. Per modellare la perdita di singoli ingredienti, preferite il campo per ingrediente `loss-in-percent-of-amount`.
`author`	String	No	Autore originale della ricetta
`location`	String	No	Luogo in cui la ricetta viene cucinata. Indirizzo o paese (formato libero). In assenza si usa la posizione della cucina.
`production-portions`	Float	No	Quante porzioni della ricetta si prevede di produrre
`sold-portions`	Float	No	Quante porzioni sono state effettivamente vendute (consumate). Usato dall'endpoint forecast per prevedere le vendite.
`instructions`	Array	No	Istruzioni di cottura come array di oggetti lingua: `[{"language": "en", "value": "..."}]`
`menu-line-name`	String	No	Descrizione della linea di menu (ad es. "Fitness", "Garden Menu", "Vegan Menu")
`menu-line-id`	Integer	No	Identificatore numerico della linea di menu
`transient`	Boolean	No	Campo dell'elemento del batch, accanto a `request-id`. `true` rende la ricetta transitoria: calcolata e restituita, non salvata, non conteggiata da sola.

Comportamento del campo date

Una ricetta senza date viene calcolata, ma manca nei report basati sulla data. Indicate sempre la data in cui la ricetta viene servita.

Proprietà della response

Proprietà	Tipo	Descrizione
`co2-value`	Integer	Emissioni totali di CO2 dell'intera ricetta per porzione servita (grammi CO2-eq)
`co2-value-improvement-percentage`	Float	Confronto tra l'impronta di CO2 di questa ricetta per food unit e la media
`co2-value-reduction-value`	Float	Grammi di CO2 risparmiati servendo questa ricetta invece di una ricetta media con lo stesso valore nutrizionale
`rating`	String	Valutazione ambientale (scala A-E, A è la migliore)
`eaternity-award`	Boolean	`true` se la ricetta è rispettosa del clima
`info-text`	String	Note sul valore di CO2 calcolato, ad es. osservazioni quando proprietà come origine o trasporto sono stimate
`final-weight-per-portion`	Float	Peso finale per porzione dopo la cottura (grammi)
`indicators.vita-score`	Object	Valutazione della qualità nutrizionale (A-E) e relativi fattori di rischio (solo con `indicators=true`). Vedere Vita Score.
`indicators`	Object	Indicatori ambientali e nutrizionali (solo con il parametro `indicators=true`)
`nutrient-values-estimated-per-recipe-portion`	Object	Valori nutrizionali aggregati per porzione, calcolati sommando i nutrienti di tutti gli ingredienti e dividendo per recipe-portions (con il parametro `nutrient-values=true`)

Ricette transitorie

Cosa significa transient

Una ricetta transitoria viene calcolata e il suo risultato torna nella response. Dopodiché non viene salvata:

Non conta mai da sola nei report, nemmeno con una date. I suoi ingredienti contano solo attraverso il menu che la usa.
Non può essere recuperata in seguito. Un GET risponde 404 e la ricetta non compare nella lista delle ricette della cucina.
Un menu può usarla come sotto-ricetta.

Dove impostarlo

Dove	Si applica a
Campo del body `"transient": true` su un elemento del batch, accanto a `request-id`	Solo quella ricetta
Parametro di query `?transient=true`	Tutte le ricette della request, menu compresi

Mettete il campo del body sull'elemento del batch, non dentro recipe. Dentro recipe viene ignorato e la ricetta viene salvata come una ricetta normale.

?transient=true su un batch di menu rende transitori anche i menu, che quindi spariscono dai report. Per le sotto-ricette usate il campo del body.

Quando usarlo

Sotto-ricette come una salsa, un contorno o una base: transitorie.
Anteprime e test: ?transient=true.
Menu che devono contare nei report: non transitori.

Operazioni batch

Elaborate più ricette in una sola request per prestazioni ottimali.

Request

POST /recipes/batch
Content-Type: application/json
Authorization: Basic {api_key}

Tracciamento tramite request ID

Ogni ricetta di un batch può includere un campo intero request-id che vi aiuta a ritrovare le ricette nella response. È utile soprattutto quando non usate ID di ricetta propri.

Per ogni voce è obbligatorio un request-id oppure un id di ricetta
Il request-id è diverso dall'id della ricetta e vale solo per la durata di una singola request (non viene salvato sul server)

Esempio di composizione con sotto-ricette

Nella request seguente, il piatto del menu "Fitness Risotto" contiene una sola ricetta, "Mushroom gravy on pumpkin risotto". Questa ricetta è a sua volta composta da due sotto-ricette: "pumpkin risotto" e "Mushroom gravy". Tutte le ricette sono incluse nel batch.

Il piatto del menu non è transitorio ("transient": false), quindi conta nei report. Le sotto-ricette sono transitorie ("transient": true): vengono calcolate con il menu e contano solo attraverso di esso. Il flag si trova su ogni elemento del batch, accanto a request-id.

POST /recipes/batch
[
  {
    "request-id": 0,
    "transient": true,
    "recipe": {
      "id": "internal-recipe-id3",
      "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"}],
          "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": "104",
          "type": "conceptual-ingredients",
          "names": [{"language": "en", "value": "onions"}],
          "amount": 78,
          "unit": "gram"
        }
      ]
    }
  },
  {
    "request-id": 3,
    "transient": false,
    "recipe": {
      "id": "menu-id1-fitness-2016-11-28",
      "kitchen-id": "kitchen-restaurant-a",
      "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"
        }
      ]
    }
  }
]

Response, una voce per ricetta nell'ordine della request:

[
  {
    "statuscode": 200,
    "message": "",
    "recipe-id": "internal-recipe-id3",
    "request-id": 0,
    "recipe": {
      "food-unit": 1.36,
      "final-weight-per-portion": 300.0,
      "eaternity-award": false,
      "co2-value": 2030,
      "rating": "C",
      "co2-value-improvement-percentage": -91,
      "co2-value-reduction-value": -969,
      "id": "internal-recipe-id3",
      "kitchen-id": "kitchen-restaurant-a",
      "titles": [{"language": "en", "value": "Mushroom gravy on pumpkin risotto"}],
      "servings": 1,
      "recipe-portions": 1,
      "ingredients": []
    }
  },
  {
    "statuscode": 200,
    "message": "",
    "recipe-id": "internal-recipe-id1",
    "request-id": 1,
    "recipe": {
      "food-unit": 0.26,
      "final-weight-per-portion": 50.0,
      "eaternity-award": false,
      "co2-value": 404,
      "rating": "C",
      "co2-value-improvement-percentage": -98,
      "co2-value-reduction-value": -200,
      "id": "internal-recipe-id1",
      "kitchen-id": "kitchen-restaurant-a",
      "titles": [{"language": "en", "value": "pumpkin risotto"}],
      "servings": 100,
      "recipe-portions": 100,
      "ingredients": []
    }
  },
  {
    "statuscode": 200,
    "message": "",
    "recipe-id": "internal-recipe-id2",
    "request-id": 2,
    "recipe": {
      "food-unit": 0.02,
      "final-weight-per-portion": 15.600000000000001,
      "eaternity-award": true,
      "co2-value": 3,
      "rating": "A",
      "co2-value-improvement-percentage": 74,
      "co2-value-reduction-value": 9,
      "id": "internal-recipe-id2",
      "kitchen-id": "kitchen-restaurant-a",
      "titles": [{"language": "en", "value": "Mushroom gravy"}],
      "servings": 5,
      "recipe-portions": 5,
      "ingredients": []
    }
  },
  {
    "statuscode": 200,
    "message": "",
    "recipe-id": "menu-id1-fitness-2016-11-28",
    "request-id": 3,
    "recipe": {
      "food-unit": 1.31,
      "final-weight-per-portion": 288.0,
      "eaternity-award": false,
      "co2-value": 1949,
      "rating": "C",
      "co2-value-improvement-percentage": -91,
      "co2-value-reduction-value": -931,
      "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": [],
      "menu-line-name": "Fitness",
      "menu-line-id": 1
    }
  }
]

Eaternity Award

L'Eaternity Award è un'etichetta per i pasti rispettosi del clima. Una ricetta riceve l'Eaternity Award quando ottiene una valutazione CO2 "A".

Il campo eaternity-award è un booleano restituito insieme alla valutazione CO2:

true — il pasto è rispettoso del clima (equivale a una valutazione CO2 "A")
false — il pasto non soddisfa i requisiti

Sistema di valutazione

Le ricette ricevono una valutazione ambientale da A (migliore) a E (peggiore). Soglie: Scala di valutazione.

Ingredienti

Ogni riga della ricetta è un oggetto ingrediente. Campi, valori ammessi, tipi e matching: Ingredienti.

Ricette

Panoramica

Unicità dell'ID della ricetta

Sotto-ricette

Parametri di query

Esempi

Parametri specifici del batch

Header della request

Proprietà della ricetta

Schema della request

Definizioni delle proprietà

Proprietà della request

Proprietà della response

Ricette transitorie

Dove impostarlo

Quando usarlo

Operazioni batch

Request

Tracciamento tramite request ID

Esempio di composizione con sotto-ricette

Eaternity Award

Sistema di valutazione

Ingredienti

Endpoint

📄️ Create or update a batch of recipes

📄️ Delete a batch of recipes

📄️ Create a recipe

📄️ Get a recipe

📄️ Update or create a recipe

📄️ Delete a recipe

📄️ Create a recipe in a kitchen

📄️ Get all recipes in a kitchen

📄️ Get a recipe from a kitchen

📄️ Create or update a recipe in a kitchen

📄️ Delete a recipe from a kitchen

Panoramica​

Unicità dell'ID della ricetta​

Sotto-ricette​

Parametri di query​

Esempi​

Parametri specifici del batch​

Header della request​

Proprietà della ricetta​

Schema della request​

Definizioni delle proprietà​

Proprietà della request​

Proprietà della response​

Ricette transitorie​

Dove impostarlo​

Quando usarlo​

Operazioni batch​

Request​

Tracciamento tramite request ID​

Esempio di composizione con sotto-ricette​

Eaternity Award​

Sistema di valutazione​

Ingredienti​

Endpoint​

📄️ Create or update a batch of recipes

📄️ Delete a batch of recipes

📄️ Create a recipe

📄️ Get a recipe

📄️ Update or create a recipe

📄️ Delete a recipe

📄️ Create a recipe in a kitchen

📄️ Get all recipes in a kitchen

📄️ Get a recipe from a kitchen

📄️ Create or update a recipe in a kitchen

📄️ Delete a recipe from a kitchen

Panoramica

Unicità dell'ID della ricetta

Sotto-ricette

Parametri di query

Esempi

Parametri specifici del batch

Header della request

Proprietà della ricetta

Schema della request

Definizioni delle proprietà

Proprietà della request

Proprietà della response

Ricette transitorie

Dove impostarlo

Quando usarlo

Operazioni batch

Request

Tracciamento tramite request ID

Esempio di composizione con sotto-ricette

Eaternity Award

Sistema di valutazione

Ingredienti

Endpoint