Joel's APIs

A collection of useful APIs for developers and data enthusiasts.

Frost Date API

Get frost date predictions for any US location based on NOAA Climate Normals data. Returns first and last frost dates with probability percentages to help with garden planning and agricultural decisions.

Endpoint


        GET apis.joelgrant.dev/api/v1/frost/{zip_code}

Example Request


curl --location 'apis.joelgrant.dev/api/v1/frost/76432'

Response Format

{
  "zip_code": "76432",
  "data": {
    "zip_code": "76432",
    "location": {
      "city": "Blanket",
      "state": "TX",
      "latitude": 31.84215,
      "longitude": -98.79696
    },
    "frost_free": false,
    "weather_station": {
      "station_id": "USC00411138",
      "name": "BROWNWOOD 2ENE, TX US",
      "latitude": 31.7383,
      "longitude": -98.9456,
      "distance_km": 18.19
    },
    "frost_dates": {
      "first_frost_32f": {
        "10%": "10/28",
        "20%": "11/01",
        "30%": "11/04",
        "40%": "11/07",
        "50%": "11/10",
        "60%": "11/13",
        "70%": "11/16",
        "80%": "11/20",
        "90%": "11/28"
      },
      "last_frost_32f": {
        "10%": "04/09",
        "20%": "04/04",
        "30%": "03/31",
        "40%": "03/27",
        "50%": "03/22",
        "60%": "03/17",
        "70%": "03/13",
        "80%": "03/09",
        "90%": "03/03"
      }
    }
  }
}

Error Responses

Status Reason Example Response

Status	Reason	Example Response
`400`	Invalid zip code format (must be 5 digits)	`{ "error": { "message": "Invalid zip code format. Please provide a 5-digit zip code.", "status": 400 } }`
`404`	No frost data found for the provided zip code	`{ "error": { "message": "Frost data not found for the provided zip code", "status": 404 }, "zip_code": "90000" }`

400

Invalid zip code format (must be 5 digits)

{
  "error": {
    "message": "Invalid zip code format. Please provide a 5-digit zip code.",
    "status": 400
  }
}

404

No frost data found for the provided zip code

{
  "error": {
    "message": "Frost data not found for the provided zip code",
    "status": 404
  },
  "zip_code": "90000"
}

⚠ Frost-Free Locations

If a zip code's location does not experience frost (e.g., tropical or very warm climates), the response will include "frost_free": true at the data level, and the frost date fields will be null:

"data": {
  "zip_code": "90001",
  "location": { ... },
  "frost_free": true,
  "weather_station": { ... },
  "frost_dates": {
    "first_frost_32f": null,
    "last_frost_32f": null
  }
}

How It Works

Location Lookup: Uses zip code to find the exact coordinates and nearest weather station
Climate Data: Pulls from NOAA Climate Normals 1991-2020 dataset for historical accuracy
Probability Calculations: Returns frost dates at different probability levels (10% = earliest likely, 90% = latest likely)
First Frost: Probability of first 32°F temperature in fall/winter
Last Frost: Probability of last 32°F temperature in spring

Data Attribution

Frost date predictions are based on historical climate data from the National Oceanic and Atmospheric Administration (NOAA).

Data Source: NOAA Climate Normals 1991-2020
U.S. Climate Normals provide a 30-year average of temperature, precipitation, and other climate variables for weather stations across the United States.