Growth Stage Models List, and Single Model Detail

Deprecating: Please note this API is being deprecated and will be removed from service by January 15, 2016. Please begin switching to our new Version-2 API Platform.

All plants require a certain amount of heat to develop. These heat units are referred to as Growing Degree Days (GDDs) or Growing Degree Units. Moreover, plant development is broken up into stages, where each stage may require a different type of activity in the field. Stages are calculated based on the number of GDDs that have accumulated since the crop was planted.

The Growth Stage Models API can calculate the current estimated growth stage for a particular crop, as well as provide information about the upcoming stage. There are models available for a number of crops and crop varieties, and have been sourced from reputable scientific sources and vetted by aWhere's own science team.

This API returns a list of the available models, the crop and variety each is for, and the source for that model. Each model has an ID and that ID can be used to retrieve a single model's detail, rather than retrieve and parse the entire list.

Use the Growth Stage Models Results API to calculate the growth stage data for any given model in the system.

About the Available Models

The current generation of growth stage models are sourced from leading universities and extensions, industry- specific science organizations, and aWhere's agronomic scientists based on published literature. Each model has been vetted by our science team as well as in everyday use by farmers, and the original source of the model is included in the model information.

Selecting a model depends on crop variety and each farmer's preferred model or source. Though extension offices tend to tune their models to their geographic area, there is not a restriction on where models may be effective. Your application may select a particular one for your customers based on crop and location, or offer an interface to allow customers to choose their preferred model.

API Request

API Endpoints

HTTP Verbs and URIs

GET /v1/models
  • Retrieves all available models.
GET /v1/models/{modelId}
  • Retrieves the model with the given ID.

Parameters

Placeholder Description Valid Values
{modelId} The model ID, which is retrievable from the list of all models. This is also used in the results API. String value provided by the list of models.

Query String Parameters

Query Parameter Name Description Valid Values
properties Optimize the size of the payload by limiting the amount of data that is returned. Only the properties specified will be included in the response payload. Include multiple properties by separating the names with a comma. Note that id and _links are always included. name
crop
cropVariety
source
type
crop Limit the result set to the models that apply to a particular crop type. These values can be derived from the values in an unfiltered response, but at time of writing include the options to the right. The list can be filtered to only one crop at a time.

This parameter has no effect on the single-model detail request.
barley
canola
cotton
oat
sugarbeet
sunflower
wheat
corn

Request Body

None

API Response

Response HTTP Status Codes and Headers

This API returns standard HTTP status codes and headers for aWhere APIs. No special headers are returned.

Response Body

Format

{
"models": [
   {
      "id": "{modelId}",
      "name": "{modelName}",
      "type": "{modelType}",
      "crop": "{crop}",
      "cropVariety": "{cropVariety}",
      "source": {
        "name": "{sourceName}",
        "link":"{sourceHRef}"
      },
      "_links": {
        "self": {
          "href": "{selfHref}"
        } 
      }
   },
   { ... repeat for each available model ... }
  ],
  "_links": {
    "self": {
      "href": "/v1/models"
    } 
  }
}

Note: When requesting a single model, the response is just an object like the first object of the array shown here.

Property Descriptions

Name Description
{modelId} The aWhere ID for the model. Use this to retrieve either the single-model detail or when calculating results.
{modelName} The name for the model.
{modelType} The model type. At this time all models are of type growthstage
{crop} The crop for which the model will calculate stages.
{cropVariety} The crop sub-type or variety for which the model applies.
{sourceName} The original source for the model, usually a university extension office or published research. All models have been vetted or augmented by aWhere's scientists.
{sourceHref} The URL where additional detail or description about the model can be found.
{selfHref} The URL for the data object, which can be stored and retrieved as-is.

Example: Get All Available Models for Sugarbeet

Request

Endpoint

GET /v1/models

Response

Body

{
  "models": [     
    {
      "id": "SugarbeetGenericNDAWN",
      "name": "Sugarbeet (North Dakota Agricultural Weather Network)",
      "type": "growthstage",
      "crop": "Sugarbeet",
      "cropVariety": "Generic",
      "source": {
        "name": "North Dakota Agricultural Weather Network",
        "link": "http://ndawn.ndsu.nodak.edu/help-sugarbeet-growing-degree-days.html"
      },
      "_links": {
        "self": {
          "href": "/v1/models/SugarbeetGenericNDAWN"
        }
      }
    }],
  "_links": {
    "self": {
      "href": "/v1/models"
    } 
  }
}

Example: Get A Single Model

Request

Endpoint

GET /v1/models/SugarbeetGenericNDAWN

Response

Body

{
  "id": "SugarbeetGenericNDAWN",
  "name": "Sugarbeet (North Dakota Agricultural Weather Network)",
  "type": "growthstage",
  "crop": "Sugarbeet",
  "cropVariety": "Generic",
  "source": {
    "name": "North Dakota Agricultural Weather Network",
    "link": "http://ndawn.ndsu.nodak.edu/help-sugarbeet-growing-degree-days.html"
  },
  "_links": {
    "self": {
      "href": "/v1/models/SugarbeetGenericNDAWN"
    }
  }
}