{ "openapi": "3.1.0", "info": { "title": "Typical Weather API", "version": "1.0.0", "summary": "Typical monthly weather — average high, low, precipitation and snow — for any US ZIP, from NOAA 1991–2020 Climate Normals.", "description": "Typical monthly weather — average high, low, precipitation and snow — for any US ZIP, from NOAA 1991–2020 Climate Normals.\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://typical-weather-api.netlify.app", "description": "Production" } ], "tags": [ { "name": "Weather", "description": "Climate normals" }, { "name": "Meta", "description": "Service metadata" } ], "paths": { "/typical-weather": { "get": { "tags": [ "Weather" ], "operationId": "getTypicalWeather", "summary": "Typical weather for a place, by month or across the year", "description": "Normal (not forecast) weather from the NOAA/NCEI 1991–2020 U.S. Climate Normals: average high, low, mean temperature, precipitation and snow. Give a `zip` or an `address`. Add `month` for one month, or omit it for the whole-year table with a best-time-to-visit framing. Resolution is monthly, so `date` resolves to that date's month.", "x-probes": { "oneMonth": "/typical-weather?zip=80202&month=January", "wholeYear": "/typical-weather?zip=80202" }, "parameters": [ { "name": "zip", "in": "query", "required": false, "description": "US ZIP code. Optional if address is given.", "schema": { "type": "string" }, "example": "80202" }, { "name": "address", "in": "query", "required": false, "description": "US address or city. Optional if zip is given.", "schema": { "type": "string" } }, { "name": "month", "in": "query", "required": false, "description": "Month name or number (1–12). Omit for the whole year.", "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": false, "description": "A date (YYYY-MM-DD); resolved to that month.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success. The shape depends on the arguments — see the examples.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "query": { "type": "object", "properties": { "zip": { "type": "string" }, "month": { "type": "integer" }, "monthName": { "type": "string" } } }, "location": { "type": "object", "properties": { "zip": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" } } }, "station": { "type": "object", "properties": { "name": { "type": "string" }, "distanceMi": { "type": "number" }, "elevationFt": { "type": "integer" } } }, "confidence": { "type": "string" }, "confidenceNote": { "type": "string" }, "source": { "type": "string" }, "normalsPeriod": { "type": "string" }, "disclaimer": { "type": "string" }, "normals": { "type": "object", "properties": { "month": { "type": "integer" }, "monthName": { "type": "string" }, "avgHighF": { "type": "number" }, "avgLowF": { "type": "number" }, "avgMeanF": { "type": "number" }, "avgPrecipIn": { "type": "number" }, "avgSnowIn": { "type": "number" } } }, "summary": { "type": "string" }, "sources": { "type": "object", "properties": { "normals": { "type": "string" }, "geocoding": { "type": "string" }, "license": { "type": "string" } } } } }, { "type": "object", "properties": { "query": { "type": "object", "properties": { "zip": { "type": "string" }, "month": { "type": [ "null" ] } } }, "location": { "type": "object", "properties": { "zip": { "type": "string" }, "lat": { "type": "number" }, "lon": { "type": "number" } } }, "station": { "type": "object", "properties": { "name": { "type": "string" }, "distanceMi": { "type": "number" }, "elevationFt": { "type": "integer" } } }, "confidence": { "type": "string" }, "confidenceNote": { "type": "string" }, "source": { "type": "string" }, "normalsPeriod": { "type": "string" }, "disclaimer": { "type": "string" }, "months": { "type": "array", "items": { "type": "object", "properties": { "month": { "type": "integer" }, "monthName": { "type": "string" }, "avgHighF": { "type": "number" }, "avgLowF": { "type": "number" }, "avgMeanF": { "type": "number" }, "avgPrecipIn": { "type": "number" }, "avgSnowIn": { "type": "number" } } } }, "yearSummary": { "type": "object", "properties": { "warmestMonth": { "type": "string" }, "coolestMonth": { "type": "string" }, "wettestMonth": { "type": "string" }, "driestMonth": { "type": "string" } } }, "sources": { "type": "object", "properties": { "normals": { "type": "string" }, "geocoding": { "type": "string" }, "license": { "type": "string" } } } } } ] }, "examples": { "oneMonth": { "summary": "Normals for a single month", "value": { "query": { "zip": "80202", "month": 1, "monthName": "January" }, "location": { "zip": "80202", "lat": 39.7294, "lon": -105.0083 }, "station": { "name": "DENVER WATER DEPT, CO US", "distanceMi": 1.6, "elevationFt": 1594 }, "confidence": "high", "confidenceNote": "Nearest normals station is 2 mi away — high confidence.", "source": "NOAA/NCEI 1991–2020 U.S. Climate Normals (monthly)", "normalsPeriod": "1991–2020", "disclaimer": "Normals are 30-year averages (1991–2020). Any individual year can differ substantially; this is the typical/expected pattern, not a forecast.", "normals": { "month": 1, "monthName": "January", "avgHighF": 48.5, "avgLowF": 21.3, "avgMeanF": 34.9, "avgPrecipIn": 0.43, "avgSnowIn": 5.5 }, "summary": "January in ZIP 80202 is typically chilly — highs around 49°F and lows near 21°F. Expect about 0.4 in of precipitation across the month, including roughly 5.5 in of snow.", "sources": { "normals": "NOAA/NCEI 1991–2020 U.S. Climate Normals — Monthly (MLY-TMAX/TMIN/TAVG/PRCP/SNOW-NORMAL), nearest station", "geocoding": "U.S. Census geocoder + 2023 Census ZCTA Gazetteer centroids", "license": "Public domain (U.S. Government work)." } } }, "wholeYear": { "summary": "Whole-year table, returned when month is omitted", "value": { "query": { "zip": "80202", "month": null }, "location": { "zip": "80202", "lat": 39.7294, "lon": -105.0083 }, "station": { "name": "DENVER WATER DEPT, CO US", "distanceMi": 1.6, "elevationFt": 1594 }, "confidence": "high", "confidenceNote": "Nearest normals station is 2 mi away — high confidence.", "source": "NOAA/NCEI 1991–2020 U.S. Climate Normals (monthly)", "normalsPeriod": "1991–2020", "disclaimer": "Normals are 30-year averages (1991–2020). Any individual year can differ substantially; this is the typical/expected pattern, not a forecast.", "months": [ { "month": 1, "monthName": "January", "avgHighF": 48.5, "avgLowF": 21.3, "avgMeanF": 34.9, "avgPrecipIn": 0.43, "avgSnowIn": 5.5 }, { "month": 2, "monthName": "February", "avgHighF": 49, "avgLowF": 21.7, "avgMeanF": 35.4, "avgPrecipIn": 0.6, "avgSnowIn": 8.4 }, { "month": 3, "monthName": "March", "avgHighF": 57.9, "avgLowF": 29.6, "avgMeanF": 43.7, "avgPrecipIn": 1.13, "avgSnowIn": 9.2 }, { "month": 4, "monthName": "April", "avgHighF": 64.1, "avgLowF": 36.2, "avgMeanF": 50.1, "avgPrecipIn": 1.98, "avgSnowIn": 5 }, { "month": 5, "monthName": "May", "avgHighF": 73, "avgLowF": 45.9, "avgMeanF": 59.4, "avgPrecipIn": 2.65, "avgSnowIn": 0.9 }, { "month": 6, "monthName": "June", "avgHighF": 85.3, "avgLowF": 55.8, "avgMeanF": 70.6, "avgPrecipIn": 1.73, "avgSnowIn": 0 }, { "month": 7, "monthName": "July", "avgHighF": 91.4, "avgLowF": 61.8, "avgMeanF": 76.6, "avgPrecipIn": 1.9, "avgSnowIn": 0 }, { "month": 8, "monthName": "August", "avgHighF": 89.6, "avgLowF": 60.1, "avgMeanF": 74.8, "avgPrecipIn": 1.81, "avgSnowIn": 0 }, { "month": 9, "monthName": "September", "avgHighF": 81.6, "avgLowF": 50.7, "avgMeanF": 66.2, "avgPrecipIn": 1.2, "avgSnowIn": 0 }, { "month": 10, "monthName": "October", "avgHighF": 67.6, "avgLowF": 37.7, "avgMeanF": 52.6, "avgPrecipIn": 1.16, "avgSnowIn": 2.5 }, { "month": 11, "monthName": "November", "avgHighF": 55.9, "avgLowF": 27.6, "avgMeanF": 41.7, "avgPrecipIn": 0.78, "avgSnowIn": 4.4 }, { "month": 12, "monthName": "December", "avgHighF": 47.3, "avgLowF": 20.6, "avgMeanF": 34, "avgPrecipIn": 0.48, "avgSnowIn": 4.8 } ], "yearSummary": { "warmestMonth": "July", "coolestMonth": "December", "wettestMonth": "May", "driestMonth": "January" }, "sources": { "normals": "NOAA/NCEI 1991–2020 U.S. Climate Normals — Monthly (MLY-TMAX/TMIN/TAVG/PRCP/SNOW-NORMAL), nearest station", "geocoding": "U.S. Census geocoder + 2023 Census ZCTA Gazetteer centroids", "license": "Public domain (U.S. Government work)." } } } } } } }, "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": { "status": { "type": "string" }, "service": { "type": "string" }, "description": { "type": "string" }, "dataset": { "type": "object", "properties": { "source": { "type": "string" }, "license": { "type": "string" }, "coverage": { "type": "object", "properties": { "zips": { "type": "integer" }, "stations": { "type": "integer" } } } } }, "endpoints": { "type": "object", "properties": { "/typical-weather?zip=80202&month=January": { "type": "string" }, "/typical-weather?address=Denver, CO&month=5": { "type": "string" }, "/typical-weather?zip=33139&date=2025-07-15": { "type": "string" }, "/typical-weather?zip=10001": { "type": "string" }, "/health": { "type": "string" } } } } }, "example": { "status": "ok", "service": "Typical Weather API", "description": "Typical/normal weather (avg high, low, mean, precipitation, snow) for any US ZIP or address, by month or across the whole year — from NOAA/NCEI 1991–2020 U.S. Climate Normals.", "dataset": { "source": "NOAA/NCEI 1991–2020 U.S. Climate Normals (monthly)", "license": "Public domain (U.S. Government work).", "coverage": { "zips": 40306, "stations": 7306 } }, "endpoints": { "/typical-weather?zip=80202&month=January": "Normals for one month by ZIP.", "/typical-weather?address=Denver, CO&month=5": "Normals for one month by address/city.", "/typical-weather?zip=33139&date=2025-07-15": "Normals for that date's month (monthly resolution).", "/typical-weather?zip=10001": "Whole-year table + best-time-to-visit framing.", "/health": "This health/metadata document." } } } } } } } } } }