Historical Agronomic Norms

This is a flexible API that allows you to calculate the averages for agronomic values and accumulations across any range of years for which we have data. Whereas the Agronomic Values and Accumulations API only supports up to 30 months of daily data, this API allow you to compare this year and the previous year to the long-term normals (however many years you want to include).

Common Best Practice: Considering the increasing weather variability over the last couple of decades, the most relevant norms to use for comparison are an average of the last 10 years.

Note: This API does not support pagination.

API Request

API Endpoints

HTTP Verbs and URIs

GET /v2/agronomics/fields/{fieldId}/agronomicnorms
GET /v2/agronomics/fields/{fieldId}/agronomicnorms/years/{startYear},{endYear}

When used without days as shown here, the API will reference the Field's most recently created Planting. The date range will be from that planting date through yesterday, and the averages will be calculated over the previous 10 years.

Alternatively, specify years without days, as shown, to use the most recent planting record and your desired number of years.

If no Planting exists for the Field, the API will return an error. If you choose not to create plantings you will need to specify the dates as shown in the next endpoint.

GET /v2/agronomics/fields/{fieldId}/agronomicnorms/{month-day}
GET /v2/agronomics/fields/{fieldId}/agronomicnorms/{startDay},{endDay}

Returns the average for either a single day or a range of days. By default, with no years specified, the API will average over the previous 10 years.

GET /v2/agronomics/fields/{fieldId}/agronomicnorms/{month-day}/years/{startYear},{endYear}
GET /v2/agronomics/fields/{fieldId}/agronomicnorms/{startDay},{endDay}/years/{startYear},{endYear}

These the same endpoints as above except you can choose to average over any number of years by specifying the start and end year in the URI.

Parameters

To get the averages for a single day, specify the month and day date here, excluding the year.

A month & day date formatted as MM-DD

{startDay}, and {endDay}

Two month-day's separated by a comma, implying the start and end days of a range. Like the previous parameter, this is only the month and day portion of a timestamp, excluding the year. The days cannot be more than a year apart.

A month & day date formatted as MM-DD

{startYear}
and{endYear}

Two years separated by a comma, implying the range of years (inclusive) for which you want the averages calculated. You must request at least three years of data.

Four-digit years, e.g., YYYY

Query String Parameters

Query Parameter Name

Description

Valid Values

sort

This API can sort its results by date, descending or ascending, when this parameter is used and set to date. See Sorting Conventions for more information.

date

properties

Only include these properties in the daily data. If not specified, then all properties are included by default. Any properties not specified are always included, and all child properties of a selection are included. Separate multiple choices with a comma. For example if you specify pet you will get amount and units.

For ranged results (multiple days), this API includes a total accumulations object in addition to an array of daily values. If you specify accumulatedGdd, accumulatedPrecipitation, accumulatedPet and/or accumulatedPpet in this parameter, the filter is applied to both the accumulations object and the daily values object. Others not included will be excluded from both as well.

If you specify accumulations in this parameter, then the accumulations object will be included and daily values array will be excluded entirely. This is useful when you only want to the know the current totals for the season. When this property is specified all of its children are included regardless of other values specified.

By default, the API will work in metric units (e.g., Celsius, millimeters, etc). When set to usa:

GDDs are calculated using Fahrenheit temperatures

PET and P/PET are calculated and returned in inches

precipitation is returned in inches

The API response includes properties that indicate the units for each temperature attribute. This parameter applies to all endpoints.

usametric

accumulationStartDay

If you want to start counting accumulations from before the specified start date (or before the planting date if using the most recent Planting), use this parameter to specify the day from which you wish to start counting. The daily values object will still only return the days between the start and end date. This date must come before the start date and not be more than one year prior.

The base temp to use for the any of the GDD equations. If the units parameter is set to metric, this value should be in Celsius units. If it is set to usa this value should be in Fahrenheit units.

Integer value

gddMinBoundary

The minimum boundary to use in the selected GDD equation. The behavior of this value is different depending on the equation you're using, see the section below on GDD equations for more. If the units parameter is set to metric, this value should be in Celsius units. If it is set to usa this value should be in Fahrenheit units.

Integer value

gddMaxBoundary

The max boundary to use in the selected GDD equation. The behavior of this value is different depending on the equation you're using, see the section below on GDD equations for more. If the units parameter is set to metric, this value should be in Celsius units. If it is set to usa this value should be in Fahrenheit units.

Integer value

excludeYears

You can opt to exclude one or more years from the range, and it's values will not be included in the averages. To exclude multiple years, separate them with a comma.

When used in conjunction with a range of days, the start of the range will be evaluated to determine exclusion. For example, for the range /agronomicnorms/11-01,03-31?excludeYears=2015, the data for 2015-11-01 through 2016-03-31 will be excluded from the results. The previous season, 2014-11-01 through 2015-03-31 will still be included.

Note: You must always have at least three years of data to average, and if using this parameter causes the number to fall lower the API will return an error.

Property Descriptions

The location the weather is for, including the geolocation and repeating the supplied Field ID.

Properties in the averageAccumulations Object

{accumulatedGdd}

The average and standard deviation of the total growing degree-days (GDDs) accumulated during the range of days over the years specified.

{accumulatedPrecipitation} and {accPrecipUnits}

The average and standard deviation of the total precipitation that fell during the range of days over the years specified; this object includes the amount and the corresponding units.

{accumulatedPET} and {accPetUnits}

The average and standard deviation of the total amount of potential evapotranspiration—the amount of water potentially lost from the ground due to plant use or evaporation—during the range of days over the years specified. This object includes both the amount and the corresponding units.

{accumulatedPPET}

The average and standard deviation of the ratio of Precipitation to Potential Evapotranspiration over the years specified. When this value is above 1, then more rain fell than the amount of likely water loss; if it's below 1, then more water was likely lost than fell as rain. P/PET is most useful when calculated for a range of days, as it is for this property, than for individual days.

Members of the dailyAverages Array

{day}

The month and day for which the averages apply, for example, if the averages are for May 1st this value would be 05-01. Each day in the requested range is an object in the dailyAverages array.

{gdd}

The average and standard deviation of the number of GDDs acquired during each day.

{pet} and {petUnits}

The average and standard deviation of the potential evapotranspiration for this day; that is, the amount of potential water lost from the ground do to plant use or evaporation.

{ppet}

The average and standard deviation of the ratio of Precipitation to Potential Evapotranspiration. When this value is above 1, then more rain fell than the amount of likely water loss; if it's below 1, then more water was likely lost than fell as rain. This figure is more useful over a range of days (see {accumulatedPPET} above, as any one day does not indicate a moisture or aridity trend.

{AccumulatedGDD}

The average and standard deviation of the total amount of GDDs accumulated since the start day through this object's day, averaged over the years specified. This is most useful for tracking events tied to GDDs (like plant growth stages) or for charting the accumulation over time.

{AccumulatedPrecip} and {AccPrecipUnits}

The average and standard deviation of the total amount of precipitation that has fallen since the start day through this object's day, averaged over the years specified. This is most useful for tracking events tied to precipitation (like plant growth or irrigation scheduling) or for charting the accumulation over time. Both the amount and the units are included.

{AccumulatedPET} and {AccPetUnits}

The average and standard deviation of the total amount of potential evapotranspiration—or water that has left the ground due to plant use or evaporation—since the start day through this object's day, averaged over the years specified. This is most useful for tracking events over time or for charting the accumulation over time. Both the amount and the units are included.

{AccumulatedPPET}

The P/PET ratio for all the days since the start day through this object's day, averaged over the years specified and the standard deviation of those values. This is most useful for tracking events tied to moisture stress or for charting the accumulation over time.

{dailyAveragesSelfHref}

The URI you can use to retrieve a specific day's agronomic norms (useful for caching a response).

awhere:field

The URI you can use to retrieve the field location information.

awhere:planting

The URI you can use to retrieve the planting information. This is only included if the API referenced the planting dates automatically.

{listSelfLink}

The URI used to generate the list.

About GDDs, Equations, and Default Values

Growing Degree Days (GDDs, also called Growing Degree Units), are a measurement of the amount of heat that a plant absorbs that aids in growing. There are a variety of equations used for calculating GDDs; depending on the crop, certain temperatures may be adjusted or discarded in cases where extreme temperatures do not increase the pace of growth. For example, common corn will not see faster growth from any temperatures above 86°F (30°C).

Four GDD equations are available via the aWhere Weather API. To use a particular equation, simply use the Equation ID as the value for the gddMethod parameter described above.

Equation ID

Description

standard (default)

The "Standard" equation is simplest of the GDD models and the one commonly used for generic GDD calculations. It simply takes the average of the day's low and high temperatures, and then subtracts a base temperature. By default, the API uses this equation for calculating GDDs (see default values below) when no equation is specified.

modifiedstandard

The "Modified" equation is common in agronomic models, especially growth stage models. If the day's max or min temperature falls outside an upper or lower boundary, the temperature is reset to the boundary for the purposes of calculating the mean temperature. A base temperature is subtracted from the mean temperature to determine the GDDs for that day.

min-temp-cap

An equation that resets the max temperature to an upper boundary if it exceeds the boundary, and uses the minimum recorded temperature only if it is lower than the boundary. Otherwise a specified lower temperature is always used. The base temperature is subtracted from the calculated mean to determine the GDDs.

min-temp-constant

An equation that resets the max temperature to an upper boundary if it exceeds the boundary, and always uses the minimum recorded temperature (no consideration of boundaries). The base temperature is subtracted from the calculated mean to determine the GDDs.

You can customize the constraints for each of the equations with the baseTemp, gddMaxBoundary, and gddMinBoundary parameters described above. If you don't specify those values, the API will use these defaults: