{ "openapi": "3.1.1", "info": { "title": "Outdoor Job Weather Window API", "version": "1.0.0", "summary": "Find the best hours this week to paint, mow, barbecue or walk, by clear weather rules.", "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://hearthweatherwindow.usefulweb.app" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Find the best hours this week to paint, mow, barbecue or walk, by clear weather rules.", "description": "Checks the MET Norway forecast hour by hour against the rules of an outdoor job — temperature, humidity, wind, rain and dew point — and lists every window long enough to do it, including rain-free time afterwards for paint to cure or before mowing for the grass to dry.\n\nMethodology:\n- Fetches the MET Norway Locationforecast 2.0 for the place (rounded to 0.01°, cached until MET’s Expires time) and builds an hourly series; 6-hour steps after the first days are split into hours with interpolated values.\n- Each hour inside the activity’s day hours is checked: no rain (≥ 0.1 mm per hour, ≥ 0.2 mm per 6-hour step or a rain chance ≥ 40 % count as rain), temperature, relative humidity and wind within the limits and, for painting, the air at least 3 K above the dew point (ISO 8502-4 asks this of the surface; air temperature stands in for it).\n- Presets: painting 10–30 °C, ≤ 85 % humidity, ≤ 7 m/s, 4 hours plus 4 rain-free hours afterwards, 8:00–18:00; mowing 5–30 °C, ≤ 90 %, 2 hours with 3 dry hours before, 9:00–20:00; barbecue 14–32 °C, ≤ 8 m/s, 3 hours, 11:00–22:00; walk −5 to 28 °C, ≤ 10 m/s, 2 hours, 7:00–21:00. Your numbers replace the preset values.\n- Runs of suitable hours are trimmed until the rain-free buffers hold and kept when they are at least the hours needed. The best window is the longest (earliest on a tie); the blocker count shows which rule failed most often.\n\nA forecast window is a plan, not a promise: check the latest forecast and the paint maker’s instructions before you start.", "tags": [ "apps" ], "x-mcp-tool": "hearth_weather_window", "x-owner-app": "hearth", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HearthWeatherWindowInput" }, "examples": { "example1": { "summary": "Paint the fence in Berlin", "value": { "place": "52.52, 13.40", "timeZone": "Europe/Berlin", "activity": "painting", "days": 7 } }, "example2": { "summary": "Mow the lawn in Amsterdam, two hours", "value": { "place": "52.37, 4.90", "timeZone": "Europe/Amsterdam", "activity": "mowing", "days": 5, "minHours": 2 } }, "example3": { "summary": "Barbecue in Madrid, at least 18 °C", "value": { "place": "40.42, -3.70", "timeZone": "Europe/Madrid", "activity": "bbq", "days": 7, "minTemp": 18 } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HearthWeatherWindowResult" } } } }, "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" } } } } } }, "HearthWeatherWindowInput": { "type": "object", "additionalProperties": false, "properties": { "place": { "title": "Place (latitude, longitude)", "description": "Decimal degrees such as “52.52, 13.40”, or degrees-minutes-seconds. Rounded to 0.01° (about 1 km) before the request.", "type": "string", "maxLength": 80, "default": "52.52, 13.40" }, "timeZone": { "title": "Time zone of the place", "description": "IANA name such as Europe/Berlin, Europe/London or America/New_York. Hours and dates are shown in this zone.", "type": "string", "maxLength": 40, "default": "Europe/Berlin" }, "activity": { "title": "Activity", "type": "string", "enum": [ "painting", "mowing", "bbq", "walk" ], "default": "painting" }, "days": { "title": "Days ahead", "description": "MET Norway forecasts about nine days ahead: hourly for the first two to three days, then in 6-hour steps.", "type": "integer", "minimum": 1, "maximum": 9, "default": 7 }, "minTemp": { "title": "Lowest temperature (°C, optional)", "description": "Empty = the activity’s rule (painting 10, mowing 5, barbecue 14, walk −5).", "type": "number", "minimum": -30, "maximum": 45, "x-unit": "°C" }, "maxTemp": { "title": "Highest temperature (°C, optional)", "type": "number", "minimum": -20, "maximum": 50, "x-unit": "°C" }, "maxHumidity": { "title": "Highest relative humidity (%, optional)", "type": "number", "minimum": 20, "maximum": 100, "x-unit": "%" }, "maxWind": { "title": "Strongest wind (m/s, optional)", "type": "number", "minimum": 1, "maximum": 40, "x-unit": "m/s" }, "minHours": { "title": "Hours needed (optional)", "type": "integer", "minimum": 1, "maximum": 14 } }, "required": [ "place" ] }, "HearthWeatherWindowResult": { "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", "activity", "rule", "windows", "best", "days", "blockers", "forecastUpdated", "attribution" ], "properties": { "place": { "type": "object", "additionalProperties": false, "required": [ "lat", "lon" ], "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } } }, "timeZone": { "type": "string" }, "activity": { "type": "string" }, "rule": { "type": "object", "additionalProperties": false, "required": [ "id", "minTemp", "maxTemp", "maxHumidity", "maxWind", "minHours", "fromHour", "toHour", "dryAfter", "dryBefore", "dewSpread" ], "properties": { "minTemp": { "type": "number" }, "maxTemp": { "type": "number" }, "maxHumidity": { "type": "number" }, "maxWind": { "type": "number" }, "minHours": { "type": "number" }, "fromHour": { "type": "number" }, "toHour": { "type": "number" }, "dryAfter": { "type": "number" }, "dryBefore": { "type": "number" }, "dewSpread": { "type": "number" }, "id": { "type": "string" } } }, "windows": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "date", "start", "end", "hours", "tempMin", "tempMax", "windMax", "humidityMax", "coarse" ], "properties": { "date": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "hours": { "type": "integer" }, "tempMin": { "type": "number" }, "tempMax": { "type": "number" }, "windMax": { "type": "number" }, "humidityMax": { "type": "number" }, "coarse": { "type": "boolean" } } } }, "best": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "date", "start", "end", "hours", "tempMin", "tempMax", "windMax", "humidityMax", "coarse" ], "properties": { "date": { "type": "string" }, "start": { "type": "string" }, "end": { "type": "string" }, "hours": { "type": "integer" }, "tempMin": { "type": "number" }, "tempMax": { "type": "number" }, "windMax": { "type": "number" }, "humidityMax": { "type": "number" }, "coarse": { "type": "boolean" } } }, "days": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "date", "suitableHours", "bestWindowHours", "mainBlocker" ], "properties": { "date": { "type": "string" }, "suitableHours": { "type": "integer" }, "bestWindowHours": { "type": "integer" }, "mainBlocker": { "type": [ "string", "null" ] } } } }, "blockers": { "type": "object", "additionalProperties": { "type": "integer" } }, "forecastUpdated": { "type": "string" }, "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" } } } } } } } }