ClearAg

Irrigation Decision Support API

Iteris’ Irrigation API enables localized, predictive irrigation analytics to help customers establish more efficient irrigation management and improve crop system performance without the requirement for additional hardware.

IMFocus

last updated 1/9/19

Utilizing proprietary ClearAg Focus modeling capabilities, IMFocus tracks all sources and transitions of water for the plant root zone, including irrigation activity, and predicts when soil moisture values will reach limiting and critical levels in the crop root zone itself. It accomplishes this by taking into account soil texture class, plant root growth, and field terrain information to come up with a holistic solution that optimizes irrigation decisions.

The IMFocus data feed includes evapotranspiration, root zone depth, root zone moisture, and other multi-depth parameters for more precise and predictive analytics based on field-specific conditions.

The IMFocus scheduler provides irrigation recommendations, energy expense, water expense, energy usage and water usage on a per irrigation event basis. For agriculture applications, ClearAg IMFocus currently supports eight different crops. Please refer to the Appendix for the current list of Supported Crops by Feature.

This service provides data for any location in the world, for any period beginning January 1 of the previous calendar year through nine days into the future. Note that daily values represent summaries of conditions spanning midnight to midnight local time for the requested location timezone.

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

This bundle requires and includes the Accounts API, the Crop Growth Model, and the Focus Soil Conditions bundles.

Uniform Irrigation

The following set of endpoints can be used to create and manage irrigation events which apply a single irrigation prescription to the whole field. Applicable locations typically have small in-field variability and/or they are not equipped with variable rate irrigation (VRI) equipment to take advantage of VRI prescription data. Future irrigation events are generated by the recommendation endpoints and consist of an event time as well as a singular irrigation depth to be applied to the whole field. The conditions data is valid for the whole field as well. A single soil texture class, terrain, and organic matter profile for the whole field is utilized in the calculations.

Irrigation Conditions with Custom Analysis Hourly - v1.0

Through the Irrigation Conditions with Custom Analysis Hourly endpoint users can obtain hourly soil temperature, moisture, and irrigation data valid for a user-defined time range of a specified growth custom to their field, irrigation, and crop specifications. Custom field modeling data availability ranges from the first of the previous year up to 240 hours from the current hour. The query time range is range inclusive with a maximum range per request of 240 hours.

Please see the Custom Field Modeling Supported Crops section of the Appendix for a complete list of currently supported crops.

URL Description

https://ag.us.clearapis.com/v1.0/crop_health/irrigation/custom_analysis/hourly?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&start_time={unix timestamp}&end_time={unix timestamp}
&start_offset={integer}&end_offset={integer}&unitcode={string}

Request Parameters

Parameter Type Required Description

account_id

string

yes

A unique account ID provided by Iteris.

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

end_offset

integer

yes

Query ending time offset from the current hour. Negative values are offsets in the past. The maximum allowable value is 240. Requires: start_offset. Excludes: start_time and end_time.

end_time

unix timestamp

yes

Query ending time. Requires: start_time. Excludes: start_offset and end_offset. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

growth_id

string

yes

ID of crop growth provided by the Create Growth endpoint.

start_offset

integer

yes

The query starting time offset from the current hour. Negative values are offsets in the past. Requires: end_offset. Excludes: start_time and end_time.

start_time

unix timestamp

yes

Query starting time. Requires: end_time. Excludes: start_offset and end_offset. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

unit_code

string

no

Unit conversion set to be used. Default is "us-std." Valid values are "us-std," "us-std-precise," "si-std," and "si-std-precise." Precision based unitcodes expand values out to six decimal places.

user_id

string

yes

User ID provided by the ClearAg Accounts API user management endpoints.

Response Object (JSON)

Field Description

abs_scaled_soil_moisture

Moisture content of the X to Y centimeter depth soil layer, relative to saturation and "wilting point" thresholds for the soil type at the growth location. Valid values range from 0 to 1, where 0 indicates an estimated moisture level at the wilting point, and 1 indicates complete saturation. Therefore, values near 0 (1) indicate very dry (very wet) soils at the chosen location and time. Valid XtoYcm depths are: 0to2cm, 0to10cm, 0to200cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

acres

Area of the field in acres.

activities

User provided field/growth activity data associated with the growth. There is current support for irrigation and soil sample activities. For soil sample activities, only activities containing soil organic matter data are used and displayed.

activities/activity_time

Starting time of the activity expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/activity_time_end

Ending time of the activity expressed as an Unix timestamp. This value may be calculated from the provided irrigation system specifications using the system flow/discharge rate, irrigated area, and applied depth of water. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/activity_type

Enumeration value representing the kind of activity, such as irrigation.

activities/created

Time when the activity was created expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/depth_unit

Unit of measure for start_depth and end_depth parameters in inches or centimeters.

activities/drive_motor _energy_used

Total amount of energy used by the drive motors for an irrigation activity. Units are specified in the associated "drive_motor_energy_used_unit" parameter. Valid only if an irrigation system is configured and configured with drive motors.

activities/drive_motor _energy_used_cost

Total cost of the energy used by the drive motors for an irrigation activity. Valid only if an irrigation system is configured and configured with drive motors.

activities/drive_motor _energy_used_unit

Unit of energy used to power the drive motors for an irrigation activity. Valid value is 'kwh' and is valid only if an irrigation system is configured and configured with drive motors.

activities/end_depth

Ending level (bottom) of layer in a soil sample. Units are specified in activities/depth_unit.

activities/modified

Time when the activity was last modified expressed as an Unix timestamp. A "null" response denotes the activity has not been modified. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/organic_matter

Fractional portion of total soil composed of organic matter of a soil layer represented as a percentage from 0.0 to 100.0 as supplied by a user soil sample.

activities/pump_ energy_used

Total amount of energy used by the irrigation pump for an irrigation activity. Units are specified in the associated "pump_energy_used_unit" parameter. Valid only if an irrigation system is configured and configured with pump irrigation delivery (flow_type=0).

activities/pump_energy _used_cost

Total cost of the energy used to power the irrigation pump for an irrigation activity. Valid only if an irrigation system is configured and configured with pump irrigation delivery (flow_type=0).

activities/pump_energy _used_unit

Unit associated with the irrigation pump’s energy source to measure energy usage for an irrigation activity in 'kwh' for electric sources, 'gal' or 'l' for diesel and LPG sources, and 'lb,' 'kg,' 'MMBtu,' or 'Mcf' for natural gas sources. Valid only if an irrigation system is configured and configured with pump irrigation delivery (flow_type=0).

activities/start_depth

Starting level (top) of layer in a soil sample. Units are specified in activities/depth_unit.

activities/unit

The unit of measure of the depth of water applied from an irrigation in inches or millimeters.

activities/value

The depth of water applied from an irrigation. Units are specified in activities/unit. This value may be calculated from provided irrigation system specifications using the system flow/discharge rate, irrigated area, and activity run time frame.

activities/water_used

Total volume of water used for an irrigation activity. Units are specified in the associated "water_used_unit" parameter. Valid only if an irrigation system is configured.

activities/water_used_cost

Total cost of water used for an irrigation activity. Valid only if an irrigation system is configured.

activities/water_used_unit

Volumetric unit of the total amount of water used for an irrigation activity in 'ac-in' or 'm^3.' Valid only if an irrigation system is configured.

air_temp

Air temperature at two meters above ground level in F or C.

dew_point

Dewpoint temperature at two meters above ground level in F or C.

effective_root _zone_depth

Depth of soil from which most water and nutrients are drawn from by the plant’s roots in feet or meters.

elevation

Field elevation in feet or meters.

emergence_date

The time valid near plant emergence expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

et0_acc_period

One hour accumulated reference evapotranspiration in inches or millimeters. Reference evapotranspiration is the amount of water that would transpire and evaporate from a hypothetical reference crop, assuming that ample water is available. In this case, short green grass is used as the reference crop.

et_acc_period

One hour accumulated depth of water in inches or millimeters, actually evapotranspired, based on the particular crop, soil, and weather conditions of the custom analysis.

field_activity_id

ID of an activity on this field pertinent to this growth.

field_capacity

Volumetric water content of the X to Y cm depth soil layer at field capacity expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

field_id

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

field_properties/irrigation

Field irrigation system specifications. Please refer to the Get Irrigation System Properties, Modify Irrigation System Properties, and Delete Irrigation System Properties endpoints within the ClearAg Focus Soil Conditions.

forecast

Boolean value if the accompanying data are forecast data. An output of "true" means the data are forecasted.

growth_id

ID of crop growth queried.

hectares

Area of the field in hectares.

irrigation_blackout_schedule

Used to schedule time periods that irrigation recommendations should not be started. Limited to 20 schedules. Please see table below for example and further description.

last_model_execution

Last completed model run expressed as an Unix timestamp. If this is "n/a," then the model has not completed a first time run yet. If this is greater than last_scheduled_update, the response represents the most current state related to data inputs. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

last_scheduled_update

Most recent scheduled model run expressed as an Unix timestamp. If this is greater than last_model_execution, the response may not represent the most current state related to data inputs. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

latitude

Latitude coordinate near the center of the field in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field.

longitude

Longitude coordinate near the center of the field in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field.

max_moisture_refill

Desired maximum amount of refill to be provided by irrigation recommendations, expressed as percent depletion from field capacity to wilting point. The default value is 0%, indicating recommended irrigation activities will try to not exceed field capacity. Valid values range from –50% (an increase in the allowed maximum soil moisture) to 50% (a decrease in the allowed maximum soil moisture). Negative values represent refill amounts that exceed field capacity and are internally limited to the soil-specific saturation point.

max_moisture_ depletion

Desired driest state the soil is allowed to attain before an irrigation recommendation is triggered, expressed as percent depletion from field capacity to wilting point. Default values are optimized to the soil composition, crop type, and crop growth stage, with typical values of around 50%. Valid values range from 0% (indicating soil moisture should not be allowed to fall below field capacity) to 100% (soil moisture is allowed to reach the permanent wilting point, at which crop death will occur). Practical values typically range from 30 to 70%. Values are internally limited to be greater than the max_moisture_refill value.

name

User given name of the field, if applicable.

plant_date

Approximate time the crop was planted expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

plant_depth

The depth that the crop was planted in inches or centimeters.

plant_name

Name of the crop plant.

plant_type

Enumeration value representing the specific variety of crop planted.

precip_acc_period

One hour accumulated precipitation (liquid equivalent across all phases) in inches or millimeters.

precip_prob

Probability of precipitation expressed as a percentage. Valid values occur only during the forecast period; historically will return "n/a."

relative_humidity

Relative humidity at two meters above ground level expressed as a percentage.

relative_maturity

Gauges how long it takes for the crop to mature. Depending on the crop, valid values may include "early," "medium- early," "medium," "medium-late," or "late," — where crops having an "early" relative maturity are expected to mature relatively fast, and crops having a "late" relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops.

root_zone_available_water

Depth of water in the root zone that is readily available to the plant in inches or millimeters. This value is negative if the root zone soil moisture is less than the allowed depletion.

root_zone_depth

Depth to which the deepest roots of the plant extend in feet or meters.

root_zone_field_capacity

Volumetric water content of the root zone at field capacity expressed as a decimal.

root_zone_max_allowable _soil_moisture

Maximum value soil moisture in the root zone should attain following an irrigation event expressed as percent volumetric water content.

root_zone_min_allowable _soil_moisture

Minimum value to which root zone soil moisture should be allowed to dry to before irrigation is recommended, expressed as percent volumetric water content.

root_zone_saturation

Volumetric water content of the root zone at saturation expressed a decimal.

root_zone_soil_moisture

Volumetric water content of the root zone expressed as a decimal.

root_zone_wilting_point

Volumetric water content of the root zone at the permanent wilting point expressed as a decimal.

saturation

Volumetric water content of the X to Y cm depth soil layer at saturation expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

short_wave_radiation

Downwelling shortwave radiation flux in watts per square meter.

soil_moisture

Volumetric water content of the X to Y centimeter depth soil layer expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 0to10cm, 0to200cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

soil_temp

Soil temperature of the X to Y centimeter depth soil layer. Valid XtoYcm depths are: 0to2cm, 0to10cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

texture_classes

User supplied list of vertically varying texture class data in a soil column.

texture_classes/texture_class

USDA soil texture class of a soil layer expressed as an integer. Please refer to section USDA Texture Classes section of the Appendix for valid values of texture_class and texture_class_description.

texture_classes/ texture_class_depth

Starting level (top) of layer for texture class data in inches or centimeters. The ending level (bottom) of a layer is obtained from the next level’s starting depth. A complete column profile needs to extend to 2 meters. Profiles that do not extend a full 2 meters will have the deepest layer having an assumed ending depth of 2 meters. Any profile data extending beyond 2 meters will not be utilized.

texture_classes/texture _class_description

Name of USDA soil texture class. Please refer to section USDA Texture Classes section of the Appendix for valid values of texture_class and texture_class_description.

units

Contains a mapping of response parameters from the data, field property and growth property sections to their respective unit.

wilting_point

Volumetric water content of the X to Y cm depth soil layer at the permanent wilting point expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

wind_speed

Wind speed at 10 meters above ground level in miles per hour or kilometers per hour.

irrigation_blackout_schedule

Description of schedule:
{start_timestamp}: unix timestamp when the schedule starts.
{duration}: integer; minimum 3600; Amount of seconds from start of an interval which blackout schedule applies.
{repeat_offset}: integer, minimum: 3600; schedule repeats every {repeat_offset} seconds.

Example irrigation_blackout_schedule:
[[1507568400, 14400, 604800],[1507554000, 432000, 604800],[1507352400, 172800, 604800],[1507392400, 112800, 204800]]

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/irrigation/custom_analysis/hourly?app_id=123&app_key=321&account_id=abc-123&user_id=abc-456
&growth_id=def123&start_time=1493240400&end_time=1493240400
&start_offset=0&end_offset=1

Example Response

Response if growth is not currently registered or at least one custom field modeling run has not been completed.

{
    "data":{},
    "metadata":{
        "units":{},
        "last_scheduled_update":1515701490,
        "last_model_execution":"n/a",
        "growth_properties":{
            "max_moisture_refill":null,
            "plant_name":"corn",
            "plant_date":1488326400,
            "growth_id":"abc-123",
            "relative_maturity":"100",
            "plant_type":51,
            "max_moisture_depletion":null,
            "emergence_date":null
        },
        "field_properties":{
            "irrigation":{
                "water":{
                    "post_irrigation_delay":null,
                    "energy_use_rate":4,
                    "irrigation_blackout_schedule":[
                        [
                            1506891615,
                            14400,
                            604800
                        ]
                    ],
                    "energy_source":0,
                    "set_irrigation_unit":"in",
                    "water_unit":"ac-in",
                    "max_moisture_refill":-2.0,
                    "energy_unit":"kwh",
                    "flow_type":0,
                    "energy_cost":4,
                    "electricity_cost_schedule":[
                        [
                            1506891600,
                            3600,
                            10800,
                            1
                        ],
                        [
                            1506891600,
                            3600,
                            18000,
                            2
                        ],
                        [
                            1506891600,
                            3600,
                            7200,
                            3
                        ]
                    ],
                    "max_moisture_depletion":50.0,
                    "water_cost":27.15,
                    "set_irrigation_amount":0.3
                },
                "system":{
                    "drive_motor_unit":"kwh",
                    "flow_rate_unit":"gpm",
                    "drive_motor_rate":1.05,
                    "flow_rate":2.64,
                    "system_type":5,
                    "irrigated_area_unit":"ac",
                    "drive_motor_cost":0.15,
                    "irrigated_area":84.02
                }
            },
            "name":"Unnamed Farm",
            "created":1515699977,
            "field_id":"abc-def",
            "longitude":-99.422605,
            "acres":260,
            "latitude":40.470448,
            "hectares":105.22
        },
        "activities":{
            "irrigation":[],
            "soil_sample":[]
        }
    }
}

Response if growth is currently registered and at least one custom field modeling run has been performed.

{
    "data":{
        "1515700800":{
            "air_temp":15,
            "dew_point":4,
            "et0_acc_period":0,
            "forecast":"True",
            "precip_acc_period":0,
            "precip_prob":0,
            "relative_humidity":61,
            "short_wave_radiation":431,
            "wind_speed":21,
            "soil_conditions":{
                "depth_0to10cm":{
                    "soil_moisture":0.29,
                    "abs_scaled_soil_moisture":0.63,
                    "soil_temp":29.85
                },
                "depth_0to200cm":{
                    "soil_moisture":0.28,
                    "abs_scaled_soil_moisture":0.5
                },
                "depth_0to2cm":{
                    "soil_moisture":0.29,
                    "abs_scaled_soil_moisture":0.62,
                    "soil_temp":27.56
                },
                "depth_2to5cm":{
                    "soil_moisture":0.29,
                    "abs_scaled_soil_moisture":0.63,
                    "soil_temp":29.27
                },
                "depth_5to10cm":{
                    "soil_moisture":0.29,
                    "abs_scaled_soil_moisture":0.63,
                    "soil_temp":31.1
                },
                "depth_10to20cm":{
                    "soil_moisture":0.29,
                    "abs_scaled_soil_moisture":0.63,
                    "soil_temp":31.36
                },
                "depth_20to40cm":{
                    "soil_moisture":0.27,
                    "abs_scaled_soil_moisture":0.54,
                    "soil_temp":30.8
                },
                "depth_40to70cm":{
                    "soil_moisture":0.27,
                    "abs_scaled_soil_moisture":0.45,
                    "soil_temp":31.03
                },
                "depth_70to100cm":{
                    "soil_moisture":0.28,
                    "abs_scaled_soil_moisture":0.48,
                    "soil_temp":33.98
                },
                "depth_100to200cm":{
                    "soil_moisture":0.28,
                    "abs_scaled_soil_moisture":0.5,
                    "soil_temp":39.19
                },
                "effective_root_zone_depth":0.1,
                "root_zone_depth":0.16,
                "root_zone_field_capacity":0.26,
                "root_zone_max_allowable_soil_moisture":0.23,
                "root_zone_min_allowable_soil_moisture":0.14,
                "root_zone_saturation":0.43,
                "root_zone_wilting_point":0.05,
                "et_acc_period":0,
                "root_zone_available_water":0.18,
                "root_zone_soil_moisture":0.29
            }
        },...
    },
    "metadata":{
        "units":{
            "elevation":"ft",
            "field_capacity":"ft^3/ft^3",
            "saturation":"ft^3/ft^3",
            "texture_class_depth":"in",
            "wilting_point":"ft^3/ft^3",
            "soil_moisture":"ft^3/ft^3",
            "abs_scaled_soil_moisture":"n/a",
            "soil_temp":"F",
            "effective_root_zone_depth":"ft",
            "root_zone_depth":"ft",
            "root_zone_field_capacity":"ft^3/ft^3",
            "root_zone_max_allowable_soil_moisture":"%",
            "root_zone_min_allowable_soil_moisture":"%",
            "root_zone_saturation":"ft^3/ft^3",
            "root_zone_wilting_point":"ft^3/ft^3",
            "et_acc_period":"in",
            "root_zone_available_water":"in",
            "root_zone_soil_moisture":"ft^3/ft^3",
            "air_temp":"F",
            "dew_point":"F",
            "et0_acc_period":"in",
            "forecast":"n/a",
            "precip_acc_period":"in",
            "precip_prob":"%",
            "relative_humidity":"%",
            "short_wave_radiation":"W/m^2",
            "wind_speed":"mph"
        },
        "field_properties":{
            "texture_classes":[{
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":0
                },
                {
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":0.79
                },
                {
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":1.97
                },
                {
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":3.94
                },
                {
                    "texture_class":6,
                    "texture_class_desc":"loam",
                    "texture_class_depth":7.87
                },
                {
                    "texture_class":9,
                    "texture_class_desc":"clay loam",
                    "texture_class_depth":15.75
                },
                {
                    "texture_class":9,
                    "texture_class_desc":"clay loam",
                    "texture_class_depth":27.56
                },
                {
                    "texture_class":9,
                    "texture_class_desc":"clay loam",
                    "texture_class_depth":39.37
                }
            ],
            "model_soil_properties":{
                "100to200cm":{
                    "field_capacity":0.37,
                    "wilting_point":0.1,
                    "saturation":0.47
                },
                "70to100cm":{
                    "field_capacity":0.37,
                    "wilting_point":0.1,
                    "saturation":0.47
                },
                "40to70cm":{
                    "field_capacity":0.37,
                    "wilting_point":0.1,
                    "saturation":0.47
                },
                "20to40cm":{
                    "field_capacity":0.3,
                    "wilting_point":0.07,
                    "saturation":0.44
                },
                "10to20cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                },
                "5to10cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                },
                "2to5cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                },
                "0to2cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                }
            },
            "elevation":2333.97,
            "longitude":-99.422605,
            "latitude":40.470448,
            "irrigation":{
                "water":{
                    "post_irrigation_delay":null,
                    "energy_use_rate":4,
                    "irrigation_blackout_schedule":[
                        [
                            1506891615,
                            14400,
                            604800
                        ]
                    ],
                    "energy_source":0,
                    "set_irrigation_unit":"in",
                    "water_unit":"ac-in",
                    "max_moisture_refill":-2.0,
                    "energy_unit":"kwh",
                    "flow_type":0,
                    "energy_cost":4,
                    "electricity_cost_schedule":[
                        [
                            1506891600,
                            3600,
                            10800,
                            1
                        ],
                        [
                            1506891600,
                            3600,
                            18000,
                            2
                        ],
                        [
                            1506891600,
                            3600,
                            7200,
                            3
                        ]
                    ],
                    "max_moisture_depletion":50.0,
                    "water_cost":27.15,
                    "set_irrigation_amount":0.3
                },
                "system":{
                    "drive_motor_unit":"kwh",
                    "flow_rate_unit":"gpm",
                    "drive_motor_rate":1.05,
                    "flow_rate":2.64,
                    "system_type":5,
                    "irrigated_area_unit":"ac",
                    "drive_motor_cost":0.15,
                    "irrigated_area":84.02
                }
            },
            "name":"Unnamed Farm",
            "created":1515699977,
            "field_id":"abc-def",
            "acres":260,
            "hectares":105.22
        },
        "last_scheduled_update":1515702617,
        "last_model_execution":1515702736,
        "growth_properties":{
            "max_moisture_refill":null,
            "plant_name":"corn",
            "plant_date":1488326400,
            "growth_id":"abc-123",
            "relative_maturity":"100",
            "plant_type":51,
            "max_moisture_depletion":null,
            "emergence_date":null
        },
        "activities":{
            "irrigation":[],
            "soil_sample":[]
        }
    }
}

Irrigation Conditions with Custom Analysis Daily - v1.0

Through the Irrigation Conditions with Custom Analysis Daily endpoint users can obtain daily soil temperature, moisture, and irrigation data valid for a user-defined time range of a specified growth custom to their field, irrigation, and crop specifications. Custom field modeling data availability ranges from the first of the previous year up to +9 days of the current date. The query time range is range inclusive with a maximum range per request of 366 days.

Please see the Custom Field Modeling Supported Crops section of the Appendix for a complete list of currently supported crops.

URL Description

https://ag.us.clearapis.com/v1.0/crop_health/irrigation/custom_analysis/
daily?app_id={string}&app_key={string}&account_id={string}
&user_id={string}&growth_id={string}&start_date={string}
&end_date={string}&start_time={unix timestamp}&end_time={unix_timestamp}
&start_offset={integer}&end_offset={integer}&unitcode={string}

Request Parameters

Parameter Type Required Description

account_id

string

yes

A unique account ID provided by Iteris.

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

end_date

string

yes

Query ending local date in YYYY-MM-DD date format. Requires: start_date. Excludes: start_offset, end_offset, start_time, and end_time.

end_offset

integer

yes

Query ending time offset from the current day. Negative values are offsets in the past. The maximum allowable value is +9. Requires: end_offset. Excludes: start_date, end_date, start_time, and end_time.

end_time

unix timestamp

yes

Query starting time. Requires: end_time Excludes: start_date, end_date, start_offset, and end_offset. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

growth_id

string

yes

ID of crop growth provided by the Create Growth endpoint.

start_date

string

yes

Query starting local date in YYYY-MM-DD date format. Requires: end_date. Excludes: start_offset, end_offset, start_time, and end_time.

start_offset

integer

yes

Query starting time offset from the current day. Negative values are offsets in the past. Requires: end_offset. Excludes: start_date, end_date, start_time, and end_time.

start_time

unix timestamp

yes

Query starting time. Requires: end_time Excludes: start_date, end_date, start_offset, and end_offset. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

unitcode

string

no

Unit conversion set to be used. Default is "us-std." Valid values are "us-std," "us-std-precise," "si-std," and "si-std-precise." Precision based unitcodes expand values out to six decimal places.

user_id

string

yes

User ID provided by the ClearAg Accounts API user management endpoints.

Response Object (JSON)

Field Description

abs_scaled_soil_moisture

Moisture content of the X to Y centimeter depth soil layer, relative to saturation and "wilting point" thresholds for the soil type at the growth location. Valid values range from 0 to 1, where 0 indicates an estimated moisture level at the wilting point, and 1 indicates complete saturation. Therefore, values near 0 (1) indicate very dry (very wet) soils at the chosen location and time. Valid XtoYcm depths are: 0to2cm, 0to10cm, 0to200cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

acres

Area of the field in acres.

activities

User provided field/growth activity data associated with the growth. There is current support for irrigation and soil sample activities. For soil sample activities, only activities containing soil organic matter data are used and displayed.

activities/activity_time

Starting time of the activity expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/activity_time_end

Ending time of the activity expressed as an Unix timestamp. This value may be calculated from the provided irrigation system specifications using the system flow/discharge rate, irrigated area, and applied depth of water. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/activity_type

Enumeration value representing the kind of activity, such as irrigation.

activities/created

Time when the activity was created expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/depth_unit

Unit of measure for start_depth and end_depth parameters in inches or centimeters.

activities/drive_motor _energy_used

Total amount of energy used by the drive motors for an irrigation activity. Units are specified in the associated "drive_motor_energy_used_unit" parameter. Valid only if an irrigation system is configured and configured with drive motors.

activities/drive_motor _energy_used_cost

Total cost of the energy used by the drive motors for an irrigation activity. Valid only if an irrigation system is configured and configured with drive motors.

activities/drive_motor _energy_used_unit

Unit of energy used to power the drive motors for an irrigation activity. Valid value is 'kwh' and is valid only if an irrigation system is configured and configured with drive motors.

activities/end_depth

Ending level (bottom) of layer in a soil sample. Units are specified in activities/depth_unit.

activities/modified

Time when the activity was last modified expressed as an Unix timestamp. A "null" response denotes the activity has not been modified. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/organic_matter

Fractional portion of total soil composed of organic matter of a soil layer represented as a percentage from 0.0 to 100.0 as supplied by a user soil sample.

activities/pump_ energy_used

Total amount of energy used by the irrigation pump for an irrigation activity. Units are specified in the associated "pump_energy_used_unit" parameter. Valid only if an irrigation system is configured and configured with pump irrigation delivery (flow_type=0).

activities/pump_energy _used_cost

Total cost of the energy used to power the irrigation pump for an irrigation activity. Valid only if an irrigation system is configured and configured with pump irrigation delivery (flow_type=0).

activities/pump_ energy_used_unit

Unit associated with the irrigation pump’s energy source to measure energy usage for an irrigation activity in 'kwh' for electric sources, 'gal' or 'l' for diesel and LPG sources, and 'lb,' 'kg,' 'MMBtu,' or 'Mcf' for natural gas sources. Valid only if an irrigation system is configured and configured with pump irrigation delivery (flow_type=0).

activities/start_depth

Starting level (top) of layer in a soil sample. Units are specified in activities/depth_unit.

activities/unit

The unit of measure of the depth of water applied from an irrigation in inches or millimeters.

activities/value

The depth of water applied from an irrigation. Units are specified in activities/unit. This value may be calculated from provided irrigation system specifications using the system flow/discharge rate, irrigated area, and activity run time frame.

activities/water_used

Total volume of water used for an irrigation activity. Units are specified in the associated "water_used_unit" parameter. Valid only if an irrigation system is configured.

activities/water_used_cost

Total cost of water used for an irrigation activity. Valid only if an irrigation system is configured.

activities/water_used_unit

Volumetric unit of the total amount of water used for an irrigation activity in 'ac-in' or 'm^3.' Valid only if an irrigation system is configured.

air_temp_avg

24-hour average air temperature at two meters above ground level in F or C.

air_temp_max

24-hour maximum air temperature at two meters above ground level in F or C.

air_temp_min

24-hour minimum air temperature at two meters above ground level in F or C.

dew_point_avg

24-hour average dewpoint temperature at two meters above ground level in F or C.

dew_point_max

24-hour maximum dewpoint temperature at two meters above ground level in F or C.

dew_point_min

24-hour minimum dewpoint temperature at two meters above ground level in F or C.

effective_root_ zone_depth

Depth of soil from which most water and nutrients are drawn from by the plant’s roots in feet or meters.

elevation

Field elevation in feet or meters.

emergence_date

The time valid near plant emergence expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

et0_acc_period

24-hour accumulated reference evapotranspiration in inches or millimeters. Reference evapotranspiration is the amount of water that would transpire and evaporate from a hypothetical reference crop, assuming that ample water is available. In this case, short green grass is used as the reference crop.

et_acc_period

24-hour accumulated depth of water in inches or millimeters, actually evapotranspired, based on the particular crop, soil, and weather conditions of the custom analysis.

field_activity_id

ID of an activity on this field pertinent to this growth.

field_capacity

Volumetric water content of the X to Y cm depth soil layer at field capacity expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

field_id

ID of an activity on this field pertinent to this growth.

field_properties/irrigation

Field irrigation system specifications. Please refer to the Get Irrigation System Properties, Modify Irrigation System Properties, and Delete Irrigation System Properties endpoints within the ClearAg Focus Soil Conditions.

forecast

Boolean value if the accompanying data are forecast data. An output of "true" means the data are forecasted.

growth_id

ID of crop growth queried.

hectares

Area of the field in hectares.

last_model_execution

Last completed model run expressed as an Unix timestamp. If this is "n/a," then the model has not completed a first time run yet. If this is greater than last_scheduled_update, the response represents the most current state related to data inputs. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

last_scheduled_update

Most recent scheduled model run expressed as an Unix timestamp. If this is greater than last_model_execution, the response may not represent the most current state related to data inputs. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

latitude

Latitude coordinate near the center of the field in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field.

longitude

Longitude coordinate near the center of the field in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field.

max_moisture_refill

Desired maximum amount of refill to be provided by irrigation recommendations, expressed as percent depletion from field capacity to wilting point. The default value is 0%, indicating recommended irrigation activities will try to not exceed field capacity. Valid values range from –50% (an increase in the allowed maximum soil moisture) to 50% (a decrease in the allowed maximum soil moisture). Negative values represent refill amounts that exceed field capacity and are internally limited to the soil-specific saturation point.

max_moisture_ depletion

Desired driest state the soil is allowed to attain before an irrigation recommendation is triggered, expressed as percent depletion from field capacity to wilting point. Default values are optimized to the soil composition, crop type, and crop growth stage, with typical values of around 50%. Valid values range from 0% (indicating soil moisture should not be allowed to fall below field capacity) to 100% (soil moisture is allowed to reach the permanent wilting point, at which crop death will occur). Practical values typically range from 30 to 70%. Values are internally limited to be greater than the max_moisture_refill value.

name

User given name of the field, if applicable.

plant_date

Approximate time the crop was planted expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

plant_depth

The depth that the crop was planted in inches or centimeters.

plant_name

Name of the crop plant.

plant_type

Enumeration value representing the specific variety of crop planted.

precip_acc_period

24-hour accumulated precipitation (liquid equivalent across all phases) in inches or millimeters.

precip_prob

Probability of precipitation expressed as a percentage. Valid values occur only during the forecast period; historically will return "n/a."

relative_humidity_avg

24-hour average relative humidity at two meters above ground level expressed as a percentage.

relative_humidity_max

24-hour maximum relative humidity at two meters above ground level expressed as percentage.

relative_humidity_min

24-hour minimum relative humidity at two meters above ground level expressed as a percentage.

relative_maturity

Gauges how long it takes for the crop to mature. Depending on the crop, valid values may include "early," "medium-early," "medium," "medium-late," or "late," — where crops having an "early" relative maturity are expected to mature relatively fast, and crops having a "late" relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops.

root_zone_available_water

Depth of water in the root zone that is readily available to the plant in inches or millimeters. This value is negative if the root zone soil moisture is less than the allowed depletion.

root_zone_depth

Depth to which the deepest roots of the plant extend in feet or meters.

root_zone_field_capacity

Volumetric water content of the root zone at field capacity expressed as a decimal.

root_zone_max_allowable _soil_moisture

Maximum value soil moisture in the root zone should attain following an irrigation event expressed as percent volumetric water content.

root_zone_min_allowable _soil_moisture

Minimum value to which root zone soil moisture should be allowed to dry to before irrigation is recommended, expressed as percent volumetric water content.

root_zone_saturation

Volumetric water content of the root zone at saturation expressed a decimal.

root_zone_soil_moisture

Volumetric water content of the root zone expressed as a decimal.

root_zone_wilting_point

Volumetric water content of the root zone at the permanent wilting point expressed as a decimal.

saturation

Volumetric water content of the X to Y cm depth soil layer at saturation expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

short_wave_radiation_avg

24-hour average downwelling shortwave radiation flux in watts per square meter.

short_wave_radiation_max

24-hour maximum downwelling shortwave radiation flux in watts per square meter.

short_wave_radiation_min

24-hour minimum downwelling shortwave radiation flux in watts per square meter.

soil_moisture

24-hour average volumetric water content of the X to Y centimeter depth soil layer expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 0to10cm, 0to200cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

soil_temp

24-hour average soil temperature of the X to Y centimeter depth soil layer. Valid XtoYcm depths are: 0to2cm, 0to10cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

soil_temp_max

24-hour maximum soil temperature of the X to Y centimeter depth soil layer. Valid XtoYcm depths are: 0to2cm, 0to10cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

soil_temp_min

24-hour minimum soil temperature of the X to Y centimeter depth soil layer. Valid XtoYcm depths are: 0to2cm, 0to10cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

texture_classes

User supplied list of vertically varying texture class data in a soil column.

texture_classes/texture_class

USDA soil texture class of a soil layer expressed as an integer. Please refer to section USDA Texture Classes section of the Appendix for valid values of texture_class and texture_class_description.

texture_classes/ texture_class_depth

Starting level (top) of layer for texture class data in inches or centimeters. The ending level (bottom) of a layer is obtained from the next level’s starting depth. A complete column profile needs to extend to 2 meters. Profiles that do not extend a full 2 meters will have the deepest layer having an assumed ending depth of 2 meters. Any profile data extending beyond 2 meters will not be utilized.

texture_classes/texture _class_description

Name of USDA soil texture class. Please refer to section USDA Texture Classes section of the Appendix for valid values of texture_class and texture_class_description.

units

Contains a mapping of response parameters from the data, field property and growth property sections to their respective unit.

wilting_point

Volumetric water content of the X to Y cm depth soil layer at the permanent wilting point expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

wind_speed_avg

24-hour average wind speed at 10 meters above ground level in miles per hour or kilometers per hour.

wind_speed_max

24-hour maximum wind speed at 10 meters above ground level in miles per hour or kilometers per hour.

wind_speed_min

24-hour minimum wind speed at 10 meters above ground level in miles per hour or kilometers per hour.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/irrigation/custom_analysis/
daily?app_id=123&app_key=321&account_id=123-abc&user_id=xyz-123
&growth_id=abc-123&start_date=07-01&end_date=07-02
&start_time=1497549600&end_time=1497556800&start_offset=0&end_offset=1

Example Response

Response if growth is not currently registered or at least one custom field modeling run has not been completed.

{
    "data":{},
    "metadata":{
        "units":{},
        "last_scheduled_update":1515701490,
        "last_model_execution":"n/a",
        "growth_properties":{
            "max_moisture_refill":null,
            "plant_name":"corn",
            "plant_date":1488326400,
            "growth_id":"abc-123",
            "relative_maturity":"100",
            "plant_type":51,
            "max_moisture_depletion":null,
            "emergence_date":null
        },
        "field_properties":{
            "irrigation":{
                "water":{
                    "post_irrigation_delay":null,
                    "energy_use_rate":4,
                    "irrigation_blackout_schedule":[
                        [
                            1506891615,
                            14400,
                            604800
                        ]
                    ],
                    "energy_source":0,
                    "set_irrigation_unit":"in",
                    "water_unit":"ac-in",
                    "max_moisture_refill":-2.0,
                    "energy_unit":"kwh",
                    "flow_type":0,
                    "energy_cost":4,
                    "electricity_cost_schedule":[
                        [
                            1506891600,
                            3600,
                            10800,
                            1
                        ],
                        [
                            1506891600,
                            3600,
                            18000,
                            2
                        ],
                        [
                            1506891600,
                            3600,
                            7200,
                            3
                        ]
                    ],
                    "max_moisture_depletion":50,
                    "water_cost":27.15,
                    "set_irrigation_amount":0.3
                },
                "system":{
                    "drive_motor_unit":"kwh",
                    "flow_rate_unit":"gpm",
                    "drive_motor_rate":1.05,
                    "flow_rate":2.64,
                    "system_type":5,
                    "irrigated_area_unit":"ac",
                    "drive_motor_cost":0.15,
                    "irrigated_area":84.02
                }
            },
            "name":"Unnamed Farm",
            "created":1515699977,
            "field_id":"abc-def",
            "longitude":-99.422605,
            "acres":260,
            "latitude":40.470448,
            "hectares":105.22
        },
        "activities":{
            "irrigation":[],
            "soil_sample":[]
        }
    }
}

Response if growth is currently registered and at least one custom field modeling run has been performed.

{
    "data":{
        "2018-01-11":{
            "air_temp_max":22,
            "air_temp_min":6,
            "air_temp_avg":13,
            "dew_point_max":14,
            "dew_point_min":-1,
            "dew_point_avg":5,
            "et0_acc_period":0.02,
            "forecast":"True",
            "precip_acc_period":0.1,
            "precip_prob":80,
            "short_wave_radiation_avg":108,
            "short_wave_radiation_max":483,
            "short_wave_radiation_min":0,
            "relative_humidity_max":87,
            "relative_humidity_min":54,
            "relative_humidity_avg":70,
            "wind_speed_max":28,
            "wind_speed_min":4,
            "wind_speed_avg":19,
            "soil_conditions":{
                "depth_0to10cm":{
                    "soil_moisture":0.29,
                    "abs_scaled_soil_moisture":0.63,
                    "soil_temp":29.29,
                    "soil_temp_max":31.9,
                    "soil_temp_min":22.89
                },
                "depth_0to200cm":{
                    "soil_moisture":0.28,
                    "abs_scaled_soil_moisture":0.5
                },
                "depth_0to2cm":{
                    "soil_moisture":0.29,
                    "abs_scaled_soil_moisture":0.62,
                    "soil_temp":26.58,
                    "soil_temp_max":31.83,
                    "soil_temp_min":22.89
                },
                "depth_2to5cm":{
                    "soil_moisture":0.29,
                    "abs_scaled_soil_moisture":0.63,
                    "soil_temp":28.93,
                    "soil_temp_max":31.9,
                    "soil_temp_min":25.64
                },
                "depth_5to10cm":{
                    "soil_moisture":0.29,
                    "abs_scaled_soil_moisture":0.63,
                    "soil_temp":30.59,
                    "soil_temp_max":31.88,
                    "soil_temp_min":28.07
                },
                "depth_10to20cm":{
                    "soil_moisture":0.29,
                    "abs_scaled_soil_moisture":0.63,
                    "soil_temp":31.3,
                    "soil_temp_max":31.44,
                    "soil_temp_min":31.04
                },
                "depth_20to40cm":{
                    "soil_moisture":0.27,
                    "abs_scaled_soil_moisture":0.53,
                    "soil_temp":30.77,
                    "soil_temp_max":30.92,
                    "soil_temp_min":30.58
                },
                "depth_40to70cm":{
                    "soil_moisture":0.27,
                    "abs_scaled_soil_moisture":0.45,
                    "soil_temp":31.03,
                    "soil_temp_max":31.03,
                    "soil_temp_min":31.02
                },
                "depth_70to100cm":{
                    "soil_moisture":0.28,
                    "abs_scaled_soil_moisture":0.48,
                    "soil_temp":33.99,
                    "soil_temp_max":34.05,
                    "soil_temp_min":33.94
                },
                "depth_100to200cm":{
                    "soil_moisture":0.28,
                    "abs_scaled_soil_moisture":0.5,
                    "soil_temp":39.22,
                    "soil_temp_max":39.35,
                    "soil_temp_min":39.09
                },
                "effective_root_zone_depth":0.1,
                "root_zone_depth":0.16,
                "root_zone_field_capacity":0.26,
                "root_zone_max_allowable_soil_moisture":0.23,
                "root_zone_min_allowable_soil_moisture":0.14,
                "root_zone_saturation":0.43,
                "root_zone_wilting_point":0.05,
                "et_acc_period":0.02,
                "root_zone_available_water":0.18,
                "root_zone_soil_moisture":0.29
            }
        },...
    },
    "metadata":{
        "units":{
            "elevation":"ft",
            "field_capacity":"ft^3/ft^3",
            "saturation":"ft^3/ft^3",
            "texture_class_depth":"in",
            "wilting_point":"ft^3/ft^3",
            "soil_moisture":"ft^3/ft^3",
            "abs_scaled_soil_moisture":"n/a",
            "soil_temp":"F",
            "soil_temp_max":"F",
            "soil_temp_min":"F",
            "effective_root_zone_depth":"ft",
            "root_zone_depth":"ft",
            "root_zone_field_capacity":"ft^3/ft^3",
            "root_zone_max_allowable_soil_moisture":"%",
            "root_zone_min_allowable_soil_moisture":"%",
            "root_zone_saturation":"ft^3/ft^3",
            "root_zone_wilting_point":"ft^3/ft^3",
            "et_acc_period":"in",
            "root_zone_available_water":"in",
            "root_zone_soil_moisture":"ft^3/ft^3",
            "air_temp_max":"F",
            "air_temp_min":"F",
            "air_temp_avg":"F",
            "dew_point_max":"F",
            "dew_point_min":"F",
            "dew_point_avg":"F",
            "et0_acc_period":"in",
            "forecast":"n/a",
            "precip_acc_period":"in",
            "precip_prob":"%",
            "short_wave_radiation_avg":"W/m^2",
            "short_wave_radiation_max":"W/m^2",
            "short_wave_radiation_min":"W/m^2",
            "relative_humidity_max":"%",
            "relative_humidity_min":"%",
            "relative_humidity_avg":"%",
            "wind_speed_max":"mph",
            "wind_speed_min":"mph",
            "wind_speed_avg":"mph"
        },
        "field_properties":{
            "texture_classes":[
                {
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":0
                },
                {
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":0.79
                },
                {
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":1.97
                },
                {
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":3.94
                },
                {
                    "texture_class":6,
                    "texture_class_desc":"loam",
                    "texture_class_depth":7.87
                },
                {
                    "texture_class":9,
                    "texture_class_desc":"clay loam",
                    "texture_class_depth":15.75
                },
                {
                    "texture_class":9,
                    "texture_class_desc":"clay loam",
                    "texture_class_depth":27.56
                },
                {
                    "texture_class":9,
                    "texture_class_desc":"clay loam",
                    "texture_class_depth":39.37
                }
            ],
            "model_soil_properties":{
                "100to200cm":{
                    "field_capacity":0.37,
                    "wilting_point":0.1,
                    "saturation":0.47
                },
                "70to100cm":{
                    "field_capacity":0.37,
                    "wilting_point":0.1,
                    "saturation":0.47
                },
                "40to70cm":{
                    "field_capacity":0.37,
                    "wilting_point":0.1,
                    "saturation":0.47
                },
                "20to40cm":{
                    "field_capacity":0.3,
                    "wilting_point":0.07,
                    "saturation":0.44
                },
                "10to20cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                },
                "5to10cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                },
                "2to5cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                },
                "0to2cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                }
            },
            "elevation":2333.97,
            "longitude":-99.422605,
            "latitude":40.470448,
            "irrigation":{
                "water":{
                    "post_irrigation_delay":null,
                    "energy_use_rate":4,
                    "irrigation_blackout_schedule":[
                        [
                            1506891615,
                            14400,
                            604800
                        ]
                    ],
                    "energy_source":0,
                    "set_irrigation_unit":"in",
                    "water_unit":"ac-in",
                    "max_moisture_refill":-2.0,
                    "energy_unit":"kwh",
                    "flow_type":0,
                    "energy_cost":4,
                    "electricity_cost_schedule":[
                        [
                            1506891600,
                            3600,
                            10800,
                            1
                        ],
                        [
                            1506891600,
                            3600,
                            18000,
                            2
                        ],
                        [
                            1506891600,
                            3600,
                            7200,
                            3
                        ]
                    ],
                    "max_moisture_depletion":50.0,
                    "water_cost":27.15,
                    "set_irrigation_amount":0.3
                },
                "system":{
                    "drive_motor_unit":"kwh",
                    "flow_rate_unit":"gpm",
                    "drive_motor_rate":1.05,
                    "flow_rate":2.64,
                    "system_type":5,
                    "irrigated_area_unit":"ac",
                    "drive_motor_cost":0.15,
                    "irrigated_area":84.02
                }
            },
            "name":"Unnamed Farm",
            "created":1515699977,
            "field_id":"abc-def",
            "acres":260,
            "hectares":105.22
        },
        "last_scheduled_update":1515702617,
        "last_model_execution":1515702736,
        "growth_properties":{
            "max_moisture_refill":null,
            "plant_name":"corn",
            "plant_date":1488326400,
            "growth_id":"abc-123",
            "relative_maturity":"100",
            "plant_type":51,
            "max_moisture_depletion":null,
            "emergence_date":null
        },
        "activities":{
            "irrigation":[],
            "soil_sample":[]
        }
    }
}

Irrigation Recommendations with Custom Analysis Hourly - v1.0

Through the Irrigation Recommendations with Custom Analysis Hourly endpoint, users can obtain recommendations for irrigation activities, along with analyzed and forecast soil conditions and overall irrigation efficiency information customized to their field, irrigation system, and crop specifications. Associated field and growth metadata, daily weather conditions pertinent to irrigation, and daily soil conditions without the impacts of the irrigation recommendations are also provided. The endpoint returns data for the period of time spanning -240 hours to +240, relative to the current hour.

In order to receive irrigation recommendations for a growth, you must have configured the Irrigation System Properties on the field for which the growth resides. Irrigation System Properties which have been applied will alter custom field modeled soil conditions and generated irrigation recommendations. Please refer to the Get Irrigation System Properties, Modify Irrigation System Properties, and Delete Irrigation System Properties endpoints within the ClearAg Focus Soil Conditions.

Please see the Custom Field Modeling Supported Crops section of the Appendix for a complete list of currently supported crops.

URL Description

https://ag.us.clearapis.com/v1.0/crop_health/irrigation/custom_analysis/hourly/
recommendation?app_id={string}&app_key={string}&account_id={string}
&user_id={string}&growth_id={string}&unitcode={string}

Request Parameters

Parameter Type Required Description

account_id

string

yes

A unique account ID provided by Iteris.

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

growth_id

string

yes

ID of crop growth provided by the Create Growth endpoint.

unitcode

string

no

Unit conversion set to be used. Default is "us-std." Valid values are "us-std," "us-std-precise," "si-std," and "si-std-precise." Precision based unitcodes expand values out to six decimal places.

user_id

string

yes

User ID provided by the ClearAg Accounts API user management endpoints.

Response Object (JSON)

Field Description

abs_scaled_soil_moisture

Moisture content of the X to Y centimeter depth soil layer, relative to saturation and "wilting point" thresholds for the soil type at the growth location. Valid values range from 0 to 1, where 0 indicates an estimated moisture level at the wilting point, and 1 indicates complete saturation. Therefore, values near 0 (1) indicate very dry (very wet) soils at the chosen location and time. Valid XtoYcm depths are: 0to2cm, 0to10cm, 0to200cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

acres

Area of the field in acres.

activities

User provided field/growth activity data associated with the growth. There is current support for irrigation and soil sample activities. For soil sample activities, only activities containing soil organic matter data are used and displayed.

activities/activity_time

Starting time of the activity expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/activity_time_end

Ending time of the activity expressed as an Unix timestamp. This value may be calculated from the provided irrigation system specifications using the system flow/discharge rate, irrigated area, and applied depth of water. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/activity_type

Enumeration value representing the kind of activity, such as irrigation.

activities/created

Time when the activity was created expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/depth_unit

Unit of measure for start_depth and end_depth parameters in inches or centimeters.

activities/drive_motor _energy_used

Total amount of energy used by the drive motors for an irrigation activity. Units are specified in the associated "drive_motor_energy_used_unit" parameter. Valid only for irrigation systems with drive motors.

activities/drive_motor _energy_used_cost

Total cost of the energy used by the drive motors for an irrigation activity. Valid only for irrigation systems with drive motors.

activities/drive_motor _energy_used_unit

Unit of energy used to power the drive motors for an irrigation activity. Valid value is 'kwh' and is valid only for irrigation systems with drive motors.

activities/end_depth

Ending level (bottom) of layer in a soil sample. Units are specified in the "activities/depth_unit" parameter.

activities/modified

Time when the activity was last modified expressed as an Unix timestamp. A "null" response denotes the activity has not been modified. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/organic_matter

Fractional portion of total soil composed of organic matter of a soil layer represented as a percentage from 0.0 to 100.0 as supplied by a user soil sample.

activities/pump_ energy_used

Total amount of energy used by the irrigation pump for an irrigation activity. Units are specified in the associated "pump_energy_used_unit" parameter. Valid only for pump irrigation delivery (flow_type=0).

activities/pump_ energy_used_cost

Total cost of the energy used to power the irrigation pump for an irrigation activity. Valid only for pump irrigation delivery (flow_type=0).

activities/pump_ energy_used_unit

Unit associated with the irrigation pump’s energy source to measure energy usage for an irrigation activity in 'kwh' for electric sources, 'gal' or 'l' for diesel and LPG sources, and 'lb' or 'kg' for natural gas sources. Valid only for pump irrigation delivery (flow_type=0).

activities/start_depth

Starting level (top) of layer in a soil sample. Units are specified in the "activities/depth_unit" parameter.

activities/unit

The unit of measure of the depth of water applied from an irrigation in inches or millimeters.

activities/value

The depth of water applied from an irrigation. Units are specified in activities/unit. This value may be calculated from provided irrigation system specifications using the system flow/discharge rate, irrigated area, and activity run time frame.

activities/water_ used

Total volume of water used for an irrigation activity. Units are specified in the associated "water_used_unit" parameter.

activities/water_ used_cost

Total cost of water used for an irrigation activity.

activities/water_ used_unit

Volumetric unit of the total amount of water used for an irrigation activity in 'ac-in' or 'm^3.'

advisor

Section contains data pertaining to the usage of the irrigation advisor. This includes an overall irrigation efficiency, recommended activities, and time series data representing expected conditions if the recommended irrigation activities are followed.

air_temp

Air temperature at two meters above ground level in F or C.

data

Section contains time series data that represent expected conditions if the irrigation recommendations are not implemented.

dew_point

Dewpoint temperature at two meters above ground level in F or C.

effective_root _zone_depth

Depth of soil from which most water and nutrients are drawn from by the plant’s roots in feet or meters.

elevation

Field elevation in feet or meters.

emergence_date

The time valid near plant emergence, expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

et0_acc_period

One hour accumulated reference evapotranspiration in inches or millimeters. Reference evapotranspiration is the amount of water that would transpire and evaporate from a hypothetical reference crop, assuming that ample water is available. In this case, short green grass is used as the reference crop.

et_acc_period

One hour accumulated depth of water in inches or millimeters, actually evapotranspired, based on the particular crop, soil, and weather conditions of the custom analysis.

field_activity_id

ID of an activity on this field pertinent to this growth.

field_capacity

Volumetric water content of the X to Y cm depth soil layer at field capacity expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

field_id

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

field_properties/irrigation

Field irrigation system specifications. Please refer to the Get Irrigation System Properties, Modify Irrigation System Properties, and Delete Irrigation System Properties endpoints within the ClearAg Focus Soil Conditions.

forecast

Boolean value if the accompanying data are forecast data. An output of "true" means the data are forecasted.

growth_id

ID of crop growth queried.

hectares

Area of the field in hectares.

irrigation_blackout_schedule

Used to schedule time periods that irrigation recommendations should not be started. Limited to 20 schedules. Please see table below for example and further description.

last_model_execution

Last completed model run expressed as an Unix timestamp. If this is "n/a," then the model has not completed a first time run yet. If this is greater than last_scheduled_update, the response represents the most current state related to data inputs. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

last_scheduled_update

Most recent scheduled model run expressed as an Unix timestamp. If this is greater than last_model_execution, the response may not represent the most current state related to data inputs. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

latitude

Latitude coordinate near the center of the field in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field.

longitude

Longitude coordinate near the center of the field in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field.

max_moisture_refill

Desired maximum amount of refill to be provided by irrigation recommendations, expressed as percent depletion from field capacity to wilting point. The default value is 0%, indicating recommended irrigation activities will try to not exceed field capacity. Valid values range from –50% (an increase in the allowed maximum soil moisture) to 50% (a decrease in the allowed maximum soil moisture). Negative values represent refill amounts that exceed field capacity and are internally limited to the soil-specific saturation point.

max_moisture_ depletion

Desired driest state the soil is allowed to attain before an irrigation recommendation is triggered, expressed as percent depletion from field capacity to wilting point. Default values are optimized to the soil composition, crop type, and crop growth stage, with typical values of around 50%. Valid values range from 0% (indicating soil moisture should not be allowed to fall below field capacity) to 100% (soil moisture is allowed to reach the permanent wilting point, at which crop death will occur). Practical values typically range from 30 to 70%. Values are internally limited to be greater than the max_moisture_refill value.

name

User given name of the field, if applicable.

overall_efficiency

Efficiency of the irrigation recommendations in terms of water retained in the root zone or transpired as a proportion of total applied water, expressed as a percentage.

plant_date

Approximate time the crop was planted expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

plant_depth

The depth that the crop was planted in inches or centimeters.

plant_name

Name of the crop plant.

plant_type

Enumeration value representing the specific variety of crop planted.

precip_acc_period

One hour accumulated precipitation (liquid equivalent across all phases) in inches or millimeters.

precip_prob

Probability of precipitation expressed as a percentage. Valid values occur only during the forecast period; historically will return "n/a."

relative_humidity

Relative humidity at two meters above ground level expressed as a percentage.

relative_maturity

Gauges how long it takes for the crop to mature. Depending on the crop, valid values may include "early," "medium- early," "medium," "medium-late," or "late," — where crops having an "early" relative maturity are expected to mature relatively fast, and crops having a "late" relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops.

root_zone_available_water

Depth of water in the root zone that is readily available to the plant in inches or millimeters. This value is negative if the root zone soil moisture is less than the allowed depletion.

root_zone_depth

Depth to which the deepest roots of the plant extend in feet or meters.

root_zone_field_capacity

Volumetric water content of the root zone at field capacity expressed as a decimal.

root_zone_max_allowable _soil_moisture

Maximum value soil moisture in the root zone should attain following an irrigation event expressed as percent volumetric water content.

root_zone_min_allowable _soil_moisture

Minimum value to which root zone soil moisture should be allowed to dry to before irrigation is recommended, expressed as percent volumetric water content.

root_zone_saturation

Volumetric water content of the root zone at saturation expressed a decimal.

root_zone_soil_moisture

Volumetric water content of the root zone expressed as a decimal.

root_zone_wilting_point

Volumetric water content of the root zone at the permanent wilting point expressed as a decimal.

saturation

Volumetric water content of the X to Y cm depth soil layer at saturation expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

short_wave_radiation

Downwelling shortwave radiation flux in watts per square meter.

soil_moisture

Volumetric water content of the X to Y centimeter depth soil layer expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 0to10cm, 0to200cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

soil_temp

Soil temperature of the X to Y centimeter depth soil layer. Valid XtoYcm depths are: 0to2cm, 0to10cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

texture_classes

User supplied list of vertically varying texture class data in a soil column.

texture_classes/texture_class

USDA soil texture class of a soil layer expressed as an integer. Please refer to section USDA Texture Classes section of the Appendix for valid values of texture_class and texture_class_description.

texture_classes/ texture_class_depth

Starting level (top) of layer for texture class data in inches or centimeters. The ending level (bottom) of a layer is obtained from the next level’s starting depth. A complete column profile needs to extend to 2 meters. Profiles that do not extend a full 2 meters will have the deepest layer having an assumed ending depth of 2 meters. Any profile data extending beyond 2 meters will not be utilized.

texture_classes/texture _class_desc

Name of USDA soil texture class. Please refer to section USDA Texture Classes section of the Appendix for valid values of texture_class and texture_class_description.

units

Contains a mapping of response parameters from the data, field property and growth property sections to their respective unit.

wilting_point

Volumetric water content of the X to Y cm depth soil layer at the permanent wilting point expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

wind_speed

Wind speed at 10 meters above ground level in miles per hour or kilometers per hour.

irrigation_blackout_schedule

Description of schedule:
{start_timestamp}: unix timestamp when the schedule starts.
{duration}: integer; minimum 3600; Amount of seconds from start of an interval which blackout schedule applies.
{repeat_offset}: integer, minimum: 3600; schedule repeats every {repeat_offset} seconds.

Example irrigation_blackout_schedule:
[[1507568400, 14400, 604800],[1507554000, 432000, 604800],[1507352400, 172800, 604800],[1507392400, 112800, 204800]]

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/irrigation/custom_analysis/hourly/
recommendation?app_id=123&app_key=321&account_id=123
&user_id=xyz-123&growth_id=abc-def

Example Response

Response if growth is not currently registered or at least one custom field modeling run has not been completed.

{
    "data":{},
    "metadata":{
        "units":{},
        "last_scheduled_update":1515701490,
        "last_model_execution":"n/a",
        "growth_properties":{
            "max_moisture_refill":null,
            "plant_name":"corn",
            "plant_date":1488326400,
            "growth_id":"abc-123",
            "relative_maturity":"100",
            "plant_type":51,
            "max_moisture_depletion":null,
            "emergence_date":null
        },
        "field_properties":{
            "irrigation":{
                "water":{
                    "post_irrigation_delay":null,
                    "energy_use_rate":4,
                    "irrigation_blackout_schedule":[
                        [
                            1506891615,
                            14400,
                            604800
                        ]
                    ],
                    "energy_source":0,
                    "set_irrigation_unit":"in",
                    "water_unit":"ac-in",
                    "max_moisture_refill":-2.0,
                    "energy_unit":"kwh",
                    "flow_type":0,
                    "energy_cost":4,
                    "electricity_cost_schedule":[
                        [
                            1506891600,
                            3600,
                            10800,
                            1
                        ],
                        [
                            1506891600,
                            3600,
                            18000,
                            2
                        ],
                        [
                            1506891600,
                            3600,
                            7200,
                            3
                        ]
                    ],
                    "max_moisture_depletion":50.0,
                    "water_cost":27.15,
                    "set_irrigation_amount":0.3
                },
                "system":{
                    "drive_motor_unit":"kwh",
                    "flow_rate_unit":"gpm",
                    "drive_motor_rate":1.05,
                    "flow_rate":2.64,
                    "system_type":5,
                    "irrigated_area_unit":"ac",
                    "drive_motor_cost":0.15,
                    "irrigated_area":84.02
                }
            },
            "name":"Unnamed Farm",
            "created":1515699977,
            "field_id":"abc-def",
            "longitude":-99.422605,
            "acres":260,
            "latitude":40.470448,
            "hectares":105.22
        },
        "activities":{
            "irrigation":[],
            "soil_sample":[]
        }
    },
    "advisor":{
        "overall_efficiency":null,
        "recommended_activities":[],
        "estimated_soil_conditions":{}
    }
}

Response if growth is currently registered and at least one custom field modeling run has been completed.

{
    "data":{
        "1514836800":{
            "air_temp":6,
            "dew_point":0,
            "et0_acc_period":0,
            "forecast":"False",
            "precip_acc_period":0,
            "precip_prob":"n/a",
            "relative_humidity":74,
            "short_wave_radiation":213,
            "wind_speed":6,
            "soil_conditions":{
                "depth_0to10cm":{
                    "soil_moisture":0.25,
                    "abs_scaled_soil_moisture":0.53,
                    "soil_temp":18.18
                },
                "depth_0to200cm":{
                    "soil_moisture":0.27,
                    "abs_scaled_soil_moisture":0.49
                },
                "depth_0to2cm":{
                    "soil_moisture":0.25,
                    "abs_scaled_soil_moisture":0.52,
                    "soil_temp":16.93
                },
                "depth_2to5cm":{
                    "soil_moisture":0.25,
                    "abs_scaled_soil_moisture":0.53,
                    "soil_temp":17.91
                },
                "depth_5to10cm":{
                    "soil_moisture":0.25,
                    "abs_scaled_soil_moisture":0.53,
                    "soil_temp":18.83
                },
                "depth_10to20cm":{
                    "soil_moisture":0.26,
                    "abs_scaled_soil_moisture":0.55,
                    "soil_temp":21.17
                },
                "depth_20to40cm":{
                    "soil_moisture":0.26,
                    "abs_scaled_soil_moisture":0.53,
                    "soil_temp":26.51
                },
                "depth_40to70cm":{
                    "soil_moisture":0.27,
                    "abs_scaled_soil_moisture":0.45,
                    "soil_temp":33.4
                },
                "depth_70to100cm":{
                    "soil_moisture":0.28,
                    "abs_scaled_soil_moisture":0.48,
                    "soil_temp":36.76
                },
                "depth_100to200cm":{
                    "soil_moisture":0.28,
                    "abs_scaled_soil_moisture":0.5,
                    "soil_temp":41.99
                },
                "effective_root_zone_depth":0.1,
                "root_zone_depth":0.16,
                "root_zone_field_capacity":0.26,
                "root_zone_max_allowable_soil_moisture":0.23,
                "root_zone_min_allowable_soil_moisture":0.14,
                "root_zone_saturation":0.43,
                "root_zone_wilting_point":0.05,
                "et_acc_period":0,
                "root_zone_available_water":0.13,
                "root_zone_soil_moisture":0.25
            }
        },...
    },
    "metadata":{
        "units":{
            "elevation":"ft",
            "field_capacity":"ft^3/ft^3",
            "saturation":"ft^3/ft^3",
            "texture_class_depth":"in",
            "wilting_point":"ft^3/ft^3",
            "soil_moisture":"ft^3/ft^3",
            "abs_scaled_soil_moisture":"n/a",
            "soil_temp":"F",
            "effective_root_zone_depth":"ft",
            "root_zone_depth":"ft",
            "root_zone_field_capacity":"ft^3/ft^3",
            "root_zone_max_allowable_soil_moisture":"%",
            "root_zone_min_allowable_soil_moisture":"%",
            "root_zone_saturation":"ft^3/ft^3",
            "root_zone_wilting_point":"ft^3/ft^3",
            "et_acc_period":"in",
            "root_zone_available_water":"in",
            "root_zone_soil_moisture":"ft^3/ft^3",
            "overall_efficiency":"n/a",
            "air_temp":"F",
            "dew_point":"F",
            "et0_acc_period":"in",
            "forecast":"n/a",
            "precip_acc_period":"in",
            "precip_prob":"%",
            "relative_humidity":"%",
            "short_wave_radiation":"W/m^2",
            "wind_speed":"mph"
        },
        "field_properties":{
            "texture_classes":[{
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":0
                },
                {
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":0.79
                },
                {
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":1.97
                },
                {
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":3.94
                },
                {
                    "texture_class":6,
                    "texture_class_desc":"loam",
                    "texture_class_depth":7.87
                },
                {
                    "texture_class":9,
                    "texture_class_desc":"clay loam",
                    "texture_class_depth":15.75
                },
                {
                    "texture_class":9,
                    "texture_class_desc":"clay loam",
                    "texture_class_depth":27.56
                },
                {
                    "texture_class":9,
                    "texture_class_desc":"clay loam",
                    "texture_class_depth":39.37
                }
            ],
            "model_soil_properties":{
                "100to200cm":{
                    "field_capacity":0.37,
                    "wilting_point":0.1,
                    "saturation":0.47
                },
                "70to100cm":{
                    "field_capacity":0.37,
                    "wilting_point":0.1,
                    "saturation":0.47
                },
                "40to70cm":{
                    "field_capacity":0.37,
                    "wilting_point":0.1,
                    "saturation":0.47
                },
                "20to40cm":{
                    "field_capacity":0.3,
                    "wilting_point":0.07,
                    "saturation":0.44
                },
                "10to20cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                },
                "5to10cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                },
                "2to5cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                },
                "0to2cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                }
            },
            "elevation":2333.97,
            "longitude":-99.422605,
            "latitude":40.470448,
            "irrigation":{
                "water":{
                    "post_irrigation_delay":null,
                    "energy_use_rate":4,
                    "irrigation_blackout_schedule":[
                        [
                            1506891615,
                            14400,
                            604800
                        ]
                    ],
                    "energy_source":0,
                    "set_irrigation_unit":"in",
                    "water_unit":"ac-in",
                    "max_moisture_refill":-2.0,
                    "energy_unit":"kwh",
                    "flow_type":0,
                    "energy_cost":4,
                    "electricity_cost_schedule":[
                        [
                            1506891600,
                            3600,
                            10800,
                            1
                        ],
                        [
                            1506891600,
                            3600,
                            18000,
                            2
                        ],
                        [
                            1506891600,
                            3600,
                            7200,
                            3
                        ]
                    ],
                    "max_moisture_depletion":50.0,
                    "water_cost":27.15,
                    "set_irrigation_amount":0.3
                },
                "system":{
                    "drive_motor_unit":"kwh",
                    "flow_rate_unit":"gpm",
                    "drive_motor_rate":1.05,
                    "flow_rate":2.64,
                    "system_type":5,
                    "irrigated_area_unit":"ac",
                    "drive_motor_cost":0.15,
                    "irrigated_area":84.02
                }
            },
            "name":"Unnamed Farm",
            "created":1515699977,
            "field_id":"abc-def",
            "acres":260,
            "hectares":105.22
        },
        "last_scheduled_update":1515702617,
        "last_model_execution":1515702736,
        "growth_properties":{
            "max_moisture_refill":null,
            "plant_name":"corn",
            "plant_date":1488326400,
            "growth_id":"abc-123",
            "relative_maturity":"100",
            "plant_type":51,
            "max_moisture_depletion":null,
            "emergence_date":null
        },
        "activities":{
            "irrigation":[],
            "soil_sample":[]
        }
    },
    "advisor":{
        "overall_efficiency":null,
        "recommended_activities":[],
        "estimated_soil_conditions":{}
    }
}

Irrigation Recommendations with Custom Analysis Daily - v1.0

Through the Irrigation Recommendations with Custom Analysis Daily endpoint, users can obtain recommendations for irrigation activities, along with analyzed and forecast soil conditions and overall irrigation efficiency information customized to their field, irrigation system, and crop specifications. Associated field and growth metadata, daily weather conditions pertinent to irrigation, and daily soil conditions without the impacts of the irrigation recommendations are also provided. The endpoint returns data for the period of time spanning -9 days to +9 days, relative to the current date.

In order to receive irrigation recommendations for a growth, you must have configured the Irrigation System Properties on the field for which the growth resides. Irrigation System Properties which have been applied will alter custom field modeled soil conditions and generated irrigation recommendations. Please refer to the Get Irrigation System Properties, Modify Irrigation System Properties, and Delete Irrigation System Properties endpoints within the ClearAg Focus Soil Conditions.

Please see the Custom Field Modeling Supported Crops section of the Appendix for a complete list of currently supported crops.

URL Description

https://ag.us.clearapis.com/v1.0/crop_health/irrigation/custom_analysis/
daily/recommendation?app_id={string}&app_key={string}&account_id={string}
&user_id={string}&growth_id={string}&unitcode={string}

Request Parameters

Parameter Type Required Description

account_id

string

yes

A unique account ID provided by Iteris.

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

growth_id

string

yes

ID of crop growth provided by the Create Growth endpoint.

unitcode

string

no

Unit conversion set to be used. Default is "us-std." Valid values are "us-std," "us-std-precise," "si-std," and "si-std-precise." Precision based unitcodes expand values out to six decimal places.

user_id

string

yes

User ID provided by the ClearAg Accounts API user management endpoints.

Response Object (JSON)

Field Description

abs_scaled_soil_moisture

Moisture content of the X to Y centimeter depth soil layer, relative to saturation and "wilting point" thresholds for the soil type at the growth location. Valid values range from 0 to 1, where 0 indicates an estimated moisture level at the wilting point, and 1 indicates complete saturation. Therefore, values near 0 (1) indicate very dry (very wet) soils at the chosen location and time. Valid XtoYcm depths are: 0to2cm, 0to10cm, 0to200cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

acres

Area of the field in acres.

activities

User provided field/growth activity data associated with the growth. There is current support for irrigation and soil sample activities. For soil sample activities, only activities containing soil organic matter data are used and displayed.

activities/activity_time

Starting time of the activity expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/activity_time_end

Ending time of the activity expressed as an Unix timestamp. This value may be calculated from the provided irrigation system specifications using the system flow/discharge rate, irrigated area, and applied depth of water. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/activity_type

Enumeration value representing the kind of activity, such as irrigation.

activities/created

Time when the activity was created expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/depth_unit

Unit of measure for start_depth and end_depth parameters in inches or centimeters.

activities/drive_motor _energy_used

Total amount of energy used by the drive motors for an irrigation activity. Units are specified in the associated "drive_motor_energy_used_unit" parameter. Valid only for irrigation systems with drive motors.

activities/drive_motor _energy_used_cost

Total cost of the energy used by the drive motors for an irrigation activity. Valid only for irrigation systems with drive motors.

activities/drive_motor _energy_used_unit

Unit of energy used to power the drive motors for an irrigation activity. Valid value is 'kwh' and is valid only for irrigation systems with drive motors.

activities/end_depth

Ending level (bottom) of layer in a soil sample. Units are specified in the "activities/depth_unit" parameter.

activities/modified

Time when the activity was last modified expressed as an Unix timestamp. A "null" response denotes the activity has not been modified. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activities/organic_matter

Fractional portion of total soil composed of organic matter of a soil layer represented as a percentage from 0.0 to 100.0 as supplied by a user soil sample.

activities/pump_ energy_used

Total amount of energy used by the irrigation pump for an irrigation activity. Units are specified in the associated "pump_energy_used_unit" parameter. Valid only for pump irrigation delivery (flow_type=0).

activities/pump_energy _used_cost

Total cost of the energy used to power the irrigation pump for an irrigation activity. Valid only for pump irrigation delivery (flow_type=0).

activities/pump_energy _used_unit

Unit associated with the irrigation pump’s energy source to measure energy usage for an irrigation activity in 'kwh' for electric sources, 'gal' or 'l' for diesel and LPG sources, and 'lb,' 'kg,' 'MMBtu,' or 'Mcf' for natural gas sources. Valid only if an irrigation system is configured and configured with pump irrigation delivery (flow_type=0).

activities/start_depth

Starting level (top) of layer in a soil sample. Units are specified in the "activities/depth_unit" parameter.

activities/unit

The unit of measure of the depth of water applied from an irrigation in inches or millimeters.

activities/value

The depth of water applied from an irrigation. Units are specified in activities/unit. This value may be calculated from provided irrigation system specifications using the system flow/discharge rate, irrigated area, and activity run time frame.

activities/water _used

Total volume of water used for an irrigation activity. Units are specified in the associated "water_used_unit" parameter.

activities/water_ used_cost

Total cost of water used for an irrigation activity.

activities/water_ used_unit

Volumetric unit of the total amount of water used for an irrigation activity in 'ac-in' or 'm^3.'

advisor

Section contains data pertaining to the usage of the irrigation advisor. This includes an overall irrigation efficiency, recommended activities, and time series data representing expected conditions if the recommended irrigation activities are followed.

air_temp_avg

24-hour average air temperature at two meters above ground level in F or C.

air_temp_max

24-hour maximum air temperature at two meters above ground level in F or C.

air_temp_min

24-hour minimum air temperature at two meters above ground level in F or C.

dew_point_avg

24-hour average dewpoint temperature at two meters above ground level in F or C.

data

Section contains time series data that represent expected conditions if the irrigation recommendations are not implemented.

dew_point_max

24-hour maximum dewpoint temperature at two meters above ground level in F or C.

dew_point_min

24-hour minimum dewpoint temperature at two meters above ground level in F or C.

effective_root _zone_depth

Depth of soil from which most water and nutrients are drawn from by the plant’s roots in feet or meters.

elevation

Field elevation in feet or meters.

emergence_date

The time valid near plant emergence, expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

et0_acc_period

24-hour accumulated reference evapotranspiration in inches or millimeters. Reference evapotranspiration is the amount of water that would transpire and evaporate from a hypothetical reference crop, assuming that ample water is available. In this case, short green grass is used as the reference crop.

et_acc_period

24-hour accumulated depth of water in inches or millimeters, actually evapotranspired, based on the particular crop, soil, and weather conditions of the custom analysis.

field_activity_id

ID of an activity on this field pertinent to this growth.

field_capacity

Volumetric water content of the X to Y cm depth soil layer at field capacity expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

field_id

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

field_properties/irrigation

Field irrigation system specifications. Please refer to the Get Irrigation System Properties, Modify Irrigation System Properties, and Delete Irrigation System Properties endpoints within the ClearAg Focus Soil Conditions.

forecast

Boolean value if the accompanying data are forecast data. An output of "true" means the data are forecasted.

growth_id

ID of crop growth queried.

hectares

Area of the field in hectares.

last_model_execution

Last completed model run expressed as an Unix timestamp. If this is "n/a," then the model has not completed a first time run yet. If this is greater than last_scheduled_update, the response represents the most current state related to data inputs. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

last_scheduled_update

Most recent scheduled model run expressed as an Unix timestamp. If this is greater than last_model_execution, the response may not represent the most current state related to data inputs. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

latitude

Latitude coordinate near the center of the field in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field.

longitude

Longitude coordinate near the center of the field in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field.

max_moisture_refill

Desired maximum amount of refill to be provided by irrigation recommendations, expressed as percent depletion from field capacity to wilting point. The default value is 0%, indicating recommended irrigation activities will try to not exceed field capacity. Valid values range from –50% (an increase in the allowed maximum soil moisture) to 50% (a decrease in the allowed maximum soil moisture). Negative values represent refill amounts that exceed field capacity and are internally limited to the soil-specific saturation point.

max_moisture_ depletion

Desired driest state the soil is allowed to attain before an irrigation recommendation is triggered, expressed as percent depletion from field capacity to wilting point. Default values are optimized to the soil composition, crop type, and crop growth stage, with typical values of around 50%. Valid values range from 0% (indicating soil moisture should not be allowed to fall below field capacity) to 100% (soil moisture is allowed to reach the permanent wilting point, at which crop death will occur). Practical values typically range from 30 to 70%. Values are internally limited to be greater than the max_moisture_refill value.

name

User given name of the field, if applicable.

overall_efficiency

Efficiency of the irrigation recommendations in terms of water retained in the root zone or transpired as a proportion of total applied water, expressed as a percentage.

plant_date

Approximate time the crop was planted expressed as an Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

plant_depth

The depth that the crop was planted in inches or centimeters.

plant_name

Name of the crop plant.

plant_type

Enumeration value representing the specific variety of crop planted.

precip_acc_period

24-hour accumulated precipitation (liquid equivalent across all phases) in inches or millimeters.

precip_prob

Probability of precipitation expressed as a percentage. Valid values occur only during the forecast period; historically will return "n/a."

relative_humidity_avg

24-hour average relative humidity at two meters above ground level expressed as a percentage.

relative_humidity_max

24-hour maximum relative humidity at two meters above ground level expressed as a percentage.

relative_humidity_min

24-hour minimum relative humidity at two meters above ground level expressed as a percentage.

relative_maturity

Gauges how long it takes for the crop to mature. Depending on the crop, valid values may include "early," "medium- early," "medium," "medium-late," or "late," — where crops having an "early" relative maturity are expected to mature relatively fast, and crops having a "late" relative maturity are expected to mature relatively slowly — or numerical values ranging from 70 for low-relative maturity crops to 130 for high-relative maturity crops.

root_zone_available_water

Depth of water in the root zone that is readily available to the plant in inches or millimeters. This value is negative if the root zone soil moisture is less than the allowed depletion.

root_zone_depth

Depth to which the deepest roots of the plant extend in feet or meters.

root_zone_field_capacity

Volumetric water content of the root zone at field capacity expressed as a decimal.

root_zone_max_allowable _soil_moisture

Maximum value soil moisture in the root zone should attain following an irrigation event expressed as percent volumetric water content.

root_zone_min_allowable _soil_moisture

Minimum value to which root zone soil moisture should be allowed to dry to before irrigation is recommended, expressed as percent volumetric water content.

root_zone_saturation

Volumetric water content of the root zone at saturation expressed a decimal.

root_zone_soil_moisture

Volumetric water content of the root zone expressed as a decimal.

root_zone_wilting_point

Volumetric water content of the root zone at the permanent wilting point expressed as a decimal.

saturation

Volumetric water content of the X to Y cm depth soil layer at saturation expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

short_wave_radiation _avg

24-hour average downwelling shortwave radiation flux in watts per square meter.

short_wave_radiation _max

24-hour maximum downwelling shortwave radiation flux in watts per square meter.

short_wave_radiation _min

24-hour minimum downwelling shortwave radiation flux in watts per square meter.

soil_moisture

24-hour average volumetric water content of the X to Y centimeter depth soil layer expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 0to10cm, 0to200cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

soil_temp

24-hour average soil temperature of the X to Y centimeter depth soil layer. Valid XtoYcm depths are: 0to2cm, 0to10cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

soil_temp_max

24-hour maximum soil temperature of the X to Y centimeter depth soil layer. Valid XtoYcm depths are: 0to2cm, 0to10cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

soil_temp_min

24-hour minimum soil temperature of the X to Y centimeter depth soil layer. Valid XtoYcm depths are: 0to2cm, 0to10cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

texture_classes

User supplied list of vertically varying texture class data in a soil column.

texture_classes/texture_class

USDA soil texture class of a soil layer expressed as an integer. Please refer to section USDA Texture Classes section of the Appendix for valid values of texture_class and texture_class_description.

texture_classes/ texture_class_depth

Starting level (top) of layer for texture class data in inches or centimeters. The ending level (bottom) of a layer is obtained from the next level’s starting depth. A complete column profile needs to extend to 2 meters. Profiles that do not extend a full 2 meters will have the deepest layer having an assumed ending depth of 2 meters. Any profile data extending beyond 2 meters will not be utilized.

texture_classes/texture _class_desc

Name of USDA soil texture class. Please refer to section USDA Texture Classes section of the Appendix for valid values of texture_class and texture_class_description.

units

Contains a mapping of response parameters from the data, field property and growth property sections to their respective unit.

wilting_point

Volumetric water content of the X to Y cm depth soil layer at the permanent wilting point expressed as a decimal. Valid XtoYcm depths are: 0to2cm, 2to5cm, 5to10cm, 10to20cm, 20to40cm, 40to70cm, 70to100cm, and 100to200cm.

wind_speed_avg

24-hour average wind speed at 10 meters above ground level in miles per hour or kilometers per hour.

wind_speed_max

24-hour maximum wind speed at 10 meters above ground level in miles per hour or kilometers per hour.

wind_speed_min

24-hour minimum wind speed at 10 meters above ground level in miles per hour or kilometers per hour.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/irrigation/custom_analysis/
daily/recommendation?app_id=123&app_key=321&account_id=123
&user_id=xyz-123&growth_id=abc-def

Example Response

Response if growth is not currently registered or at least one custom field modeling run has not been completed.

{
    "data":{},
    "metadata":{
        "units":{},
        "last_scheduled_update":1515701490,
        "last_model_execution":"n/a",
        "growth_properties":{
            "max_moisture_refill":null,
            "plant_name":"corn",
            "plant_date":1488326400,
            "growth_id":"abc-123",
            "relative_maturity":"100",
            "plant_type":51,
            "max_moisture_depletion":null,
            "emergence_date":null
        },
        "field_properties":{
            "irrigation":{
                "water":{
                    "post_irrigation_delay":null,
                    "energy_use_rate":4,
                    "irrigation_blackout_schedule":[
                        [
                            1506891615,
                            14400,
                            604800
                        ]
                    ],
                    "energy_source":0,
                    "set_irrigation_unit":"in",
                    "water_unit":"ac-in",
                    "max_moisture_refill":-2.0,
                    "energy_unit":"kwh",
                    "flow_type":0,
                    "energy_cost":4,
                    "electricity_cost_schedule":[
                        [
                            1506891600,
                            3600,
                            10800,
                            1
                        ],
                        [
                            1506891600,
                            3600,
                            18000,
                            2
                        ],
                        [
                            1506891600,
                            3600,
                            7200,
                            3
                        ]
                    ],
                    "max_moisture_depletion":50.0,
                    "water_cost":27.15,
                    "set_irrigation_amount":0.3
                },
                "system":{
                    "drive_motor_unit":"kwh",
                    "flow_rate_unit":"gpm",
                    "drive_motor_rate":1.05,
                    "flow_rate":2.64,
                    "system_type":5,
                    "irrigated_area_unit":"ac",
                    "drive_motor_cost":0.15,
                    "irrigated_area":84.02
                }
            },
            "name":"Unnamed Farm",
            "created":1515699977,
            "field_id":"abc-def",
            "longitude":-99.422605,
            "acres":260,
            "latitude":40.470448,
            "hectares":105.22
        },
        "activities":{
            "irrigation":[],
            "soil_sample":[]
        }
    },
    "advisor":{
        "overall_efficiency":null,
        "recommended_activities":[],
        "estimated_soil_conditions":{}
    }
}

Response if growth is currently registered and at least one custom field modeling run has been completed.

{
    "data":{
        "2018-01-02":{
            "air_temp_max":23,
            "air_temp_min":-5,
            "air_temp_avg":9,
            "dew_point_max":14,
            "dew_point_min":-8,
            "dew_point_avg":2,
            "et0_acc_period":0.02,
            "forecast":"False",
            "precip_acc_period":0,
            "precip_prob":"n/a",
            "short_wave_radiation_avg":112,
            "short_wave_radiation_max":487,
            "short_wave_radiation_min":0,
            "relative_humidity_max":89,
            "relative_humidity_min":60,
            "relative_humidity_avg":74,
            "wind_speed_max":14,
            "wind_speed_min":1,
            "wind_speed_avg":9,
            "soil_conditions":{
                "depth_0to10cm":{
                    "soil_moisture":0.25,
                    "abs_scaled_soil_moisture":0.53,
                    "soil_temp":17.07,
                    "soil_temp_max":19.91,
                    "soil_temp_min":11.86
                },
                "depth_0to200cm":{
                    "soil_moisture":0.27,
                    "abs_scaled_soil_moisture":0.49
                },
                "depth_0to2cm":{
                    "soil_moisture":0.25,
                    "abs_scaled_soil_moisture":0.52,
                    "soil_temp":15.06,
                    "soil_temp_max":18.67,
                    "soil_temp_min":11.86
                },
                "depth_2to5cm":{
                    "soil_moisture":0.25,
                    "abs_scaled_soil_moisture":0.53,
                    "soil_temp":16.79,
                    "soil_temp_max":19.36,
                    "soil_temp_min":14.71
                },
                "depth_5to10cm":{
                    "soil_moisture":0.25,
                    "abs_scaled_soil_moisture":0.53,
                    "soil_temp":18.04,
                    "soil_temp_max":19.91,
                    "soil_temp_min":16.52
                },
                "depth_10to20cm":{
                    "soil_moisture":0.26,
                    "abs_scaled_soil_moisture":0.55,
                    "soil_temp":20.45,
                    "soil_temp_max":21.43,
                    "soil_temp_min":19.61
                },
                "depth_20to40cm":{
                    "soil_moisture":0.26,
                    "abs_scaled_soil_moisture":0.53,
                    "soil_temp":25.2,
                    "soil_temp_max":25.86,
                    "soil_temp_min":24.72
                },
                "depth_40to70cm":{
                    "soil_moisture":0.27,
                    "abs_scaled_soil_moisture":0.45,
                    "soil_temp":33.39,
                    "soil_temp_max":33.39,
                    "soil_temp_min":33.38
                },
                "depth_70to100cm":{
                    "soil_moisture":0.28,
                    "abs_scaled_soil_moisture":0.48,
                    "soil_temp":36.63,
                    "soil_temp_max":36.7,
                    "soil_temp_min":36.56
                },
                "depth_100to200cm":{
                    "soil_moisture":0.28,
                    "abs_scaled_soil_moisture":0.5,
                    "soil_temp":41.74,
                    "soil_temp_max":41.87,
                    "soil_temp_min":41.6
                },
                "effective_root_zone_depth":0.1,
                "root_zone_depth":0.16,
                "root_zone_field_capacity":0.26,
                "root_zone_max_allowable_soil_moisture":0.23,
                "root_zone_min_allowable_soil_moisture":0.14,
                "root_zone_saturation":0.43,
                "root_zone_wilting_point":0.05,
                "et_acc_period":0.01,
                "root_zone_available_water":0.13,
                "root_zone_soil_moisture":0.25
            }
        },...
    },
    "metadata":{
        "units":{
            "elevation":"ft",
            "field_capacity":"ft^3/ft^3",
            "saturation":"ft^3/ft^3",
            "texture_class_depth":"in",
            "wilting_point":"ft^3/ft^3",
            "soil_moisture":"ft^3/ft^3",
            "abs_scaled_soil_moisture":"n/a",
            "soil_temp":"F",
            "soil_temp_max":"F",
            "soil_temp_min":"F",
            "effective_root_zone_depth":"ft",
            "root_zone_depth":"ft",
            "root_zone_field_capacity":"ft^3/ft^3",
            "root_zone_max_allowable_soil_moisture":"%",
            "root_zone_min_allowable_soil_moisture":"%",
            "root_zone_saturation":"ft^3/ft^3",
            "root_zone_wilting_point":"ft^3/ft^3",
            "et_acc_period":"in",
            "root_zone_available_water":"in",
            "root_zone_soil_moisture":"ft^3/ft^3",
            "overall_efficiency":"n/a",
            "air_temp_max":"F",
            "air_temp_min":"F",
            "air_temp_avg":"F",
            "dew_point_max":"F",
            "dew_point_min":"F",
            "dew_point_avg":"F",
            "et0_acc_period":"in",
            "forecast":"n/a",
            "precip_acc_period":"in",
            "precip_prob":"%",
            "short_wave_radiation_avg":"W/m^2",
            "short_wave_radiation_max":"W/m^2",
            "short_wave_radiation_min":"W/m^2",
            "relative_humidity_max":"%",
            "relative_humidity_min":"%",
            "relative_humidity_avg":"%",
            "wind_speed_max":"mph",
            "wind_speed_min":"mph",
            "wind_speed_avg":"mph"
        },
        "field_properties":{
            "texture_classes":[{
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":0
                },
                {
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":0.79
                },
                {
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":1.97
                },
                {
                    "texture_class":3,
                    "texture_class_desc":"sandy loam",
                    "texture_class_depth":3.94
                },
                {
                    "texture_class":6,
                    "texture_class_desc":"loam",
                    "texture_class_depth":7.87
                },
                {
                    "texture_class":9,
                    "texture_class_desc":"clay loam",
                    "texture_class_depth":15.75
                },
                {
                    "texture_class":9,
                    "texture_class_desc":"clay loam",
                    "texture_class_depth":27.56
                },
                {
                    "texture_class":9,
                    "texture_class_desc":"clay loam",
                    "texture_class_depth":39.37
                }
            ],
            "model_soil_properties":{
                "100to200cm":{
                    "field_capacity":0.37,
                    "wilting_point":0.1,
                    "saturation":0.47
                },
                "70to100cm":{
                    "field_capacity":0.37,
                    "wilting_point":0.1,
                    "saturation":0.47
                },
                "40to70cm":{
                    "field_capacity":0.37,
                    "wilting_point":0.1,
                    "saturation":0.47
                },
                "20to40cm":{
                    "field_capacity":0.3,
                    "wilting_point":0.07,
                    "saturation":0.44
                },
                "10to20cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                },
                "5to10cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                },
                "2to5cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                },
                "0to2cm":{
                    "field_capacity":0.26,
                    "wilting_point":0.05,
                    "saturation":0.43
                }
            },
            "elevation":2333.97,
            "longitude":-99.422605,
            "latitude":40.470448,
            "irrigation":{
                "water":{
                    "post_irrigation_delay":null,
                    "energy_use_rate":4,
                    "irrigation_blackout_schedule":[
                        [
                            1506891615,
                            14400,
                            604800
                        ]
                    ],
                    "energy_source":0,
                    "set_irrigation_unit":"in",
                    "water_unit":"ac-in",
                    "max_moisture_refill":-2.0,
                    "energy_unit":"kwh",
                    "flow_type":0,
                    "energy_cost":4,
                    "electricity_cost_schedule":[
                        [
                            1506891600,
                            3600,
                            10800,
                            1
                        ],
                        [
                            1506891600,
                            3600,
                            18000,
                            2
                        ],
                        [
                            1506891600,
                            3600,
                            7200,
                            3
                        ]
                    ],
                    "max_moisture_depletion":50.0,
                    "water_cost":27.15,
                    "set_irrigation_amount":0.3
                },
                "system":{
                    "drive_motor_unit":"kwh",
                    "flow_rate_unit":"gpm",
                    "drive_motor_rate":1.05,
                    "flow_rate":2.64,
                    "system_type":5,
                    "irrigated_area_unit":"ac",
                    "drive_motor_cost":0.15,
                    "irrigated_area":84.02
                }
            },
            "name":"Unnamed Farm",
            "created":1515699977,
            "field_id":"abc-def",
            "acres":260,
            "hectares":105.22
        },
        "last_scheduled_update":1515702617,
        "last_model_execution":1515702736,
        "growth_properties":{
            "max_moisture_refill":null,
            "plant_name":"corn",
            "plant_date":1488326400,
            "growth_id":"abc-123",
            "relative_maturity":"100",
            "plant_type":51,
            "max_moisture_depletion":null,
            "emergence_date":null
        },
        "activities":{
            "irrigation":[],
            "soil_sample":[]
        }
    },
    "advisor":{
        "overall_efficiency":null,
        "recommended_activities":[],
        "estimated_soil_conditions":{}
    }
}

Modify Irrigation System Properties - v1.0

Please refer to the ClearAg Focus Soil Conditions.

Get Irrigation System Properties - v1.0

Please refer to the ClearAg Focus Soil Conditions.

Delete Irrigation System Properties - v1.0

Please refer to the ClearAg Focus Soil Conditions.

Add Irrigation Activity - v1.0

Please refer to the ClearAg Focus Soil Conditions.

Get Irrigation Activity By ID - v1.0

Please refer to the ClearAg Focus Soil Conditions.

Irrigation Activity - Get By Growth - v1.0

Please refer to the ClearAg Focus Soil Conditions.

Growth Activity: Irrigation Activity - Modify - v1.0

Please refer to the ClearAg Focus Soil Conditions.

Growth Activity: Irrigation Activity - Delete - v1.0

Please refer to the ClearAg Focus Soil Conditions.

Variable Rate Irrigation

Locations that have significant in-field variability may benefit from a management zone approach whereby irrigation amounts are applied specific to conditions in each zone. The following endpoints support such a variable rate irrigation (VRI) approach by allowing users to upload a map of zones (zone map) and then receive recommendations that are specific for each zone on a per field per event basis. Users can employ different VRI strategies to trigger irrigation events including a driest zone trigger approach as well as triggering by conditions within a user specified zone. The recommendation output will list irrigation recommendations for each zone on a per event basis. Irrigation conditions data provides soil data output for each zone within the field. Finally, the soil texture class and organic matter content are configurable for each zone to assure maximum user feedback on the actual zone conditions.

Get Irrigation Zone Activity - v1.0

This endpoint allows users to receive a target irrigation zone activity. Zone data will only include data for a single active zone map. The active zone map is either the provided zone_map_id or the zone map configured for a zone aware growth.

Please note that if an irrigation zone activity was created manually (not via Shapefile/GeoJSON), the activity can only be retrieved when the zone map used for its creation is specified; the target growth must be assigned the same zone map use to create the activity.

URL Description

https://ag.us.clearapis.com/v1.0/zone/activity/irrigation/get?app_id={string}
&app_key={string}&field_activity_id={string}&account_id={string}
&user_id={string}&growth_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

Target irrigation activity ID.

account_id

string

yes

Your Account ID.

user_id

string

yes

User must have read privileges for field in which the target growth is assigned.

growth_id

string

yes

The depths of irrigation applied to the target growths zone map will be returned. ** must be zone aware growth

Response Object (JSON)

Field Description

created

Timestamp when the activity was created. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

field_activity_id

ID of activity.

modified

Timestamp of when the activity was last modified, with 'null' denoting that the activity has not been modified. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

activity_type

Enumeration value of activity.

activity_time

Timestamp of when the activity took place. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

unit

Unit of measure for irrigation.

activity_time_end

Timestamp activity ended.

zone_data

Object with the format: {<active_zone_map_id>: [[<zone_id>, <value>],…​]}. **If this section is empty, activity map extraction has not been performed.

Example Request

https://ag.us.clearapis.com/v1.0/zone/activity/irrigation/get?app_id=123
&app_key=321&account_id=321&user_id=456&growth_id=abc-123

Example Response

{
  "field_activity_id":"be5",
  "created":1535396407,
  "zone_data":{
    "31c":[
      [
        "02d",
        13.0316873243
      ],
      [
        "5ca",
        12.4573337864
      ],
      [
        "62b",
        12.5006451756
      ],...
    ]
  },
  "field_id":"e2a",
  "modified":null,
  "activity_time":1535396407,
  "activity_time_end":1535396407,
  "unit":"in",
  "activity_type":311
}

Create Zone Aware Irrigation Activity - v1.0

This endpoint allows the user to create a new zone aware irrigation activity.

URL Description

https://ag.us.clearapis.com/v1.0/zone/activity/irrigation/create?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&activity_time={timestamp}&activity_time_end={timestamp}&growth_id={string}
&zone_activities=[[{string},23]]&unit={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.

activity_time

timestamp

yes

Start time of the irrigation activity, formatted as an epoch timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

activity_time_end

timestamp

yes

End time of the irrigation activity, formatted as an epoch timestamp.

growth_id

string

yes

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

zone_activities

string

yes

A list of tuples containing zone_id, value pairs in the format [(“zone_id”, value),…​] where zone_id is a valid UUID and value is null or a float value greater than 0.0

unit

string

yes

This value can be "cm," "in," or "mm."

Response Object

Returns the 'field_activity_id' that was created.

Example Request

https://ag.us.clearapis.com/v1.0/zone/activity/irrigation/create?
app_id=123&app_key=321&account_id=abc-123&user_id=def-123&activity_time=1532621922
&activity_time_end=1532625522&growth_id=123-aaa&zone_activities=[[“cba-321”,1.3]]
&unit=in

Example Response

def-345

Modify Zone Aware Irrigation Activity - v1.0

This endpoint allows the user to modify a zone aware irrigation activity.

URL Description

https://ag.us.clearapis.com/v1.0/zone/activity/irrigation/modify?app_id={string}
&app_key={string}&field_activity_id={string}&account_id={string}&user_id={string}
&zone_activities=[[“{string}”,{float}]]&unit=in

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

Unique ID for the activity to be modified.

activity_time

timestamp

no

Start time of the irrigation activity, formatted as an epoch timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

activity_time_end

timestamp

no

End time of the irrigation activity, formatted as an epoch timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

zone_activities

string

no

A list of tuples containing zone_id, value pairs in the format [(“zone_id”, value),…​] where zone_id is a valid UUID and value is null or a float value greater than 0.0.

unit

string

no

This value can be "cm," "in," or "mm." (This is not case sensitive, but is stored as lowercase.)

Response Object

Returns "true" on success.

Example Request

https://ag.us.clearapis.com/v1.0/zone/activity/irrigation/modify?
app_id=123&app_key=321&field_activity_id=abc-123&account_id=cba-123
&user_id=bcd-234&zone_activities=[[“aaa-123”,4.56]]&unit=cm

Example Response

true

Add Irrigation Activity From Activity Map - v1.0

This endpoint allows a user to create an irrigation activity from a shapefile or GeoJSON file.

URL Description

https://ag.us.clearapis.com/v1.0/zone/activity/irrigation/map/create?app_id={string}
&app_key={string}&user_id={string}&account_id={string}&zone_map_id={string}
&growth_id={string}&unit={string}&activity_time={timestamp}
&activity_time_end={timestamp}&value_property={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.

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.

account_id

string

yes

Your Accounts API account ID.

growth_id

string

yes

The target growth must be zone aware. The activity_map will be applied to the growth’s zone map.

unit

string

yes

Allowed values: mm, cm, or in.

activity_time

timestamp

yes

Start time of the irrigation activity, formatted as an epoch timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

activity_time_end

timestamp

yes

** must be after activity_time

value_property

string

yes

Case sensitive name of the the field/key where the irrigation amount is stored in the uploaded activity map. For shapefiles this is the name of the field where irrigation value is stored. For GeoJSON, this is the key from the Feature’s properties section where irrigation value is stored. **If the field/key is missing from the activity map, the irrigation value will default to 0.0.

file

file

yes

This is the activity map. Accepted file types are shapefile or GeoJSON/JSON. Accepted file extensions are .json, .geojson, .tgz, tar.gz and .zip. For this parameter HTTP POST method must be used and the file is expected to be provided in the form-data section of the request.

Response Object

Returns ID of created irrigation activity.

Example Request

curl -X POST \
'https://ag.us.clearapis.com/v1.0/zone/activity/irrigation/map/create?growth_id=16a&account_id=292&user_id=4fcc&activity_time=1534528549&activity_time_end=1534528550&unit=mm&value_property=value' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'content-type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW' \
-F file=@/path/to/activity_map/irrigation-activity.geojson

Example Response

888-444

Custom Field Zone Modeling Hourly Soil - 1.0

Through the Custom Field Zone Modeling Hourly Soil endpoint users can obtain hourly soil temperature and moisture data valid for a user-defined time range of a specified growth custom to their field zone map, irrigation, and crop specifications. Custom field zone modeling data availability ranges from the first of the previous year and the most current year up to 240 hours from the current hour. The query time range is range inclusive with a maximum range per request of 240 hours.

URL Description

https://ag.us.clearapis.com/v1.0/zone/soil_conditions/custom_analysis/hourly?
app_id={string}&app_key={string]&account_id={string}&user_id={string}
&growth_id={string}&start={timestamp}&end={timestamp}&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 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

Provided by the Create Growth endpoint. Target Growth must be zone aware.

start

timestamp

yes

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

end

timestamp

yes

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

unitcode

string

no

default is "us-std."

Response Object (JSON)

Field Description

zone_data

Contains per field zone data using the zone id as the key.

soil_conditons/temp

Array of 1-hour average temperature of the layer between x and y cm. Values are ordered by layer ['0to2cm,' '2to5cm,' '5to10cm,' '10to20cm,' '20to40cm,' '40to70cm,' '70to100cm,' '100to200cm']

soil_conditons/moisture

Array of 1-hour average moisture content of the layer between x and y cm. Values are ordered by layer ['0to2cm,' '2to5cm,' '5to10cm,' '10to20cm,' '20to40cm,' '40to70cm,' '70to100cm,' '100to200cm']

et_acc_period

Accumulated depth of water in inches or millimeters, actually evapotranspired, based on the particular crop, soil, and weather conditions of the custom analysis.

last_model_execution

Unix timestamp of the last completed model run. If this is "n/a," then the model has not been run yet. If this is greater than metadata/last_scheduled_update, the data should represent the most current state. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

last_scheduled_update

Unix timestamp of the most recent scheduled model run. If this is greater than metadata/last_model_execution, the data may not represent the most current state. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

activity_time

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

activity_time_end

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

irrigation_value

The applied amount resulting from an irrigation activity.

water_used

Total volume of water used for an irrigation activity. Units are specified in the associated "water_used_unit" parameter. Valid only if an irrigation system is configured.

water_used_cost

Total cost of water used for an irrigation activity. Valid only if an irrigation system is configured.

pump_energy_used

Total amount of energy used by the irrigation pump for an irrigation activity. Units are specified in the associated "pump_energy_used_unit" parameter. Valid only if an irrigation system is configured and configured with pump irrigation delivery (flow_type=0).

pump_energy_used_cost

Total cost of the energy used to power the irrigation pump for an irrigation activity. Valid only if an irrigation system is configured and configured with pump irrigation delivery (flow_type=0).

drive_motor_energy_used

Total amount of energy used by the drive motors for an irrigation activity. Valid only if an irrigation system is configured and configured with drive motors.

drive_motor_energy_used_cost

Total cost of the energy used by the drive motors for an irrigation activity. Valid only if an irrigation system is configured and configured with drive motors.

metatdata/units

This section contains a key value mapping between values in data and the applicable measurement unit.

root_zone/available_water

Estimated depth of water in the root zone that is readily available to the plant in inches or millimeters. This value is negative if the root zone soil moisture is less than the allowed depletion, as set by the user or as determined based on soil texture class.

root_zone/soil_moisture

Volumetric water content of the root zone expressed as a decimal.

root_zone/effective_depth

Depth of soil from which most water and nutrients are drawn from by the plant’s roots in feet or meters.

root_zone/depth

Depth to which the deepest roots of the plant extend in feet or meters.

root_zone/field_capacity

Volumetric water content of the root zone at field capacity expressed as a decimal.

root_zone/max_allowable_ soil_moisture

Maximum value soil moisture in the root zone should attain following an irrigation event expressed as percent volumetric water content.

root_zone/min_allowable_ soil_moisture

Minimum value to which root zone soil moisture should be allowed to dry to before irrigation is recommended, expressed as percent volumetric water content.

root_zone/saturation

Volumetric water content of the root zone at saturation expressed as a decimal.

root_zone/wilting_point

Volumetric water content of the root zone at the permanent wilting point expressed as a decimal.

Example Request

https://ag.us.clearapis.com/v1.0/zone/soil_conditions/custom_analysis/hourly?
app_id=456&app_key=789&account_id=123&user_id=xyz-123&growth_id=bcd-def
&start=1388534400&end=1388707200

Example Response

Response if growth is not currently registered.

{
  "metadata":{
    "units":{},
    "last_scheduled_update":1545413091,
    "last_model_execution":"n/a"
  },
  "zone_data":{}
}

Response if growth is currently registered and at least one custom field modeling run has been performed.

 {
  "metadata":{
    "units":{
      "field_capacity":"ft^3/ft^3",
      "saturation":"ft^3/ft^3",
      "wilting_point":"ft^3/ft^3",
      "drive_motor_energy_used":"kwh",
      "moisture":"ft^3/ft^3",
      "et_acc_period":"in",
      "available_water":"in",
      "soil_moisture":"ft^3/ft^3",
      "temp":"F",
      "effective_depth":"ft",
      "depth":"ft",
      "max_allowable_soil_moisture":"%",
      "min_allowable_soil_moisture":"%",
      "temp_max":"F",
      "temp_min":"F",
      “irrigation_value”:"in",
      "water_used":"ac-in",
      "pump_energy_used":"kwh"

    },
    "last_scheduled_update":1545411603,
    "last_model_execution":1545411611
  },
  "zone_data":{
    "abcd-1":{
      "soil_conditions":{
        "1510099200":{
          "moisture":[
            0.05,
            0.05,
            0.05,
            0.05,
            0.05,
            0.05,
            0.05,
            0.06
          ],
          "et_acc_period":0,
          "root_zone":{
            "available_water":0,
            "soil_moisture":0.05,
            "effective_depth":1.8,
            "depth":4.89,
            "field_capacity":0.26,
            "max_allowable_soil_moisture":0.37,
            "min_allowable_soil_moisture":0.05,
            "saturation":0.43,
            "wilting_point":0.05
          },
          "temp":[
            60.94,
            62,
            62.76,
            64.3,
            67.52,
            72.31,
            76.17,
            80.69
          ]
        },
        "21510102800":{...
        }
      },
      "activities":{
        "irrigation":[{
          "irrigation_value":0.135,
          "field_activity_id":"def-1",
          "created":1544085315,
          "modified":null,
          "activity_time_end":1541383200,
          "activity_time":1541376000,
          "water_used":4.23,
          "water_used_cost":0.02,
          "pump_energy_used":1,
          "pump_energy_used_cost":0.15,
          "drive_motor_energy_used":1.34,
          "drive_motor_energy_used_cost":0.16
        }],
        "soil_sample":[]
      }
    },
    "abcd-2":{...
    },
    "abcd-3":{...
    },
  }
 }

Custom Field Zone Modeling Daily Soil - 1.0

Through the Custom Field Zone Modeling Daily Soil endpoint users can obtain daily soil temperature and moisture data valid for a user-defined time range of a specified growth custom to their field zone map, irrigation, and crop specifications. Custom field zone modeling data availability ranges from the first of the previous year and the most current year up to +9 days of the current date.

URL Description

https://ag.us.clearapis.com/v1.0/zone/soil_conditions/custom_analysis/daily?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&start={timestamp}&end={timestamp}&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 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

Provided by the Create Growth endpoint. Target Growth must be zone aware.

start

timestamp

yes

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

end

timestamp

yes

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

unitcode

string

no

default is "us-std."

Response Object (JSON)

Field Description

zone_data

Contains per field zone data using the zone id as the key.

soil_conditons/moisture

Array of 24-hour average moisture content of the layer between x and y cm. Values are ordered by layer ['0to2cm,' '2to5cm,' '5to10cm,' '10to20cm,' '20to40cm,' '40to70cm,' '70to100cm,' '100to200cm']

soil_conditons/temp

Array of 24-hour average temperature of the layer between x and y cm. Values are ordered by layer ['0to2cm,' '2to5cm,' '5to10cm,' '10to20cm,' '20to40cm,' '40to70cm,' '70to100cm,' '100to200cm']

soil_conditons/temp_max

Array of 24-hour maximum temperature of the layer between x and y cm.. Values are ordered by layer ['0to2cm,' '2to5cm,' '5to10cm,' '10to20cm,' '20to40cm,' '40to70cm,' '70to100cm,' '100to200cm']

et_acc_period

Accumulated depth of water in inches or millimeters, actually evapotranspired, based on the particular crop, soil, and weather conditions of the custom analysis.

soil_conditions/temp_min

Array of 24-hour maximum temperature of the layer between x and y cm. Values are ordered by layer ['0to2cm,' '2to5cm,' '5to10cm,' '10to20cm,' '20to40cm,' '40to70cm,' '70to100cm,' '100to200cm']

last_model_execution

Unix timestamp of the last completed model run. If this is "n/a," then the model has not been run yet. If this is greater than metadata/last_scheduled_update, the data should represent the most current state. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

last_scheduled_update

Unix timestamp of the most recent scheduled model run. If this is greater than metadata/last_model_execution, the data may not represent the most current state. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris’ definition of Epoch/Unix timestamp.

activity_time

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

activity_time_end

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

irrigation_value

The applied amount resulting from an irrigation activity.

water_used

Total volume of water used for an irrigation activity. Units are specified in the associated "water_used_unit" parameter. Valid only if an irrigation system is configured.

water_used_cost

Total cost of water used for an irrigation activity. Valid only if an irrigation system is configured.

pump_energy_used

Total amount of energy used by the irrigation pump for an irrigation activity. Units are specified in the associated "pump_energy_used_unit" parameter. Valid only if an irrigation system is configured and configured with pump irrigation delivery (flow_type=0).

pump_energy_used_cost

Total cost of the energy used to power the irrigation pump for an irrigation activity. Valid only if an irrigation system is configured and configured with pump irrigation delivery (flow_type=0).

drive_motor_energy_used

Total amount of energy used by the drive motors for an irrigation activity. Valid only if an irrigation system is configured and configured with drive motors.

drive_motor_energy_used_cost

Total cost of the energy used by the drive motors for an irrigation activity. Valid only if an irrigation system is configured and configured with drive motors.

metatdata/units

This section contains a key value mapping between values in data and the applicable measurement unit.

root_zone/available_water

Estimated depth of water in the root zone that is readily available to the plant in inches or millimeters. This value is negative if the root zone soil moisture is less than the allowed depletion, as set by the user or as determined based on soil texture class.

root_zone/soil_moisture

Volumetric water content of the root zone expressed as a decimal.

root_zone/effective_depth

Depth of soil from which most water and nutrients are drawn from by the plant’s roots in feet or meters.

root_zone/depth

Depth to which the deepest roots of the plant extend in feet or meters.

root_zone/field_capacity

Volumetric water content of the root zone at field capacity expressed as a decimal.

root_zone/max_allowable_ soil_moisture

Maximum value soil moisture in the root zone should attain following an irrigation event expressed as percent volumetric water content.

root_zone/min_allowable_ soil_moisture

Minimum value to which root zone soil moisture should be allowed to dry to before irrigation is recommended, expressed as percent volumetric water content.

root_zone/saturation

Volumetric water content of the root zone at saturation expressed as a decimal.

root_zone/wilting_point

Volumetric water content of the root zone at the permanent wilting point expressed as a decimal.

Example Request

https://ag.us.clearapis.com/v1.0/zone/soil_conditions/custom_analysis/daily?
app_id=456&app_key=789&account_id=123&user_id=xyz-123&growth_id=bcd-def
&start=1388534400&end=1388707200

Example Response

Response if growth is not currently registered.

{
  "metadata":{
    "units":{},
    "last_scheduled_update":1545413091,
    "last_model_execution":"n/a"
  },
  "zone_data":{}
}

Response if growth is currently registered and at least one custom field modeling run has been performed.

 {
  "metadata":{
    "units":{
      "field_capacity":"ft^3/ft^3",
      "saturation":"ft^3/ft^3",
      "wilting_point":"ft^3/ft^3",
      "drive_motor_energy_used":"kwh",
      "moisture":"ft^3/ft^3",
      "et_acc_period":"in",
      "available_water":"in",
      "soil_moisture":"ft^3/ft^3",
      "temp":"F",
      "effective_depth":"ft",
      "depth":"ft",
      "max_allowable_soil_moisture":"%",
      "min_allowable_soil_moisture":"%",
      "temp_max":"F",
      "temp_min":"F",
      “irrigation_value”:"in",
      "water_used":"ac-in",
      "pump_energy_used":"kwh"

    },
    "last_scheduled_update":1545411603,
    "last_model_execution":1545411611
  },
  "zone_data":{
    "abcd-1":{
      "soil_conditions":{
        "2018-12-13":{
          "moisture":[
            0.05,
            0.05,
            0.05,
            0.05,
            0.05,
            0.05,
            0.05,
            0.06
          ],
          "et_acc_period":0,
          "root_zone":{
            "available_water":0,
            "soil_moisture":0.05,
            "effective_depth":1.8,
            "depth":4.89,
            "field_capacity":0.26,
            "max_allowable_soil_moisture":0.37,
            "min_allowable_soil_moisture":0.05,
            "saturation":0.43,
            "wilting_point":0.05
          },
          "temp":[
            60.94,
            62,
            62.76,
            64.3,
            67.52,
            72.31,
            76.17,
            80.69
          ],
          "temp_max":[
            82.73,
            71.07,
            67.6,
            65.65,
            67.7,
            72.49,
            76.32,
            80.78
          ],
          "temp_min":[
            46,
            54.08,
            57.97,
            62.75,
            67.34,
            72.14,
            76.02,
            80.6
          ]
        },
        "2018-12-14":{...
        }
      },
      "activities":{
        "irrigation":[{
          "irrigation_value":0.135,
          "field_activity_id":"def-1",
          "created":1544085315,
          "modified":null,
          "activity_time_end":1541383200,
          "activity_time":1541376000,
          "water_used":4.23,
          "water_used_cost":0.02,
          "pump_energy_used":1,
          "pump_energy_used_cost":0.15,
          "drive_motor_energy_used":1.34,
          "drive_motor_energy_used_cost":0.16
        }],
        "soil_sample":[]
      }
    },
    "abcd-2":{...
    },
    "abcd-3":{...
    },
  }
 }

Custom Field Zone Modeling Hourly Irrigation Recommendations - v1.0

Through the Field Zone Irrigation Recommendations with Custom Analysis Hourly endpoint, users can obtain recommendations for irrigation activities, along with field zone map and overall irrigation efficiency information customized to their field, irrigation system, and crop specifications. The endpoint returns data for the period of time spanning 0 to +240 hours, relative to the current hour.

In order to receive irrigation recommendations for a growth, you must have configured the Irrigation System Properties on the field for which the growth resides. Irrigation System Properties which have been applied will alter custom field modeled soil conditions and generated irrigation recommendations. Please refer to the Get Irrigation System Properties, Modify Irrigation System Properties, and Delete Irrigation System Properties endpoints within the ClearAg Focus Soil Conditions.

Please see the Custom Field Modeling Supported Crops section of the Appendix for a complete list of currently supported crops.

URL Description

https://ag.us.clearapis.com/v1.0/zone/irrigation/custom_analysis/hourly/
recommendation?app_id={string}&app_key={string}&account_id={string}
&user_id={string}&growth_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 an Iteris account representative.

user_id

string

yes

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

growth_id

string

yes

Provided by the Create Growth endpoint. Target Growth must be zone aware.

unitcode

string

no

default is "us-std."

Response Object (JSON)

Field Description

zone_data

Contains per field zone data using the zone id as the key.

estimated_soil_conditons/ moisture

Array of 24-hour estimated average moisture content of the layer between x and y cm if irrigation recommendations are followed. Values are ordered by layer ['0to2cm,' '2to5cm,' '5to10cm,' '10to20cm,' '20to40cm,' '40to70cm,' '70to100cm,' and '100to200cm']

et_acc_period

Estimated accumulated depth of water in inches or millimeters, actually evapotranspired, based on the particular crop, soil, and weather conditions of the custom analysis.

last_model_execution

Unix timestamp of the last completed model run. If this is "n/a," then the model has not been run yet. If this is greater than metadata/last_scheduled_update, the data should represent the most current state. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

last_scheduled_update

Unix timestamp of the most recent scheduled model run. If this is greater than metadata/last_model_execution, the data may not represent the most current state. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activity_time

Unix timestamp of activity start time. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activity_time_end

Unix timestamp of activity end time. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

irrigation_value

The applied amount resulting from an irrigation activity.

water_used

Total volume of water used for an irrigation activity. Units are specified in the associated "water_used_unit" parameter. Valid only if an irrigation system is configured.

water_used_cost

Total cost of water used for an irrigation activity. Valid only if an irrigation system is configured.

pump_energy_used

Total amount of energy used by the irrigation pump for an irrigation activity. Units are specified in the associated "pump_energy_used_unit" parameter. Valid only if an irrigation system is configured and configured with pump irrigation delivery (flow_type=0).

pump_energy_used_cost

Total cost of the energy used to power the irrigation pump for an irrigation activity. Valid only if an irrigation system is configured and configured with pump irrigation delivery (flow_type=0).

drive_motor_energy_used

Total amount of energy used by the drive motors for an irrigation activity. Valid only if an irrigation system is configured and configured with drive motors.

drive_motor_energy_used_cost

Total cost of the energy used by the drive motors for an irrigation activity. Valid only if an irrigation system is configured and configured with drive motors.

metatdata/units

This section contains a key value mapping between values in data and the applicable measurement unit.

root_zone/available_water

Estimated depth of water in the root zone that is readily available to the plant in inches or millimeters. This value is negative if the root zone soil moisture is less than the allowed depletion, as set by the user or as determined based on soil texture class.

root_zone/soil_moisture

Estimated volumetric water content of the root zone expressed as a decimal.

root_zone/saturation

Volumetric water content of the root zone at saturation expressed as a decimal.

root_zone/wilting_point

Volumetric water content of the root zone at the permanent wilting point expressed as a decimal.

recommended_activities

Array of recommended irrigation events.

Example Request

https://ag.us.clearapis.com/v1.0/zone/irrigation/custom_analysis/hourly/
recommendation?app_id=456&app_key=789&account_id=123&user_id=xyz-123
&growth_id=abc-def

Example Response

Response if growth is not currently registered.

{
    "metadata":{
        "units":{},
        "last_scheduled_update":1545413091,
        "last_model_execution":"n/a"
    },
    "zone_data":{}
}

Response if growth is currently registered, at least one custom field modeling run has been performed, and if an irrigation recommendation has been generated.

{
    "metadata":{
        "last_model_execution":1546037435,
        "last_scheduled_update":1546037283,
        "units":{
            "available_water":"in",
            "drive_motor_energy_used":"n/a",
            "et_acc_period":"in",
            "irrigation_value":"in",
            "moisture":"ft^3/ft^3",
            "overall_efficiency":"%",
            "soil_moisture":"ft^3/ft^3",
            "water_used":"ac-in"
        }
    },
    "zone_data":{
        "abc-1":{
            "activities":{
                "irrigation":[],
                "soil_sample":[]
            },
            "recommended_activities":[{
                    "activity_time":1546068600,
                    "activity_time_end":1546133399,
                    "drive_motor_energy_used":"n/a",
                    "drive_motor_energy_used_cost":"n/a",
                    "irrigation_value":1.51,
                    "water_used":39.77,
                    "water_used_cost":216.0
                },
                {...
                }
            ],
            "estimated_soil_conditions":{
                "1546038000":{
                    "et_acc_period":0.04,
                    "moisture":[
                        0.29,
                        0.29,
                        0.28,
                        0.28,
                        0.27,
                        0.23,
                        0.19,
                        0.21
                    ],
                    "root_zone":{
                        "available_water":1.21,
                        "soil_moisture":0.27
                    }
                },
                "1546041600": {...
                }
            }
        }
        "abc-2": {...
        }
    }
}

Custom Field Zone Modeling Daily Irrigation Recommendations - v1.0

Through the Field Zone Irrigation Recommendations with Custom Analysis Daily endpoint, users can obtain recommendations for irrigation activities, along with field zone map and overall irrigation efficiency information customized to their field, irrigation system, and crop specifications.Associated field and growth metadata, daily weather conditions pertinent to irrigation, and daily soil conditions without the impacts of the irrigation recommendations are also provided. The endpoint returns data for the period of time spanning 0 days to +9 days, relative to the current date.

In order to receive irrigation recommendations for a growth, you must have configured the Irrigation System Properties on the field for which the growth resides. Irrigation System Properties which have been applied will alter custom field modeled soil conditions and generated irrigation recommendations. Please refer to the Get Irrigation System Properties, Modify Irrigation System Properties, and Delete Irrigation System Properties endpoints within the ClearAg Focus Soil Conditions.

Please see the Custom Field Modeling Supported Crops section of the Appendix for a complete list of currently supported crops.

URL Description

https://ag.us.clearapis.com/v1.0/zone/irrigation/custom_analysis/daily/recommendation?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_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

A unique account ID provided by an Iteris account representative.

user_id

string

yes

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

growth_id

string

yes

Provided by the Create Growth endpoint. Target Growth must be zone aware.

unitcode

string

no

default is "us-std."

Response Object (JSON)

Field Description

zone_data

Contains per field zone data using the zone id as the key.

estimated_soil_conditons/moisture

Array of 24-hour estimated average moisture content of the layer between x and y cm if irrigation recommendations are followed. Values are ordered by layer ['0to2cm,' '2to5cm,' '5to10cm,' '10to20cm,' '20to40cm,' '40to70cm,' '70to100cm,' and '100to200cm']

et_acc_period

Estimated accumulated depth of water in inches or millimeters, actually evapotranspired, based on the particular crop, soil, and weather conditions of the custom analysis.

last_model_execution

Unix timestamp of the last completed model run. If this is "n/a," then the model has not been run yet. If this is greater than metadata/last_scheduled_update, the data should represent the most current state. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

last_scheduled_update

Unix timestamp of the most recent scheduled model run. If this is greater than metadata/last_model_execution, the data may not represent the most current state. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activity_time

Unix timestamp of activity start time. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

activity_time_end

Unix timestamp of activity end time. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

irrigation_value

The applied amount resulting from an irrigation activity.

water_used

Total volume of water used for an irrigation activity. Units are specified in the associated "water_used_unit" parameter. Valid only if an irrigation system is configured.

water_used_cost

Total cost of water used for an irrigation activity. Valid only if an irrigation system is configured.

pump_energy_used

Total amount of energy used by the irrigation pump for an irrigation activity. Units are specified in the associated "pump_energy_used_unit" parameter. Valid only if an irrigation system is configured and configured with pump irrigation delivery (flow_type=0).

pump_energy_used_cost

Total cost of the energy used to power the irrigation pump for an irrigation activity. Valid only if an irrigation system is configured and configured with pump irrigation delivery (flow_type=0).

drive_motor_energy_used

Total amount of energy used by the drive motors for an irrigation activity. Valid only if an irrigation system is configured and configured with drive motors.

drive_motor_energy_used_cost

Total cost of the energy used by the drive motors for an irrigation activity. Valid only if an irrigation system is configured and configured with drive motors.

metatdata/units

This section contains a key value mapping between values in data and the applicable measurement unit.

root_zone/available_water

Estimated depth of water in the root zone that is readily available to the plant in inches or millimeters. This value is negative if the root zone soil moisture is less than the allowed depletion, as set by the user or as determined based on soil texture class.

root_zone/soil_moisture

Estimated volumetric water content of the root zone expressed as a decimal.

root_zone/saturation

Volumetric water content of the root zone at saturation expressed as a decimal.

root_zone/wilting_point

Volumetric water content of the root zone at the permanent wilting point expressed as a decimal.

recommended_activities

Array of recommended irrigation events.

overall_efficiency

Efficiency of the irrigation recommendations in terms of water retained in the root zone or transpired as a proportion of total applied water, expressed as a percentage.

Example Request

https://ag.us.clearapis.com/v1.0/zone/irrigation/custom_analysis/daily/recommendation?
app_id=456&app_key=789&account_id=123&user_id=xyz-123&growth_id=abc-def

Example Response

Response if growth is not currently registered.

{
	"metadata":{
		"units":{},
		"last_scheduled_update":1545413091,
		"last_model_execution":"n/a"
	},
	"zone_data":{}
}

Response if growth is currently registered, at least one custom field modeling run has been performed, and if an irrigation recommendation has been generated.

{
	"metadata":{
		"last_model_execution":1546037435,
		"last_scheduled_update":1546037283,
		"units":{
			"available_water":"in",
			"drive_motor_energy_used":"n/a",
			"et_acc_period":"in",
			"irrigation_value":"in",
			"moisture":"ft^3/ft^3",
			"overall_efficiency":"%",
			"soil_moisture":"ft^3/ft^3",
			"water_used":"ac-in"
		}
	},
	"zone_data":{
		"abc-1":{
			"activities":{
				"irrigation":[],
				"soil_sample":[]
			},
			"overall_efficiency":13.4,
			"recommended_activities":[{
					"activity_time":1546068600,
					"activity_time_end":1546133399,
					"drive_motor_energy_used":"n/a",
					"drive_motor_energy_used_cost":"n/a",
					"irrigation_value":1.51,
					"water_used":39.77,
					"water_used_cost":216.0
				},
				{ ...
				}
			],
			"estimated_soil_conditions":{
				"2018-12-29":{
					"et_acc_period":0.04,
					"moisture":[
						0.29,
						0.29,
						0.28,
						0.28,
						0.27,
						0.23,
						0.19,
						0.21
					],
					"root_zone":{
						"available_water":1.21,
						"soil_moisture":0.27
					}
				},
				"2018-12-30":{...
				}
			}
		}
		"abc-2":{ ...
		}
	}
}

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.

Epoch/Unix Timestamp

Iteris employs Epoch/Unix timestamps for some time-based parameters. Timestamps are defined as the number of seconds since 1970-01-01 00:00 Coordinated Universal Time (UTC).

Note that in daily endpoints, timestamps as URL arguments do not necessarily conform to this definition. In these endpoints, timestamps can be thought of as being relative to the local time zone. For example, a plant_date timestamp corresponding to 2016-05-01 00:00 UTC in the Corn Growth endpoint can be viewed as 2016-05-01 00:00 local time, and the endpoint returns data starting on that date.

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>

Feedback Information

The feedback timestamp, which is the precise time when the feedback was observed, must happen after the plant/emergence date and prior to the current date. Growth feedback is considered (confirmed) if the stage of feedback occurs before the model anticipates. Should the length of model execution be insufficient to reach a stage for which feedback exists, that feedback will have no effect. If the feedback stage - the growth stage observed that warranted the entered feedback - matches the current stage, it is not confirmed and the model will continue as normal. If there are multiple feedbacks for a given stage (and they occur prior to reaching that stage with the initial model run) the feedback with the most recent feedback timestamp will take precedence. If more than one feedback with the same stage and the same feedback timestamp are present then the system will use the feedback with the most recent created timestamp.

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

Bermuda Turfgrass

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

X

X

Potato

X

X

X

Sorghum

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

Sunflower

X

X

X

Tomato

X

X

X

Winter Wheat

X

X

X

X

X

X

X

Custom Field Modeling Supported Crops

  • almond

  • canola

  • corn

  • cotton

  • lemon

  • orange

  • potato

  • sorghum

  • soybean

  • springwheat

  • tomato

  • turfgrass bermuda

  • turfgrass zoysia

  • winter wheat

Plant Enumerations

Below is a listing of available values for plant_type and plant_name.

Plant Type Plant Name

50

barley

59

canola

51

corn

57

springwheat

65

cotton

76

peanut

75

potato

70

sorghum

66

soybean

60

sugarbeet

72

sunflower

68

winter wheat

USDA Texture Classes

texture class texture class description

1

Sand

2

Loamy Sand

3

Sandy Loam

4

Silt Loam

5

Silt

6

Loam

7

Sandy Clay Loam

8

Silty Clay Loam

9

Clay Loam

10

Sandy Clay

11

Silty Clay

12

Clay

13

Organic Materials

14

Water

15

Bedrock

16

Other

Changelog

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

1/4/19

Added Zone Management endpoints.