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 Creation - v1.0

This endpoint allows users to create a corn growth on an existing field. The given user adding the corn growth must have write privileges for the field being updated.

1.1.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/corn/growth/create/{field_id}?
account_id={string}&user_id={string}&plant_date={timestamp}
&relative_maturity={integer}&min_soil_moisture_allowed={float}
&max_soil_moisture_allowed={float}

1.1.2. Request Parameters

Parameter Type Required Description

account_id

string

yes

Your Accounts API account ID.

field_id

string

yes

Specifies ID of field to be updated.

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.

plant_date, emergence_date

timestamp

yes

Epoch timestamp valid near the time that the crop reached emergence2.

relative_maturity

integer

no

Gauges how long it will take for the crop to mature. Relative maturity must be an integer between 70 and 130. Lower numerical values represent “early” relative maturity, resulting in plants maturing fast. A higher numerical value represents crops that have a “late” relative maturity, meaning a relatively slow maturity. If no value is provided, the default relative maturity is 100.

min_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level. Values must be greater than 0.0 and less than 100.0

max_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level. Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0

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

1.1.3. Response Object

A string representing a growth ID.

1.1.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/corn/growth/create/abc-123?
account_id=123&user_id=xyz-123&app_id=456&app_key=789&plant_date=1393632000
&relative_maturity=88

1.1.5. Example Response

abc-def

1.2. Corn Get Growth - v1.0

This endpoint allows a user to receive a previously created growth based on growth ID.

1.2.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/corn/growth/get/{growth_id}?
plant={string}&account_id={string}&user_id={string}

1.2.2. Request Parameters

Parameter Type Required Description

plant

string

yes

Name of plant (i.e. corn or winter_wheat).

growth_id

string

yes

Specifies ID of crop growth to be queried from the user information database, provided by the Create Growth endpoint.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

1.2.3. Response Object (JSON)

Field Description

acres

Areal size of the field in acres.

created

Epoch timestamp in seconds.2

field_id

Specifies ID of field to which crop growth data has been assigned.

field_name

Name of the field.

growth_id

Specifies ID of crop growth queried.

harvest_date

An epoch timestamp in seconds for which harvest has begun.2

irrigation_type

Represents whether or not the cropland utilizes pivot irrigation. Valid values: 0 is “false” and 1 is “true.”

latitude

Latitude coordinate near the center of the field in decimal degrees.

longitude

Longitude coordinate near the center of the field in decimal degrees.

min_soil_moisture_allowed

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level Values must be greater than 0.0 and less than 100.0.

max_soil_moisture_allowed

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level. Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0

name

Name of the growth.

plant_date

Approximate time at which the crop was planted.

plant_name

Name of the crop plant.

plant_type

Coded value representing the type of crop planted. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

plant_subtype

Coded value representing the specific variety of crop planted.

plant_type

Enumeration value representing plant sub-type.

relative_maturity

Classification indicating how early a variety matures. Depending on the crop, valid values may include “early,” “medium-early,” “medium,” “medium-late,” or “late,” — where crops having an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

seed_variety

Additional description or notes for the seed used.

subdrainage_type

Represents whether or not the cropland utilizes drainage tile. Valid values: 0 is “false” (default) and 1 is “true.”

surface_drainage_quality

Represents field drainage effectiveness. Valid values: 0 is poor, 1 is average, and 2 is good.

previous_crop

Type ID of previously planted crop.

previous_harvest_date

Epoch time which previous crop was harvested.2

previous_yield

Yield of previous crop.

previous_yield_unit

Unit of measure for previous yield.

yield_goal

Yield target of current growth.

yield_goal_unit

Unit of measure for yield goal.

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

1.2.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/corn/growth/get/bcd-def?
&account_id=123&user_id=xyz-123

1.2.5. Example Response

{
    "acres":160.0,
    "created":1498058928,
    "field_id":"abc-def",
    "field_name":"MyField",
    "growth_id":"bcd-def",
    "harvest_date":null,
    "irrigation_type":0,
    "latitude":47.92338180541992,
    "longitude":-97.0919189453125,
    "min_soil_moisture_allowed":12.32,
    "max_soil_moisture_allowed":24.48,
    "name":"MyGrowth",
    "plant_date":1398920400,
    "plant_name":"corn",
    "plant_subtype":0,
    "plant_type":51,
    "relative_maturity":"73",
    "seed_variety":null,
    "subdrainage_type":0,
    "surface_drainage_quality":1
}

1.3. Corn Growth Modify - v1.0

This endpoint allows a user to modify an existing corn growth.

1.3.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/corn/growth/modify/{growth_id}?
account_id={string}&user_id={string}&plant_date={timestamp}
&relative_maturity={integer}&min_soil_moisture_allowed={float}
&max_soil_moisture_allowed={float}

1.3.2. Request Parameters

Parameter Type Required Description

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.

plant_date, emergence_date

timestamp

yes

Epoch timestamp valid near the time that the crop reached emergence2.

growth_id

string

yes

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

relative_maturity

integer

no

Gauges how long it will take for the crop to mature. Relative maturity must be an integer between 70 and 130. Lower numerical values represent “early” relative maturity, resulting in plants maturing fast. A higher numerical value represents crops that have a “late” relative maturity, meaning a relatively slow maturity. If no value is provided, the default relative maturity is 100.

min_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level. Values must be greater than 0.0 and less than 100.0

max_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0.

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

1.3.3. Response Object

Returns “true” on success.

1.3.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/corn/growth/modify/abc-123?account_id=123&user_id=xyz-123&plant_date=1456890400&relative_maturity=100

1.3.5. Example Response

true

1.4. Corn Growth Delete - v1.0

The endpoint allows a user to delete a corn growth. By deleting a growth, any applicable growth feedback and growth whitelist items will also be deleted.

1.4.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/corn/growth/delete/{growth_id}?
account_id={string}&user_id={string}

1.4.2. Request Parameters

Parameter Type Required Description

growth_id

string

yes

The ID of the target growth to delete.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

sring

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

1.4.3. Response Object

Returns “true” on success.

1.4.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/corn/growth/delete/abc-def?
account_id=123&user_id=xyz-123

1.4.5. Example Response

true

1.5. 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.5.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.5.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.5.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.5.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.5.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.6. 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.6.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.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.

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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.6.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.6.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.6.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.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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":".../Figure_12_ISUE300.jpg"
                },...
            ],
            "name":"VE - Emergence",
            "order":"1"
        },...
    }
}

1.8. 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.8.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.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.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; 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.8.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.8.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"
            },...
        }
    }
}

1.9. 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.9.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}
&use_unconfirmed={flag}
&relative_maturity={integer}

1.9.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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 emergence.2

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 harvested.2 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.

use_unconfirmed

flag

no

yes

When included in the query string, the nitrogen model will use all fertilizer treatment activities with confirmed value of “true” and “false.” If there exists a fertilizer treatment activity with a “rate” value of “null,” the nitrogen model will provide a rate recommendation.

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

fertilizer_treatment

Structure holding all fertilizer treatment data utilized by the nitrogen model, including the fertilizer type, application rate, and depth. Each fertilizer treatment activity will have an addition property of “recommendation,” which is “true” if the “rate” is a recommendation calculated by the nitrogen model or “false” if the “rate” was set from the fertilizer treatment activity.

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.9.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.9.5. Example Response

{
    "activities":{
        "fertilizer_treatment":{
            "2016-05-20":[{
                "field_activity_id":"123-def",
                "depth_unit":"m",
                "rate":0,
                "fertilizer_id":"25",
                "confirmed":false,
                "created":1494522940,
                "modified":"n/a",
                "rate_unit":"gal/ac",
                "subtype":0,
                "depth":0.07619999999999999,
                "activity_type":308,
                "recommendation":true
            }]
        },
    "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":".../Figure_16_ISUE300.jpg"
                },...
            ],
            "name":"V3 - 3 Leaves",
            "order":"3"
        },...
    }
}

1.10. 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.10.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.10.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.10.3. Response Object

A string representing a feedback ID.

1.10.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.10.5. Example Response

def-345

1.11. Corn Growth Feedbacks by Growth - v1.0

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

1.11.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.11.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

1.11.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.11.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.11.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.12. 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.12.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.12.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.12.3. Response Object

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

1.12.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.12.5. Example Response

true

1.13. 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.13.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.13.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.13.3. Response Object

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

1.13.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.13.5. Example Response

true

2. Spring Wheat

2.1. Spring Wheat Growth Creation - v1.0

This endpoint allows users to create a spring wheat growth on an existing field. The given user adding the spring wheat growth must have write privileges for the field being updated.

2.1.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/springwheat/growth/create/{field_id}?
account_id={string}&user_id={string}&plant_date={timestamp}
&relative_maturity={string}&min_soil_moisture_allowed={float}
&max_soil_moisture_allowed={float}

2.1.2. Request Parameters

Parameter Type Required Description

account_id

string

yes

Your Accounts API account ID.

field_id

string

yes

Specifies ID of field to be updated.

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.

plant_date, emergence_date

timestamp

yes

Epoch timestamp valid near the time that the crop reached emergence2.

relative_maturity

string

no

Gauges how long it takes for the crop to mature. Valid values include “early,” “medium-early,” “medium,” “medium-late,” or “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. If no value is given, a default relative maturity of “medium” will be used.

min_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level. Values must be greater than 0.0 and less than 100.0

max_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level. Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0

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

2.1.3. Response Object

A string representing a growth ID.

2.1.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/springwheat/growth/create/abc-123?
account_id=123&user_id=xyz-123&app_id=456&app_key=789&plant_date=1393632000
&relative_maturity=early

2.1.5. Example Response

abc-def

2.2. Spring Wheat Get Growth - v1.0

This endpoint allows a user to receive a previously created growth based on growth ID.

2.2.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/springwheat/growth/get/{growth_id}?
plant={string}&account_id={string}&user_id={string}

2.2.2. Request Parameters

Parameter Type Required Description

plant

string

yes

Name of plant (i.e. corn or winter_wheat).

growth_id

string

yes

Specifies ID of crop growth to be queried from the user information database, provided by the Create Growth endpoint.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

2.2.3. Response Object (JSON)

Field Description

acres

Areal size of the field in acres.

created

Epoch timestamp in seconds.2

field_id

Specifies ID of field to which crop growth data has been assigned.

field_name

Name of the field.

growth_id

Specifies ID of crop growth queried.

harvest_date

An epoch timestamp in seconds for which harvest has begun.2

irrigation_type

Represents whether or not the cropland utilizes pivot irrigation. Valid values: 0 is “false” and 1 is “true.”

latitude

Latitude coordinate near the center of the field in decimal degrees.

longitude

Longitude coordinate near the center of the field in decimal degrees.

min_soil_moisture_allowed

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level Values must be greater than 0.0 and less than 100.0.

max_soil_moisture_allowed

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level. Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0

name

Name of the growth.

plant_date

Approximate time at which the crop was planted.

plant_name

Name of the crop plant.

plant_type

Coded value representing the type of crop planted. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

plant_subtype

Coded value representing the specific variety of crop planted.

plant_type

Enumeration value representing plant sub-type.

relative_maturity

Classification indicating how early a variety matures. Depending on the crop, valid values may include “early,” “medium-early,” “medium,” “medium-late,” or “late,” — where crops having an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

seed_variety

Additional description or notes for the seed used.

subdrainage_type

Represents whether or not the cropland utilizes drainage tile. Valid values: 0 is “false” (default) and 1 is “true.”

surface_drainage_quality

Represents field drainage effectiveness. Valid values: 0 is poor, 1 is average, and 2 is good.

previous_crop

Type ID of previously planted crop.

previous_harvest_date

Epoch time which previous crop was harvested.2

previous_yield

Yield of previous crop.

previous_yield_unit

Unit of measure for previous yield.

yield_goal

Yield target of current growth.

yield_goal_unit

Unit of measure for yield goal.

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

2.2.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/springwheat/growth/get/bcd-def?
&account_id=123&user_id=xyz-123

2.2.5. Example Response

{
    "acres":160.0,
    "created":1496777599,
    "field_id":"abc-def",
    "field_name":"MyField",
    "growth_id":"bcd-def",
    "harvest_date":null,
    "irrigation_type":0,
    "latitude":47.92338180541992,
    "longitude":-97.0919189453125,
    "min_soil_moisture_allowed":12.32,
    "max_soil_moisture_allowed":24.48,
    "name":"MyGrowth",
    "plant_date":1398920400,
    "plant_name":"spring wheat",
    "plant_subtype":0,
    "plant_type":57,
    "relative_maturity":"",
    "seed_variety":null,
    "subdrainage_type":0,
    "surface_drainage_quality":1
}

2.3. Spring Wheat Growth Modify - v1.0

This endpoint allows a user to modify an existing spring wheat growth.

2.3.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/springwheat/growth/modify/{growth_id}?
account_id={string}&user_id={string}&plant_date={timestamp}&relative_maturity={string}
&min_soil_moisture_allowed={float}&max_soil_moisture_allowed={float}

2.3.2. Request Parameters

Parameter Type Required Description

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.

plant_date, emergence_date

timestamp

yes

Epoch timestamp valid near the time that the crop reached emergence2.

growth_id

string

yes

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

relative_maturity

string

no

Gauges how long it takes for the crop to mature. Valid values include “early,” “medium-early,” “medium,” “medium-late,” or “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. If no value is given, a default relative maturity of “medium” will be used.

min_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level. Values must be greater than 0.0 and less than 100.0

max_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level. Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0

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

2.3.3. Response Object

Returns “true” on success.

2.3.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/springwheat/growth/modify/abc-123?
account_id=123&user_id=xyz-123&relative_maturity=medium

2.3.5. Example Response

true

Please note that valid stage values for spring wheat feedback are listed in the Stage Enumeration column.

Stage Enumeration Stage Name Stage Equivalent Feekes Stage Equivalent Haun Stage Equivalent Zadoks

101

Emergence

1

0.5

10

102

1 Leaf

1.1

1.0

11

103

2 Leaves

1.2

2.0

12

104

3 Leaves

2

3.0

13

105

4 Leaves

None

4.0

14

106

5 Leaves

4-5

5.0

30

107

6th Leaf Emerged

6

None

31

108

6 Leaves

None

6.0

None

109

7th Leaf Emerged

7

32

110

7 Leaves

None

7.0

None

111

Flag Leaf Emerging

8

7.5

37

112

Flag Leaf Emerged

9

8.0

39

113

Boot Swelling Begins

None

9.0

43

114

Boot Swollen

10

10.0

45

115

Awns Emerging

None

10.1

49

116

Head Emerged

10.5

11.0

59

117

Flowering Begins

10.51

11.4

61

118

Flowering Complete

10.53

11.6

69

119

Kernel Water Ripe

10.54

12.1

71

120

Hard Dough

None

15.0

87

121

Physiological Maturity

11.3

15.6

92

2.4. Spring Wheat Growth Delete - v1.0

This endpoint allows a user to delete a spring wheat growth. By deleting a growth, any applicable growth feedback and growth whitelist items will also be deleted.

2.4.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/springwheat/growth/delete/{growth_id}?
account_id={string}&user_id={string}

2.4.2. Request Parameters

Parameter Type Required Description

growth_id

string

yes

The ID of the target growth to delete.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

sring

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

2.4.3. Response Object

Returns “true” on success.

2.4.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/springwheat/growth/delete/abc-def?
account_id=123&user_id=xyz-123

2.4.5. Example Response

true

2.5. 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.5.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.5.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.5.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.5.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.5.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.6. 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.6.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.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.

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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.6.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.6.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.6.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.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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":".../Coleoptile.jpg"
                },...
            ],
            "name":"Emergence",
            "order":"1"
        },...
    }
}

2.8. 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.8.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.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.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.

2.8.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.8.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"
            },...
        }
    }
}

2.9. 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.9.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}
&use_unconfirmed={flag}
&relative_maturity={string}

2.9.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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 emergence.2

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 harvested.2 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.

use_unconfirmed

flag

no

yes

When included in the query string, the nitrogen model will use all fertilizer treatment activities with confirmed value of “true” and “false.” If there exists a fertilizer treatment activity with a “rate” value of “null,” the nitrogen model will provide a rate recommendation.

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

fertilizer_treatment

Structure holding all fertilizer treatment data utilized by the nitrogen model, including the fertilizer type, application rate, and depth. Each fertilizer treatment activity will have an addition property of “recommendation,” which is “true” if the “rate” is a recommendation calculated by the nitrogen model or “false” if the “rate” was set from the fertilizer treatment activity.

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.9.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.9.5. Example Response

{
    "activities":{
        "fertilizer_treatment":{
            "2016-05-20":[{
                "field_activity_id":"123-def",
                "depth_unit":"m",
                "rate":0,
                "fertilizer_id":"25",
                "confirmed":false,
                "created":1494522940,
                "modified":"n/a",
                "rate_unit":"gal/ac",
                "subtype":0,
                "depth":0.07619999999999999,
                "activity_type":308,
                "recommendation":true
            }]
        },
    "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":".../Coleoptile.jpg"
                }
            ],
            "name":"Emergence",
            "order":"1"
        },...
    }
}

2.10. 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.10.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.10.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.10.3. Response Object

A string representing a feedback ID.

2.10.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.10.5. Example Response

def-345

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

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

2.11.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.11.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

2.11.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.11.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.11.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.12. 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.12.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.12.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.12.3. Response Object

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

2.12.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.12.5. Example Response

true

2.13. 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.13.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.13.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.13.3. Response Object

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

2.13.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.13.5. Example Response

true

3. Winter Wheat

3.1. Winter Wheat Growth Creation - v1.0

This endpoint allows users to create a winter wheat growth on an existing field. The given user adding the winter wheat growth must have write privileges for the field being updated.

3.1.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/winter_wheat/growth/create/{field_id}?
account_id={string}&user_id={string}&plant_date={timestamp}
&relative_maturity={string}&plant_depth={float}
&min_soil_moisture_allowed={float}&max_soil_moisture_allowed={float}

3.1.2. Request Parameters

Parameter Type Required Description

account_id

string

yes

Your Accounts API account ID.

field_id

string

yes

Specifies ID of field to be updated.

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.

plant_date, emergence_date

timestamp

yes

Epoch timestamp valid near the time that the crop reached emergence2.

relative_maturity

string

no

Gauges how long it takes for the crop to mature. Valid values include “early,” “medium,” 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. If no value is given, a default relative maturity of “medium” will be used.

plant_depth

float

no

The depth in centimeters that the crop was planted. Plant depth must be a float between 0.1 and 10.0 cm. If no value is provided, the default plant depth is 5.

min_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level. Values must be greater than 0.0 and less than 100.0

max_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level. Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0

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

3.1.3. Response Object

A string representing a growth ID.

3.1.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/winter_wheat/create/abc-123?
account_id=123&user_id=xyz-123&app_id=456&app_key=789
&plant_date=1393632000&relative_maturity=early&plant_depth=4.0

3.1.5. Example Response

abc-def

3.2. Winter Wheat Get Growth - v1.0

This endpoint allows a user to receive a previously created growth based on growth ID.

3.2.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/winter_wheat/growth/get/{growth_id}?
plant={string}&account_id={string}&user_id={string}

3.2.2. Request Parameters

Parameter Type Required Description

plant

string

yes

Name of plant (i.e. corn or winter_wheat).

growth_id

string

yes

Specifies ID of crop growth to be queried from the user information database, provided by the Create Growth endpoint.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

3.2.3. Response Object (JSON)

Field Description

acres

Areal size of the field in acres.

created

Epoch timestamp in seconds.2

field_id

Specifies ID of field to which crop growth data has been assigned.

field_name

Name of the field.

growth_id

Specifies ID of crop growth queried.

harvest_date

An epoch timestamp in seconds for which harvest has begun.2

irrigation_type

Represents whether or not the cropland utilizes pivot irrigation. Valid values: 0 is “false” and 1 is “true.”

latitude

Latitude coordinate near the center of the field in decimal degrees.

longitude

Longitude coordinate near the center of the field in decimal degrees.

min_soil_moisture_allowed

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level Values must be greater than 0.0 and less than 100.0.

max_soil_moisture_allowed

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level. Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0

name

Name of the growth.

plant_date

Approximate time at which the crop was planted.

plant_name

Name of the crop plant.

plant_type

Coded value representing the type of crop planted. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

plant_subtype

Coded value representing the specific variety of crop planted.

plant_type

Enumeration value representing plant sub-type.

relative_maturity

Classification indicating how early a variety matures. Depending on the crop, valid values may include “early,” “medium-early,” “medium,” “medium-late,” or “late,” — where crops having an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

seed_variety

Additional description or notes for the seed used.

subdrainage_type

Represents whether or not the cropland utilizes drainage tile. Valid values: 0 is “false” (default) and 1 is “true.”

surface_drainage_quality

Represents field drainage effectiveness. Valid values: 0 is poor, 1 is average, and 2 is good.

previous_crop

Type ID of previously planted crop.

previous_harvest_date

Epoch time which previous crop was harvested.2

previous_yield

Yield of previous crop.

previous_yield_unit

Unit of measure for previous yield.

yield_goal

Yield target of current growth.

yield_goal_unit

Unit of measure for yield goal.

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

3.2.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/winter_wheat/growth/get/bcd-def?
&growth_id=abc-feg&account_id=123&user_id=xyz-123

3.2.5. Example Response

{
    "acres":160.0,
    "created":1496777689,
    "field_id":"abc-def",
    "field_name":"MyField",
    "growth_id":"bcd-def",
    "harvest_date":null,
    "irrigation_type":0,
    "latitude":47.92338180541992,
    "longitude":-97.0919189453125,
    "min_soil_moisture_allowed":12.32,
    "max_soil_moisture_allowed":24.48,
    "name":"MyGrowth",
    "plant_date":1410757200,
    "plant_name":"winter wheat",
    "plant_subtype":0,
    "plant_type":68,
    "relative_maturity":"",
    "seed_variety":null,
    "subdrainage_type":0,
    "surface_drainage_quality":1
}

3.3. Winter Wheat Growth Modify - v1.0

This endpoint allows a user to modify an existing winter wheat growth.

3.3.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/winter_wheat/modify/{growth_id}?
account_id={string}&user_id={string}&plant_date={timestamp}
&relative_maturity={string}&plant_depth={float}
&min_soil_moisture_allowed={float}&max_soil_moisture_allowed={float}

3.3.2. Request Parameters

Parameter Type Required Description

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.

plant_date, emergence_date

timestamp

yes

Epoch timestamp valid near the time that the crop reached emergence2.

growth_id

string

yes

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

relative_maturity

string

no

Gauges how long it takes for the crop to mature. Valid values include “early,” “medium,” 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. If no value is given, a default relative maturity of “medium” will be used.

plant_depth

float

no

The depth in centimeters that the crop was planted. Plant depth must be a float between 0.1 and 10.0 cm. If no value is provided, the default plant depth is 5.

min_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level. Values must be greater than 0.0 and less than 100.0

max_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0.

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

3.3.3. Response Object

Returns “true” on success.

3.3.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/winter_wheat/modify/abc-123?
account_id=123&user_id=xyz-123&plant_date=1456890400
&relative_maturity=medium&plant_depth=5

3.3.5. Example Response

true

3.4. Winter Wheat Growth Delete - v1.0

This endpoint allows a user to delete a winter wheat growth. By deleting a growth, any applicable growth feedback and growth whitelist items will also be deleted.

3.4.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/winterwheat/growth/delete/{growth_id}?
account_id={string}&user_id={string}

3.4.2. Request Parameters

Parameter Type Required Description

growth_id

string

yes

The ID of the target growth to delete.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

sring

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

3.4.3. Response Object

Returns “true” on success.

3.4.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/winterwheat/growth/delete/abc-def?
account_id=123&user_id=xyz-123

3.4.5. Example Response

true

3.5. 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.5.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.5.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.5.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.5.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.5.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.6. 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.6.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.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.

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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.6.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.6.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.6.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.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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 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.8.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.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.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.

3.8.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.8.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"
            },...
        }
    }
}

3.9. 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.9.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}
&use_unconfirmed={flag}
&relative_maturity={string}&plant_depth={float}

3.9.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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 emergence.2

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 harvested.2 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.

use_unconfirmed

flag

no

yes

When included in the query string, the nitrogen model will use all fertilizer treatment activities with confirmed value of “true” and “false.” If there exists a fertilizer treatment activity with a “rate” value of “null,” the nitrogen model will provide a rate recommendation.

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

fertilizer_treatment

Structure holding all fertilizer treatment data utilized by the nitrogen model, including the fertilizer type, application rate, and depth. Each fertilizer treatment activity will have an addition property of “recommendation,” which is “true” if the “rate” is a recommendation calculated by the nitrogen model or “false” if the “rate” was set from the fertilizer treatment activity.

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.9.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.9.5. Example Response

{
    "activities":{
        "fertilizer_treatment":{
            "2016-05-20":[{
                "field_activity_id":"123-def",
                "depth_unit":"m",
                "rate":0,
                "fertilizer_id":"25",
                "confirmed":false,
                "created":1494522940,
                "modified":"n/a",
                "rate_unit":"gal/ac",
                "subtype":0,
                "depth":0.07619999999999999,
                "activity_type":308,
                "recommendation":true
            }]
        },
    "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":".../Zadoks+21.jpg"
                },...
            ],
            "name":"First Tiller",
            "order":"3"
        },...
    }
}

3.10. 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.10.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.10.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.10.3. Response Object

A string representing a feedback ID.

3.10.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.10.5. Example Response

def-345

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

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

3.11.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.11.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

3.11.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.11.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.11.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.12. 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.12.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.12.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.12.3. Response Object

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

3.12.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.12.5. Example Response

true

3.13. 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.13.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.13.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.13.3. Response Object

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

3.13.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.13.5. Example Response

true

4. Canola

4.1. Canola Growth Creation - v1.0

This endpoint allows users to create a canola growth on an existing field. The given user adding the canola growth must have write privileges for the field being updated.

4.1.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/canola/growth/create/{field_id}?
account_id={string}&user_id={string}&plant_date={timestamp}
&maturity_group={string}&min_soil_moisture_allowed={float}
&max_soil_moisture_allowed={float}

4.1.2. Request Parameters

Parameter Type Required Description

account_id

string

yes

Your Accounts API account ID.

field_id

string

yes

Specifies ID of field to be updated.

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.

plant_date, emergence_date

timestamp

yes

Epoch timestamp valid near the time that the crop reached emergence between 0.1 and 10.0 cm2. If no value is provided, the default plant depth is 5.

maturity_group, relative_maturity

string

no

Classification indicating how early a variety matures. Values include early, medium-early, medium, medium-late, and late. Please note that if maturity group is specified, it will be stored as relative maturity.

min_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level. Values must be greater than 0.0 and less than 100.0

max_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level. Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0

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

4.1.3. Response Object

A string representing a growth ID.

4.1.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/canola/growth/create/abc-123?
account_id=123&user_id=xyz-123&app_id=456&app_key=789&plant_date=1393632000

4.1.5. Example Response

abc-def

4.2. Canola Get Growth - v1.0

This endpoint allows a user to receive a previously created growth based on growth ID.

4.2.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/canola/growth/get/{growth_id}?
plant={string}&account_id={string}&user_id={string}

4.2.2. Request Parameters

Parameter Type Required Description

plant

string

yes

Name of plant (i.e. corn or winter_wheat).

growth_id

string

yes

Specifies ID of crop growth to be queried from the user information database, provided by the Create Growth endpoint.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

4.2.3. Response Object (JSON)

Field Description

acres

Areal size of the field in acres.

created

Epoch timestamp in seconds.2

field_id

Specifies ID of field to which crop growth data has been assigned.

field_name

Name of the field.

growth_id

Specifies ID of crop growth queried.

harvest_date

An epoch timestamp in seconds for which harvest has begun.2

irrigation_type

Represents whether or not the cropland utilizes pivot irrigation. Valid values: 0 is “false” and 1 is “true.”

latitude

Latitude coordinate near the center of the field in decimal degrees.

longitude

Longitude coordinate near the center of the field in decimal degrees.

min_soil_moisture_allowed

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level Values must be greater than 0.0 and less than 100.0.

max_soil_moisture_allowed

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level. Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0

name

Name of the growth.

plant_date

Approximate time at which the crop was planted.

plant_name

Name of the crop plant.

plant_type

Coded value representing the type of crop planted. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

plant_subtype

Coded value representing the specific variety of crop planted.

plant_type

Enumeration value representing plant sub-type.

relative_maturity

Classification indicating how early a variety matures. Depending on the crop, valid values may include “early,” “medium-early,” “medium,” “medium-late,” or “late,” — where crops having an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

seed_variety

Additional description or notes for the seed used.

subdrainage_type

Represents whether or not the cropland utilizes drainage tile. Valid values: 0 is “false” (default) and 1 is “true.”

surface_drainage_quality

Represents field drainage effectiveness. Valid values: 0 is poor, 1 is average, and 2 is good.

previous_crop

Type ID of previously planted crop.

previous_harvest_date

Epoch time which previous crop was harvested.2

previous_yield

Yield of previous crop.

previous_yield_unit

Unit of measure for previous yield.

yield_goal

Yield target of current growth.

yield_goal_unit

Unit of measure for yield goal.

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

4.2.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/canola/growth/get/bcd-def?
&account_id=123&user_id=xyz-123

4.2.5. Example Response

{
    "acres":160.0,
    "created":1496777557,
    "field_id":"abc-def",
    "field_name":"MyField",
    "growth_id":"bcd-def",
    "harvest_date":null,
    "irrigation_type":0,
    "latitude":47.92338180541992,
    "longitude":-97.0919189453125,
    "min_soil_moisture_allowed":12.32,
    "max_soil_moisture_allowed":24.48,
    "name":"MyGrowth",
    "plant_date":1398920400,
    "plant_name":"canola",
    "plant_subtype":0,
    "plant_type":59,
    "seed_variety":null,
    "subdrainage_type":0,
    "surface_drainage_quality":1
}

4.3. Canola Growth Modify - v1.0

This endpoint allows a user to modify an existing canola growth.

4.3.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/canola/growth/modify/{growth_id}?
account_id={string}&user_id={string}&plant_date={timestamp}
&min_soil_moisture_allowed={float}&max_soil_moisture_allowed={float}

4.3.2. Request Parameters

Parameter Type Required Description

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.

plant_date, emergence_date

timestamp

yes

Epoch timestamp valid near the time that the crop reached emergence2.

growth_id

string

yes

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

min_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level. Values must be greater than 0.0 and less than 100.0

max_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0.

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

4.3.3. Response Object

Returns “true” on success.

4.3.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/canola/growth/modify/abc-123?
account_id=123&user_id=xyz-123&plant_date=1456890400

4.3.5. Example Response

true

4.4. Canola Growth Delete - v1.0

This endpoint allows a user to delete a canola growth. By deleting a growth, any applicable growth feedback and growth whitelist items will also be deleted.

4.4.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/canola/growth/delete/{growth_id}?
account_id={string}&user_id={string}

4.4.2. Request Parameters

Parameter Type Required Description

growth_id

string

yes

The ID of the target growth to delete.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

sring

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

4.4.3. Response Object

Returns “true” on success.

4.4.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/canola/growth/delete/abc-def?
account_id=123&user_id=xyz-123

4.4.5. Example Response

true

4.5. 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.5.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.5.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.5.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.5.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.5.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.6. 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.6.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.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.

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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.6.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.6.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.6.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":".../2leaf_150.jpg"
                },...
            ],
            "name":"Rosette - 3rd Leaf",
            "order":"2"
        },...
    }
}

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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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":".../cotyledon_150.jpg"
                },...
            ],
            "name":"Emergence",
            "order":"1"
        },...
    }
}

4.8. 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.8.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.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.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.

4.8.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.8.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"
            },...
        }
    }
}

4.9. 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.9.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}
&use_unconfirmed={flag}
&relative_maturity={string}

4.9.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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 emergence.2

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 harvested.2 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.

use_unconfirmed

flag

no

yes

When included in the query string, the nitrogen model will use all fertilizer treatment activities with confirmed value of “true” and “false.” If there exists a fertilizer treatment activity with a “rate” value of “null,” the nitrogen model will provide a rate recommendation.

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

fertilizer_treatment

Structure holding all fertilizer treatment data utilized by the nitrogen model, including the fertilizer type, application rate, and depth. Each fertilizer treatment activity will have an addition property of “recommendation,” which is “true” if the “rate” is a recommendation calculated by the nitrogen model or “false” if the “rate” was set from the fertilizer treatment activity.

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.9.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.9.5. Example Response

{
    "activities":{
        "fertilizer_treatment":{
            "2016-05-20":[{
                "field_activity_id":"123-def",
                "depth_unit":"m",
                "rate":0,
                "fertilizer_id":"25",
                "confirmed":false,
                "created":1494522940,
                "modified":"n/a",
                "rate_unit":"gal/ac",
                "subtype":0,
                "depth":0.07619999999999999,
                "activity_type":308,
                "recommendation":true
            }]
        },
    "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":".../ripening4.png"
                },...
            ],
            "name":"Ripe",
            "order":"9"
        }
    }
}

4.10. 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.10.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.10.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.10.3. Response Object

A string representing a feedback ID.

4.10.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.10.5. Example Response

def-345

4.11. 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.11.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.11.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.11.3. Response Object

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

4.11.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.11.5. Example Response

true

4.12. Canola Growth Feedbacks by Growth - v1.1

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

4.12.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.12.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

4.12.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.12.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.12.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.13. 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.13.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.13.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.13.3. Response Object

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

4.13.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.13.5. Example Response

true

5. Sugar Beet

5.1. Sugar Beet Growth Creation - v1.0

This endpoint allows users to create a sugar beet growth on an existing field. The given user adding the sugar beet growth must have write privileges for the field being updated.

5.1.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/sugarbeet/growth/create/{field_id}?
account_id={string}&user_id={string}&plant_date={timestamp}

5.1.2. Request Parameters

Parameter Type Required Description

account_id

string

yes

Your Accounts API account ID.

field_id

string

yes

Specifies ID of field to be updated.

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.

plant_date, emergence_date

timestamp

yes

Epoch timestamp valid near the time that the crop reached emergence.

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

5.1.3. Response Object

A string representing a growth ID.

5.1.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/sugarbeet/growth/create/abc-123?
account_id=123&user_id=xyz-123&app_id=456&app_key=789&plant_date=1393632000

5.1.5. Example Response

abc-def

5.2. Sugar Beet Get Growth - v1.0

This endpoint allows a user to receive a previously created growth based on growth ID.

5.2.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/sugarbeet/growth/get/{growth_id}?
plant={string}&account_id={string}&user_id={string}

5.2.2. Request Parameters

Parameter Type Required Description

plant

string

yes

Name of plant (i.e. corn or winter_wheat).

growth_id

string

yes

Specifies ID of crop growth to be queried from the user information database, provided by the Create Growth endpoint.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

5.2.3. Response Object (JSON)

Field Description

acres

Areal size of the field in acres.

created

Epoch timestamp in seconds.2

field_id

Specifies ID of field to which crop growth data has been assigned.

field_name

Name of the field.

growth_id

Specifies ID of crop growth queried.

harvest_date

An epoch timestamp in seconds for which harvest has begun.2

irrigation_type

Represents whether or not the cropland utilizes pivot irrigation. Valid values: 0 is “false” and 1 is “true.”

latitude

Latitude coordinate near the center of the field in decimal degrees.

longitude

Longitude coordinate near the center of the field in decimal degrees.

name

Name of the growth.

plant_date

Approximate time at which the crop was planted.

plant_name

Name of the crop plant.

plant_type

Coded value representing the type of crop planted. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

plant_subtype

Coded value representing the specific variety of crop planted.

plant_type

Enumeration value representing plant sub-type.

relative_maturity

Classification indicating how early a variety matures. Depending on the crop, valid values may include “early,” “medium-early,” “medium,” “medium-late,” or “late,” — where crops having an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

seed_variety

Additional description or notes for the seed used.

subdrainage_type

Represents whether or not the cropland utilizes drainage tile. Valid values: 0 is “false” (default) and 1 is “true.”

surface_drainage_quality

Represents field drainage effectiveness. Valid values: 0 is poor, 1 is average, and 2 is good.

previous_crop

Type ID of previously planted crop.

previous_harvest_date

Epoch time which previous crop was harvested.2

previous_yield

Yield of previous crop.

previous_yield_unit

Unit of measure for previous yield.

yield_goal

Yield target of current growth.

yield_goal_unit

Unit of measure for yield goal.

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

5.2.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/sugarbeet/growth/get/bcd-def?
&account_id=123&user_id=xyz-123

5.2.5. Example Response

{
    "acres":160.0,
    "created":1496777647,
    "field_id":"abc-def",
    "field_name":"MyField",
    "growth_id":"bcd-def",
    "harvest_date":null,
    "irrigation_type":0,
    "latitude":47.92338180541992,
    "longitude":-97.0919189453125,
    "name":"MyGrowth",
    "plant_date":1398920400,
    "plant_name":"sugarbeet",
    "plant_subtype":0,
    "plant_type":60,
    "seed_variety":null,
    "subdrainage_type":0,
    "surface_drainage_quality":1
}

5.3. Sugar Beet Growth Modify - v1.0

This endpoint allows a user to modify an existing sugar beet growth.

5.3.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/sugarbeet/growth/modify/{growth_id}?
account_id={string}&user_id={string}&plant_date={timestamp}

5.3.2. Request Parameters

Parameter Type Required Description

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.

plant_date, emergence_date

timestamp

yes

Epoch timestamp valid near the time that the crop reached emergence2.

growth_id

string

yes

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

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

5.3.3. Response Object

Returns “true” on success.

5.3.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/sugarbeet/growth/modify/abc-123?
account_id=123&user_id=xyz-123&plant_date=1456890400

5.3.5. Example Response

true

5.4. Sugar Beet Growth Delete - v1.0

The endpoint allows a user to delete a sugar beet growth. By deleting a growth, any applicable growth feedback and growth whitelist items will also be deleted.

5.4.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/sugarbeet/growth/delete/{growth_id}?
account_id={string}&user_id={string}

5.4.2. Request Parameters

Parameter Type Required Description

growth_id

string

yes

The ID of the target growth to delete.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

sring

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

5.4.3. Response Object

Returns “true” on success.

5.4.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/sugarbeet/growth/delete/abc-def?
account_id=123&user_id=xyz-123

5.4.5. Example Response

true

5.5. 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.5.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.5.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.5.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.5.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.5.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.6. 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.6.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.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.

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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.6.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.6.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.6.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.7. 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.7.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.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

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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.7.3. Response Object

A string representing a feedback ID.

5.7.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.7.5. Example Response

def-345

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

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

5.8.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.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

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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

5.8.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.8.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.8.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.9. 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.9.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.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

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.9.3. Response Object

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

5.9.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.9.5. Example Response

true

5.10. 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.10.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.10.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.10.3. Response Object

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

5.10.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.10.5. Example Response

true

6. Barley

6.1. Barley Growth Creation - v1.0

This endpoint allows users to create a barley growth on an existing field. The given user adding the barley growth must have write privileges for the field being updated.

6.1.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/barley/growth/create/{field_id}?
account_id={string}&user_id={string}&plant_date={timestamp}
&maturity_group={string}

6.1.2. Request Parameters

Parameter Type Required Description

account_id

string

yes

Your Accounts API account ID.

field_id

string

yes

Specifies ID of field to be updated.

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.

plant_date, emergence_date

timestamp

yes

Epoch timestamp valid near the time that the crop reached emergence2.

maturity_group, relative_maturity

string

no

Classification indicating how early a variety matures. Values include early, medium-early, medium, medium-late, and late. Please note that if maturity group is specified, it will be stored as relative maturity.

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

6.1.3. Response Object

A string representing a growth ID.

6.1.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/barley/growth/create/abc-123?
account_id=123&user_id=xyz-123&app_id=456&app_key=789&plant_date=1393632000

6.1.5. Example Response

abc-def

6.2. Barley Get Growth - v1.0

This endpoint allows a user to receive a previously created growth based on growth ID.

6.2.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/barley/growth/get/{growth_id}?
plant={string}&account_id={string}&user_id={string}

6.2.2. Request Parameters

Parameter Type Required Description

plant

string

yes

Name of plant (i.e. corn or winter_wheat).

growth_id

string

yes

Specifies ID of crop growth to be queried from the user information database, provided by the Create Growth endpoint.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

6.2.3. Response Object (JSON)

Field Description

acres

Areal size of the field in acres.

created

Epoch timestamp in seconds.2

field_id

Specifies ID of field to which crop growth data has been assigned.

field_name

Name of the field.

growth_id

Specifies ID of crop growth queried.

harvest_date

An epoch timestamp in seconds for which harvest has begun.2

irrigation_type

Represents whether or not the cropland utilizes pivot irrigation. Valid values: 0 is “false” and 1 is “true.”

latitude

Latitude coordinate near the center of the field in decimal degrees.

longitude

Longitude coordinate near the center of the field in decimal degrees.

name

Name of the growth.

plant_date

Approximate time at which the crop was planted.

plant_name

Name of the crop plant.

plant_type

Coded value representing the type of crop planted. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

plant_subtype

Coded value representing the specific variety of crop planted.

plant_type

Enumeration value representing plant sub-type.

relative_maturity

Classification indicating how early a variety matures. Depending on the crop, valid values may include “early,” “medium-early,” “medium,” “medium-late,” or “late,” — where crops having an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

seed_variety

Additional description or notes for the seed used.

subdrainage_type

Represents whether or not the cropland utilizes drainage tile. Valid values: 0 is “false” (default) and 1 is “true.”

surface_drainage_quality

Represents field drainage effectiveness. Valid values: 0 is poor, 1 is average, and 2 is good.

previous_crop

Type ID of previously planted crop.

previous_harvest_date

Epoch time which previous crop was harvested.2

previous_yield

Yield of previous crop.

previous_yield_unit

Unit of measure for previous yield.

yield_goal

Yield target of current growth.

yield_goal_unit

Unit of measure for yield goal.

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

6.2.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/barley/growth/get/bcd-def?
&account_id=123&user_id=xyz-123

6.2.5. Example Response

{
    "acres":1234.0,
    "created":1445972460,
    "emergence_date":null,
    "field_id":"abc-def",
    "field_name":"MyField",
    "growth_id":"bcd-def",
    "harvest_date":null,
    "irrigation_type":1,
    "latitude":47.92338180541992,
    "longitude":-97.0919189453125,
    "name":"MyGrowth",
    "plant_date":1398920400,
    "plant_name":"barley",
    "plant_subtype":0,
    "plant_type":50,
    "seed_variety":null,
    "subdrainage_type":1,
    "surface_drainage_quality":1,
    "version":"v1.1"
}

6.3. Barley Growth Modify - v1.0

This endpoint allows a user to modify an existing barley growth.

6.3.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/barley/growth/modify/{growth_id}?
account_id={string}&user_id={string}&plant_date={timestamp}

6.3.2. Request Parameters

Parameter Type Required Description

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.

plant_date, emergence_date

timestamp

yes

Epoch timestamp valid near the time that the crop reached emergence2.

growth_id

string

yes

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

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

6.3.3. Response Object

Returns “true” on success.

6.3.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/barley/growth/modify/abc-123?
account_id=123&user_id=xyz-123&plant_date=1456890400

6.3.5. Example Response

true

6.4. Barley Growth Delete - v1.0

This endpoint allows a user to delete a barley growth. By deleting a growth, any applicable growth feedback and growth whitelist items will also be deleted.

6.4.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/barley/growth/delete/{growth_id}?
account_id={string}&user_id={string}

6.4.2. Request Parameters

Parameter Type Required Description

growth_id

string

yes

The ID of the target growth to delete.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

sring

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

6.4.3. Response Object

Returns “true” on success.

6.4.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/barley/growth/delete/abc-def?
account_id=123&user_id=xyz-123

6.4.5. Example Response

true

6.5. 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.5.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.5.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.5.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.5.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.5.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.6. 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.6.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.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.

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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.6.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.6.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.6.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.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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":".../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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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
            },...
        }
    }
}

6.9. 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.9.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.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

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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.9.3. Response Object

A string representing a feedback ID.

6.9.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.9.5. Example Response

def-345

6.10. Barley Growth Feedbacks by Growth - v1.0

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

6.10.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.10.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

6.10.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.10.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.10.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.11. 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.11.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.11.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.11.3. Response Object

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

6.11.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.11.5. Example Response

true

6.12. 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.12.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.12.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.12.3. Response Object

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

6.12.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.12.5. Example Response

true

7. Soybean

7.1. Soybean Growth Creation - v1.0

This endpoint allows users to create a soybean growth on an existing field. The given user adding the soybean growth must have write privileges for the field being updated.

7.1.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/soybean/growth/create/{field_id}?
account_id={string}&user_id={string}&plant_date={timestamp}
&maturity_group={string}&plant_depth={float}
&min_soil_moisture_allowed={float}&max_soil_moisture_allowed={float}

7.1.2. Request Parameters

Parameter Type Required Description

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.

field_id

string

yes

Specifies ID of field to be updated.

plant_date, emergence_date

timestamp

yes

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

maturity_group, relative_maturity

string

no

Classification indicating how early a variety matures. Valid values fall into the following range bins: 000.0 to 000.9, 00.0 to 00.9, and 0.0 to 10.9. Multi-zero range bins indicate the earliest maturities, with values near 10.9 indicating the latest maturities. Default is 3.0. Please note that if neither relative maturity nor maturity group are specified, the default value will be stored as relative maturity; if maturity group is specified, it will be stored as relative maturity.

plant_depth

float

no

The depth (in cm) that the crop was planted. Valid values range from 0.1 to 7.5 cm. Default is 3.5.

min_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level. Values must be greater than 0.0 and less than 100.0

max_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level. Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0

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

7.1.3. Response Object

A string representing a growth ID.

7.1.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/soybean/create/abc-123?
account_id=123&user_id=xyz-123&app_id=456&app_key=789
&plant_date=1393632000&maturity_group=4.0&plant_depth=4.0

7.1.5. Example Response

abc-def

7.2. Soybean Get Growth - v1.0

This endpoint allows a user to receive a previously created growth based on growth ID.

7.2.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/soybean/growth/get/{growth_id}?
plant={string}&account_id={string}&user_id={string}

7.2.2. Request Parameters

Parameter Type Required Description

plant

string

yes

Name of plant (i.e. corn or winter_wheat).

growth_id

string

yes

Specifies ID of crop growth to be queried from the user information database, provided by the Create Growth endpoint.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

7.2.3. Response Object (JSON)

Field Description

acres

Areal size of the field in acres.

created

Epoch timestamp in seconds.2

field_id

Specifies ID of field to which crop growth data has been assigned.

field_name

Name of the field.

growth_id

Specifies ID of crop growth queried.

harvest_date

An epoch timestamp in seconds for which harvest has begun.2

irrigation_type

Represents whether or not the cropland utilizes pivot irrigation. Valid values: 0 is “false” and 1 is “true.”

latitude

Latitude coordinate near the center of the field in decimal degrees.

longitude

Longitude coordinate near the center of the field in decimal degrees.

min_soil_moisture_allowed

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level Values must be greater than 0.0 and less than 100.0.

max_soil_moisture_allowed

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level. Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0

name

Name of the growth.

plant_date

Approximate time at which the crop was planted.

plant_name

Name of the crop plant.

plant_type

Coded value representing the type of crop planted. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

plant_subtype

Coded value representing the specific variety of crop planted.

plant_type

Enumeration value representing plant sub-type.

relative_maturity

Classification indicating how early a variety matures. Depending on the crop, valid values may include “early,” “medium-early,” “medium,” “medium-late,” or “late,” — where crops having an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

seed_variety

Additional description or notes for the seed used.

subdrainage_type

Represents whether or not the cropland utilizes drainage tile. Valid values: 0 is “false” (default) and 1 is “true.”

surface_drainage_quality

Represents field drainage effectiveness. Valid values: 0 is poor, 1 is average, and 2 is good.

previous_crop

Type ID of previously planted crop.

previous_harvest_date

Epoch time which previous crop was harvested.2

previous_yield

Yield of previous crop.

previous_yield_unit

Unit of measure for previous yield.

yield_goal

Yield target of current growth.

yield_goal_unit

Unit of measure for yield goal.

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

7.2.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/soybean/growth/get/bcd-def?
&account_id=123&user_id=xyz-123

7.2.5. Example Response

{
    "acres":160.0,
    "created":1496777654,
    "field_id":"abc-def",
    "field_name":"MyField",
    "growth_id":"bcd-def",
    "harvest_date":null,
    "irrigation_type":0,
    "latitude":47.92338180541992,
    "longitude":-97.0919189453125,
    "min_soil_moisture_allowed":12.32,
    "max_soil_moisture_allowed":24.48,
    "name":"MyGrowth",
    "plant_date":1398920400,
    "plant_name":"soybean",
    "plant_subtype":0,
    "plant_type":66,
    "relative_maturity":"000.6",
    "seed_variety":null,
    "subdrainage_type":0,
    "surface_drainage_quality":1
}

7.3. Soybean Growth Modify - v1.0

This endpoint allows a user to modify an existing soybean growth.

7.3.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/soybean/growth/modify/{growth_id}?
account_id={string}&user_id={string}&plant_date={timestamp}
&maturity_group={string}&plant_depth={float}
&min_soil_moisture_allowed={float}&max_soil_moisture_allowed={float}

7.3.2. Request Parameters

Parameter Type Required Description

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 the Soybean Growth Creation endpoint. This ID is given when a growth is successfully created on a field.

plant_date, emergence_date

timestamp

yes

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

maturity_group, relative_maturity

string

no

Classification indicating how early a variety matures. Valid values fall into the following range bins: 000.0 to 000.9, 00.0 to 00.9, and 0.0 to 10.9. Multi-zero range bins indicate the earliest maturities, with values near 10.9 indicating the latest maturities. Default is 3.0. Please note that if maturity group is specified, it will be stored as relative maturity.

plant_depth

float

no

The depth (in cm) that the crop was planted. Valid values range from 0.1 to 7.5 cm. Default is 3.5.

min_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level. Values must be greater than 0.0 and less than 100.0

max_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0.

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

7.3.3. Response Object

Returns “true” on success.

7.3.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/soybean/growth/modify/abc-123?
account_id=123&user_id=xyz-123&plant_date=1456890400&maturity_group=3.0
&plant_depth=3.5

7.3.5. Example Response

true

7.4. Soybean Growth Delete - v1.0

This endpoint allows a user to delete a soybean growth. By deleting a growth, any applicable growth feedback and growth whitelist items will also be deleted.

7.4.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/soybean/growth/delete/{growth_id}?
account_id={string}&user_id={string}

7.4.2. Request Parameters

Parameter Type Required Description

growth_id

string

yes

The ID of the target growth to delete.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

sring

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

7.4.3. Response Object

Returns “true” on success.

7.4.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/soybean/growth/delete/abc-def?
account_id=123&user_id=xyz-123

7.4.5. Example Response

true

7.5. Soybean Growth - v1.1

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.5.1. URL Description

http://ag.us.clearapis.com/v1.1/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={string}&plant_depth={float}

7.5.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

string

no

 — 

Classification indicating how early a variety matures. Valid values fall into the following range bins: 000.0 to 000.9, 00.0 to 00.9, and 0.0 to 10.9. Multi-zero range bins indicate the earliest maturities, with values near 10.9 indicating the latest maturities. Default is 3.0.

plant_depth

float

no

 — 

The depth (in cm) that the crop was planted. Valid values range from 0.1 to 7.5 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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.5.3. Response Object (JSON)

Field Description

attribution

Various model attributions.

agdd

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

air_temp_avg

Average daily air temperature in degrees Fahrenheit, which may be a historical, forecast, or climatological value, depending on the timeframe.

air_temp_max

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

air_temp_min

Minimum daily air temperature in degrees Fahrenheit, which may be a historical, forecast, or climatological value, 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_reproductive_stage

The last known reproductive stage. If no valid stage has been reached, this value will be “n/a.”

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, after which only new reproductive stages will be listed.

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 may have entered a new reproductive stage between the current date and the previous date. If new_reproductive_stage is “n/a,” 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 “n/a,” 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, after which 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 “n/a,” 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 a stage within the growth scale.

7.5.4. Example Request

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

7.5.5. Example Response

{
    "attribution":[
        "Growth model based on DSSAT / CROPGRO / Soybean."
    ],
    "data":{
        "47,-97":{
            "growth":{
                "2016-08-20":{
                    "agdd":1656.57,
                    "air_temp_avg":61.0,
                    "air_temp_max":69.0,
                    "air_temp_min":53.0,
                    "gdd":11.31,
                    "last_reproductive_stage":"R7",
                    "last_stage":"R7",
                    "last_vegetative_stage":"V10",
                    "new_reproductive_stage":"R8",
                    "new_stage":"R8",
                    "new_vegetative_stage":"n/a",
                    "relative_humidity_avg":72.0
                },...
            },
            "harvest_window":{
                "end":"2016-09-14",
                "start":"2016-08-20"
            }
        }
    },
    "stage_descriptions":{
        "R8":{
            "advisor":"Harvest",
            "description":"Plants have at least 95 percent of pods that are brown.",
            "images":[
                {
                    "attribution":"Courtesy of Agronomy Extension, Iowa State University.",
                    "caption":"R8 - Full maturity",
                    "url":".../R8.jpg"
                }
            ],
            "name":"R8 - Harvest Maturity",
            "order":"21"
        },...
    }
}

7.6. Soybean Growth with GDD Envelope - v1.1

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.6.1. URL Description

http://ag.us.clearapis.com/v1.1/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={string}&plant_depth={float}

7.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.

days

integer

yes

yes

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

maturity_group

string

no

 — 

Classification indicating how early a variety matures. Valid values fall into the following range bins: 000.0 to 000.9, 00.0 to 00.9, and 0.0 to 10.9. Multi-zero range bins indicate the earliest maturities, with values near 10.9 indicating the latest maturities. Default is 3.0.

plant_depth

float

no

 — 

The depth (in cm) that the crop was planted. Valid values range from 0.1 to 7.5 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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.6.3. Response Object (JSON)

Field Description

attribution

Various model attributions.

agdd

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

agdd_envelope_max

Maximum observed AGDD during the past 10 years.

agdd_envelope_max_year

Year that the maximum AGDD value was observed.

agdd_envelope_min

Minimum observed AGDD during the past 10 years.

agdd_envelope_min_year

Year that the minimum AGDD value was observed.

air_temp_avg

Average daily air temperature in degrees Fahrenheit, which may be a historical, forecast, or climatological value, depending on the timeframe.

air_temp_max

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

air_temp_min

Minimum daily air temperature in degrees Fahrenheit, which may be a historical, forecast, or climatological value, 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_reproductive_stage

The last known reproductive stage. If no valid stage has been reached, this value will be “n/a.”

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, after which only new reproductive stages will be listed.

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 may have entered a new reproductive stage between the current date and the previous date. If new_reproductive_stage is “n/a,” 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 “n/a,” 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, after which 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 “n/a,” 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 a stage within the growth scale.

7.6.4. Example Request

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

7.6.5. Example Response

{
    "attribution":[
        "Growth model based on DSSAT / CROPGRO / Soybean."
    ],
    "data":{
        "47,-97":{
            "growth":{
                "2016-08-20":{
                    "agdd":1656.57,
                    "agdd_envelope_max":1755.00,
                    "agdd_envelope_max_year":"2015",
                    "agdd_envelope_min":1601.25,
                    "agdd_envelope_min_year":"2010",
                    "air_temp_avg":61.0,
                    "air_temp_max":69.0,
                    "air_temp_min":53.0,
                    "gdd":11.31,
                    "last_reproductive_stage":"R7",
                    "last_stage":"R7",
                    "last_vegetative_stage":"V10",
                    "new_reproductive_stage":"R8",
                    "new_stage":"R8",
                    "new_vegetative_stage":"n/a",
                    "relative_humidity_avg":72.0
                },...
            },
            "harvest_window":{
                "end":"2016-09-14",
                "start":"2016-08-20"
            }
        }
    },
    "stage_descriptions":{
        "R8":{
            "advisor":"Harvest",
            "description":"Plants have at least 95 percent of pods that are brown.",
            "images":[
                {
                    "attribution":"Courtesy of Agronomy Extension, Iowa State University.",
                    "caption":"R8 - Full maturity",
                    "url":".../R8.jpg"
                }
            ],
            "name":"R8 - Harvest Maturity",
            "order":"21"
        },...
    }
}

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={string}&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

string

no

 — 

Classification indicating how early a variety matures. Valid values fall into the following range bins: 000.0 to 000.9, 00.0 to 00.9, and 0.0 to 10.9. Multi-zero range bins indicate the earliest maturities, with values near 10.9 indicating the latest maturities. Default is 3.0.

plant_depth

float

no

 — 

The depth (in cm) that the crop was planted. Valid values range from 0.1 to 7.5 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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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 in degrees Fahrenheit, which may be a historical, forecast, or climatological value, depending on the timeframe.

air_temp_max

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

air_temp_min

Minimum daily air temperature in degrees Fahrenheit, 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. 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_reproductive_stage

The last known reproductive stage. If no valid stage has been reached, this value will be “n/a.”

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, after which only new reproductive stages will be listed.

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 may have entered a new reproductive stage between the current date and the previous date. If new_reproductive_stage is “n/a,” 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 “n/a,” 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, after which 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 “n/a,” 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 DSSAT / CROPGRO / Soybean."
    ],
    "data":{
        "47,-97":{
            "2016-08-11":{
                "agdd":1562.67,
                "air_temp_avg":71.0,
                "air_temp_max":86.0,
                "air_temp_min":57.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":54.0
            },...
        }
    },
    "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":".../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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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 in degrees Fahrenheit, which may be a historical, forecast, or climatological value, depending on the timeframe.

air_temp_max

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

air_temp_min

Minimum daily air temperature in degrees Fahrenheit, 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. If no valid stage has been reached, this value will be “n/a.”

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, after which only new reproductive stages will be listed.

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 may have entered a new reproductive stage between the current date and the previous date. If new_reproductive_stage is “n/a,” 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 “n/a,” 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, after which 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 “n/a,” 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":52.0,
                "air_temp_max":65.0,
                "air_temp_min":39.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.0
            },...
        }
    }
}

7.9. 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.9.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.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

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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.9.3. Response Object

A string representing a feedback ID.

7.9.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.9.5. Example Response

def-345

7.10. Soybean Growth Feedbacks by Growth - v1.0

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

7.10.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.10.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

7.10.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.10.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.10.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.11. 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.11.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.11.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.11.3. Response Object

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

7.11.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.11.5. Example Response

true

7.12. 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.12.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.12.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.12.3. Response Object

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

7.12.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.12.5. Example Response

true

8. Cotton

8.1. Cotton Growth Creation - v1.0

This endpoint allows users to create a cotton growth on an existing field. The given user adding the cotton growth must have write privileges for the field being updated.

8.1.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/cotton/growth/create/{field_id}?
account_id={string}&user_id={string}&plant_date={timestamp}
&relative_maturity={string}&plant_depth={float}
&min_soil_moisture_allowed={float}&max_soil_moisture_allowed={float}

8.1.2. Request Parameters

Parameter Type Required Description

account_id

string

yes

Your Accounts API account ID.

field_id

string

yes

Specifies ID of field to be updated.

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.

plant_date, emergence_date

timestamp

yes

Epoch timestamp valid near the time that the crop reached emergence2.

relative_maturity

string

no

Gauges how long it will take for the crop to mature. The relative maturity of cotton is categorized by one of the following statements: “early,” “medium-early,” “medium,” “medium-late,” or “late.” If no value is given, a default relative maturity of “medium” will be used.

plant_depth

float

no

The depth in centimeters that the crop was planted. Plant depth must be a float between 0.1 and 4.9 cm. If no value is provided, the default plant depth is 3.5.

min_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level. Values must be greater than 0.0 and less than 100.0

max_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level. Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0

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

8.1.3. Response Object

A string representing a growth ID.

8.1.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/cotton/growth/create/abc-123?
account_id=123&user_id=xyz-123&app_id=456&app_key=789&plant_date=1393632000
&relative_maturity=early

8.1.5. Example Response

abc-def

8.2. Cotton Get Growth - v1.0

This endpoint allows a user to receive a previously created growth based on growth ID.

8.2.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/cotton/growth/get/{growth_id}?
plant={string}&account_id={string}&user_id={string}

8.2.2. Request Parameters

Parameter Type Required Description

plant

string

yes

Name of plant (i.e. corn or winter_wheat).

growth_id

string

yes

Specifies ID of crop growth to be queried from the user information database, provided by the Create Growth endpoint.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

8.2.3. Response Object (JSON)

Field Description

acres

Areal size of the field in acres.

created

Epoch timestamp in seconds.2

field_id

Specifies ID of field to which crop growth data has been assigned.

field_name

Name of the field.

growth_id

Specifies ID of crop growth queried.

harvest_date

An epoch timestamp in seconds for which harvest has begun.2

irrigation_type

Represents whether or not the cropland utilizes pivot irrigation. Valid values: 0 is “false” and 1 is “true.”

latitude

Latitude coordinate near the center of the field in decimal degrees.

longitude

Longitude coordinate near the center of the field in decimal degrees.

min_soil_moisture_allowed

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level Values must be greater than 0.0 and less than 100.0.

max_soil_moisture_allowed

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level. Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0

name

Name of the growth.

plant_date

Approximate time at which the crop was planted.

plant_name

Name of the crop plant.

plant_type

Coded value representing the type of crop planted. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

plant_subtype

Coded value representing the specific variety of crop planted.

plant_type

Enumeration value representing plant sub-type.

relative_maturity

Classification indicating how early a variety matures. Depending on the crop, valid values may include “early,” “medium-early,” “medium,” “medium-late,” or “late,” — where crops having an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

seed_variety

Additional description or notes for the seed used.

subdrainage_type

Represents whether or not the cropland utilizes drainage tile. Valid values: 0 is “false” (default) and 1 is “true.”

surface_drainage_quality

Represents field drainage effectiveness. Valid values: 0 is poor, 1 is average, and 2 is good.

previous_crop

Type ID of previously planted crop.

previous_harvest_date

Epoch time which previous crop was harvested.2

previous_yield

Yield of previous crop.

previous_yield_unit

Unit of measure for previous yield.

yield_goal

Yield target of current growth.

yield_goal_unit

Unit of measure for yield goal.

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

8.2.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/cotton/growth/get/bcd-def?
&account_id=123&user_id=xyz-123

8.2.5. Example Response

{
    "acres":1234.0,
    "created":1445972460,
    "emergence_date":null,
    "field_id":"abc-def",
    "field_name":"MyField",
    "growth_id":"bcd-def",
    "harvest_date":null,
    "irrigation_type":1,
    "latitude":30.107118606567383,
    "longitude":-82.3095703125,
    "min_soil_moisture_allowed":12.32,
    "max_soil_moisture_allowed":24.48,
    "name":"MyGrowth",
    "plant_date":1398920400,
    "plant_name":"cotton",
    "plant_subtype":0,
    "plant_type":65,
    "relative_maturity":"late",
    "seed_variety":null,
    "subdrainage_type":1,
    "surface_drainage_quality":1,
    "version":"v1.1"
}

8.3. Cotton Growth Modify - v1.0

This endpoint allows a user to modify an existing cotton growth.

8.3.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/cotton/growth/modify/{growth_id}?
account_id={string}&user_id={string}&plant_date={timestamp}
&relative_maturity={string}&min_soil_moisture_allowed={float}
&max_soil_moisture_allowed={float}

8.3.2. Request Parameters

Parameter Type Required Description

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.

plant_date, emergence_date

timestamp

yes

Epoch timestamp valid near the time that the crop reached emergence2.

growth_id

string

yes

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

relative_maturity

string

no

Gauges how long it will take for the crop to mature. The relative maturity of cotton is categorized by one of the following statements: “early,” “medium-early,” “medium,” “medium-late,” or “late. If no value is given, a default relative maturity of “medium” will be used.

min_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level. Values must be greater than 0.0 and less than 100.0

max_soil_moisture_allowed

float

no

Management Allowed Depletion (MAD) level input as root zone volumetric water content in percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level Values must be greater than 0.0, at least 5.0 greater than min_soil_moisture_allowed (if a value is or is being set), and must be less than 100.0.

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

8.3.3. Response Object

Returns “true” on success.

8.3.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/cotton/growth/modify/abc-123?
account_id=123&user_id=xyz-123&plant_date=1456890400&relative_maturity=medium

8.3.5. Example Response

true

8.4. Cotton Growth Delete - v1.0

This endpoint allows a user to delete a cotton growth. By deleting a growth, any applicable growth feedback and growth whitelist items will also be deleted.

8.4.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/cotton/growth/delete/{growth_id}?
account_id={string}&user_id={string}

8.4.2. Request Parameters

Parameter Type Required Description

growth_id

string

yes

The ID of the target growth to delete.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

sring

yes

User ID provided by the Create User endpoint as a result of adding a new user to the user information database.

8.4.3. Response Object

Returns “true” on success.

8.4.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/cotton/growth/delete/abc-def?
account_id=123&user_id=xyz-123

8.4.5. Example Response

true

8.5. 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.5.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.5.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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.5.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.5.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.5.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.6. 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.6.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.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.

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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.6.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.6.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.6.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.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}
&use_unconfirmed={flag}
&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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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 emergence.2

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 harvested.2 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.

use_unconfirmed

flag

no

yes

When included in the query string, the nitrogen model will use all fertilizer treatment activities with confirmed value of “true” and “false.” If there exists a fertilizer treatment activity with a “rate” value of “null,” the nitrogen model will provide a rate recommendation.

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. Each fertilizer treatment activity will have an addition property of “recommendation,” which is “true” if the “rate” is a recommendation calculated by the nitrogen model or “false” if the “rate” was set from the fertilizer treatment activity.

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-05-20":[{
                "field_activity_id":"123-def",
                "depth_unit":"m",
                "rate":0,
                "fertilizer_id":"25",
                "confirmed":false,
                "created":1494522940,
                "modified":"n/a",
                "rate_unit":"gal/ac",
                "subtype":0,
                "depth":0.07619999999999999,
                "activity_type":308,
                "recommendation":true
            }]
        },
    "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"
        }
    }
}

8.8. 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.8.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.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

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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

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.8.3. Response Object

A string representing a feedback ID.

8.8.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.8.5. Example Response

def-345

8.9. Cotton Growth Feedbacks by Growth - v1.0

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

8.9.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.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

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

Specifies the ID given when a growth is successfully added to a field using the create growth endpoint.

8.9.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.9.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.9.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.10. 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.10.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.10.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.10.3. Response Object

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

8.10.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.10.5. Example Response

true

8.11. 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.11.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.11.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.11.3. Response Object

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

8.11.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.11.5. Example Response

true

9. Sunflower

9.1. Sunflower Growth Creation - v1.0

This endpoint allows users to create a sunflower growth on an existing field. The given user adding the sunflower growth must have write privileges for the field being updated.

9.1.1. URL Description

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/growth/create?
account_id={string}&field_id={string}&user_id={string}&plant_date={timestamp}
&relative_maturity={string}

9.1.2. Request Parameters

Parameter Type Required Description

account_id

string

yes

Your Accounts API account ID.

field_id

string

yes

Specifies ID of field to be updated.

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.

plant_date, emergence_date

timestamp

yes

Epoch timestamp valid near the time that the crop reached emergence2.

relative_maturity

string

no

Gauges how long it takes for the crop to mature. 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. If no value is given, a default relative maturity of “medium” will be used.

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

9.1.3. Response Object

A string representing a growth ID.

9.1.4. Example Request

http://ag.us.clearapis.com/v1.0/crop_health/sunflower/growth/create?
account_id=123&field_id=321-abc&user_id=xyz-123&plant_date=1462060800

9.1.5. Example Response

def-345

9.2. Sunflower Get Growth - v1.0

This endpoint allows a user to receive a previously created growth based on growth ID.

9.2.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/sunflower/growth/get/{growth_id}?
plant={string}&account_id={string}&user_id={string}

9.2.2. Request Parameters

Parameter Type Required Description

plant

string

yes

Name of plant (i.e. corn or winter_wheat).

growth_id

string

yes

The ID of the target growth.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

sring

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.

9.2.3. Response Object (JSON)

Field Description

acres

Areal size of the field in acres.

created

Epoch timestamp in seconds.2

field_id

Specifies ID of field to which crop growth data has been assigned.

field_name

Name of the field.

growth_id

Specifies ID of crop growth queried.

harvest_date

An epoch timestamp in seconds for which harvest has begun.2

irrigation_type

Represents whether or not the cropland utilizes pivot irrigation. Valid values: 0 is “false” and 1 is “true.”

latitude

Latitude coordinate near the center of the field in decimal degrees.

longitude

Longitude coordinate near the center of the field in decimal degrees.

name

Name of the growth.

plant_date

Approximate time at which the crop was planted.

plant_name

Name of the crop plant.

plant_type

Coded value representing the type of crop planted. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

plant_subtype

Coded value representing the specific variety of crop planted.

plant_type

Enumeration value representing plant sub-type.

relative_maturity

Classification indicating how early a variety matures. Depending on the crop, valid values may include “early,” “medium-early,” “medium,” “medium-late,” or “late,” — where crops having an “early” relative maturity are expected to mature relatively fast, and crops having a “late” relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops. (See the Activity and Plant Codes section of the Accounts API appendix for a complete listing of activity type codes and their meanings.)

seed_variety

Additional description or notes for the seed used.

subdrainage_type

Represents whether or not the cropland utilizes drainage tile. Valid values: 0 is “false” (default) and 1 is “true.”

surface_drainage_quality

Represents field drainage effectiveness. Valid values: 0 is poor, 1 is average, and 2 is good.

previous_crop

Type ID of previously planted crop.

previous_harvest_date

Epoch time which previous crop was harvested.2

previous_yield

Yield of previous crop.

previous_yield_unit

Unit of measure for previous yield.

yield_goal

Yield target of current growth.

yield_goal_unit

Unit of measure for yield goal.

9.2.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/sunflower/growth/get/bcd-def?
&account_id=123&user_id=xyz-123

9.2.5. Example Response

{
    "acres":160.0,
    "created":1498071470,
    "emergence_date":null,
    "field_id":"abc-def",
    "field_name":"MyField",
    "growth_id":"bcd-def",
    "harvest_date":null,
    "irrigation_type":null,
    "latitude":47.92338180541992,
    "longitude":-97.0919189453125,
    "name":"MyGrowth",
    "plant_date":1398920400,
    "plant_name":"sunflower",
    "plant_subtype":0,
    "plant_type":72,
    "relative_maturity":"medium-early",
    "seed_variety":"",
    "subdrainage_type":0,
    "surface_drainage_quality":1,
    "version":"v1.0"
}

9.3. Sunflower Growth Modify - v1.0

The endpoint allows a user to modify or update a sunflower growth.

9.3.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/sunflower/growth/modify/{growth_id}?
account_id={string}&user_id={string}&plant_date={timestamp}
&emergence_date={timestamp}&harvest_date={timestamp}&plant_subtype={integer}
name={string}&seed_variety={string}&relative_maturity={string}

9.3.2. Request Parameters

Parameter Type Required Description

growth_id

string

yes

The ID of the target growth to be modified.

plant_date

timestamp

no

Epoch timestamp in seconds2.

emergence_date

timestamp

no

Epoch timestamp in seconds2.

harvest_date

timestamp

no

Epoch timestamp in seconds2.

plant_subtype

integer

no

Coded value representing the specific variety of crop planted.

name

string

no

New name of the field.

seed_variety

string

no

Additional description or notes for the seed used.

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.

relative_maturity

string

no

Gauges how long it takes for the crop to mature. Valid values include “early,” “medium-early,” “medium,” “medium-late,” or “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. If no value is given, a default relative maturity of “medium” will be used.

9.3.3. Response Object

Returns “true” on success.

9.3.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/sunflower/growth/modify/abc-def?
account_id=123&user_id=xyz-123

9.3.5. Example Response

true

9.4. Sunflower Growth Delete - v1.0

The endpoint allows a user to delete a sunflower growth. By deleting a growth, any applicable growth feedback and growth whitelist items will also be deleted.

9.4.1. URL Description

http://ag.clearapis.com/v1.0/crop_health/sunflower/growth/delete/{growth_id}?
account_id={string}&user_id={string}

9.4.2. Request Parameters

Parameter Type Required Description

growth_id

string

yes

The ID of the target growth to delete.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

sring

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.

9.4.3. Response Object

Returns “true” on success.

9.4.4. Example Request

http://ag.clearapis.com/v1.0/crop_health/sunflower/growth/delete/abc-def?
account_id=123&user_id=xyz-123

9.4.5. Example Response

true

9.5. 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.5.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.5.2. Request Parameters

Parameter