ClearAg

ClearAg Indices

The ClearAg Indices form a suite of APIs that leverage big data and robust weather, soil, and agronomic modeling to provide a simple yet powerful analysis of environmental conditions impacting things such as crop yield, disease risk, and crop chemical applications.

ClearAg Indices

last updated 1/6/20

Welcome to the ClearAg Indices API guide. The ClearAg Indices form a suite of APIs that leverage big data and robust weather, soil, and agronomic modeling to provide a simple yet powerful analysis of environmental conditions impacting things such as crop yield, disease risk, and crop chemical applications. All of the Index APIs are documented below.

Most of the Index API endpoints require Accounts API integration. To use such endpoints, clients must first contact an Iteris account representative to set up an account, and then set up a user and field with the Accounts API, and a growth with the applicable Growth Creation endpoint as necessary.

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.

Daily Powdery Mildew Risk - v1.0

The Daily Powdery Mildew Risk endpoint provides a daily 0-100 rating of conditions impacting powdery mildew development on a crop, where zero represents a very low risk of challenging conditions and 100 represents a very high risk. Risks associated with weather conditions and growth stage are independently assessed in order to generate an overall score.

URL Description

https://ag.us.clearapis.com/v1.0/indices/powdery_mildew_risk/daily/{crop}?app_id={string}&app_key={string}&account_id={string}&user_id={string}&growth_id={string}&start_date={string}&end_date={string}&unitcode={string}

Request Parameters

Parameter Type Required Description

crop

string

yes

Crop type for which to generate results. Supported values: "preset_grape_table," "preset_grape_wine."

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

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

growth_id

string

yes

Growth ID provided by the Growth Creation endpoint. The growth must be consistent with the chosen crop type.

start_date

string

yes

Start of time window over which to assess powdery mildew risk, in the format YYYY-MM-DD.

end_date

string

yes

End of time window over which to assess powdery mildew risk, in the format YYYY-MM-DD.

unitcode

string

no

Unit conversion set to be used. Default is "us-std." Valid values are "us-std," "si-std," "us-std-precise," and "si-std-precise." When "precise" is not set, the output will be rounded to an appropriate level of precision for the parameter. Additional information is available in the Parameter Units section of the Appendix.

Response Object (JSON)

Field Description

auxiliary_info

Container for supporting information or data.

auxiliary_info/
current_period

Container for data valid on the current date.

current_period/
air_temp_avg

Average daily air temperature at two meters above ground level.

current_period/
last_stage

Previous growth stage reached.

current_period/
new_stage

Growth stage reached on the current date. Returns "n/a" if a new stage is not reached.

current_period/
relative_humidity_avg

Average daily relative humidity at two meters above ground level.

index

Overall risk of powdery mildew on a scale of zero to 100, with zero representing a very low risk of challenging conditions and 100 representing a very high risk.

subindex

Container for subindices.

subindex/
current_weather

Current weather subindex. This indicates the conduciveness of weather conditions to powdery mildew development.

subindex/
growth_stage

Growth stage subindex. This represents susceptibility to powdery mildew associated with the current growth stage.

errors

Container for any errors encountered.

units

Container for units of measure.

units/
air_temp_avg

Average daily air temperature unit.

units/
relative_humidity_avg

Average daily relative humidity unit.

Example Request

https://ag.us.clearapis.com/v1.0/indices/powdery_mildew_risk/daily/preset_grape_wine?app_id=123&app_key=321&account_id=abc&user_id=xyz-123&growth_id=abc-def&start_date=2019-05-01&end_date=2019-05-31

Example Response

{
    "data":{
        "47,-97":{
            "2019-05-01":{
                "auxiliary_info":{
                    "current_period":{
                        "air_temp_avg":75.0,
                        "last_stage":"5",
                        "new_stage":"0",
                        "relative_humidity_avg":79.0
                    }
                },
                "index":69.0,
                "subindex":{
                    "current_weather":69.0,
                    "growth_stage":100.0
                }
            }, ...
        }
    },
    "errors":{},
    "units":{
        "air_temp_avg":"F",
        "relative_humidity_avg":"%"
    }
}

Emergence Risk - v1.0

The Emergence Risk index is a 0-100 rating of environmental conditions impacting emergence of a user-specified growth, where zero represents a very low risk of challenging conditions and 100 represents a very high risk. Risks of imbibitional chilling, cold soil temperatures, large swings in soil temperatures, seedling disease, and crusting are independently assessed in order to generate an overall score.

URL Description

https://ag.us.clearapis.com/v1.0/indices/emergence_risk/{crop}?app_id={string}&app_key={string}&account_id={string}&user_id={string}&growth_id={string}

Request Parameters

Parameter Type Required Description

crop

string

yes

Crop type for which to generate results. Supported values: "corn."

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

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

growth_id

string

yes

Growth ID provided by the Growth Creation endpoint. The growth must be consistent with the chosen crop type. The plant_date growth property must be defined in order for the algorithm to identify conditions occurring between planting and the simulated emergence date.

Response Object (JSON)

Field Description

auxiliary_info

Container for supporting information or data.

auxiliary_info/
emergence_date

Date that the crop began to emerge from the soil as estimated by the simulation.

auxiliary_info/
plant_date

User-provided date that the crop was planted.

index

Overall risk to emergence on a scale of zero to 100, with zero representing a very low risk of challenging conditions and 100 representing a very high risk.

subindex

Container for subindices.

subindex/
crusting

Crusting subindex. This represents the risk of crusting at the soil surface due to rainfall events between planting and emergence.

subindex/
imbibitional_chilling

Imbibitional chilling subindex. This represents the risk associated with a seed imbibing cold water.

subindex/
seedling_disease

Seedling disease subindex. This represents the risk associated with the length of time between planting and emergence, with longer time to emergence resulting in a higher risk of seedling disease.

subindex/
soil_temperature

Soil temperature subindex. This represents the risk that soil temperatures are too cold for optimal emergence.

subindex/
temperature_swing

Temperature swing subindex. This represents the risk associated with dramatic swings in soil temperature during the period between planting and emergence.

errors

Container for any errors encountered.

Example Request

https://ag.us.clearapis.com/v1.0/indices/emergence_risk/corn?app_id=123&app_key=321&account_id=abc&user_id=xyz-123&growth_id=abc-def

Example Response

{
    "data":{
        "47,-97":{
            "auxiliary_info":{
                "emergence_date":"2019-05-22",
                "plant_date":"2019-05-01"
            },
            "index":95.0,
            "subindex":{
                "crusting":0.0,
                "imbibitional_chilling":81.0,
                "seedling_disease":36.0,
                "soil_temperature":46.0,
                "temperature_swing":25.0
            }
        }
    },
    "errors":{}
}

Environmental Conditions - v1.0

The Environmental Conditions index indicates the extent to which environmental conditions deviate from historical norms for a selected time period on a scale of zero to 100, with 50 indicating conditions are about average, 100 indicating conditions are significantly above average, and zero indicating conditions are significantly below average. This index can be calculated for things such as air temperature, dew point, wind speed, soil temperature, and precipitation. (See the complete list here.)

URL Description

https://ag.us.clearapis.com/v1.0/indices/environmental_conditions?app_id={string}&app_key={string}&location={lat,loncoordinates}&start_date={string}&end_date={string}&reference_start_year={string}&reference_end_year={string}&variable={string}&unitcode={string}&verbose

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

Lat-lon coordinates in decimal degrees. Only one location may be provided.

start_date

string

yes

Start of date range to compare against a climatological average. Format is: YYYY-MM-DD. Earliest allowed is 1980-01-01; latest allowed is <current date> - one day. Date range cannot exceed 100 days.

end_date

string

yes

End of date range to compare against a climatological average. Format is: YYYY-MM-DD. Earliest allowed is 1980-01-01; latest allowed is <current date> - one day. Date range cannot exceed 100 days.

reference_start_year

string

yes

Start of year range for calculating a climatological average. Range must be at least five years in length but cannot exceed 30 years. May not predate 1980. Actual date range used for each year begins with the month and day as defined by the start date argument, and may not exceed <current date> - one day.

reference_end_year

string

yes

End of year range for calculating a climatological average. Range must be at least five years in length but cannot exceed 30 years. May not predate 1980. Actual date range used for each year begins with the month and day as defined by the start date argument, and may not exceed <current date> - one day.

variable

string

yes

The environmental variable for which to calculate results. Supported values are listed in the Variable Enumerations section of the Appendix.

unitcode

string

no

Unit conversion set to be used. Default is "us-std." Valid values are "us-std," "si-std," "us-std-precise," and "si-std-precise." When "precise" is not set, the output will be rounded to an appropriate level of precision for the parameter. Additional information is available in the Parameter Units section of the Appendix.

verbose

flag

no

Display detailed response, including yearly values.

Response Object (JSON)

Field Description

auxiliary_info

Container for supporting information or data.

auxiliary_info/
environmental_data

Container for data from all years in reference and target periods. Only appears if verbose option is set.

environmental_data/
accumulation

Period sum of daily values. Filled with data for variables "13" (daily total precipitation), "29" (daily total reference evapotranspiration), and "40" through "48" (daily total soil moisture flux).

environmental_data/
average

Period average of daily values. Filled with data for all variables except "13," "29," and "40" through "48."

environmental_data/
end_date

Period end date.

environmental_data/
maximum

Period maximum of daily values.

environmental_data/
minimum

Period minimum of daily values.

environmental_data/
start_date

Period start date.

auxiliary_info/
reference_period

Container for reference period data.

reference_period/
average

Reference period average. This is the average of the sums or averages from all of the reference period years in the "environmental_data" section.

reference_period/
stddev

Reference period standard deviation. This is the standard deviation of the sums or averages from all of the reference period years in the "environmental_data" section.

auxiliary_info/
target_period

Container for target period data.

target_period/
accumulation

Target period sum of daily values. Filled with data for variables "13" (daily total precipitation), "29" (daily total reference evapotranspiration), and "40" through "48" (daily total soil moisture flux).

target_period/
average

Target period average of daily values. Filled with data for all variables except "13," "29," and "40" through "48."

target_period/
maximum

Target period maximum of daily values.

target_period/
minimum

Target period minimum of daily values.

target_period/
z-score

Z-score of target period average or accumulation. Indicates the number of standard deviations away that the target period value is from the reference period average.

index

Indicates how similar the target period average or accumulation is to the reference period average, with 50 indicating that the target period value is about the same, 100 indicating it is significantly greater, and zero indicating it is significantly less.

errors

Container for any errors encountered.

units

Container for units of measure.

units/
accumulation

Accumulation unit.

units/
average

Average unit.

units/
maximum

Maximum unit.

units/
minimum

Minimum unit.

units/
stddev

Standard deviation unit.

Example Request

https://ag.us.clearapis.com/v1.0/indices/environmental_conditions?app_id=123&app_key=321&location=47,-97&start_date=2019-05-01&end_date=2019-05-31&reference_start_year=1980&reference_end_year=2009&verbose&variable=0

Example Response

{
    "data":{
        "47,-97":{
            "auxiliary_info":{
                "environmental_data":{
                    "1980":{
                        "accumulation":"n/a",
                        "average":63.0,
                        "end_date":"1980-05-31",
                        "maximum":77.0,
                        "minimum":38.0,
                        "start_date":"1980-05-01"
                    }, ...
                },
                "reference_period":{
                    "average":58.0,
                    "stddev":3.2
                },
                "target_period":{
                    "accumulation":"n/a",
                    "average":53.0,
                    "maximum":75.0,
                    "minimum":40.0,
                    "z-score":-1.41
                }
            },
            "index":22.0
        }
    },
    "errors":{},
    "units":{
        "accumulation":"n/a",
        "average":"F",
        "maximum":"F",
        "minimum":"F",
        "stddev":"F"
    }
}

Field Accessibility - v1.0

The Field Accessibility endpoint leverages Iteris' weather and soil data to simulate field conditions for the next hour and quantify field accessibility on a 0-100 scale, with zero indicating very poor conditions and the field likely inaccessible to equipment, and 100 indicating very good conditions.

URL Description

https://ag.us.clearapis.com/v1.0/indices/field_accessibility?app_id={string}&app_key={string}&account_id={string}&user_id={string}&field_id={string}&unitcode={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

A unique account ID provided by your Iteris account representative.

user_id

string

yes

User ID provided by the Accounts API.

field_id

string

yes

Field ID provided by the Accounts API.

unitcode

string

no

Unit conversion set to be used. Default is "us-std." Valid values are "us-std," "si-std," "us-std-precise," and "si-std-precise." When "precise" is not set, the output will be rounded to an appropriate level of precision for the parameter. Additional information is available in the Parameter Units section of the Appendix.

Response Object (JSON)

Field Description

auxiliary_info

Container for supporting information or data.

auxiliary_info/
environmental_data

Container for environmental conditions impacting field accessibility.

environmental_data/
pet_last_24hr

Total reference evapotranspiration of the last 24 hours, calculated using the FAO-56 grass formulation. Reference evapotranspiration is the amount of water that would transpire and evaporate from a hypothetical reference crop, assuming ample water is available.

environmental_data/
pet_last_48hr

Total reference evapotranspiration of the last 48 hours.

environmental_data/
precip_acc_last_24hr

Total liquid-equivalent precipitation of the last 24 hours.

environmental_data/
precip_acc_last_48hr

Total liquid-equivalent precipitation of the last 48 hours.

environmental_data/
soil_moisture_0to2cm

Volumetric water content of the soil between the surface and the 2-cm depth.

environmental_data/
soil_moisture_2to5cm

Volumetric water content of the soil between the 2- and 5-cm depths.

environmental_data/
soil_moisture_5to10cm

Volumetric water content of the soil between the 5- and 10-cm depths.

environmental_data/
soil_moisture_10to20cm

Volumetric water content of the soil between the 10- and 20-cm depths.

environmental_data/
soil_moisture_20to40cm

Volumetric water content of the soil between the 20- and 40-cm depths.

environmental_data/
soil_moisture_0to40cm

Volumetric water content of the soil between the surface and the 40-cm depth.

environmental_data/
soil_temp_0to2cm

Temperature of the soil between the surface and the 2-cm depth.

environmental_data/
soil_temp_2to5cm

Temperature of the soil between the 2- and 5-cm depths.

environmental_data/
soil_temp_5to10cm

Temperature of the soil between the 5- and 10-cm depths.

environmental_data/
soil_temp_10to20cm

Temperature of the soil between the 10- and 20-cm depths.

environmental_data/
soil_temp_20to40cm

Temperature of the soil between the 20- and 40-cm depths.

environmental_data/
soil_temp_40to70cm

Temperature of the soil between the 40- and 70-cm depths.

environmental_data/
soil_temp_70to100cm

Temperature of the soil between the 70- and 100-cm depths.

environmental_data/
soil_temp_100to200cm

Temperature of the soil between the 100- and 200-cm depths.

index

Field accessibility on a scale of zero to 100, with zero representing poor field conditions and 100 representing good conditions.

errors

Container for any errors encountered.

units

Container for units of measure.

units/
pet_last_24hr

24-hour reference evapotranspiration unit.

units/
pet_last_48hr

48-hour reference evapotranspiration unit.

units/
precip_acc_last_24hr

24-hour precip accumulation unit.

units/
precip_acc_last_48hr

48-hour precip accumulation unit.

units/
soil_moisture_0to2cm

0-2 cm soil moisture unit.

units/
soil_moisture_2to5cm

2-5 cm soil moisture unit.

units/
soil_moisture_5to10cm

5-10 cm soil moisture unit.

units/
soil_moisture_10to20cm

10-20 cm soil moisture unit.

units/
soil_moisture_20to40cm

20-40 cm soil moisture unit.

units/
soil_moisture_0to40cm

0-40 cm soil moisture unit.

units/
soil_temp_0to2cm

0-2 cm soil temperature unit.

units/
soil_temp_2to5cm

2-5 cm soil temperature unit.

units/
soil_temp_5to10cm

5-10 cm soil temperature unit.

units/
soil_temp_10to20cm

10-20 cm soil temperature unit.

units/
soil_temp_20to40cm

20-40 cm soil temperature unit.

units/
soil_temp_40to70cm

40-70 cm soil temperature unit.

units/
soil_temp_70to100cm

70-100 cm soil temperature unit.

units/
soil_temp_100to200cm

100-200 cm soil temperature unit.

Example Request

https://ag.us.clearapis.com/v1.0/indices/field_accessibility?app_id=123&app_key=321&account_id=abc&user_id=xyz-123&field_id=aaa-111

Example Response

{
    "data":{
        "47,-97":{
            "auxiliary_info":{
                "environmental_data":{
                    "1571850000":{
                        "pet_last_24hr":0.04,
                        "pet_last_48hr":0.07,
                        "precip_acc_last_24hr":0.0,
                        "precip_acc_last_48hr":0.04,
                        "soil_moisture_0to2cm":0.4,
                        "soil_moisture_2to5cm":0.4,
                        "soil_moisture_5to10cm":0.4,
                        "soil_moisture_10to20cm":0.39,
                        "soil_moisture_20to40cm":0.37,
                        "soil_moisture_0to40cm":0.38,
                        "soil_temp_0to2cm":39.0,
                        "soil_temp_2to5cm":38.0,
                        "soil_temp_5to10cm":38.0,
                        "soil_temp_10to20cm":40.0,
                        "soil_temp_20to40cm":44.0,
                        "soil_temp_40to70cm":48.0,
                        "soil_temp_70to100cm":50.0,
                        "soil_temp_100to200cm":54.0
                    }
                }
            },
            "index":44.0
        }
    },
    "errors":{},
    "units":{
        "pet_last_24hr":"in",
        "pet_last_48hr":"in",
        "precip_acc_last_24hr":"in",
        "precip_acc_last_48hr":"in",
        "soil_moisture_0to2cm":"ft^3/ft^3",
        "soil_moisture_2to5cm":"ft^3/ft^3",
        "soil_moisture_5to10cm":"ft^3/ft^3",
        "soil_moisture_10to20cm":"ft^3/ft^3",
        "soil_moisture_20to40cm":"ft^3/ft^3",
        "soil_moisture_0to40cm":"ft^3/ft^3",
        "soil_temp_0to2cm":"F",
        "soil_temp_2to5cm":"F",
        "soil_temp_5to10cm":"F",
        "soil_temp_10to20cm":"F",
        "soil_temp_20to40cm":"F",
        "soil_temp_40to70cm":"F",
        "soil_temp_70to100cm":"F",
        "soil_temp_100to200cm":"F"
    }
}

Fusarium Head Blight Risk - v1.0

The Fusarium Head Blight Risk index quantifies the risk of fusarium head blight (FHB) in wheat based on environmental conditions around the time of flowering. Resistance of the wheat variety to FHB may also be specified and used in the calculation. The risk index is given on a 0-100 scale, with zero indicating minimal risk of FHB and 100 indicating high risk.

URL Description

https://ag.us.clearapis.com/v1.0/indices/fhb_risk/{crop}?app_id={string}&app_key={string}&account_id={string}&user_id={string}&growth_id={string}&resistance={string}&unitcode={string}

Request Parameters

Parameter Type Required Description

crop

string

yes

Crop type for which to generate results. Supported values: "springwheat," "winter_wheat."

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

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

growth_id

string

yes

Growth ID provided by the Growth Creation endpoint. The growth must be consistent with the chosen crop type.

resistance

string

no

Resistance to FHB. Valid values include "0" (very susceptible), "1" (susceptible), "2" (moderately susceptible), and "3" (moderately resistant). Default is "0."

unitcode

string

no

Unit conversion set to be used. Default is "us-std." Valid values are "us-std," "si-std," "us-std-precise," and "si-std-precise." When "precise" is not set, the output will be rounded to an appropriate level of precision for the parameter. Additional information is available in the Parameter Units section of the Appendix.

Response Object (JSON)

Field Description

auxiliary_info

Container for supporting information or data.

auxiliary_info/
emergence_date

Date that the crop began to emerge from the soil.

auxiliary_info/
environmental_data

Container for a timeseries of weather data used to compute the index value.

environmental_data/
relative_humidity_avg

Daily average relative humidity.

auxiliary_info/
flowering_date

Date that the flowering stage is reached. (This corresponds to stage "117" for spring wheat and "10" for winter wheat.)

auxiliary_info/
plant_date

Date that the crop was planted.

index

Overall risk of fusarium head blight on a scale of zero to 100, with zero representing a very low risk and 100 representing a very high risk.

errors

Container for any errors encountered.

units

Container for units of measure.

units/
relative_humidity_avg

Daily average relative humidity unit.

Example Request

https://ag.us.clearapis.com/v1.0/indices/fhb_risk/springwheat?app_id=123&app_key=321&account_id=abc&user_id=xyz-123&growth_id=abc-def

Example Response

{
    "data":{
        "47,-97":{
            "auxiliary_info":{
                "emergence_date":"2019-05-18",
                "environmental_data":{
                    "2019-06-17":{
                        "relative_humidity_avg":77.0
                    }, ...
                },
                "flowering_date":"2019-07-05",
                "plant_date":"2019-05-01"
            },
            "index":49.0
        }
    },
    "errors":{},
    "units":{
        "relative_humidity_avg":"%"
    }
}

Grain-fill Stress - v1.0

The Grain-fill Stress index is a 0-100 rating of stress on a crop during grain-fill, where zero indicates minimal stress and 100 indicates very high stress. Damaging drought, heat, and frost stresses are independently assessed in order to generate an overall score.

The time period when grain-fill is expected to occur varies by crop. For corn, this is typically the period between the "R2" and "R6" stages.

URL Description

https://ag.us.clearapis.com/v1.0/indices/grainfill_stress/{crop}?app_id={string}&app_key={string}&account_id={string}&user_id={string}&growth_id={string}&unitcode={string}

Request Parameters

Parameter Type Required Description

crop

string

yes

Crop type for which to generate results. Supported values: "corn."

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

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

yes

Growth ID provided by the Growth Creation endpoint. The growth must be consistent with the chosen crop type.

unitcode

string

no

Unit conversion set to be used. Default is "us-std." Valid values are "us-std," "si-std," "us-std-precise," and "si-std-precise." When "precise" is not set, the output will be rounded to an appropriate level of precision for the parameter. Additional information is available in the Parameter Units section of the Appendix.

Response Object (JSON)

Field Description

auxiliary_info

Container for supporting information or data.

auxiliary_info/
grainfill_period

Container for environmental conditions during grain-fill.

grainfill_period/
abs_scaled_paw_soil_moisture_avg

Grain-fill period average of daily average soil moisture in the root zone, expressed as a scaled value between wilting point (0.0) and field capacity (1.0).

grainfill_period/
abs_scaled_paw_soil_moisture_max

Grain-fill period maximum of daily average soil moisture in the root zone, expressed as a scaled value between wilting point (0.0) and field capacity (1.0).

grainfill_period/
abs_scaled_paw_soil_moisture_min

Grain-fill period minimum of daily average soil moisture in the root zone, expressed as a scaled value between wilting point (0.0) and field capacity (1.0).

grainfill_period/
air_temp_max

Grain-fill period maximum of daily maximum air temperature.

grainfill_period/
air_temp_max_avg

Grain-fill period average of daily maximum air temperature.

grainfill_period/
air_temp_min

Grain-fill period minimum of daily minimum air temperature.

grainfill_period/
air_temp_min_avg

Grain-fill period average of daily minimum air temperature.

grainfill_period/
end_date

Grain-fill period end date.

grainfill_period/
pet_period_avg

Grain-fill period average of daily total reference evapotranspiration, calculated using the FAO-56 grass formulation. Reference evapotranspiration is the amount of water that would transpire and evaporate from a hypothetical reference crop, assuming ample water is available.

grainfill_period/
start_date

Grain-fill period start date.

index

Overall amount of stress on the crop during grain-fill on a scale of zero to 100, with zero representing minimally stressful conditions and 100 representing highly stressful conditions.

subindex

Container for subindices.

subindex/
drought_stress

Drought stress subindex. This represents the amount of stress on the crop owing to dry conditions.

subindex/
frost_stress

Frost stress subindex. This represents the amount of stress on the crop owing to cold conditions.

subindex/
heat_stress

Heat stress subindex. This represents the amount of stress on the crop owing to hot conditions.

errors

Container for any errors encountered.

units

Container for units of measure.

units/
air_temp_max

Maximum of daily maximum air temperature unit.

units/
air_temp_max_avg

Average of daily maximum air temperature unit.

units/
air_temp_min

Minimum of daily minimum air temperature unit.

units/
air_temp_min_avg

Average of daily minimum air temperature unit.

units/
pet_period_avg

Average of daily total reference evapotranspiration unit.

Example Request

https://ag.us.clearapis.com/v1.0/indices/grainfill_stress/corn?app_id=123&app_key=321&account_id=abc&user_id=xyz-123&growth_id=abc-def

Example Response

{
    "data":{
        "47,-97":{
            "auxiliary_info":{
                "grainfill_period":{
                    "abs_scaled_paw_soil_moisture_avg":0.83,
                    "abs_scaled_paw_soil_moisture_max":1.0,
                    "abs_scaled_paw_soil_moisture_min":0.68,
                    "air_temp_max":88.0,
                    "air_temp_max_avg":73.0,
                    "air_temp_min":44.0,
                    "air_temp_min_avg":55.0,
                    "end_date":"2019-09-22",
                    "pet_period_avg":0.11,
                    "start_date":"2019-08-05"
                 }
            },
            "index":0.0,
            "subindex":{
                "drought_stress":0.0,
                "frost_stress":0.0,
                "heat_stress":0.0
            }
        }
    },
    "errors":{},
    "units":{
        "air_temp_max":"F",
        "air_temp_max_avg":"F",
        "air_temp_min":"F",
        "air_temp_min_avg":"F",
        "pet_period_avg":"in"
    }
}

Hourly Desiccant Application Suitability - v1.0

The Hourly Desiccant Application Suitability endpoint provides an hourly 0-100 rating of conditions impacting desiccant application, where zero indicates very unsuitable conditions, and 100 indicates ideal conditions. Weather conditions during and after a potential application, and suitability with respect to growth stage are independently assessed in order to generate an overall score.

URL Description

https://ag.us.clearapis.com/v1.0/indices/desiccant_application_suitability/hourly/{crop}?app_id={string}&app_key={string}&account_id={string}&user_id={string}&growth_id={string}&start_time={timestamp}&end_time={timestamp}&desiccant={string}

Request Parameters

Parameter Type Required Description

crop

string

yes

Crop type for which to generate results. Supported values: "soybean."

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

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

growth_id

string

yes

Growth ID provided by the Growth Creation endpoint. The growth must be consistent with the chosen crop type.

start_time

timestamp

yes

Start of desiccant application time window in the form of a Unix timestamp. May not precede January 1 00:00 UTC of the previous year and may not be more than 72 hours into the future. Time window may not exceed 240 hours.

end_time

timestamp

yes

End of desiccant application time window in the form of a Unix timestamp. May not precede January 1 00:00 UTC of the previous year and may not be more than 72 hours into the future. Time window may not exceed 240 hours.

desiccant

string

no

Brand of desiccant to apply. Currently, only "gramoxone" is supported.

Response Object (JSON)

Field Description

index

Overall suitability of conditions for desiccant application on a scale of zero to 100, with zero representing very unsuitable conditions and 100 representing ideal conditions.

subindex

Container for subindices.

subindex/
current_weather_suitability

Current weather suitability subindex. This represents suitability for desiccant application based on weather conditions at the time of application.

subindex/
future_weather_suitability

Future weather suitability subindex. This represents suitability for desiccant application based on weather conditions for up to 15 days following application.

subindex/
growth_stage_suitability

Growth stage suitability subindex. This represents suitability for desiccant application based on growth stage. For soybean, the ideal time to apply a desiccant is halfway between the "R6" and "R7" stages.

errors

Container for any errors encountered.

Example Request

https://ag.us.clearapis.com/v1.0/indices/desiccant_application_suitability/hourly/soybean?app_id=123&app_key=321&account_id=abc&user_id=xyz-123&growth_id=abc-def&start_time=1569628800&end_time=1569628800

Example Response

{
    "data":{
        "47,-97":{
            "1569628800":{
                "index":1.0,
                "subindex":{
                    "current_weather_suitability":50.0,
                    "future_weather_suitability":2.0,
                    "growth_stage_suitability":100.0
                }
            }, ...
        }
    },
    "errors":{}
}

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>

Parameter Units

Below is a listing of weather parameter units, including a description of each and a listing of the associated parameter types.

System of units Parameter unit What it stands for Associated parameters

US-std

F

Degrees Fahrenheit

temperature, dew point temperature

SI-std

C

Degrees Celsius

temperature, dew point temperature

US-std & SI-std

%

Percent

cloud cover, forecast confidence, relative humidity

US-std

In

Inch

precipitation accumulation, potential evapotranspiration

SI-std

mm

Millimeter

precipitation accumulation

Variable Enumerations

The following is the list of variables supported in the Environmental Conditions endpoint.

Variable Enum Description

0

Daily average 2m air temperature

1

Daily maximum 2m air temperature

2

Daily minimum 2m air temperature

3

Daily average 0-2cm soil temperature

4

Daily average 2-5cm soil temperature

5

Daily average 5-10cm soil temperature

6

Daily average 0-2cm soil moisture

7

Daily average 2-5cm soil moisture

8

Daily average 5-10cm soil moisture

9

Daily average 0-200cm soil moisture

10

Daily average 10m wind speed

11

Daily maximum 10m wind speed

12

Daily average shortwave radiation

13

Daily total liquid-equivalent precipitation

14

Daily total hours of canopy wetness

15

Daily average 5cm air temperature

16

Daily maximum 5cm air temperature

17

Daily minimum 5cm air temperature

18

Daily average 2m dew point temperature

19

Daily maximum 2m dew point temperature

20

Daily minimum 2m dew point temperature

21

Daily average 2m relative humidity

22

Daily maximum 2m relative humidity

23

Daily minimum 2m relative humidity

24

Daily minimum 10m wind speed

25

Daily maximum shortwave radiation

26

Daily average longwave radiation

27

Daily maximum longwave radiation

28

Daily minimum longwave radiation

29

Daily total reference evapotranspiration

30

Daily average 10-20cm soil temperature

31

Daily average 20-40cm soil temperature

32

Daily average 40-70cm soil temperature

33

Daily average 70-100cm soil temperature

34

Daily average 100-200cm soil temperature

35

Daily average 10-20cm soil moisture

36

Daily average 20-40cm soil moisture

37

Daily average 40-70cm soil moisture

38

Daily average 70-100cm soil moisture

39

Daily average 100-200cm soil moisture

40

Daily total surface soil moisture flux

41

Daily total 2cm soil moisture flux

42

Daily total 5cm soil moisture flux

43

Daily total 10cm soil moisture flux

44

Daily total 20cm soil moisture flux

45

Daily total 40cm soil moisture flux

46

Daily total 70cm soil moisture flux

47

Daily total 100cm soil moisture flux

48

Daily total 200cm soil moisture flux

Changelog

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

1/6/20

Added the Daily Powdery Mildew Risk endpoint and made general text updates.

10/29/19

Created initial version of the guide.