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 9/3/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. 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 Supported Crops by Feature 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={timestamp}&end_time={timestamp}
&start_offset={integer}&end_offset={integer}&unitcode={string}&poll

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

timestamp

yes

Query ending time in the form of a Unix timestamp. Requires: start_time. Excludes: start_offset and end_offset.

growth_id

string

yes

ID of crop growth provided by the Create Growth endpoint.

poll

no

Allows an endpoint to obtain registration/state information with no model data returned. If both last_completed and last_scheduled are "n/a," the registration does not exist. Example response:

{ "metadata": { "last_completed": 1548180769, "last_scheduled": 1548180257 } }

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

timestamp

yes

Query starting time in the form of a Unix timestamp. Requires: end_time. Excludes: start_offset and end_offset.

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 a Unix timestamp.

activities/activity_time_end

Ending time of the activity expressed as a 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.

activities/activity_type

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

activities/created

Time when the activity was created expressed as a 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 a Unix timestamp. A "null" response denotes the activity has not been modified.

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 a 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 following endpoints for additional information: Get Irrigation System Properties - v1.0; Add/Modify Irrigation System Properties - v1.0; Delete Irrigation System Properties - v1.0.

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

last_scheduled_update

Most recent scheduled model run expressed as a Unix timestamp. If this is greater than last_model_execution, the response may not represent the most current state related to data inputs.

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.

obs_influenced

If present, user provided field observation data has been provided. This user provided data overrides the precip_acc_period value calculated by the model.

plant_date

Approximate time the crop was planted expressed as a 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 volumetric water content the root zone soil moisture should attain following an irrigation event, expressed as a decimal.

root_zone_min_allowable _soil_moisture

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

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

Below is the electricity_cost_schedule example provided above in plain text:

10/9/2017 12pm Central for 4 hours every week
10/9/2017 8am Central for 120 hours every week
10/7/2017 12am Central for 48 hours every week
10/7/2017 11:06:40am Central for 31.333 hours every 56.88 hours

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",
            "obs_influenced":"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":"ft^3/ft^3",
            "root_zone_min_allowable_soil_moisture":"ft^3/ft^3",
            "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 Supported Crops by Feature 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={timestamp}&end_time={timestamp}
&start_offset={integer}&end_offset={integer}&unitcode={string}&poll

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

timestamp

yes

Query ending time in the form of a Unix timestamp. Requires: start_time Excludes: start_date, end_date, start_offset, and end_offset.

growth_id

string

yes

ID of crop growth provided by the Create Growth endpoint.

poll

no

Allows an endpoint to obtain registration/state information with no model data returned. If both last_completed and last_scheduled are "n/a," the registration does not exist. Example response:

{ "metadata": { "last_completed": 1548180769, "last_scheduled": 1548180257 } }

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

timestamp

yes

Query starting time in the form of a Unix timestamp. Requires: end_time Excludes: start_date, end_date, start_offset, and end_offset.

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 a Unix timestamp.

activities/activity_time_end

Ending time of the activity expressed as a 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.

activities/activity_type

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

activities/created

Time when the activity was created expressed as a 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 a Unix timestamp. A "null" response denotes the activity has not been modified.

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 a 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 following endpoints for additional information: Get Irrigation System Properties - v1.0; Add/Modify Irrigation System Properties - v1.0; Delete Irrigation System Properties - v1.0.

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

last_scheduled_update

Most recent scheduled model run expressed as a Unix timestamp. If this is greater than last_model_execution, the response may not represent the most current state related to data inputs.

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.

obs_influenced

If present, user provided field observation data has been provided. This user provided data overrides the precip_acc_period value calculated by the model.

plant_date

Approximate time the crop was planted expressed as a 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 volumetric water content the root zone soil moisture should attain following an irrigation event, expressed as a decimal.

root_zone_min_allowable _soil_moisture

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

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",
            "obs_influenced":"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":"ft^3/ft^3",
            "root_zone_min_allowable_soil_moisture":"ft^3/ft^3",
            "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 following endpoints for additional information: Get Irrigation System Properties - v1.0; Add/Modify Irrigation System Properties - v1.0; Delete Irrigation System Properties - v1.0.

Please see the Supported Crops by Feature 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}&poll

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.

poll

no

Allows an endpoint to obtain registration/state information with no model data returned. If both last_completed and last_scheduled are "n/a," the registration does not exist. Example response:

{ "metadata": { "last_completed": 1548180769, "last_scheduled": 1548180257 } }

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 a Unix timestamp.

activities/activity_time_end

Ending time of the activity expressed as a 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.

activities/activity_type

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

activities/created

Time when the activity was created expressed as a 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 a Unix timestamp. A "null" response denotes the activity has not been modified.

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 a 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 following endpoints for additional information: Get Irrigation System Properties - v1.0; Add/Modify Irrigation System Properties - v1.0; Delete Irrigation System Properties - v1.0.

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

last_scheduled_update

Most recent scheduled model run expressed as a Unix timestamp. If this is greater than last_model_execution, the response may not represent the most current state related to data inputs.

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.

obs_influenced

If present, user provided field observation data has been provided. This user provided data overrides the precip_acc_period value calculated by the model.

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 a 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 volumetric water content the root zone soil moisture should attain following an irrigation event, expressed as a decimal.

root_zone_min_allowable _soil_moisture

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

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

Below is the electricity_cost_schedule example provided above in plain text:

10/9/2017 12pm Central for 4 hours every week
10/9/2017 8am Central for 120 hours every week
10/7/2017 12am Central for 48 hours every week
10/7/2017 11:06:40am Central for 31.333 hours every 56.88 hours

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",
            "obs_influenced":"True",
            "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":"ft^3/ft^3",
            "root_zone_min_allowable_soil_moisture":"ft^3/ft^3",
            "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 following endpoints for additional information: Get Irrigation System Properties - v1.0; Add/Modify Irrigation System Properties - v1.0; Delete Irrigation System Properties - v1.0.

Please see the Supported Crops by Feature 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}&poll

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.

poll

no

Allows an endpoint to obtain registration/state information with no model data returned. If both last_completed and last_scheduled are "n/a," the registration does not exist. Example response:

{ "metadata": { "last_completed": 1548180769, "last_scheduled": 1548180257 } }

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 a Unix timestamp.

activities/activity_time_end

Ending time of the activity expressed as a 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.

activities/activity_type

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

activities/created

Time when the activity was created expressed as a 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 a Unix timestamp. A "null" response denotes the activity has not been modified.

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 a 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 following endpoints for additional information: Get Irrigation System Properties - v1.0; Add/Modify Irrigation System Properties - v1.0; Delete Irrigation System Properties - v1.0.

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

last_scheduled_update

Most recent scheduled model run expressed as a Unix timestamp. If this is greater than last_model_execution, the response may not represent the most current state related to data inputs.

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.

obs_influenced

If present, user provided field observation data has been provided. This user provided data overrides the precip_acc_period value calculated by the model.

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 a 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 volumetric water content the root zone soil moisture should attain following an irrigation event, expressed as a decimal.

root_zone_min_allowable _soil_moisture

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

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",
            "obs_influenced":"True",
            "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":"ft^3/ft^3",
            "root_zone_min_allowable_soil_moisture":"ft^3/ft^3",
            "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":{}
    }
}

Irrigation Auxiliary Data

Hourly Irrigation Custom Analysis Auxiliary Data

The purpose of this endpoint is to return environmental variables that were used when running custom analysis.

URL Description

https://ag.us.clearapis.com/v1.0/crop_health/irrigation/custom_analysis/hourlyauxiliary_data?account_id={string}&user_id={string}&field_id={string}&start_time={timestamp}&end_time={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

Your Accounts API account ID.

user_id

string

yes

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

field_id

string

yes

Field ID provided by the Account API. The resulting growth will be associated with this field.

start_time

timestamp

yes

Start time of the data returned in the form of Unix timestamp.

end_time

timestamp

yes

End time of the data returned in the form of Unix timestamp.

unitcode

string

no

Unit conversion set to be used. Default is "us-std." Valid values are "us-std" or "si-std."

Response Object (JSON)

Field Description

air_temp

Air temperature at two meters above ground level.

long_wave_radiation

Downwelling longwave radiation flux data. Longwave radiation is the energy emitted from non-solar radiation sources.

obs_influenced

Boolean to denote if precip_acc_period has been overridden by user provided observation.

precip_acc_period

Liquid-equivalent precipitation accumulation.

precip_prob

Probability of precipitation. Probabilities of no more than 40-50% are recommended for determining rain-free hours. Generally expected to be "n/a" for historical timeframes.

short_wave_radiation

Downwelling shortwave radiation flux in watts per square meter.

relative_humidity

Relative humidity data. Relative humidity is the ratio of the actual amount of water vapor in the air to the maximum amount that can physically exist at a given air temperature.

station_pressure

Current station pressure data. Station pressure is the barometric pressure at a specific elevation and is the true barometric pressure at the observing location.

wind_speed

Wind speed at 10 meters above ground level.

wind_direction

Wind direction, measured with respect to true north. A wind direction from true north corresponds to a value of 0 degrees, which increases to 360 degrees with corresponding clockwise shifts in wind direction.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/irrigation/custom_analysis/hourlyauxiliary_data?account_id=abc&user_id=def&field_id=bcd-def&start_time=1388534400&end_time=1388707200

Example Response

{
    "data":{
        "1562702400":{
            "air_temp":30.99,
            "long_wave_radiation":383.5,
            "obs_influenced":"True",
            "precip_acc_period":25.4,
            "precip_prob":0,
            "short_wave_radiation":0,
            "relative_humidity":0.01,
            "station_pressure":96600.66,
            "wind_speed":16.57,
            "wind_direction":39.779
        },
        "1562706000":{
            "air_temp":30.33,
            "long_wave_radiation":379.79,
            "obs_influenced":"False",
            "precip_acc_period":0,
            "precip_prob":0,
            "short_wave_radiation":0,
            "relative_humidity":0.01,
            "station_pressure":96626.7,
            "wind_speed":17.33,
            "wind_direction":50.2
        }
    },
    "metadata":{
        "units":{
            "radiation":"w/m^2",
            "air_temp":"C",
            "wind_speed":"kph",
            "wind_direction":"degrees",
            "relative_humidity":"%",
            "station_pressure":"pa",
            "precip_acc":"mm",
            "precip_prob":"%"
        }
    }
}

Daily Irrigation Custom Analysis Auxiliary Data

The purpose of this endpoint is to return environmental variables that were used when running custom analysis.

URL Description

https://ag.us.clearapis.com/v1.0/crop_health/irrigation/custom_analysis/daily/auxiliary_data?account_id={string}&user_id={string}&field_id={string}&start_time={timestamp}&end_time={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

Your Accounts API account ID.

user_id

string

yes

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

field_id

string

yes

Field ID provided by the Account API. The resulting growth will be associated with this field.

start_time

timestamp

yes

Start time of the data returned in the form of Unix timestamp.

end_time

timestamp

yes

End time of the data returned in the form of Unix timestamp.

unitcode

string

no

Unit conversion set to be used. Default is "us-std." Valid values are "us-std" or "si-std."

Response Object (JSON)

Field Description

air_temp_avg

Average daily air temperature valid for the current period’s date. This value is obtained by adding the daily minimum air temperature and daily maximum air temperature and dividing that value by two. These values are obtained from recorded values, forecasted values, or climatological averages, depending on the time frame.

air_temp_max

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

air_temp_min

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

long_wave_radiation_avg

Downwelling longwave radiation flux data. Longwave radiation is the energy emitted from non-solar radiation sources.

long_wave_radiation_max

Maximum downwelling longwave radiation flux data.

long_wave_radiation_min

Minimum downwelling longwave radiation flux data.

obs_influenced

Boolean to denote if precip_acc_period has been overridden by user provided observation.

precip_acc_period

Liquid-equivalent precipitation accumulation.

precip_prob

Probability of precipitation. Probabilities of no more than 40-50% are recommended for determining rain-free hours. Generally expected to be "n/a" for historical timeframes.

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.

relative_humidity_avg

Average daily relative humidity provided as a percentage.

relative_humidity_max

Maximum relative humidity at two meters above ground level.

relative_humidity_min

Minimum relative humidity at two meters above ground level.

station_pressure

Current station pressure data. Station pressure is the barometric pressure at a specific elevation and is the true barometric pressure at the observing location.

wind_speed_avg

Average wind speed at 10 meters above ground level.

wind_speed_max

Maximum wind speed at 10 meters above ground level.

wind_speed_min

Minimum wind speed at 10 meters above ground level.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/irrigation/custom_analysis/dailyauxiliary_data?account_id=abc&user_id=def&field_id=bcd-def&start_time=1388534400&end_time=1388707200

Example Response

{
    "data":{
        "2019-07-08":{
            "air_temp_avg":32.45,
            "air_temp_max":38.99,
            "air_temp_min":25.76,
            "long_wave_radiation_avg":391.02,
            "long_wave_radiation_max":433.55,
            "long_wave_radiation_min":349.94,
            "obs_influenced":"False",
            "precip_acc_period":0,
            "precip_prob":0,
            "relative_humidity_avg":0,
            "relative_humidity_max":0.01,
            "relative_humidity_min":0,
            "short_wave_radiation_avg":331.28,
            "short_wave_radiation_max":1002.8,
            "short_wave_radiation_min":0,
            "station_pressure_avg":97539.46,
            "wind_speed_avg":13.83,
            "wind_speed_max":18.96,
            "wind_speed_min":9.01
        },
        "2019-07-09":{
            "air_temp_avg":32.79,
            "air_temp_max":39.33,
            "air_temp_min":26.09,
            "long_wave_radiation_avg":391.67,
            "long_wave_radiation_max":427.17,
            "long_wave_radiation_min":355.85,
            "obs_influenced":"True",
            "precip_acc_period":25.4,
            "precip_prob":0,
            "relative_humidity_avg":0.01,
            "relative_humidity_max":0.01,
            "relative_humidity_min":0,
            "short_wave_radiation_avg":337.57,
            "short_wave_radiation_max":1012.6,
            "short_wave_radiation_min":0,
            "station_pressure_avg":97312.71,
            "wind_speed_avg":15.65,
            "wind_speed_max":21.73,
            "wind_speed_min":8.35
        }
    },
    "metadata":{
        "units":{
            "radiation":"w/m^2",
            "air_temp":"C",
            "wind_speed":"kph",
            "wind_direction":"degrees",
            "relative_humidity":"%",
            "station_pressure":"pa",
            "precip_acc":"mm",
            "precip_prob":"%"
        }
    }
}

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. Specifying a zone to be used for recommendation triggering occurs through the relevant growth endpoint. 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.

Please refer to the Irrigation System Properties section for endpoints relating to adding/modifying, deleting, and getting irrigation system properties.

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

Unix timestamp when the activity was created.

field_activity_id

ID of activity.

modified

Unix timestamp when the activity was last modified, with 'null' denoting that the activity has not been modified.

activity_type

Enumeration value of activity.

activity_time

Unix timestamp when the activity took place.

unit

Unit of measure for irrigation.

activity_time_end

Unix timestamp when 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.

Please note that to delete a zone aware irrigation activity one must use the Delete Irrigation Activity - v1.0 endpoint.

Please

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}&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 a Unix 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
&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 a 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

curl -X POST \
'https://ag.us.clearapis.com/v1.0/zone/activity/irrigation/map/create?account_id={string}&user_id={string}&zone_map_id={string}&activity_time={integer}&activity_time_end={integer}&unit={string}&app_id={string}&app_key={string}' \
-H 'content-type: multipart/form-data;' \
-F file=@{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 a 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?account_id=abc-123&user_id=def-456&zone_map_id=ghi-789&activity_time=1533081600&activity_time_end=1533103200&unit=mm&app_id=jkl-101&app_key=mno-121' \
-H 'content-type: multipart/form-data;' \
-F file=@/my_fields/field1/irrigation_events/irrigation_event_shapefile.zip

Example Response

888-444

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 following endpoints for additional information: Get Irrigation System Properties - v1.0; Add/Modify Irrigation System Properties - v1.0; Delete Irrigation System Properties - v1.0.

Please see the Supported Crops by Feature 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}&poll

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.

poll

no

Allows an endpoint to obtain registration/state information with no model data returned. If both last_completed and last_scheduled are "n/a," the registration does not exist. Example response:

{ "metadata": { "last_completed": 1548180769, "last_scheduled": 1548180257 } }

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.

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.

activity_time

Unix timestamp of activity start time.

activity_time_end

Unix timestamp of activity end time.

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 following endpoints for additional information: Get Irrigation System Properties - v1.0; Add/Modify Irrigation System Properties - v1.0; Delete Irrigation System Properties - v1.0.

Please see the Supported Crops by Feature 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}&poll

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.

growth_id

string

yes

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

poll

no

Allows an endpoint to obtain registration/state information with no model data returned. If both last_completed and last_scheduled are "n/a," the registration does not exist. Example response:

{ "metadata": { "last_completed": 1548180769, "last_scheduled": 1548180257 } }

unitcode

string

no

default is "us-std."

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.

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.

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.

activity_time

Unix timestamp of activity start time.

activity_time_end

Unix timestamp of activity end time.

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":{ ...
		}
	}
}

Irrigation System Properties

Add/Modify Irrigation System Properties - v1.0

This endpoint allows a user to configure and modify irrigation properties for a given field. By default every field will contain un-configured irrigation system properties. These settings will affect custom soil modeling and related irrigation advisement products.

URL Description

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/
modify/{field_id}?app_id={string}&app_key={string}
&account_id={string}&user_id={string}&water_cost={float}
&water_unit={string}&max_moisture_depletion={float}
&max_moisture_refill={float}&flow_type={integer}
&energy_source={integer}&energy_cost={float}
&energy_unit={string}&energy_use_rate={float}
&post_irrigation_delay={integer}
&irrigation_blackout_schedule={list or null}

Request Parameters

Required and optional parameters will vary depending on irrigation system type of the target field, or upon the irrigation system type being set. The parameters field_id, account_id, and user_id are required for all irrigation system management operations. These parameters are described directly below. Parameters which vary by irrigation system type are described thereafter.

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_id

string

yes

ID of field in which properties are to be modified.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

User ID provided by the ClearAg Accounts API user management endpoints. User must have write privileges for the field.

water_cost

float

no

Cost of water per volume (water_unit). The minimum value is 0.0. Requires: water_unit.

water_unit

string

no

Volumetric unit used to measure water usage. Valid values include 'gal,' 'l,' 'ac-in,' and 'm^3.' Requires: water_cost.

max_moisture_ depletion

float

no

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.

max_moisture_refill

float

no

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.

set_irrigation_ amount

float or null

no

The predefined depth of water to be applied for each recommended irrigation application. Minimum value is 0.0. Requires: set_irrigation_unit. If 'null' value is provided, set_irrigation_unit will also be set to 'null.'

set_irrigation_unit

string or null

no

Unit of measure for the predefined amount of water to be applied for each recommended irrigation application. Valid values: are 'in,' 'cm,' 'mm,' or 'null'. Requires: set_irrigation_amount. If null value is provided, set_irrigation_amount will also be set to null.

flow_type

integer

no

Irrigation delivery method. Valid values are 0 for Pump or 1 for Gravity-fed.

energy_source

integer

no

The power source used to run the irrigation pump. Valid only for pump irrigation delivery (flow_type=0). Valid values: 0 for Electric, 1 for Diesel, 2 for Natural Gas, or 3 for LPG. Requires: energy, cost, energy_unit, energy_use_rate, and flow_type of 0.

energy_cost

float

no

The cost to power the irrigation pump per energy unit, if applicable. Valid only for pump irrigation delivery (flow_type=0).. The minimum value is 0.0. Requires: energy_unit, energy_source, energy_use_rate, and flow_type of 0.

energy_unit

string

no

Energy unit associated with the energy source. Valid only for pump irrigation delivery (flow_type=0). Valid values: 'kwh' for energy_source of 0 (Electric); 'gal' or 'l' for energy_source of 1 (Diesel); 'lb,' 'kg,' 'MMBtu,' or 'mcf' for energy_source of 2 (Natural Gas); 'gal' or 'l' for energy_source of 3 (LPG). Requires: energy_cost, energy_source, energy_use_rate, and flow_type of 0.

energy_use_rate

float

no

The rate at which energy is consumed by the irrigation pump in units of energy_unit per hour. Valid only for pump irrigation delivery (flow_type=0). The minimum value is 0.0. Requires: energy_source, energy_cost, energy_source, energy_unit, and flow_type of 0 (pump).

post_irrigation_delay

integer or null

no

Minimum time to wait in seconds between irrigation recommendations.

electricity_cost_ schedule

List or null

no

Used for estimating the total electricity cost of an irrigation activity for custom field modeling endpoints. The electricity_cost_schedule will only be used in estimating the cost of an irrigation activity if drive_motor_unit is kwh and/or energy_source is 0, and energy_unit is kwh . Expected format is a list of, up to 10 schedules, given in order of desired precedence, where a schedule is a list of four values. Each schedule has the format: [{start_timestamp}, {duration}, {repeat_offset}, {electricity_cost}]. *See below for example and further description.

irrigation_blackout _schedule

list or null

no

Used to schedule time periods for which irrigation recommendations should not be started. A list/array of up to 10 schedules can be provided, in the format of: [{start_timestamp}, {duration}, {repeat_offset}]. See below for example and further description.

Description of schedule:
{start_timestamp}: unix timestamp when the schedule starts.
{duration}: integer; minimum 3600; Amount of seconds from start of an interval which electricity cost applies.
{repeat_offset}: integer, minimum: 3600; schedule repeats every {repeat_offset} seconds.
{electricity_cost}: float;  must be greater than 0.0;  cost of electricity during schedule

Example electricity_cost_schedule:
[[1507568400, 14400, 604800, 0.005],[1507554000, 432000, 604800, 0.0025],[1507352400, 172800, 604800, 0.037],[1507392400, 112800, 204800, 0.099]]

The example electricity_cost_schedule contains four schedules, but can contain up to 10 schedules. Schedules are kept in order of precedence, with the first schedule having the highest precedence and the last one having the lowest precedence. A schedule's precedence is only used when two or more schedules have an overlapping time period, in which case the electricity_cost will be used from the schedule with the highest precedence.

The first schedule in the above example starts Monday, October 9, 2017 17:00:00 +00:00 with a duration of four hours (14400 seconds), and with an electricity cost of 0.005. This schedule repeats every seven days (604800 seconds).
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]]

Below is the electricity_cost_schedule example provided above in plain text:

10/9/2017 12pm Central for 4 hours every week
10/9/2017 8am Central for 120 hours every week
10/7/2017 12am Central for 48 hours every week
10/7/2017 11:06:40am Central for 31.333 hours every 56.88 hours

Request Parameters - Surface - Level Basin (System Type 0)

Parameter Type Required Description

system_type

integer

yes

Enumeration value of irrigation system (i.e. 0). This value is only required upon initial configuration or when switching system types.

flow_rate

float

yes

Total rate at which irrigation is applied; for example, the pump capacity in a pumped irrigation system. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

flow_rate_unit

string

yes

Unit of rate at which irrigation is applied. Valid values are 'gpm' or 'lpm.' This value is only required upon initial configuration or when switching system types.

irrigated_area

float

yes

Area of applied irrigation. The minimum value is 0.0. The value is only required upon initial configuration or when switching system types.

irrigated_area_unit

string

yes

Unit of the area of the applied irrigation. Valid values are 'ac' or 'ha.' This value is only required upon initial configuration or when switching system types.

Request Parameters - Surface - Furrow (System Type 1)

Parameter Type Required Description

system_type

integer

yes

Enumeration value of irrigation system (i.e. 1). This value is only required upon initial configuration or when switching system types.

flow_rate

float

yes

Total rate at which irrigation is applied; for example, the pump capacity in a pumped irrigation system. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

flow_rate_unit

string

yes

Unit of rate at which irrigation is applied. Valid values are 'gpm' or 'lpm.' This value is only required upon initial configuration or when switching system types.

irrigated_area

float

yes

Area of applied irrigation. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

irrigated_area_unit

string

yes

Unit of the area of the applied irrigation. Valid values are 'ac' or 'ha.' This value is only required upon initial configuration or when switching system types.

slope

float

yes

Slope of the field, expressed as elevation gain per unit horizontal distance. Minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

slope_unit

string

yes

Unit of measure for slope. Valid values are 'ft/ft' or 'm/m.' This value is only required upon initial configuration or when switching system types.

Request Parameters - Center Pivot/Lateral Move with Sprinkler (System Type 2)

Parameter Type Required Description

system_type

integer

yes

Enumeration value of irrigation system (i.e. 2). This value is only required upon initial configuration or when switching system types.

drive_motor_cost

float

no

The cost of the drive motor energy source per energy unit (drive_motor_unit). Requires: drive_motor_rate and drive_motor_unit. The minimum value is 0.0.

drive_motor_rate

float

no

Total rate at which energy is consumed by all drive motors on a per hour basis. Requires: drive_motor_cost and drive_motor_unit. The minimum value is 0.0.

drive_motor_unit

string

no

Unit of energy used to power the drive motors. Requires: drive_motor_cost and drive_motor_rate. Valid value is 'kwh.'

flow_rate

float

yes

Total rate at which irrigation is applied; for example, the pump capacity in a pumped irrigation system. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

flow_rate_unit

string

yes

Unit of rate at which irrigation is applied. Valid values are 'gpm' or 'lpm.' This value is only required upon initial configuration or when switching system types.

irrigated_area

float

yes

Area of applied irrigation. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

irrigated_area_unit

string

yes

Unit of the area of the applied irrigation. Valid values are 'ac' or 'ha.' This value is only required upon initial configuration or when switching system types.

nozzle_type

integer

yes

The type of sprinkler nozzle being used. Valid values are 0 for "spray" and 1 for "impact." The default value is 0 (spray). This value is only required upon initial configuration or when switching system types.

Request Parameters - Solid Set with Sprinkler (System Type 3)

Parameter Type Required Description

system_type

integer

yes

Enumeration value of irrigation system (i.e. 3). This value is only required upon initial configuration or when switching system types.

flow_rate

float

yes

Total rate at which irrigation is applied; for example, the pump capacity in a pumped irrigation system. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

flow_rate_unit

string

yes

Unit of rate at which irrigation is applied. Valid values are 'gpm' or 'lpm.' This value is only required upon initial configuration or when switching system types.

irrigated_area

float

yes

Area of applied irrigation. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

irrigated_area_unit

string

yes

Unit of the area of the applied irrigation. Valid values are 'ac' or 'ha.' This value is only required upon initial configuration or when switching system types.

nozzle_type

integer

yes

The type of sprinkler nozzle being used. Valid values are 0 for "spray" and 1 for "impact." The default value is 0 (spray). This value is only required upon initial configuration or when switching system types.

Request Parameters - Wheel Line/Hand Line with Sprinkler (System Type 4)

Parameter Type Required Description

system_type

integer

yes

Enumeration value of irrigation system (i.e. 4). This value is only required upon initial configuration or when switching system types.

flow_rate

float

yes

Total rate at which irrigation is applied; for example, the pump capacity in a pumped irrigation system. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

flow_rate_unit

string

yes

Unit of rate at which irrigation is applied. Valid values are 'gpm' or 'lpm.' This value is only required upon initial configuration or when switching system types.

irrigated_area

float

yes

Area of applied irrigation. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

irrigated_area_unit

string

yes

Unit of the area of the applied irrigation. Valid values are 'ac' or 'ha.' This value is only required upon initial configuration or when switching system types.

nozzle_type

integer

yes

The type of sprinkler nozzle being used. Valid values are 0 for "spray" and 1 for "impact." The default value is 0 (spray). This value is only required upon initial configuration or when switching system types.

Request Parameters - Center Pivot/Lateral Move with Bubbler (System Type 5)

Parameter Type Required Description

system_type

integer

yes

Enumeration value of irrigation system (i.e. 5). This value is only required upon initial configuration or when switching system types.

drive_motor_cost

float

no

The cost of the drive motor energy source per energy unit (drive_motor_unit). Requires: drive_motor_rate and drive_motor_unit. The minimum value is 0.0.

drive_motor_rate

float

no

Total rate at which energy is consumed by all drive motors on a per hour basis. Requires: drive_motor_cost and drive_motor_unit. The minimum value is 0.0.

drive_motor_unit

string

no

Unit of energy used to power the drive motors. Requires: drive_motor_cost and drive_motor_rate. Valid value is 'kwh.'

flow_rate

float

yes

Total rate at which irrigation is applied; for example, the pump capacity in a pumped irrigation system. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

flow_rate_unit

string

yes

Unit of rate at which irrigation is applied. Valid values are 'gpm' or 'lpm.' This value is only required upon initial configuration or when switching system types.

irrigated_area

float

yes

Area of applied irrigation. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

irrigated_area_unit

string

yes

Unit of the area of the applied irrigation. Valid values are 'ac' or 'ha.' This value is only required upon initial configuration or when switching system types.

Request Parameters - Solid Set with Bubbler (System Type 6)

Parameter Type Required Description

system_type

integer

yes

Enumeration value of irrigation system (i.e. 6). This value is only required upon initial configuration or when switching system types.

flow_rate

float

yes

Total rate at which irrigation is applied; for example, the pump capacity in a pumped irrigation system. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

flow_rate_unit

string

yes

Unit of rate at which irrigation is applied. Valid values are 'gpm' or 'lpm.' This value is only required upon initial configuration or when switching system types.

irrigated_area

float

yes

Area of applied irrigation. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

irrigated_area_unit

string

yes

Unit of the area of the applied irrigation. Valid values are 'ac' or 'ha.' This value is only required upon initial configuration or when switching system types.

Request Parameters - Wheel Line/Hand Line with Bubbler (System Type 7)

Parameter Type Required Description

system_type

integer

yes

Enumeration value of irrigation system (i.e. 7). This value is only required upon initial configuration or when switching system types.

flow_rate

float

yes

Rate at which irrigation is applied. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

flow_rate_unit

string

yes

Unit of rate at which irrigation is applied. Valid values are 'gpm' or 'lpm.' This value is only required upon initial configuration or when switching system types.

irrigated_area

float

yes

Area of applied irrigation. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

irrigated_area_unit

string

yes

Unit of the area of the applied irrigation. Valid values are 'ac' or 'ha.' This value is only required upon initial configuration or when switching system types.

Request Parameters - Subsurface Drip (System Type 8)

Parameter Type Required Description

system_type

integer

yes

Enumeration value of irrigation system (i.e. 8). This value is only required upon initial configuration or when switching system types.

emitter_discharge_ rate

float

yes

The rate at which water is released from a drip emitter. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

emitter_discharge_ rate_unit

string

yes

Unit of measure for the rate of water being released from drip emitter. Valid values are 'gpm' or 'lpm.' This value is only required upon initial configuration or when switching system types.

emitter_spacing

float

yes

Distance between emitters on a drip line. Mutually excludes: emitters_per_plant, plant_density, and plant_density_unit. Requires: emitter_spacing_unit, lateral_spacing, lateral_spacing_unit. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

emitter_spacing _unit

string

yes

The unit of measure for the distance between emitters on a drip line. Mutually excludes: emitters_per_plant, plant_density, and plant_density_unit. Requires: emitter_spacing, lateral_spacing, lateral_spacing_unit. Valid values are 'in', 'ft', 'cm', or 'm.' This value is only required upon initial configuration or when switching system types.

emitters_per_plant

integer

yes

Number of emitters assigned to each plant. Mutually excludes: emitter_spacing, emitter_spacing_unit, lateral_spacing, and lateral_spacing_unit. Requires: plant_density, plant_density_unit. The minimum value is 0. This value is only required upon initial configuration or when switching system types.

irrigated_area

float

yes

Area of applied irrigation. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

irrigated_area_unit

string

yes

Unit of the area of the applied irrigation. Valid values are 'ac' or 'ha.' This value is only required upon initial configuration or when switching system types.

lateral_spacing

float

yes

The distance between drip lines. Mutually excludes: emitters_per_plant, plant_density, and plant_density_unit. Requires: emitter_spacing, emitter_spacing_unit, lateral_spacing_unit. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

lateral_spacing_unit

string

yes

The unit of measure for the distance between drip lines. Mutually excludes: emitters_per_plant, plant_density, and plant_density_unit. Requires: emitter_spacing, emitter_spacing_unit, lateral_spacing. Valid values are 'in', 'ft', 'cm', or 'm.' This value is only required upon initial configuration or when switching system types.

line_depth

float

yes

Depth at which the drip line is placed. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

line_depth_unit

string

yes

Unit of measure for the depth of the drip line is placed. Valid values are 'in' or 'cm.' This value is only required upon initial configuration or when switching system types.

plant_density

integer

yes

Number of irrigated plants per unit area. Mutually excludes: emitter_spacing, emitter_spacing_unit, lateral_spacing, and lateral_spacing_unit. Requires: plant_density_unit, emitters_per_plant. The minimum value is 0. This value is only required upon initial configuration or when switching system types.

plant_density_unit

string

yes

Areal unit of measure for the density of irrigated plants. Mutually excludes: emitter_spacing, emitter_spacing_unit, lateral_spacing, and lateral_spacing_unit. Requires: plant_density, emitters_per_plant. Valid values are 'ac' or 'ha.' This value is only required upon initial configuration or when switching system types.

Request Parameters - Subsurface Textile (System Type 9)

Parameter Type Required Description

system_type

integer

yes

Enumeration value of irrigation system (i.e. 9). This value is only required upon initial configuration or when switching system types.

emitter_discharge_ rate

float

yes

The rate at which water is released from an emitter. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

emitter_discharge_ rate_unit

string

yes

Unit of measure for the rate of water being released from an emitter. Valid values are 'gpm' or 'lpm.' This value is only required upon initial configuration or when switching system types.

emitter_spacing

float

yes

Distance between emitters on a drip line. Mutually excludes: emitters_per_plant, plant_density, and plant_density_unit. Requires: emitter_spacing_unit, lateral_spacing, lateral_spacing_unit. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

emitter_spacing _unit

string

yes

The unit of measure for the distance between emitters on a drip line. Mutually excludes: emitters_per_plant, plant_density, and plant_density_unit. Requires: emitter_spacing, lateral_spacing, lateral_spacing_unit. Valid values are 'in', 'ft', 'cm', or 'm.' This value is only required upon initial configuration or when switching system types.

emitters_per_plant

integer

yes

Number of emitters assigned to each plant. Mutually excludes: emitter_spacing, emitter_spacing_unit, lateral_spacing, and lateral_spacing_unit. Requires: plant_density, plant_density_unit. The minimum value is 0. This value is only required upon initial configuration or when switching system types.

irrigated_area

float

yes

Area of applied irrigation. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

irrigated_area_unit

string

yes

Unit of the area of the applied irrigation. Valid values are 'ac' or 'ha.' This value is only required upon initial configuration or when switching system types.

lateral_spacing

float

yes

The unit of measure for the distance between drip lines. Mutually excludes: emitters_per_plant, plant_density, and plant_density_unit. Requires: emitter_spacing, emitter_spacing_unit, lateral_spacing. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

lateral_spacing_unit

string

yes

The unit of measure for the distance between drip lines. Mutually excludes: emitters_per_plant, plant_density, and plant_density_unit. Requires: emitter_spacing, emitter_spacing_unit, lateral_spacing. Valid values are 'in', 'ft', 'cm', or 'm.' This value is only required upon initial configuration or when switching system types.

line_depth

float

yes

Depth at which the drip line is placed. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

line_depth_unit

string

yes

Unit of measure for the depth of the drip line. Valid values are 'in' or 'cm.' This value is only required upon initial configuration or when switching system types.

plant_density

integer

yes

Number of irrigated plants per unit area. Mutually excludes: emitter_spacing, emitter_spacing_unit, lateral_spacing, and lateral_spacing_unit. Requires: plant_density_unit, emitters_per_plant. The minimum value is 0. This value is only required upon initial configuration or when switching system types.

plant_density_unit

string

yes

Areal unit of measure for the density of irrigated plants. Mutually excludes: emitter_spacing, emitter_spacing_unit, lateral_spacing, and lateral_spacing_unit. Requires: plant_density, emitters_per_plant. Valid values are 'ac' or 'ha.' This value is only required upon initial configuration or when switching system types.

Request Parameters - Above Ground Drip (System Type 10)

Parameter Type Required Description

system_type

integer

yes

Enumeration value of irrigation system (i.e. 10). This value is only required upon initial configuration or when switching system types.

emitter_discharge_ rate

float

yes

The rate at which water is released from a drip emitter. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

emitter_discharge_ rate_unit

string

yes

Unit of measure for the rate of water being released from a drip emitter. Valid values are 'gpm' or 'lpm.' This value is only required upon initial configuration or when switching system types.

emitter_spacing

float

yes

Distance between emitters on a drip line. Mutually excludes: emitters_per_plant, plant_density, and plant_density_unit. Requires: emitter_spacing_unit, lateral_spacing, lateral_spacing_unit. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

emitter_spacing _unit

string

yes

The unit of measure for the distance between emitters on a drip line. Mutually excludes: emitters_per_plant, plant_density, and plant_density_unit. Requires: emitter_spacing, lateral_spacing, lateral_spacing_unit. Valid values are 'in', 'ft', 'cm', or 'm.' This value is only required upon initial configuration or when switching system types.

emitters_per_plant

integer

yes

Number of emitters assigned to each plant. Mutually excludes: emitter_spacing, emitter_spacing_unit, lateral_spacing, and lateral_spacing_unit. Requires: plant_density, plant_density_unit. The minimum value is 0. This value is only required upon initial configuration or when switching system types.

irrigated_area

float

yes

Area of applied irrigation. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

irrigated_area_unit

string

yes

Unit of the area of the applied irrigation. Valid values are 'ac' or 'ha.' This value is only required upon initial configuration or when switching system types.

lateral_spacing

float

yes

The lateral distance between drip lines. Mutually excludes: emitters_per_plant, plant_density, and plant_density_unit. Requires: emitter_spacing, emitter_spacing_unit, lateral_spacing_unit. The minimum value is 0.0. This value is only required upon initial configuration or when switching system types.

lateral_spacing_unit

string

yes

The unit of measure for the distance between drip lines. Mutually excludes: emitters_per_plant, plant_density, and plant_density_unit. Requires: emitter_spacing, emitter_spacing_unit, lateral_spacing. Valid values are 'in', 'ft', 'cm', or 'm.' This value is only required upon initial configuration or when switching system types.

plant_density

integer

yes

Number of irrigated plants per unit area. Mutually excludes: emitter_spacing, emitter_spacing_unit, lateral_spacing, and lateral_spacing_unit. Requires: plant_density_unit, emitters_per_plant. The minimum value is 0. This value is only required upon initial configuration or when switching system types.

plant_density_unit

string

yes

Areal unit of measure for the density of irrigated plants. Mutually excludes: emitter_spacing, emitter_spacing_unit, lateral_spacing, and lateral_spacing_unit. Requires: plant_density, emitters_per_plant. Valid values are 'ac' or 'ha.' This value is only required upon initial configuration or when switching system types.

Response Object (JSON)

The JSON response structure is representative of the available properties for a given irrigation system type if one has been configured.

Field Description

system

Contains specifications of the irrigation system. See above request parameters of the specific system type for parameter descriptions.

water

Contains properties related to the water and energy usage of the irrigation system.

water/water_cost

Cost of water per volume (water_unit).

water/water_unit

Volumetric unit used to measure water usage in 'gal' or 'l,' 'ac-in,' and 'm^3.'

water/max_moisture_refill

Desired maximum root zone water content expressed as a volumetric percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture below this level.

water/max_moisture_depletion

Management Allowed Depletion (MAD) level expressed as a volumetric percentage; recommended irrigation activities from the irrigation advisor will attempt to keep root zone soil moisture above this level.

water/flow_type

Irrigation delivery method. Valid values are 0 for pump or 1 for gravity-fed.

water/energy_source

The power source used to run the irrigation pump. Valid only for pump irrigation delivery (flow_type=0). Valid values are 0 for Electric, 1 for Diesel, 2 for Natural Gas, or 3 for LPG.

water/energy_cost

Cost to power the irrigation pump per energy unit (energy_unit). Valid only for pump irrigation delivery (flow_type=0).

water/energy_unit

Unit associated with the irrigation pump’s energy source 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).

water/set_irrigation_amount

The predefined depth of water to be applied for each recommended irrigation application. Value may be numeric or 'null.'

water/set_irrigation_unit

Unit of measure for the predefined amount of irrigation water to be applied for each recommended irrigation application in 'mm,' 'cm,' or 'in.'

water/post_irrigation _delay

Minimum time to wait in seconds after one irrigation recommendation ends and the next irrigation recommendation can be scheduled.

electricity_cost_schedule

User defined electricity rate schedule.

Example Request - Water Properties

Example request for adding water properties to a previous irrigation system configuration. Adding water section properties requires that the system section has been configured or all applicable system properties are included in the request.

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/modify/123?
user_id=456&account_id=789&flow_type=0&energy_source=0&energy_unit=kwh
&energy_cost=1.618&water_cost=2&water_unit=gal&energy_use_rate=2.3232323
&max_moisture_depletion=50.0&max_moisture_refill=-2.0
&set_irrigation_amount=3.77&set_irrigation_unit=in
&electricity_cost_schedule=null

Example Response - Water Properties

The following is an example of output when adding water properties to a previous irrigation system configuration.

{
    "system":{
        "flow_rate":3.14,
        "flow_rate_unit":"gpm",
        "irrigated_area":42,
        "irrigated_area_unit":"ac",
        "system_type":2,
        "nozzle_type":0,
        "drive_motor_cost":0.12,
        "drive_motor_rate":4.6692,
        "drive_motor_unit":"kwh"
    },
    "water":{
        "water_unit":"gal",
        "water_cost":2,
        "max_moisture_depletion":50.0,
        "max_moisture_refill":-2.0,
        "flow_type":0,
        "energy_source":0,
        "energy_unit":"kwh",
        "energy_cost":1.618,
        "energy_use_rate":2.3232323,
        "set_irrigation_amount":3.77,
        "set_irrigation_unit":"in",
        "electricity_cost_schedule":null
    }
}

Example Request - System and Water Property Updates

Example request for updating system and water specifications in the same request.

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/modify/123?
user_id=456&account_id=789&flow_rate=3.14&flow_rate_unit=gpm&irrigated_area=42
&irrigated_area_unit=ac&nozzle_type=0&system_type=2&drive_motor_unit=kwh
&drive_motor_rate=4.6692&drive_motor_cost=0.12&flow_type=1&water_cost=2
&water_unit=gAL&max_moisture_depletion=50.0&max_moisture_refill=-2.0
&set_irrigation_amount=3.77&set_irrigation_unit=mm&electricity_cost_schedule=
[[1507568400, 14400, 604800, 0.005],[1507554000, 432000, 604800, 0.0025],
[1507352400, 172800, 604800, 0.037],[1507392400, 112800, 204800, 0.099]]

Example Response - System and Water Property Updates

Example output when updating system and water specifications in the same request.

{
    "system":{
        "flow_rate":3.14,
        "flow_rate_unit":"gpm",
        "irrigated_area":42,
        "irrigated_area_unit":"ac",
        "system_type":2,
        "nozzle_type":0,
        "drive_motor_cost":0.12,
        "drive_motor_rate":4.6692,
        "drive_motor_unit":"kwh"
    },
    "water":{
        "water_unit":"gal",
        "water_cost":2,
        "max_moisture_depletion":50.0,
        "max_moisture_refill":-2.0,
        "flow_type":1,
        "set_irrigation_amount":3.77,
        "set_irrigation_unit":"mm",
        "electricity_cost_schedule":[
            [
                1507568400,
                14400,
                604800,
                0.005
            ],
            [
                1507554000,
                432000,
                604800,
                0.0025
            ],
            [
                1507352400,
                172800,
                604800,
                0.037
            ],
            [
                1507392400,
                112800,
                204800,
                0.099
            ]
        ]

    }
}

Example Request - Surface - Level Basin (System Type 0)

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/modify/123?
user_id=456&account_id=789&system_type=0&flow_rate=1000.0&flow_rate_unit=gpm
&irrigated_area=400&irrigated_area_unit=ac

Example Response - Surface - Level Basin (System Type 0)

{
    "system":{
        "flow_rate":1000.0,
        "flow_rate_unit":"gpm",
        "irrigated_area":400,
        "irrigated_area_unit":"ac",
        "system_type":0
    },
    "water":{}
}

Example Request - Surface - Furrow (System Type 1)

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/modify/123?
user_id=456&account_id=789&system_type=1&flow_rate=1000.0&flow_rate_unit=lpm
&irrigated_area=400&irrigated_area_unit=ha&slope=0.5&slope_unit=ft/ft

Example Response - Surface - Furrow (System Type 1)

{
    "system":{
        "flow_rate":1000.0,
        "flow_rate_unit":"lpm",
        "irrigated_area":400,
        "irrigated_area_unit":"ha",
        "slope":0.5,
        "slope_unit":"ft/ft",
        "system_type":1
    },
    "water":{}
}

Example Request - Center Pivot/Lateral Move with Sprinkler (System Type 2)

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/modify/123?
user_id=456&account_id=789&flow_rate=300&flow_rate_unit=gpm
&irrigated_area=42&irrigated_area_unit=ac&nozzle_type=0&system_type=2
&drive_motor_unit=kwh&drive_motor_rate=1.0&drive_motor_cost=0.25

Example Response - Center Pivot/Lateral Move with Sprinkler (System Type 2)

{
    "system":{
        "drive_motor_cost":0.25,
        "drive_motor_rate":1.0,
        "drive_motor_unit":"kwh",
        "flow_rate":300,
        "flow_rate_unit":"gpm",
        "irrigated_area":42,
        "irrigated_area_unit":"ac",
        "nozzle_type":0,
        "system_type":2
    },
    "water":{}
}

Example Request - Solid Set with Sprinkler (System Type 3)

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/modify/
123?user_id=456&account_id=789&system_type=3&flow_rate=1000.0
&flow_rate_unit=lpm&irrigated_area=200&irrigated_area_unit=ha&nozzle_type=1

Example Response - Solid Set with Sprinkler (System Type 3)

{
    "system":{
        "flow_rate":1000.0,
        "flow_rate_unit":"lpm",
        "irrigated_area":200,
        "irrigated_area_unit":"ha",
        "nozzle_type":1,
        "system_type":3
    },
    "water":{}
}

Example Request - Wheel Line/Hand Line with Sprinkler (System Type 4)

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/modify/123?
user_id=456&account_id=789&system_type=4&flow_rate=1000.0&flow_rate_unit=lpm
&irrigated_area=200&irrigated_area_unit=ac&nozzle_type=0

Example Response - Wheel Line/Hand Line with Sprinkler (System Type 4)

{
    "system":{
        "flow_rate":1000.0,
        "flow_rate_unit":"lpm",
        "irrigated_area":200,
        "irrigated_area_unit":"ac",
        "nozzle_type":0,
        "system_type":4
    },
    "water":{}
}

Example Request - Center Pivot/Lateral Move with Bubbler (System Type 5)

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/modify/123?
user_id=456&account_id=789&system_type=5&flow_rate=1000.0&flow_rate_unit=lpm
&irrigated_area=200&irrigated_area_unit=ha

Example Response - Center Pivot/Lateral Move with Bubbler (System Type 5)

{
  "system":{
    "drive_motor_unit":null,
    "drive_motor_rate":null,
    "drive_motor_cost":null,
    "flow_rate":1000.0,
    "flow_rate_unit":"lpm",
    "irrigated_area":200,
    "irrigated_area_unit":"ha",
    "system_type":5
  },
  "water":{}
}

Example Request - Solid Set with Bubbler (System Type 6)

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/modify/
123?user_id=456&account_id=789&system_type=6&flow_rate=1000.0
&flow_rate_unit=lpm&irrigated_area=200&irrigated_area_unit=ac

Example Response - Solid Set with Bubbler (System Type 6)

{
    "system":
        "flow_rate":1000.0,
        "flow_rate_unit":"lpm",
        "irrigated_area":200,
        "irrigated_area_unit":"ac",
        "system_type":6
    },
    "water":{}
}

Example Request - Wheel Line/Hand Line with Bubbler (System Type 7)

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/modify/123?
user_id=456&account_id=789&system_type=7&flow_rate=1000.0&flow_rate_unit=lpm
&irrigated_area=200&irrigated_area_unit=ac

Example Response - Wheel Line/Hand Line with Bubbler (System Type 7)

{
    "system":{
        "flow_rate":1000.0,
        "flow_rate_unit":"lpm",
        "irrigated_area":200,
        "irrigated_area_unit":"ac",
        "system_type":6
    },
    "water":{}
}

Example Request - Subsurface Drip (System Type 8)

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/modify/
123?user_id=456&account_id=789&system_type=8&line_depth=2&line_depth_unit=cm
&emitter_spacing=0.4&emitter_spacing_unit=m&emitter_discharge_rate_unit=lpm&
emitter_discharge_rate=0.0167&lateral_spacing=1.93&lateral_spacing_unit=m
&irrigated_area=25&irrigated_area_unit=ha

Example Response - Subsurface Drip (System Type 8)

{
    "system":{
        "emitter_discharge_rate":0.0167,
        "emitter_discharge_rate_unit":"lpm",
        "emitter_spacing":0.4,
        "emitter_spacing_unit":"m",
        "emitters_per_plant":null,
        "irrigated_area":25,
        "irrigated_area_unit":"ha",
        "lateral_spacing":1.93,
        "lateral_spacing_unit":"m",
        "line_depth":2,
        "line_depth_unit":"cm",
        "plant_density":null,
        "plant_density_unit":null,
        "system_type":8
    },
    "water":{}
}

Example Request - Subsurface Textile (System Type 9)

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/modify/
123?user_id=456&account_id=789&system_type=9&line_depth=1&line_depth_unit=in
&emitter_discharge_rate_unit=gpm&emitter_discharge_rate=0.004&plant_density=90
&plant_density_unit=ac&emitters_per_plant=6&irrigated_area=52
&irrigated_area_unit=ac

Example Response - Subsurface Textile (System Type 9)

{
    "system":{
        "emitter_discharge_rate":0.004,
        "emitter_discharge_rate_unit":"gpm",
        "emitter_spacing":null,
        "emitter_spacing_unit":null,
        "emitters_per_plant":6,
        "irrigated_area":52,
        irrigated_area_unit":"ac",
        "lateral_spacing":null,
        "lateral_spacing_unit":null,
        "line_depth":1,
        "line_depth_unit":"in",
        "plant_density":90,
        "plant_density_unit":"ac",
        "system_type":9
    },
    "water":{}
}

Example Request - Above Ground Drip (System Type 10)

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/modify/123?
user_id=456&account_id=789&system_type=10&line_depth=2&line_depth_unit=cm
&emitter_spacing=0.4&emitter_spacing_unit=m&emitter_discharge_rate_unit=lpm
&emitter_discharge_rate=0.0167&lateral_spacing=1.93&lateral_spacing_unit=m
&irrigated_area=25&irrigated_area_unit=ha

Example Response - Above Ground Drip (System Type 10)

{
    "system":{
        "emitter_discharge_rate":0.0167,
        "emitter_discharge_rate_unit":"lpm",
        "emitter_spacing":0.4,
        "emitter_spacing_unit":"m",
        "emitters_per_plant":null,
        "irrigated_area:25,
        "irrigated_area_unit":"ha",
        "lateral_spacing":1.93,
        "lateral_spacing_unit":"m",
        "plant_density":null,
        "plant_density_unit":null,
        "system_type":10
    },
    "water":{}
}

Get Irrigation System Properties - v1.0

This endpoint allows a user to view irrigation properties for a given field.

URL Description

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/get/{field_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_id

string

yes

ID of field in which properties are desired.

account_id

string

yes

A unique account ID provided by your Iteris account representative.

user_id

string

yes

User ID provided by the ClearAg Accounts API user management endpoints. User must have write privileges for the field.

Response Object (JSON)

Field Description

system

Contains specifications of the irrigation system. Please refer to the following endpoints for additional information: Get Irrigation System Properties - v1.0; Add/Modify Irrigation System Properties - v1.0; Delete Irrigation System Properties - v1.0.

water

Contains properties related to the water and energy usage of the irrigation system. Please refer to the following endpoints for additional information: Get Irrigation System Properties - v1.0; Add/Modify Irrigation System Properties - v1.0; Delete Irrigation System Properties - v1.0.

Example Request

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/get/123?
app_id=123&app_key=321&user_id=456&account_id=789

Example Response

Default response if no properties have been added, or a user deletes them:

{
    "irrigation":{
        "system":{},
        "water":{}
    }
}

Response where both water and system settings have been configured:

{
    "irrigation":{
        "system":{
            "drive_motor_cost":0.12,
            "drive_motor_rate":100.9,
            "drive_motor_unit":"kwh",
            "flow_rate":700.0,
            "flow_rate_unit":"gpm",
            "irrigated_area":50,
            "irrigated_area_unit":"ac",
            "nozzle_type":0,
            "system_type":2
        },
        "water":{
            "energy_cost":0.25,
            "energy_source":0,
            "energy_unit":"kwh",
            "energy_use_rate":100.0,
            "flow_type":0,
            "max_moisture_refill":-2.0,
            "max_moisture_depletion":50.0,
            "set_irrigation_amount":0.5,
            "set_irrigation_unit":"in",
            "water_cost":0.0036,
            "water_unit":"gal"
        }
    }
}

Delete Irrigation System Properties - v1.0

This endpoint allows a user to delete and reset irrigation properties back to the default for a field.

The default for a field is as follows:

{
    "irrigation":{
        "system":{ },
        "energy":{},
        "water":{}
    }
}

URL Description

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/
delete/{field_id}?app_id={string}&app_key={string}
&account_id={string}&user_id={string}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

field_id

string

yes

Specifies ID of field to be updated.

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. User must have write privileges for the field.

Response Object

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

Example Request

https://ag.clearapis.com/v1.0/crop_health/irrigation/properties/
delete/123?app_id=123&app_key=321&user_id=456&account_id=789

Example Response

true

Add Irrigation Activity - v1.0

This endpoint allows a user to add an irrigation activity to a given growth.

URL Description

https://ag.clearapis.com/v1.0/crop_health/growth/activity/irrigation/add/{growth_id}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}&unit={string}
&value={float}&activity_time={timestamp}&activity_time_end={timestamp}

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.

growth_id

string

yes

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

unit

string

yes

Measurement of "value" parameter. Valid values include 'mm,' 'cm,' and 'in.'

value

float

yes

Numeric indicator of activity. Value must be a float greater than 0.0.

activity_time

timestamp

no

Unix timestamp when the activity took place. This parameter defaults to current time if activity time is not provided. The minimum value is 31552800. If activity_time is not provided, activity_time_end must not be provided. If a non-null activity_time_end is provided, activity_time must be less than provided activity_time_end.

activity_time_end

timestamp

no

Activity end time in the form of a Unix timestamp. This value may be inferred given irrigation system configuration.

Response Object

Returns UUID of created irrigation activity.

Example Request

https://ag.clearapis.com/v1.0/crop_health/growth/activity/irrigation/add/321?
app_id=456&app_key=789&account_id=123&user_id=xyz-123&unit=in&value=2

Example Response

8888888-4444-4444-4444-cccccccccccc

Get Irrigation Activity By Activity ID - v1.0

This endpoint allows users to receive information related to the irrigation activity by utilizing an activity ID.

URL Description

https://ag.clearapis.com/v1.0/crop_health/growth/activity/irrigation/get/
{activity_id}?app_id={string}&app_key={string}&account_id={string}
&user_id={string}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

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

activity_id

string

yes

Target irrigation activity to be gathered.

Response Object (JSON)

Field Description

field_activity_id

ID of the activity.

created

Unix timestamp when the activity was created.

modified

Unix timestamp when the activity was last modified. A "null" value denotes that the activity has not been modified.

subtype

A further classification of the activity (zero is generic). **currently not implemented for this activity.

value

Amount of irrigation applied.

activity_time

Unix timestamp when the activity took place.

unit

Unit of measure for irrigation. Available values include 'mm,' 'cm,' or 'in.'

activity_type

Enumeration value of activity.

activity_time_end

Activity end time in the form of a Unix timestamp. This value may be inferred given irrigation system configuration.

Example Request

https://ag.clearapis.com/v1.0/crop_health/growth/activity/irrigation/
get/123-45?app_id=456&app_key=789&account_id=321&user_id=456

Example Response

{
    "field_activity_id":"50ab",
    "created":1457471059,
    "modified":null,
    "subtype":0,
    "value":45.90,
    "activity_time":1457471059,
    "activity_time_end": null
    "unit":"in",
    "activity_type":311
}

Get Irrigation Activity By Growth - v1.0

This endpoint allows a user to retrieve all irrigation activities on the field to which the growth is assigned.

URL Description

https://ag.us.clearapis.com/v1.0/crop_health/growth/activity/irrigation/
get/by_growth/{growth_id}?app_id={string}&app_key={string}&
account_id={string}&user_id={string}&whitelist_only={Boolean}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

growth_id

string

yes

Target growth to which to receive activities.

account_id

string

yes

Your Accounts API account ID.

user_id

string

yes

User must have read privileges for field that target growth is assigned.

whitelist_only

Boolean

no

If whitelist_only is in the request, then only activities that have membership in the target growth’s whitelist are returned.

Response Object (JSON)

Field Description

created

Unix timestamp when the activity was created.

field_activity_id

ID of activity.

whitelist

Boolean value denoting membership to the target growths whitelist.

modified

Unix timestamp when the activity was last modified. A "null" response denotes that the activity has not been modified.

activity_type

Enumeration value of activity.

activity_time

Unix timestamp when the activity took place.

value

The amount of irrigation applied.

unit

The unit of measure for irrigation. Available values include 'mm,' 'cm,' or 'in.'

subtype

Further classification of activity. Zero is generic. **currently not implemented for this activity.

activity_time_end

Activity end time in the form of a Unix timestamp. This value may be inferred given irrigation system configuration.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/growth/activity/irrigation/
get/by_growth/123-45?app_id=456&app_key=789&account_id=321&user_id=456

Example Response

[{
    "field_activity_id":"50ab",
      "created":1457471059,
      "whitelist":false,
      "modified":null,
      "subtype":0,
      "value":45.90,
      "activity_time":1457471059,
      "activity_time_end":null,
      "unit":"in",
      "activity_type":311
},   {
    "field_activity_id":"50ab",
      "created":1457471000,
      "whitelist":true,
      "modified":1457471059,
      "subtype":0,
      "value":3.14159,
      "activity_time":1457471059,
      "activity_time_end":1457475555,
      "unit":"cm",
      "activity_type":311
}]

Modify Irrigation Activity - v1.0

This endpoint allows users to modify unit, value, and activity time of an irrigation activity.

URL Description

https://ag.us.clearapis.com/v1.0/crop_health/growth/activity/irrigation/
modify/{activity_id}?app_id={string}&app_key={string}&value={float}
&unit={string}&user_id={string}&account_id={string}
&activity_time={timestamp}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

activity_id

string

yes

ID of target irrigation activity to modify.

value

float

no

A float greater than zero (unit and value are mutually inclusive).

unit

string

no

Values can be 'mm,' 'cm,' or 'in' (unit and value are mutually inclusive).

user_id

string

yes

User must have write privileges.

account_id

string

yes

Your Accounts API account ID.

activity_time

timestamp

no

Unix timestamp that the activity took place. Minimum value must be 31552800.

Response Object

200 response results in response with body of "true."

Please note that the request will result in a 400 response if at least one value is not given to update or the requested modification would result in no change to the irrigation activity.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/growth/activity/irrigation/modify/123-5813?app_id=456&app_key=789&account_id=123&user_id=456
&activity_time=315532800&unit=in&value=3.14159

Example Response

true

Delete Irrigation Activity - v1.0

This endpoint allows users to delete an irrigation activity. In this process, the activity is also removed from the field whitelist and the growth whitelist.

URL Description

https://ag.us.clearapis.com/v1.0/crop_health/growth/activity/irrigation/
delete/{activity_id}?user_id={string}&app_id={string}&app_key={string}
&account_id={string}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

activity_id

string

yes

ID of target irrigation activity to modify.

user_id

string

yes

User must have write privileges.

account_id

string

yes

Your Accounts API account ID.

Response Object

Returns "true" on success.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/growth/activity/irrigation/
delete/123-5813?app_id=456&app_key=789&user_id=456&account_id=123

Example Response

true

Appendix

Common HTTP response codes

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

  • 200 OK - The request was successful.

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

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

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

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

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

  • 502 Bad Gateway - The service is not reachable.

Null or Empty Values

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

Unix Timestamp

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

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

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

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

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

Regional-based Account Access

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

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

Supported Crops by Feature

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

Barley

X

X

X

X

X

X

X

Bent Turfgrass

X

X

X

Bermuda Turfgrass

X

X

X

Canola

X

X

X

X

X

X

X

Corn

X

X

X

X

X

X

X

Cotton

X

X

X

X

X

X

Peanut

X

Potato

X

Preset Almond

X

X

X

X

Preset Leaf Lettuce

X

X

X

X

Preset Lemon

X

X

X

X

Preset Orange

X

X

X

X

Preset Potato

X

X

X

X

Preset Strawberry

X

X

X

X

Preset Table Grape

X

X

X

X

Preset Tomato

X

X

X

X

Preset Wine Grape

X

X

X

X

Sorghum

X

X

X

X

X

X

Soybean

X

X

X

X

X

X

Spring wheat

X

X

X

X

X

X

X

Sugar Beet

X

X

X

Sunflower

X

X

X

X

X

X

Winter Wheat

X

X

X

X

X

X

X

Zoysia Turfgrass

X

X

X

USDA Texture Classes

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.

9/3/19

Added the Hourly Irrigation Custom Analysis Auxiliary Data and the Daily Irrigation Custom Analysis Auxiliary Data endpoints.

7/15/19

Added the 'obs_influenced' parameter that, if present, user provided field observation data has been provided. This user provided data overrides the precip_acc_period value calculated by the model.