{ "openapi": "3.1.0", "info": { "title": "Frost Dates & Planting Zone API", "version": "1.0.0", "summary": "USDA hardiness zone, average frost dates, growing-season length and a frost-anchored planting calendar for any US ZIP.", "description": "USDA hardiness zone, average frost dates, growing-season length and a frost-anchored planting calendar for any US ZIP.\n\nNo API key is required. Data comes from official US government sources and is attributed in each response. Where the underlying model does not cover a location, the API says so explicitly rather than returning a confident wrong answer.", "contact": { "email": "chris.ellington13@gmail.com" }, "license": { "name": "Proprietary", "identifier": "LicenseRef-Proprietary" } }, "servers": [ { "url": "https://garden-frost-planting-api.netlify.app", "description": "Production" } ], "tags": [ { "name": "Garden", "description": "Frost dates and planting calendars" }, { "name": "Meta", "description": "Service metadata" } ], "paths": { "/frost-dates": { "get": { "tags": [ "Garden" ], "operationId": "getFrostDates", "summary": "Hardiness zone and frost dates for a location", "description": "USDA plant-hardiness zone, average last-spring and first-fall frost dates, and frost-free growing-season length. Provide `zip` OR `address`.", "x-probes": { "default": "/frost-dates?zip=20500" }, "parameters": [ { "name": "zip", "in": "query", "required": false, "description": "US ZIP code. Optional if address is given.", "schema": { "type": "string" }, "example": "20500" }, { "name": "address", "in": "query", "required": false, "description": "US address. Optional if zip is given.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "properties": { "zip": { "type": "string" } } }, "matchedAddress": { "type": [ "null" ] }, "zip": { "type": "string" }, "hardinessZone": { "type": "string" }, "zoneTempRangeF": { "type": "string" }, "zoneAvgMinTempNote": { "type": "string" }, "location": { "type": "object", "properties": { "lat": { "type": "number" }, "lon": { "type": "number" } } }, "frost": { "type": "object", "properties": { "frostFree": { "type": "boolean" }, "growingSeasonDays": { "type": "integer" }, "station": { "type": "string" }, "distanceMi": { "type": "number" }, "confidence": { "type": "string" }, "lastSpringFrost": { "type": "object", "properties": { "mmdd": { "type": "string" }, "monthDay": { "type": "string" }, "month": { "type": "integer" }, "day": { "type": "integer" } } }, "firstFallFrost": { "type": "object", "properties": { "mmdd": { "type": "string" }, "monthDay": { "type": "string" }, "month": { "type": "integer" }, "day": { "type": "integer" } } }, "thresholds": { "type": "object", "properties": { "hardFreeze28F": { "type": "object", "properties": { "lastSpring": { "type": "object", "properties": { "mmdd": { "type": "string" }, "monthDay": { "type": "string" }, "month": { "type": "integer" }, "day": { "type": "integer" } } }, "firstFall": { "type": "object", "properties": { "mmdd": { "type": "string" }, "monthDay": { "type": "string" }, "month": { "type": "integer" }, "day": { "type": "integer" } } } } }, "freeze32F": { "type": "object", "properties": { "lastSpring": { "type": "object", "properties": { "mmdd": { "type": "string" }, "monthDay": { "type": "string" }, "month": { "type": "integer" }, "day": { "type": "integer" } } }, "firstFall": { "type": "object", "properties": { "mmdd": { "type": "string" }, "monthDay": { "type": "string" }, "month": { "type": "integer" }, "day": { "type": "integer" } } } } }, "lightFrost36F": { "type": "object", "properties": { "lastSpring": { "type": "object", "properties": { "mmdd": { "type": "string" }, "monthDay": { "type": "string" }, "month": { "type": "integer" }, "day": { "type": "integer" } } }, "firstFall": { "type": "object", "properties": { "mmdd": { "type": "string" }, "monthDay": { "type": "string" }, "month": { "type": "integer" }, "day": { "type": "integer" } } } } } } }, "definition": { "type": "string" } } }, "sources": { "type": "object", "properties": { "hardinessZone": { "type": "string" }, "frostDates": { "type": "string" }, "geocoding": { "type": "string" } } }, "disclaimer": { "type": "string" } } }, "example": { "query": { "zip": "20500" }, "matchedAddress": null, "zip": "20500", "hardinessZone": "8a", "zoneTempRangeF": "10 to 15", "zoneAvgMinTempNote": "Average annual extreme minimum temperature 10 to 15 °F", "location": { "lat": 38.8948, "lon": -77.0361 }, "frost": { "frostFree": false, "growingSeasonDays": 241, "station": "WASHINGTON REAGAN AP, VA US", "distanceMi": 3.2, "confidence": "high", "lastSpringFrost": { "mmdd": "03-24", "monthDay": "March 24", "month": 3, "day": 24 }, "firstFallFrost": { "mmdd": "11-18", "monthDay": "November 18", "month": 11, "day": 18 }, "thresholds": { "hardFreeze28F": { "lastSpring": { "mmdd": "03-12", "monthDay": "March 12", "month": 3, "day": 12 }, "firstFall": { "mmdd": "12-03", "monthDay": "December 3", "month": 12, "day": 3 } }, "freeze32F": { "lastSpring": { "mmdd": "03-24", "monthDay": "March 24", "month": 3, "day": 24 }, "firstFall": { "mmdd": "11-18", "monthDay": "November 18", "month": 11, "day": 18 } }, "lightFrost36F": { "lastSpring": { "mmdd": "04-03", "monthDay": "April 3", "month": 4, "day": 3 }, "firstFall": { "mmdd": "11-06", "monthDay": "November 6", "month": 11, "day": 6 } } }, "definition": "Dates are the 50% probability of the last spring / first fall occurrence of the given minimum temperature (NOAA/NCEI 1991–2020 normals). Half the years frost falls outside this window." }, "sources": { "hardinessZone": "2023 USDA Plant Hardiness Zone Map — ZIP listing via PRISM Climate Group, Oregon State University", "frostDates": "NOAA/NCEI 1991–2020 U.S. Climate Normals (annual/seasonal freeze/frost normals), nearest station", "geocoding": "U.S. Census geocoder + 2023 Census ZCTA Gazetteer centroids" }, "disclaimer": "Average conditions from 1991–2020 climate normals — not a forecast. Roughly half of years see frost outside the stated window. Adjust for your microclimate (low spots, elevation, urban heat)." } } } }, "400": { "description": "The request did not identify a location (no address, ZIP or lat/lon).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/planting-calendar": { "get": { "tags": [ "Garden" ], "operationId": "getPlantingCalendar", "summary": "When to sow and transplant, anchored to local frost dates", "description": "A planting calendar built from the location's real frost dates. Omit `crop` for the full-garden calendar, or pass one of the 27 supported crop keys for a single crop.", "x-probes": { "default": "/planting-calendar?zip=20500&crop=tomato" }, "parameters": [ { "name": "zip", "in": "query", "required": false, "description": "US ZIP code. Optional if address is given.", "schema": { "type": "string" }, "example": "20500" }, { "name": "address", "in": "query", "required": false, "description": "US address. Optional if zip is given.", "schema": { "type": "string" } }, { "name": "crop", "in": "query", "required": false, "description": "Crop key. Omit for the whole garden.", "schema": { "type": "string", "enum": [ "tomato", "pepper", "eggplant", "cucumber", "zucchini", "wintersquash", "pumpkin", "beans", "corn", "melon", "basil", "okra", "sweetpotato", "peas", "spinach", "lettuce", "kale", "broccoli", "cabbage", "cauliflower", "onion", "carrot", "beet", "radish", "chard", "potato", "turnip" ] } }, { "name": "year", "in": "query", "required": false, "description": "Reference year. Defaults to the current one.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "object", "properties": { "zip": { "type": "string" }, "crop": { "type": "string" } } }, "matchedAddress": { "type": [ "null" ] }, "location": { "type": "object", "properties": { "zip": { "type": "string" }, "hardinessZone": { "type": "string" }, "lastSpringFrost": { "type": "string" }, "firstFallFrost": { "type": "string" }, "growingSeasonDays": { "type": "integer" }, "frostFree": { "type": "boolean" } } }, "calendar": { "type": "object", "properties": { "crop": { "type": "string" }, "name": { "type": "string" }, "category": { "type": "string" }, "frostTender": { "type": "boolean" }, "year": { "type": "integer" }, "schedule": { "type": "array", "items": { "type": "object", "properties": { "action": { "type": "string" }, "date": { "type": "string" }, "monthDay": { "type": "string" }, "relativeTo": { "type": "string" }, "offsetWeeks": { "type": "integer" } } } } } }, "method": { "type": "string" }, "sources": { "type": "object", "properties": { "frostDates": { "type": "string" }, "hardinessZone": { "type": "string" }, "plantingOffsets": { "type": "string" } } } } }, "example": { "query": { "zip": "20500", "crop": "tomato" }, "matchedAddress": null, "location": { "zip": "20500", "hardinessZone": "8a", "lastSpringFrost": "03/24", "firstFallFrost": "11/18", "growingSeasonDays": 241, "frostFree": false }, "calendar": { "crop": "tomato", "name": "Tomatoes", "category": "warm-season", "frostTender": true, "year": 2026, "schedule": [ { "action": "Start seeds indoors", "date": "2026-02-10", "monthDay": "February 10", "relativeTo": "last spring frost", "offsetWeeks": -6 }, { "action": "Transplant outdoors", "date": "2026-03-31", "monthDay": "March 31", "relativeTo": "last spring frost", "offsetWeeks": 1 } ] }, "method": "Dates computed as fixed week-offsets from this location's average frost dates (standard horticultural practice). Advisory — adjust for your microclimate, the current season, and variety maturity.", "sources": { "frostDates": "NOAA/NCEI 1991–2020 U.S. Climate Normals (nearest station)", "hardinessZone": "2023 USDA PHZM via PRISM Climate Group, Oregon State University", "plantingOffsets": "Computed general horticultural guidance (weeks relative to average frost) — not from any proprietary source" } } } } }, "400": { "description": "The request did not identify a location (no address, ZIP or lat/lon).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } } } } } } } }, "/health": { "get": { "tags": [ "Meta" ], "operationId": "getHealth", "summary": "Service metadata and status", "description": "The service description, version and endpoint documentation. Also serves as a liveness check.", "x-probes": { "default": "/health" }, "parameters": [], "responses": { "200": { "description": "Service is up", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "status": { "type": "string" }, "version": { "type": "string" }, "description": { "type": "string" }, "coverage": { "type": "object", "properties": { "zipCodes": { "type": "integer" }, "frostStations": { "type": "integer" }, "note": { "type": "string" } } }, "endpoints": { "type": "object", "properties": { "/frost-dates": { "type": "object", "properties": { "method": { "type": "string" }, "params": { "type": "object", "properties": { "zip": { "type": "string" }, "address": { "type": "string" } } }, "note": { "type": "string" }, "example": { "type": "string" } } }, "/planting-calendar": { "type": "object", "properties": { "method": { "type": "string" }, "params": { "type": "object", "properties": { "zip": { "type": "string" }, "address": { "type": "string" }, "crop": { "type": "string" }, "year": { "type": "string" } } }, "note": { "type": "string" }, "example": { "type": "string" }, "crops": { "type": "array", "items": { "type": "string" } } } }, "/health": { "type": "object", "properties": { "method": { "type": "string" }, "note": { "type": "string" } } } } }, "dataSources": { "type": "object", "properties": { "hardinessZone": { "type": "string" }, "frostDates": { "type": "string" }, "geocoding": { "type": "string" } } }, "docs": { "type": "string" } } }, "example": { "name": "Frost Dates & Planting Zone API", "status": "ok", "version": "1.0.0", "description": "Keyless US gardening data: USDA plant-hardiness zone, average last-spring / first-fall frost dates, frost-free growing-season length, and a frost-anchored planting calendar — from a US ZIP or address.", "coverage": { "zipCodes": 40502, "frostStations": 6517, "note": "Every US ZIP with a 2023 USDA hardiness zone; ~99% also carry NOAA frost dates from a nearest station with a distance-based confidence label." }, "endpoints": { "/frost-dates": { "method": "GET", "params": { "zip": "US ZIP (optional)", "address": "US address (optional)" }, "note": "Provide zip OR address.", "example": "/frost-dates?zip=20500" }, "/planting-calendar": { "method": "GET", "params": { "zip": "US ZIP (optional)", "address": "US address (optional)", "crop": "optional crop key (27 supported)", "year": "optional reference year" }, "note": "Omit crop for the full-garden calendar.", "example": "/planting-calendar?zip=20500&crop=tomato", "crops": [ "tomato", "pepper", "eggplant", "cucumber", "zucchini", "wintersquash", "pumpkin", "beans", "corn", "melon", "basil", "okra", "sweetpotato", "peas", "spinach", "lettuce", "kale", "broccoli", "cabbage", "cauliflower", "onion", "carrot", "beet", "radish", "chard", "potato", "turnip" ] }, "/health": { "method": "GET", "note": "Same as this document; returns status ok." } }, "dataSources": { "hardinessZone": "2023 USDA Plant Hardiness Zone Map, ZIP listing published by PRISM Climate Group, Oregon State University (public / freely reproducible).", "frostDates": "NOAA/NCEI 1991–2020 U.S. Climate Normals — annual/seasonal freeze/frost normals (public domain).", "geocoding": "U.S. Census geocoder + 2023 Census ZCTA Gazetteer centroids (public domain)." }, "docs": "/api-docs.html" } } } } } } } } }