{ "openapi": "3.1.1", "info": { "title": "Garden Watering Need API", "version": "1.0.0", "summary": "Litres of water per bed for the coming week from the MET Norway forecast and FAO-56 crop water use.", "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://hearthwateringneed.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Litres of water per bed for the coming week from the MET Norway forecast and FAO-56 crop water use.", "description": "Estimates how much to water each garden bed over the next days: FAO-56 Penman–Monteith reference evapotranspiration from the MET Norway forecast, times the crop coefficient of each planting and its growth stage, minus the rain that reaches the roots — in millimetres and litres, with a suggested number of waterings.\n\nMethodology:\n- Fetches the MET Norway Locationforecast 2.0 for the place (rounded to 0.01°, cached until MET’s Expires time) and groups the hours into local days; only complete days count (at least 20 forecast hours).\n- Per day: maximum and minimum temperature and humidity, mean wind (10 m wind reduced to 2 m, FAO-56 eq. 47) and mean cloud cover. Solar radiation is estimated from the clear-sky radiation and the cloud fraction C with Kasten \u0026 Czeplak (1980): Rs = Rso (1 − 0.75 C^3.4).\n- Reference evapotranspiration ET0 is the FAO-56 Penman–Monteith equation (eq. 6) with net radiation from eq. 38–40 and the height MET reports for the point; a test reproduces FAO-56 example 18 (Brussels, 6 July: 3.9 mm/day).\n- Crop water use ETc = Kc × ET0 with FAO-56 Table 12 coefficients; with a planting date the Kc follows the FAO single-coefficient curve over a season of 1.25 × the days to harvest (20 / 30 / 35 / 15 % initial, development, mid-season, late), otherwise the mid-season value of an established crop. Plantings sown after a day do not count that day.\n- Rain under 2 mm a day is lost to leaves and evaporation; 80 % of larger amounts reach the roots. Need = ETc − effective rain over the period (not below zero); litres = millimetres × square metres. One watering per about 12 mm of need (soaking, not sprinkling).\n\nAn estimate for open beds: sandy soil, wind, containers and greenhouses need more water; mulch and heavy soil less. Check the soil a finger deep before watering.", "tags": [ "apps" ], "x-mcp-tool": "hearth_watering_need", "x-owner-app": "hearth", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HearthWateringNeedInput" }, "examples": { "example1": { "summary": "Berlin: tomatoes, beans and lettuce", "value": { "place": "52.52, 13.40", "timeZone": "Europe/Berlin", "days": 7, "plantings": [ { "bed": "Bed 1", "crop": "tomato", "areaM2": 0.36 }, { "bed": "Bed 1", "crop": "bush-bean", "areaM2": 0.54 }, { "bed": "Bed 2", "crop": "lettuce", "areaM2": 1.2 } ] } }, "example2": { "summary": "Madrid: courgettes and peppers on an allotment", "value": { "place": "40.42, -3.70", "timeZone": "Europe/Madrid", "days": 5, "plantings": [ { "bed": "Plot", "crop": "zucchini", "areaM2": 2.5 }, { "bed": "Plot", "crop": "pepper", "areaM2": 1.5 } ] } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HearthWateringNeedResult" } } } }, "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" } } } } } }, "HearthWateringNeedInput": { "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": 7 }, "plantings": { "title": "Plantings", "type": "array", "minItems": 1, "maxItems": 120, "items": { "type": "object", "additionalProperties": false, "properties": { "bed": { "title": "Bed", "type": "string", "maxLength": 40 }, "crop": { "title": "Crop", "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" ], "default": "tomato" }, "areaM2": { "title": "Area (m²)", "type": "number", "minimum": 0.01, "maximum": 500, "default": 1 }, "planted": { "title": "Planted or sown on (optional)", "type": "string", "format": "date" } }, "required": [ "bed" ] }, "default": [ { "bed": "Bed 1", "crop": "tomato", "areaM2": 0.36 }, { "bed": "Bed 1", "crop": "bush-bean", "areaM2": 0.54 }, { "bed": "Bed 2", "crop": "lettuce", "areaM2": 1.2 } ] } }, "required": [ "place" ] }, "HearthWateringNeedResult": { "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", "altitude", "forecastUpdated", "days", "plantings", "beds", "totalLitres", "et0Total", "rainTotal", "attribution" ], "properties": { "place": { "type": "object", "additionalProperties": false, "required": [ "lat", "lon" ], "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } } }, "timeZone": { "type": "string" }, "altitude": { "type": "number" }, "forecastUpdated": { "type": "string" }, "days": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "date", "et0", "rain", "effectiveRain", "tmax", "tmin", "cloud", "wind" ], "properties": { "et0": { "type": "number" }, "rain": { "type": "number" }, "effectiveRain": { "type": "number" }, "tmax": { "type": "number" }, "tmin": { "type": "number" }, "cloud": { "type": "number" }, "wind": { "type": "number" }, "date": { "type": "string" } } } }, "plantings": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "bed", "crop", "areaM2", "planted", "stage", "etcMm", "rainMm", "needMm", "litres" ], "properties": { "bed": { "type": "string" }, "crop": { "type": "string" }, "areaM2": { "type": "number" }, "planted": { "type": [ "string", "null" ] }, "stage": { "type": "string" }, "etcMm": { "type": "number" }, "rainMm": { "type": "number" }, "needMm": { "type": "number" }, "litres": { "type": "number" } } } }, "beds": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "bed", "areaM2", "litres", "needMm", "waterings", "litresPerWatering" ], "properties": { "bed": { "type": "string" }, "areaM2": { "type": "number" }, "litres": { "type": "number" }, "needMm": { "type": "number" }, "waterings": { "type": "integer" }, "litresPerWatering": { "type": "number" } } } }, "totalLitres": { "type": "number" }, "et0Total": { "type": "number" }, "rainTotal": { "type": "number" }, "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" } } } } } } } }