Forecast

The Forecast API predicts sold menu portions based on planned recipes and historical sales data for a kitchen, enabling better production planning and reduced food waste.

Overview

Use the Forecast API to:

• Predict how many portions of each recipe will be sold on upcoming days
• Get confidence intervals (low/high bounds) for predictions
• Plan production quantities to reduce overproduction and food waste
• Update actual sold and production portions for improved future predictions

Data Requirements

The forecast requires at least 10 consecutive days of menus with full recipes and sales data. More data improves prediction accuracy. You will receive a warning if there is too little data for a prediction.

Creating a Forecast

Send a POST request to /prognosis/{kitchen_id}/forecast with the desired date range.

Request Properties

Property	Type	Required	Description
date-start	String	Yes	Start date for the forecast period. Format: YYYY-MM-DD
date-end	String	Yes	End date for the forecast period. Format: YYYY-MM-DD
async	Boolean	No	If true, returns immediately with a prediction_id without waiting for the calculation to finish. Default: false

Request Example

curl -X POST "https://co2.eaternity.ch/api/prognosis/YOURKITCHENID/forecast" \
  -u YOUR_API_KEY: \
  -H "Content-Type: application/json" \
  -d '{
    "date-start": "2021-02-08",
    "date-end": "2021-02-09",
    "async": false
  }'

Response Properties

Property	Type	Description
kitchen_id	String	The kitchen for which the forecast was calculated
prediction_id	String	Unique identifier for this forecast (generated by Eaternity)
status	String	Calculation status: processing, done, or error
error	String	Error message if the forecast calculation was not possible
info	Array	Warnings and errors (e.g., unmatched ingredients). Each entry may contain error, warning, and product_id fields.
predicted_sales	Object	The resulting sales forecast (see below)

Predicted Sales Structure

Property	Type	Description
date-start	String	Start date of the forecast period
date-end	String	End date of the forecast period
results	Array	List of forecast results grouped by day

Each day in results contains:

Property	Type	Description
date	String	The date for this result set (YYYY-MM-DD)
total-sales	Object	Prediction of total sales for the kitchen on this date
recipes	Array	Per-recipe predictions for this date

total-sales fields:

Property	Type	Description
portions	Number	Predicted number of total portions sold
low	Number	Lower bound of the 90% confidence interval
high	Number	Upper bound of the 90% confidence interval

Each recipe in recipes:

Property	Type	Description
recipe-id	String	The ID of the recipe
portions	Number	Predicted number of portions to be sold
low	Number	Lower bound of the 90% confidence interval
high	Number	Upper bound of the 90% confidence interval

Response Example

{
  "kitchen_id": "11122233",
  "prediction_id": "3f8e11ca-5234-47da-8602-c255a290e5f2",
  "status": "done",
  "info": [],
  "predicted_sales": {
    "date-start": "2021-02-08",
    "date-end": "2021-02-09",
    "results": [
      {
        "date": "2021-02-08",
        "total-sales": {
          "portions": 1203,
          "low": 1123,
          "high": 1265
        },
        "recipes": [
          {
            "recipe-id": "11111",
            "portions": 489,
            "low": 416,
            "high": 526
          }
        ]
      }
    ]
  }
}

Retrieving a Forecast

If you created a forecast with async: true, retrieve results via GET /prognosis/{kitchen_id}/forecast/{prediction_id}.

The response has the same structure as the creation response. Check the status field:

• processing — calculation is still running
• done — results are available in predicted_sales
• error — check the error field for details

Updating Sold and Production Portions

After actual sales data is available, update recipes with real numbers via POST /prognosis/{kitchen_id}/portions. This improves future predictions.

Request

{
  "recipes": [
    {
      "recipe-id": "11111",
      "sold-portions": 444,
      "production-portions": 500
    },
    {
      "recipe-id": "22222",
      "sold-portions": 555,
      "production-portions": 600
    }
  ]
}

Response

Each recipe returns a status indicating whether the update was applied:

{
  "recipes": [
    {
      "recipe-id": "11111",
      "status": "UPDATED"
    },
    {
      "recipe-id": "22222",
      "status": "NOT_FOUND"
    }
  ]
}

Endpoints

📄️ Create a forecast

Create a new forecast calculation for the kitchen.

📄️ Get a forecast

Retrieve the status and results of a previously created forecast calculation.

📄️ Update recipe portions

Update the production-portions and sold-portions of multiple recipes.