Agriculture

Growing Degree Units (GDU / GDD) for a point.

Returns Growing Degree Units (also called Growing Degree Days) for a US point (CONUS, Alaska, Hawaii), computed on read from stored daily maximum/minimum temperatures. No GDU grids are stored; the values are derived per request from the temperature bundles, so a crop's base/upper thresholds and the simple/modified method can be selected freely without re-running the pipeline.

Two modes:

  • Forecast (default). Without season_start, the response carries a per-day GDU series across the NBM forecast horizon (days).
  • Season cumulative. With season_start (a YYYY-MM-DD local date within the ~180-day observed window), the response stitches RTMA observed daily history + today's partial (hourly on-read rollup) + NBM forecast, returns a cumulative_total, and adds a per-day cumulative_gdu running sum. This is the number a grower tracks against crop growth-stage milestones. If part of the season window has no observed data, the per-day series still comes back 200 but cumulative_total is omitted and meta.gaps carries an unfilled span — a partial sum is not a season total.

Crops. Pass a catalog crop id (e.g. corn, soybean, wheat_winter, cotton, alfalfa) to use calibrated thresholds, or crop=custom with base_temp_c (and optionally upper_temp_c / method) to supply your own.

Every response echoes the resolved method, thresholds (always in °C), and a meta provenance block (day_definition, computation_path, source, unit, any gaps) so nothing is silently assumed.

Pass one location: lat and lon, zip, or location. A request without one returns 400; a ZIP or name that does not resolve returns 404; while location lookup is unavailable, a zip or location request returns 503 with Retry-After. The resolved place is echoed as location, present when the place was resolved.

A point outside the 50 US states and DC returns 404 outside-coverage with next_steps.

get/v1/agriculture/growing-degree-days

Request

  • Base URL: https://api.smarterweather.com
  • URL: https://api.smarterweather.com/v1/agriculture/growing-degree-days
  • Auth: HTTP bearer

Query parameters

latnumber double

Latitude (WGS84 decimal degrees). Give it with lon. On a route that also takes zip or location, give only one location form.

lonnumber double

Longitude (WGS84 decimal degrees). Give it with lat. On a route that also takes zip or location, give only one location form.

zipstring

5-digit US ZIP code. Mutually exclusive with lat/lon and location.

locationstring

Free-text location name. Examples: "Boston, MA", "94043", "Denver". Resolved by the Smarter Weather geocoder. Mutually exclusive with lat/lon and zip.

cropstring required

Crop catalog id (e.g. corn, soybean, wheat_winter, cotton, alfalfa) or custom to supply thresholds directly.

season_startstring date

Season/planting start as a YYYY-MM-DD local date. Presence switches the response into cumulative season-to-date mode. Must be within the ~180-day observed-history window.

daysinteger

Forecast horizon in days (default 10).

day_definition'nws' | 'local_calendar'

Daily boundary: nws (default; native NBM MaxT/MinT period extremes) or local_calendar (midnight-to-midnight local day).

unit'imperial' | 'metric'

Unit system for GDU + temperatures. imperial (default) uses °F-days; metric uses °C-days. Thresholds are always echoed in °C regardless.

base_temp_cnumber double

Custom base threshold in °C. Required when crop=custom.

upper_temp_cnumber double

Custom upper cutoff in °C (enables the modified method). Optional.

method'simple' | 'modified'

GDU method for custom crops. Defaults based on whether upper_temp_c is supplied.

include_milestonesboolean

Include the crop's growth-stage GDU milestones.

Response

Growing Degree Units for the requested point.

cropstring required

Echoed crop id (corn, ..., or custom).

catalog_versioninteger required

Version of the crop catalog used to resolve thresholds.

method'simple' | 'modified' required

GDU method applied.

cumulative_totalnumber double

Season-to-date GDU total in the requested unit. Present only in cumulative mode (when season_start was supplied), and omitted even then when meta.gaps contains an unfilled span: those days have no observed data, so the sum would under-count the season. Treat an absent total on a season_start request as "season total unavailable" and fall back to the per-day series, which is still good for the days it covers. meta.gaps names the window that was lost.

Example response

{
  "location": {
    "name": "Boston",
    "region": "MA",
    "country": "US",
    "timezone": "America/New_York",
    "county": "Suffolk",
    "zip": "02108"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.