Agronomic Values and Accumulations by Geolocation

Agronomic Values are calculated numbers that can be used to show the agronomic status of a location. These figures can be used, for example, to track and predict plant growth or identify water stress. Accumulated values allow growers to easily identify how the weather has been over the season. Both sets of data are commonly used on small and large farms alike. This is a very flexible API that supports a wide variety of configurations to get exactly the data you want as efficiently as possible.

Note: Most aWhere customers reference locations by a registered field ID. At this time, all our supporting resources and code samples are geared for these use cases. If you need assistance using this API please contact your aWhere representative.

[Toc:ul]

API Request

API Endpoints

HTTP Verbs and URIs

GET /v2/agronomics/locations/{latitude},{longitude}/agronomicvalues/{singleDate}
GET /v2/agronomics/locations/{latitude},{longitude}/agronomicvalues/{startDate},{endDate}
  • Use either a single date or a start and end date to return any number of days of data (up to 30 months).
  • Dates specified that are today or later, relative to the Field's location, will return Forecast Agronomic Values. Forecast Agronomic Values are available for today plus the next 7 days.
  • Note that this API does not support pagination, so a large number of days may result in slightly slower response times.

Parameters

Parameter Description Valid Values
{latitude} The decimal-notation latitude of the location for which you want weather data. A number
{longitude} The decimal-notation longitude of the location for which you want weather data. A number
{singleDate} A single date, for which the API will return just one day's worth of agronomic values weather for the location. Must be between 30 months ago, and 7 days from today (inclusive). A date formatted as YYYY-MM-DD
{startDate}
and
{endDate}
Two dates separated by a comma, specifying the start and end date of a range. The API will return data for all the days between those dates (inclusive). Both dates must be between 30 months ago, and 7 days from today (inclusive). Dates formatted as YYYY-MM-DD

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.

location
accumulations
gdd
pet
ppet
accumulatedGdd
accumulatedPrecipitation
accumulatedPet
accumulatedPpet
units 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.

usa
metric
accumulationStartDate 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 date from which you wish to start counting. The daily values object will still only return the days between the start and end date (inclusive). The accumulationStartDate must come before the startDate, and be between yesterday and one year prior to today (inclusive). Valid date formatted as YYYY-MM-DD
gddMethod There are variety of equations available for calculating growing degree-days (GDDs). Details about the available equations are below. standard
modifiedstandard
min-temp-cap
min-temp-constant
gddBaseTemp 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

Request Body

None

HTTP Headers

Remember to always send your OAuth2 Access Token in the Authorization header (see Authentication). This API doesn't require any additional headers.

API Response

Response HTTP Status Codes and Headers

This API returns standard HTTP status codes and headers for aWhere APIs. It doesn't return anything more.

Response Body

Format for Ranged Results

{
 "location":":{
	"latitude":{latitude},
	"longitude":{longitude}
	},
 "accumulations":{ 
	"gdd":{accumulatedGDD},
	"precipitation":":{
		"amount":{accumulatedPrecipitation},
		"units":"{accPrecipUnits}"
		},
	"pet":{
		"amount":{accumulatedPET},
		"units":"{accPetUnits}"
		},
	"ppet":{accumulatedPPET}
	},
 "dailyValues":[{
	"date":"{date}",
	"gdd":{gdd},
	"pet":{
		"amount":{pet},
		"units":"{petUnits}"
		},
	"ppet":{pPet},
	"accumulatedGdd":{rollingAccumulatedGDD}, 
	"accumulatedPrecipitation":":{
		"amount":{rollingAccumulatedPrecip},
		"units":"{rollingAccPrecipUnits}"
		},
	"accumulatedPet":{
		"amount":{rollingAccumulatedPET},
		"units":"{rollingAccPetUnits}"
		},
	"accumulatedPpet":{rollingAccumulatedPPET},
	"_links":{ 
		"self":{"href":"{dailyValueSelfHref}"}
		}
	},{ 
	   ...
 	  }
	],
 "_links":{
	"self":{"href":"{selfLink}"}
 }
}

Format for Single Days

{
"date":"{date}",
 "location":":{
	"latitude":{latitude},
	"longitude":{longitude}
	},
"gdd":{gdd},
"pet":{
	"amount":{pet},
	"units":"{petUnits}"
	},
"ppet":{pPet},
"accumulatedGdd":{rollingAccumulatedGDD}, 
"accumulatedPrecipitation":":{
	"amount":{rollingAccumulatedPrecip},
	"units":"{rollingAccPrecipUnits}"
	},
"accumulatedPet":{
	"amount":{rollingAccumulatedPET},
	"units":"{rollingAccPetUnits}"
	},
"accumulatedPpet":{rollingAccumulatedPPET},
"_links":{ 
	"self":{"href":"{dailyValueSelfHref}"}
	}
}

Property Descriptions

Name Description
location The location the weather is for, echoing the supplied latitude and longitude.
Properties in the accumulations Object
{gdd} The total growing degree-days (GDDs) accumulated during the range of days.
{precipitation} and {units} The total precipitation that fell during the range of days; this object includes the amount and the corresponding units.
{pet} and {units} 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. This object includes both the amount and the corresponding units.
{ppet} 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. 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 dailyValues Array
{date} The date for which the agronomic values apply. Each day in the requested range is an object in the dailyValues array.
{gdd} The number of GDDs acquired during each day.
{pet} and {units} 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 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 {ppet} in the accumulations object above), as any one day does not indicate a moisture or aridity trend.

{accumulatedGdd} The total amount of GDDs accumulated since the start date through this object's date. This is most useful for tracking events tied to GDDs (like plant growth stages) or for charting the accumulation over time.
{accumulatedPrecip} and {units} The total amount of precipitation that has fallen since the start date through this object's date. 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 {units} The total amount of potential evapotranspiration—or water that has left the ground due to plant use or evaporation—since the start date through this object's date. 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 date through this object's date. This is most useful for tracking events tied to moisture stress or for charting the accumulation over time.
{href} The URI you can use to retrieve a specific day's agronomic values (useful for caching a response).
{self} 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:

Equation ID Base Temp Upper Boundary Lower Boundary
standard (default) 10°C (50°F) Not Used Not Used
modifiedstandard 10°C (50°F) 30°C (86°F) 10°C (50°F)
minTempCapped 12°C (53.6°F) 35°C (95°F) 21.1°C (70°F)
minTempConstant 10°C (50°F) 33°C (91.4°F) Not Used

Example: Getting Only The Total Accumulations For a Range

Request

Endpoint

GET /v2/agronomics/locations/39.8282,-98.5795/agronomicvalues/2015-07-01,2015-07-31?properties=accumulations

Response

Body

{
 "location":":{
	"latitude":38.2314132,
	"longitude":-97.232133
	},
 "accumulations":{ 
	"gdd":682,
	"precipitation":":{
		"amount":154,
		"units":"mm"
		},
	"pet":{
		"amount":221,
		"units":"mm"
		},
	"ppet":0.6968325792
	},
 "_links":{
	"self":{"href":"/v2/agronomics/locations/39.8282,-98.5795/agronomicvalues/2015-07-01,2015-07-31?properties=accumulations"}
 }
}