{ "openapi": "3.1.1", "info": { "title": "Frost Dates Finder API", "version": "1.0.0", "summary": "Last spring and first autumn frost at your place, with the chance of a later or earlier frost.", "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://hearthfrostdates.usefulweb.site" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Last spring and first autumn frost at your place, with the chance of a later or earlier frost.", "description": "Finds the nearest weather station with frost statistics for 1991–2020 — Deutscher Wetterdienst for Germany, NOAA for the United States — and gives the last spring frost and the first autumn frost at three risk levels, a hard frost and the length of the frost-free season.\n\nMethodology:\n- Germany: the nearest of 265 Deutscher Wetterdienst stations (within 40 km) with daily minimum temperatures for at least 25 of the years 1991–2020, from a bundled table built by scripts/data/hearth-dwd-frost.py. Frost = a daily minimum at 2 m of 0 °C or lower; hard frost = −2.2 °C or lower (NOAA’s 32 °F and 28 °F).\n- Per year, the last spring frost is the last such day from January to July and the first autumn frost the first one from August to December; a year counts when March–June (or September–December) miss at most five days. The 10 / 50 / 90 % dates are percentiles over the years (linear interpolation): after the 10 % spring date a frost came in only one year in ten.\n- United States: the nearest NOAA NCEI station with 1991–2020 freeze-date probabilities (annual/seasonal normals ANN-TMIN-PRBLST/PRBFST at 32 °F and 28 °F, same 10 / 50 / 90 % meaning) found with the NCEI search service in a box of ±0.4° (then ±1.2°) around the place; answers are cached for 30 days.\n- Frost-free days per level = days between the last spring and the first autumn frost of that level. The station’s own median frost-free season is shown as well.\n\nFrost dates describe 1991–2020 at a weather station; hollows, slopes and city gardens can differ by weeks. Watch the forecast before planting out tender plants.", "tags": [ "apps" ], "x-mcp-tool": "hearth_frost_dates", "x-owner-app": "hearth", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HearthFrostDatesInput" }, "examples": { "example1": { "summary": "Berlin", "value": { "place": "52.47, 13.40" } }, "example2": { "summary": "Munich", "value": { "place": "48.14, 11.58" } }, "example3": { "summary": "Hamburg", "value": { "place": "53.55, 9.99" } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HearthFrostDatesResult" } } } }, "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" } } } } } }, "HearthFrostDatesInput": { "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" } }, "required": [ "place" ] }, "HearthFrostDatesResult": { "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", "station", "frost", "levels", "attribution" ], "properties": { "place": { "type": "object", "additionalProperties": false, "required": [ "lat", "lon" ], "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } } }, "station": { "type": "object", "additionalProperties": false, "required": [ "source", "id", "name", "lat", "lon", "elevation", "distanceKm", "years" ], "properties": { "source": { "enum": [ "dwd", "noaa" ] }, "id": { "type": "string" }, "name": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" }, "elevation": { "type": [ "number", "null" ] }, "distanceKm": { "type": "number" }, "years": { "type": [ "integer", "null" ] } } }, "frost": { "type": "object", "additionalProperties": false, "required": [ "spring", "autumn", "hardSpring", "hardAutumn", "frostFreeDays" ], "properties": { "spring": { "type": "object", "additionalProperties": false, "required": [ "p10", "p50", "p90" ], "properties": { "p10": { "type": "string" }, "p50": { "type": "string" }, "p90": { "type": "string" } } }, "autumn": { "type": "object", "additionalProperties": false, "required": [ "p10", "p50", "p90" ], "properties": { "p10": { "type": "string" }, "p50": { "type": "string" }, "p90": { "type": "string" } } }, "hardSpring": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "p10", "p50", "p90" ], "properties": { "p10": { "type": "string" }, "p50": { "type": "string" }, "p90": { "type": "string" } } }, "hardAutumn": { "type": [ "object", "null" ], "additionalProperties": false, "required": [ "p10", "p50", "p90" ], "properties": { "p10": { "type": "string" }, "p50": { "type": "string" }, "p90": { "type": "string" } } }, "frostFreeDays": { "type": [ "integer", "null" ] } } }, "levels": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "level", "lastSpring", "firstAutumn", "frostFreeDays" ], "properties": { "level": { "type": "integer" }, "lastSpring": { "type": "string" }, "firstAutumn": { "type": "string" }, "frostFreeDays": { "type": "integer" } } } }, "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" } } } } } } } }