Introduction

Welcome to the Iteris ClearAg Crop Health API. This API combines crop growth, drydown, and nutrient models, applied in conjunction with Iteris’ own state-of-the-art weather and soil models, to provide users with agronomic advisory information. This information includes crop growth stage tracking and forecasting, pest and disease pressures, nutrient needs, and in-field and on-farm grain drying timelines and costs for a host of different crops. The Crop Health API is intended to provide agricultural professionals with scientifically based decision support tools.

Please note that before users can access the ClearAg Crop Health API, an active account and license key is required. These credentials will be provided for each service request. To obtain your API key, contact your Iteris account representative.

API Services

Through the ClearAg Crop Health API, users can evaluate the expected growth and maturation of crops, crop nutrient uptake, nutrient profiles of fields, the periods of plant wetness relative to historical norms, the suitability of spraying conditions for any particular product, and the post-maturity drydown and drying costs of various grain and oilseed crops. Also included in this API are endpoints that serve as an interface with the Accounts API, which allows users to provide real-time feedback regarding a given crop, serving as a means of calibrating and optimizing the applicable model.

The required parameters in the Crop Health API will vary depending on whether coordinates are provided or Accounts API integration is used. For clients not using the Accounts API, required and optional parameters are listed under the “location-based” column within the Request Parameters tables. For required and optional parameters when utilizing the Accounts API, please refer to the information contained in the “Accounts API Integration” column. When utilizing the Accounts API, field, growth, activity, and feedback information present in the system will be used where necessary. The Accounts API integration will automatically pre-populate client data where applicable.

Additional information regarding the Accounts API is available on the ClearAg website: https://docs.clearag.com/documentation/Accounts_API/latest

For those not currently using the Accounts API, please contact your Iteris account representative for details.

Multiple data center regions are available to meet users’ legal and performance needs. Currently, data centers exist within the United States (ag.us.clearapis.com) and the European Union (ag.eu.clearapis.com). Account and related information such as fields and growths are not shared between these regions. Data resolution and availability also vary by region, and each region requires a unique set of credentials. Please contact your account representative for account creation, data segregation, and data coverage information.

Additional API information is available in the Supplementary API Information section of the Appendix.

1. Corn

1.1. Corn Growth - v1.0

Leveraging Iteris’ corn growth stage model, the Corn Growth endpoint allows users to model the maturation and development of corn crops. Users may also take advantage of Accounts API integration to provide crop growth feedback and optimize model results.

1.1.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/corn/growth?app_id={string}
&app_key={string}&location={lat, lon coordinates}&plant_date={timestamp}
&days={integer}&account_id={string}&user_id={string}&growth_id={string}
&relative_maturity={integer}

1.1.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

relative_maturity

integer

no

 — 

Classification indicating how early a variety matures. Valid values range from 70 to 130, with lower values indicating an “early” relative maturity and higher values indicating a “late” relative maturity. Default is 100.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

1.1.3. Response Object (JSON)

Field Description

gdd

Growing degree days accumulated on the current date.

agdd

Aggregate growing degree days from plant date, including the current period’s date.

air_temp_min

Minimum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

air_temp_max

Maximum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

last_stage

The last known growth stage. If no valid stage has been reached, this value will be “n/a.” This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

new_stage

The crop is expected to have entered a new growth stage between the current period’s date and the previous period’s date.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

description

Text description for a stage.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

1.1.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/corn/growth?app_id=123&app_key=321
&location=47,-97&plant_date=1462060800&days=160

1.1.5. Example Response

{
    "data":{
        "47,-97":{
            "2014-09-11":{
                "agdd":2396.0,
                "air_temp_max":73.0,
                "air_temp_min":51.0,
                "gdd":12.0,
                "last_stage":"r5",
                "new_stage":"r6"
            },...
        }
    },
    "harvest_window":{
        "end":"2016-10-25",
        "start":"2016-09-23"
    },
    "stage_descriptions":{
        "r6":{
            "description":"Physiological Maturity - kernels have attained their maximum dry weight or dry matter accumulation. The hard starch layer has advanced completely to the cob."
        },...
    }
}

1.2. Corn Growth with GDD Envelope - v1.1

The Corn Growth with GDD Envelope service provides corn growth information in addition to GDD envelope data. GDD envelope calculation begins from either the current day, or the planted/emergence date, whichever is further in the future. The envelope is constructed by compiling the previous 10 years of weather data, and simulating the maximum and minimum GDD that would have accumulated within those 10 years for each date. The calculated minimum and maximum values are then added to the current start of calculation date AGDD going onwards to show range of possibilities.

1.2.1. URL Description

http://ag.us.clearapis.com/v1.1/crop_health/corn/growth/
gdd_envelope?app_id={string}&app_key={string}&plant_date={timestamp}
&location={lat, lon coordinates}&days={integer}&account_id={string}
&user_id={string}&growth_id={string}
&relative_maturity={integer}

1.2.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

relative_maturity

integer

no

 — 

Classification indicating how early a variety matures. Valid values range from 70 to 130, with lower values indicating an “early” relative maturity and higher values indicating a “late” relative maturity. Default is 100.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

1.2.3. Response Object (JSON)

Field Description

gdd

Growing degree days accumulated on the current date.

agdd

Aggregate growing degree days from plant date, including the current period’s date.

agdd_envelope_max

Maximum observed agdd during the previous 10 years.

agdd_envelope_min

Minimum observed agdd during the previous 10 years.

agdd_envelope_min_year

Year that the agdd_envelope_min was observed.

agdd_envelope_max_year

Year that the agdd_envelope_max was observed.

air_temp_min

Minimum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

air_temp_max

Maximum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

last_stage

The last known growth stage. If last_stage is empty, the crop is somewhere between the previous growth stage and the next growth stage.

new_stage

The crop is expected to have entered a new growth stage between the current period’s date and the previous period’s date.

start

The beginning of typical harvest operations.

end

The end of typical harvest operations.

description

Text description for a stage.

feedback_id

If this field is present, it indicates a confirmed or observed growth stage on the current date.

1.2.4. Example Request

http://ag.us.clearapis.com/v1.1/crop_health/corn/growth/gdd_envelope?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800&days=160

1.2.5. Example Response

{
    "attribution":[],
    "data":{
        "42.22851735620852,-100.986328125":{
            "growth":{
                "2016-10-20":{
                    "agdd":14.5,
                    "agdd_envelope_max":14.5,
                    "agdd_envelope_max_year":"2015",
                    "agdd_envelope_min":14.5,
                    "agdd_envelope_min_year":"2015",
                    "air_temp_max":58.0,
                    "air_temp_min":38.0,
                    "gdd":4.0,
                    "last_stage":"n/a",
                    "new_stage":"n/a"
                }, ...
            },
            "harvest_window":{
                "end":"n/a",
                "start":"n/a"
            }
        }
    },
    "stage_descriptions":{
        "n/a":{
            "advisor":"Not available/Not applicable",
            "description":"Not available/Not applicable",
            "images":[],
            "name":"Not available/Not applicable",
            "order":"0"
        }
    }
}

1.3. Corn Growth Add Feedback - v1.0

By providing feedback relating to the growth stage estimates, Iteris will be able to make updates and adjustments to offer its users better results in the future. The given user providing feedback must have write privileges for the field in which the field growth belongs.

Additional information related to feedback timestamp, growth feedback, and feedback stage is available in the Feedback Information section of the Appendix.

1.3.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/corn/growth/feedback/add/
{growth_id}/{timestamp}/{stage}?account_id={string}&user_id={string}
&app_id={string}&app_key={string}

1.3.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

1.3.3. Response Object

A string representing a feedback ID.

1.3.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/corn/growth/feedback/add/
xyz/1472688000/r6?account_id=abc&user_id=cba&app_id=123&app_key=321

1.3.5. Example Response

def-345

1.4. Corn Growth Feedbacks by Growth - v1.0

Returns a list of growth feedback activities associated with the target growth_id.

1.4.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/corn/growth/feedback/
get/by_growth/{growth_id}?app_id={string}&app_key={string}account_id={string}
&user_id={string}

1.4.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1.4.3. Response Object (JSON)

Field Description

user_id

User ID provided by and used with the Accounts API.

created

Timestamp denoting when the feedback was created.

data

Information pertaining to the activity.

subtype

Enumeration value representing the specific variety of the activity. Defaults to 0.

growth_feedback_id

ID of target growth feedback.

type

Enumeration value of plant.

feedback/date

Unix timestamp denoting when the feedback happened2.

feedback/stage

Stage provided as feedback.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

1.4.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/corn/growth/feedback/
get/by_growth/xyz?app_id=123&app_key=321&account_id=abc&user_id=cba

1.4.5. Example Response

[
    {
        "user_id":"1234",
        "feedback":{
            "date":1400371200,
            "type":51,
            "stage":"v1.0"
        },
        "created":1446229281,
        "data":"{}",
        "subtype":"0",
        "growth_feedback_id":"1111",
        "type":51
    },...
]

1.5. Corn Growth Modify Feedback - v1.0

The Corn Growth Modify Feedback endpoint allows users to modify previously provided growth stage estimate feedback. The given user providing feedback must have write privileges for the field in which the field growth belongs. At least one modification must be provided.

1.5.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/corn/growth/feedback/modify/
{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}&timestamp={integer}&stage={string}

1.5.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

1.5.3. Response Object

A string representing success (“true”) or failure (“false”).

1.5.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/corn/growth/feedback/
modify/abc-123?account_id=abc&user_id=cba&app_id=123&app_key=321
&timestamp=1472688000&stage=r6

1.5.5. Example Response

true

1.6. Corn Growth Delete Feedback - v1.0

This endpoint allows users to delete the previously provided growth stage estimate feedback. The given user deleting feedback must have write privileges for the field in which the field growth belongs.

1.6.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/corn/growth/feedback/
delete/{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}

1.6.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

1.6.3. Response Object

A string representing success (“true”) or failure (“false”).

1.6.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/corn/growth/
feedback/delete/abc-123?account_id=abc&user_id=cba
&app_id=123&app_key=321

1.6.5. Example Response

true

1.7. Corn In-Field Drydown - v1.0

Drawing from the ClearAg Field Weather API and corn growth model, the Corn In-Field Drydown endpoint simulates the drying process of corn grain in the field after the crop achieves full maturity, and provides daily grain moisture estimates during the drydown period. If Accounts API integration is used, any available moisture measurements are used to improve model results.

1.7.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/corn/infield_drydown?
app_id={string}&app_key={string}&location={lat, lon coordinates}
&plant_date={timestamp}&account_id={string}&user_id={string}&growth_id={string}
&relative_maturity={integer}

1.7.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

relative_maturity

integer

no

 — 

Classification indicating how early a variety matures. Valid values range from 70 to 130, with lower values indicating an “early” relative maturity and higher values indicating a “late” relative maturity. Default is 100.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

1.7.3. Response Object (JSON)

Field Description

attribution

Various model attributions.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum daily air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum daily air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures. Note that wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

advisor

Suggested field properties to check.

description

Text description for a stage.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Image URL.

name

Growth stage name.

order

Relative position of the stage within the growth scale.

1.7.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/corn/infield_drydown?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800

1.7.5. Example Response

{
    "attribution":[],
    "data":{
        "45,-97":{
            "2016-10-02":{
                "agdd":2303.5,
                "air_temp_max":62,
                "air_temp_min":40,
                "equilibrium_moisture_content":7.43,
                "gdd":6.0,
                "grain_moisture_content":30.92,
                "grain_moisture_content_change":-0.51
                "last_stage":"r6",
                "new_stage":"n/a"
            },...
        }
    },
    "harvest_window":{
        "end":"2016-10-19",
        "start":"2016-09-17"
    },
    "stage_descriptions":{
        "ve":{
            "advisor":"Nutrient",
            "description":"Emergence - VE (emergence) occurs when the coleoptile (spike) pushes through the soil surface. Corn plants can emerge within five days in ideal heat and moisture conditions. But in practice, due to early planting under seasonably cool conditions, at least two weeks are normally required from planting to emergence.",
            "images":[
                {
                    "attribution":"Courtesy of Agronomy Extension, Iowa State University.",
                    "caption":"Emergence",
                    "url":"https://.../Figure_12_ISUE300.jpg"
                },...
            ],
            "name":"VE - Emergence",
            "order":"1"
        },...
    }
}

1.8. Corn Nitrogen Advisor - v1.1

The ClearAg Corn Nitrogen Advisor simulates the various processes of the nitrogen cycle that impact the availability of nitrogen to corn crops. The model is based on a combination of proven algorithms from several industry models for simulating the nitrogen cycle. When used in combination with the Accounts API, the Corn Nitrogen Advisor allows provision of several types of field level activities, including fertilizer treatments and soil sample results, containing information such as soil nitrate and organic matter levels, as well as soil pH. Crop growth and the corresponding crop parameters of importance are simulated based on user-specified location, relative maturity, and planting date. Weather and soil information required by the Clear-N model are provided by the ClearAg Field Weather and Soil Conditions APIs, which provide a seamless global dataset of current, forecast, and historical conditions (dating back to 1980) for any arable location globally.

1.8.1. URL Description

http://ag.us.clearapis.com/v1.1/crop_health/corn/nutrient/nitrogen?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&location={lat, lon coordinates}&plant_date={timestamp}
&yield_goal={integer}&yield_goal_unit={string}&previous_crop={integer}
&previous_harvest_date={timestamp}&previous_yield={integer}
&previous_yield_unit={string}&output_unit={string}&year_offset={integer}
&relative_maturity={integer}

1.8.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Limited to a single location per query.

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the current crop was planted or the date of emergence2.

relative_maturity

integer

no

 — 

Classification indicating how early a variety matures. Valid values range from 70 to 130, with lower values indicating an “early” relative maturity and higher values indicating a “late” relative maturity. Default is 100.

yield_goal

integer

yes

yes

Target yield for current crop.

yield_goal_unit

string

yes

yes

Target yield unit. Accepted values are “lb/ac,” “kg/ha,” or “bu/ac”.

previous_crop

integer

no

no

Enumeration value of previous crop on field. Accepted values are currently 50 (barley), 51 (corn), 57 (spring wheat), 59 (canola), 65 (cotton), 66 (soybean), 68 (winter wheat), 69 (vegetable), 70 (sorghum), 71 (pea), 72 (sunflower), 73 (rice), and 74 (alfalfa).

previous_harvest_date

timestamp

no

no

Epoch timestamp valid near the time that the previous crop was harvested2. Required if previous crop is specified. May not predate the planting or emergence date by more than 366 days.

previous_yield

integer

no

no

Actual yield of the previous crop. Required if previous crop is specified.

previous_yield_ unit

string

no

no

Previous yield unit. Accepted values are “lb/ac,” “kg/ha,” or “bu/ac.” Required if previous crop is specified. Note that “bu/ac” is not a valid yield unit for alfalfa, cotton, or vegetable.

output_unit

string

yes

yes

Specifies the unit of the area density data displayed. Accepted values are “lb/ac” or “kg/ha.”

year_offset

integer

no

no

Specifies a number of years by which to adjust model results. Values must be less than 0.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

1.8.3. Response Object (JSON)

Field Description

fertilizer_treatment

Structure holding all fertilizer treatment data utilized by the nitrogen model, including the fertilizer type, application rate, and depth.

soil_sample

Structure holding all soil sample data utilized by the nitrogen model, including the soil nitrate content, organic matter content, pH level, and sample depth.

tillage

Structure holding all tillage data utilized by the nitrogen model, including the tillage type and depth.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum air temperature valid for the current date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the timeframe.

air_temp_min

Minimum air temperature valid for the current date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the timeframe.

gdd

Growing degree days accumulated on the current date.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

ammonium,
ammonium_XtoY

The amount of nitrogen in the form of ammonium within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters.

ammonium_in_last_sample_depth

The modeled amount of ammonium above the depth of the previous soil sample.

nitrate,
nitrate_XtoY

The amount of nitrogen in the form of nitrate within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters.

nitrate_in_last_sample_depth

The modeled amount of nitrate above the depth of the previous soil sample.

applied_fertilizers,
applied_fertilizers_XtoY

The amount of nitrogen applied as fertilizer resident within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters3.

denitrified,
denitrified_XtoY

The amount of soil nitrate lost from the entire 2-meter depth of the modeled soil profile, or from within the layer spanning from depth=X to depth=Y centimeters, due to the process of denitrification, whereby nitrate is converted into nitrogen gas and then escapes into the atmosphere3.

immobilized,
immobilized_XtoY

The amount of nitrogen that has been immobilized within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters, in order to support mineralization of the previous crop’s residues3.

leached,
leached_XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning from depth=X to depth=Y centimeters, due to the process of leaching. Only losses will normally be seen when aggregated across the entire depth of the modeled soil profile; otherwise, some layers may gain nitrate at the expense of others, due to the vertical movement of water within the soil profile3.

leached_below_current_root_depth

The amount of soil nitrate that has been leached below the depth of the current crop’s roots as of the indicated date3.

leached_below_maximum_root_depth

The amount of soil nitrate that has been leached below the maximum depth that the current crop’s roots are expected to reach during the entirety of its growth cycle3.

realized_from_crop_organic_matter,
realized_from_crop_organic_matter_ XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, due to the process of mineralization of residues associated with the previous crop. This can be either positive or negative, depending on the carbon to nitrogen ratio of the previous crop’s residues3.

realized_from_soil_organic_matter,
realized_from_soil_organic_matter_ XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, due to the process of mineralization of soil organic matter. Since the carbon to nitrogen ratio of soil organic matter is typically below that associated with the diet of soil microbes, values will normally be positive3.

uptaken_by_crop,
uptaken_by_crop_XtoY

The amount of nitrogen uptaken by the crop from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters. If less than uptaken_by_crop_optimal, this can be indicative of a risk that the crop may be short of nitrogen3.

uptaken_by_crop_optimal,
uptaken_by_crop_optimal_XtoY

The amount of nitrogen the crop would have ideally taken up from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters3.

volatized,
volatized_XtoY

The amount of nitrogen lost by the process of volatization (also referred to as volatilization) from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, whereby urea fertilizer is converted into ammonia gas and then escapes into the atmosphere3.

applied_use_efficiency

The crop’s use efficiency of fertilizer-based nitrogen applied since the harvest of the previous crop. Values will be less than or equal to 100%, with higher percentages indicating that the crop has (or will) use a higher percentage of the fertilizers that have been applied.

applied_use_efficiency_unit

Units of “applied_use_efficiency.”

current_root_depth

The depth to which the current crop’s roots are assumed to reach as of the indicated date.

current_root_depth_unit

Units of “current_root_depth”. Chosen automatically based on the user-provided input value of “output_unit.”

indigenous_use_efficiency

The crop’s use efficiency of nitrogen realized through organic matter mineralization since the harvest of the previous crop. Values are in percentages, with higher percentages indicating that the crop has (or will) use a higher percentage of the nitrogen that has been realized through organic matter mineralization. Values in excess of 100% are possible.

indigenous_use_efficiency_unit

Units of “indigenous_use_efficiency.”

maximum_root_depth

The maximum depth to which the current crop’s roots are expected to reach during the entirety of its growth cycle.

maximum_root_depth_unit

Units of “maximum_root_depth.” Chosen automatically based on the user-provided input value of “output_unit.”

nitrogen_available_unit

Units of all data values in the “nitrogen_available” subsection of the returned JSON object.

nitrogen_budget_unit

Units of all data values in the “nitrogen_budget” subsection of the returned JSON object.

notes

A dictionary containing textual descriptions of noteworthy problems or occurrences on the indicated date.

uptake_score

A 0-100 score quantifying the adequacy of crop nitrogen uptake relative to the goals specified in the API call. Higher values indicate better uptake, with values at or near 100 being desirable in order to optimize the crop’s prospects for achieving the caller-specified yield_goal.

uptake_score_unit

Units of “uptake_score.”

advisor

Suggested field properties to check.

description

Text description for a growth stage.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Image URL.

name

Growth stage name.

order

Relative position of a stage within the growth scale.

3 Positive numeric values indicate that nitrogen has been gained by the soil due to the associated process, whereas negative numeric values indicate that nitrogen has been lost by the soil due to the associated process.

1.8.4. Example Request

http://ag.us.clearapis.com/v1.1/crop_health/corn/nutrient/nitrogen?
app_id=123&app_key=321&account_id=abc&user_id=cba&growth_id=xyz
&previous_harvest_date=1450757200&previous_crop=51&previous_yield=1000
&previous_yield_unit=kg/ha&yield_goal=1050&yield_goal_unit=kg/ha
&output_unit=kg/ha

1.8.5. Example Response

{
    "activities":{
        "fertilizer_treatment":{
            "2016-05-20":[{
                "depth":0.5,
                "depth_unit":"m",
                "fertilizer_id":11,
                "rate":1.0,
                "rate_unit":"lb/ac"
            }]
        },
        "soil_sample":{
            "2016-05-20":[{
                "depth_unit":"m",
                "end_depth":1.0,
                "nitrate":3.0,
                "nitrate_unit":"kg/ha",
                "organic_matter":"n/a",
                "ph":"n/a",
                "start_depth":0.5
            }]
        },
        "tillage":{}
    },
    "data":{
        "2016-05-24":{
            "agdd":533.0,
            "air_temp_max":73.0,
            "air_temp_min":50.0,
            "gdd":11.5,
            "last_stage":"v3",
            "new_stage":"n/a",
            "nitrogen_available":{
                "ammonium":0.0,
                "ammonium_0to2":0.0,
                "ammonium_100to200":0.0,
                "ammonium_10to20":0.0,
                "ammonium_20to40":0.0,
                "ammonium_2to5":0.0,
                "ammonium_40to70":0.0,
                "ammonium_5to10":0.0,
                "ammonium_70to100":0.0,
                "ammonium_in_last_sample_depth":0.0,
                "nitrate":53.3,
                "nitrate_0to2":0.0,
                "nitrate_100to200":0.0,
                "nitrate_10to20":12.9,
                "nitrate_20to40":26.1,
                "nitrate_2to5":0.1,
                "nitrate_40to70":11.0,
                "nitrate_5to10":1.4,
                "nitrate_70to100":1.7,
                "nitrate_in_last_sample_depth":0.0
            },
            "nitrogen_budget":{
                "applied_fertilizers":0.0,
                "applied_fertilizers_0to2":0.0,
                "applied_fertilizers_100to200":0.0,
                "applied_fertilizers_10to20":0.0,
                "applied_fertilizers_20to40":0.0,
                "applied_fertilizers_2to5":0.0,
                "applied_fertilizers_40to70":0.0,
                "applied_fertilizers_5to10":0.0,
                "applied_fertilizers_70to100":0.0,
                "denitrified":0.0,
                "denitrified_0to2":0.0,
                "denitrified_100to200":0.0,
                "denitrified_10to20":0.0,
                "denitrified_20to40":0.0,
                "denitrified_2to5":0.0,
                "denitrified_40to70":0.0,
                "denitrified_5to10":0.0,
                "denitrified_70to100":0.0,
                "immobilized":-2.3,
                "immobilized_0to2":-0.8,
                "immobilized_100to200":-0.1,
                "immobilized_10to20":0.0,
                "immobilized_20to40":0.0,
                "immobilized_2to5":-1.2,
                "immobilized_40to70":-0.1,
                "immobilized_5to10":0.0,
                "immobilized_70to100":-0.1,
                "leached":0.0,
                "leached_0to2":-3.9,
                "leached_100to200":0.1,
                "leached_10to20":-0.3,
                "leached_20to40":4.5,
                "leached_2to5":-3.5,
                "leached_40to70":7.6,
                "leached_5to10":-6.2,
                "leached_70to100":1.7,
                "leached_below_current_root_depth":-8.1,
                "leached_below_maximum_root_depth":0.0,
                "realized_from_crop_organic_matter":0.0,
                "realized_from_crop_organic_matter_0to2":0.0,
                "realized_from_crop_organic_matter_100to200":0.0,
                "realized_from_crop_organic_matter_10to20":0.0,
                "realized_from_crop_organic_matter_20to40":0.0,
                "realized_from_crop_organic_matter_2to5":0.0,
                "realized_from_crop_organic_matter_40to70":0.0,
                "realized_from_crop_organic_matter_5to10":0.0,
                "realized_from_crop_organic_matter_70to100":0.0,
                "realized_from_soil_organic_matter":7.0,
                "realized_from_soil_organic_matter_0to2":0.8,
                "realized_from_soil_organic_matter_100to200":0.0,
                "realized_from_soil_organic_matter_10to20":1.9,
                "realized_from_soil_organic_matter_20to40":1.8,
                "realized_from_soil_organic_matter_2to5":1.0,
                "realized_from_soil_organic_matter_40to70":0.2,
                "realized_from_soil_organic_matter_5to10":1.4,
                "realized_from_soil_organic_matter_70to100":0.0,
                "uptaken_by_crop":-1.4,
                "uptaken_by_crop_0to2":0.0,
                "uptaken_by_crop_100to200":0.0,
                "uptaken_by_crop_10to20":-0.7,
                "uptaken_by_crop_20to40":-0.2,
                "uptaken_by_crop_2to5":-0.1,
                "uptaken_by_crop_40to70":0.0,
                "uptaken_by_crop_5to10":-0.4,
                "uptaken_by_crop_70to100":0.0,
                "uptaken_by_crop_optimal":-2.1,
                "uptaken_by_crop_optimal_0to2":0.0,
                "uptaken_by_crop_optimal_100to200":0.0,
                "uptaken_by_crop_optimal_10to20":-0.8,
                "uptaken_by_crop_optimal_20to40":-0.2,
                "uptaken_by_crop_optimal_2to5":-0.3,
                "uptaken_by_crop_optimal_40to70":0.0,
                "uptaken_by_crop_optimal_5to10":-0.6,
                "uptaken_by_crop_optimal_70to100":0.0,
                "volatized":-0.6,
                "volatized_0to2":-0.1,
                "volatized_100to200":0.0,
                "volatized_10to20":0.0,
                "volatized_20to40":0.0,
                "volatized_2to5":-0.2,
                "volatized_40to70":0.0,
                "volatized_5to10":-0.3,
                "volatized_70to100":0.0
            },
            "nitrogen_metadata":{
                "applied_use_efficiency":16.7,
                "applied_use_efficiency_unit":"%",
                "current_root_depth":49.0,
                "current_root_depth_unit":"cm",
                "indigenous_use_efficiency":20.2,
                "indigenous_use_efficiency_unit":"%",
                "maximum_root_depth":149.0,
                "maximum_root_depth_unit":"cm",
                "nitrogen_available_unit":"kg/ha",
                "nitrogen_budget_unit":"kg/ha",
                "notes":{},
                "uptake_score":99.8,
                "uptake_score_unit":"%"
            }
        },...
    },
    "stage_descriptions":{
        "v3":{
            "advisor":"Nutrient",
            "description":"The plant has three leaves with visible collars. The stalk hasn't increased much in length. The growing point is still below the surface.",
            "images":[
                {
                    "attribution":"Courtesy of Agronomy Extension, Iowa State University.",
                    "caption":"V3 stage",
                    "url":"https://.../Figure_16_ISUE300.jpg"
                },...
            ],
            "name":"V3 - 3 Leaves",
            "order":"3"
        },...
    }
}

1.9. Corn Mechanical Drying - v1.0

The Corn Mechanical Drying endpoint simulates the drydown process of corn using either fan-powered low-temperature drying or burner-driven high-temperature drying facilities to provide drying statistics and cost projections. The mechanical drying process is simulated using up to 10 future days of grain moisture estimates. Results from the corn in-field drying model are also returned for comparison.

Note that a field, growth, and drying facility are required to utilize this feature. Any available grain moisture measurements are used to improve model results.

Please be aware that mechanical drying data will not be returned if grain moisture estimates are unable to be obtained from the corn in-field drying model. This may occur if one of the following conditions are met:

  • The corn growth model simulation does not bring the crop to maturity. This is more likely to occur for certain location (e.g., cooler climates) and relative maturity combinations.

  • The crop planting date or emergence date are too far in the past. The models are designed for future planning; users can utilize the “current_date” argument to determine what model results could have been on a past date. These results can be different than what would have been seen on the emulated date, as the forecast timeframes are now represented by historical data.

1.9.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/corn/mechanical_drying?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&drying_facility_ids={string}&grain_unit={string}
&target_moisture_content_wb={float}&current_date={timestamp}

1.9.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Accounts API ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have read privileges for the field in which the growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field.

target_moisture_ content_wb

float

yes

Numeric representation of the desired moisture level for safe storage, measured in percent on a wet basis. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

grain_unit

string

yes

Units to use when returning unit costs of drying. Valid values are “bu” (bushel) and “mt” (metric ton).

drying_facility_ids

string

no

Comma-delimited list of drying facility IDs to be used. Currently, only the most recently created facility in the list will be used. Default behavior is to use the most recently created facility overall. Note that the calling user must have at least read privileges for the asset (drying facility).

current_date

timestamp

no

Emulate model results as if viewed on this date2. Useful for viewing approximate model results for historical timeframes greater than one year in the past. There can be differences in results due to what would have been forecasted weather data now being replaced with historical or climatological data used in the calculations.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

1.9.3. Response Object (JSON)

Field Description

asset_id

The ID given to a particular drying facility.

name

The user-provided name of the drying facility. If this is not supplied, a generic name of “Drying Facility” followed by a number is used.

burner_fuel_type

Type of fuel consumed by the burner, as provided by the Accounts API.

burner_fuel_unit

Unit of measure associated with the fuel type, as provided by the Accounts API.

driest_datetime

Time that the grain reached its lowest moisture content of the model run. Represented by a date string in the case of low-temperature drying or hours and minutes in the case of high-temperature drying. Note that the simulation will stop when the user-specified target moisture content is reached, in which case this will indicate the timing of the grain reaching that threshold.

driest_moisture_content_db

Driest dry-basis grain moisture content of the simulation, in percent. Dry-basis moisture content is defined as the ratio of the mass of water to the dry mass of a sample of grain.

driest_moisture_content_wb

Driest wet-basis grain moisture content of the simulation, in percent. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

dryer_throughput_grain_units _per_hour

Amount of grain dried per hour. Applicable only in high-temperature drying facilities.

drying_time

Amount of time, in seconds, that elapsed for the grain to reach its lowest moisture content.

grain_storability

Likelihood of spoilage. Possible values include “0,” indicating that grain is not likely to spoil; “1,” indicating a marginal risk; and “2,” warning that spoilage is likely; and “n/a” when high-temperature drying is in use.

grain_unit

Unit of measure associated with the volume of grain as provided by the user.

per_grain_unit/burner_fuel_ cost

Expected burner fuel cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/burner_ fuel_units_consumed

Expected amount of fuel consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/burner_kwh_ consumed

Expected amount of fuel energy, in kilowatt-hours, consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/electricity_cost

Expected electricity cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/electricity_kwh_ consumed

Expected amount of electrical energy, in kilowatt-hours, consumed by the fan per unit of grain, in the grain unit provided by the user.

per_grain_unit/total_cost

Expected total drying cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit_per_percent_ moisture/total_cost

Expected total drying cost per unit of grain per percent moisture change, in the user’s local currency, and in the grain unit provided by the user.

sample_datetime

Valid time of the grain moisture sample provided by the in-field drydown model.

sample_moisture_content_wb

Starting wet-basis moisture content of the grain sample, in percent, provided by the in-field drydown model.

simulation_length

Total length of time, in seconds, over which the drydown process was modeled.

target_moisture_reached

Flag indicating whether the target storage moisture content is reached in the simulation, where “1” indicates that the storage moisture is reached and “0” indicates that it is not. Primarily applicable in low-temperature drying facilities, where ambient environmental conditions may not permit an adequate amount of drying.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum daily air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum daily air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

1.9.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/corn/mechanical_drying?
app_id=123&app_key=321&account_id=abc&user_id=cba&growth_id=xyz
&grain_unit=bu&target_moisture_content_wb=14.5

1.9.5. Example Response

{
    "drying_facilities":[
        {
            "asset_id":"abc-123",
            "data":[
                {
                    "burner_fuel_type":"liquid_propane",
                    "burner_fuel_unit":"gallon",
                    "driest_datetime":"03:16",
                    "driest_moisture_content_db":16.9,
                    "driest_moisture_content_wb":14.46,
                    "dryer_throughput_grain_units_per_hour":433.0,
                    "drying_time":11790,
                    "grain_storability":"n/a",
                    "grain_unit":"bu",
                    "per_grain_unit":{
                        "burner_fuel_cost":0.265,
                        "burner_fuel_units_consumed":0.294,
                        "burner_kwh_consumed":7.27,
                        "electricity_cost":0.186,
                        "electricity_kwh_consumed":0.37,
                        "total_cost":0.451
                    },
                    "per_grain_unit_per_percent_moisture":{
                        "total_cost":0.027
                    },
                    "sample_datetime":"2016-09-12",
                    "sample_moisture_content_wb":31.02,
                    "simulation_length":11790,
                    "target_moisture_reached":1
                },...
            ],
            "name":"Neco 24180"
        }
    ],
    "infield_drydown_data":{
        "47,-97":{
            "2016-09-12":{
                "agdd":2392.5,
                "air_temp_max":72.0,
                "air_temp_min":50.0,
                "equilibrium_moisture_content":10.39,
                "gdd":11.0,
                "grain_moisture_content":31.02,
                "grain_moisture_content_change":"n/a",
                "last_stage":"r5",
                "new_stage":"r6"
            },...
        }
    }
}

2. Spring Wheat

2.1. Spring Wheat Growth - v1.0

Leveraging Iteris’ spring wheat growth stage model, the Spring Wheat Growth endpoint allows users to model the maturation and development of spring wheat crops. Users may also take advantage of Accounts API integration to provide crop growth feedback and optimize model results.

2.1.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/growth?app_id={string}
&app_key={string}&location={lat, lon coordinates}&plant_date={timestamp}
&days={integer}&account_id={string}&user_id={string}&growth_id={string}
&relative_maturity={string}&scale={string}

2.1.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” “medium,” “medium-late,” and “late.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

scale

string

no

no

Specifies which growth scale the response will display. Valid values include “feekes,” “haun,” and “zadoks.” Default behavior is to utilize a unified scale and display the equivalent stages from all three scales in the response.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

2.1.3. Response Object (JSON)

Field Description

gdd

Growing degree days accumulated on the current date.

agdd

Aggregate growing degree days from plant date, including the current period’s date.

air_temp_min

Minimum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

air_temp_max

Maximum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

last_stage

The last known growth stage. If no valid stage has been reached, this value will be “n/a.” This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

new_stage

The crop is expected to have entered a new stage between the current period’s date and the previous period’s date.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

advisor

Suggested field properties to check.

description

Text description for a stage.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

2.1.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/growth?app_id=123&app_key=321
&location=47,-97&plant_date=1462060800&days=160

2.1.5. Example Response

{
    "data":{
        "47,-97":{
            "2016-07-31":{
                "agdd":2432.5,
                "air_temp_max":74.0,
                "air_temp_min":64.0,
                "gdd":37.0,
                "last_stage":"20",
                "new_stage":"21"
            },...
        }
    },
    "harvest_window":{
        "end":"2016-08-16",
        "start":"2016-07-25"
    },
    "stage_descriptions":{
        "11.3":{
            "advisor":"Harvest",
            "description":"Physiological maturity"
        },...
    }
}

2.2. Spring Wheat Growth with GDD Envelope - v1.0

The Spring Wheat Growth with GDD Envelope service provides spring wheat growth information in addition to GDD envelope data. GDD envelope calculation begins from either the current day, or the planted/emergence date, whichever is further in the future. The envelope is constructed by compiling the previous 10 years of weather data, and simulating the maximum and minimum GDD that would have accumulated within those 10 years for each date. The calculated minimum and maximum values are then added to the current start of calculation date AGDD going onwards to show range of possibilities.

2.2.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/growth/
gdd_envelope?app_id={string}&app_key={string}&plant_date={timestamp}
&location={lat, lon coordinates}&days={integer}&account_id={string}
&user_id={string}&growth_id={string}
&relative_maturity={string}&scale={string}

2.2.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” “medium,” “medium-late,” and “late.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

scale

string

no

no

Specifies which growth scale the response will display. Valid values include “feekes,” “haun,” and “zadoks.” Default behavior is to utilize a unified scale and display the equivalent stages from all three scales in the response.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

2.2.3. Response Object (JSON)

Field Description

gdd

Growing degree days accumulated on the current date.

agdd

Aggregate growing degree days from plant date, including the current period’s date.

air_temp_min

Minimum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

air_temp_max

Maximum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

last_stage

The last known growth stage. If no valid stage has been reached, this value will be “n/a.” This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

new_stage

The crop is expected to have entered a new stage between the current period’s date and the previous period’s date.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

advisor

Suggested field properties to check.

description

Text description for a stage.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

agdd_envelope_max

Maximum observed agdd during the the previous 10 years.

agdd_envelope_min

Minimum observed agdd during the the previous 10 years.

agdd_envelope_min_year

Year that the agdd_envelope_min was observed.

agdd_envelope_max_year

Year that the agdd_envelope_max was observed.

2.2.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/growth/gdd_envelope?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800&days=160

2.2.5. Example Response

{
    "data":{
        "32.509761735919426,-96.85546875":{
            "2016-10-20":{
                "agdd":111.5,
                "agdd_envelope_max":111.5,
                "agdd_envelope_max_year":"2015",
                "agdd_envelope_min":111.5,
                "agdd_envelope_min_year":"2015",
                "air_temp_max":75.0,
                "air_temp_min":60.0,
                "gdd":33.0,
                "last_stage":"n/a",
                "new_stage":"n/a"
            },...
        }
    },
    "harvest_window":{
        "end":"n/a",
        "start":"n/a"
    },
    "stage_descriptions":{
        "1":{
            "advisor":"Nutrient",
            "description":"The first leaf is at half of its final length."
        },...
    }
}

2.3. Spring Wheat Growth Add Feedback - v1.0

By providing feedback relating to the growth stage estimates, Iteris will be able to make updates and adjustments to offer its users better results in the future. The given user providing feedback must have write privileges for the field in which the field growth belongs.

Additional information related to feedback timestamp, growth feedback, and feedback stage is available in the Feedback Information section of the Appendix.

2.3.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/growth/feedback/add/
{growth_id}/{timestamp}/{stage}?account_id={string}&user_id={string}
&app_id={string}&app_key={string}

2.3.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

2.3.3. Response Object

A string representing a feedback ID.

2.3.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/growth/feedback/add/
xyz/1472688000/121?account_id=abc&user_id=cba&app_id=123&app_key=321

2.3.5. Example Response

def-345

2.4. Spring Wheat Growth Feedbacks by Growth - v1.1

Returns a list of growth feedback activities associated with the target growth_id.

2.4.1. URL Description

http://ag.us.clearapis.com/v1.1/crop_health/springwheat/growth/feedback/
get/by_growth/{growth_id}?app_id={string}&app_key={string}account_id={string}
&user_id={string}

2.4.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

2.4.3. Response Object (JSON)

Field Description

user_id

User ID provided by and used with the Accounts API.

created

Timestamp denoting when the feedback was created.

data

Information pertaining to the activity.

subtype

Enumeration value representing the specific variety of the activity. Defaults to 0.

growth_feedback_id

ID of target growth feedback.

type

Enumeration value of plant.

feedback/date

Unix timestamp denoting when the feedback happened2.

feedback/stage

Stage provided as feedback.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

2.4.4. Example Request

http://ag.us.clearapis.com/v1.1/crop_health/springwheat/growth/feedback/
get/by_growth/xyz?app_id=123&app_key=321&account_id=abc&user_id=cba

2.4.5. Example Response

[
    {
        "user_id":"1234",
        "feedback":{
            "date":1400371200,
            "type":57,
            "stage":"101"
        },
        "created":1446229281,
        "data":"{}",
        "subtype":"0",
        "growth_feedback_id":"1111",
        "type":57
    },...
]

2.5. Spring Wheat Growth Modify Feedback - v1.0

The Spring Wheat Growth Modify Feedback endpoint allows users to modify previously provided growth stage estimate feedback. The given user providing feedback must have write privileges for the field in which the field growth belongs. At least one modification must be provided.

2.5.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/growth/feedback/modify/
{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}&timestamp={integer}&stage={string}

2.5.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

2.5.3. Response Object

A string representing success (“true”) or failure (“false”).

2.5.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/growth/feedback/
modify/abc-123?account_id=abc&user_id=cba&app_id=123&app_key=321
&timestamp=1472688000&stage=121

2.5.5. Example Response

true

2.6. Spring Wheat Growth Delete Feedback - v1.0

This endpoint allows users to delete the previously provided growth stage estimate feedback. The given user deleting feedback must have write privileges for the field in which the field growth belongs.

2.6.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/growth/feedback/
delete/{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}

2.6.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

2.6.3. Response Object

A string representing success (“true”) or failure (“false”).

2.6.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/growth/
feedback/delete/abc-123?account_id=abc&user_id=cba
&app_id=123&app_key=321

2.6.5. Example Response

true

2.7. Spring Wheat In-Field Drydown - v1.0

Drawing from the ClearAg Field Weather API and spring wheat growth model, the Spring Wheat In-Field Drydown endpoint simulates the drying process of spring wheat grain in the field after the crop achieves full maturity, and provides daily grain moisture estimates during the drydown period. If Accounts API integration is used, any available moisture measurements are used to improve model results.

2.7.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/infield_drydown?
app_id={string}&app_key={string}&location={lat, lon coordinates}
&plant_date={timestamp}&account_id={string}&user_id={string}&growth_id={string}
&relative_maturity={string}&scale={string}

2.7.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” “medium,” “medium-late,” and “late.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

scale

string

no

no

Specifies which growth scale the response will display. Valid values include “feekes,” “haun,” and “zadoks.” Default behavior is to utilize a unified scale and display the equivalent stages from all three scales in the response.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

2.7.3. Response Object (JSON)

Field Description

attribution

Various model attributions.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures. Note that wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

advisor

Suggested field properties to check.

applicable_scales

Container for the equivalent stage within the Feekes, Haun, and/or Zadoks growth scales.

description

Text description for a stage.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Image URL.

name

Growth stage name.

order

Relative position of the stage within the growth scale.

2.7.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/infield_drydown?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800

2.7.5. Example Response

{
    "attribution":[
        "Model based on a model presented by the North Dakota Agricultural Weather Network, but substantially modified."
    ],
    "data":{
        "39.26628442213066,-103.1396484375":{
            "2016-08-11":{
                "agdd":4491.5,
                "air_temp_max":86.0,
                "air_temp_min":58.0,
                "equilibrium_moisture_content":6.68,
                "gdd":40.0,
                "grain_moisture_content":6.57,
                "grain_moisture_content_change":0.02,
                "last_stage":"20",
                "new_stage":"n/a"
            },...
        }
    },
    "harvest_window":{
        "end":"2016-10-12",
        "start":"2016-09-17"
    },
    "stage_descriptions":{
        "101":{
            "advisor":"Nutrient",
            "applicable_scales":{
                "feekes":"1",
                "haun":"0.5",
                "zadoks":"10"
            },
            "description":"The first leaf is at half of its final length.",
            "images":[
                {
                    "attribution":"Courtesy of David L. Hansen, University of Minnesota.",
                    "caption":"Emergence",
                    "url":"https://.../Coleoptile.jpg"
                },...
            ],
            "name":"Emergence",
            "order":"1"
        },...
    }
}

2.8. Spring Wheat Nitrogen Advisor - v1.0

The ClearAg Spring Wheat Nitrogen Advisor simulates the various processes of the nitrogen cycle that impact the availability of nitrogen to spring wheat crops. The model is based on a combination of proven algorithms from several industry models for simulating the nitrogen cycle. When used in combination with the Accounts API, the Spring Wheat Nitrogen Advisor allows provision of several types of field level activities, including fertilizer treatments and soil sample results, containing information such as soil nitrate and organic matter levels, as well as soil pH. Crop growth and the corresponding crop parameters of importance are simulated based on user-specified location, relative maturity, and planting date. Weather and soil information required by the Clear-N model are provided by the ClearAg Field Weather and Soil Conditions APIs, which provide a seamless global dataset of current, forecast, and historical conditions (dating back to 1980) for any arable location globally.

2.8.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/nutrient/nitrogen?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&location={lat, lon coordinates}&plant_date={timestamp}
&yield_goal={integer}&yield_goal_unit={string}&previous_crop={integer}
&previous_harvest_date={timestamp}&previous_yield={integer}
&previous_yield_unit={string}&output_unit={string}&year_offset={integer}
&relative_maturity={string}

2.8.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Limited to a single location per query.

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the current crop was planted or the date of emergence2.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” “medium,” “medium-late,” and “late.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

yield_goal

integer

yes

yes

Target yield for current crop.

yield_goal_unit

string

yes

yes

Target yield unit. Accepted values are “lb/ac,” “kg/ha,” or “bu/ac”.

previous_crop

integer

no

no

Enumeration value of previous crop on field. Accepted values are currently 50 (barley), 51 (corn), 57 (spring wheat), 59 (canola), 65 (cotton), 66 (soybean), 68 (winter wheat), 69 (vegetable), 70 (sorghum), 71 (pea), 72 (sunflower), 73 (rice), and 74 (alfalfa).

previous_harvest_date

timestamp

no

no

Epoch timestamp valid near the time that the previous crop was harvested2. Required if previous crop is specified. May not predate the planting or emergence date by more than 366 days.

previous_yield

integer

no

no

Actual yield of the previous crop. Required if previous crop is specified.

previous_yield_ unit

string

no

no

Previous yield unit. Accepted values are “lb/ac,” “kg/ha,” or “bu/ac.” Required if previous crop is specified. Note that “bu/ac” is not a valid yield unit for alfalfa, cotton, or vegetable.

output_unit

string

yes

yes

Specifies the unit of the area density data displayed. Accepted values are “lb/ac” or “kg/ha.”

year_offset

integer

no

no

Specifies a number of years by which to adjust model results. Values must be less than 0.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

2.8.3. Response Object (JSON)

Field Description

fertilizer_treatment

Structure holding all fertilizer treatment data utilized by the nitrogen model, including the fertilizer type, application rate, and depth.

soil_sample

Structure holding all soil sample data utilized by the nitrogen model, including the soil nitrate content, organic matter content, pH level, and sample depth.

tillage

Structure holding all tillage data utilized by the nitrogen model, including the tillage type and depth.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum air temperature valid for the current date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the timeframe.

air_temp_min

Minimum air temperature valid for the current date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the timeframe.

gdd

Growing degree days accumulated on the current date.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

ammonium,
ammonium_XtoY

The amount of nitrogen in the form of ammonium within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters.

ammonium_in_last_sample_depth

The modeled amount of ammonium above the depth of the previous soil sample.

nitrate,
nitrate_XtoY

The amount of nitrogen in the form of nitrate within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters.

nitrate_in_last_sample_depth

The modeled amount of nitrate above the depth of the previous soil sample.

applied_fertilizers,
applied_fertilizers_XtoY

The amount of nitrogen applied as fertilizer resident within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters3.

denitrified,
denitrified_XtoY

The amount of soil nitrate lost from the entire 2-meter depth of the modeled soil profile, or from within the layer spanning from depth=X to depth=Y centimeters, due to the process of denitrification, whereby nitrate is converted into nitrogen gas and then escapes into the atmosphere3.

immobilized,
immobilized_XtoY

The amount of nitrogen that has been immobilized within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters, in order to support mineralization of the previous crop’s residues3.

leached,
leached_XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning from depth=X to depth=Y centimeters, due to the process of leaching. Only losses will normally be seen when aggregated across the entire depth of the modeled soil profile; otherwise, some layers may gain nitrate at the expense of others, due to the vertical movement of water within the soil profile3.

leached_below_current_root_depth

The amount of soil nitrate that has been leached below the depth of the current crop’s roots as of the indicated date3.

leached_below_maximum_root_depth

The amount of soil nitrate that has been leached below the maximum depth that the current crop’s roots are expected to reach during the entirety of its growth cycle3.

realized_from_crop_organic_matter,
realized_from_crop_organic_matter_ XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, due to the process of mineralization of residues associated with the previous crop. This can be either positive or negative, depending on the carbon to nitrogen ratio of the previous crop’s residues3.

realized_from_soil_organic_matter,
realized_from_soil_organic_matter_ XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, due to the process of mineralization of soil organic matter. Since the carbon to nitrogen ratio of soil organic matter is typically below that associated with the diet of soil microbes, values will normally be positive3.

uptaken_by_crop,
uptaken_by_crop_XtoY

The amount of nitrogen uptaken by the crop from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters. If less than uptaken_by_crop_optimal, this can be indicative of a risk that the crop may be short of nitrogen3.

uptaken_by_crop_optimal,
uptaken_by_crop_optimal_XtoY

The amount of nitrogen the crop would have ideally taken up from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters3.

volatized,
volatized_XtoY

The amount of nitrogen lost by the process of volatization (also referred to as volatilization) from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, whereby urea fertilizer is converted into ammonia gas and then escapes into the atmosphere3.

applied_use_efficiency

The crop’s use efficiency of fertilizer-based nitrogen applied since the harvest of the previous crop. Values will be less than or equal to 100%, with higher percentages indicating that the crop has (or will) use a higher percentage of the fertilizers that have been applied.

applied_use_efficiency_unit

Units of “applied_use_efficiency.”

current_root_depth

The depth to which the current crop’s roots are assumed to reach as of the indicated date.

current_root_depth_unit

Units of “current_root_depth.” Chosen automatically based on the user-provided input value of “output_unit”.

indigenous_use_efficiency

The crop’s use efficiency of nitrogen realized through organic matter mineralization since the harvest of the previous crop. Values are in percentages, with higher percentages indicating that the crop has (or will) use a higher percentage of the nitrogen that has been realized through organic matter mineralization. Values in excess of 100% are possible.

indigenous_use_efficiency_unit

Units of “indigenous_use_efficiency.”

maximum_root_depth

The maximum depth to which the current crop’s roots are expected to reach during the entirety of its growth cycle.

maximum_root_depth_unit

Units of “maximum_root_depth.” Chosen automatically based on the user-provided input value of “output_unit.”

nitrogen_available_unit

Units of all data values in the “nitrogen_available” subsection of the returned JSON object.

nitrogen_budget_unit

Units of all data values in the “nitrogen_budget” subsection of the returned JSON object.

notes

A dictionary containing textual descriptions of noteworthy problems or occurrences on the indicated date.

uptake_score

A 0-100 score quantifying the adequacy of crop nitrogen uptake relative to the goals specified in the API call. Higher values indicate better uptake, with values at or near 100 being desirable in order to optimize the crop’s prospects for achieving the caller-specified yield_goal.

uptake_score_unit

Units of “uptake_score.”

advisor

Suggested field properties to check.

applicable_scales

Container for the equivalent stage within the Feekes, Haun, and Zadoks growth scales.

description

Text description for a growth stage.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Image URL.

name

Growth stage name.

order

Relative position of a stage within the growth scale.

3 Positive numeric values indicate that nitrogen has been gained by the soil due to the associated process, whereas negative numeric values indicate that nitrogen has been lost by the soil due to the associated process.

2.8.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/nutrient/nitrogen?
app_id=123&app_key=321&account_id=abc&user_id=cba&growth_id=xyz
&previous_harvest_date=1450757200&previous_crop=51&previous_yield=1000
&previous_yield_unit=kg/ha&yield_goal=1050&yield_goal_unit=kg/ha
&output_unit=kg/ha

2.8.5. Example Response

{
    "activities":{
        "fertilizer_treatment":{
            "2016-05-20":[{
                "depth":0.5,
                "depth_unit":"m",
                "fertilizer_id":11,
                "rate":1.0,
                "rate_unit":"lb/ac"
            }]
        },
        "soil_sample":{
            "2016-05-20":[{
                "depth_unit":"m",
                "end_depth":1.0,
                "nitrate":3.0,
                "nitrate_unit":"kg/ha",
                "organic_matter":"n/a",
                "ph":"n/a",
                "start_depth":0.5
            }]
        },
        "tillage":{
            "2016-05-21":{
                "depth":0.1,
                "depth_unit":"m",
                "type":"conventional"
            }
        }
    },
    "data":{
        "2016-05-24":{
            "agdd":533.0,
            "air_temp_max":73.0,
            "air_temp_min":50.0,
            "gdd":11.5,
            "last_stage":"101",
            "new_stage":"n/a",
            "nitrogen_available":{
                "ammonium":0.0,
                "ammonium_0to2":0.0,
                "ammonium_100to200":0.0,
                "ammonium_10to20":0.0,
                "ammonium_20to40":0.0,
                "ammonium_2to5":0.0,
                "ammonium_40to70":0.0,
                "ammonium_5to10":0.0,
                "ammonium_70to100":0.0,
                "ammonium_in_last_sample_depth":0.0,
                "nitrate":53.3,
                "nitrate_0to2":0.0,
                "nitrate_100to200":0.0,
                "nitrate_10to20":12.9,
                "nitrate_20to40":26.1,
                "nitrate_2to5":0.1,
                "nitrate_40to70":11.0,
                "nitrate_5to10":1.4,
                "nitrate_70to100":1.7,
                "nitrate_in_last_sample_depth":0.0
            },
            "nitrogen_budget":{
                "applied_fertilizers":0.0,
                "applied_fertilizers_0to2":0.0,
                "applied_fertilizers_100to200":0.0,
                "applied_fertilizers_10to20":0.0,
                "applied_fertilizers_20to40":0.0,
                "applied_fertilizers_2to5":0.0,
                "applied_fertilizers_40to70":0.0,
                "applied_fertilizers_5to10":0.0,
                "applied_fertilizers_70to100":0.0,
                "applied_use_efficiency":"n/a",
                "denitrified":0.0,
                "denitrified_0to2":0.0,
                "denitrified_100to200":0.0,
                "denitrified_10to20":0.0,
                "denitrified_20to40":0.0,
                "denitrified_2to5":0.0,
                "denitrified_40to70":0.0,
                "denitrified_5to10":0.0,
                "denitrified_70to100":0.0,
                "immobilized":-2.3,
                "immobilized_0to2":-0.8,
                "immobilized_100to200":-0.1,
                "immobilized_10to20":0.0,
                "immobilized_20to40":0.0,
                "immobilized_2to5":-1.2,
                "immobilized_40to70":-0.1,
                "immobilized_5to10":0.0,
                "immobilized_70to100":-0.1,
                "leached":0.0,
                "leached_0to2":-3.9,
                "leached_100to200":0.1,
                "leached_10to20":-0.3,
                "leached_20to40":4.5,
                "leached_2to5":-3.5,
                "leached_40to70":7.6,
                "leached_5to10":-6.2,
                "leached_70to100":1.7,
                "leached_below_current_root_depth":-8.1,
                "leached_below_maximum_root_depth":0.0,
                "realized_from_crop_organic_matter":0.0,
                "realized_from_crop_organic_matter_0to2":0.0,
                "realized_from_crop_organic_matter_100to200":0.0,
                "realized_from_crop_organic_matter_10to20":0.0,
                "realized_from_crop_organic_matter_20to40":0.0,
                "realized_from_crop_organic_matter_2to5":0.0,
                "realized_from_crop_organic_matter_40to70":0.0,
                "realized_from_crop_organic_matter_5to10":0.0,
                "realized_from_crop_organic_matter_70to100":0.0,
                "realized_from_soil_organic_matter":7.0,
                "realized_from_soil_organic_matter_0to2":0.8,
                "realized_from_soil_organic_matter_100to200":0.0,
                "realized_from_soil_organic_matter_10to20":1.9,
                "realized_from_soil_organic_matter_20to40":1.8,
                "realized_from_soil_organic_matter_2to5":1.0,
                "realized_from_soil_organic_matter_40to70":0.2,
                "realized_from_soil_organic_matter_5to10":1.4,
                "realized_from_soil_organic_matter_70to100":0.0,
                "uptaken_by_crop":-1.4,
                "uptaken_by_crop_0to2":0.0,
                "uptaken_by_crop_100to200":0.0,
                "uptaken_by_crop_10to20":-0.7,
                "uptaken_by_crop_20to40":-0.2,
                "uptaken_by_crop_2to5":-0.1,
                "uptaken_by_crop_40to70":0.0,
                "uptaken_by_crop_5to10":-0.4,
                "uptaken_by_crop_70to100":0.0,
                "uptaken_by_crop_optimal":-2.1,
                "uptaken_by_crop_optimal_0to2":0.0,
                "uptaken_by_crop_optimal_100to200":0.0,
                "uptaken_by_crop_optimal_10to20":-0.8,
                "uptaken_by_crop_optimal_20to40":-0.2,
                "uptaken_by_crop_optimal_2to5":-0.3,
                "uptaken_by_crop_optimal_40to70":0.0,
                "uptaken_by_crop_optimal_5to10":-0.6,
                "uptaken_by_crop_optimal_70to100":0.0,
                "volatized":0.0,
                "volatized_0to2":0.0,
                "volatized_100to200":0.0,
                "volatized_10to20":0.0,
                "volatized_20to40":0.0,
                "volatized_2to5":0.0,
                "volatized_40to70":0.0,
                "volatized_5to10":0.0,
                "volatized_70to100":0.0
            },
            "nitrogen_metadata":{
                "applied_use_efficiency":16.7,
                "applied_use_efficiency_unit":"%",
                "current_root_depth":49.0,
                "current_root_depth_unit":"cm",
                "indigenous_use_efficiency":20.2,
                "indigenous_use_efficiency_unit":"%",
                "maximum_root_depth":149.0,
                "maximum_root_depth_unit":"cm",
                "nitrogen_available_unit":"kg/ha",
                "nitrogen_budget_unit":"kg/ha",
                "notes":{},
                "uptake_score":99.8,
                "uptake_score_unit":"%"
            }
        },...
    },
    "stage_descriptions":{
        "101":{
            "advisor":"Nutrient",
            "applicable_scales":{
                "feekes":"1.0",
                "haun":"0.5",
                "zadoks":"10"
            },
            "description":"The first leaf is at half of its final length.",
            "images":[
                {
                    "attribution":"Courtesy of David L. Hansen, University of Minnesota.",
                    "caption":"Emergence",
                    "url":"https://.../Coleoptile.jpg"
                }
            ],
            "name":"Emergence",
            "order":"1"
        },...
    }
}

2.9. Spring Wheat Mechanical Drying - v1.0

The Spring Wheat Mechanical Drying endpoint simulates the drydown process of spring wheat using either fan-powered low-temperature drying or burner-driven high-temperature drying facilities to provide drying statistics and cost projections. The mechanical drying process is simulated using up to 10 future days of grain moisture estimates. Results from the spring wheat in-field drying model are also returned for comparison.

Note that a field, growth, and drying facility are required to utilize this feature. Any available grain moisture measurements are used to improve model results.

Please be aware that mechanical drying data will not be returned if grain moisture estimates are unable to be obtained from the spring wheat in-field drying model. This may occur if one of the following conditions are met:

  • The spring wheat growth model simulation does not bring the crop to maturity. This is more likely to occur for certain location (e.g., cooler climates) and relative maturity combinations.

  • The crop planting date or emergence date are too far in the past. The models are designed for future planning; users can utilize the “current_date” argument to determine what model results could have been on a past date. These results can be different than what would have been seen on the emulated date, as the forecast timeframes are now represented by historical data.

2.9.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/mechanical_drying?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&drying_facility_ids={string}&grain_unit={string}
&target_moisture_content_wb={float}&current_date={timestamp}

2.9.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Accounts API ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have read privileges for the field in which the growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field.

target_moisture_ content_wb

float

yes

Numeric representation of the desired moisture level for safe storage, measured in percent on a wet basis. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

grain_unit

string

yes

Units to use when returning unit costs of drying. Valid values are “bu” (bushel) and “mt” (metric ton).

drying_facility_ids

string

no

Comma-delimited list of drying facility IDs to be used. Currently, only the most recently created facility in the list will be used. Default behavior is to use the most recently created facility overall. Note that the calling user must have at least read privileges for the asset (drying facility).

current_date

timestamp

no

Emulate model results as if viewed on this date2. Useful for viewing approximate model results for historical timeframes greater than one year in the past. There can be differences in results due to what would have been forecasted weather data now being replaced with historical or climatological data used in the calculations.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

2.9.3. Response Object (JSON)

Field Description

asset_id

The ID given to a particular drying facility.

name

The user-provided name of the drying facility. If this is not supplied, a generic name of “Drying Facility” followed by a number is used.

burner_fuel_type

Type of fuel consumed by the burner, as provided by the Accounts API.

burner_fuel_unit

Unit of measure associated with the fuel type, as provided by the Accounts API.

driest_datetime

Time that the grain reached its lowest moisture content of the model run. Represented by a date string in the case of low-temperature drying or hours and minutes in the case of high-temperature drying. Note that the simulation will stop when the user-specified target moisture content is reached, in which case this will indicate the timing of the grain reaching that threshold.

driest_moisture_content_db

Driest dry-basis grain moisture content of the simulation, in percent. Dry-basis moisture content is defined as the ratio of the mass of water to the dry mass of a sample of grain.

driest_moisture_content_wb

Driest wet-basis grain moisture content of the simulation, in percent. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

dryer_throughput_grain_units_ per_hour

Amount of grain dried per hour. Applicable only in high-temperature drying facilities.

drying_time

Amount of time, in seconds, that elapsed for the grain to reach its lowest moisture content.

grain_storability

Likelihood of spoilage. Possible values include “0,” indicating that grain is not likely to spoil; “1,” indicating a marginal risk; and “2,” warning that spoilage is likely. When high-temperature drying is in use, “n/a” will be used.

grain_unit

Unit of measure associated with the volume of grain as provided by the user.

per_grain_unit/burner_fuel_ cost

Expected burner fuel cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/burner_fuel_ units_consumed

Expected amount of fuel consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/burner_kwh_ consumed

Expected amount of fuel energy, in kilowatt-hours, consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/electricity_cost

Expected electricity cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/electricity_kwh_ consumed

Expected amount of electrical energy, in kilowatt-hours, consumed by the fan per unit of grain, in the grain unit provided by the user.

per_grain_unit/total_cost

Expected total drying cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit_per_percent_ moisture/total_cost

Expected total drying cost per unit of grain per percent moisture change, in the user’s local currency, and in the grain unit provided by the user.

sample_datetime

Valid time of the grain moisture sample provided by the in-field drydown model.

sample_moisture_content_wb

Starting wet-basis moisture content of the grain sample, in percent, provided by the in-field drydown model.

simulation_length

Total length of time, in seconds, over which the drydown process was modeled.

target_moisture_reached

Flag indicating whether the target storage moisture content is reached in the simulation, where “1” indicates that the storage moisture is reached and “0” indicates it is not. Primarily applicable in low-temperature drying facilities, where ambient environmental conditions may not permit an adequate amount of drying.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum daily air temperature, which may be a historical, forecast, or climatological value, depending on the timeframe.

air_temp_min

Minimum daily air temperature, which may be a historical, forecast, or climatological value, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures.

feedback_id

If this field is present, it indicates a confirmed or observed growth stage on the current date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

2.9.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/springwheat/mechanical_drying?
app_id=123&app_key=321&account_id=abc&user_id=cba&growth_id=xyz
&grain_unit=bu&target_moisture_content_wb=14.5

2.9.5. Example Response

{
    "drying_facilities":[
        {
            "asset_id":"abc-123",
            "data":[
                {
                    "burner_fuel_type":"liquid_propane",
                    "burner_fuel_unit":"gallon",
                    "driest_datetime":"04:11",
                    "driest_moisture_content_db":16.96,
                    "driest_moisture_content_wb":14.5,
                    "dryer_throughput_grain_units_per_hour":339.0,
                    "drying_time":15075,
                    "grain_storability":"n/a",
                    "grain_unit":"bu",
                    "per_grain_unit":{
                        "burner_fuel_cost":0.431,
                        "burner_fuel_units_consumed":0.479,
                        "burner_kwh_consumed":11.8,
                        "electricity_cost":0.499,
                        "electricity_kwh_consumed":1.0,
                        "total_cost":0.93
                    },
                    "per_grain_unit_per_percent_moisture":{
                        "total_cost":0.051
                    },
                    "sample_datetime":"2016-07-13",
                    "sample_moisture_content_wb":32.88,
                    "simulation_length":15075,
                    "target_moisture_reached":1
                },...
            ],
            "name":"Spring Wheat Dryer"
        }
    ],
    "infield_drydown_data":{
        "47,-97":{
            "2016-07-13":{
                "agdd":2432.5,
                "air_temp_max":74.0,
                "air_temp_min":64.0,
                "equilibrium_moisture_content":10.0,
                "gdd":37.0,
                "grain_moisture_content":32.88,
                "grain_moisture_content_change":"n/a",
                "last_stage":"20",
                "new_stage":"21"
            },...
        }
    }
}

3. Winter Wheat

3.1. Winter Wheat Growth - v1.0

Leveraging Iteris’ winter wheat growth stage model, the Winter Wheat Growth endpoint allows users to model the maturation and development of winter wheat crops. Users may also take advantage of Accounts API integration to provide crop growth feedback and optimize model results.

Please note that winter wheat has a vernalization (cold) requirement that must be satisfied before floral initiation can occur. This requirement will not be met if winter temperatures do not get low enough, which means that the model will not go past the First Tiller stage.

3.1.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/growth?app_id={string}
&app_key={string}&location={lat, lon coordinates}&plant_date={timestamp}
&days={integer}&account_id={string}&user_id={string}&growth_id={string}
&relative_maturity={string}&scale={string}&plant_depth={float}

3.1.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early”, “medium-early”, “medium”, “medium-late”, and “late”. Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

scale

string

no

no

Specifies which growth scale (feekes, haun, or zadoks) the response will display. Default behavior is to utilize a unified scale and display the equivalent stages from all three scales in the response.

plant_depth

float

no

 — 

The depth in centimeters that the crop was planted. Possible values range from 0.1 to 10.0 cm. The default is 5.0 cm.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

3.1.3. Response Object (JSON)

Field Description

gdd

Growing degree days accumulated on the current date.

agdd

Aggregate growing degree days from plant date, including the current period’s date.

air_temp_min

Minimum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

air_temp_max

Maximum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

last_stage

The last known growth stage. If no valid stage has been reached, this value will be “n/a.” This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

new_stage

The crop is expected to have entered a new stage between the current period’s date and the previous period’s date.

advisor

Suggested field properties to check.

description

Text description for a stage.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

order

Ordering of stage when displaying/listing stage_descriptions.

applicable_scales

Displays the stage equivalent in other scales.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

feekes

Stage equivalent in the feekes scale.

haun

Stage equivalent in the haun scale.

zadoks

Stage equivalent in the zadoks scale.

attribution

Various attributions for the model used.

images

List of image metadata.

attribution

Credit for image.

caption

Image description.

url

Location of image.

3.1.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/growth?app_id=123&app_key=321
&location=47,-97&plant_date=1462060800&days=160

3.1.5. Example Response

{
    "data":{
        "47,-97":{
            "2015-10-15":{
                "agdd":184.59,
                "air_temp_max":57.0,
                "air_temp_min":30.0,
                "gdd":6.41,
                "last_stage":"0",
                "new_stage":"1"
            },...
        }
    },
    "harvest_window":{
        "end":"2016-08-08",
        "start":"2016-07-21"
    },
    "stage_descriptions":{
        "0":{
            "advisor":"Nutrient",
            "applicable_scales":{
                "feekes":"n/a",
                "haun":"n/a",
                "zadoks":"05"
            },
            "description":"Germination",
            "order":"1"
        },...
    }
}

3.2. Winter Wheat Growth with GDD Envelope - v1.0

The Winter Wheat Growth with GDD Envelope service provides winter wheat growth information in addition to GDD envelope data. GDD envelope calculation begins from either the current day, or the planted/emergence date, whichever is further in the future. The envelope is constructed by compiling the previous 10 years of weather data, and simulating the maximum and minimum GDD that would have accumulated within those 10 years for each date. The calculated minimum and maximum values are then added to the current start of calculation date AGDD going onwards to show range of possibilities.

3.2.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/growth/
gdd_envelope?app_id={string}&app_key={string}&plant_date={timestamp}
&location={lat, lon coordinates}&days={integer}&account_id={string}
&user_id={string}&growth_id={string}
&relative_maturity={string}&scale={string}&plant_depth={float}

3.2.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early”, “medium-early”, “medium”, “medium-late”, and “late”. Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

scale

string

no

no

Specifies which growth scale (feekes, haun, or zadoks) the response will display. Default behavior is to utilize a unified scale and display the equivalent stages from all three scales in the response.

plant_depth

float

no

 — 

The depth in centimeters that the crop was planted. Possible values range from 0.1 to 10.0 cm. The default is 5.0 cm.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

3.2.3. Response Object (JSON)

Field Description

gdd

Growing degree days accumulated on the current date.

agdd

Aggregate growing degree days from plant date, including the current period’s date.

air_temp_min

Minimum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

air_temp_max

Maximum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

last_stage

The last known growth stage. If no valid stage has been reached, this value will be “n/a.” This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

new_stage

The crop is expected to have entered a new stage between the current period’s date and the previous period’s date.

advisor

Suggested field properties to check.

description

Text description for a stage.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

order

Ordering of stage when displaying/listing stage_descriptions.

applicable_scales

Displays the stage equivalent in other scales.

start

The beginning of typical harvest operations.

end

The end of typical harvest operations.

feekes

Stage equivalent in the feekes scale.

haun

Stage equivalent in the haun scale.

zadoks

Stage equivalent in the zadoks scale.

agdd_envelope_max

Maximum observed agdd during the previous 10 years.

agdd_envelope_min

Minimum observed agdd during the previous 10 years.

agdd_envelope_min_year

Year that the agdd_envelope_min was observed.

agdd_envelope_max_year

Year that the agdd_envelope_max was observed.

3.2.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/growth/gdd_envelope?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800&days=160

3.2.5. Example Response

{
    "data":{
        "32.509761735919426,-96.85546875":{
            "2016-10-21":{
                "agdd":118.09,
                "agdd_envelope_max":159.2098575,
                "agdd_envelope_max_year":"2012",
                "agdd_envelope_min":133.3998575,
                "agdd_envelope_min_year":"2013",
                "air_temp_max":71.0,
                "air_temp_min":55.0,
                "gdd":17.22,
                "last_stage":"0",
                "new_stage":"n/a"
            }, ...
        }
    },
    "harvest_window":{
        "end":"n/a",
        "start":"n/a"
    },
    "stage_descriptions":{
        "0":{
            "advisor":"Nutrient",
            "applicable_scales":{
                "feekes":"n/a",
                "haun":"n/a",
                "zadoks":"05"
            },
            "description":"The radicle (primary root) is appearing from the seed.",
            "order":"1"
        },...
    }
}

3.3. Winter Wheat Growth Add Feedback - v1.0

By providing feedback relating to the growth stage estimates, Iteris will be able to make updates and adjustments to offer its users better results in the future. The given user providing feedback must have write privileges for the field in which the field growth belongs.

Additional information related to feedback timestamp, growth feedback, and feedback stage is available in the Feedback Information section of the Appendix.

3.3.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/growth/feedback/add/
{growth_id}/{timestamp}/{stage}?account_id={string}&user_id={string}
&app_id={string}&app_key={string}

3.3.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

3.3.3. Response Object

A string representing a feedback ID.

3.3.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/growth/feedback/add/
xyz/1472688000/1?account_id=abc&user_id=cba&app_id=123&app_key=321

3.3.5. Example Response

def-345

3.4. Winter Wheat Growth Feedbacks by Growth - v1.0

Returns a list of growth feedback activities associated with the target growth_id.

3.4.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/growth/feedback/
get/by_growth/{growth_id}?app_id={string}&app_key={string}account_id={string}
&user_id={string}

3.4.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

3.4.3. Response Object (JSON)

Field Description

user_id

User ID provided by and used with the Accounts API.

created

Timestamp denoting when the feedback was created.

data

Information pertaining to the activity.

subtype

Enumeration value representing the specific variety of the activity. Defaults to 0.

growth_feedback_id

ID of target growth feedback.

type

Enumeration value of plant.

feedback/date

Unix timestamp denoting when the feedback happened2.

feedback/stage

Stage provided as feedback.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

3.4.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/growth/feedback/
get/by_growth/xyz?app_id=123&app_key=321&account_id=abc&user_id=cba

3.4.5. Example Response

[
    {
        "user_id":"1234",
        "feedback":{
            "date":1400371200,
            "type":68,
            "stage":"1"
        },
        "created":1446229281,
        "data":"{}",
        "subtype":"0",
        "growth_feedback_id":"1111",
        "type":68
    },...
]

3.5. Winter Wheat Growth Modify Feedback - v1.0

The Winter Wheat Growth Modify Feedback endpoint allows users to modify previously provided growth stage estimate feedback. The given user providing feedback must have write privileges for the field in which the field growth belongs. At least one modification must be provided.

3.5.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/growth/feedback/modify/
{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}&timestamp={integer}&stage={string}

3.5.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

3.5.3. Response Object

A string representing success (“true”) or failure (“false”).

3.5.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/growth/feedback/
modify/abc-123?account_id=abc&user_id=cba&app_id=123&app_key=321
&timestamp=1472688000&stage=1

3.5.5. Example Response

true

3.6. Winter Wheat Growth Delete Feedback - v1.0

This endpoint allows users to delete the previously provided growth stage estimate feedback. The given user deleting feedback must have write privileges for the field in which the field growth belongs.

3.6.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/growth/feedback/
delete/{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}

3.6.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

3.6.3. Response Object

A string representing success (“true”) or failure (“false”).

3.6.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/growth/
feedback/delete/abc-123?account_id=abc&user_id=cba
&app_id=123&app_key=321

3.6.5. Example Response

true

3.7. Winter Wheat In-Field Drydown - v1.0

Drawing from the ClearAg Field Weather API and winter wheat growth model, the Winter Wheat In-Field Drydown endpoint simulates the drying process of winter wheat grain in the field after the crop achieves full maturity, and provides daily grain moisture estimates during the drydown period. If Accounts API integration is used, any available moisture measurements are used to improve model results.

3.7.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/infield_drydown?
app_id={string}&app_key={string}&location={lat, lon coordinates}
&plant_date={timestamp}&account_id={string}&user_id={string}&growth_id={string}
&relative_maturity={string}&scale={string}&plant_depth={float}

3.7.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early”, “medium-early”, “medium”, “medium-late”, and “late”. Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

scale

string

no

no

Specifies which growth scale (feekes, haun, or zadoks) the response will display. Default behavior is to utilize a unified scale and display the equivalent stages from all three scales in the response.

plant_depth

float

no

 — 

The depth in centimeters that the crop was planted. Possible values range from 0.1 to 10.0 cm. The default is 5.0 cm.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

3.7.3. Response Object (JSON)

Field Description

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures. Note that wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

advisor

Suggested field properties to check.

applicable_scales

Container for the equivalent stage within the Feekes, Haun, and/or Zadoks growth scales.

description

Text description for a stage.

order

Relative position of the stage within the growth scale.

3.7.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/infield_drydown?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800

3.7.5. Example Response

{
    "data":{
        "39.26628442213066,-103.1396484375":{
            "2016-08-11":{
                "agdd":4462.58,
                "air_temp_max":81.0,
                "air_temp_min":66.0,
                "equilibrium_moisture_content":6.44,
                "gdd":22.97,
                "grain_moisture_content":5.62,
                "grain_moisture_content_change":0.14,
                "last_stage":"13",
                "new_stage":"n/a"
            },...
        }
    },
    "harvest_window":{
        "end":"2016-08-26",
        "start":"2016-08-08"
    },
    "stage_descriptions":{
        "0":{
            "advisor":"Nutrient",
            "applicable_scales":{
                "feekes":"n/a",
                "haun":"n/a",
                "zadoks":"05"
            },
            "description":"Germination",
            "order":"1"
        },...
    }
}

3.8. Winter Wheat Nitrogen Advisor - v1.0

The ClearAg Winter Wheat Nitrogen Advisor simulates the various processes of the nitrogen cycle that impact the availability of nitrogen to winter wheat crops. The model is based on a combination of proven algorithms from several industry models for simulating the nitrogen cycle. When used in combination with the Accounts API, the Winter Wheat Nitrogen Advisor allows provision of several types of field level activities, including fertilizer treatments and soil sample results, containing information such as soil nitrate and organic matter levels, as well as soil pH. Crop growth and the corresponding crop parameters of importance are simulated based on user-specified location, relative maturity, and planting date. Weather and soil information required by the Clear-N model are provided by the ClearAg Field Weather and Soil Conditions APIs, which provide a seamless global dataset of current, forecast, and historical conditions (dating back to 1980) for any arable location globally.

3.8.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/nutrient/nitrogen?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&location={lat, lon coordinates}&plant_date={timestamp}
&yield_goal={integer}&yield_goal_unit={string}&previous_crop={integer}
&previous_harvest_date={timestamp}&previous_yield={integer}
&previous_yield_unit={string}&output_unit={string}&year_offset={integer}
&relative_maturity={string}&plant_depth={float}

3.8.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Limited to a single location per query.

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the current crop was planted or the date of emergence2.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early”, “medium-early”, “medium”, “medium-late”, and “late”. Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

plant_depth

float

no

 — 

The depth in centimeters that the crop was planted. Possible values range from 0.1 to 10.0 cm. The default is 5.0 cm.

yield_goal

integer

yes

yes

Target yield for current crop.

yield_goal_unit

string

yes

yes

Target yield unit. Accepted values are “lb/ac,” “kg/ha,” or “bu/ac”.

previous_crop

integer

no

no

Enumeration value of previous crop on field. Accepted values are currently 50 (barley), 51 (corn), 57 (spring wheat), 59 (canola), 65 (cotton), 66 (soybean), 68 (winter wheat), 69 (vegetable), 70 (sorghum), 71 (pea), 72 (sunflower), 73 (rice), and 74 (alfalfa).

previous_harvest_date

timestamp

no

no

Epoch timestamp valid near the time that the previous crop was harvested2. Required if previous crop is specified. May not predate the planting or emergence date by more than 366 days.

previous_yield

integer

no

no

Actual yield of the previous crop. Required if previous crop is specified.

previous_yield_ unit

string

no

no

Previous yield unit. Accepted values are “lb/ac,” “kg/ha,” or “bu/ac.” Required if previous crop is specified. Note that “bu/ac” is not a valid yield unit for alfalfa, cotton, or vegetable.

output_unit

string

yes

yes

Specifies the unit of the area density data displayed. Accepted values are “lb/ac” or “kg/ha.”

year_offset

integer

no

no

Specifies a number of years by which to adjust model results. Values must be less than 0.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

3.8.3. Response Object (JSON)

Field Description

fertilizer_treatment

Structure holding all fertilizer treatment data utilized by the nitrogen model, including the fertilizer type, application rate, and depth.

soil_sample

Structure holding all soil sample data utilized by the nitrogen model, including the soil nitrate content, organic matter content, pH level, and sample depth.

tillage

Structure holding all tillage data utilized by the nitrogen model, including the tillage type and depth.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum air temperature valid for the current date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the timeframe.

air_temp_min

Minimum air temperature valid for the current date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the timeframe.

gdd

Growing degree days accumulated on the current date.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

ammonium,
ammonium_XtoY

The amount of nitrogen in the form of ammonium within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters.

ammonium_in_last_sample_depth

The modeled amount of ammonium above the depth of the previous soil sample.

nitrate,
nitrate_XtoY

The amount of nitrogen in the form of nitrate within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters.

nitrate_in_last_sample_depth

The modeled amount of nitrate above the depth of the previous soil sample.

applied_fertilizers,
applied_fertilizers_XtoY

The amount of nitrogen applied as fertilizer resident within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters3.

denitrified,
denitrified_XtoY

The amount of soil nitrate lost from the entire 2-meter depth of the modeled soil profile, or from within the layer spanning from depth=X to depth=Y centimeters, due to the process of denitrification, whereby nitrate is converted into nitrogen gas and then escapes into the atmosphere3.

immobilized,
immobilized_XtoY

The amount of nitrogen that has been immobilized within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters, in order to support mineralization of the previous crop’s residues3.

leached,
leached_XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning from depth=X to depth=Y centimeters, due to the process of leaching. Only losses will normally be seen when aggregated across the entire depth of the modeled soil profile; otherwise, some layers may gain nitrate at the expense of others, due to the vertical movement of water within the soil profile3.

leached_below_current_root_depth

The amount of soil nitrate that has been leached below the depth of the current crop’s roots as of the indicated date3.

leached_below_maximum_root_depth

The amount of soil nitrate that has been leached below the maximum depth that the current crop’s roots are expected to reach during the entirety of its growth cycle3.

realized_from_crop_organic_matter,
realized_from_crop_organic_matter_ XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, due to the process of mineralization of residues associated with the previous crop. This can be either positive or negative, depending on the carbon to nitrogen ratio of the previous crop’s residues3.

realized_from_soil_organic_matter,
realized_from_soil_organic_matter_ XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, due to the process of mineralization of soil organic matter. Since the carbon to nitrogen ratio of soil organic matter is typically below that associated with the diet of soil microbes, values will normally be positive3.

uptaken_by_crop,
uptaken_by_crop_XtoY

The amount of nitrogen uptaken by the crop from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters. If less than uptaken_by_crop_optimal, this can be indicative of a risk that the crop may be short of nitrogen3.

uptaken_by_crop_optimal,
uptaken_by_crop_optimal_XtoY

The amount of nitrogen the crop would have ideally taken up from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters3.

volatized,
volatized_XtoY

The amount of nitrogen lost by the process of volatization (also referred to as volatilization) from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, whereby urea fertilizer is converted into ammonia gas and then escapes into the atmosphere3.

applied_use_efficiency

The crop’s use efficiency of fertilizer-based nitrogen applied since the harvest of the previous crop. Values will be less than or equal to 100%, with higher percentages indicating that the crop has (or will) use a higher percentage of the fertilizers that have been applied.

applied_use_efficiency_unit

Units of “applied_use_efficiency.”

current_root_depth

The depth to which the current crop’s roots are assumed to reach as of the indicated date.

current_root_depth_unit

Units of “current_root_depth.” Chosen automatically based on the user-provided input value of “output_unit.”

indigenous_use_efficiency

The crop’s use efficiency of nitrogen realized through organic matter mineralization since the harvest of the previous crop. Values are in percentages, with higher percentages indicating that the crop has (or will) use a higher percentage of the nitrogen that has been realized through organic matter mineralization. Values in excess of 100% are possible.

indigenous_use_efficiency_unit

Units of “indigenous_use_efficiency.”

maximum_root_depth

The maximum depth to which the current crop’s roots are expected to reach during the entirety of its growth cycle.

maximum_root_depth_unit

Units of “maximum_root_depth.” Chosen automatically based on the user-provided input value of “output_unit”.

nitrogen_available_unit

Units of all data values in the “nitrogen_available” subsection of the returned JSON object.

nitrogen_budget_unit

Units of all data values in the “nitrogen_budget” subsection of the returned JSON object.

notes

A dictionary containing textual descriptions of noteworthy problems or occurrences on the indicated date.

uptake_score

A 0-100 score quantifying the adequacy of crop nitrogen uptake relative to the goals specified in the API call. Higher values indicate better uptake, with values at or near 100 being desirable in order to optimize the crop’s prospects for achieving the caller-specified yield_goal.

uptake_score_unit

Units of “uptake_score.”

advisor

Suggested field properties to check.

applicable_scales

Container for the equivalent stage within the Feekes, Haun, and Zadoks growth scales.

description

Text description for a growth stage.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Image URL.

name

Growth stage name.

order

Relative position of a stage within the growth scale.

3 Positive numeric values indicate that nitrogen has been gained by the soil due to the associated process, whereas negative numeric values indicate that nitrogen has been lost by the soil due to the associated process.

3.8.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/nutrient/nitrogen?
app_id=123&app_key=321&account_id=abc&user_id=cba&growth_id=xyz
&previous_harvest_date=1450757200&previous_crop=51&previous_yield=1000
&previous_yield_unit=kg/ha&yield_goal=1050&yield_goal_unit=kg/ha
&output_unit=kg/ha

3.8.5. Example Response

{
    "activities":{
        "fertilizer_treatment":{
            "2015-10-20":[{
                "depth":0.5,
                "depth_unit":"m",
                "fertilizer_id":"11",
                "rate":366.0,
                "rate_unit":"lb/ac"
            }]
        },
        "soil_sample":{
            "2015-10-15":[{
                "depth_unit":"m",
                "end_depth":1.0,
                "nitrate":3.0,
                "nitrate_unit":"kg/ha",
                "organic_matter":"n/a",
                "ph":"n/a",
                "start_depth":0.5
            }]
        },
        "tillage":{}
    },
    "data":{
        "2015-11-17":{
            "agdd":520.74,
            "air_temp_max":74.0,
            "air_temp_min":51.0,
            "gdd":16.86,
            "last_stage":"2",
            "new_stage":"n/a",
            "nitrogen_available":{
                "ammonium":0.0,
                "ammonium_0to2":0.0,
                "ammonium_100to200":0.0,
                "ammonium_10to20":0.0,
                "ammonium_20to40":0.0,
                "ammonium_2to5":0.0,
                "ammonium_40to70":0.0,
                "ammonium_5to10":0.0,
                "ammonium_70to100":0.0,
                "ammonium_in_last_sample_depth":"n/a",
                "nitrate":83.6,
                "nitrate_0to2":0.0,
                "nitrate_100to200":59.5,
                "nitrate_10to20":0.8,
                "nitrate_20to40":2.9,
                "nitrate_2to5":0.0,
                "nitrate_40to70":8.0,
                "nitrate_5to10":0.2,
                "nitrate_70to100":12.1,
                "nitrate_in_last_sample_depth":"n/a"
            },
            "nitrogen_budget":{
                "applied_fertilizers":0.0,
                "applied_fertilizers_0to2":0.0,
                "applied_fertilizers_100to200":0.0,
                "applied_fertilizers_10to20":0.0,
                "applied_fertilizers_20to40":0.0,
                "applied_fertilizers_2to5":0.0,
                "applied_fertilizers_40to70":0.0,
                "applied_fertilizers_5to10":0.0,
                "applied_fertilizers_70to100":0.0,
                "denitrified":-5.1,
                "denitrified_0to2":0.0,
                "denitrified_100to200":-1.9,
                "denitrified_10to20":-0.2,
                "denitrified_20to40":-0.4,
                "denitrified_2to5":-0.1,
                "denitrified_40to70":-1.0,
                "denitrified_5to10":-0.2,
                "denitrified_70to100":-1.4,
                "immobilized":-7.6,
                "immobilized_0to2":-1.8,
                "immobilized_100to200":-0.9,
                "immobilized_10to20":-0.2,
                "immobilized_20to40":-0.4,
                "immobilized_2to5":-3.1,
                "immobilized_40to70":-0.6,
                "immobilized_5to10":-0.1,
                "immobilized_70to100":-0.6,
                "leached":-30.1,
                "leached_0to2":-0.2,
                "leached_100to200":8.9,
                "leached_10to20":-7.4,
                "leached_20to40":-13.8,
                "leached_2to5":0.1,
                "leached_40to70":-8.8,
                "leached_5to10":-5.7,
                "leached_70to100":-3.2,
                "leached_below_current_root_depth":-0.6,
                "leached_below_maximum_root_depth":-32.9,
                "realized_from_crop_organic_matter":0.0,
                "realized_from_crop_organic_matter_0to2":0.0,
                "realized_from_crop_organic_matter_100to200":0.0,
                "realized_from_crop_organic_matter_10to20":0.0,
                "realized_from_crop_organic_matter_20to40":0.0,
                "realized_from_crop_organic_matter_2to5":0.0,
                "realized_from_crop_organic_matter_40to70":0.0,
                "realized_from_crop_organic_matter_5to10":0.0,
                "realized_from_crop_organic_matter_70to100":0.0,
                "realized_from_soil_organic_matter":81.8,
                "realized_from_soil_organic_matter_0to2":1.3,
                "realized_from_soil_organic_matter_100to200":35.0,
                "realized_from_soil_organic_matter_10to20":5.4,
                "realized_from_soil_organic_matter_20to40":11.2,
                "realized_from_soil_organic_matter_2to5":1.9,
                "realized_from_soil_organic_matter_40to70":11.9,
                "realized_from_soil_organic_matter_5to10":3.9,
                "realized_from_soil_organic_matter_70to100":11.2,
                "uptaken_by_crop":0.0,
                "uptaken_by_crop_0to2":0.0,
                "uptaken_by_crop_100to200":0.0,
                "uptaken_by_crop_10to20":0.0,
                "uptaken_by_crop_20to40":0.0,
                "uptaken_by_crop_2to5":0.0,
                "uptaken_by_crop_40to70":0.0,
                "uptaken_by_crop_5to10":0.0,
                "uptaken_by_crop_70to100":0.0,
                "uptaken_by_crop_optimal":-0.1,
                "uptaken_by_crop_optimal_0to2":0.0,
                "uptaken_by_crop_optimal_100to200":0.0,
                "uptaken_by_crop_optimal_10to20":0.0,
                "uptaken_by_crop_optimal_20to40":0.0,
                "uptaken_by_crop_optimal_2to5":0.0,
                "uptaken_by_crop_optimal_40to70":0.0,
                "uptaken_by_crop_optimal_5to10":0.0,
                "uptaken_by_crop_optimal_70to100":0.0,
                "volatized":-0.6,
                "volatized_0to2":-0.1,
                "volatized_100to200":0.0,
                "volatized_10to20":0.0,
                "volatized_20to40":0.0,
                "volatized_2to5":-0.2,
                "volatized_40to70":0.0,
                "volatized_5to10":-0.3,
                "volatized_70to100":0.0
            },
            "nitrogen_metadata":{
                "applied_use_efficiency":"n/a",
                "applied_use_efficiency_unit":"%",
                "current_root_depth":2.0,
                "current_root_depth_unit":"in",
                "indigenous_use_efficiency":0.0,
                "indigenous_use_efficiency_unit":"%",
                "maximum_root_depth":67.0,
                "maximum_root_depth_unit":"in",
                "nitrogen_available_unit":"lb/ac",
                "nitrogen_budget_unit":"lb/ac",
                "notes":{
                    "0":"Some nitrogen leached below the maximum depth the crop roots will reach.",
                    "1":"Some nitrogen leached below the current root depth.",
                    "5":"Crop nitrogen uptake limited by soil location relative to crop roots."
                },
                "uptake_score":0.2,
                "uptake_score_unit":"%"
            }
        },...
    },
    "stage_descriptions":{
        "2":{
            "advisor":"Nutrient",
            "applicable_scales":{
                "feekes":"2",
                "haun":"1.9-2.7",
                "zadoks":"21"
            },
            "description":"The first tiller is visible.",
            "images":[
                {
                    "attribution":"Courtesy of David L. Hansen, University of Minnesota.",
                    "caption":"First tiller",
                    "url":"https://.../Zadoks+21.jpg"
                },...
            ],
            "name":"First Tiller",
            "order":"3"
        },...
    }
}

3.9. Winter Wheat Mechanical Drying - v1.0

The Winter Wheat Mechanical Drying endpoint simulates the drydown process of winter wheat using either fan-powered low-temperature drying or burner-driven high-temperature drying facilities to provide drying statistics and cost projections. The mechanical drying process is simulated using up to 10 future days of grain moisture estimates. Results from the winter wheat in-field drying model are also returned for comparison.

Note that a field, growth, and drying facility are required to utilize this feature. Any available grain moisture measurements are used to improve model results.

Please be aware that mechanical drying data will not be returned if grain moisture estimates are unable to be obtained from the winter wheat in-field drying model. This may occur if one of the following conditions are met:

  • The winter wheat growth model simulation does not bring the crop to maturity. This is more likely to occur for certain location (e.g., cooler climates) and relative maturity combinations.

  • The crop planting date or emergence date are too far in the past. The models are designed for future planning; users can utilize the “current_date” argument to determine what model results could have been on a past date. These results can be different than what would have been seen on the emulated date, as the forecast timeframes are now represented by historical data.

3.9.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/mechanical_drying?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&drying_facility_ids={string}&grain_unit={string}
&target_moisture_content_wb={float}&current_date={timestamp}

3.9.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Accounts API ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have read privileges for the field in which the growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field.

target_moisture_ content_wb

float

yes

Numeric representation of the desired moisture level for safe storage, measured in percent on a wet basis. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

grain_unit

string

yes

Units to use when returning unit costs of drying. Valid values are “bu” (bushel) and “mt” (metric ton).

drying_facility_ids

string

no

Comma-delimited list of drying facility IDs to be used. Currently, only the most recently created facility in the list will be used. Default behavior is to use the most recently created facility overall. Note that the calling user must have at least read privileges for the asset (drying facility).

current_date

timestamp

no

Emulate model results as if viewed on this date2. Useful for viewing approximate model results for historical timeframes greater than one year in the past. There can be differences in results due to what would have been forecasted weather data now being replaced with historical or climatological data used in the calculations.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

3.9.3. Response Object (JSON)

Field Description

asset_id

The ID given to a particular drying facility.

name

The user-provided name of the drying facility. If this is not supplied, a generic name of “Drying Facility” followed by a number is used.

burner_fuel_type

Type of fuel consumed by the burner, as provided by the Accounts API.

burner_fuel_unit

Unit of measure associated with the fuel type, as provided by the Accounts API.

driest_datetime

Time that the grain reached its lowest moisture content of the model run. Represented by a date string in the case of low-temperature drying or hours and minutes in the case of high-temperature drying. Note that the simulation will stop when the user-specified target moisture content is reached, in which case this will indicate the timing of the grain reaching that threshold.

driest_moisture_content_db

Driest dry-basis grain moisture content of the simulation, in percent. Dry-basis moisture content is defined as the ratio of the mass of water to the dry mass of a sample of grain.

driest_moisture_content_wb

Driest wet-basis grain moisture content of the simulation, in percent. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

dryer_throughput_grain_units_ per_hour

Amount of grain dried per hour. Applicable only in high-temperature drying facilities.

drying_time

Amount of time, in seconds, that elapsed for the grain to reach its lowest moisture content.

grain_storability

Likelihood of spoilage. Possible values include “0,” indicating that grain is not likely to spoil; “1,” indicating a marginal risk; and “2,” warning that spoilage is likely. When high-temperature drying is in use, “n/a” will be used.

grain_unit

Unit of measure associated with the volume of grain as provided by the user.

per_grain_unit/burner_fuel_ cost

Expected burner fuel cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/burner_fuel_ units_consumed

Expected amount of fuel consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/burner_kwh_ consumed

Expected amount of fuel energy, in kilowatt-hours, consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/electricity_cost

Expected electricity cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/electricity_kwh_ consumed

Expected amount of electrical energy, in kilowatt-hours, consumed by the fan per unit of grain, in the grain unit provided by the user.

per_grain_unit/total_cost

Expected total drying cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit_per_percent_ moisture/total_cost

Expected total drying cost per unit of grain per percent moisture change, in the user’s local currency, and in the grain unit provided by the user.

sample_datetime

Valid time of the grain moisture sample provided by the in-field drydown model.

sample_moisture_content_wb

Starting wet-basis moisture content of the grain sample, in percent, provided by the in-field drydown model.

simulation_length

Total length of time, in seconds, over which the drydown process was modeled.

target_moisture_reached

Flag indicating whether the target storage moisture content is reached in the simulation, where “1” indicates that the storage moisture is reached and “0” indicates it is not. Primarily applicable in low-temperature drying facilities, where ambient environmental conditions may not permit an adequate amount of drying.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum daily air temperature, which may be a historical, forecast, or climatological value, depending on the timeframe.

air_temp_min

Minimum daily air temperature, which may be a historical, forecast, or climatological value, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures.

feedback_id

If this field is present, it indicates a confirmed or observed growth stage on the current date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

3.9.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/mechanical_drying?
app_id=123&app_key=321&account_id=abc&user_id=cba&growth_id=xyz
&grain_unit=bu&target_moisture_content_wb=14.5

3.9.5. Example Response

{
    "drying_facilities":[
        {
            "asset_id":"abc-123",
            "data":[
                {
                    "burner_fuel_type":"liquid_propane",
                    "burner_fuel_unit":"gallon",
                    "driest_datetime":"03:31",
                    "driest_moisture_content_db":16.96,
                    "driest_moisture_content_wb":14.5,
                    "dryer_throughput_grain_units_per_hour":402.0,
                    "drying_time":12710,
                    "grain_storability":"n/a"
                    "grain_unit":"bu",
                    "per_grain_unit":{
                        "burner_fuel_cost":0.381,
                        "burner_fuel_units_consumed":0.423,
                        "burner_kwh_consumed":10.4,
                        "electricity_cost":0.421,
                        "electricity_kwh_consumed":0.8,
                        "total_cost":0.801
                    },
                    "per_grain_unit_per_percent_moisture":{
                        "total_cost":0.047
                    },
                    "sample_datetime":"2016-07-12",
                    "sample_moisture_content_wb":31.39,
                    "simulation_length":12710,
                    "target_moisture_reached":1
                },...
            ],
            "name":"Winter Wheat Dryer"
        }
    ],
    "infield_drydown_data":{
        "47,-97":{
            "2016-07-12":{
                "agdd":2126.41,
                "air_temp_max":84.0,
                "air_temp_min":61.0,
                "equilibrium_moisture_content":9.88,
                "gdd":22.56,
                "grain_moisture_content":31.39,
                "grain_moisture_content_change":"n/a",
                "last_stage":"11",
                "new_stage":"12"
            },...
        }
    }
}

4. Canola

4.1. Canola Growth - v1.0

Leveraging Iteris’ canola growth stage model, the Canola Growth endpoint allows users to model the maturation and development of canola crops. Users may also take advantage of Accounts API integration to provide crop growth feedback and optimize model results.

4.1.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/canola/growth?app_id={string}
&app_key={string}&location={lat, lon coordinates}&plant_date={timestamp}
&days={integer}&account_id={string}&user_id={string}&growth_id={string}
&relative_maturity={string}

4.1.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” and “medium.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “medium” relative maturity are expected to mature relatively slowly. Default is “medium.”

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

4.1.3. Response Object (JSON)

Field Description

gdd

Growing degree days accumulated on the current date.

agdd

Aggregate growing degree days from plant date, including the current period’s date

current_stage

Current estimated stage of growth.

air_temp_min

Minimum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

air_temp_max

Maximum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

advisor

Suggested field properties to check.

description

Text description for a stage.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

4.1.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/canola/growth?app_id=123&app_key=321
&location=47,-97&plant_date=1462060800&days=160

4.1.5. Example Response

{
    "data":{
        "47,-97":{
            "2016-07-16":{
                "agdd":1894.0,
                "air_temp_max":77.0,
                "air_temp_min":58.0,
                "gdd":26.5,
                "current_stage":"v9.0"
            },...
        }
    },
    "harvest_window":{
        "end":"2016-08-12",
        "start":"2016-07-23"
    },
    "stage_descriptions":{
        "v9.0":{
            "advisor":"Harvest",
            "description":"Ripe"
        },...
    }
}

4.2. Canola Growth with GDD Envelope - v1.1

The Canola Growth with GDD Envelope service provides canola growth information in addition to GDD envelope data. GDD envelope calculation begins from either the current day, or the planted/emergence date, whichever is further in the future. The envelope is constructed by compiling the previous 10 years of weather data, and simulating the maximum and minimum GDD that would have accumulated within those 10 years for each date. The calculated minimum and maximum values are then added to the current start of calculation date AGDD going onwards to show range of possibilities.

4.2.1. URL Description

http://ag.us.clearapis.com/v1.1/crop_health/canola/growth/
gdd_envelope?app_id={string}&app_key={string}&plant_date={timestamp}
&location={lat, lon coordinates}&days={integer}&account_id={string}
&user_id={string}&growth_id={string}
&relative_maturity={string}

4.2.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” and “medium.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “medium” relative maturity are expected to mature relatively slowly. Default is “medium.”

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

4.2.3. Response Object (JSON)

Field Description

gdd

Growing degree days accumulated on the current date.

agdd

Aggregate growing degree days from plant date, including the current period’s date

current_stage

Current estimated stage of growth.

air_temp_min

Minimum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

air_temp_max

Maximum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

advisor

Suggested field properties to check.

description

Text description for a stage.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

agdd_envelope_max

Maximum observed agdd during the previous 10 years.

agdd_envelope_min

Minimum observed agdd during the previous 10 years.

agdd_envelope_min_year

Year that the agdd_envelope_min was observed.

agdd_envelope_max_year

Year that the agdd_envelope_max was observed.

4.2.4. Example Request

http://ag.us.clearapis.com/v1.1/crop_health/canola/growth/gdd_envelope?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800&days=160

4.2.5. Example Response

{
    "attribution":[
        "Based on a model presented by the North Dakota Agricultural Weather Network, but substantially modified."
    ],
    "data":{
        "32.509761735919426,-96.85546875":{
            "growth":{
                "2016-10-20":{
                    "agdd":105.5,
                    "agdd_envelope_max":105.5,
                    "agdd_envelope_max_year":"2015",
                    "agdd_envelope_min":105.5,
                    "agdd_envelope_min_year":"2015",
                    "air_temp_max":75.0,
                    "air_temp_min":60.0,
                    "gdd":26.5,
                    "last_stage":"n/a",
                    "new_stage":"n/a"
                },...
             },
            "harvest_window":{
                "end":"n/a",
                "start":"n/a"
            }
        }
    },
    "stage_descriptions":{
        "R3":{
            "advisor":"Nutrient",
            "description":"A rosette is formed: bigger, older leaves at the base and smaller, younger leaves in the center.",
            "images":[
                {
                    "attribution":"Courtesy of the Canola Council of Canada.",
                    "caption":"Two-leaf stage",
                    "url":"https://.../2leaf_150.jpg"
                },...
            ],
            "name":"Rosette - 3rd Leaf",
            "order":"2"
        },...
    }
}

4.3. Canola Growth Add Feedback - v1.0

By providing feedback relating to the growth stage estimates, Iteris will be able to make updates and adjustments to offer its users better results in the future. The given user providing feedback must have write privileges for the field in which the field growth belongs.

Additional information related to feedback timestamp, growth feedback, and feedback stage is available in the Feedback Information section of the Appendix.

4.3.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/canola/growth/feedback/add/
{growth_id}/{timestamp}/{stage}?account_id={string}&user_id={string}
&app_id={string}&app_key={string}

4.3.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

4.3.3. Response Object

A string representing a feedback ID.

4.3.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/canola/growth/feedback/add/
xyz/1472688000/R?account_id=abc&user_id=cba&app_id=123&app_key=321

4.3.5. Example Response

def-345

4.4. Canola Growth Modify Feedback - v1.0

The Canola Growth Modify Feedback endpoint allows users to modify previously provided growth stage estimate feedback. The given user providing feedback must have write privileges for the field in which the field growth belongs. At least one modification must be provided.

4.4.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/canola/growth/feedback/modify/
{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}&timestamp={integer}&stage={string}

4.4.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

4.4.3. Response Object

A string representing success (“true”) or failure (“false”).

4.4.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/canola/growth/feedback/
modify/abc-123?account_id=abc&user_id=cba&app_id=123&app_key=321
&timestamp=1472688000&stage=R

4.4.5. Example Response

true

4.5. Canola Growth Feedbacks by Growth - v1.1

Returns a list of growth feedback activities associated with the target growth_id.

4.5.1. URL Description

http://ag.us.clearapis.com/v1.1/crop_health/canola/growth/feedback/
get/by_growth/{growth_id}?app_id={string}&app_key={string}account_id={string}
&user_id={string}

4.5.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

4.5.3. Response Object (JSON)

Field Description

user_id

User ID provided by and used with the Accounts API.

created

Timestamp denoting when the feedback was created.

data

Information pertaining to the activity.

subtype

Enumeration value representing the specific variety of the activity. Defaults to 0.

growth_feedback_id

ID of target growth feedback.

type

Enumeration value of plant.

feedback/date

Unix timestamp denoting when the feedback happened2.

feedback/stage

Stage provided as feedback.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

4.5.4. Example Request

http://ag.us.clearapis.com/v1.1/crop_health/canola/growth/feedback/
get/by_growth/xyz?app_id=123&app_key=321&account_id=abc&user_id=cba

4.5.5. Example Response

[
    {
        "user_id":"1234",
        "feedback":{
            "date":1400371200,
            "type":59,
            "stage":"v1.0"
        },
        "created":1446229281,
        "data":"{}",
        "subtype":"0",
        "growth_feedback_id":"1111",
        "type":59
    },...
]

4.6. Canola Growth Delete Feedback - v1.0

This endpoint allows users to delete the previously provided growth stage estimate feedback. The given user deleting feedback must have write privileges for the field in which the field growth belongs.

4.6.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/canola/growth/feedback/
delete/{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}

4.6.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

4.6.3. Response Object

A string representing success (“true”) or failure (“false”).

4.6.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/canola/growth/
feedback/delete/abc-123?account_id=abc&user_id=cba
&app_id=123&app_key=321

4.6.5. Example Response

true

4.7. Canola In-Field Drydown - v1.0

Drawing from the ClearAg Field Weather API and canola growth model, the Canola In-Field Drydown endpoint simulates the drying process of canola seed in the field after the crop achieves full maturity, and provides daily seed moisture estimates during the drydown period. If Accounts API integration is used, any available moisture measurements are used to improve model results.

4.7.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/canola/infield_drydown?
app_id={string}&app_key={string}&location={lat, lon coordinates}
&plant_date={timestamp}&account_id={string}&user_id={string}&growth_id={string}
&relative_maturity={string}

4.7.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” and “medium.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “medium” relative maturity are expected to mature relatively slowly. Default is “medium.”

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

4.7.3. Response Object (JSON)

Field Description

attribution

Various model attributions.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures. Note that wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

advisor

Suggested field properties to check.

description

Text description for a stage.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Image URL.

name

Growth stage name.

order

Relative position of the stage within the growth scale.

4.7.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/canola/infield_drydown?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800

4.7.5. Example Response

{
    "attribution":[
        "Growth model based on a model presented by the North Dakota Agricultural Weather Network, but substantially modified."
    ],
    "data":{
        "39,-103":{
            "2016-04-14":{
                "agdd":410.0,
                "air_temp_max":75.0,
                "air_temp_min":42.0,
                "equilibrium_moisture_content":"n/a",
                "gdd":17.5,
                "grain_moisture_content":"n/a",
                "grain_moisture_content_change":"n/a",
                "last_stage":"S",
                "new_stage":"R3"
            },...
        }
    },
    "harvest_window":{
        "end":"2016-07-27",
        "start":"2016-07-07"
    },
    "stage_descriptions":{
        "S":{
            "advisor":"Nutrient",
            "description":"Emergence occurs when the seedling pushes through the soil surface.",
            "images":[
                {
                    "attribution":"Courtesy of the Canola Council of Canada.",
                    "caption":"Seedling (cotyledon)",
                    "url":"https://.../cotyledon_150.jpg"
                },...
            ],
            "name":"Emergence",
            "order":"1"
        },...
    }
}

4.8. Canola Nitrogen Advisor - v1.0

The ClearAg Canola Nitrogen Advisor simulates the various processes of the nitrogen cycle that impact the availability of nitrogen to canola crops. The model is based on a combination of proven algorithms from several industry models for simulating the nitrogen cycle. When used in combination with the Accounts API, the Canola Nitrogen Advisor allows provision of several types of field level activities, including fertilizer treatments and soil sample results, containing information such as soil nitrate and organic matter levels, as well as soil pH. Crop growth and the corresponding crop parameters of importance are simulated based on user-specified location, relative maturity, and planting date. Weather and soil information required by the Clear-N model are provided by the ClearAg Field Weather and Soil Conditions APIs, which provide a seamless global dataset of current, forecast, and historical conditions (dating back to 1980) for any arable location globally.

4.8.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/canola/nutrient/nitrogen?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&location={lat, lon coordinates}&plant_date={timestamp}
&yield_goal={integer}&yield_goal_unit={string}&previous_crop={integer}
&previous_harvest_date={timestamp}&previous_yield={integer}
&previous_yield_unit={string}&output_unit={string}&year_offset={integer}
&relative_maturity={string}

4.8.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Limited to a single location per query.

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the current crop was planted or the date of emergence2.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” and “medium.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “medium” relative maturity are expected to mature relatively slowly. Default is “medium.”

yield_goal

integer

yes

yes

Target yield for current crop.

yield_goal_unit

string

yes

yes

Target yield unit. Accepted values are “lb/ac,” “kg/ha,” or “bu/ac”.

previous_crop

integer

no

no

Enumeration value of previous crop on field. Accepted values are currently 50 (barley), 51 (corn), 57 (spring wheat), 59 (canola), 65 (cotton), 66 (soybean), 68 (winter wheat), 69 (vegetable), 70 (sorghum), 71 (pea), 72 (sunflower), 73 (rice), and 74 (alfalfa).

previous_harvest_date

timestamp

no

no

Epoch timestamp valid near the time that the previous crop was harvested2. Required if previous crop is specified. May not predate the planting or emergence date by more than 366 days.

previous_yield

integer

no

no

Actual yield of the previous crop. Required if previous crop is specified.

previous_yield_ unit

string

no

no

Previous yield unit. Accepted values are “lb/ac,” “kg/ha,” or “bu/ac.” Required if previous crop is specified. Note that “bu/ac” is not a valid yield unit for alfalfa, cotton, or vegetable.

output_unit

string

yes

yes

Specifies the unit of the area density data displayed. Accepted values are “lb/ac” or “kg/ha.”

year_offset

integer

no

no

Specifies a number of years by which to adjust model results. Values must be less than 0.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

4.8.3. Response Object (JSON)

Field Description

fertilizer_treatment

Structure holding all fertilizer treatment data utilized by the nitrogen model, including the fertilizer type, application rate, and depth.

soil_sample

Structure holding all soil sample data utilized by the nitrogen model, including the soil nitrate content, organic matter content, pH level, and sample depth.

tillage

Structure holding all tillage data utilized by the nitrogen model, including the tillage type and depth.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum air temperature valid for the current date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the timeframe.

air_temp_min

Minimum air temperature valid for the current date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the timeframe.

gdd

Growing degree days accumulated on the current date.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

ammonium,
ammonium_XtoY

The amount of nitrogen in the form of ammonium within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters.

ammonium_in_last_sample_depth

The modeled amount of ammonium above the depth of the previous soil sample.

nitrate,
nitrate_XtoY

The amount of nitrogen in the form of nitrate within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters.

nitrate_in_last_sample_depth

The modeled amount of nitrate above the depth of the previous soil sample.

applied_fertilizers,
applied_fertilizers_XtoY

The amount of nitrogen applied as fertilizer resident within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters3.

denitrified,
denitrified_XtoY

The amount of soil nitrate lost from the entire 2-meter depth of the modeled soil profile, or from within the layer spanning from depth=X to depth=Y centimeters, due to the process of denitrification, whereby nitrate is converted into nitrogen gas and then escapes into the atmosphere3.

immobilized,
immobilized_XtoY

The amount of nitrogen that has been immobilized within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters, in order to support mineralization of the previous crop’s residues3.

leached,
leached_XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning from depth=X to depth=Y centimeters, due to the process of leaching. Only losses will normally be seen when aggregated across the entire depth of the modeled soil profile; otherwise, some layers may gain nitrate at the expense of others, due to the vertical movement of water within the soil profile3.

leached_below_current_root_depth

The amount of soil nitrate that has been leached below the depth of the current crop’s roots as of the indicated date3.

leached_below_maximum_root_depth

The amount of soil nitrate that has been leached below the maximum depth that the current crop’s roots are expected to reach during the entirety of its growth cycle3.

realized_from_crop_organic_matter,
realized_from_crop_organic_matter_ XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, due to the process of mineralization of residues associated with the previous crop. This can be either positive or negative, depending on the carbon to nitrogen ratio of the previous crop’s residues3.

realized_from_soil_organic_matter,
realized_from_soil_organic_matter_ XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, due to the process of mineralization of soil organic matter. Since the carbon to nitrogen ratio of soil organic matter is typically below that associated with the diet of soil microbes, values will normally be positive3.

uptaken_by_crop,
uptaken_by_crop_XtoY

The amount of nitrogen uptaken by the crop from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters. If less than uptaken_by_crop_optimal, this can be indicative of a risk that the crop may be short of nitrogen3.

uptaken_by_crop_optimal,
uptaken_by_crop_optimal_XtoY

The amount of nitrogen the crop would have ideally taken up from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters3.

volatized,
volatized_XtoY

The amount of nitrogen lost by the process of volatization (also referred to as volatilization) from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, whereby urea fertilizer is converted into ammonia gas and then escapes into the atmosphere3.

applied_use_efficiency

The crop’s use efficiency of fertilizer-based nitrogen applied since the harvest of the previous crop. Values will be less than or equal to 100%, with higher percentages indicating that the crop has (or will) use a higher percentage of the fertilizers that have been applied.

applied_use_efficiency_unit

Units of “applied_use_efficiency.”

current_root_depth

The depth to which the current crop’s roots are assumed to reach as of the indicated date.

current_root_depth_unit

Units of “current_root_depth.” Chosen automatically based on the user-provided input value of “output_unit”.

indigenous_use_efficiency

The crop’s use efficiency of nitrogen realized through organic matter mineralization since the harvest of the previous crop. Values are in percentages, with higher percentages indicating that the crop has (or will) use a higher percentage of the nitrogen that has been realized through organic matter mineralization. Values in excess of 100% are possible.

indigenous_use_efficiency_unit

Units of “indigenous_use_efficiency.”

maximum_root_depth

The maximum depth to which the current crop’s roots are expected to reach during the entirety of its growth cycle.

maximum_root_depth_unit

Units of “maximum_root_depth.” Chosen automatically based on the user-provided input value of “output_unit.”

nitrogen_available_unit

Units of all data values in the "nitrogen_available" subsection of the returned JSON object.

nitrogen_budget_unit

Units of all data values in the "nitrogen_budget" subsection of the returned JSON object.

notes

A dictionary containing textual descriptions of noteworthy problems or occurrences on the indicated date.

uptake_score

A 0-100 score quantifying the adequacy of crop nitrogen uptake relative to the goals specified in the API call. Higher values indicate better uptake, with values at or near 100 being desirable in order to optimize the crop’s prospects for achieving the caller-specified yield_goal.

uptake_score_unit

Units of “uptake_score.”

advisor

Suggested field properties to check.

description

Text description for a growth stage.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Image URL.

name

Growth stage name.

order

Relative position of a stage within the growth scale.

3 Positive numeric values indicate that nitrogen has been gained by the soil due to the associated process, whereas negative numeric values indicate that nitrogen has been lost by the soil due to the associated process.

4.8.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/canola/nutrient/nitrogen?
app_id=123&app_key=321&account_id=abc&user_id=cba&growth_id=xyz
&previous_harvest_date=1450757200&previous_crop=51&previous_yield=1000
&previous_yield_unit=kg/ha&yield_goal=1050&yield_goal_unit=kg/ha
&output_unit=kg/ha

4.8.5. Example Response

{
    "activities":{
        "fertilizer_treatment":{
            "2016-05-20":[{
                "depth":0.5,
                "depth_unit":"m",
                "fertilizer_id":11,
                "rate":1.0,
                "rate_unit":"lb/ac"
            }]
        },
        "soil_sample":{
            "2016-05-20":[{
                "depth_unit":"m",
                "end_depth":1.0,
                "nitrate":3.0,
                "nitrate_unit":"kg/ha",
                "organic_matter":"n/a",
                "ph":"n/a",
                "start_depth":0.5
            }]
        },
        "tillage":{
            "2016-05-21":{
                "depth":0.1,
                "depth_unit":"m",
                "type":"conventional"
            }
        }
    },
    "data":{
        "2016-08-01":{
            "agdd":2125.5,
            "air_temp_max":79.0,
            "air_temp_min":65.0,
            "gdd":31.0,
            "last_stage":"ER",
            "new_stage":"R",
            "nitrogen_available":{
                "ammonium":0.0,
                "ammonium_0to2":0.0,
                "ammonium_100to200":0.0,
                "ammonium_10to20":0.0,
                "ammonium_20to40":0.0,
                "ammonium_2to5":0.0,
                "ammonium_40to70":0.0,
                "ammonium_5to10":0.0,
                "ammonium_70to100":0.0,
                "ammonium_in_last_sample_depth":"n/a",
                "nitrate":8.4,
                "nitrate_0to2":0.0,
                "nitrate_100to200":2.5,
                "nitrate_10to20":0.5,
                "nitrate_20to40":0.7,
                "nitrate_2to5":0.0,
                "nitrate_40to70":1.1,
                "nitrate_5to10":0.1,
                "nitrate_70to100":3.4,
                "nitrate_in_last_sample_depth":"n/a"
            },
            "nitrogen_budget":{
                "applied_fertilizers":0.0,
                "applied_fertilizers_0to2":0.0,
                "applied_fertilizers_100to200":0.0,
                "applied_fertilizers_10to20":0.0,
                "applied_fertilizers_20to40":0.0,
                "applied_fertilizers_2to5":0.0,
                "applied_fertilizers_40to70":0.0,
                "applied_fertilizers_5to10":0.0,
                "applied_fertilizers_70to100":0.0,
                "denitrified":0.0,
                "denitrified_0to2":0.0,
                "denitrified_100to200":0.0,
                "denitrified_10to20":0.0,
                "denitrified_20to40":0.0,
                "denitrified_2to5":0.0,
                "denitrified_40to70":0.0,
                "denitrified_5to10":0.0,
                "denitrified_70to100":0.0,
                "immobilized":-2.8,
                "immobilized_0to2":-2.1,
                "immobilized_100to200":-0.2,
                "immobilized_10to20":0.0,
                "immobilized_20to40":0.0,
                "immobilized_2to5":0.0,
                "immobilized_40to70":-0.2,
                "immobilized_5to10":0.0,
                "immobilized_70to100":-0.3,
                "leached":0.0,
                "leached_0to2":-2.3,
                "leached_100to200":0.7,
                "leached_10to20":-6.0,
                "leached_20to40":-0.6,
                "leached_2to5":-6.1,
                "leached_40to70":11.9,
                "leached_5to10":-4.8,
                "leached_70to100":7.3,
                "leached_below_current_root_depth":-0.6,
                "leached_below_maximum_root_depth":-0.6,
                "realized_from_crop_organic_matter":0.0,
                "realized_from_crop_organic_matter_0to2":0.0,
                "realized_from_crop_organic_matter_100to200":0.0,
                "realized_from_crop_organic_matter_10to20":0.0,
                "realized_from_crop_organic_matter_20to40":0.0,
                "realized_from_crop_organic_matter_2to5":0.0,
                "realized_from_crop_organic_matter_40to70":0.0,
                "realized_from_crop_organic_matter_5to10":0.0,
                "realized_from_crop_organic_matter_70to100":0.0,
                "realized_from_soil_organic_matter":29.2,
                "realized_from_soil_organic_matter_0to2":3.7,
                "realized_from_soil_organic_matter_100to200":2.3,
                "realized_from_soil_organic_matter_10to20":5.5,
                "realized_from_soil_organic_matter_20to40":6.0,
                "realized_from_soil_organic_matter_2to5":5.3,
                "realized_from_soil_organic_matter_40to70":1.9,
                "realized_from_soil_organic_matter_5to10":3.7,
                "realized_from_soil_organic_matter_70to100":0.8,
                "uptaken_by_crop":-37.1,
                "uptaken_by_crop_0to2":-0.1,
                "uptaken_by_crop_100to200":-0.2,
                "uptaken_by_crop_10to20":-3.2,
                "uptaken_by_crop_20to40":-12.5,
                "uptaken_by_crop_2to5":-0.4,
                "uptaken_by_crop_40to70":-15.4,
                "uptaken_by_crop_5to10":-0.8,
                "uptaken_by_crop_70to100":-4.5,
                "uptaken_by_crop_optimal":-523.5,
                "uptaken_by_crop_optimal_0to2":-8.5,
                "uptaken_by_crop_optimal_100to200":0.0,
                "uptaken_by_crop_optimal_10to20":-143.9,
                "uptaken_by_crop_optimal_20to40":-201.3,
                "uptaken_by_crop_optimal_2to5":-59.7,
                "uptaken_by_crop_optimal_40to70":-45.1,
                "uptaken_by_crop_optimal_5to10":-58.0,
                "uptaken_by_crop_optimal_70to100":-6.9,
                "volatized":0.0,
                "volatized_0to2":0.0,
                "volatized_100to200":0.0,
                "volatized_10to20":0.0,
                "volatized_20to40":0.0,
                "volatized_2to5":0.0,
                "volatized_40to70":0.0,
                "volatized_5to10":0.0,
                "volatized_70to100":0.0
            },
            "nitrogen_metadata":{
                "applied_use_efficiency":"n/a",
                "applied_use_efficiency_unit":"%",
                "current_root_depth":44.0,
                "current_root_depth_unit":"in",
                "indigenous_use_efficiency":126.9,
                "indigenous_use_efficiency_unit":"%",
                "maximum_root_depth":44.0,
                "maximum_root_depth_unit":"in",
                "nitrogen_available_unit":"lb/ac",
                "nitrogen_budget_unit":"lb/ac",
                "notes":{},
                "uptake_score":1.0,
                "uptake_score_unit":"%"
            }
        },...
    },
    "stage_descriptions":{
        "R":{
            "advisor":"Harvest",
            "description":"About one third of the seeds on the main stem have changed color; the crop is ready to swath.",
            "images":[
                {
                    "attribution":"Courtesy of Oklahoma State University.",
                    "caption":"Mature",
                    "url":"https://.../ripening4.png"
                },...
            ],
            "name":"Ripe",
            "order":"9"
        }
    }
}

4.9. Canola Mechanical Drying - v1.0

The Canola Mechanical Drying endpoint simulates the drydown process of canola using either fan-powered low-temperature drying or burner-driven high-temperature drying facilities to provide drying statistics and cost projections. The mechanical drying process is simulated using up to 10 future days of grain moisture estimates. Results from the canola in-field drying model are also returned for comparison.

Note that a field, growth, and drying facility are required to utilize this feature. Any available seed moisture measurements are used to improve model results.

Please be aware that mechanical drying data will not be returned if seed moisture estimates are unable to be obtained from the canola in-field drying model. This may occur if one of the following conditions are met:

  • The canola growth model simulation does not bring the crop to maturity. This is more likely to occur for certain location (e.g., cooler climates) and relative maturity combinations.

  • The crop planting date or emergence date are too far in the past. The models are designed for future planning; users can utilize the “current_date” argument to determine what model results could have been on a past date. These results can be different than what would have been seen on the emulated date, as the forecast timeframes are now represented by historical data.

4.9.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/canola/mechanical_drying?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&drying_facility_ids={string}&grain_unit={string}
&target_moisture_content_wb={float}&current_date={timestamp}

4.9.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Accounts API ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have read privileges for the field in which the growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field.

target_moisture_ content_wb

float

yes

Numeric representation of the desired moisture level for safe storage, measured in percent on a wet basis. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

grain_unit

string

yes

Units to use when returning unit costs of drying. Valid values are “bu” (bushel) and “mt” (metric ton).

drying_facility_ids

string

no

Comma-delimited list of drying facility IDs to be used. Currently, only the most recently created facility in the list will be used. Default behavior is to use the most recently created facility overall. Note that the calling user must have at least read privileges for the asset (drying facility).

current_date

timestamp

no

Emulate model results as if viewed on this date2. Useful for viewing approximate model results for historical timeframes greater than one year in the past. There can be differences in results due to what would have been forecasted weather data now being replaced with historical or climatological data used in the calculations.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

4.9.3. Response Object (JSON)

Field Description

asset_id

The ID given to a particular drying facility.

name

The user-provided name of the drying facility. If this is not supplied, a generic name of “Drying Facility” followed by a number is used.

burner_fuel_type

Type of fuel consumed by the burner, as provided by the Accounts API.

burner_fuel_unit

Unit of measure associated with the fuel type, as provided by the Accounts API.

driest_datetime

Time that the grain reached its lowest moisture content of the model run. Represented by a date string in the case of low-temperature drying or hours and minutes in the case of high-temperature drying. Note that the simulation will stop when the user-specified target moisture content is reached, in which case this will indicate the timing of the grain reaching that threshold.

driest_moisture_content_db

Driest dry-basis grain moisture content of the simulation, in percent. Dry-basis moisture content is defined as the ratio of the mass of water to the dry mass of a sample of grain.

driest_moisture_content_wb

Driest wet-basis grain moisture content of the simulation, in percent. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

dryer_throughput_grain_units_ per_hour

Amount of grain dried per hour. Applicable only in high-temperature drying facilities.

drying_time

Amount of time, in seconds, that elapsed for the grain to reach its lowest moisture content.

grain_storability

Likelihood of spoilage. Possible values include “0,” indicating that grain is not likely to spoil; “1,” indicating a marginal risk; and “2,” warning that spoilage is likely. When high-temperature drying is in use, “n/a” will be used.

grain_unit

Unit of measure associated with the volume of grain as provided by the user.

per_grain_unit/burner_fuel_ cost

Expected burner fuel cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/burner_fuel_ units_consumed

Expected amount of fuel consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/burner_kwh_ consumed

Expected amount of fuel energy, in kilowatt-hours, consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/electricity_cost

Expected electricity cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/electricity_kwh_ consumed

Expected amount of electrical energy, in kilowatt-hours, consumed by the fan per unit of grain, in the grain unit provided by the user.

per_grain_unit/total_cost

Expected total drying cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit_per_percent_ moisture/total_cost

Expected total drying cost per unit of grain per percent moisture change, in the user’s local currency, and in the grain unit provided by the user.

sample_datetime

Valid time of the grain moisture sample provided by the in-field drydown model.

sample_moisture_content_wb

Starting wet-basis moisture content of the grain sample, in percent, provided by the in-field drydown model.

simulation_length

Total length of time, in seconds, over which the drydown process was modeled.

target_moisture_reached

Flag indicating whether the target storage moisture content is reached in the simulation, where “1” indicates that the storage moisture is reached and “0” indicates it is not. Primarily applicable in low-temperature drying facilities, where ambient environmental conditions may not permit an adequate amount of drying.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum daily air temperature, which may be a historical, forecast, or climatological value, depending on the timeframe.

air_temp_min

Minimum daily air temperature, which may be a historical, forecast, or climatological value, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures.

feedback_id

If this field is present, it indicates a confirmed or observed growth stage on the current date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

4.9.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/canola/mechanical_drying?
app_id=123&app_key=321&account_id=abc&user_id=cba&growth_id=xyz
&grain_unit=bu&target_moisture_content_wb=14.5

4.9.5. Example Response

{
    "drying_facilities":[
        {
            "asset_id":"abc-123",
            "data":[
                {
                    "burner_fuel_type":"liquid_propane",
                    "burner_fuel_unit":"gallon",
                    "driest_datetime":"01:32",
                    "driest_moisture_content_db":16.96,
                    "driest_moisture_content_wb":14.5,
                    "dryer_throughput_grain_units_per_hour":922.0,
                    "drying_time":5540,
                    "grain_storability":"n/a",
                    "grain_unit":"bu",
                    "per_grain_unit":{
                        "burner_fuel_cost":0.168,
                        "burner_fuel_units_consumed":0.186,
                        "burner_kwh_consumed":4.6,
                        "electricity_cost":0.395,
                        "electricity_kwh_consumed":0.79,
                        "total_cost":0.563
                    },
                    "per_grain_unit_per_percent_moisture":{
                        "total_cost":0.031
                    },
                    "sample_datetime":"2016-07-16",
                    "sample_moisture_content_wb":32.87,
                    "simulation_length":5540,
                    "target_moisture_reached":1
                },...
            ],
            "name":"Canola Dryer"
        }
    ],
    "infield_drydown_data":{
        "47,-97":{
            "2016-07-16":{
                "agdd":1894.0,
                "air_temp_max":77.0,
                "air_temp_min":58.0,
                "equilibrium_moisture_content":6.32,
                "gdd":26.5,
                "grain_moisture_content":32.87,
                "grain_moisture_content_change":"n/a",
                "last_stage":"ER",
                "new_stage":"R"
            },...
        }
    }
}

5. Sugar Beet

5.1. Sugar Beet Growth - v1.0

Leveraging Iteris’ sugar beet growth stage model, the Sugar Beet Growth endpoint allows users to model the maturation and development of sugar beet crops. Users may also take advantage of Accounts API integration to provide crop growth feedback and optimize model results.

5.1.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sugarbeet/growth?app_id={string}
&app_key={string}&location={lat, lon coordinates}&plant_date={timestamp}
&days={integer}&account_id={string}&user_id={string}&growth_id={string}

5.1.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

5.1.3. Response Object (JSON)

Field Description

gdd

Growing degree days accumulated on the current date.

agdd

Aggregate growing degree days from plant date, including the current period’s date

air_temp_min

Minimum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

air_temp_max

Maximum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

last_stage

The last known growth stage. If no valid stage has been reached, this value will be “n/a.” This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

new_stage

The crop is expected to have entered a new growth stage between the current period’s date and the previous period’s date.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

advisor

Suggested field properties to check.

stage

Text description for a stage.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

5.1.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sugarbeet/growth?app_id=123&app_key=321
&location=47,-97&plant_date=1462060800&days=160

5.1.5. Example Response

{
    "data":{
        "47,-97":{
            "2016-05-29":{
                "agdd":735.5,
                "air_temp_max":80.0,
                "air_temp_min":57.0,
                "gdd":34.5,
                "last_stage":"v2.0",
                "new_stage":"v3.0"
            },...
        }
    },
    "harvest_window":{
        "end":"2016-07-28",
        "start":"2016-06-26"
    },
    "stage_descriptions":{
        "v2.0":{
            "advisor":"n/a",
            "stage":"Two true leaves unrolled and no evidence of three leaf stage. These are the first two leaves that develop simultaneously. At this stage and subsequent stages the cotyledons are no longer counted as leaves"
        },...
    }
}

5.2. Sugar Beet Growth with GDD Envelope - v1.1

The Sugar Beet Growth with GDD Envelope service provides sugar beet growth information in addition to GDD envelope data. GDD envelope calculation begins from either the current day, or the planted/emergence date, whichever is further in the future. The envelope is constructed by compiling the previous 10 years of weather data, and simulating the maximum and minimum GDD that would have accumulated within those 10 years for each date. The calculated minimum and maximum values are then added to the current start of calculation date AGDD going onwards to show range of possibilities.

5.2.1. URL Description

http://ag.us.clearapis.com/v1.1/crop_health/sugarbeet/growth/
gdd_envelope?app_id={string}&app_key={string}&plant_date={timestamp}
&location={lat, lon coordinates}&days={integer}&account_id={string}
&user_id={string}&growth_id={string}

5.2.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

5.2.3. Response Object (JSON)

Field Description

gdd

Growing degree days accumulated on the current date.

agdd

Aggregate growing degree days from plant date, including the current period’s date

air_temp_min

Minimum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

air_temp_max

Maximum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

last_stage

The last known growth stage. If no valid stage has been reached, this value will be “n/a.” This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

new_stage

The crop is expected to have entered a new growth stage between the current period’s date and the previous period’s date.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

advisor

Suggested field properties to check.

stage

Text description for a stage.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

agdd_envelope_max

Maximum observed agdd during the previous 10 years.

agdd_envelope_min

Minimum observed agdd during the previous 10 years.

agdd_envelope_min_year

Year that the agdd_envelope_min was observed.

agdd_envelope_max_year

Year that the agdd_envelope_max was observed.

5.2.4. Example Request

http://ag.us.clearapis.com/v1.1/crop_health/sugarbeet/growth/gdd_envelope?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800&days=160

5.2.5. Example Response

{
    "attribution":[
        "Based on a model presented by the North Dakota Agricultural Weather Network."
    ],
    "data":{
        "32.509761735919426,-96.85546875":{
            "growth":{
                "2016-10-27":{
                    "agdd":363.5,
                    "agdd_envelope_max":386.0,
                    "agdd_envelope_max_year":"2014",
                    "agdd_envelope_min":295.5,
                    "agdd_envelope_min_year":"2009",
                    "air_temp_max":82.0,
                    "air_temp_min":64.0,
                    "gdd":39.0,
                    "last_stage":"v1.0",
                    "new_stage":"n/a"
                },...
            },
            "harvest_window":{
                "end":"n/a",
                "start":"n/a"
            }
        }
    },
    "stage_descriptions":{
        "v1.0":{
            "advisor":"Nutrient",
            "description":"Emergence occurs when the seedling pushes through the soil surface.",
            "images":[],
            "name":"Emergence",
            "order":"1"
        },...
    }
}

5.3. Sugar Beet Growth Add Feedback - v1.0

By providing feedback relating to the growth stage estimates, Iteris will be able to make updates and adjustments to offer its users better results in the future. The given user providing feedback must have write privileges for the field in which the field growth belongs.

Additional information related to feedback timestamp, growth feedback, and feedback stage is available in the Feedback Information section of the Appendix.

5.3.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sugarbeet/growth/feedback/add/
{growth_id}/{timestamp}/{stage}?account_id={string}&user_id={string}
&app_id={string}&app_key={string}

5.3.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

5.3.3. Response Object

A string representing a feedback ID.

5.3.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sugarbeet/growth/feedback/add/
xyz/1472688000/v9.0?account_id=abc&user_id=cba&app_id=123&app_key=321

5.3.5. Example Response

def-345

5.4. Sugar Beet Growth Feedbacks by Growth - v1.0

Returns a list of growth feedback activities associated with the target growth_id.

5.4.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sugarbeet/growth/feedback/
get/by_growth/{growth_id}?app_id={string}&app_key={string}account_id={string}
&user_id={string}

5.4.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

5.4.3. Response Object (JSON)

Field Description

user_id

User ID provided by and used with the Accounts API.

created

Timestamp denoting when the feedback was created.

data

Information pertaining to the activity.

subtype

Enumeration value representing the specific variety of the activity. Defaults to 0.

growth_feedback_id

ID of target growth feedback.

type

Enumeration value of plant.

feedback/date

Unix timestamp denoting when the feedback happened2.

feedback/stage

Stage provided as feedback.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

5.4.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sugarbeet/growth/feedback/
get/by_growth/xyz?app_id=123&app_key=321&account_id=abc&user_id=cba

5.4.5. Example Response

[
    {
        "user_id":"1234",
        "feedback":{
            "date":1400371200,
            "type":60,
            "stage":"v1.0"
        },
        "created":1446229281,
        "data":"{}",
        "subtype":"0",
        "growth_feedback_id":"1111",
        "type":60
    },...
]

5.5. Sugar Beet Growth Modify Feedback - v1.0

The Sugar Beet Growth Modify Feedback endpoint allows users to modify previously provided growth stage estimate feedback. The given user providing feedback must have write privileges for the field in which the field growth belongs. At least one modification must be provided.

5.5.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sugarbeet/growth/feedback/modify/
{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}&timestamp={integer}&stage={string}

5.5.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

5.5.3. Response Object

A string representing success (“true”) or failure (“false”).

5.5.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sugarbeet/growth/feedback/
modify/abc-123?account_id=abc&user_id=cba&app_id=123&app_key=321
&timestamp=1472688000&stage=v9.0

5.5.5. Example Response

true

5.6. Sugar Beet Growth Delete Feedback - v1.0

This endpoint allows users to delete the previously provided growth stage estimate feedback. The given user deleting feedback must have write privileges for the field in which the field growth belongs.

5.6.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sugarbeet/growth/feedback/
delete/{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}

5.6.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

5.6.3. Response Object

A string representing success (“true”) or failure (“false”).

5.6.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sugarbeet/growth/
feedback/delete/abc-123?account_id=abc&user_id=cba
&app_id=123&app_key=321

5.6.5. Example Response

true

6. Barley

6.1. Barley Growth - v1.0

Leveraging Iteris’ spring barley growth stage model, the Barley Growth endpoint allows users to model the maturation and development of spring barley crops. Users may also take advantage of Accounts API integration to provide crop growth feedback and optimize model results.

6.1.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/barley/growth?app_id={string}
&app_key={string}&location={lat, lon coordinates}&plant_date={timestamp}
&days={integer}&account_id={string}&user_id={string}&growth_id={string}
&relative_maturity={string}

6.1.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” “medium,” “medium-late”, and “late.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

6.1.3. Response Object (JSON)

Field Description

agdd

Aggregate growing degree days from plant date, including the current date.

air_temp_max

Maximum air temperature valid for the current date, in Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum air temperature valid for the current date, in Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

feedback_id

If this field is present, it indicates a confirmed or observed growth stage on the current date.

gdd

Growing degree days accumulated on the current date.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

harvest_window/end

Expected end date for harvest operations.

harvest_window/start

Expected start date for harvest operations.

advisor

Suggested field properties to check.

stage

The current growth stage, derived using the Haun barley growth-stage scale.

6.1.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/barley/growth?app_id=123&app_key=321
&location=47,-97&plant_date=1462060800&days=160

6.1.5. Example Response

{
    "data":{
        "47,-97":{
            "2016-07-09":{
                "agdd":2283.0,
                "air_temp_max":82.0,
                "air_temp_min":56.0,
                "gdd":37.0,
                "last_stage":"13.0",
                "new_stage":"15.0"
            },...
        }
    },
    "harvest_window":{
        "end":"2016-08-09",
        "start":"2016-07-19"
    },
    "stage_descriptions":{
        "15.0":{
            "advisor":"Harvest",
            "stage":"Dry weight of the kernels stops increasing."
        },...
    }
}

6.2. Barley Growth with GDD Envelope - v1.1

The Barley Growth with GDD Envelope service provides spring barley growth information in addition to GDD envelope data. GDD envelope calculation begins from either the current day, or the planted/emergence date, whichever is further in the future. The envelope is constructed by compiling the previous 10 years of weather data, and simulating the maximum and minimum GDD that would have accumulated within those 10 years for each date. The calculated minimum and maximum values are then added to the current start of calculation date AGDD going onwards to show range of possibilities.

6.2.1. URL Description

http://ag.us.clearapis.com/v1.1/crop_health/barley/growth/
gdd_envelope?app_id={string}&app_key={string}&plant_date={timestamp}
&location={lat, lon coordinates}&days={integer}&account_id={string}
&user_id={string}&growth_id={string}
&relative_maturity={string}

6.2.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” “medium,” “medium-late”, and “late.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

6.2.3. Response Object (JSON)

Field Description

gdd

Growing degree days accumulated on the current date.

agdd

Aggregate growing degree days from plant date, including the current period’s date.

air_temp_min

Minimum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

air_temp_max

Maximum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

last_stage

The last known growth stage. If no valid stage has been reached, this value will be “n/a.” This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

new_stage

The crop is expected to have entered a new growth stage between the current period’s date and the previous period’s date.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

advisor

Suggested field properties to check.

stage

The current growth stage, derived using the Haun barley growth-stage scale.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

agdd_envelope_max

Maximum observed agdd during the previous 10 years.

agdd_envelope_min

Minimum observed agdd during the previous 10 years.

agdd_envelope_min_year

Year that the agdd_envelope_min was observed.

agdd_envelope_max_year

Year that the agdd_envelope_max was observed.

6.2.4. Example Request

http://ag.us.clearapis.com/v1.1/crop_health/barley/growth/gdd_envelope?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800&days=160

6.2.5. Example Response

{
    "data":{
        "32.509761735919426,-96.85546875":{
            "growth":{
                "2016-10-20":{
                    "agdd":111.5,
                    "agdd_envelope_max":111.5,
                    "agdd_envelope_max_year":"2015",
                    "agdd_envelope_min":111.5,
                    "agdd_envelope_min_year":"2015",
                    "air_temp_max":75.0,
                    "air_temp_min":60.0,
                    "gdd":33.0,
                    "last_stage":"n/a",
                    "new_stage":"n/a"
                },...
            },
            "harvest_window":{
                "end":"n/a",
                "start":"n/a"
            }
        }
    },
    "stage_descriptions":{
        "0.5":{
            "advisor":"Nutrient",
            "description":"Emergence",
            "order":"2"
        },...
    }
}

6.3. Barley Growth Add Feedback - v1.0

By providing feedback relating to the growth stage estimates, Iteris will be able to make updates and adjustments to offer its users better results in the future. The given user providing feedback must have write privileges for the field in which the field growth belongs.

Additional information related to feedback timestamp, growth feedback, and feedback stage is available in the Feedback Information section of the Appendix.

6.3.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/barley/growth/feedback/add/
{growth_id}/{timestamp}/{stage}?account_id={string}&user_id={string}
&app_id={string}&app_key={string}

6.3.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

6.3.3. Response Object

A string representing a feedback ID.

6.3.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/barley/growth/feedback/add/
xyz/1472688000/15.0?account_id=abc&user_id=cba&app_id=123&app_key=321

6.3.5. Example Response

def-345

6.4. Barley Growth Feedbacks by Growth - v1.0

Returns a list of growth feedback activities associated with the target growth_id.

6.4.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/barley/growth/feedback/
get/by_growth/{growth_id}?app_id={string}&app_key={string}account_id={string}
&user_id={string}

6.4.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

6.4.3. Response Object (JSON)

Field Description

user_id

User ID provided by and used with the Accounts API.

created

Timestamp denoting when the feedback was created.

data

Information pertaining to the activity.

subtype

Enumeration value representing the specific variety of the activity. Defaults to 0.

growth_feedback_id

ID of target growth feedback.

type

Enumeration value of plant.

feedback/date

Unix timestamp denoting when the feedback happened2.

feedback/stage

Stage provided as feedback.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

6.4.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/barley/growth/feedback/
get/by_growth/xyz?app_id=123&app_key=321&account_id=abc&user_id=cba

6.4.5. Example Response

[
    {
        "user_id":"1234",
        "feedback":{
            "date":1400371200,
            "type":50,
            "stage":"1.0"
        },
        "created":1446229281,
        "data":"{}",
        "subtype":"0",
        "growth_feedback_id":"1111",
        "type":50
    },...
]

6.5. Barley Growth Modify Feedback - v1.0

The Barley Growth Modify Feedback endpoint allows users to modify previously provided growth stage estimate feedback. The given user providing feedback must have write privileges for the field in which the field growth belongs. At least one modification must be provided.

6.5.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/barley/growth/feedback/modify/
{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}&timestamp={integer}&stage={string}

6.5.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

6.5.3. Response Object

A string representing success (“true”) or failure (“false”).

6.5.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/barley/growth/feedback/
modify/abc-123?account_id=abc&user_id=cba&app_id=123&app_key=321
&timestamp=1472688000&stage=15.0

6.5.5. Example Response

true

6.6. Barley Growth Delete Feedback - v1.0

This endpoint allows users to delete the previously provided growth stage estimate feedback. The given user deleting feedback must have write privileges for the field in which the field growth belongs.

6.6.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/barley/growth/feedback/
delete/{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}

6.6.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

6.6.3. Response Object

A string representing success (“true”) or failure (“false”).

6.6.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/barley/growth/
feedback/delete/abc-123?account_id=abc&user_id=cba
&app_id=123&app_key=321

6.6.5. Example Response

true

6.7. Barley In-Field Drydown - v1.0

Drawing from the ClearAg Field Weather API and spring barley growth model, the Barley In-Field Drydown endpoint simulates the drying process of spring barley grain in the field after the crop achieves full maturity, and provides daily grain moisture estimates during the drydown period. If Accounts API integration is used, any available moisture measurements are used to improve model results.

6.7.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/barley/infield_drydown?
app_id={string}&app_key={string}&location={lat, lon coordinates}
&plant_date={timestamp}&account_id={string}&user_id={string}&growth_id={string}
&relative_maturity={string}

6.7.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” “medium,” “medium-late”, and “late.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

6.7.3. Response Object (JSON)

Field Description

attribution

Various model attributions.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures. Note that wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

advisor

Suggested field properties to check.

description

Text description for a stage.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Image URL.

name

Growth stage name.

order

Relative position of the stage within the growth scale.

6.7.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/barley/infield_drydown?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800

6.7.5. Example Response

{
    "attribution":[
        "Growth model based on a model presented by the North Dakota Agricultural Weather Network, but substantially modified."
    ],
    "data":{
        "39,-103":{
            "2016-06-06":{
                "agdd":1757.0,
                "air_temp_max":82.0,
                "air_temp_min":54.0,
                "equilibrium_moisture_content":"n/a",
                "gdd":36.0,
                "grain_moisture_content":"n/a",
                "grain_moisture_content_change":"n/a",
                "last_stage":"11.0",
                "new_stage":"11.5"
            },...
        }
    },
    "harvest_window":{
        "end":"2016-07-29",
        "start":"2016-07-08"
    },
    "stage_descriptions":{
        "11.5":{
            "advisor":"Harvest",
            "description":"Kernel width and length are set; not much dry matter has accumulated.",
            "images":[
                {
                    "attribution":"Courtesy of David L. Hansen, University of Minnesota.",
                    "caption":"Watery ripe",
                    "url":"https://.../Watery_ripe.png"
                },...
            ],
            "name":"11.5 - Kernel Watery Ripe",
            "order":"14"
        },...
    }
}

6.8. Barley Mechanical Drying - v1.0

The Barley Mechanical Drying endpoint simulates the drydown process of spring barley using either fan-powered low-temperature drying or burner-driven high-temperature drying facilities to provide drying statistics and cost projections. The mechanical drying process is simulated using up to 10 future days of grain moisture estimates. Results from the spring barley in-field drying model are also returned for comparison.

Note that a field, growth, and drying facility are required to utilize this feature. Any available grain moisture measurements are used to improve model results.

Please be aware that mechanical drying data will not be returned if grain moisture estimates are unable to be obtained from the spring barley in-field drying model. This may occur if one of the following conditions are met:

  • The spring barley growth model simulation does not bring the crop to maturity. This is more likely to occur for certain location (e.g., cooler climates) and relative maturity combinations.

  • The crop planting date or emergence date are too far in the past. The models are designed for future planning; users can utilize the “current_date” argument to determine what model results could have been on a past date. These results can be different than what would have been seen on the emulated date, as the forecast timeframes are now represented by historical data.

6.8.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/barley/mechanical_drying?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&drying_facility_ids={string}&grain_unit={string}
&target_moisture_content_wb={float}&current_date={timestamp}

6.8.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Accounts API ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have read privileges for the field in which the growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field.

target_moisture_ content_wb

float

yes

Numeric representation of the desired moisture level for safe storage, measured in percent on a wet basis. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

grain_unit

string

yes

Units to use when returning unit costs of drying. Valid values are “bu” (bushel) and “mt” (metric ton).

drying_facility_ids

string

no

Comma-delimited list of drying facility IDs to be used. Currently, only the most recently created facility in the list will be used. Default behavior is to use the most recently created facility overall. Note that the calling user must have at least read privileges for the asset (drying facility).

current_date

timestamp

no

Emulate model results as if viewed on this date2. Useful for viewing approximate model results for historical timeframes greater than one year in the past. There can be differences in results due to what would have been forecasted weather data now being replaced with historical or climatological data used in the calculations.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

6.8.3. Response Object (JSON)

Field Description

asset_id

The ID given to a particular drying facility.

name

The user-provided name of the drying facility. If this is not supplied, a generic name of “Drying Facility” followed by a number is used.

burner_fuel_type

Type of fuel consumed by the burner, as provided by the Accounts API.

burner_fuel_unit

Unit of measure associated with the fuel type, as provided by the Accounts API.

driest_datetime

Time that the grain reached its lowest moisture content of the model run. Represented by a date string in the case of low-temperature drying or hours and minutes in the case of high-temperature drying. Note that the simulation will stop when the user-specified target moisture content is reached, in which case this will indicate the timing of the grain reaching that threshold.

driest_moisture_content_db

Driest dry-basis grain moisture content of the simulation, in percent. Dry-basis moisture content is defined as the ratio of the mass of water to the dry mass of a sample of grain.

driest_moisture_content_wb

Driest wet-basis grain moisture content of the simulation, in percent. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

dryer_throughput_grain_units_ per_hour

Amount of grain dried per hour. Applicable only in high-temperature drying facilities.

drying_time

Amount of time, in seconds, that elapsed for the grain to reach its lowest moisture content.

grain_storability

Likelihood of spoilage. Possible values include “0,” indicating that grain is not likely to spoil; “1,” indicating a marginal risk; and “2,” warning that spoilage is likely. When high-temperature drying is in use, “n/a” will be used.

grain_unit

Unit of measure associated with the volume of grain as provided by the user.

per_grain_unit/burner_fuel_ cost

Expected burner fuel cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/burner_fuel_ units_consumed

Expected amount of fuel consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/burner_kwh_ consumed

Expected amount of fuel energy, in kilowatt-hours, consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/electricity_cost

Expected electricity cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/electricity_kwh_ consumed

Expected amount of electrical energy, in kilowatt-hours, consumed by the fan per unit of grain, in the grain unit provided by the user.

per_grain_unit/total_cost

Expected total drying cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit_per_percent_ moisture/total_cost

Expected total drying cost per unit of grain per percent moisture change, in the user’s local currency, and in the grain unit provided by the user.

sample_datetime

Valid time of the grain moisture sample provided by the in-field drydown model.

sample_moisture_content_wb

Starting wet-basis moisture content of the grain sample, in percent, provided by the in-field drydown model.

simulation_length

Total length of time, in seconds, over which the drydown process was modeled.

target_moisture_reached

Flag indicating whether the target storage moisture content is reached in the simulation, where “1” indicates that the storage moisture is reached and “0” indicates it is not. Primarily applicable in low-temperature drying facilities, where ambient environmental conditions may not permit an adequate amount of drying.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum daily air temperature, which may be a historical, forecast, or climatological value, depending on the timeframe.

air_temp_min

Minimum daily air temperature, which may be a historical, forecast, or climatological value, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures.

feedback_id

If this field is present, it indicates a confirmed or observed growth stage on the current date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

6.8.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/barley/mechanical_drying?
app_id=123&app_key=321&account_id=abc&user_id=cba&growth_id=xyz
&grain_unit=bu&target_moisture_content_wb=14.5

6.8.5. Example Response

{
    "drying_facilities":[
        {
            "asset_id":"abc-123",
            "data":[
                {
                    "burner_fuel_type":"liquid_propane",
                    "burner_fuel_unit":"gallon",
                    "driest_datetime":"02:38",
                    "driest_moisture_content_db":16.95,
                    "driest_moisture_content_wb":14.49,
                    "dryer_throughput_grain_units_per_hour":537.0,
                    "drying_time":9505,
                    "grain_storability":"n/a",
                    "grain_unit":"bu",
                    "per_grain_unit":{
                        "burner_fuel_cost":0.233,
                        "burner_fuel_units_consumed":0.259,
                        "burner_kwh_consumed":6.39,
                        "electricity_cost":0.209,
                        "electricity_kwh_consumed":0.42,
                        "total_cost":0.442
                    },
                    "per_grain_unit_per_percent_moisture":{
                        "total_cost":0.023
                    },
                    "sample_datetime":"2016-07-07",
                    "sample_moisture_content_wb":33.77,
                    "simulation_length":9505,
                    "target_moisture_reached":1
                },...
            ],
            "name":"Barley Dryer"
        }
    ],
    "infield_drydown_data":{
        "47,-97":{
            "2016-07-07":{
                "agdd":2208.0,
                "air_temp_max":78.0,
                "air_temp_min":64.0,
                "equilibrium_moisture_content":12.18,
                "gdd":39.0,
                "grain_moisture_content":33.77,
                "grain_moisture_content_change":"n/a",
                "last_stage":13.0,
                "new_stage":15.0
            },...
        }
    }
}

7. Soybean

7.1. Soybean Growth - v1.0

Leveraging Iteris’ soybean growth stage model, the Soybean Growth endpoint allows users to model the maturation and development of soybean crops. Users may also take advantage of Accounts API integration to provide crop growth feedback and optimize model results.

7.1.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/soybean/growth?app_id={string}
&app_key={string}&location={lat, lon coordinates}&plant_date={timestamp}
&days={integer}&account_id={string}&user_id={string}&growth_id={string}
&maturity_group={float}&plant_depth={float}

7.1.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

maturity_group

float

no

 — 

Classification indicating how early a variety matures. Valid values range from 2.0 to 4.5, with a lower number indicating an earlier maturity and a higher number indicating a later maturity. Default is 3.0.

plant_depth

float

no

 — 

The depth (in cm) that the crop was planted. Valid values range from 0.1 to 4.9 cm. Default is 3.5.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

7.1.3. Response Object (JSON)

Field Description

agdd

Aggregate growing degree days from plant date, including the current period’s date. (Only used or returned from plant date to emergence).

air_temp_avg

Average daily air temperature valid for the current period’s date. This value is obtained by adding the daily minimum air temperature and daily maximum air temperature and dividing that value by two. These values are obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

gdd

Growing degree days accumulated on the current date.

last_reproductive_stage

The last known reproductive stage. If no valid stage has been reached, this value will be “n/a.”

last_vegetative_stage

The last known vegetative stage. If no valid stage has been reached, this value will be “n/a.”

new_reproductive_stage

The crop is expected to have entered a new reproductive stage between the current period’s date and the previous period’s date.

new_vegetative_stage

The crop is expected to have entered a new vegetative stage between the current period’s date and the previous period’s date.

relative_humidity_avg

Average daily relative humidity provided as a percentage.

last_stage

The last known growth stage. If no valid stage has been reached, this value will be “n/a.” This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

new_stage

The crop is expected to have entered a new growth stage between the current period’s date and the previous period’s date. This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

advisor

Suggested field properties to check.

description

Text description for a stage.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

7.1.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/soybean/growth?app_id=123&app_key=321
&location=47,-97&plant_date=1462060800&days=160

7.1.5. Example Response

{
    "data":{
        "47,-97":{
            "2016-05-25":{
                "agdd":258.58,
                "air_temp_avg":64.0,
                "gdd":13.02,
                "last_reproductive_stage":"n/a",
                "last_stage":"VE",
                "last_vegetative_stage":"VE",
                "new_reproductive_stage":"n/a",
                "new_stage":"V0",
                "new_vegetative_stage":"V0",
                "relative_humidity_avg":75.14
            },...
        }
    },
    "harvest_window":{
        "end":"2016-10-23",
        "start":"2016-09-28"
    },
    "stage_descriptions":{
        "VE":{
            "advisor":"Nutrient",
            "description":"Emergence"
        },...
    }
}

7.2. Soybean Growth with GDD Envelope - v1.0

The Soybean Growth with GDD Envelope service provides soybean growth information in addition to GDD envelope data. GDD envelope calculation begins from either the current day, or the planted/emergence date, whichever is further in the future. The envelope is constructed by compiling the previous 10 years of weather data, and simulating the maximum and minimum GDD that would have accumulated within those 10 years for each date. The calculated minimum and maximum values are then added to the current start of calculation date AGDD going onwards to show range of possibilities.

7.2.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/soybean/growth/
gdd_envelope?app_id={string}&app_key={string}&plant_date={timestamp}
&location={lat, lon coordinates}&days={integer}&account_id={string}
&user_id={string}&growth_id={string}
&maturity_group={float}&plant_depth={float}

7.2.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

maturity_group

float

no

 — 

Classification indicating how early a variety matures. Valid values range from 2.0 to 4.5, with a lower number indicating an earlier maturity and a higher number indicating a later maturity. Default is 3.0.

plant_depth

float

no

 — 

The depth (in cm) that the crop was planted. Valid values range from 0.1 to 4.9 cm. Default is 3.5.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

7.2.3. Response Object (JSON)

Field Description

agdd

Aggregate growing degree days from plant date, including the current period’s date. (Only used or returned from plant date to emergence).

air_temp_avg

Average daily air temperature valid for the current period’s date. This value is obtained by adding the daily minimum air temperature and daily maximum air temperature and dividing that value by two. These values are obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

gdd

Growing degree days accumulated on the current date.

last_reproductive_stage

The last known reproductive stage. If last_reproductive_stage is empty, the crop is somewhere between the previous growth stage and the next growth stage.

last_vegetative_stage

The last known vegetative stage. If last_vegetative_stage is empty, the crop is somewhere between the previous growth stage and the next growth stage.

new_reproductive_stage

The crop is expected to have entered a new reproductive stage between the current period’s date and the previous period’s date.

relative_humidity_avg

Average daily relative humidity provided as a percentage.

last_stage

The last known growth stage. If last_stage is empty, the crop is somewhere between the previous growth stage and the next growth stage. This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

new_stage

The crop is expected to have entered a new growth stage between the current period’s date and the previous period’s date. This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

start

The beginning of typical harvest operations.

end

The end of typical harvest operations.

advisor

Suggested field properties to check.

description

Text description for a stage.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

7.2.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/soybean/growth/gdd_envelope?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800&days=160

7.2.5. Example Response

{
    "data":{
        "32.509761735919426,-96.85546875":{
            "2016-10-20":{
                "agdd":58.79,
                "agdd_envelope_max":58.79,
                "agdd_envelope_max_year":"2015",
                "agdd_envelope_min":58.79,
                "agdd_envelope_min_year":"2015",
                "air_temp_avg":69.0,
                "gdd":15.81,
                "last_reproductive_stage":"n/a",
                "last_stage":"RA",
                "last_vegetative_stage":"RA",
                "new_reproductive_stage":"n/a",
                "new_stage":"n/a",
                "new_vegetative_stage":"n/a",
                "relative_humidity_avg":64.13
            },...
        }
    },
    "harvest_window":{
        "end":"n/a",
        "start":"n/a"
    },
    "stage_descriptions":{
        "RA":{
            "advisor":"Nutrient",
            "description":"Radicle Appearance"
        },...
    }
}

7.3. Soybean Growth Add Feedback - v1.0

By providing feedback relating to the growth stage estimates, Iteris will be able to make updates and adjustments to offer its users better results in the future. The given user providing feedback must have write privileges for the field in which the field growth belongs.

Additional information related to feedback timestamp, growth feedback, and feedback stage is available in the Feedback Information section of the Appendix.

7.3.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/soybean/growth/feedback/add/
{growth_id}/{timestamp}/{stage}?account_id={string}&user_id={string}
&app_id={string}&app_key={string}

7.3.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

7.3.3. Response Object

A string representing a feedback ID.

7.3.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/soybean/growth/feedback/add/
xyz/1472688000/R8?account_id=abc&user_id=cba&app_id=123&app_key=321

7.3.5. Example Response

def-345

7.4. Soybean Growth Feedbacks by Growth - v1.0

Returns a list of growth feedback activities associated with the target growth_id.

7.4.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/soybean/growth/feedback/
get/by_growth/{growth_id}?app_id={string}&app_key={string}account_id={string}
&user_id={string}

7.4.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

7.4.3. Response Object (JSON)

Field Description

user_id

User ID provided by and used with the Accounts API.

created

Timestamp denoting when the feedback was created.

data

Information pertaining to the activity.

subtype

Enumeration value representing the specific variety of the activity. Defaults to 0.

growth_feedback_id

ID of target growth feedback.

type

Enumeration value of plant.

feedback/date

Unix timestamp denoting when the feedback happened2.

feedback/stage

Stage provided as feedback.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

7.4.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/soybean/growth/feedback/
get/by_growth/xyz?app_id=123&app_key=321&account_id=abc&user_id=cba

7.4.5. Example Response

[
    {
        "user_id":"1234",
        "feedback":{
            "date":1400371200,
            "type":66,
            "stage":"V1"
        },
        "created":1446229281,
        "data":"{}",
        "subtype":"0",
        "growth_feedback_id":"1111",
        "type":66
    },...
]

7.5. Soybean Growth Modify Feedback - v1.0

The Soybean Growth Modify Feedback endpoint allows users to modify previously provided growth stage estimate feedback. The given user providing feedback must have write privileges for the field in which the field growth belongs. At least one modification must be provided.

7.5.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/soybean/growth/feedback/modify/
{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}&timestamp={integer}&stage={string}

7.5.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

7.5.3. Response Object

A string representing success (“true”) or failure (“false”).

7.5.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/soybean/growth/feedback/
modify/abc-123?account_id=abc&user_id=cba&app_id=123&app_key=321
&timestamp=1472688000&stage=R8

7.5.5. Example Response

true

7.6. Soybean Growth Delete Feedback - v1.0

This endpoint allows users to delete the previously provided growth stage estimate feedback. The given user deleting feedback must have write privileges for the field in which the field growth belongs.

7.6.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/soybean/growth/feedback/
delete/{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}

7.6.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

7.6.3. Response Object

A string representing success (“true”) or failure (“false”).

7.6.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/soybean/growth/
feedback/delete/abc-123?account_id=abc&user_id=cba
&app_id=123&app_key=321

7.6.5. Example Response

true

7.7. Soybean In-Field Drydown - v1.0

Drawing from the ClearAg Field Weather API and soybean growth model, the Soybean In-Field Drydown endpoint simulates the drying process of soybean seed in the field after the crop achieves full maturity, and provides daily seed moisture estimates during the drydown period. If Accounts API integration is used, any available moisture measurements are used to improve model results.

7.7.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/soybean/infield_drydown?
app_id={string}&app_key={string}&location={lat, lon coordinates}
&plant_date={timestamp}&account_id={string}&user_id={string}&growth_id={string}
&maturity_group={float}&plant_depth={float}

7.7.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

maturity_group

float

no

 — 

Classification indicating how early a variety matures. Valid values range from 2.0 to 4.5, with a lower number indicating an earlier maturity and a higher number indicating a later maturity. Default is 3.0.

plant_depth

float

no

 — 

The depth (in cm) that the crop was planted. Valid values range from 0.1 to 4.9 cm. Default is 3.5.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

7.7.3. Response Object (JSON)

Field Description

attribution

Various model attributions.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_avg

Average daily air temperature valid for the current date. This value is calculated by averaging the current date’s minimum and maximum air temperature. Obtained from historical, forecast, or climatological data, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures. Note that wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_reproductive_stage

The last known reproductive stage.

last_stage

The last known growth stage. This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

last_vegetative_stage

The last known vegetative stage.

new_reproductive_stage

The crop may have entered a new reproductive stage between the current date and the previous date. If new_reproductive_stage is null, the crop is somewhere between the previous reproductive stage and the next reproductive stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage. This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

new_vegetative_stage

The crop may have entered a new vegetative stage between the current date and the previous date. If new_vegetative_stage is null, the crop is somewhere between the previous vegetative stage and the next vegetative stage.

relative_humidity_avg

Average daily relative humidity provided as a percentage.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

advisor

Suggested field properties to check.

description

Text description for a stage.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Image URL.

name

Growth stage name.

order

Relative position of the stage within the growth scale.

7.7.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/soybean/infield_drydown?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800

7.7.5. Example Response

{
    "attribution":[
        "Growth model based on SoySim, a model developed by the University of Nebraska - Lincoln."
    ],
    "data":{
        "39.26628442213066,-103.1396484375":{
            "2016-08-11":{
                "agdd":1562.67,
                "air_temp_avg":71.0,
                "equilibrium_moisture_content":7.22,
                "gdd":16.58,
                "grain_moisture_content":12.95,
                "grain_moisture_content_change":-1.33,
                "last_reproductive_stage":"R6",
                "last_stage":"R6",
                "last_vegetative_stage":"V1",
                "new_reproductive_stage":"n/a",
                "new_stage":"n/a",
                "new_vegetative_stage":"n/a",
                "relative_humidity_avg":53.79
            },...
        }
    },
    "harvest_window":{
        "end":"2016-10-12",
        "start":"2016-09-17"
    },
    "stage_descriptions":{
        "R6":{
            "advisor":"Harvest",
            "description":"Full Seed - pod containing a green seed that fills the pod cavity at one of the four uppermost nodes on the main stem with a fully developed trifoliate leaf node",
            "images":[
                {
                    "attribution":"Courtesy of Agronomy Extension, Iowa State University.",
                    "caption":"R6 - Full seed",
                    "url":"https://.../R6.jpg"
                },...
            ],
            "name":"R6 - Full Seed",
            "order":"12"
        },...
    }
}

7.8. Soybean Mechanical Drying - v1.0

The Soybean Mechanical Drying endpoint simulates the drydown process of soybean using either fan-powered low-temperature drying or burner-driven high-temperature drying facilities to provide drying statistics and cost projections. The mechanical drying process is simulated using up to 10 future days of grain moisture estimates. Results from the soybean in-field drying model are also returned for comparison.

Note that a field, growth, and drying facility are required to utilize this feature. Any available seed moisture measurements are used to improve model results.

Please be aware that mechanical drying data will not be returned if seed moisture estimates are unable to be obtained from the soybean in-field drying model. This may occur if one of the following conditions are met:

  • The soybean growth model simulation does not bring the crop to maturity. This is more likely to occur for certain location (e.g., cooler climates) and relative maturity combinations.

  • The crop planting date or emergence date are too far in the past. The models are designed for future planning; users can utilize the “current_date” argument to determine what model results could have been on a past date. These results can be different than what would have been seen on the emulated date, as the forecast timeframes are now represented by historical data.

7.8.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/soybean/mechanical_drying?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&drying_facility_ids={string}&grain_unit={string}
&target_moisture_content_wb={float}&current_date={timestamp}

7.8.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Accounts API ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have read privileges for the field in which the growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field.

target_moisture_ content_wb

float

yes

Numeric representation of the desired moisture level for safe storage, measured in percent on a wet basis. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

grain_unit

string

yes

Units to use when returning unit costs of drying. Valid values are “bu” (bushel) and “mt” (metric ton).

drying_facility_ids

string

no

Comma-delimited list of drying facility IDs to be used. Currently, only the most recently created facility in the list will be used. Default behavior is to use the most recently created facility overall. Note that the calling user must have at least read privileges for the asset (drying facility).

current_date

timestamp

no

Emulate model results as if viewed on this date2. Useful for viewing approximate model results for historical timeframes greater than one year in the past. There can be differences in results due to what would have been forecasted weather data now being replaced with historical or climatological data used in the calculations.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

7.8.3. Response Object (JSON)

Field Description

asset_id

The ID given to a particular drying facility.

name

The user-provided name of the drying facility. If this is not supplied, a generic name of “Drying Facility” followed by a number is used.

burner_fuel_type

Type of fuel consumed by the burner, as provided by the Accounts API.

burner_fuel_unit

Unit of measure associated with the fuel type, as provided by the Accounts API.

driest_datetime

Time that the grain reached its lowest moisture content of the model run. Represented by a date string in the case of low-temperature drying or hours and minutes in the case of high-temperature drying. Note that the simulation will stop when the user-specified target moisture content is reached, in which case this will indicate the timing of the grain reaching that threshold.

driest_moisture_content_db

Driest dry-basis grain moisture content of the simulation, in percent. Dry-basis moisture content is defined as the ratio of the mass of water to the dry mass of a sample of grain.

driest_moisture_content_wb

Driest wet-basis grain moisture content of the simulation, in percent. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

dryer_throughput_grain_units_ per_hour

Amount of grain dried per hour. Applicable only in high-temperature drying facilities.

drying_time

Amount of time, in seconds, that elapsed for the grain to reach its lowest moisture content.

grain_storability

Likelihood of spoilage. Possible values include “0,” indicating that grain is not likely to spoil; “1,” indicating a marginal risk; and “2,” warning that spoilage is likely. When high-temperature drying is in use, “n/a” will be used.

grain_unit

Unit of measure associated with the volume of grain as provided by the user.

per_grain_unit/burner_fuel_ cost

Expected burner fuel cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/burner_fuel_ units_consumed

Expected amount of fuel consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/burner_kwh_ consumed

Expected amount of fuel energy, in kilowatt-hours, consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/electricity_cost

Expected electricity cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/electricity_kwh_ consumed

Expected amount of electrical energy, in kilowatt-hours, consumed by the fan per unit of grain, in the grain unit provided by the user.

per_grain_unit/total_cost

Expected total drying cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit_per_percent_ moisture/total_cost

Expected total drying cost per unit of grain per percent moisture change, in the user’s local currency, and in the grain unit provided by the user.

sample_datetime

Valid time of the grain moisture sample provided by the in-field drydown model.

sample_moisture_content_wb

Starting wet-basis moisture content of the grain sample, in percent, provided by the in-field drydown model.

simulation_length

Total length of time, in seconds, over which the drydown process was modeled.

target_moisture_reached

Flag indicating whether the target storage moisture content is reached in the simulation, where “1” indicates that the storage moisture is reached and “0” indicates that it is not. Primarily applicable in low-temperature drying facilities, where ambient environmental conditions may not permit an adequate amount of drying.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_avg

Average daily air temperature, which may be a historical, forecast, or climatological value, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures.

feedback_id

If this field is present, it indicates a confirmed or observed growth stage on the current date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_reproductive_stage

The last known reproductive stage.

last_stage

The last known growth stage. This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

last_vegetative_stage

The last known vegetative stage.

new_reproductive_stage

The crop may have entered a new reproductive stage between the current date and the previous date. If new_reproductive_stage is null, the crop is somewhere between the previous reproductive stage and the next reproductive stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage. This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

new_vegetative_stage

The crop may have entered a new vegetative stage between the current date and the previous date. If new_vegetative_stage is null, the crop is somewhere between the previous vegetative stage and the next vegetative stage.

relative_humidity_avg

Average daily relative humidity provided as a percentage.

7.8.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/soybean/mechanical_drying?
app_id=123&app_key=321&account_id=abc&user_id=cba&growth_id=xyz
&grain_unit=bu&target_moisture_content_wb=14.5

7.8.5. Example Response

{
    "drying_facilities":[
        {
            "asset_id":"abc-123",
            "data":[
                {
                    "burner_fuel_type":"liquid_propane",
                    "burner_fuel_unit":"gallon",
                    "driest_datetime":"04:14",
                    "driest_moisture_content_db":16.9,
                    "driest_moisture_content_wb":14.46,
                    "dryer_throughput_grain_units_per_hour":335.0,
                    "drying_time":15240,
                    "grain_storability":"n/a",
                    "grain_unit":"bu",
                    "per_grain_unit":{
                        "burner_fuel_cost":0.359,
                        "burner_fuel_units_consumed":0.399,
                        "burner_kwh_consumed":9.85,
                        "electricity_cost":0.148,
                        "electricity_kwh_consumed":0.3,
                        "total_cost":0.507
                    },
                    "per_grain_unit_per_percent_moisture":{
                        "total_cost":0.031
                    },
                    "sample_datetime":"2016-09-28",
                    "sample_moisture_content_wb":31.09,
                    "simulation_length":15240,
                    "target_moisture_reached":1
                },...
            ],
            "name":"Soybean Dryer"
        }
    ],
    "infield_drydown_data":{
        "47,-97":{
            "2016-09-28":{
                "agdd":2135.94,
                "air_temp_avg":55.0,
                "equilibrium_moisture_content":7.54,
                "gdd":8.0,
                "grain_moisture_content":31.09,
                "grain_moisture_content_change":"n/a",
                "last_reproductive_stage":"R7",
                "last_stage":"R7",
                "last_vegetative_stage":"V15",
                "new_reproductive_stage":"R8",
                "new_stage":"R8",
                "new_vegetative_stage":"n/a",
                "relative_humidity_avg":62.11
            },...
        }
    }
}

8. Cotton

8.1. Cotton Growth - v1.0

Leveraging Iteris’ cotton growth stage model, the Cotton Growth endpoint allows users to model the maturation and development of cotton crops. Users may also take advantage of Accounts API integration to provide crop growth feedback and optimize model results.

8.1.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/cotton/growth?app_id={string}
&app_key={string}&location={lat, lon coordinates}&plant_date={timestamp}
&days={integer}&account_id={string}&user_id={string}&growth_id={string}
&relative_maturity={string}

8.1.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” “medium,” “medium-late,” and “late.” Default is “medium.”

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

8.1.3. Response Object (JSON)

field Description

gdd

Growing degree days accumulated on the current date.

agdd

Aggregate growing degree days from plant date, including the current period’s date.

air_temp_min

Minimum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

air_temp_max

Maximum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

last_stage

The last known growth stage. If no valid stage has been reached, this value will be "n/a." This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

new_stage

The crop is expected to have entered a new stage between the current period’s date and the previous period’s date.

harvest_window/end

The end of typical harvest operations.

harvest_window/start

The beginning of typical harvest operations.

advisor

Suggested field properties to check.

description

Text description for a stage.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

8.1.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/cotton/growth?app_id=123&app_key=321
&location=47,-97&plant_date=1462060800&days=160

8.1.5. Example Response

{
    "data":{
        "35,-97":{
            "2016-06-30":{
                "agdd":1072.5,
                "air_temp_max":92.0,
                "air_temp_min":69.0,
                "gdd":24.5,
                "last_stage":"v1.0",
                "new_stage":"v2.0"
            },...
        }
    },
    "harvest_window":{
        "end":"2016-11-30",
        "start":"2016-10-27"
    },
    "stage_descriptions":{
        "v1.0":{
            "advisor":"Nutrient",
            "description":"Emergence occurs when the seedling pushes through the soil surface."
        },...
    }
}

8.2. Cotton Growth with GDD Envelope - v1.1

The Cotton Growth with GDD Envelope service provides cotton growth information in addition to GDD envelope data. GDD envelope calculation begins from either the current day, or the planted/emergence date, whichever is further in the future. The envelope is constructed by compiling the previous 10 years of weather data, and simulating the maximum and minimum GDD that would have accumulated within those 10 years for each date. The calculated minimum and maximum values are then added to the current start of calculation date AGDD going onwards to show range of possibilities.

8.2.1. URL Description

http://ag.us.clearapis.com/v1.1/crop_health/cotton/growth/
gdd_envelope?app_id={string}&app_key={string}&plant_date={timestamp}
&location={lat, lon coordinates}&days={integer}&account_id={string}
&user_id={string}&growth_id={string}
&relative_maturity={string}

8.2.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” “medium,” “medium-late,” and “late.” Default is “medium.”

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

8.2.3. Response Object (JSON)

Field Description

gdd

Growing degree days accumulated on the current date.

agdd

Aggregate growing degree days from plant date, including the current period’s date.

air_temp_min

Minimum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

air_temp_max

Maximum air temperature valid for the current period’s date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

last_stage

The last known growth stage. If no valid stage has been reached, this value will be "n/a." This variable will contain vegetative stages until the beginning of flowering is reached. At this time, only new reproductive stages will be listed.

new_stage

The crop is expected to have entered a new stage between the current period’s date and the previous period’s date.

start

The beginning of typical harvest operations.

end

The end of typical harvest operations.

advisor

Suggested field properties to check.

damage

Possibility for damage to occur.

description

Text description for a stage.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

order

Ordering of stage when displaying/listing stage_descriptions.

attribution

Various attributions for the model used.

images

List of image metadata.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Location of image.

agdd_envelope_max

Maximum observed agdd during the previous 10 years.

agdd_envelope_min

Minimum observed agdd during the previous 10 years.

agdd_envelope_min_year

Year that the agdd_envelope_min was observed.

agdd_envelope_max_year

Year that the agdd_envelope_max was observed.

8.2.4. Example Request

http://ag.us.clearapis.com/v1.1/crop_health/cotton/growth/gdd_envelope?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800&days=160

8.2.5. Example Response

{
    "attribution":[
        "Based on models presented by the University of Florida and the University of California at Davis, but substantially modified."
    ],
    "data":{
        "32.509761735919426,-96.85546875":{
            "growth":{
                "2016-10-20":{
                    "agdd":63.5,
                    "agdd_envelope_max":63.5,
                    "agdd_envelope_max_year":"2015",
                    "agdd_envelope_min":63.5,
                    "agdd_envelope_min_year":"2015",
                    "air_temp_max":75.0,
                    "air_temp_min":60.0,
                    "gdd":12.5,
                    "last_stage":"n/a",
                    "new_stage":"n/a"
                },...
            }
        },
        "harvest_window":{
            "end":"n/a",
            "start":"n/a"
            }
        }
    },
    "stage_descriptions":{
        "n/a":{
            "advisor":"Not available/Not applicable",
            "description":"Not available/Not applicable",
            "images":[],
            "name":"Not available/Not applicable",
            "order":"0"
        }
    }
}

8.3. Cotton Growth Add Feedback - v1.0

By providing feedback relating to the growth stage estimates, Iteris will be able to make updates and adjustments to offer its users better results in the future. The given user providing feedback must have write privileges for the field in which the field growth belongs.

Additional information related to feedback timestamp, growth feedback, and feedback stage is available in the Feedback Information section of the Appendix.

8.3.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/cotton/growth/feedback/add/
{growth_id}/{timestamp}/{stage}?account_id={string}&user_id={string}
&app_id={string}&app_key={string}

8.3.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

8.3.3. Response Object

A string representing a feedback ID.

8.3.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/cotton/growth/feedback/add/
xyz/1472688000/v7.0?account_id=abc&user_id=cba&app_id=123&app_key=321

8.3.5. Example Response

def-345

8.4. Cotton Growth Feedbacks by Growth - v1.0

Returns a list of growth feedback activities associated with the target growth_id.

8.4.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/cotton/growth/feedback/
get/by_growth/{growth_id}?app_id={string}&app_key={string}account_id={string}
&user_id={string}

8.4.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

8.4.3. Response Object (JSON)

Field Description

user_id

User ID provided by and used with the Accounts API.

created

Timestamp denoting when the feedback was created.

data

Information pertaining to the activity.

subtype

Enumeration value representing the specific variety of the activity. Defaults to 0.

growth_feedback_id

ID of target growth feedback.

type

Enumeration value of plant.

feedback/date

Unix timestamp denoting when the feedback happened2.

feedback/stage

Stage provided as feedback.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

8.4.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/cotton/growth/feedback/
get/by_growth/xyz?app_id=123&app_key=321&account_id=abc&user_id=cba

8.4.5. Example Response

[
    {
        "user_id":"1234",
        "feedback":{
            "date":1400371200,
            "type":65,
            "stage":"v1.0"
        },
        "created":1446229281,
        "data":"{}",
        "subtype":"0",
        "growth_feedback_id":"1111",
        "type":65
    },...
]

8.5. Cotton Growth Modify Feedback - v1.0

The Cotton Growth Modify Feedback endpoint allows users to modify previously provided growth stage estimate feedback. The given user providing feedback must have write privileges for the field in which the field growth belongs. At least one modification must be provided.

8.5.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/cotton/growth/feedback/modify/
{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}&timestamp={integer}&stage={string}

8.5.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

8.5.3. Response Object

A string representing success (“true”) or failure (“false”).

8.5.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/cotton/growth/feedback/
modify/abc-123?account_id=abc&user_id=cba&app_id=123&app_key=321
&timestamp=1472688000&stage=v7.0

8.5.5. Example Response

true

8.6. Cotton Growth Delete Feedback - v1.0

This endpoint allows users to delete the previously provided growth stage estimate feedback. The given user deleting feedback must have write privileges for the field in which the field growth belongs.

8.6.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/cotton/growth/feedback/
delete/{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}

8.6.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

8.6.3. Response Object

A string representing success (“true”) or failure (“false”).

8.6.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/cotton/growth/
feedback/delete/abc-123?account_id=abc&user_id=cba
&app_id=123&app_key=321

8.6.5. Example Response

true

8.7. Cotton Nitrogen Advisor - v1.0

The ClearAg Cotton Nitrogen Advisor simulates the various processes of the nitrogen cycle that impact the availability of nitrogen to cotton crops. The model is based on a combination of proven algorithms from several industry models for simulating the nitrogen cycle. When used in combination with the Accounts API, the Cotton Nitrogen Advisor allows provision of several types of field level activities, including fertilizer treatments and soil sample results, containing information such as soil nitrate and organic matter levels, as well as soil pH. Crop growth and the corresponding crop parameters of importance are simulated based on user-specified location, relative maturity, and planting date. Weather and soil information required by the Clear-N model are provided by the ClearAg Field Weather and Soil Conditions APIs, which provide a seamless global dataset of current, forecast, and historical conditions (dating back to 1980) for any arable location globally.

8.7.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/cotton/nutrient/nitrogen?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&location={lat, lon coordinates}&plant_date={timestamp}
&yield_goal={integer}&yield_goal_unit={string}&previous_crop={integer}
&previous_harvest_date={timestamp}&previous_yield={integer}
&previous_yield_unit={string}&output_unit={string}&year_offset={integer}
&relative_maturity={string}

8.7.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Limited to a single location per query.

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the current crop was planted or the date of emergence2.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” “medium,” “medium-late,” and “late.” Default is “medium.”

yield_goal

integer

yes

yes

Target yield for current crop.

yield_goal_unit

string

yes

yes

Target yield unit. Accepted values are “lb/ac” or “kg/ha”.

previous_crop

integer

no

no

Enumeration value of previous crop on field. Accepted values are currently 50 (barley), 51 (corn), 57 (spring wheat), 59 (canola), 65 (cotton), 66 (soybean), 68 (winter wheat), 69 (vegetable), 70 (sorghum), 71 (pea), 72 (sunflower), 73 (rice), and 74 (alfalfa).

previous_harvest_date

timestamp

no

no

Epoch timestamp valid near the time that the previous crop was harvested2. Required if previous crop is specified. May not predate the planting or emergence date by more than 366 days.

previous_yield

integer

no

no

Actual yield of the previous crop. Required if previous crop is specified.

previous_yield_ unit

string

no

no

Previous yield unit. Accepted values are “lb/ac,” “kg/ha,” or “bu/ac.” Required if previous crop is specified. Note that “bu/ac” is not a valid yield unit for alfalfa, cotton, or vegetable.

output_unit

string

yes

yes

Specifies the unit of the area density data displayed. Accepted values are “lb/ac” or “kg/ha.”

year_offset

integer

no

no

Specifies a number of years by which to adjust model results. Values must be less than 0.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

8.7.3. Response Object (JSON)

Field Description

fertilizer_treatment

Structure holding all fertilizer treatment data utilized by the nitrogen model, including the fertilizer type, application rate, and depth.

soil_sample

Structure holding all soil sample data utilized by the nitrogen model, including the soil nitrate content, organic matter content, pH level, and sample depth.

tillage

Structure holding all tillage data utilized by the nitrogen model, including the tillage type and depth.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum air temperature valid for the current date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the timeframe.

air_temp_min

Minimum air temperature valid for the current date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the timeframe.

gdd

Growing degree days accumulated on the current date.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

ammonium,
ammonium_XtoY

The amount of nitrogen in the form of ammonium within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters.

ammonium_in_last_sample_depth

The modeled amount of ammonium above the depth of the previous soil sample.

nitrate,
nitrate_XtoY

The amount of nitrogen in the form of nitrate within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters.

nitrate_in_last_sample_depth

The modeled amount of nitrate above the depth of the previous soil sample.

applied_fertilizers,
applied_fertilizers_XtoY

The amount of nitrogen applied as fertilizer resident within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters3.

denitrified,
denitrified_XtoY

The amount of soil nitrate lost from the entire 2-meter depth of the modeled soil profile, or from within the layer spanning from depth=X to depth=Y centimeters, due to the process of denitrification, whereby nitrate is converted into nitrogen gas and then escapes into the atmosphere3.

immobilized,
immobilized_XtoY

The amount of nitrogen that has been immobilized within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters, in order to support mineralization of the previous crop’s residues3.

leached,
leached_XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning from depth=X to depth=Y centimeters, due to the process of leaching. Only losses will normally be seen when aggregated across the entire depth of the modeled soil profile; otherwise, some layers may gain nitrate at the expense of others, due to the vertical movement of water within the soil profile3.

leached_below_current_root_depth

The amount of soil nitrate that has been leached below the depth of the current crop’s roots as of the indicated date3.

leached_below_maximum_root_depth

The amount of soil nitrate that has been leached below the maximum depth that the current crop’s roots are expected to reach during the entirety of its growth cycle3.

realized_from_crop_organic_matter,
realized_from_crop_organic_matter_ XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, due to the process of mineralization of residues associated with the previous crop. This can be either positive or negative, depending on the carbon to nitrogen ratio of the previous crop’s residues3.

realized_from_soil_organic_matter,
realized_from_soil_organic_matter_ XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, due to the process of mineralization of soil organic matter. Since the carbon to nitrogen ratio of soil organic matter is typically below that associated with the diet of soil microbes, values will normally be positive3.

uptaken_by_crop,
uptaken_by_crop_XtoY

The amount of nitrogen uptaken by the crop from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters. If less than uptaken_by_crop_optimal, this can be indicative of a risk that the crop may be short of nitrogen3.

uptaken_by_crop_optimal,
uptaken_by_crop_optimal_XtoY

The amount of nitrogen the crop would have ideally taken up from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters3.

volatized,
volatized_XtoY

The amount of nitrogen lost by the process of volatization (also referred to as volatilization) from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, whereby urea fertilizer is converted into ammonia gas and then escapes into the atmosphere3.

applied_use_efficiency

The crop’s use efficiency of fertilizer-based nitrogen applied since the harvest of the previous crop. Values will be less than or equal to 100%, with higher percentages indicating that the crop has (or will) use a higher percentage of the fertilizers that have been applied.

applied_use_efficiency_unit

Units of “applied_use_efficiency.”

current_root_depth

The depth to which the current crop’s roots are assumed to reach as of the indicated date.

current_root_depth_unit

Units of “current_root_depth.” Chosen automatically based on the user-provided input value of “output_unit.”

indigenous_use_efficiency

The crop’s use efficiency of nitrogen realized through organic matter mineralization since the harvest of the previous crop. Values are in percentages, with higher percentages indicating that the crop has (or will) use a higher percentage of the nitrogen that has been realized through organic matter mineralization. Values in excess of 100% are possible.

indigenous_use_efficiency_unit

Units of “indigenous_use_efficiency.”

maximum_root_depth

The maximum depth to which the current crop’s roots are expected to reach during the entirety of its growth cycle.

maximum_root_depth_unit

Units of “maximum_root_depth.” Chosen automatically based on the user-provided input value of “output_unit.”

nitrogen_available_unit

Units of all data values in the “nitrogen_available” subsection of the returned JSON object.

nitrogen_budget_unit

Units of all data values in the “nitrogen_budget” subsection of the returned JSON object.

notes

A dictionary containing textual descriptions of noteworthy problems or occurrences on the indicated date.

uptake_score

A 0-100 score quantifying the adequacy of crop nitrogen uptake relative to the goals specified in the API call. Higher values indicate better uptake, with values at or near 100 being desirable in order to optimize the crop’s prospects for achieving the caller-specified yield_goal.

uptake_score_unit

Units of “uptake_score.”

advisor

Suggested field properties to check.

description

Text description for a growth stage.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Image URL.

name

Growth stage name.

order

Relative position of a stage within the growth scale.

3 Positive numeric values indicate that nitrogen has been gained by the soil due to the associated process, whereas negative numeric values indicate that nitrogen has been lost by the soil due to the associated process.

8.7.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/cotton/nutrient/nitrogen?
app_id=123&app_key=321&account_id=abc&user_id=cba&growth_id=xyz
&previous_harvest_date=1450757200&previous_crop=51&previous_yield=1000
&previous_yield_unit=kg/ha&yield_goal=1050&yield_goal_unit=kg/ha
&output_unit=kg/ha

8.7.5. Example Response

{
    "activities":{
        "fertilizer_treatment":{
            "2016-04-20":[{
                "depth":0.5,
                "depth_unit":"m",
                "fertilizer_id":"11",
                "rate":366.0,
                "rate_unit":"lb/ac"
            }]
        },
        "soil_sample":{
            "2016-04-01":[{
                "depth_unit":"m",
                "end_depth":1.0,
                "nitrate":3.0,
                "nitrate_unit":"kg/ha",
                "organic_matter":"n/a",
                "ph":"n/a",
                "start_depth":0.5
            }]
        },
        "tillage": {}
    },
    "data":{
        "2016-07-01":{
            "agdd":795.5,
            "air_temp_max":90.0,
            "air_temp_min":72.0,
            "gdd":21.0,
            "last_stage":"v2.0",
            "new_stage":"n/a",
            "nitrogen_available":{
                "ammonium":4.9,
                "ammonium_0to2":0.0,
                "ammonium_100to200":0.0,
                "ammonium_10to20":0.2,
                "ammonium_20to40":1.7,
                "ammonium_2to5":0.0,
                "ammonium_40to70":3.0,
                "ammonium_5to10":0.0,
                "ammonium_70to100":0.0,
                "ammonium_in_last_sample_depth":2.0,
                "nitrate":102.2,
                "nitrate_0to2":0.0,
                "nitrate_100to200":34.5,
                "nitrate_10to20":2.7,
                "nitrate_20to40":15.2,
                "nitrate_2to5":0.1,
                "nitrate_40to70":29.3,
                "nitrate_5to10":0.5,
                "nitrate_70to100":19.9,
                "nitrate_in_last_sample_depth":39.5
            },
            "nitrogen_budget":{
                "applied_fertilizers":70.6,
                "applied_fertilizers_0to2":2.8,
                "applied_fertilizers_100to200":0.0,
                "applied_fertilizers_10to20":12.7,
                "applied_fertilizers_20to40":28.2,
                "applied_fertilizers_2to5":4.2,
                "applied_fertilizers_40to70":14.1,
                "applied_fertilizers_5to10":8.5,
                "applied_fertilizers_70to100":0.0,
                "denitrified":0.0,
                "denitrified_0to2":0.0,
                "denitrified_100to200":0.0,
                "denitrified_10to20":0.0,
                "denitrified_20to40":0.0,
                "denitrified_2to5":0.0,
                "denitrified_40to70":0.0,
                "denitrified_5to10":0.0,
                "denitrified_70to100":0.0,
                "immobilized":-3.3,
                "immobilized_0to2":-1.0,
                "immobilized_100to200":0.0,
                "immobilized_10to20":0.0,
                "immobilized_20to40":0.0,
                "immobilized_2to5":-2.4,
                "immobilized_40to70":0.0,
                "immobilized_5to10":0.0,
                "immobilized_70to100":0.0,
                "leached":-27.9,
                "leached_0to2":-4.0,
                "leached_100to200":-2.6,
                "leached_10to20":-14.5,
                "leached_20to40":-25.4,
                "leached_2to5":-5.3,
                "leached_40to70":18.7,
                "leached_5to10":-15.7,
                "leached_70to100":21.0,
                "leached_below_current_root_depth":-25.7,
                "leached_below_maximum_root_depth":-26.7,
                "realized_from_crop_organic_matter":1.3,
                "realized_from_crop_organic_matter_0to2":0.0,
                "realized_from_crop_organic_matter_100to200":0.5,
                "realized_from_crop_organic_matter_10to20":0.1,
                "realized_from_crop_organic_matter_20to40":0.2,
                "realized_from_crop_organic_matter_2to5":0.0,
                "realized_from_crop_organic_matter_40to70":0.3,
                "realized_from_crop_organic_matter_5to10":0.1,
                "realized_from_crop_organic_matter_70to100":0.3,
                "realized_from_soil_organic_matter":67.5,
                "realized_from_soil_organic_matter_0to2":2.1,
                "realized_from_soil_organic_matter_100to200":35.8,
                "realized_from_soil_organic_matter_10to20":4.5,
                "realized_from_soil_organic_matter_20to40":14.0,
                "realized_from_soil_organic_matter_2to5":3.4,
                "realized_from_soil_organic_matter_40to70":0.0,
                "realized_from_soil_organic_matter_5to10":7.6,
                "realized_from_soil_organic_matter_70to100":0.0,
                "uptaken_by_crop":-1.2,
                "uptaken_by_crop_0to2":0.0,
                "uptaken_by_crop_100to200":-0.2,
                "uptaken_by_crop_10to20":-0.1,
                "uptaken_by_crop_20to40":-0.3,
                "uptaken_by_crop_2to5":0.0,
                "uptaken_by_crop_40to70":-0.4,
                "uptaken_by_crop_5to10":0.0,
                "uptaken_by_crop_70to100":-0.2,
                "uptaken_by_crop_optimal":-1.2,
                "uptaken_by_crop_optimal_0to2":0.0,
                "uptaken_by_crop_optimal_100to200":-0.2,
                "uptaken_by_crop_optimal_10to20":-0.1,
                "uptaken_by_crop_optimal_20to40":-0.3,
                "uptaken_by_crop_optimal_2to5":0.0,
                "uptaken_by_crop_optimal_40to70":-0.4,
                "uptaken_by_crop_optimal_5to10":0.0,
                "uptaken_by_crop_optimal_70to100":-0.2,
                "volatized":-0.6,
                "volatized_0to2":-0.1,
                "volatized_100to200":0.0,
                "volatized_10to20":0.0,
                "volatized_20to40":0.0,
                "volatized_2to5":-0.2,
                "volatized_40to70":0.0,
                "volatized_5to10":-0.3,
                "volatized_70to100":0.0
            },
            "nitrogen_metadata":{
                "applied_use_efficiency":1.3,
                "applied_use_efficiency_unit":"%",
                "current_root_depth":45.0,
                "current_root_depth_unit":"in",
                "indigenous_use_efficiency":0.5,
                "indigenous_use_efficiency_unit":"%",
                "maximum_root_depth":60.0,
                "maximum_root_depth_unit":"in",
                "nitrogen_available_unit":"lb/ac",
                "nitrogen_budget_unit":"lb/ac",
                "notes":{
                    "1":"Some nitrogen leached below the current root depth.",
                    "3":"Soil moisture is limiting crop nitrogen uptake.",
                    "5":"Crop nitrogen uptake limited by soil location relative to crop roots."
                },
                "uptake_score":100.0,
                "uptake_score_unit":"%"
            }
        },...
    },
    "stage_descriptions":{
        "v2.0":{
            "advisor":"Nutrient",
            "description":"The first squares (flower buds) are visible. Typically, less than %50 of all squares produce mature bolls.",
            "images":[
                {
                    "attribution":"Courtesy of North Carolina State University.",
                    "caption":"Flared square",
                    "url":"https://.../Flared_square2.jpg"
                },...
            ],
            "name":"First Square",
            "order":"2"
        },...
    }
}

9. Sunflower

9.1. Sunflower Growth - v1.0

Leveraging Iteris’ sunflower growth stage model, the Sunflower Growth endpoint allows users to model the maturation and development of sunflower crops. Users may also take advantage of Accounts API integration to provide crop growth feedback and optimize model results.

9.1.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/growth?app_id={string}
&app_key={string}&location={lat, lon coordinates}&plant_date={timestamp}
&days={integer}&account_id={string}&user_id={string}&growth_id={string}
&relative_maturity={string}

9.1.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” “medium,” “medium-late,” and “late.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

9.1.3. Response Object (JSON)

Field Description

attribution

Container for general model credits.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum air temperature valid for the current date, in Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum air temperature valid for the current date, in Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

gdd

Growing degree days accumulated on the current date.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

harvest_window/end

Expected end date for harvest operations.

harvest_window/start

Expected start date for harvest operations.

advisor

Suggested field properties to check.

description

Text description for a stage.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Image URL.

name

Stage name.

order

Relative position of the stage within the growth scale.

9.1.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/growth?app_id=123&app_key=321
&location=47,-97&plant_date=1462060800&days=160

9.1.5. Example Response

{
    "attribution":[
        "Based on a model presented by the North Dakota Agricultural Weather Network, but substantially modified."
    ],
    "data":{
        "47,-97":{
            "growth":{
                "2016-05-22":{
                    "agdd":326.5,
                    "air_temp_max":83.0,
                    "air_temp_min":57.0,
                    "gdd":26.0,
                    "last_stage":"1",
                    "new_stage":"2"
                },...
            },
            "harvest_window":{
                "end":"2016-10-08",
                "start":"2016-09-13"
            }
        }
    },
    "stage_descriptions":{
        "1":{
            "advisor":"Nutrient",
            "description":"Emergence occurs when the seedling pushes through the soil surface.",
            "images":[
                {
                    "attribution":"Courtesy of the National Sunflower Association.",
                    "caption":"VE - Emergence",
                    "url":"https://.../Emerging.jpg"
                },...
            ],
            "name":"VE - Emergence",
            "order":"1"
        },...
    }
}

9.2. Sunflower Growth Add Feedback - v1.0

By providing feedback relating to the growth stage estimates, Iteris will be able to make updates and adjustments to offer its users better results in the future. The given user providing feedback must have write privileges for the field in which the field growth belongs.

Additional information related to feedback timestamp, growth feedback, and feedback stage is available in the Feedback Information section of the Appendix.

9.2.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/growth/feedback/add/
{growth_id}/{timestamp}/{stage}?account_id={string}&user_id={string}
&app_id={string}&app_key={string}

9.2.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

9.2.3. Response Object

A string representing a feedback ID.

9.2.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/growth/feedback/add/
xyz/1472688000/v7.0?account_id=abc&user_id=cba&app_id=123&app_key=321

9.2.5. Example Response

def-345

9.3. Sunflower Growth Feedbacks by Growth - v1.0

Returns a list of growth feedback activities associated with the target growth_id.

9.3.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/growth/feedback/
get/by_growth/{growth_id}?app_id={string}&app_key={string}account_id={string}
&user_id={string}

9.3.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

9.3.3. Response Object (JSON)

Field Description

user_id

User ID provided by and used with the Accounts API.

created

Timestamp denoting when the feedback was created.

data

Information pertaining to the activity.

subtype

Enumeration value representing the specific variety of the activity. Defaults to 0.

growth_feedback_id

ID of target growth feedback.

type

Enumeration value of plant.

feedback/date

Unix timestamp denoting when the feedback happened2.

feedback/stage

Stage provided as feedback.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

9.3.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/growth/feedback/
get/by_growth/xyz?app_id=123&app_key=321&account_id=abc&user_id=cba

9.3.5. Example Response

[
    {
        "user_id":"1234",
        "feedback":{
            "date":1400371200,
            "type":72,
            "stage":"1"
        },
        "created":1446229281,
        "data":"{}",
        "subtype":"0",
        "growth_feedback_id":"1111",
        "type":72
    },...
]

9.4. Sunflower Growth Modify Feedback - v1.0

The Sunflower Growth Modify Feedback endpoint allows users to modify previously provided growth stage estimate feedback. The given user providing feedback must have write privileges for the field in which the field growth belongs. At least one modification must be provided.

9.4.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/growth/feedback/modify/
{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}&timestamp={integer}&stage={string}

9.4.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

9.4.3. Response Object

A string representing success (“true”) or failure (“false”).

9.4.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/growth/feedback/
modify/abc-123?account_id=abc&user_id=cba&app_id=123&app_key=321
&timestamp=1472688000&stage=v7.0

9.4.5. Example Response

true

9.5. Sunflower Growth Delete Feedback - v1.0

This endpoint allows users to delete the previously provided growth stage estimate feedback. The given user deleting feedback must have write privileges for the field in which the field growth belongs.

9.5.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/growth/feedback/
delete/{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}

9.5.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

9.5.3. Response Object

A string representing success (“true”) or failure (“false”).

9.5.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/growth/
feedback/delete/abc-123?account_id=abc&user_id=cba
&app_id=123&app_key=321

9.5.5. Example Response

true

9.6. Sunflower In-Field Drydown - v1.0

Drawing from the ClearAg Field Weather API and sunflower growth model, the Sunflower In-Field Drydown endpoint simulates the drying process of sunflower seed in the field after the crop achieves full maturity, and provides daily seed moisture estimates during the drydown period. If Accounts API integration is used, any available moisture measurements are used to improve model results.

9.6.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/infield_drydown?
app_id={string}&app_key={string}&location={lat, lon coordinates}
&plant_date={timestamp}&account_id={string}&user_id={string}&growth_id={string}
&relative_maturity={string}

9.6.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” “medium,” “medium-late,” and “late.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

9.6.3. Response Object (JSON)

Field Description

attribution

Various model attributions.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum air temperature valid for the current date, in Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum air temperature valid for the current date, in Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures. Note that wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

feedback_id

If this field is present, it indicates a confirmed or observed growth stage on the current date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

harvest_window/end

Expected end date for harvest operations.

harvest_window/start

Expected start date for harvest operations.

advisor

Suggested field properties to check.

description

Text description for a growth stage.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Image URL.

name

Growth stage name.

order

Relative position of the stage within the growth scale.

9.6.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/infield_drydown?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800

9.6.5. Example Response

{
    "attribution":[
        "Based on a model presented by the North Dakota Agricultural Weather Network, but substantially modified."
    ],
    "data":{
        "47,-97":{
            "2016-08-30":{
                "agdd":2891.0,
                "air_temp_max":81.0,
                "air_temp_min":49.0,
                "equilibrium_moisture_content":5.57,
                "gdd":21.0,
                "grain_moisture_content":31.63,
                "grain_moisture_content_change":"n/a",
                "last_stage":"30",
                "new_stage":"31"
            },...
        }
    },
    "stage_descriptions":{
        "31":{
            "advisor":"Harvest",
            "description":"The back of the head is brown; the bracts turn yellow/brown.",
            "images":[
                {
                    "attribution":"Courtesy of the National Sunflower Association.",
                    "caption":"R9 stage",
                    "url":"https://.../{image_filename}.jpg"
                },...
            ],
            "name":"R9 - Physiological Maturity",
            "order":"31"
        },...
    }
}

9.7. Sunflower Mechanical Drying - v1.0

The Sunflower Mechanical Drying endpoint simulates the drydown process of sunflower using either fan-powered low-temperature drying or burner-driven high-temperature drying facilities to provide drying statistics and cost projections. The mechanical drying process is simulated using up to 10 future days of grain moisture estimates. Results from the sunflower in-field drying model are also returned for comparison.

Note that a field, growth, and drying facility are required to utilize this feature. Any available seed moisture measurements are used to improve model results.

Please be aware that mechanical drying data will not be returned if seed moisture estimates are unable to be obtained from the sunflower in-field drying model. This may occur if one of the following conditions are met:

  • The sunflower growth model simulation does not bring the crop to maturity. This is more likely to occur for certain location (e.g., cooler climates) and relative maturity combinations.

  • The crop planting date or emergence date are too far in the past. The models are designed for future planning; users can utilize the “current_date” argument to determine what model results could have been on a past date. These results can be different than what would have been seen on the emulated date, as the forecast timeframes are now represented by historical data.

9.7.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/mechanical_drying?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&drying_facility_ids={string}&grain_unit={string}
&target_moisture_content_wb={float}&current_date={timestamp}

9.7.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Accounts API ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have read privileges for the field in which the growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field.

target_moisture_ content_wb

float

yes

Numeric representation of the desired moisture level for safe storage, measured in percent on a wet basis. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

grain_unit

string

yes

Units to use when returning unit costs of drying. Valid values are “bu” (bushel) and “mt” (metric ton).

drying_facility_ids

string

no

Comma-delimited list of drying facility IDs to be used. Currently, only the most recently created facility in the list will be used. Default behavior is to use the most recently created facility overall. Note that the calling user must have at least read privileges for the asset (drying facility).

current_date

timestamp

no

Emulate model results as if viewed on this date2. Useful for viewing approximate model results for historical timeframes greater than one year in the past. There can be differences in results due to what would have been forecasted weather data now being replaced with historical or climatological data used in the calculations.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

9.7.3. Response Object (JSON)

Field Description

asset_id

The ID given to a particular drying facility.

name

The user-provided name of the drying facility. If this is not supplied, a generic name of “Drying Facility” followed by a number is used.

burner_fuel_type

Type of fuel consumed by the burner, as provided by the Accounts API.

burner_fuel_unit

Unit of measure associated with the fuel type, as provided by the Accounts API.

driest_datetime

Time that the grain reached its lowest moisture content of the model run. Represented by a date string in the case of low-temperature drying or hours and minutes in the case of high-temperature drying. Note that the simulation will stop when the user-specified target moisture content is reached, in which case this will indicate the timing of the grain reaching that threshold.

driest_moisture_content_db

Driest dry-basis grain moisture content of the simulation, in percent. Dry-basis moisture content is defined as the ratio of the mass of water to the dry mass of a sample of grain.

driest_moisture_content_wb

Driest wet-basis grain moisture content of the simulation, in percent. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

dryer_throughput_grain_units _per_hour

Amount of grain dried per hour. Applicable only in high-temperature drying facilities.

drying_time

Amount of time, in seconds, that elapsed for the grain to reach its lowest moisture content.

grain_storability

Likelihood of spoilage. Possible values include “0,” indicating that grain is not likely to spoil; “1,” indicating a marginal risk; and “2,” warning that spoilage is likely. When high-temperature drying is in use, “n/a” will be used.

grain_unit

Unit of measure associated with the volume of grain as provided by the user.

per_grain_unit/burner_fuel_ cost

Expected burner fuel cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/burner_fuel _units_consumed

Expected amount of fuel consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/burner _kwh_consumed

Expected amount of fuel energy, in kilowatt-hours, consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/electricity_cost

Expected electricity cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/electricity _kwh_consumed

Expected amount of electrical energy, in kilowatt-hours, consumed by the fan per unit of grain, in the grain unit provided by the user.

per_grain_unit/total_cost

Expected total drying cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit_per_percent_ moisture/total_cost

Expected total drying cost per unit of grain per percent moisture change, in the user’s local currency, and in the grain unit provided by the user.

sample_datetime

Valid time of the grain moisture sample provided by the in-field drydown model.

sample_moisture_content_wb

Starting wet-basis moisture content of the grain sample, in percent, provided by the in-field drydown model.

simulation_length

Total length of time, in seconds, over which the drydown process was modeled.

target_moisture_reached

Flag indicating whether the target storage moisture content is reached in the simulation, where “1” indicates that the storage moisture is reached and “0” indicates it is not. Primarily applicable in low-temperature drying facilities, where ambient environmental conditions may not permit an adequate amount of drying.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum daily air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum daily air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures.

feedback_id

If this field is present, it indicates a confirmed or observed growth stage on the current date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

9.7.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/mechanical_drying?
app_id=123&app_key=321&account_id=abc&user_id=cba&growth_id=xyz
&grain_unit=bu&target_moisture_content_wb=14.5

9.7.5. Example Response

{
    "drying_facilities":[
        {
            "asset_id":"abc-123",
            "data":[
                {
                    "burner_fuel_type":"liquid_propane",
                    "burner_fuel_unit":"gallon",
                    "driest_datetime":"03:10",
                    "driest_moisture_content_db":16.95,
                    "driest_moisture_content_wb":14.49,
                    "dryer_throughput_grain_units_per_hour":546.0,
                    "drying_time":11430,
                    "grain_storability":"n/a",
                    "grain_unit":"bu",
                    "per_grain_unit":{
                        "burner_fuel_cost":0.252,
                        "burner_fuel_units_consumed":0.28,
                        "burner_kwh_consumed":6.91,
                        "electricity_cost":0.008,
                        "electricity_kwh_consumed":0.07,
                        "total_cost":0.26
                    },
                    "per_grain_unit_per_percent_moisture":{
                        "total_cost":0.015
                    },
                    "sample_datetime":"2016-08-30",
                    "sample_moisture_content_wb":31.63,
                    "simulation_length":11430,
                    "target_moisture_reached":1
                },...
           ],
           "name":"Sunflower Dryer"
       }
   ],
    "infield_drydown_data":{
        "47,-97":{
            "2016-08-30":{
                "agdd":2891.0,
                "air_temp_max":81.0,
                "air_temp_min":49.0,
                "equilibrium_moisture_content":5.57,
                "gdd":21.0,
                "grain_moisture_content":31.63,
                "grain_moisture_content_change":"n/a",
                "last_stage":"30",
                "new_stage":"31"
            },...
        }
    }
}

10. Sorghum

10.1. Sorghum Growth - v1.0

Leveraging Iteris’ sorghum growth stage model, the Sorghum Growth endpoint allows users to model the maturation and development of sorghum crops. Users may also take advantage of Accounts API integration to provide crop growth feedback and optimize model results.

10.1.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/growth?app_id={string}
&app_key={string}&location={lat, lon coordinates}&plant_date={timestamp}
&days={integer}&account_id={string}&user_id={string}&growth_id={string}
&relative_maturity={string}

10.1.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

days

integer

yes

yes

Number of days for which to calculate results. Possible values range from 1 to 366.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” “medium,” “medium-late,” and “late.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

10.1.3. Response Object (JSON)

Field Description

attribution

Container for general model credits.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum air temperature valid for the current date, in Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum air temperature valid for the current date, in Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

feedback_id

If this field is present in the output it indicates a confirmed or observed growth stage on that date.

gdd

Growing degree days accumulated on the current date.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

harvest_window/end

Expected end date for harvest operations.

harvest_window/start

Expected start date for harvest operations.

advisor

Suggested field properties to check.

description

Text description for a stage.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Image URL.

name

Stage name.

order

Relative position of the stage within the growth scale.

10.1.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/growth?app_id=123&app_key=321
&location=47,-97&plant_date=1462060800&days=160

10.1.5. Example Response

{
    "attribution":[
        "Descriptions courtesy of Kansas State University (Sorghum Growth and Development. MF3234. Dr. Ciampitti, Crop Production & Cropping Systems Specialist, Dept. of Agronomy, Kansas State University. Ciampitti@ksu.edu; Twitter @KSUCROPS) and Texas A&M University."
    ],
    "data":{
        "47,-97":{
            "growth":{
                "2016-10-15":{
                    "agdd":2757.5,
                    "air_temp_max":72.0,
                    "air_temp_min":44.0,
                    "gdd":11.0,
                    "last_stage":"11",
                    "new_stage":"12"
                },...
            },
            "harvest_window":{
                "end":"2016-11-17",
                "start":"2016-10-22"
            }
        }
    },
    "stage_descriptions":{
        "12":{
            "advisor":"Harvest",
            "description":"Grain achieves its maximum dry weight. Mature grain is identified by looking for the dark spot, the black layer, on the bottom of the kernel. Grain moisture ranges from 25 to 35%.",
            "images":[
                {
                    "attribution":"Courtesy of Kansas State University (Sorghum Growth and Development. MF3234. Dr. Ciampitti, Crop Production & Cropping Systems Specialist, Dept. of Agronomy, Kansas State University. Ciampitti@ksu.edu; Twitter @KSUCROPS).",
                    "caption":"Physiological Maturity",
                    "url":"https://.../Physiological+Maturity.png"
                },...
            ],
            "name":"Physiological Maturity",
            "order":"12"
        },...
    }
}

10.2. Sorghum Growth Add Feedback - v1.0

By providing feedback relating to the growth stage estimates, Iteris will be able to make updates and adjustments to offer its users better results in the future. The given user providing feedback must have write privileges for the field in which the field growth belongs.

Additional information related to feedback timestamp, growth feedback, and feedback stage is available in the Feedback Information section of the Appendix.

10.2.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/growth/feedback/add/
{growth_id}/{timestamp}/{stage}?account_id={string}&user_id={string}
&app_id={string}&app_key={string}

10.2.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

10.2.3. Response Object

A string representing a feedback ID.

10.2.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/growth/feedback/add/
xyz/1472688000/v7.0?account_id=abc&user_id=cba&app_id=123&app_key=321

10.2.5. Example Response

def-345

10.3. Sorghum Growth Feedbacks by Growth - v1.0

Returns a list of growth feedback activities associated with the target growth_id.

10.3.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/growth/feedback/
get/by_growth/{growth_id}?app_id={string}&app_key={string}account_id={string}
&user_id={string}

10.3.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

10.3.3. Response Object (JSON)

Field Description

user_id

User ID provided by and used with the Accounts API.

created

Timestamp denoting when the feedback was created.

data

Information pertaining to the activity.

subtype

Enumeration value representing the specific variety of the activity. Defaults to 0.

growth_feedback_id

ID of target growth feedback.

type

Enumeration value of plant.

feedback/date

Unix timestamp denoting when the feedback happened2.

feedback/stage

Stage provided as feedback.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

10.3.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/growth/feedback/
get/by_growth/xyz?app_id=123&app_key=321&account_id=abc&user_id=cba

10.3.5. Example Response

[
    {
        "user_id":"1234",
        "feedback":{
            "date":1400371200,
            "type":70,
            "stage":"R0"
        },
        "created":1446229281,
        "data":"{}",
        "subtype":"0",
        "growth_feedback_id":"1111",
        "type":70
    },...
]

10.4. Sorghum Growth Modify Feedback - v1.0

The Sorghum Growth Modify Feedback endpoint allows users to modify previously provided growth stage estimate feedback. The given user providing feedback must have write privileges for the field in which the field growth belongs. At least one modification must be provided.

10.4.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/growth/feedback/modify/
{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}&timestamp={integer}&stage={string}

10.4.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

timestamp

integer

yes

An epoch timestamp in seconds representing the date for which the feedback applies2.

stage

string

yes

Inform the system that on the given date, the plant has entered or is currently in the provided stage.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

10.4.3. Response Object

A string representing success (“true”) or failure (“false”).

10.4.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/growth/feedback/
modify/abc-123?account_id=abc&user_id=cba&app_id=123&app_key=321
&timestamp=1472688000&stage=v7.0

10.4.5. Example Response

true

10.5. Sorghum Growth Delete Feedback - v1.0

This endpoint allows users to delete the previously provided growth stage estimate feedback. The given user deleting feedback must have write privileges for the field in which the field growth belongs.

10.5.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/growth/feedback/
delete/{feedback_id}?account_id={string}&user_id={string}&app_id={string}
&app_key={string}

10.5.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

feedback_id

string

yes

A unique ID returned as a result from successfully adding feedback.

10.5.3. Response Object

A string representing success (“true”) or failure (“false”).

10.5.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/growth/
feedback/delete/abc-123?account_id=abc&user_id=cba
&app_id=123&app_key=321

10.5.5. Example Response

true

10.6. Sorghum In-Field Drydown - v1.0

Drawing from the ClearAg Field Weather API and sorghum growth model, the Sorghum In-Field Drydown endpoint simulates the drying process of sorghum grain in the field after the crop achieves full maturity, and provides daily grain moisture estimates during the drydown period. If Accounts API integration is used, any available moisture measurements are used to improve model results.

10.6.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/infield_drydown?
app_id={string}&app_key={string}&location={lat, lon coordinates}
&plant_date={timestamp}&account_id={string}&user_id={string}&growth_id={string}
&relative_maturity={string}

10.6.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the crop was planted or the date of emergence2.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” “medium,” “medium-late,” and “late.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

10.6.3. Response Object (JSON)

Field Description

attribution

Various model attributions.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum air temperature valid for the current date, in Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum air temperature valid for the current date, in Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures. Note that wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

feedback_id

If this field is present, it indicates a confirmed or observed growth stage on the current date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

harvest_window/end

Expected end date for harvest operations.

harvest_window/start

Expected start date for harvest operations.

advisor

Suggested field properties to check.

description

Text description for a growth stage.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Image URL.

name

Growth stage name.

order

Relative position of the stage within the growth scale.

10.6.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/infield_drydown?
app_id=123&app_key=321&location=47,-97&plant_date=1462060800

10.6.5. Example Response

{
    "attribution":[
        "Descriptions courtesy of Kansas State University (Sorghum Growth and Development. MF3234. Dr. Ciampitti, Crop Production & Cropping Systems Specialist, Dept. of Agronomy, Kansas State University. Ciampitti@ksu.edu; Twitter @KSUCROPS) and Texas A&M University."
    ],
    "data":{
        "47,-97":{
            "2016-10-15":{
                "agdd":2757.5,
                "air_temp_max":72.0,
                "air_temp_min":44.0,
                "equilibrium_moisture_content":11.54,
                "gdd":11.0,
                "grain_moisture_content":29.56,
                "grain_moisture_content_change":"n/a",
                "last_stage":"11",
                "new_stage":"12"
            },...
        }
    },
    "harvest_window":{
        "end":"2016-11-17",
        "start":"2016-10-22"
    },
    "stage_descriptions":{
        "12":{
            "advisor":"Harvest",
            "description":"Grain achieves its maximum dry weight. Mature grain is identified by looking for the dark spot, the black layer, on the bottom of the kernel. Grain moisture ranges from 25 to 35%.",
            "images":[
                {
                    "attribution":"Courtesy of Kansas State University (Sorghum Growth and Development. MF3234. Dr. Ciampitti, Crop Production & Cropping Systems Specialist, Dept. of Agronomy, Kansas State University. Ciampitti@ksu.edu; Twitter @KSUCROPS).",
                    "caption":"Physiological Maturity",
                    "url":"https://.../Physiological+Maturity.png"
                }
            ],
            "name":"Physiological Maturity",
            "order":"12"
        },...
    }
}

10.7. Sorghum Nitrogen Advisor - v1.0

The ClearAg Sorghum Nitrogen Advisor simulates the various processes of the nitrogen cycle that impact the availability of nitrogen to sorghum crops. The model is based on a combination of proven algorithms from several industry models for simulating the nitrogen cycle. When used in combination with the Accounts API, the Sorghum Nitrogen Advisor allows provision of several types of field level activities, including fertilizer treatments and soil sample results, containing information such as soil nitrate and organic matter levels, as well as soil pH. Crop growth and the corresponding crop parameters of importance are simulated based on user-specified location, relative maturity, and planting date. Weather and soil information required by the Clear-N model are provided by the ClearAg Field Weather and Soil Conditions APIs, which provide a seamless global dataset of current, forecast, and historical conditions (dating back to 1980) for any arable location globally.

10.7.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/nutrient/nitrogen?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&location={lat, lon coordinates}&plant_date={timestamp}
&yield_goal={integer}&yield_goal_unit={string}&previous_crop={integer}
&previous_harvest_date={timestamp}&previous_yield={integer}
&previous_yield_unit={string}&output_unit={string}&year_offset={integer}
&relative_maturity={string}

10.7.2. Request Parameters

Parameter Type Location-based Accounts API Integration Description

app_id

string

yes

yes

API ID provided by Iteris.

app_key

string

yes

yes

API key provided by Iteris.

account_id

string

no

yes

Your Accounts API account ID.

user_id

string

no

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

growth_id

string

no

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field in the Accounts API.

location

lat, lon coordinates

yes

 — 

User-provided latitude and longitude coordinates in decimal degrees. Limited to a single location per query.

plant_date, emergence_date

timestamp

yes

 — 

Epoch timestamp valid near the time that the current crop was planted or the date of emergence2.

relative_maturity

string

no

 — 

Classification indicating how early a variety matures. Valid values include “early,” “medium-early,” “medium,” “medium-late,” and “late.” Crops that have an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly. Default is “medium.”

yield_goal

integer

yes

yes

Target yield for current crop.

yield_goal_unit

string

yes

yes

Target yield unit. Accepted values are “lb/ac,” “kg/ha,” or “bu/ac”.

previous_crop

integer

no

no

Enumeration value of previous crop on field. Accepted values are currently 50 (barley), 51 (corn), 57 (spring wheat), 59 (canola), 65 (cotton), 66 (soybean), 68 (winter wheat), 69 (vegetable), 70 (sorghum), 71 (pea), 72 (sunflower), 73 (rice), and 74 (alfalfa).

previous_harvest_date

timestamp

no

no

Epoch timestamp valid near the time that the previous crop was harvested2. Required if previous crop is specified. May not predate the planting or emergence date by more than 366 days.

previous_yield

integer

no

no

Actual yield of the previous crop. Required if previous crop is specified.

previous_yield_ unit

string

no

no

Previous yield unit. Accepted values are “lb/ac,” “kg/ha,” or “bu/ac.” Required if previous crop is specified. Note that “bu/ac” is not a valid yield unit for alfalfa, cotton, or vegetable.

output_unit

string

yes

yes

Specifies the unit of the area density data displayed. Accepted values are “lb/ac” or “kg/ha.”

year_offset

integer

no

no

Specifies a number of years by which to adjust model results. Values must be less than 0.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

10.7.3. Response Object (JSON)

Field Description

fertilizer_treatment

Structure holding all fertilizer treatment data utilized by the nitrogen model, including the fertilizer type, application rate, and depth.

soil_sample

Structure holding all soil sample data utilized by the nitrogen model, including the soil nitrate content, organic matter content, pH level, and sample depth.

tillage

Structure holding all tillage data utilized by the nitrogen model, including the tillage type and depth.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum air temperature valid for the current date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the timeframe.

air_temp_min

Minimum air temperature valid for the current date. This value is obtained from recorded values, forecasted values, or climatological averages, depending on the timeframe.

gdd

Growing degree days accumulated on the current date.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

ammonium,
ammonium_XtoY

The amount of nitrogen in the form of ammonium within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters.

ammonium_in_last_sample_depth

The modeled amount of ammonium above the depth of the previous soil sample.

nitrate,
nitrate_XtoY

The amount of nitrogen in the form of nitrate within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters.

nitrate_in_last_sample_depth

The modeled amount of nitrate above the depth of the previous soil sample.

applied_fertilizers,
applied_fertilizers_XtoY

The amount of nitrogen applied as fertilizer resident within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters3.

denitrified,
denitrified_XtoY

The amount of soil nitrate lost from the entire 2-meter depth of the modeled soil profile, or from within the layer spanning from depth=X to depth=Y centimeters, due to the process of denitrification, whereby nitrate is converted into nitrogen gas and then escapes into the atmosphere3.

immobilized,
immobilized_XtoY

The amount of nitrogen that has been immobilized within the entire 2-meter depth of the modeled soil profile, or within the layer spanning from depth=X to depth=Y centimeters, in order to support mineralization of the previous crop’s residues3.

leached,
leached_XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning from depth=X to depth=Y centimeters, due to the process of leaching. Only losses will normally be seen when aggregated across the entire depth of the modeled soil profile; otherwise, some layers may gain nitrate at the expense of others, due to the vertical movement of water within the soil profile3.

leached_below_current_root_depth

The amount of soil nitrate that has been leached below the depth of the current crop’s roots as of the indicated date3.

leached_below_maximum_root_depth

The amount of soil nitrate that has been leached below the maximum depth that the current crop’s roots are expected to reach during the entirety of its growth cycle3.

realized_from_crop_organic_matter,
realized_from_crop_organic_matter_ XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, due to the process of mineralization of residues associated with the previous crop. This can be either positive or negative, depending on the carbon to nitrogen ratio of the previous crop’s residues3.

realized_from_soil_organic_matter,
realized_from_soil_organic_matter_ XtoY

The amount of soil nitrate that has been gained or lost from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, due to the process of mineralization of soil organic matter. Since the carbon to nitrogen ratio of soil organic matter is typically below that associated with the diet of soil microbes, values will normally be positive3.

uptaken_by_crop,
uptaken_by_crop_XtoY

The amount of nitrogen uptaken by the crop from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters. If less than uptaken_by_crop_optimal, this can be indicative of a risk that the crop may be short of nitrogen3.

uptaken_by_crop_optimal,
uptaken_by_crop_optimal_XtoY

The amount of nitrogen the crop would have ideally taken up from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters3.

volatized,
volatized_XtoY

The amount of nitrogen lost by the process of volatization (also referred to as volatilization) from the entire 2-meter depth of the modeled soil profile, or from the layer spanning depth=X to depth=Y centimeters, whereby urea fertilizer is converted into ammonia gas and then escapes into the atmosphere3.

applied_use_efficiency

The crop’s use efficiency of fertilizer-based nitrogen applied since the harvest of the previous crop. Values will be less than or equal to 100%, with higher percentages indicating that the crop has (or will) use a higher percentage of the fertilizers that have been applied.

applied_use_efficiency_unit

Units of “applied_use_efficiency.”

current_root_depth

The depth to which the current crop’s roots are assumed to reach as of the indicated date.

current_root_depth_unit

Units of “current_root_depth.” Chosen automatically based on the user-provided input value of “output_unit.”

indigenous_use_efficiency

The crop’s use efficiency of nitrogen realized through organic matter mineralization since the harvest of the previous crop. Values are in percentages, with higher percentages indicating that the crop has (or will) use a higher percentage of the nitrogen that has been realized through organic matter mineralization. Values in excess of 100% are possible.

indigenous_use_efficiency_unit

Units of “indigenous_use_efficiency.”

maximum_root_depth

The maximum depth to which the current crop’s roots are expected to reach during the entirety of its growth cycle.

maximum_root_depth_unit

Units of “maximum_root_depth.” Chosen automatically based on the user-provided input value of “output_unit.”

nitrogen_available_unit

Units of all data values in the “nitrogen_available” subsection of the returned JSON object.

nitrogen_budget_unit

Units of all data values in the “nitrogen_budget” subsection of the returned JSON object.

notes

A dictionary containing textual descriptions of noteworthy problems or occurrences on the indicated date.

uptake_score

A 0-100 score quantifying the adequacy of crop nitrogen uptake relative to the goals specified in the API call. Higher values indicate better uptake, with values at or near 100 being desirable in order to optimize the crop’s prospects for achieving the caller-specified yield_goal.

uptake_score_unit

Units of “uptake_score.”

advisor

Suggested field properties to check.

description

Text description for a growth stage.

images/attribution

Credit for image.

images/caption

Image description.

images/url

Image URL.

name

Growth stage name.

order

Relative position of a stage within the growth scale.

3 Positive numeric values indicate that nitrogen has been gained by the soil due to the associated process, whereas negative numeric values indicate that nitrogen has been lost by the soil due to the associated process.

10.7.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/nutrient/nitrogen?
app_id=123&app_key=321&account_id=abc&user_id=cba&growth_id=xyz
&previous_harvest_date=1450757200&previous_crop=51&previous_yield=1000
&previous_yield_unit=kg/ha&yield_goal=1050&yield_goal_unit=kg/ha
&output_unit=kg/ha

10.7.5. Example Response

{
    "activities":{
        "fertilizer_treatment":{},
        "soil_sample":{},
        "tillage":{}
    },
    "data":{
        "2016-10-15":{
            "agdd":2757.5,
            "air_temp_max":72.0,
            "air_temp_min":44.0,
            "gdd":11.0,
            "last_stage":"11",
            "new_stage":"12",
            "nitrogen_available":{
                "ammonium":0.0,
                "ammonium_0to2":0.0,
                "ammonium_100to200":0.0,
                "ammonium_10to20":0.0,
                "ammonium_20to40":0.0,
                "ammonium_2to5":0.0,
                "ammonium_40to70":0.0,
                "ammonium_5to10":0.0,
                "ammonium_70to100":0.0,
                "ammonium_in_last_sample_depth":"n/a",
                "nitrate":76.1,
                "nitrate_0to2":0.5,
                "nitrate_100to200":0.0,
                "nitrate_10to20":12.3,
                "nitrate_20to40":35.3,
                "nitrate_2to5":0.9,
                "nitrate_40to70":22.8,
                "nitrate_5to10":2.7,
                "nitrate_70to100":1.6,
                "nitrate_in_last_sample_depth":"n/a"
            },
            "nitrogen_budget":{
                "applied_fertilizers":0.0,
                "applied_fertilizers_0to2":0.0,
                "applied_fertilizers_100to200":0.0,
                "applied_fertilizers_10to20":0.0,
                "applied_fertilizers_20to40":0.0,
                "applied_fertilizers_2to5":0.0,
                "applied_fertilizers_40to70":0.0,
                "applied_fertilizers_5to10":0.0,
                "applied_fertilizers_70to100":0.0,
                "denitrified":0.0,
                "denitrified_0to2":0.0,
                "denitrified_100to200":0.0,
                "denitrified_10to20":0.0,
                "denitrified_20to40":0.0,
                "denitrified_2to5":0.0,
                "denitrified_40to70":0.0,
                "denitrified_5to10":0.0,
                "denitrified_70to100":0.0,
                "immobilized":0.0,
                "immobilized_0to2":0.0,
                "immobilized_100to200":0.0,
                "immobilized_10to20":0.0,
                "immobilized_20to40":0.0,
                "immobilized_2to5":0.0,
                "immobilized_40to70":0.0,
                "immobilized_5to10":0.0,
                "immobilized_70to100":0.0,
                "leached":0.0,
                "leached_0to2":-6.9,
                "leached_100to200":0.0,
                "leached_10to20":-11.6,
                "leached_20to40":18.9,
                "leached_2to5":-9.6,
                "leached_40to70":20.1,
                "leached_5to10":-12.7,
                "leached_70to100":1.8,
                "leached_below_current_root_depth":0.0,
                "leached_below_maximum_root_depth":0.0,
                "realized_from_crop_organic_matter":0.0,
                "realized_from_crop_organic_matter_0to2":0.0,
                "realized_from_crop_organic_matter_100to200":0.0,
                "realized_from_crop_organic_matter_10to20":0.0,
                "realized_from_crop_organic_matter_20to40":0.0,
                "realized_from_crop_organic_matter_2to5":0.0,
                "realized_from_crop_organic_matter_40to70":0.0,
                "realized_from_crop_organic_matter_5to10":0.0,
                "realized_from_crop_organic_matter_70to100":0.0,
                "realized_from_soil_organic_matter":61.0,
                "realized_from_soil_organic_matter_0to2":6.1,
                "realized_from_soil_organic_matter_100to200":0.0,
                "realized_from_soil_organic_matter_10to20":21.7,
                "realized_from_soil_organic_matter_20to40":10.4,
                "realized_from_soil_organic_matter_2to5":9.1,
                "realized_from_soil_organic_matter_40to70":0.0,
                "realized_from_soil_organic_matter_5to10":13.6,
                "realized_from_soil_organic_matter_70to100":0.0,
                "uptaken_by_crop":-22.2,
                "uptaken_by_crop_0to2":-0.3,
                "uptaken_by_crop_100to200":0.0,
                "uptaken_by_crop_10to20":-6.0,
                "uptaken_by_crop_20to40":-9.3,
                "uptaken_by_crop_2to5":-1.0,
                "uptaken_by_crop_40to70":-3.1,
                "uptaken_by_crop_5to10":-2.3,
                "uptaken_by_crop_70to100":-0.2,
                "uptaken_by_crop_optimal":-22.2,
                "uptaken_by_crop_optimal_0to2":-0.5,
                "uptaken_by_crop_optimal_100to200":0.0,
                "uptaken_by_crop_optimal_10to20":-6.0,
                "uptaken_by_crop_optimal_20to40":-9.3,
                "uptaken_by_crop_optimal_2to5":-1.0,
                "uptaken_by_crop_optimal_40to70":-3.1,
                "uptaken_by_crop_optimal_5to10":-2.2,
                "uptaken_by_crop_optimal_70to100":-0.2,
                "volatized":0.0,
                "volatized_0to2":0.0,
                "volatized_100to200":0.0,
                "volatized_10to20":0.0,
                "volatized_20to40":0.0,
                "volatized_2to5":0.0,
                "volatized_40to70":0.0,
                "volatized_5to10":0.0,
                "volatized_70to100":0.0
            },
            "nitrogen_metadata":{
                "applied_use_efficiency":"n/a",
                "applied_use_efficiency_unit":"%",
                "current_root_depth":138.0,
                "current_root_depth_unit":"cm",
                "indigenous_use_efficiency":36.4,
                "indigenous_use_efficiency_unit":"%",
                "maximum_root_depth":138.0,
                "maximum_root_depth_unit":"cm",
                "nitrogen_available_unit":"kg/ha",
                "nitrogen_budget_unit":"kg/ha",
                "notes":{
                    "3":"Soil moisture is limiting crop nitrogen uptake."
                },
                "uptake_score":100.0,
                "uptake_score_unit":"%"
            }
        },...
    },
    "stage_descriptions":{
        "12":{
            "advisor":"Harvest",
            "description":"Grain achieves its maximum dry weight. Mature grain is identified by looking for the dark spot, the black layer, on the bottom of the kernel. Grain moisture ranges from 25 to 35%.",
            "images":[
                {
                    "attribution":"Courtesy of Kansas State University (Sorghum Growth and Development. MF3234. Dr. Ciampitti, Crop Production & Cropping Systems Specialist, Dept. of Agronomy, Kansas State University. Ciampitti@ksu.edu; Twitter @KSUCROPS).",
                    "caption":"Physiological Maturity",
                    "url":"https://.../Physiological+Maturity.png"
                }
            ],
            "name":"Physiological Maturity",
            "order":"12"
        },...
    }
}

10.8. Sorghum Mechanical Drying - v1.0

The Sorghum Mechanical Drying endpoint simulates the drydown process of sorghum using either fan-powered low-temperature drying or burner-driven high-temperature drying facilities to provide drying statistics and cost projections. The mechanical drying process is simulated using up to 10 future days of grain moisture estimates. Results from the sorghum in-field drying model are also returned for comparison.

Note that a field, growth, and drying facility are required to utilize this feature. Any available grain moisture measurements are used to improve model results.

Please be aware that mechanical drying data will not be returned if grain moisture estimates are unable to be obtained from the sorghum in-field drying model. This may occur if one of the following conditions are met:

  • The sorghum growth model simulation does not bring the crop to maturity. This is more likely to occur for certain location (e.g., cooler climates) and relative maturity combinations.

  • The crop planting date or emergence date are too far in the past. The models are designed for future planning; users can utilize the “current_date” argument to determine what model results could have been on a past date. These results can be different than what would have been seen on the emulated date, as the forecast timeframes are now represented by historical data.

10.8.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/mechanical_drying?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&drying_facility_ids={string}&grain_unit={string}
&target_moisture_content_wb={float}&current_date={timestamp}

10.8.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Accounts API ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have read privileges for the field in which the growth is assigned.

growth_id

string

yes

Growth ID provided by and used with the Accounts API. This ID is given when a growth is successfully added to a field.

target_moisture_ content_wb

float

yes

Numeric representation of the desired moisture level for safe storage, measured in percent on a wet basis. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

grain_unit

string

yes

Units to use when returning unit costs of drying. Valid values are “bu” (bushel) and “mt” (metric ton).

drying_facility_ids

string

no

Comma-delimited list of drying facility IDs to be used. Currently, only the most recently created facility in the list will be used. Default behavior is to use the most recently created facility overall. Note that the calling user must have at least read privileges for the asset (drying facility).

current_date

timestamp

no

Emulate model results as if viewed on this date2. Useful for viewing approximate model results for historical timeframes greater than one year in the past. There can be differences in results due to what would have been forecasted weather data now being replaced with historical or climatological data used in the calculations.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

10.8.3. Response Object (JSON)

Field Description

asset_id

The ID given to a particular drying facility.

name

The user-provided name of the drying facility. If this is not supplied, a generic name of “Drying Facility” followed by a number is used.

burner_fuel_type

Type of fuel consumed by the burner, as provided by the Accounts API.

burner_fuel_unit

Unit of measure associated with the fuel type, as provided by the Accounts API.

driest_datetime

Time that the grain reached its lowest moisture content of the model run. Represented by a date string in the case of low-temperature drying or hours and minutes in the case of high-temperature drying. Note that the simulation will stop when the user-specified target moisture content is reached, in which case this will indicate the timing of the grain reaching that threshold.

driest_moisture_ content_db

Driest dry-basis grain moisture content of the simulation, in percent. Dry-basis moisture content is defined as the ratio of the mass of water to the dry mass of a sample of grain.

driest_moisture_content_wb

Driest wet-basis grain moisture content of the simulation, in percent. Wet-basis moisture content is defined as the ratio of the mass of water to the total mass of a sample of grain.

dryer_throughput_grain_units _per_hour

Amount of grain dried per hour. Applicable only in high-temperature drying facilities.

drying_time

Amount of time, in seconds, that elapsed for the grain to reach its lowest moisture content.

grain_storability

Likelihood of spoilage. Possible values include “0,” indicating that grain is not likely to spoil; “1,” indicating a marginal risk; and “2,” warning that spoilage is likely. When high-temperature drying is in use, “n/a” will be used.

grain_unit

Unit of measure associated with the volume of grain as provided by the user.

per_grain_unit/burner_fuel_ cost

Expected burner fuel cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/burner_fuel_ units_consumed

Expected amount of fuel consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/burner_kwh_ consumed

Expected amount of fuel energy, in kilowatt-hours, consumed by the burner per unit of grain, in the grain unit provided by the user.

per_grain_unit/electricity_cost

Expected electricity cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit/electricity_kwh_ consumed

Expected amount of electrical energy, in kilowatt-hours, consumed by the fan per unit of grain, in the grain unit provided by the user.

per_grain_unit/total_cost

Expected total drying cost per unit of grain, in the user’s local currency, and in the grain unit provided by the user.

per_grain_unit_per_percent_ moisture/total_cost

Expected total drying cost per unit of grain per percent moisture change, in the user’s local currency, and in the grain unit provided by the user.

sample_datetime

Valid time of the grain moisture sample provided by the in-field drydown model.

sample_moisture_content_wb

Starting wet-basis moisture content of the grain sample, in percent, provided by the in-field drydown model.

simulation_length

Total length of time, in seconds, over which the drydown process was modeled.

target_moisture_reached

Flag indicating whether the target storage moisture content is reached in the simulation, where “1” indicates that the storage moisture is reached and “0” indicates it is not. Primarily applicable in low-temperature drying facilities, where ambient environmental conditions may not permit an adequate amount of drying.

agdd

Aggregate growing degree days from plant or emergence date, including the current date.

air_temp_max

Maximum daily air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum daily air temperature valid for the current date. Obtained from historical, forecast, or climatological data, depending on the timeframe.

equilibrium_moisture_content

The wet-basis moisture content, in percent, at which the grain is neither gaining nor losing moisture. Changes with relative humidity and air temperature. Provided after the crop fully matures.

feedback_id

If this field is present, it indicates a confirmed or observed growth stage on the current date.

gdd

Growing degree days accumulated on the current date.

grain_moisture_content

Percent wet-basis moisture content of the grain at the end of the day. Provided after the crop fully matures.

grain_moisture_content_change

The change in the amount of wet-basis moisture in the grain since the previous day, in percent. Positive values indicate that the moisture content has increased, and negative values indicate that the moisture content has decreased. Provided after the crop fully matures.

last_stage

The last known growth stage.

new_stage

The crop may have entered a new growth stage between the current date and the previous date. If new_stage is null, the crop is somewhere between the previous growth stage and the next growth stage.

10.8.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sorghum/mechanical_drying?
app_id=123&app_key=321&account_id=abc&user_id=cba&growth_id=xyz
&grain_unit=bu&target_moisture_content_wb=14.5

10.8.5. Example Response

{
    "drying_facilities":[
        {
            "asset_id":"abc-123",
            "data":[
                {
                    "burner_fuel_type":"liquid_propane",
                    "burner_fuel_unit":"gallon",
                    "driest_datetime":"09:50",
                    "driest_moisture_content_db":16.96,
                    "driest_moisture_content_wb":14.5,
                    "dryer_throughput_grain_units_per_hour":176.0,
                    "drying_time":35430,
                    "grain_storability":"n/a",
                    "grain_unit":"bu",
                    "per_grain_unit":{
                        "burner_fuel_cost":0.412,
                        "burner_fuel_units_consumed":0.458,
                        "burner_kwh_consumed":11.3,
                        "electricity_cost":0.025,
                        "electricity_kwh_consumed":0.2,
                        "total_cost":0.438
                    },
                    "per_grain_unit_per_percent_moisture":{
                        "total_cost":0.031
                    },
                    "sample_datetime":"2016-08-13",
                    "sample_moisture_content_wb":28.7,
                    "simulation_length":35430,
                    "target_moisture_reached":1
                },...
            ],
            "name":"Sorghum Dryer"
        }
    ],
    "infield_drydown_data":{
        "32,-100":{
            "2016-08-13":{
                "agdd":2765.5,
                "air_temp_max":87.0,
                "air_temp_min":66.0,
                "equilibrium_moisture_content":11.38,
                "gdd":26.5,
                "grain_moisture_content":28.7,
                "grain_moisture_content_change":"n/a",
                "last_stage":"11",
                "new_stage":"12"
            },...
        }
    }
}

11. Field Soil Sample

11.1. Add Field Soil Sample - v1.0

This endpoint allows a user to add a soil sample. When adding a soil sample, the activity will be automatically added to the field whitelist. While active on the field whitelist for which a target growth resides, the soil sample activity will be used to improve various model/advisor results (e.g., the nitrogen advisor).

11.1.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/soil_sample/add/{field_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&start_depth={float}&end_depth={float}&depth_unit={string}&nitrate={float}
&nitrate_unit={string}&organic_matter={float}&activity_time={timestamp}

11.1.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_id

string

yes

Specifies ID of field to be updated.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have write privileges for the field to which a sample is being added.

start_depth

float

yes

Starting depth of soil sample. Must be less than or equal to end_depth.

end_depth

float

yes

Ending depth of soil sample. Must be greater than or equal to start_depth.

depth_unit

string

yes

This value can be “m,” “ft,” “cm,” or “in.” (This is not case sensitive, but is stored as lowercase.)8

nitrate

float

*

Minimum value is 0.0. *If nitrate is included then nitrate_unit is required.8

nitrate_unit

string

*

This value can be “lb/ac” or “kg/ha.” (This is not case sensitive, but is stored as lowercase). *If nitrate_unit is included then nitrate is required.8

organic_matter

float

no

The range of this parameter must be between 0.0-100.08.

ph

float

no

Decimal logarithm of the reciprocal of hydrogen ion activity in a solution. The range must be between 0.0-14.08.

activity_time

timestamp

no

Time activity took place, which defaults to current UTC time2.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

8 At least one of the annotated parameters is required.

11.1.3. Response Object

Returns the UUID of the created soil sample activity.

11.1.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/soil_sample/add/abc-123?
app_id=123&app_key=321&account_id=123&user_id=xyz-123&start_depth={float}
&end_depth={float}&depth_unit=m

11.1.5. Example Response

def-345

11.2. Get Field Soil Sample - v1.0

This endpoint allows users to receive a soil sample.

11.2.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/soil_sample/get/
{field_activity_id}?app_id={string}&app_key={string}&account_id={string}
&user_id={string}

11.2.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_activity_id

string

yes

Specifies ID of the given field activity.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the sample is being gained.

11.2.3. Response Object (JSON)

Field Description

field_activity_id

ID of soil_sample activity.

created

Time of sample creation.

activity_type

Enumeration value representing the type of activity performed.

activity_time

The time the activity was performed. Defaults to current time.

modified

Time of last modification.

start_depth

Starting depth of soil sample.

end_depth

Ending depth of soil sample.

depth_unit

Unit for depth.

nitrate

Amount of nitrate.

nitrate_unit

Unit for nitrate measurement.

organic_matter

Percent of organic matter in sample.

ph

Float value of ph sample (0.0-14.0).

11.2.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/soil_sample/get/
456-789?app_id=123&app_key=321&account_id=123&user_id=xyz-123

11.2.5. Example Response

{
    "field_activity_id":"123-456",
    "created":1458059561,
    "modified":1458099561,
    "activity_time":1458099561,
    "start_depth":5,
    "end_depth":7.9,
    "depth_unit":"in",
    "nitrate":97.89,
    "nitrate_unit":"lb/ac",
    "organic_matter":29.9842,
    "ph":4.7,
    "subtype":0
}

11.3. Get Field Soil Samples by Field - v1.0

This endpoint allows for a user to receive all soil samples associated with a given field.

11.3.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/soil_sample/
get/by_field/{field_id}?app_id={string}&app_key={string}
&account_id={string}&user_id={string}

11.3.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_id

string

yes

Specifies ID of field.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have privileges to view information for the field to which the target growth is assigned.

11.3.3. Response Object (JSON)

Field Description

created

Time of sample creation.

activity_type

Enumeration value representing the type of activity performed.

activity_time

The time the activity was performed. Defaults to current time.

created_by

User_id of user that created activity.

modified

Time of last modification.

modified_by

User_id who last modified activity.

start_depth

Starting depth of soil sample.

end_depth

Ending depth of soil sample.

depth_unit

Unit for depth.

nitrate

Amount of nitrate.

nitrate_unit

Unit for nitrate measurement.

organic_matter

Percent of organic matter in sample.

ph

Float value of ph sample (0.0-14.0).

whitelist

Boolean value which denotes membership in field’s whitelist.

11.3.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/soil_sample/
get/by_field/abc-123?app_id=123&app_key=321&account_id=123
&user_id=xyz-123

11.3.5. Example Response

[
    {
        "field_activity_id":"123-456",
        "activity_time":1458059561,
        "created":1458059561,
        "modified":1458099561,
        "start_depth":5,
        "end_depth":7.9,
        "depth_unit":"in",
        "nitrate":97.89,
        "nitrate_unit":"lb/ac",
        "organic_matter":29.9842,
        "ph":4.7,
        "subtype":0,
        "whitelist":false
    },...
]

11.4. Modify Field Soil Sample - v1.0

The Modify Field Soil Sample endpoint allows users to modify an existing soil sample.

11.4.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/soil_sample/
modify/{field_activity_id}?app_id={string}&app_key={string}
&account_id={string}&user_id={string}&start_depth={float}
&end_depth={float}&depth_unit={string}&nitrate={float}
&nitrate_unit={string}&organic_matter={float}
&ph={float}&activity_time={timestamp}

11.4.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_activity_id

string

yes

Specifies ID of the given field activity.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have write privileges for the field to which the soil sample is being modified.

start_depth

float

no

Starting depth of soil sample5.

end_depth

float

no

Ending depth of soil sample5.

depth_unit

string

no

value can be “m,” “ft,” “cm,” or “in.” (This is not case sensitive, but is stored as lowercase.)

nitrate

float

no

Minimum value for this parameter is 0.06.

nitrate_unit

string

no

The value must be “lb/ac” or “kg/ha.” (This is not case sensitive, but is stored as lowercase)6.

organic_matter

float

no

The range for this value is 0.0-100.0.

ph

float

no

Decimal logarithm of the reciprocal of hydrogen ion activity in a solution. The range for this value is 0.0-14.0.

activity_time

timestamp

no

Time activity took place, which defaults to current UTC time2.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

5 start_depth and end_depth: if one is included, the other parameter is required. If included, start_depth must be less than or equal to end_depth.

6 nitrate and nitrate_unit: if one is included, the other parameter is required. If included, both parameters must be either both set to valid values or both set to “null.”

11.4.3. Response Object

A string representing success (“true”) or failure (“false”).

11.4.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/soil_sample/
modify/456-789?app_id=123&app_key=321&account_id=123&user_id=xyz-123

11.4.5. Example Response

true

11.5. Delete Field Soil Sample - v1.0

Through this endpoint users are able to delete a previously created soil sample.

11.5.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/soil_sample/delete/
{field_activity_id}?app_id={string}&app_key={string}&account_id={string}
&user_id={string}

11.5.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_activity_id

string

yes

Specifies ID of the given field activity.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User ID provided by and used with the Accounts API. The user must have write privileges for the field to which the target growth is assigned.

11.5.3. Response Object

A string representing success (“true”) or failure (“false”).

11.5.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/soil_sample/delete/
456-789?app_id=123&app_key=321&account_id=123&user_id=xyz-123

11.5.5. Example Response

true

12. Fertilizer Treatment

12.1. Add Fertilizer Treatment - v1.0

This endpoint allows the user to add a field activity (fertilizer treatment) to a field. Upon creation, fertilizer treatment activities are automatically added to the target fields’ whitelist.

12.1.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/fertilizer_treatment/
add/{field_id}/?app_id={string}&app_key={string}&account_id={string}
&user_id={string}&fertilizer_id={integer}&rate={float}&rate_unit={string}
&depth={float}&depth_unit={string}

12.1.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_id

string

yes

Specifies ID of field in which the activity is being applied.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

This ID is provided as a result of creating a new user.

fertilizer_id

integer

yes

Enumeration value representing the type of fertilizer.4

rate

float

yes

The amount of fertilizer used in the application.

rate_unit

string

yes

The unit associated with the rate of application4.

depth

float

yes

The depth at which the application was applied.

depth_unit

string

yes

The unit associated with the depth. Valid options are “m,” “ft,” “cm,” and “in.”

activity_time

timestamp

no

The time the activity was performed. Defaults to current time2.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

4 Please refer to the Fertilizer Types section of the Appendix for a complete listing of coded values and their meanings.

12.1.3. Response Object

Returns the field_activity_id that was created.

12.1.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/fertilizer_treatment/
add/abc-123/?app_id=123&app_key=321&account_id=abf-345&user_id=bcd-678
&fertilizer_id=13&rate=1.0&rate_unit=lb/ac&depth=1&depth_unit=in

12.1.5. Example Response

def-345

12.2. Get All Fertilizer Treatment By Field ID - v1.0

This endpoint allows the user to get all fertilizer treatment activities on a field.

12.2.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/fertilizer_treatment/
get/by_field/{field_id}/?app_id={string}&app_key={string}&account_id={string}
&user_id={string}

12.2.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_id

string

yes

Specifies ID of field in which all fertilizer treatment activities are returned.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

This ID is provided as a result of creating a new user.

12.2.3. Response Object (JSON)

Field Description

activity_time

Timestamp when the activity occurred.

activity_type

Enumeration value representing the type of activity. This will always be 308 for fertilizer treatments5.

created

Timestamp when the activity was created in the system.

depth

The float valued depth at which the fertilizer was applied.

depth_unit

The unit associated with the depth. Valid options are “m,” “ft,” “cm,” and “in.”

fertilizer_id

Enumeration value of the fertilizer used4.

field_activity_id

UUID of the field activity.

modified

Timestamp of when the activity was modified. This is set to null by default.

rate

The amount of fertilizer used in the application.

rate_unit

The unit associated with the rate of application4.

subtype

Subtype of activity. Defaults to 0.

whitelist

Boolean denoting membership of the activity in the field’s whitelist.

4 Please refer to the Fertilizer Types section of the Appendix for a complete listing of coded values and their meanings.

12.2.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/fertilizer_treatment/
get/by_field/abc-123/?app_id=123&app_key=321&account_id=def-345&user_id=bcd-678

12.2.5. Example Response

[
    {
        "activity_time":1459802785,
        "activity_type":308,
        "created":1459802785,
        "depth":1.0,
        "depth_unit":"in",
        "fertilizer_id":16,
        "field_activity_id":"cef-345",
        "modified":null,
        "rate_unit":"lb/ac",
        "subtype":0,
        "whitelist":true
    },...
]

12.3. Get Fertilizer Treatment by Field Activity ID - v1.0

This endpoint allows the user to get one specific fertilizer treatment activity on a field.

12.3.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/fertilizer_treatment/
get/{field_activity_id}/?app_id={string}&app_key={string}&account_id={string}
&user_id={string}

12.3.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

activity_id

string

yes

Specifies ID of target activity to get.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

This ID is provided as a result of creating a new user.

12.3.3. Response Object (JSON)

Field Description

activity_time

Timestamp when the activity occurred.

activity_type

Enumeration value representing the type of activity. This will always be 308 for fertilizer treatments5.

created

Timestamp when the activity was created in the system.

depth

The float valued depth at which the fertilizer was applied.

depth_unit

The unit associated with the depth. Valid options are “m,” “ft,” “cm,” and “in.”

fertilizer_id

Enumeration value of the fertilizer used4.

field_activity_id

UUID of the field activity.

modified

Timestamp of when the activity was modified. This is set to null by default.

rate

The amount of fertilizer used in the application.

rate_unit

The unit associated with the rate of application4.

subtype

Subtype of activity. Defaults to 0.

4 Please refer to the Fertilizer Types section of the Appendix for a complete listing of coded values and their meanings.

12.3.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/fertilizer_treatment/
get/abc-123/?app_id=123&app_key=321&account_id=def-345&user_id=bcd-678

12.3.5. Example Response

{
    "activity_time":1459802785,
    "activity_type":308,
    "created":1459802785,
    "depth":1.0,
    "depth_unit":"in",
    "fertilizer_id":16,
    "field_activity_id":"cef-345",
    "modified":null,
    "rate":1.0,
    "rate_unit":"lb/ac",
    "subtype":0
}

12.4. Modify Fertilizer Treatment - v1.0

This endpoint allows the user to modify an existing fertilizer treatment activity.

12.4.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/
field/activity/fertilizer_treatment/modify/{field_id}/?
app_id={string}&app_key={string}&account_id={string}
&user_id={string}&rate={float}&rate_unit={string}
&depth={float}&depth_unit={string}
&activity_time={timestamp}&fertilizer_id={integer}

12.4.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_id

string

yes

Specifies ID of field in which to assign crop growth data.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

This ID is provided as a result of creating a new user.

rate

float

no

The amount of fertilizer used in the application.

rate_unit

string

no

The unit associated with the rate of application4.

depth

float

no

The depth at which the application was applied.

depth_unit

string

no

The unit associated with the depth. Valid options are “m,” “ft,” “cm,” and “in.”

activity_time

timestamp

no

The time the activity was performed2.

fertilizer_id

integer

no

Enumeration of the fertilizer type used in treatment4.

2 Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

4 Please refer to the Fertilizer Types section of the Appendix for a complete listing of coded values and their meanings.

12.4.3. Response Object

A string representing success (“true”) or failure (“false”).

12.4.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/field/activity/
fertilizer_treatment/modify/abc-123/?app_id=123&app_key=321
&account_id=def-345&user_id=bcd-678&depth_unit=m

12.4.5. Example Response

true

13. Drydown Features

13.1. Create Low Temperature Drying Facility - v1.0

This endpoint allows a user to create a low temperature drying facility asset (type 0).

13.1.1. URL Description

http://ag.us.clearapis.com/v1.0/asset/drying_facility/low_temp/create?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&electricity_cost={float}&electricity_cost_unit={string}
&fan_distribution_area={float}&fan_distribution_area_unit={string}
&grain_thickness={float}&grain_thickness_unit={string}
&name={string}&fan_efficiency={float}&latitude={float}
&longitude={float}&location={lat, lon coordinates}
&field_id={string}&fan_power={float}
&fan_power_unit={string}&airflow={float}
&airflow_unit={float}

13.1.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

sting

yes

User ID provided by and used with the Accounts API.

electricity_cost

float

yes

The cost to supply energy to the drying facility. Entry must be greater than zero.

electricity_cost_unit

string

yes

The unit denoting electricity cost (“kwh”).

fan_distribution_area

float

yes

The area to which the drying fan impacts. Entry must be greater than zero.

fan_distribution_area_unit

string

yes

The unit denoting the fan distribution (“m^2” or “ft^2”).

grain_thickness

float

yes

The thickness of the grain being dryed in the given facility. Entry must be greater than zero.

grain_thickness_unit

string

yes

The unit denoting the thickness of grain being dried (“m” or “ft”).

name

string

no

Defaults to “unnamed.”

fan_efficiency

float

no

If fan_efficiency is not provided, the default will be a value of 0.47. If fan_efficiency is provided, but a value of “null” is used, the property will be stored as “null.”

latitude

float

no

The range varies from -90 to 90. Longitude is required but if location or field_id are provided a 400 response is returned.

longitude

float

no

The range varies from -360 to 360. Latitude is required but if location or field_id are provided a 400 response is returned.

location

lat, lon coordinates

no

In the form of “{latitude},{longitude}.” If latitude, longitude, or field_id are provided a 400 response is returned.

field_id

string

yes4

Used to get latitude and longitude. If latitude, longitude, or field_id are provided a 400 response is returned.

fan_power

float

yes4

The value of the entry must be greater than zero and requires fan_power_unit. If airflow or airflow_unit are provided a 400 response is returned.

fan_power_unit

string

yes4

The units include “kw” or “hp” and requires fan_power. If airflow or airflow_unit are provided a 400 response is returned.

airflow

float

yes4

This entry must be greater than zero and requires airflow_unit. If fan_power or fan_power_unit are provided a 400 response is returned.

airflow_unit

float

yes4

The units include “m^3/s” or “ft^3/min,” and requires airflow. If fan_power or fan_power_unit are provided a 400 response is returned.

4 Denotes special rules for if a parameter is required or not.

13.1.3. Response Object

Returns asset ID.

13.1.4. Example Request

http://ag.us.clearapis.com/v1.0/asset/drying_facility/low_temp/create?
app_id=123&app_key=321&account_id=123&user_id=xyz-123
&electricity_cost=10&electricity_cost_unit=kwh
&fan_distribution_area=15&fan_distribution_area_unit=ft^2
&grain_thickness=2&grain_thickness_unit=f
t&location=47.279229,-101.381836&fan_power=12
&fan_power_unit=kw

13.1.5. Example Response

fgh-567

13.2. Create High Temperature Drying Facility - v1.0

This endpoint allows users to create a high temperature drying facility asset (type 1).

13.2.1. URL Description

http://ag.us.clearapis.com/v1.0/asset/drying_facility/high_temp/create?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&electricity_cost={float}&electricity_cost_unit={string}
&fan_distribution_area={float}&fan_distribution_area_unit={string}
&grain_thickness={float}&grain_thickness_unit={string}
&fuel_type={string}&fuel_unit={string}&fuel_cost_per_unit={float}
&plenum_temperature={float}&plenum_temperature_unit={float}
&name={string}&fan_efficiency={float}&latitude={float}
&longitude={float}&location={lat, lon coordinates}&field_id={string}
&fan_power={float}&fan_power_unit={string}
&airflow={float}&airflow_unit={float}

13.2.2. Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

sting

yes

User ID provided by and used with the Accounts API.

electricity_cost

float

yes

The cost to supply energy to the drying facility. Entry must be greater than zero.

electricity_cost_unit

string

yes

The unit denoting electricity cost (“kwh”).

fan_distribution_area

float

yes

The area to which the drying fan impacts. Entry must be greater than zero.

fan_distribution_area_unit

string

yes

The unit denoting the fan distribution (“m^2” or “ft^2”).

grain_thickness

float

yes

The thickness of the grain being dryed in the given facility. Entry must be greater than zero.

grain_thickness_unit

string

yes

The unit denoting the thickness of grain being dried (“m” or “ft”).

fuel_type

string

yes

This is either liquid_propane or natural_gas. If a fuel type of “liquid_propane” is provided, then the following fuel_unit values are valid: “l, “gal,” “lb,” or “kg.” If a fuel type of “natural_gas” is provided, then the following fuel_unit values are valid: “lb” or “kg.”

fuel_unit

string

yes

If a fuel type of “liquid_propane” is provided, then the following fuel_unit values are valid: “l, “gal,” “lb,” or “kg.” If a fuel type of “natural_gas” is provided, then the following fuel_unit values are valid: “lb” or “kg.”

fuel_cost_per_unit

float

yes

This entry must be greater than zero.

plenum_temperature

float

yes

Temperature output in drying facility.

plenum_temperature_unit

string

yes

Unit can be either “c” or “f,” and is required if plenum_temperature is provided.

name

string

no

Defaults to “unnamed.”

fan_efficiency

float

no

If fan_efficiency is not provided, the default will be a value of 0.47. If fan_efficiency is provided, but a value of “null” is used, the property will be stored as “null.”

latitude

float

no

The range varies from -90 to 90. Longitude is required but if location or field_id are provided a 400 response is returned.

longitude

float

no

The range varies from -360 to 360. Latitude is required but if location or field_id are provided a 400 response is returned.

location

lat, lon coordinates

no

In the form of “{latitude},{longitude}.” If latitude, longitude, or field_id are provided a 400 response is returned.

field_id

string

yes4

Used to get latitude and longitude. If latitude, longitude, or field_id are provided then a 400 response is returned.

fan_power

float

yes4

The value of the entry must be greater than zero and requires fan_power_unit. If airflow or airflow_unit are provided then a 400 response is returned.

fan_power_unit

string

yes4

The units include “kw” or “hp” and requires fan_power. If airflow or airflow_unit are provided then a 400 response is returned.

airflow

float

yes4

This entry must be greater than zero and requires airflow_unit. If fan_power or fan_power_unit are provided then a 400 response is returned.

airflow_unit