Growth

Crop Growth & Health API

Iteris’ Crop Growth & Health API includes crop-specific growth models, including Crop Growth Model Feedback, Crop Harvest Modeling, and Crop Nutrient (Nitrogen) Decision Support.

Crop Nutrient Decision

last updated 3/21/19

The ClearAg Nitrogen Advisor simulates the various processes of the nitrogen cycle that impact the availability of nitrogen to the crops. This model is based on a combination of proven algorithms from several industry models for simulating the nitrogen cycle. It allows for the 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 via the Crop Growth Models. Weather and soil information required by the Clear-N model are provided by the ClearAg Field Weather and Soil Conditions APIs. Please refer to the Appendix for a list of Supported Crops by Feature.

This bundle requires and includes the Accounts API and the Crop Growth Model bundle.

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.

Please note that API responses are currently only provided in English.

Iteris requires the use of https when working within the ClearAg APIs.

Additional API information is available in the Appendix.

Nitrogen Advisor

Barley Nitrogen Advisor - v1.0

The ClearAg Barley Nitrogen Advisor simulates the various processes of the nitrogen cycle that impact the availability of nitrogen to spring barley 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 Barley 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.

URL Description

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

Request Parameters

Parameter Type Location-based Account 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

A unique account ID provided by your Iteris account representative.

user_id

string

no

yes

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

growth_id

string

no

yes

Growth ID provided by the Growth Creation endpoint. If provided, properties of this growth will be used to generate model results.

yield_goal

integer

yes

yes

Target yield for current crop.

yield_goal_unit

string

yes

yes

Target yield unit. Accepted values: "lb/ac", "kg/ha", "bu/ac".

output_unit

string

yes

yes

Desired unit of area density data to be displayed in the response. Accepted values: "lb/ac", "kg/ha".

location

lat, lon coordinates

yes

 — 

Lat-lon coordinates of the field in decimal degrees. Format is: [(lat1, lon1), ...]. Limited to a single location per query.

plant_date

timestamp

no*

 — 

Date that the crop was planted in the form of a Unix timestamp. *Required if emergence_date is not provided.

emergence_date

timestamp

no*

 — 

Date that the crop began to emerge from the soil, in the form of a Unix timestamp. *Required if plant_date is not provided.

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

previous_crop

string

no

no

Enumeration value of previous crop on field. Accepted values: 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), 74 (alfalfa).

previous_harvest_date

timestamp

no

no

Date that the previous crop was harvested in the form of a Unix timestamp. 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: "lb/ac", "kg/ha", "bu/ac". Required if previous crop is specified. Note that "bu/ac" is not a valid yield unit for alfalfa, cotton, or vegetable.

year_offset

integer

no

no

Number of years by which to adjust model results. Useful for viewing results from a previous growing season given the exact same input configuration. Values must be less than 0.

use_unconfirmed

flag

no

no

Results in using all fertilizer treatment activities provided, including those where the application rate is undefined. The nitrogen model generates a recommended application rate in this case, with these activities otherwise ignored by default.

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. Recommendation property indicates whether or not the application rate is a recommendation calculated by the nitrogen model.

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 daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

feedback_id

If this parameter is present, it indicates a confirmed or observed growth stage.

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. "n/a" if 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 centimeters. 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.

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

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

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

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

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

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

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

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

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

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

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 "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 "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 desired yield goal.

uptake_score_unit

Units of "uptake_score."

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.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/barley/nutrient/nitrogen?app_id=456&app_key=789&account_id=123&user_id=xyz-123&growth_id=abc-def&yield_goal=1050&yield_goal_unit=kg/ha&output_unit=kg/ha

Example Response

{
    "activities":{
        "fertilizer_treatment":{
            "2016-05-20":[{
                "activity_type":308,
                "confirmed":true,
                "created":1494522940,
                "depth":0.1,
                "depth_unit":"m",
                "fertilizer_id":"25",
                "field_activity_id":"123-def",
                "modified":"n/a",
                "rate":0,
                "rate_unit":"gal/ac",
                "recommendation":false,
                "subtype":0
            }]
        }
    },
    "data":{
        "2016-07-25":{
            "agdd":2584.0,
            "air_temp_max":91.0,
            "air_temp_min":59.0,
            "gdd":43.0,
            "last_stage":"13.0",
            "new_stage":"15.0",
            "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":77.6,
                "nitrate_0to2":0.6,
                "nitrate_100to200":0.1,
                "nitrate_10to20":9.4,
                "nitrate_20to40":35.1,
                "nitrate_2to5":1.3,
                "nitrate_40to70":28.4,
                "nitrate_5to10":2.1,
                "nitrate_70to100":0.7,
                "nitrate_in_last_sample_depth":"n/a"
            },
            "nitrogen_budget":{
                "applied_fertilizers":0.0,
                "applied_fertilizers_0to2":0.0,
                "applied_fertilizers_100to200":0.0,
                "applied_fertilizers_10to20":0.0,
                "applied_fertilizers_20to40":0.0,
                "applied_fertilizers_2to5":0.0,
                "applied_fertilizers_40to70":0.0,
                "applied_fertilizers_5to10":0.0,
                "applied_fertilizers_70to100":0.0,
                "denitrified":0.0,
                "denitrified_0to2":0.0,
                "denitrified_100to200":0.0,
                "denitrified_10to20":0.0,
                "denitrified_20to40":0.0,
                "denitrified_2to5":0.0,
                "denitrified_40to70":0.0,
                "denitrified_5to10":0.0,
                "denitrified_70to100":0.0,
                "immobilized":-0.9,
                "immobilized_0to2":-0.3,
                "immobilized_100to200":-0.1,
                "immobilized_10to20":0.0,
                "immobilized_20to40":0.0,
                "immobilized_2to5":-0.5,
                "immobilized_40to70":0.0,
                "immobilized_5to10":0.0,
                "immobilized_70to100":0.0,
                "leached":0.0,
                "leached_0to2":-5.1,
                "leached_100to200":0.0,
                "leached_10to20":-13.0,
                "leached_20to40":13.4,
                "leached_2to5":-7.1,
                "leached_40to70":22.5,
                "leached_5to10":-11.4,
                "leached_70to100":0.7,
                "leached_below_current_root_depth":0.0,
                "leached_below_maximum_root_depth":0.0,
                "realized_from_crop_organic_matter":0.0,
                "realized_from_crop_organic_matter_0to2":0.0,
                "realized_from_crop_organic_matter_100to200":0.0,
                "realized_from_crop_organic_matter_10to20":0.0,
                "realized_from_crop_organic_matter_20to40":0.0,
                "realized_from_crop_organic_matter_2to5":0.0,
                "realized_from_crop_organic_matter_40to70":0.0,
                "realized_from_crop_organic_matter_5to10":0.0,
                "realized_from_crop_organic_matter_70to100":0.0,
                "realized_from_soil_organic_matter":41.2,
                "realized_from_soil_organic_matter_0to2":4.4,
                "realized_from_soil_organic_matter_100to200":0.2,
                "realized_from_soil_organic_matter_10to20":14.1,
                "realized_from_soil_organic_matter_20to40":6.5,
                "realized_from_soil_organic_matter_2to5":6.4,
                "realized_from_soil_organic_matter_40to70":0.2,
                "realized_from_soil_organic_matter_5to10":9.4,
                "realized_from_soil_organic_matter_70to100":0.1,
                "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.0,
                "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.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":120.0,
                "current_root_depth_unit":"cm",
                "indigenous_use_efficiency":0.0,
                "indigenous_use_efficiency_unit":"%",
                "maximum_root_depth":120.0,
                "maximum_root_depth_unit":"cm",
                "nitrogen_available_unit":"kg/ha",
                "nitrogen_budget_unit":"kg/ha",
                "notes":{},
                "uptake_score":"n/a",
                "uptake_score_unit":"%"
            }
        },...
    },
    "stage_descriptions":{
        "15.0":{
            "advisor":"Harvest",
            "description":"Dry weight of the kernels stops increasing.",
            "images":[
                {
                    "attribution":"Courtesy of...",
                    "caption":"This stage is between Hard Dough (left) and Harvest Ripe (right)",
                    "url":".../Physiological_maturity.png"
                },...
            ],
            "name":"15.0 - Physiological Maturity",
            "order":"16"
        },...
    }
}

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.

URL Description

https://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}&yield_goal={integer}&yield_goal_unit={string}&output_unit={string}&location={lat, lon coordinates}&plant_date={timestamp}&emergence_date={timestamp}&relative_maturity={string}&previous_crop={string}&previous_harvest_date={timestamp}&previous_yield={integer}&previous_yield_unit={string}&year_offset={integer}&use_unconfirmed

Request Parameters

Parameter Type Location-based Account 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

A unique account ID provided by your Iteris account representative.

user_id

string

no

yes

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

growth_id

string

no

yes

Growth ID provided by the Growth Creation endpoint. If provided, properties of this growth will be used to generate model results.

yield_goal

integer

yes

yes

Target yield for current crop.

yield_goal_unit

string

yes

yes

Target yield unit. Accepted values: "lb/ac", "kg/ha", "bu/ac".

output_unit

string

yes

yes

Desired unit of area density data to be displayed in the response. Accepted values: "lb/ac", "kg/ha".

location

lat, lon coordinates

yes

 — 

Lat-lon coordinates of the field in decimal degrees. Format is: [(lat1, lon1), ...]. Limited to a single location per query.

plant_date

timestamp

no*

 — 

Date that the crop was planted in the form of a Unix timestamp. *Required if emergence_date is not provided.

emergence_date

timestamp

no*

 — 

Date that the crop began to emerge from the soil, in the form of a Unix timestamp. *Required if plant_date is not provided.

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

previous_crop

string

no

no

Enumeration value of previous crop on field. Accepted values: 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), 74 (alfalfa).

previous_harvest_date

timestamp

no

no

Date that the previous crop was harvested in the form of a Unix timestamp. 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: "lb/ac", "kg/ha", "bu/ac". Required if previous crop is specified. Note that "bu/ac" is not a valid yield unit for alfalfa, cotton, or vegetable.

year_offset

integer

no

no

Number of years by which to adjust model results. Useful for viewing results from a previous growing season given the exact same input configuration. Values must be less than 0.

use_unconfirmed

flag

no

no

Results in using all fertilizer treatment activities provided, including those where the application rate is undefined. The nitrogen model generates a recommended application rate in this case, with these activities otherwise ignored by default.

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. Recommendation property indicates whether or not the application rate is a recommendation calculated by the nitrogen model.

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 daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

feedback_id

If this parameter is present, it indicates a confirmed or observed growth stage.

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. "n/a" if 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 centimeters. 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.

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

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

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

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

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

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

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

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

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

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

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 "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 "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 desired yield goal.

uptake_score_unit

Units of "uptake_score."

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.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/canola/nutrient/nitrogen?app_id=456&app_key=789&account_id=123&user_id=xyz-123&growth_id=abc-def&yield_goal=1050&yield_goal_unit=kg/ha&output_unit=kg/ha

Example Response

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

URL Description

https://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}&yield_goal={integer}&yield_goal_unit={string}&output_unit={string}&location={lat, lon coordinates}&plant_date={timestamp}&emergence_date={timestamp}&relative_maturity={integer}&previous_crop={string}&previous_harvest_date={timestamp}&previous_yield={integer}&previous_yield_unit={string}&year_offset={integer}&use_unconfirmed

Request Parameters

Parameter Type Location-based Account 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

A unique account ID provided by your Iteris account representative.

user_id

string

no

yes

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

growth_id

string

no

yes

Growth ID provided by the Growth Creation endpoint. If provided, properties of this growth will be used to generate model results.

yield_goal

integer

yes

yes

Target yield for current crop.

yield_goal_unit

string

yes

yes

Target yield unit. Accepted values: "lb/ac", "kg/ha", "bu/ac".

output_unit

string

yes

yes

Desired unit of area density data to be displayed in the response. Accepted values: "lb/ac", "kg/ha".

location

lat, lon coordinates

yes

 — 

Lat-lon coordinates of the field in decimal degrees. Format is: [(lat1, lon1), ...]. Limited to a single location per query.

plant_date

timestamp

no*

 — 

Date that the crop was planted in the form of a Unix timestamp. *Required if emergence_date is not provided.

emergence_date

timestamp

no*

 — 

Date that the crop began to emerge from the soil, in the form of a Unix timestamp. *Required if plant_date is not provided.

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.

previous_crop

string

no

no

Enumeration value of previous crop on field. Accepted values: 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), 74 (alfalfa).

previous_harvest_date

timestamp

no

no

Date that the previous crop was harvested in the form of a Unix timestamp. 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: "lb/ac", "kg/ha", "bu/ac". Required if previous crop is specified. Note that "bu/ac" is not a valid yield unit for alfalfa, cotton, or vegetable.

year_offset

integer

no

no

Number of years by which to adjust model results. Useful for viewing results from a previous growing season given the exact same input configuration. Values must be less than 0.

use_unconfirmed

flag

no

no

Results in using all fertilizer treatment activities provided, including those where the application rate is undefined. The nitrogen model generates a recommended application rate in this case, with these activities otherwise ignored by default.

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. Recommendation property indicates whether or not the application rate is a recommendation calculated by the nitrogen model.

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 daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

feedback_id

If this parameter is present, it indicates a confirmed or observed growth stage.

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. "n/a" if 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 centimeters. 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.

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

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

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

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

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

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

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

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

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

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

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 "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 "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 desired yield goal.

uptake_score_unit

Units of "uptake_score."

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.

Example Request

https://ag.us.clearapis.com/v1.1/crop_health/corn/nutrient/nitrogen?app_id=456&app_key=789&account_id=123&user_id=xyz-123&growth_id=abc-def&yield_goal=1050&yield_goal_unit=kg/ha&output_unit=kg/ha

Example Response

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

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.

URL Description

https://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}&yield_goal={integer}&yield_goal_unit={string}&output_unit={string}&location={lat, lon coordinates}&plant_date={timestamp}&emergence_date={timestamp}&relative_maturity={string}&previous_crop={string}&previous_harvest_date={timestamp}&previous_yield={integer}&previous_yield_unit={string}&year_offset={integer}&use_unconfirmed

Request Parameters

Parameter Type Location-based Account 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

A unique account ID provided by your Iteris account representative.

user_id

string

no

yes

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

growth_id

string

no

yes

Growth ID provided by the Growth Creation endpoint. If provided, properties of this growth will be used to generate model results.

yield_goal

integer

yes

yes

Target yield for current crop.

yield_goal_unit

string

yes

yes

Target yield unit. Accepted values: "lb/ac", "kg/ha", "bu/ac".

output_unit

string

yes

yes

Desired unit of area density data to be displayed in the response. Accepted values: "lb/ac", "kg/ha".

location

lat, lon coordinates

yes

 — 

Lat-lon coordinates of the field in decimal degrees. Format is: [(lat1, lon1), ...]. Limited to a single location per query.

plant_date

timestamp

no*

 — 

Date that the crop was planted in the form of a Unix timestamp. *Required if emergence_date is not provided.

emergence_date

timestamp

no*

 — 

Date that the crop began to emerge from the soil, in the form of a Unix timestamp. *Required if plant_date is not provided.

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

previous_crop

string

no

no

Enumeration value of previous crop on field. Accepted values: 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), 74 (alfalfa).

previous_harvest_date

timestamp

no

no

Date that the previous crop was harvested in the form of a Unix timestamp. 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: "lb/ac", "kg/ha", "bu/ac". Required if previous crop is specified. Note that "bu/ac" is not a valid yield unit for alfalfa, cotton, or vegetable.

year_offset

integer

no

no

Number of years by which to adjust model results. Useful for viewing results from a previous growing season given the exact same input configuration. Values must be less than 0.

use_unconfirmed

flag

no

no

Results in using all fertilizer treatment activities provided, including those where the application rate is undefined. The nitrogen model generates a recommended application rate in this case, with these activities otherwise ignored by default.

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. Recommendation property indicates whether or not the application rate is a recommendation calculated by the nitrogen model.

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 daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

feedback_id

If this parameter is present, it indicates a confirmed or observed growth stage.

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. "n/a" if 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 centimeters. 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.

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

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

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

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

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

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

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

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

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

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

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 "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 "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 desired yield goal.

uptake_score_unit

Units of "uptake_score."

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.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/cotton/nutrient/nitrogen?app_id=456&app_key=789&account_id=123&user_id=xyz-123&growth_id=abc-def&yield_goal=1050&yield_goal_unit=kg/ha&output_unit=kg/ha

Example Response

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

Sorghum Nitrogen Advisor - v1.0

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

URL Description

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

Request Parameters

Parameter Type Location-based Account 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

A unique account ID provided by your Iteris account representative.

user_id

string

no

yes

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

growth_id

string

no

yes

Growth ID provided by the Growth Creation endpoint. If provided, properties of this growth will be used to generate model results.

yield_goal

integer

yes

yes

Target yield for current crop.

yield_goal_unit

string

yes

yes

Target yield unit. Accepted values: "lb/ac", "kg/ha", "bu/ac".

output_unit

string

yes

yes

Desired unit of area density data to be displayed in the response. Accepted values: "lb/ac", "kg/ha".

location

lat, lon coordinates

yes

 — 

Lat-lon coordinates of the field in decimal degrees. Format is: [(lat1, lon1), ...]. Limited to a single location per query.

plant_date

timestamp

no*

 — 

Date that the crop was planted in the form of a Unix timestamp. *Required if emergence_date is not provided.

emergence_date

timestamp

no*

 — 

Date that the crop began to emerge from the soil, in the form of a Unix timestamp. *Required if plant_date is not provided.

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

previous_crop

string

no

no

Enumeration value of previous crop on field. Accepted values: 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), 74 (alfalfa).

previous_harvest_date

timestamp

no

no

Date that the previous crop was harvested in the form of a Unix timestamp. 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: "lb/ac", "kg/ha", "bu/ac". Required if previous crop is specified. Note that "bu/ac" is not a valid yield unit for alfalfa, cotton, or vegetable.

year_offset

integer

no

no

Number of years by which to adjust model results. Useful for viewing results from a previous growing season given the exact same input configuration. Values must be less than 0.

use_unconfirmed

flag

no

no

Results in using all fertilizer treatment activities provided, including those where the application rate is undefined. The nitrogen model generates a recommended application rate in this case, with these activities otherwise ignored by default.

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. Recommendation property indicates whether or not the application rate is a recommendation calculated by the nitrogen model.

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 daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

feedback_id

If this parameter is present, it indicates a confirmed or observed growth stage.

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. "n/a" if 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 centimeters. 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.

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

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

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

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

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

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

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

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

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

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

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 "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 "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 desired yield goal.

uptake_score_unit

Units of "uptake_score."

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.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/sorghum/nutrient/nitrogen?app_id=456&app_key=789&account_id=123&user_id=xyz-123&growth_id=abc-def&yield_goal=1050&yield_goal_unit=kg/ha&output_unit=kg/ha

Example Response

{
    "activities":{
        "fertilizer_treatment":{
            "2016-05-20":[{
                "activity_type":308,
                "confirmed":true,
                "created":1494522940,
                "depth":0.1,
                "depth_unit":"m",
                "fertilizer_id":"25",
                "field_activity_id":"123-def",
                "modified":"n/a",
                "rate":0,
                "rate_unit":"gal/ac",
                "recommendation":false,
                "subtype":0
            }]
        },
    "data":{
        "2016-10-15":{
            "agdd":2757.5,
            "air_temp_max":72.0,
            "air_temp_min":44.0,
            "gdd":11.0,
            "last_stage":"11",
            "new_stage":"12",
            "nitrogen_available":{
                "ammonium":0.0,
                "ammonium_0to2":0.0,
                "ammonium_100to200":0.0,
                "ammonium_10to20":0.0,
                "ammonium_20to40":0.0,
                "ammonium_2to5":0.0,
                "ammonium_40to70":0.0,
                "ammonium_5to10":0.0,
                "ammonium_70to100":0.0,
                "ammonium_in_last_sample_depth":"n/a",
                "nitrate":76.1,
                "nitrate_0to2":0.5,
                "nitrate_100to200":0.0,
                "nitrate_10to20":12.3,
                "nitrate_20to40":35.3,
                "nitrate_2to5":0.9,
                "nitrate_40to70":22.8,
                "nitrate_5to10":2.7,
                "nitrate_70to100":1.6,
                "nitrate_in_last_sample_depth":"n/a"
            },
            "nitrogen_budget":{
                "applied_fertilizers":0.0,
                "applied_fertilizers_0to2":0.0,
                "applied_fertilizers_100to200":0.0,
                "applied_fertilizers_10to20":0.0,
                "applied_fertilizers_20to40":0.0,
                "applied_fertilizers_2to5":0.0,
                "applied_fertilizers_40to70":0.0,
                "applied_fertilizers_5to10":0.0,
                "applied_fertilizers_70to100":0.0,
                "denitrified":0.0,
                "denitrified_0to2":0.0,
                "denitrified_100to200":0.0,
                "denitrified_10to20":0.0,
                "denitrified_20to40":0.0,
                "denitrified_2to5":0.0,
                "denitrified_40to70":0.0,
                "denitrified_5to10":0.0,
                "denitrified_70to100":0.0,
                "immobilized":0.0,
                "immobilized_0to2":0.0,
                "immobilized_100to200":0.0,
                "immobilized_10to20":0.0,
                "immobilized_20to40":0.0,
                "immobilized_2to5":0.0,
                "immobilized_40to70":0.0,
                "immobilized_5to10":0.0,
                "immobilized_70to100":0.0,
                "leached":0.0,
                "leached_0to2":-6.9,
                "leached_100to200":0.0,
                "leached_10to20":-11.6,
                "leached_20to40":18.9,
                "leached_2to5":-9.6,
                "leached_40to70":20.1,
                "leached_5to10":-12.7,
                "leached_70to100":1.8,
                "leached_below_current_root_depth":0.0,
                "leached_below_maximum_root_depth":0.0,
                "realized_from_crop_organic_matter":0.0,
                "realized_from_crop_organic_matter_0to2":0.0,
                "realized_from_crop_organic_matter_100to200":0.0,
                "realized_from_crop_organic_matter_10to20":0.0,
                "realized_from_crop_organic_matter_20to40":0.0,
                "realized_from_crop_organic_matter_2to5":0.0,
                "realized_from_crop_organic_matter_40to70":0.0,
                "realized_from_crop_organic_matter_5to10":0.0,
                "realized_from_crop_organic_matter_70to100":0.0,
                "realized_from_soil_organic_matter":61.0,
                "realized_from_soil_organic_matter_0to2":6.1,
                "realized_from_soil_organic_matter_100to200":0.0,
                "realized_from_soil_organic_matter_10to20":21.7,
                "realized_from_soil_organic_matter_20to40":10.4,
                "realized_from_soil_organic_matter_2to5":9.1,
                "realized_from_soil_organic_matter_40to70":0.0,
                "realized_from_soil_organic_matter_5to10":13.6,
                "realized_from_soil_organic_matter_70to100":0.0,
                "uptaken_by_crop":-22.2,
                "uptaken_by_crop_0to2":-0.3,
                "uptaken_by_crop_100to200":0.0,
                "uptaken_by_crop_10to20":-6.0,
                "uptaken_by_crop_20to40":-9.3,
                "uptaken_by_crop_2to5":-1.0,
                "uptaken_by_crop_40to70":-3.1,
                "uptaken_by_crop_5to10":-2.3,
                "uptaken_by_crop_70to100":-0.2,
                "uptaken_by_crop_optimal":-22.2,
                "uptaken_by_crop_optimal_0to2":-0.5,
                "uptaken_by_crop_optimal_100to200":0.0,
                "uptaken_by_crop_optimal_10to20":-6.0,
                "uptaken_by_crop_optimal_20to40":-9.3,
                "uptaken_by_crop_optimal_2to5":-1.0,
                "uptaken_by_crop_optimal_40to70":-3.1,
                "uptaken_by_crop_optimal_5to10":-2.2,
                "uptaken_by_crop_optimal_70to100":-0.2,
                "volatized":0.0,
                "volatized_0to2":0.0,
                "volatized_100to200":0.0,
                "volatized_10to20":0.0,
                "volatized_20to40":0.0,
                "volatized_2to5":0.0,
                "volatized_40to70":0.0,
                "volatized_5to10":0.0,
                "volatized_70to100":0.0
            },
            "nitrogen_metadata":{
                "applied_use_efficiency":"n/a",
                "applied_use_efficiency_unit":"%",
                "current_root_depth":138.0,
                "current_root_depth_unit":"cm",
                "indigenous_use_efficiency":36.4,
                "indigenous_use_efficiency_unit":"%",
                "maximum_root_depth":138.0,
                "maximum_root_depth_unit":"cm",
                "nitrogen_available_unit":"kg/ha",
                "nitrogen_budget_unit":"kg/ha",
                "notes":{
                    "3":"Soil moisture is limiting crop nitrogen uptake."
                },
                "uptake_score":100.0,
                "uptake_score_unit":"%"
            }
        },...
    },
    "stage_descriptions":{
        "12":{
            "advisor":"Harvest",
            "description":"Grain achieves its maximum dry weight. Mature grain is identified by looking for the dark spot, the black layer, on the bottom of the kernel. Grain moisture ranges from 25 to 35%.",
            "images":[
                {
                    "attribution":"Courtesy of...",
                    "caption":"Physiological Maturity",
                    "url":".../Physiological+Maturity.png"
                },...
            ],
            "name":"Physiological Maturity",
            "order":"12"
        },...
    }
}

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.

URL Description

https://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}&yield_goal={integer}&yield_goal_unit={string}&output_unit={string}&location={lat, lon coordinates}&plant_date={timestamp}&emergence_date={timestamp}&relative_maturity={string}&previous_crop={string}&previous_harvest_date={timestamp}&previous_yield={integer}&previous_yield_unit={string}&year_offset={integer}&use_unconfirmed

Request Parameters

Parameter Type Location-based Account 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

A unique account ID provided by your Iteris account representative.

user_id

string

no

yes

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

growth_id

string

no

yes

Growth ID provided by the Growth Creation endpoint. If provided, properties of this growth will be used to generate model results.

yield_goal

integer

yes

yes

Target yield for current crop.

yield_goal_unit

string

yes

yes

Target yield unit. Accepted values: "lb/ac", "kg/ha", "bu/ac".

output_unit

string

yes

yes

Desired unit of area density data to be displayed in the response. Accepted values: "lb/ac", "kg/ha".

location

lat, lon coordinates

yes

 — 

Lat-lon coordinates of the field in decimal degrees. Format is: [(lat1, lon1), ...]. Limited to a single location per query.

plant_date

timestamp

no*

 — 

Date that the crop was planted in the form of a Unix timestamp. *Required if emergence_date is not provided.

emergence_date

timestamp

no*

 — 

Date that the crop began to emerge from the soil, in the form of a Unix timestamp. *Required if plant_date is not provided.

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

previous_crop

string

no

no

Enumeration value of previous crop on field. Accepted values: 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), 74 (alfalfa).

previous_harvest_date

timestamp

no

no

Date that the previous crop was harvested in the form of a Unix timestamp. 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: "lb/ac", "kg/ha", "bu/ac". Required if previous crop is specified. Note that "bu/ac" is not a valid yield unit for alfalfa, cotton, or vegetable.

year_offset

integer

no

no

Number of years by which to adjust model results. Useful for viewing results from a previous growing season given the exact same input configuration. Values must be less than 0.

use_unconfirmed

flag

no

no

Results in using all fertilizer treatment activities provided, including those where the application rate is undefined. The nitrogen model generates a recommended application rate in this case, with these activities otherwise ignored by default.

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. Recommendation property indicates whether or not the application rate is a recommendation calculated by the nitrogen model.

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 daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

feedback_id

If this parameter is present, it indicates a confirmed or observed growth stage.

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. "n/a" if 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 centimeters. 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.

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

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

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

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

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

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

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

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

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

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

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 "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 "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 desired yield goal.

uptake_score_unit

Units of "uptake_score."

advisor

Suggested field properties to check.

applicable_scales/feekes

Stage equivalent in the Feekes scale.

applicable_scales/haun

Stage equivalent in the Haun scale.

applicable_scales/zadoks

Stage equivalent in the Zadoks scale.

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.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/springwheat/nutrient/nitrogen?app_id=456&app_key=789&account_id=123&user_id=xyz-123&growth_id=abc-def&yield_goal=1050&yield_goal_unit=kg/ha&output_unit=kg/ha

Example Response

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

Sunflower Nitrogen Advisor - v1.0

The ClearAg Sunflower Nitrogen Advisor simulates the various processes of the nitrogen cycle that impact the availability of nitrogen to sunflower 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 Sunflower 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.

URL Description

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

Request Parameters

Parameter Type Location-based Account 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

A unique account ID provided by your Iteris account representative.

user_id

string

no

yes

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

growth_id

string

no

yes

Growth ID provided by the Growth Creation endpoint. If provided, properties of this growth will be used to generate model results.

yield_goal

integer

yes

yes

Target yield for current crop.

yield_goal_unit

string

yes

yes

Target yield unit. Accepted values: "lb/ac", "kg/ha", "bu/ac".

output_unit

string

yes

yes

Desired unit of area density data to be displayed in the response. Accepted values: "lb/ac", "kg/ha".

location

lat, lon coordinates

yes

 — 

Lat-lon coordinates of the field in decimal degrees. Format is: [(lat1, lon1), ...]. Limited to a single location per query.

plant_date

timestamp

no*

 — 

Date that the crop was planted in the form of a Unix timestamp. *Required if emergence_date is not provided.

emergence_date

timestamp

no*

 — 

Date that the crop began to emerge from the soil, in the form of a Unix timestamp. *Required if plant_date is not provided.

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

previous_crop

string

no

no

Enumeration value of previous crop on field. Accepted values: 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), 74 (alfalfa).

previous_harvest_date

timestamp

no

no

Date that the previous crop was harvested in the form of a Unix timestamp. 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: "lb/ac", "kg/ha", "bu/ac". Required if previous crop is specified. Note that "bu/ac" is not a valid yield unit for alfalfa, cotton, or vegetable.

year_offset

integer

no

no

Number of years by which to adjust model results. Useful for viewing results from a previous growing season given the exact same input configuration. Values must be less than 0.

use_unconfirmed

flag

no

no

Results in using all fertilizer treatment activities provided, including those where the application rate is undefined. The nitrogen model generates a recommended application rate in this case, with these activities otherwise ignored by default.

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. Recommendation property indicates whether or not the application rate is a recommendation calculated by the nitrogen model.

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 daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

feedback_id

If this parameter is present, it indicates a confirmed or observed growth stage.

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. "n/a" if 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 centimeters. 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.

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

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

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

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

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

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

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

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

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

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

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 "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 "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 desired yield goal.

uptake_score_unit

Units of "uptake_score."

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.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/sunflower/nutrient/nitrogen?app_id=456&app_key=789&account_id=123&user_id=xyz-123&growth_id=abc-def&yield_goal=1050&yield_goal_unit=kg/ha&output_unit=kg/ha

Example Response

{
    "activities":{
        "fertilizer_treatment":{
            "2016-05-20":[{
                "activity_type":308,
                "confirmed":true,
                "created":1494522940,
                "depth":0.1,
                "depth_unit":"m",
                "fertilizer_id":"25",
                "field_activity_id":"123-def",
                "modified":"n/a",
                "rate":0,
                "rate_unit":"gal/ac",
                "recommendation":false,
                "subtype":0
            }]
        }
    },
    "data":{
        "2016-09-07":{
            "agdd":2906.5,
            "air_temp_max":76.0,
            "air_temp_min":52.0,
            "gdd":20.0,
            "last_stage":"30",
            "new_stage":"31",
            "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":64.3,
                "nitrate_0to2":0.0,
                "nitrate_100to200":0.0,
                "nitrate_10to20":18.4,
                "nitrate_20to40":28.6,
                "nitrate_2to5":0.1,
                "nitrate_40to70":14.7,
                "nitrate_5to10":2.3,
                "nitrate_70to100":0.3,
                "nitrate_in_last_sample_depth":"n/a"
            },
            "nitrogen_budget":{
                "applied_fertilizers":0.0,
                "applied_fertilizers_0to2":0.0,
                "applied_fertilizers_100to200":0.0,
                "applied_fertilizers_10to20":0.0,
                "applied_fertilizers_20to40":0.0,
                "applied_fertilizers_2to5":0.0,
                "applied_fertilizers_40to70":0.0,
                "applied_fertilizers_5to10":0.0,
                "applied_fertilizers_70to100":0.0,
                "denitrified":0.0,
                "denitrified_0to2":0.0,
                "denitrified_100to200":0.0,
                "denitrified_10to20":0.0,
                "denitrified_20to40":0.0,
                "denitrified_2to5":0.0,
                "denitrified_40to70":0.0,
                "denitrified_5to10":0.0,
                "denitrified_70to100":0.0,
                "immobilized":0.0,
                "immobilized_0to2":0.0,
                "immobilized_100to200":0.0,
                "immobilized_10to20":0.0,
                "immobilized_20to40":0.0,
                "immobilized_2to5":0.0,
                "immobilized_40to70":0.0,
                "immobilized_5to10":0.0,
                "immobilized_70to100":0.0,
                "leached":0.0,
                "leached_0to2":-6.9,
                "leached_100to200":0.0,
                "leached_10to20":0.9,
                "leached_20to40":14.5,
                "leached_2to5":-9.5,
                "leached_40to70":11.0,
                "leached_5to10":-10.4,
                "leached_70to100":0.3,
                "leached_below_current_root_depth":0.0,
                "leached_below_maximum_root_depth":0.0,
                "realized_from_crop_organic_matter":0.0,
                "realized_from_crop_organic_matter_0to2":0.0,
                "realized_from_crop_organic_matter_100to200":0.0,
                "realized_from_crop_organic_matter_10to20":0.0,
                "realized_from_crop_organic_matter_20to40":0.0,
                "realized_from_crop_organic_matter_2to5":0.0,
                "realized_from_crop_organic_matter_40to70":0.0,
                "realized_from_crop_organic_matter_5to10":0.0,
                "realized_from_crop_organic_matter_70to100":0.0,
                "realized_from_soil_organic_matter":53.3,
                "realized_from_soil_organic_matter_0to2":5.7,
                "realized_from_soil_organic_matter_100to200":0.0,
                "realized_from_soil_organic_matter_10to20":18.8,
                "realized_from_soil_organic_matter_20to40":8.1,
                "realized_from_soil_organic_matter_2to5":8.3,
                "realized_from_soil_organic_matter_40to70":0.0,
                "realized_from_soil_organic_matter_5to10":12.4,
                "realized_from_soil_organic_matter_70to100":0.0,
                "uptaken_by_crop":-26.3,
                "uptaken_by_crop_0to2":-0.4,
                "uptaken_by_crop_100to200":0.0,
                "uptaken_by_crop_10to20":-9.5,
                "uptaken_by_crop_20to40":-9.3,
                "uptaken_by_crop_2to5":-1.2,
                "uptaken_by_crop_40to70":-2.1,
                "uptaken_by_crop_5to10":-3.7,
                "uptaken_by_crop_70to100":0.0,
                "uptaken_by_crop_optimal":-26.5,
                "uptaken_by_crop_optimal_0to2":-0.4,
                "uptaken_by_crop_optimal_100to200":0.0,
                "uptaken_by_crop_optimal_10to20":-9.6,
                "uptaken_by_crop_optimal_20to40":-9.0,
                "uptaken_by_crop_optimal_2to5":-1.2,
                "uptaken_by_crop_optimal_40to70":-2.0,
                "uptaken_by_crop_optimal_5to10":-4.2,
                "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":"n/a",
                "applied_use_efficiency_unit":"%",
                "current_root_depth":191.0,
                "current_root_depth_unit":"cm",
                "indigenous_use_efficiency":49.4,
                "indigenous_use_efficiency_unit":"%",
                "maximum_root_depth":191.0,
                "maximum_root_depth_unit":"cm",
                "nitrogen_available_unit":"kg/ha",
                "nitrogen_budget_unit":"kg/ha",
                "notes":{},
                "uptake_score":86.3,
                "uptake_score_unit":"%"
            }
        },...
    },
    "stage_descriptions":{
        "31":{
            "advisor":"Harvest",
            "description":"The back of the head is brown; the bracts turn yellow/brown.",
            "images":[
                {
                    "attribution":"Courtesy of...",
                    "caption":"R9 stage",
                    "url":".../R9.jpg"
                },...
            ],
            "name":"R9 - Physiological Maturity",
            "order":"17"
        },...
    }
}

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.

URL Description

https://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}&yield_goal={integer}&yield_goal_unit={string}&output_unit={string}&location={lat, lon coordinates}&plant_date={timestamp}&emergence_date={timestamp}&relative_maturity={string}&plant_depth={float}&previous_crop={string}&previous_harvest_date={timestamp}&previous_yield={integer}&previous_yield_unit={string}&year_offset={integer}&use_unconfirmed

Request Parameters

Parameter Type Location-based Account 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

A unique account ID provided by your Iteris account representative.

user_id

string

no

yes

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

growth_id

string

no

yes

Growth ID provided by the Growth Creation endpoint. If provided, properties of this growth will be used to generate model results.

yield_goal

integer

yes

yes

Target yield for current crop.

yield_goal_unit

string

yes

yes

Target yield unit. Accepted values: "lb/ac", "kg/ha", "bu/ac".

output_unit

string

yes

yes

Desired unit of area density data to be displayed in the response. Accepted values: "lb/ac", "kg/ha".

location

lat, lon coordinates

yes

 — 

Lat-lon coordinates of the field in decimal degrees. Format is: [(lat1, lon1), ...]. Limited to a single location per query.

plant_date

timestamp

no*

 — 

Date that the crop was planted in the form of a Unix timestamp. *Required if emergence_date is not provided.

emergence_date

timestamp

no*

 — 

Date that the crop began to emerge from the soil, in the form of a Unix timestamp. *Required if plant_date is not provided.

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.

previous_crop

string

no

no

Enumeration value of previous crop on field. Accepted values: 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), 74 (alfalfa).

previous_harvest_date

timestamp

no

no

Date that the previous crop was harvested in the form of a Unix timestamp. 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: "lb/ac", "kg/ha", "bu/ac". Required if previous crop is specified. Note that "bu/ac" is not a valid yield unit for alfalfa, cotton, or vegetable.

year_offset

integer

no

no

Number of years by which to adjust model results. Useful for viewing results from a previous growing season given the exact same input configuration. Values must be less than 0.

use_unconfirmed

flag

no

no

Results in using all fertilizer treatment activities provided, including those where the application rate is undefined. The nitrogen model generates a recommended application rate in this case, with these activities otherwise ignored by default.

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. Recommendation property indicates whether or not the application rate is a recommendation calculated by the nitrogen model.

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 daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

air_temp_min

Minimum daily air temperature in degrees Fahrenheit. Obtained from historical, forecast, or climatological data, depending on the timeframe.

feedback_id

If this parameter is present, it indicates a confirmed or observed growth stage.

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. "n/a" if 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 centimeters. 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.

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

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

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

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

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

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

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

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

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

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

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 "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 "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 desired yield goal.

uptake_score_unit

Units of "uptake_score."

advisor

Suggested field properties to check.

applicable_scales/feekes

Stage equivalent in the Feekes scale.

applicable_scales/haun

Stage equivalent in the Haun scale.

applicable_scales/zadoks

Stage equivalent in the Zadoks scale.

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.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/winter_wheat/nutrient/nitrogen?app_id=456&app_key=789&account_id=123&user_id=xyz-123&growth_id=abc-def&yield_goal=1050&yield_goal_unit=kg/ha&output_unit=kg/ha

Example Response

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

Add Field Soil Sample - v1.1

This endpoint allows a user to add a soil sample. When adding a soil sample, the activity will be automatically added to the field whitelist. While active on the field whitelist for which a target growth resides, the soil sample activity will be used to improve various model/advisor results (e.g., the nitrogen advisor).

URL Description

https://ag.us.clearapis.com/v1.1/crop_health/field/activity/soil_sample/add/{field_id}?account_id={string}&user_id={string}&activity_time={integer}&depth_unit={string}&nitrate_unit={string}&samples={string}&app_id={string}&app_key={string}

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.

field_id

string

yes

Specifies ID of field to which the soil sample pertains.

activity_time

integer

yes

A timestamp in seconds representing the date for which soil sample in the form of a Unix timestamp.

depth_unit

string

yes

The unit associated with the depth. Valid options are "m," "ft," "cm," and "in."

nitrate_unit

string

*

This value can be "lb/ac" or "kg/ha." (This is not case sensitive, but is stored as lowercase). *If nitrate_unit is included then nitrate is required in at least one sample.

samples

string

yes

A list of tuples containing one or more soil samples at different depths. Must be formatted: [(<start_depth>, <nitrate>, <ph>, <organic matter>), …​]. Start_depth is required, and at least one of nitrate, ph, and/or organic_matter must be included. Null is a valid value for nitrate, ph, and/or organic so long as at least one of these has a valid value. *If nitrate is included in any sample then nitrate_unit is required.

Response Object

A string representing a feedback ID.

Example Request

https://ag.us.clearapis.com/v1.1/crop_health/field/activity/soil_sample/add/bcd-def?account_id=abc&user_id=def&activity_time=1494522939&depth_unit=m&nitrate_unit=lb/ac&samples=[(0,2,6,67)]&app_id=123&app_key=321

Example Response

def-345

Modify Field Soil Sample - v1.1

The Modify Field Soil Sample endpoint allows users to modify an existing soil sample.

URL Description

https://ag.us.clearapis.com/v1.1/crop_health/field/activity/soil_sample/modify/{field_id}?account_id={string}&user_id={string}&activity_time={integer}&depth_unit={string}&nitrate_unit={string}&samples={string}&app_id={string}&app_key={string}

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.

field_activity_id

string

yes

Specifies ID of the given field activity.

depth_unit

string

no

The unit associated with the depth. Valid options are "m," "ft," "cm," and "in."

nitrate_unit

string

*

This value can be "lb/ac" or "kg/ha." (This is not case sensitive, but is stored as lowercase). *If nitrate_unit is included then nitrate is required in at least one sample.

samples

string

no

A list of tuples containing one or more soil samples at different depths. Must be formatted: [(<start_depth>, <nitrate>, <ph>, <organic matter>), …​]. Start_depth is required, and at least one of nitrate, ph, and/or organic_matter must be included. Null is a valid value for nitrate, ph, and/or organic so long as at least one of these has a valid value. *If nitrate is included in any sample then nitrate_unit is required.

Response Object

Returns "true" on success.

Example Request

https://ag.us.clearapis.com/v1.1/crop_health/field/activity/soil_sample/modify/bcd-def?account_id=abc&user_id=def&activity_time=1494522939&nitrate_unit=lb/ac&app_id=123&app_key=321

Example Response

true

Get Field Soil Sample - v1.1

This endpoint allows users to receive a soil sample.

Please note that v1.1 is backward compatible with v1.0 soil_sample activities such that when working in v1.1, any available v1.0 samples will also show. If working in v1.0, however, v1.1 samples will not show. The outputs will be formatted as outlined below.

URL Description

https://ag.us.clearapis.com/v1.1/crop_health/field/activity/soil_sample/get/{field_activity_id}?app_id={string}&app_key={string}&account_id={string}&user_id={string}

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.

field_activity_id

string

yes

Specifies ID of the given field activity.

Response Object (JSON)

Field Description

field_activity_id

ID of soil_sample activity.

created

Time of sample creation.

activity_type

Enumeration value representing the type of activity performed.

activity_time

The time the activity was performed. Defaults to current time.

modified

Time of last modification.

start_depth

Starting depth of soil sample.

depth_unit

Unit for depth.

nitrate_unit

Unit for nitrate measurement.

samples

A list of tuples containing one or more soil samples at different depths. Formatted like: [[<start_depth>, <nitrate>, <ph>, <organic matter>], …​].

Example Request

https://ag.us.clearapis.com/v1.1/crop_health/field/activity/soil_sample/get/abc-def?app_id=123&app_key=321&account_id=123&user_id=xyz-123

Example Response

{
    "field_activity_id":"abc-def",
    "depth_unit":"in",
    "created":1530114568,
    "modified":1530117741,
    "subtype":0,
    "samples":[
        [
            4.124,
            null,
            4.4,
            8
        ],...
    ],
    "activity_time":1436918400,
    "nitrate_unit":"lb/ac",
    "activity_type":307
}

Get Field Soil Samples by Field - v1.1

This endpoint allows for a user to receive all soil samples associated with a given field.

Please note that v1.1 is backward compatible with v1.0 soil_sample activities such that when working in v1.1, any available v1.0 samples will also show. If working in v1.0, however, v1.1 samples will not show. The outputs will be formatted as outlined below.

URL Description

https://ag.us.clearapis.com/v1.1/crop_health/field/activity/soil_sample/get/by_field/{field_id}?app_id={string}&app_key={string}&account_id={string}&user_id={string}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_id

string

yes

Specifies ID of field.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

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

Response Object (JSON)

Field Description

field_activity_id

ID of soil_sample activity.

created

Time of sample creation.

activity_type

Enumeration value representing the type of activity performed.

activity_time

The time the activity was performed. Defaults to current time.

modified

Time of last modification.

start_depth

Starting depth of soil sample.

depth_unit

Unit for depth.

nitrate_unit

Unit for nitrate measurement.

samples

A list of tuples containing one or more soil samples at different depths. Formatted like: [[<start_depth>, <nitrate>, <ph>, <organic matter>], …​].

whitelist

Boolean value which denotes membership in field’s whitelist.

Example Request

https://ag.us.clearapis.com/v1.1/crop_health/field/activity/soil_sample/get/by_field/abc-123?app_id=123&app_key=321&account_id=123&user_id=xyz-123

Example Response

[{
    "field_activity_id":"abc-def",
    "depth_unit":"in",
    "whitelist":true,
    "created":1529988456,
    "modified":null,
    "subtype":0,
    "samples":[
        [
            0,
            2,
            6,
            67
        ],...
    ],
    "activity_time":1436918400,
    "nitrate_unit":"lb/ac",
    "activity_type":307
},...]

Get Field Soil Sample By Growth - v1.1

Receive a previously created growth, based on growth_id.

Please note that v1.1 is backward compatible with v1.0 soil_sample activities such that when working in v1.1, any available v1.0 samples will also show. If working in v1.0, however, v1.1 samples will not show. The outputs will be formatted as outlined below.

URL Description

https://ag.us.clearapis.com/v1.1/crop_health/field/activity/soil_sample/get/by_growth/{growth_id}?app_id={string}&app_key={string}&account_id={string}&user_id={string}

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 ID of crop growth to be queried from the user information database, provided by the Create Growth endpoint.

Response Object (JSON)

Field Description

field_activity_id

ID of soil_sample activity.

created

Time of sample creation.

activity_type

Enumeration value representing the type of activity performed.

activity_time

The time the activity was performed. Defaults to current time.

modified

Time of last modification.

start_depth

Starting depth of soil sample.

depth_unit

Unit for depth.

nitrate_unit

Unit for nitrate measurement.

samples

A list of tuples containing one or more soil samples at different depths. Formatted like: [[<start_depth>, <nitrate>, <ph>, <organic matter>], …​].

whitelist

Boolean value which denotes membership in field’s whitelist.

Example Request

https://ag.us.clearapis.com/v1.1/crop_health/field/activity/soil_sample/get/by_growth/456-789?app_id=123&app_key=321&account_id=123&user_id=xyz-123

Example Response

[{
    "field_activity_id":"abc-def",
    "depth_unit":"in",
    "whitelist":true,
    "created":1529988456,
    "modified":null,
    "subtype":0,
    "samples":[
        [
            0,
            2,
            6,
            67
        ],...
    ],
    "activity_time":1436918400,
    "nitrate_unit":"lb/ac",
    "activity_type":307
},...]

Add Fertilizer Treatment - v1.0

This endpoint allows the user to add a field activity (fertilizer treatment) to a field. Upon creation, fertilizer treatment activities are automatically added to the target fields' whitelist.

URL Description

https://ag.us.clearapis.com/v1.0/crop_health/field/activity/fertilizer_treatment/
add/{field_id}/?app_id={string}&app_key={string}&account_id={string}
&user_id={string}&fertilizer_id={integer}&rate={float}&rate_unit={string}
&depth={float}&depth_unit={string}&growth_ids={string}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_id

string

yes

Specifies ID of field in which the activity is being applied.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

This ID is provided as a result of creating a new user.

fertilizer_id

integer

yes

Enumeration value representing the type of fertilizer.4

rate

float or null

no

The amount of fertilizer used in the application. If rate is set to null, the fertilizer treatment activity will be used for the recommendation feature in the nitrogen. Only one fertilizer treatment activity with a rate of “null” exist per day.

rate_unit

string

yes

The unit associated with the rate of application.4

depth

float

yes

The depth at which the application was applied.

depth_unit

string

yes

The unit associated with the depth. Valid options are “m,” “ft,” “cm,” and “in.”

activity_time

timestamp

no

The time the activity was performed in the form of a Unix timestamp. Defaults to current time.

confirmed

boolean

no

Value of “true” indicates that this activity will be considered during other model runs. A value of “false” indicates that this activity will only be considered during other model runs when a special query string parameter has been set. Default value depends on the value for the query string parameter rate. If rate is a float the default is “true.” If rate is “null” the default is “false.” This can only be set to “false” during the creation of a new fertilizer treatment activity.

growth_ids

string

no

Comma-delimited list of growth IDs. If provided, the fertilizer treatment activity will be added to the whitelist of each growth in the list.

Response Object

Returns the field_activity_id that was created.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/field/activity/fertilizer_treatment/
add/abc-123/?app_id=123&app_key=321&account_id=abf-345&user_id=bcd-678
&fertilizer_id=13&rate=1.0&rate_unit=lb/ac&depth=1&depth_unit=in

Example Response

def-345

Modify Fertilizer Treatment - v1.0

This endpoint allows the user to modify an existing fertilizer treatment activity.

URL Description

https://ag.us.clearapis.com/v1.0/crop_health/
field/activity/fertilizer_treatment/modify/{field_id}/?
app_id={string}&app_key={string}&account_id={string}
&user_id={string}&rate={float}&rate_unit={string}
&depth={float}&depth_unit={string}
&activity_time={timestamp}&fertilizer_id={integer}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_id

string

yes

Specifies ID of field in which to assign crop growth data.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

This ID is provided as a result of creating a new user.

rate

float

no

The amount of fertilizer used in the application.

rate_unit

string

no

The unit associated with the rate of application. Please refer to the Fertilizer Types section of the Appendix for a complete listing of coded values and their meanings.

depth

float

no

The depth at which the application was applied.

depth_unit

string

no

The unit associated with the depth. Valid options are "m," "ft," "cm," and "in."

activity_time

timestamp

no

The time the activity was performed in the form of a Unix timestamp.

fertilizer_id

integer

no

Enumeration of the fertilizer type used in treatment. Please refer to the Fertilizer Types section of the Appendix for a complete listing of coded values and their meanings.

Response Object

A string representing success ("true") or failure ("false").

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/field/activity/
fertilizer_treatment/modify/abc-123/?app_id=123&app_key=321
&account_id=def-345&user_id=bcd-678&depth_unit=m

Example Response

true

Delete Fertilizer Treatment - v1.0

This endpoint allows the user to delete a fertilizer treatment from a field. The activity will also be removed from the field whitelist and growth whitelist.

URL Description

https://ag.us.clearapis.com/v1.0/crop_health/field/activity/fertilizer_treatment/
delete/{field_activity_id}?app_id={string}&app_key={string}
&account_id={string}&user_id={string}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_activity_id

string

yes

Specifies ID of field activity that is to be deleted.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

This ID is provided as a result of creating a new user.

Response Object

Returns "true" on success.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/field/activity/fertilizer_treatment/
delete/abc-123?app_id=123&app_key=321&account_id=def-345&user_id=bcd-678

Example Response

true

Get All Fertilizer Treatment By Field ID - v1.0

This endpoint allows the user to get all fertilizer treatment activities on a field.

URL Description

https://ag.us.clearapis.com/v1.0/crop_health/field/activity/fertilizer_treatment/
get/by_field/{field_id}/?app_id={string}&app_key={string}&account_id={string}
&user_id={string}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_id

string

yes

Specifies ID of field in which all fertilizer treatment activities are returned.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

This ID is provided as a result of creating a new user.

Response Object (JSON)

Field Description

activity_time

Unix timestamp when the activity occurred.

activity_type

Enumeration value representing the type of activity. This will always be 308 for fertilizer treatments (see Appendix for complete listing of coded values and their meanings).

created

Unix timestamp when the activity was created in the system.

depth

The depth at which the fertilizer was applied.

depth_unit

The unit associated with the depth. Valid options are "m," "ft," "cm," and "in."

fertilizer_id

Enumeration value of the fertilizer used. Please refer to the Fertilizer Types section of the Appendix for a complete listing of coded values and their meanings.

field_activity_id

UUID of the field activity.

modified

Unix timestamp when the activity was modified. This is set to "null" by default.

rate

The amount of fertilizer used in the application. Can be a float or "null."

rate_unit

The unit associated with the rate of application. Please refer to the Fertilizer Types section of the Appendix for a complete listing of coded values and their meanings.

subtype

Subtype of activity. Defaults to 0.

whitelist

Boolean denoting membership of the activity in the field’s whitelist.

confirmed

Used during other model runs. "True" denotes that it will always be considered, and "false" denotes that the activity will only be considered when explicitly requested.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/field/activity/fertilizer_treatment/
get/by_field/abc-123/?app_id=123&app_key=321&account_id=def-345&user_id=bcd-678

Example Response

Returns a list of fertilizer_treatment field_activities.

[{
        "field_activity_id":"abc-123",
        "depth_unit":"in",
        "whitelist":true,
        "rate":3.14159,
        "fertilizer_id":25,
        "confirmed":true,
        "created":1494522940,
        "modified":null,
        "rate_unit":"gal/ac",
        "subtype":0,
        "depth":3,
        "activity_time":1494522939,
        "activity_type":308
    },
    {
        "field_activity_id":"456-def",
        "depth_unit":"in",
        "whitelist":true,
        "rate":null,
        "fertilizer_id":25,
        "confirmed":false,
        "created":1494522940,
        "modified":null,
        "rate_unit":"gal/ac",
        "subtype":0,
        "depth":3,
        "activity_time":1494522939,
        "activity_type":308
    }

]

Get Fertilizer Treatment by Field Activity ID - v1.0

This endpoint allows the user to get one specific fertilizer treatment activity on a field.

URL Description

https://ag.us.clearapis.com/v1.0/crop_health/field/activity/fertilizer_treatment/
get/{field_activity_id}/?app_id={string}&app_key={string}&account_id={string}
&user_id={string}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

activity_id

string

yes

Specifies ID of target activity to get.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

This ID is provided as a result of creating a new user.

Response Object (JSON)

Field Description

activity_time

Unix timestamp when the activity occurred.

activity_type

Enumeration value representing the type of activity. This will always be 308 for fertilizer treatments (see Appendix for complete listing of coded values and their meanings).

created

Unix timestamp when the activity was created in the system.

depth

The depth at which the fertilizer was applied.

depth_unit

The unit associated with the depth. Valid options are "m," "ft," "cm," and "in."

fertilizer_id

Enumeration value of the fertilizer used. Please refer to the Fertilizer Types section of the Appendix for a complete listing of coded values and their meanings.

field_activity_id

UUID of the field activity.

modified

Unix timestamp when the activity was modified. This is set to "null" by default.

rate

The amount of fertilizer used in the application. Can be a float or "null."

rate_unit

The unit associated with the rate of application. Please refer to the Fertilizer Types section of the Appendix for a complete listing of coded values and their meanings.

subtype

Subtype of activity. Defaults to 0.

confirmed

Used during other model runs. "True" denotes that it will always be considered, and "false" denotes that the activity will only be considered when explicitly requested.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/field/activity/fertilizer_treatment/
get/abc-123/?app_id=123&app_key=321&account_id=def-345&user_id=bcd-678

Example Response

{
    "field_activity_id":"abc-123",
    "depth_unit":"in",
    "rate":null,
    "fertilizer_id":25,
    "confirmed":false,
    "created":1494522940,
    "modified":null,
    "rate_unit":"gal/ac",
    "subtype":0,
    "depth":3,
    "activity_time":1494522939,
    "activity_type":308
}

Appendix

Common HTTP response codes

The following are common HTTP response codes and their meanings. These are standard across all API services.

  • 200 OK - The request was successful.

  • 400 Bad Request - The request was invalid. An accompanying error message will be provided if available.

  • 401 Unauthorized - Authentication to the API has failed. Authentication credentials are missing or incorrect.

  • 403 Forbidden - You are trying to access a resource for which you do not have the appropriate privileges.

  • 404 Not found - The requested resource was not found. An accompanying error message will be provided if available.

  • 500 Internal Server Error - An internal server error has occurred while processing the request.

  • 502 Bad Gateway - The service is not reachable.

Null or Empty Values

In some cases values will be represented as "n/a." This indicates that the requested data is not available or is not applicable.

Unix Timestamp

Iteris employs Unix timestamps for some time-based parameters. Unix timestamps are defined as the number of seconds since 1970-01-01 00:00 Coordinated Universal Time (UTC), and are an absolute and universal measure of time, independent of timezones. For example, when the current Unix time is 1457543400, it is 1457543400 everywhere, whether it is the middle of the night or middle of the day at any particular location on Earth.

When requesting hourly or sub-hourly data, the use of Unix timestamps is straightforward. Simply convert the desired date/time/timezone into its corresponding Unix timestamp, and pass the resulting value in via the URL associated with the API request. For instance, if you wish to retrieve hourly data for the period spanning 2001-03-09 12:00 Central Standard Time (CST) to 2001-03-10 12:00 CST, you would pass in Unix timestamps of 984160800 and 984247200, respectively.

When requesting daily data, however, the use of Unix timestamps is less straightforward. Ideally, the Unix timestamps provided would be evaluated in the timezone of the requested location in order to interpret the date ranges desired from the request. However, since many of Iteris’ API endpoints permit requesting data for many different locations in a single query, the timezone may vary between the different locations included in the query. If the Unix timestamps were evaluated in the local timezone of each of the query locations, there would be instances when the data returned would be for a date range that is shifted by a day between the different locations, which is generally an undesirable behavior. For example, while 984160800 evaluates to 2001-03-09 in Central Standard Time (CST; which is equivalent to UTC-6), it evaluates to 2001-03-10 in New Zealand (UTC+12).

Because of this, when Unix timestamps are used in queries for daily data, the method employed by Iteris is to do all conversions between Unix timestamps and year/month/day assuming the timezone is UTC (equivalent to UTC+0). If you desire daily data for 2001-03-09, you must pass in a Unix timestamp that falls within the range 984096000 (corresponding to 2001-03-09 00:00 UTC) and 984182399 (2001-03-09 23:59:59 UTC). It is generally easiest to find an appropriate Unix timestamp by just converting the date/time/timezone string of “YYYY-MM-DD 00:00 UTC” replacing the year (YYYY), month (MM), and day (DD) as desired. If you wish for any particular date to be included, the Unix timestamps provided for the start and end of the query must encapsulate that date when evaluated in the UTC+0 timezone.

It is important to note that while the system Iteris employs for converting Unix timestamps in query URLs into the associated date ranges operates under the assumption of a UTC+0 timezone for daily data requests, the data that are returned from the requests are aligned to midnight-to-midnight local time in the timezone of each location contained in the request. For example, if locations in the Central and Mountain timezones of the United States are included in the same request, the data from locations falling in the Central timezone would be valid for the period spanning midnight-to-midnight CST (Central Standard Time), while the data from locations falling in the Mountain timezone would be valid for the period spanning midnight-to-midnight MST (Mountain Standard Time). Thus, if one were to create any sort of spatial display of data returned from Iteris’ daily data endpoints, the boundaries between timezones may be evident (for instance if rain fell in the hour prior to midnight immediately on the west side of the timezone boundary, while it fell in the hour following midnight immediately on the east side of the timezone boundary).

Regional-based Account Access

Any data stored by the Account API in one region is not available in another. Each region will require a unique set of credentials. Please contact your account representative if interested in utilizing an additional region. When attempting to use the credentials from one region with the services in another, an 'account not found' error will be returned with HTTP status code 400. See example below:

<title>400 Bad Request</title>
<h1>Bad Request</h1>
<p>Account not found.</p>

Supported Crops by Feature

Crop Type Growth Model Growth Model Feedback Growth GDD Envelope Nutrient (Nitrogen) Modeling Harvest (Drydown) Modeling Focus Soil Conditions IMFocus Irrigation

Barley

X

X

X

X

X

Bermuda Turfgrass

X

X

X

Canola

X

X

X

X

X

X

X

Corn

X

X

X

X

X

X

X

Cotton

X

X

X

X

X

X

Peanut

X

Potato

X

X

X

Sorghum

X

X

X

X

X

X

Soybean

X

X

X

X

X

X

Spring wheat

X

X

X

X

X

X

X

Sugar Beet

X

X

X

Sunflower

X

X

X

X

Winter Wheat

X

X

X

X

X

X

X

Zoysia Turfgrass

X

X

X

Activity Enumerations

Activity Type

Coded Value Meaning

300

Planting

301

Spraying

302

Harvesting

303

Row Crop Cultivating

304

Post-harvest Tillage

305

Pre-planting Tillage

306

Cutting

307

Soil Test

308

Fertilizer Treatment

309

Grain Moisture Test

310

Scouting Report

311

Irrigation

Activity Subtype

Activity Type Subtype Code Meaning

Planting

0

Generic

Planting

50

Barley

Planting

51

Corn

Planting

57

Spring Wheat

Planting

59

Canola

Planting

60

Sugar Beets

Planting

65

Cotton

Spraying

0

Generic

Harvesting

0

Generic

Row Crop Cultivating

0

Generic

Post-harvest Tillage

0

Generic

Pre-planting Tillage

0

Generic

Cutting

0

Generic

Cutting

1

Alfalfa

Soil Test

0

Generic

Fertilizer Treatment

0

Generic

Grain Moisture Test

0

Generic

Scouting Report

0

Generic

Irrigation

0

Generic

Fertilizer Types

ID Name Type Units N P K Ca Mg S

1

Ammonium nitrate 34 0 0 0 0 0

solid

kg/ha, lb/ac

0.34

0

0

0

0

0

2

Ammonium phosphate sulfate 16 20 0 0 0 13

solid

kg/ha, lb/ac

0.16

0.2

0

0

0

0.13

3

Ammonium polyphosphate granular 11 57 0 0 0 0

solid

kg/ha, lb/ac

0.11

0.57

0

0

0

0

4

Ammonium sulfate 21 0 0 0 0 24

solid

kg/ha, lb/ac

0.21

0

0

0

0

0.24

5

Ammonium nitrate sulfate 30 0 0 0 0 6.5

solid

kg/ha, lb/ac

0.3

0

0

0

0

0.6

6

Calcium ammonium nitrate 27 0 0 0 0 0

solid

kg/ha, lb/ac

0.27

0

0

0

0

0

7

Calcium carbonate 0 0 0 40 0 0

solid

kg/ha, lb/ac

0

0

0

0.4

0

0

8

Calcium nitrate 15.5 0 0 19 0 0

solid

kg/ha, lb/ac

.15.5

0

0

0.19

0

0

9

Calcium oxide 0 0 0 71.5 0 0

solid

kg/ha, lb/ac

0

0

0

0.715

0

0

10

Diammonium phosphate 18 46 0 0 0 0

solid

kg/ha, lb/ac

0.18

0.46

0

0

0

0

11

Diammonium phosphate 21 53 0 0 0 0

solid

kg/ha, lb/ac

0.21

0.53

0

0

0

0

12

Monoammonium phosphate 11 52 0 0 0 0

solid

kg/ha, lb/ac

0.11

0.52

0

0

0

0

13

Potassium chloride 0 0 60 0 0 0

solid

kg/ha, lb/ac

0

0

0.6

0

0

0

14

Potassium nitrate 13 0 44 0 0 0

solid

kg/ha, lb/ac

0.13

0

0.44

0

0

0

15

Potassium sulfate 0 0 50 0 0 18

solid

kg/ha, lb/ac

0

0

0.5

0

0

0.18

16

Single super phosphate 0 18 0 16 0 8

solid

kg/ha, lb/ac

0

0.18

0

0.16

0

0.8

17

Sodium nitrate 16.5 0 0 0 0 0

solid

kg/ha, lb/ac

.16.5

0

0

0

0

0

18

Triple super phosphate 0 48 0 0 0 0

solid

kg/ha, lb/ac

0

0.48

0

0

0

0

19

Urea 46 0 0 0 0 0

solid

kg/ha, lb/ac

0.46

0

0

0

0

0

20

Ammonium phosphate liquid 10 34 0 0 0 0

liquid

l/ha, gal/ac

0.1

0.34

0

0

0

0

21

Ammonium polyphosphate fluid 10 34 0 0 0 0

liquid

l/ha, gal/ac

0.1

0.34

0

0

0

0

22

Ammonium polyphosphate fluid 10 37 0 0 0 0

liquid

l/ha, gal/ac

0.1

0.37

0

0

0

0

23

Anhydrous ammonia 82 0 0 0 0 0

liquid

kg/ha, lb/ac

0.82

0

0

0

0

0

24

Aqua ammonia 20 0 0 0 0 0

liquid

l/ha, gal/ac

0.2

0

0

0

0

0

25

Calcium ammonium nitrate liquid (17 0 0 8)

liquid

l/ha, gal/ac

0.17

0

0

0.88

0

0

26

Phosphoric acid 0 30 0 0 0 0

liquid

l/ha, gal/ac

0

0.3

0

0

0

0

27

Phosphoric acid 0 54 0 0 0 0

liquid

l/ha, gal/ac

0

0.54

0

0

0

0

28

Phosphoric acid 0 65 0 0 0 0

liquid

l/ha, gal/ac

0

0.65

0

0

0

0

29

Super phosphoric acid liquid 0 68 0 0 0 0

liquid

l/ha, gal/ac

0

0.68

0

0

0

0

30

Urea ammonium nitrate 32 0 0 0 0 0

liquid

l/ha, gal/ac

0.32

0

0

0

0

0

31

Microessentials sz 12 40 0 0 0 10

solid

kg/ha, lb/ac

0.12

0.4

0

0

0

0.1

32

Microessentials s10 12 40 0 0 0 10

solid

kg/ha, lb/ac

0.1

0.12

0.4

0

0

0.1

33

Microessentials s15 13 33 0 0 0 15

solid

kg/ha, lb/ac

0.15

0.13

0.33

0

0

0.15

34

Urea ammonium nitrate 28 0 0 0 0 0

liquid

l/ha, gal/ac

0.28

0

0

0

0

0

35

Urea ammonium nitrate 30 0 0 0 0 0

liquid

l/ha, gal/ac

0.3

0

0

0

0

0

Changelog

This section describes document changes occurring in the two most recent versions.

3/21/19

Updated the Field Soil Sample endpoints with v1.1.

3/18/19

Updates made to improve parameter descriptions throughout, as well as revisions to example URLs.