{
  "openapi": "3.1.1",
  "info": {
    "title": "Garden Forecast Planner API",
    "version": "1.0.0",
    "summary": "Nine-day garden forecast: frost risk, soil warmth, when to sow, what to water, what to move.",
    "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp."
  },
  "servers": [
    {
      "url": "https://greenplotforecastplanner.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Nine-day garden forecast: frost risk, soil warmth, when to sow, what to water, what to move.",
        "description": "Reads the MET Norway forecast for your garden and plans the next nine days: frost and cold-night risk, an estimated soil temperature, evapotranspiration, whether planned sowings and plantings should go ahead or wait (and until when), a watering plan per bed from rain and water use, hints for logs and mushroom beds, and in Norway, Sweden, Finland and Denmark the radar rain for the next two hours.\n\nMethodology:\n- Fetches the MET Norway Locationforecast 2.0 for the place (rounded to 0.01°) through Hearth’s cached client — an identifying User-Agent, the answer kept until MET’s Expires time and revalidated with If-Modified-Since — and groups the hours into local days (today from now on).\n- Frost risk per night: frost at a minimum of 0 °C or lower; ground frost likely at 3 °C or lower on a clear (cloud ≤ 50 %) or calm (≤ 2 m/s) night; a cold night for tender plants at 5 °C or lower.\n- Soil temperature at about 10 cm is estimated, not measured: the daily mean air temperature smoothed with a 3-day time constant, plus up to 1.5 °C on clear days for sun on bare soil, with 40 % of the air’s daily swing. Mulch, shade and wet clay keep soil cooler; raised beds and black fleece warm it.\n- Evapotranspiration by Hargreaves (FAO-56 eq. 52) from the day’s minimum and maximum and the latitude; crop water use = FAO-56 crop coefficient of each planting (by its growth stage) × that value.\n- Sowing and planting: each planned date from the last 14 days to the end of the forecast is checked day by day — no frost (tender plants: no ground frost or cold nights either) in the next 4–5 days, soil at least as warm as the plant’s minimum for germination (Alabama Extension table of soil temperatures for seed germination), no downpour of 10 mm or more — and gets “go”, “wait until …” or “not yet”.\n- Watering: a soil-water balance per bed starting half-full; a soaking is planned when the deficit reaches 8 mm (thirsty plants), 12 mm (medium) or 18 mm (drought-tolerant), unless the next day’s rain covers it; beds under glass get no rain.\n- Nowcast: in Norway, Sweden, Finland and Denmark the MET Nowcast 2.0 radar forecast (5-minute steps, next two hours) is added when the radar covers the place; elsewhere MET Norway offers no nowcast.\n\nForecasts change and soil temperatures are estimates; frost in hollows and on clear, still nights can come earlier than forecast for the area.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "greenplot_forecast_planner",
        "x-owner-app": "greenplot",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/GreenplotForecastPlannerInput"
              },
              "examples": {
                "example1": {
                  "summary": "Berlin: beans and tomatoes still to plant, lettuce in the ground",
                  "value": {
                    "place": "52.47, 13.40",
                    "timeZone": "Europe/Berlin",
                    "days": 9,
                    "lastFrost": "04-20",
                    "firstFrost": "10-20",
                    "plantings": [
                      {
                        "bed": "Raised bed 1",
                        "kind": "garden",
                        "plant": "tomato",
                        "variety": "tomato-cherry",
                        "areaM2": 0.72,
                        "start": "2026-11-10"
                      },
                      {
                        "bed": "Raised bed 2",
                        "kind": "garden",
                        "plant": "bush-bean",
                        "areaM2": 1,
                        "start": "2026-11-09"
                      },
                      {
                        "bed": "Raised bed 2",
                        "kind": "garden",
                        "plant": "lettuce",
                        "variety": "lettuce-looseleaf",
                        "areaM2": 0.5
                      },
                      {
                        "bed": "Shade",
                        "kind": "log-stack",
                        "plant": "shiitake",
                        "areaM2": 1,
                        "start": "2025-04-01"
                      }
                    ]
                  }
                },
                "example2": {
                  "summary": "Oslo allotment with garlic, kale and a wine cap bed",
                  "value": {
                    "place": "59.91, 10.75",
                    "timeZone": "Europe/Oslo",
                    "days": 7,
                    "lastFrost": "05-10",
                    "firstFrost": "10-01",
                    "plantings": [
                      {
                        "bed": "Plot",
                        "kind": "garden",
                        "plant": "garlic",
                        "areaM2": 3,
                        "start": "2026-10-20"
                      },
                      {
                        "bed": "Plot",
                        "kind": "garden",
                        "plant": "kale",
                        "areaM2": 2
                      },
                      {
                        "bed": "Chips",
                        "kind": "mushroom-bed",
                        "plant": "wine-cap",
                        "areaM2": 2,
                        "start": "2026-05-01"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/GreenplotForecastPlannerResult"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid input (see errors[]).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tool": {
      "get": {
        "operationId": "getToolDefinition",
        "summary": "Inputs, output schema and examples for this tool",
        "responses": {
          "200": {
            "description": "Tool definition.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details. 422 responses include per-field `errors`.",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "field",
                "message"
              ],
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "GreenplotForecastPlannerInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "place": {
            "title": "Place (latitude, longitude)",
            "description": "Decimal degrees such as “52.47, 13.40”. Rounded to 0.01° (about 1 km).",
            "type": "string",
            "maxLength": 80,
            "default": "52.47, 13.40"
          },
          "timeZone": {
            "title": "Time zone of the place",
            "type": "string",
            "maxLength": 40,
            "default": "Europe/Berlin"
          },
          "days": {
            "title": "Days ahead",
            "type": "integer",
            "minimum": 1,
            "maximum": 9,
            "default": 9
          },
          "lastFrost": {
            "title": "Last spring frost (MM-DD)",
            "description": "Month and day, for example 04-20. Hearth’s Frost Dates Finder gives it for Germany and the United States.",
            "type": "string",
            "maxLength": 5,
            "default": "04-20"
          },
          "firstFrost": {
            "title": "First autumn frost (MM-DD)",
            "type": "string",
            "maxLength": 5,
            "default": "10-20"
          },
          "plantings": {
            "title": "Plantings",
            "type": "array",
            "minItems": 1,
            "maxItems": 120,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "properties": {
                "bed": {
                  "title": "Bed",
                  "type": "string",
                  "maxLength": 40
                },
                "kind": {
                  "title": "Kind of bed",
                  "type": "string",
                  "enum": [
                    "garden",
                    "mushroom-bed",
                    "log-stack",
                    "indoor-box"
                  ],
                  "default": "garden"
                },
                "plant": {
                  "title": "Plant",
                  "type": "string",
                  "enum": [
                    "tomato",
                    "pepper",
                    "eggplant",
                    "potato",
                    "cucumber",
                    "zucchini",
                    "squash",
                    "melon",
                    "sweetcorn",
                    "bush-bean",
                    "pole-bean",
                    "pea",
                    "broad-bean",
                    "lettuce",
                    "spinach",
                    "chard",
                    "beet",
                    "carrot",
                    "parsnip",
                    "radish",
                    "turnip",
                    "onion",
                    "spring-onion",
                    "garlic",
                    "leek",
                    "cabbage",
                    "broccoli",
                    "cauliflower",
                    "kale",
                    "brussels-sprouts",
                    "kohlrabi",
                    "pak-choi",
                    "rocket",
                    "celery",
                    "fennel",
                    "parsley",
                    "basil",
                    "dill",
                    "coriander",
                    "chives",
                    "asparagus",
                    "rhubarb",
                    "artichoke",
                    "jerusalem-artichoke",
                    "sweet-potato",
                    "okra",
                    "celeriac",
                    "swede",
                    "endive",
                    "chicory",
                    "mizuna",
                    "corn-salad",
                    "shallot",
                    "chilli",
                    "mangetout",
                    "chinese-cabbage",
                    "horseradish",
                    "cress",
                    "mustard-greens",
                    "soybean",
                    "tomatillo",
                    "watermelon",
                    "rosemary",
                    "thyme",
                    "sage",
                    "oregano",
                    "mint",
                    "lavender",
                    "tarragon",
                    "lemon-balm",
                    "lovage",
                    "sorrel",
                    "bay",
                    "marjoram",
                    "chamomile",
                    "borage",
                    "chervil",
                    "summer-savory",
                    "strawberry",
                    "raspberry",
                    "autumn-raspberry",
                    "blackberry",
                    "blueberry",
                    "gooseberry",
                    "redcurrant",
                    "blackcurrant",
                    "apple",
                    "pear",
                    "plum",
                    "cherry",
                    "peach",
                    "apricot",
                    "quince",
                    "fig",
                    "grape",
                    "kiwi",
                    "physalis",
                    "sunflower",
                    "french-marigold",
                    "calendula",
                    "nasturtium",
                    "sweet-pea",
                    "cosmos",
                    "zinnia",
                    "cornflower",
                    "poppy",
                    "nigella",
                    "phacelia",
                    "crimson-clover",
                    "dahlia",
                    "tulip",
                    "daffodil",
                    "snapdragon",
                    "alyssum",
                    "larkspur",
                    "gladiolus",
                    "echinacea",
                    "rudbeckia",
                    "lupin",
                    "hollyhock",
                    "verbena",
                    "sweet-william",
                    "salsify",
                    "scorzonera",
                    "sprouting-broccoli",
                    "daikon",
                    "collards",
                    "komatsuna",
                    "tatsoi",
                    "choy-sum",
                    "kai-lan",
                    "cima-di-rapa",
                    "shungiku",
                    "purslane",
                    "winter-purslane",
                    "land-cress",
                    "watercress",
                    "amaranth",
                    "malabar-spinach",
                    "new-zealand-spinach",
                    "orache",
                    "good-king-henry",
                    "sea-kale",
                    "yacon",
                    "chinese-artichoke",
                    "hamburg-parsley",
                    "welsh-onion",
                    "elephant-garlic",
                    "cowpea",
                    "lima-bean",
                    "lentil",
                    "peanut",
                    "quinoa",
                    "cucamelon",
                    "bitter-gourd",
                    "bottle-gourd",
                    "luffa",
                    "dandelion",
                    "cutting-celery",
                    "cardoon",
                    "chayote",
                    "lemongrass",
                    "garlic-chives",
                    "hyssop",
                    "winter-savory",
                    "lemon-verbena",
                    "caraway",
                    "anise",
                    "fenugreek",
                    "salad-burnet",
                    "sweet-cicely",
                    "angelica",
                    "comfrey",
                    "feverfew",
                    "stevia",
                    "perilla",
                    "vietnamese-coriander",
                    "wild-garlic",
                    "roman-chamomile",
                    "mitsuba",
                    "herb-fennel",
                    "saffron",
                    "cumin",
                    "catnip",
                    "sweet-woodruff",
                    "honeyberry",
                    "jostaberry",
                    "hybrid-berry",
                    "cranberry",
                    "lingonberry",
                    "aronia",
                    "elderberry",
                    "sea-buckthorn",
                    "goji",
                    "mulberry",
                    "medlar",
                    "hazelnut",
                    "walnut",
                    "almond",
                    "lemon",
                    "olive",
                    "alpine-strawberry",
                    "wineberry",
                    "kiwiberry",
                    "persimmon",
                    "saskatoon",
                    "cornelian-cherry",
                    "pawpaw",
                    "pomegranate",
                    "crab-apple",
                    "foxglove",
                    "aster",
                    "sedum",
                    "salvia",
                    "catmint",
                    "scabious",
                    "yarrow",
                    "agastache",
                    "monarda",
                    "eryngium",
                    "allium",
                    "crocus",
                    "snowdrop",
                    "muscari",
                    "iris",
                    "peony",
                    "delphinium",
                    "hardy-geranium",
                    "hellebore",
                    "primrose",
                    "viola",
                    "wallflower",
                    "honesty",
                    "forget-me-not",
                    "aquilegia",
                    "campanula",
                    "sweet-rocket",
                    "echium",
                    "phlox",
                    "helenium",
                    "hosta",
                    "lobelia",
                    "petunia",
                    "pelargonium",
                    "cleome",
                    "tithonia",
                    "strawflower",
                    "love-lies-bleeding",
                    "clematis",
                    "honeysuckle",
                    "rose",
                    "buddleja",
                    "verbascum",
                    "heather",
                    "field-bean",
                    "grazing-rye",
                    "winter-tares",
                    "buckwheat",
                    "white-mustard",
                    "fodder-radish",
                    "red-clover",
                    "lucerne",
                    "trefoil",
                    "italian-ryegrass",
                    "field-lupin",
                    "button-mushroom",
                    "oyster-mushroom",
                    "king-oyster",
                    "shiitake",
                    "lions-mane",
                    "wine-cap",
                    "nameko",
                    "enoki",
                    "pioppino",
                    "maitake",
                    "beech-mushroom"
                  ],
                  "default": "tomato"
                },
                "variety": {
                  "title": "Variety type (optional id)",
                  "description": "For example tomato-cherry, tomato-beefsteak, tomato-paste.",
                  "type": "string",
                  "maxLength": 40
                },
                "areaM2": {
                  "title": "Area (m²)",
                  "type": "number",
                  "minimum": 0.01,
                  "maximum": 500,
                  "default": 1
                },
                "start": {
                  "title": "Planted, sown or planned on (optional)",
                  "type": "string",
                  "format": "date"
                }
              },
              "required": [
                "bed"
              ]
            },
            "default": [
              {
                "bed": "Raised bed 1",
                "kind": "garden",
                "plant": "tomato",
                "areaM2": 0.72,
                "start": ""
              },
              {
                "bed": "Raised bed 2",
                "kind": "garden",
                "plant": "bush-bean",
                "areaM2": 1,
                "start": ""
              }
            ]
          }
        },
        "required": [
          "place",
          "lastFrost",
          "firstFrost"
        ]
      },
      "GreenplotForecastPlannerResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schemaVersion",
          "tool",
          "computedAt",
          "inputs",
          "summary",
          "result",
          "units",
          "assumptions",
          "sources",
          "warnings",
          "presentation",
          "links"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1.0"
          },
          "tool": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "version"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "version": {
                "type": "string"
              }
            }
          },
          "computedAt": {
            "type": "string",
            "format": "date-time"
          },
          "inputs": {
            "type": "object",
            "description": "Normalised inputs actually used, including applied defaults."
          },
          "summary": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "place",
              "timeZone",
              "forecastUpdated",
              "lastFrost",
              "firstFrost",
              "today",
              "days",
              "nowcast",
              "suggestions",
              "watering",
              "reschedule",
              "mushrooms",
              "skipWatering",
              "frostDays",
              "beds",
              "model",
              "attribution"
            ],
            "properties": {
              "place": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "lat",
                  "lon"
                ],
                "properties": {
                  "lat": {
                    "type": "number"
                  },
                  "lon": {
                    "type": "number"
                  }
                }
              },
              "timeZone": {
                "type": "string"
              },
              "forecastUpdated": {
                "type": "string"
              },
              "lastFrost": {
                "type": "string"
              },
              "firstFrost": {
                "type": "string"
              },
              "today": {
                "type": "string"
              },
              "days": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "date",
                    "complete",
                    "hours",
                    "tmin",
                    "tmax",
                    "tmean",
                    "rain",
                    "pop",
                    "wind",
                    "windMax",
                    "cloud",
                    "et0",
                    "soil",
                    "soilMin",
                    "soilMax",
                    "frost"
                  ],
                  "properties": {
                    "hours": {
                      "type": "number"
                    },
                    "tmin": {
                      "type": "number"
                    },
                    "tmax": {
                      "type": "number"
                    },
                    "tmean": {
                      "type": "number"
                    },
                    "rain": {
                      "type": "number"
                    },
                    "wind": {
                      "type": "number"
                    },
                    "windMax": {
                      "type": "number"
                    },
                    "cloud": {
                      "type": "number"
                    },
                    "et0": {
                      "type": "number"
                    },
                    "soil": {
                      "type": "number"
                    },
                    "soilMin": {
                      "type": "number"
                    },
                    "soilMax": {
                      "type": "number"
                    },
                    "date": {
                      "type": "string"
                    },
                    "complete": {
                      "type": "boolean"
                    },
                    "pop": {
                      "type": [
                        "number",
                        "null"
                      ]
                    },
                    "frost": {
                      "enum": [
                        "frost",
                        "ground",
                        "cold",
                        "none"
                      ]
                    }
                  }
                }
              },
              "nowcast": {
                "type": [
                  "object",
                  "null"
                ]
              },
              "suggestions": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "reschedule": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "mushrooms": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "beds": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "watering": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "beds",
                  "totalLitres"
                ],
                "properties": {
                  "beds": {
                    "type": "array",
                    "items": {
                      "type": "object"
                    }
                  },
                  "totalLitres": {
                    "type": "number"
                  }
                }
              },
              "skipWatering": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "date",
                    "rain",
                    "rainBefore"
                  ],
                  "properties": {
                    "date": {
                      "type": "string"
                    },
                    "rain": {
                      "type": "number"
                    },
                    "rainBefore": {
                      "type": "number"
                    }
                  }
                }
              },
              "frostDays": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "model": {
                "type": "object"
              },
              "attribution": {
                "type": "string"
              }
            }
          },
          "units": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "retrievedAt": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "presentation": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Display blocks used by the human page (same data)."
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "human",
              "api",
              "openapi",
              "methodology"
            ],
            "properties": {
              "human": {
                "type": "string",
                "format": "uri"
              },
              "api": {
                "type": "string",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "methodology": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}