ClearAg

Spray Conditions API

Iteris’ Spray Conditions API meets the growing demand for minimizing drift, over-spraying, and crop damage, while improving the results of crop protection product applications.

Spray Conditions Decision Support

last updated 11/7/18

The ClearAg Spray Window Decision Support API meets the growing demand for minimizing drift, over-spraying and crop damage, while improving the results of crop protection product applications. The Spray Window API includes 10 environmental conditions most critical for spray applications: wind direction; wind speed; inversion risk; rain-free hours; 24-hour precipitation amounts; leaf canopy wetness; air temperature; humidity; field soil conditions; and Delta-T.

Multiple data center regions are available to meet users’ legal and performance needs. Currently, data centers exist within the United States (ag.us.clearapis.com) and the European Union (ag.eu.clearapis.com). Account and related information such as fields and growths are not shared between these regions. Data resolution and availability also vary by region, and each region requires a unique set of credentials. Please contact your account representative for account creation, data segregation, and data coverage information.

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

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

Additional API information is available in the Appendix.

Leaf Canopy Wetness - v1.1

The Leaf Canopy Wetness endpoint provides an hour-by-hour estimate of the wetness of leaves for a user-provided location. This endpoint may be used to estimate pressures for moisture-related diseases that can impact plant growth or crop yield.

URL Description

https://ag.us.clearapis.com/v1.1/canopywetness/hourly?app_id={string}
&app_key={string}&location={lat, lon coordinates}&start={integer}
&end={integer}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

start

timestamp

yes

Epoch timestamp valid near the starting time for the requested canopy wetness. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

end

timestamp

yes

Epoch timestamp valid near the ending time for the requested canopy wetness. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

location

lat, lon coordinates

yes

User-provided latitude and longitude coordinates in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field. Users are allowed a maximum of five coordinates1, formatted as "&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)]."

1 Additional coordinates are not counted against a client’s account.

Response Object (JSON)

Field Description

canopy_surface_water

The measure of the amount of water on surface vegetation, taken as an average from all available models.

canopy_wetness_classification

A text value representation of the overall canopy wetness.

canopy_wetness_id

An enumerated representation of the overall canopy wetness (1=Dry, 2=Marginal, 3=Wet).

mosaic_canopy_surface_water

The measure of the amount of water on surface vegetation as estimated by the Mosaic model.

noah_canopy_surface_water

The measure of the amount of water on surface vegetation as estimated by the Noah model.

valid_time_end

Epoch timestamp of the start of the hour being returned for the requested canopy wetness. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

valid_time_start

Epoch timestamp of the start of the hour being returned for the requested canopy wetness. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

Example Request

https://ag.us.clearapis.com/v1.1/canopywetness/hourly?app_id=123&app_key=321
&location=47.546872,-100.151367&start=1393632000&end=1393639200

Example Response

{
    "47.546872,-100.151367":{
        "hourly_canopy_wetness:1393632000":{
            "canopy_surface_water":{
                "unit":"in",
                "value":0.01
            },
            "canopy_wetness_classification":{
                "unit":"n/a",
                "value":"Wet"
            },
            "canopy_wetness_id":{
                "unit":"n/a",
                "value":3
            },
            "mosaic_canopy_surface_water":{
                "unit":"in",
                "value":0.01
            },
            "noah_canopy_surface_water":{
                "unit":"in",
                "value":0.01
            },
            "valid_time_end":1393635600,
            "valid_time_start":1393632000
        },...
    }
}

Hourly Spray Conditions - v1.0

The Hourly Spray Conditions endpoint retrieves and displays up to 240 hours of historical and forecast data, useful for evaluating suitability for spraying.

URL Description

https://ag.us.clearapis.com/v1.0/hourly/spray_conditions?
app_id={string}&app_key={string}&location={lat, lon coordinates}
&start={timestamp}&end={timestamp}&unitcode={string}&lang={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.

location

lat, lon coordinates

yes

User-provided latitude and longitude coordinates in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field. Users are allowed a maximum of five coordinates,1 formatted as "&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)]."

start

timestamp

yes

Query start time. Maximum is 240 hours into the future. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

end

timestamp

yes

Query end time. Maximum is 240 hours into the future. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

unitcode

string

no

Unit conversion set to be used. Default is "us-std." Valid values are "us-std," "si-std," "us-std-precise," and "si-std-precise." Values of "us-std-precise" and "si-std-precise" round output values to six decimal places.

lang

string

no

Language setting. Default is "en-us." Currently, only "en-us" is supported.

1 Additional coordinates are not counted against a client’s account.

Response Object (JSON)

Field Description

air_temp

Air temperature at two meters above ground level.

canopy_wetness_ classification

A text value representation of the overall canopy wetness. Possible values include "Dry", "Marginal", and "Wet".

canopy_wetness_id

An enumerated representation of the overall canopy wetness. Possible values include "1" ("Dry"), "2" ("Marginal"), and "3" ("Wet").

delta_t

Delta-T data. Delta-T is the difference between the air temperature and wet-bulb temperature. Note that units are sensitive to unitcode setting.

inversion_risk

Likelihood of a thermal inversion based on near-surface lapse rates and wind speeds. Possible values include "low", "medium", and "high".

lapse_rate_0to2m

Change in temperature from the surface to two meters above ground level. Negative if temperature decreases with increasing altitude; positive if temperature increases with increasing altitude. Note that lapse rate units are K/m regardless of unitcode setting.

lapse_rate_2to80m

Change in temperature from two to 80 meters above ground level. Negative if temperature decreases with increasing altitude; positive if temperature increases with increasing altitude. Note that lapse rate units are K/m regardless of unitcode setting.

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.

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.

valid_time_end

End time of the period, expessed as a Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

valid_time_start

Start time of the period, expressed as a Unix timestamp. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

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.

wind_gust

Wind gust at two meters above ground level. "n/a" if less than 5.0 mph stronger than wind speed.

wind_speed

Wind speed at two meters above ground level.

Example Request

https://ag.us.clearapis.com/v1.0/hourly/spray_conditions?
location=47,-97&start=1502985600&end=1502989200

Example Response

{
    "47,-97":{
        "1502985600":{
            "air_temp":{
                "unit":"F",
                "value":68.0
            },
            "canopy_wetness_classification":{
                "unit":"n/a",
                "value":"Wet"
            },
            "canopy_wetness_id":{
                "unit":"n/a",
                "value":3
            },
            "delta_t":{
                "unit":"F",
                "value":4.0
            },
            "inversion_risk":{
                "unit":"n/a",
                "value":"low"
            },
            "lapse_rate_0to2m":{
                "unit":"K/m",
                "value":-2.84
            },
            "lapse_rate_2to80m":{
                "unit":"K/m",
                "value":-0.0199
            },
            "precip_acc_period":{
                "unit":"in",
                "value":0.0
            },
            "precip_prob":{
                "unit":"%",
                "value":0.0
            },
            "relative_humidity":{
                "unit":"%",
                "value":84.0
            },
            "valid_time_end":1502989200,
            "valid_time_start":1502985600,
            "wind_direction":{
                "unit":"degrees",
                "value":360.0
            },
            "wind_gust":{
                "unit":"mph",
                "value":22.0
            },
            "wind_speed":{
                "unit":"mph",
                "value":14.0
            }
        }
    }
}

Spray Window - v1.0

The Spray Window endpoint provides hourly spraying conditions tailored to a particular field and chemical application, using high-resolution weather forecasts and thresholds for maximum acceptable wind speed and number of hours before the next potential rain. In return, a rating of good, marginal, or poor spraying conditions are provided.

URL Description

https://ag.us.clearapis.com/v1.0/crop_health/advisors/spray_window?
app_id={string}&app_key={string}&location={lat, lon coordinates}
&start={integer}&end={integer}&wind_speed_threshold={integer}
&rain_free_threshold={integer}&inversion_risk_threshold={integer}

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

location

lat, lon coordinates

yes

User-provided latitude and longitude coordinates in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field. Users are allowed a maximum of five coordinates1, formatted as "&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)]."

start

integer

yes

Start hour of time range. Valid values range from 0 to 240. Hour 0 represents the current hour.

end

integer

yes

End hour of time range. Valid values range from 0 to 240. Cannot be greater than 240 minus the "rain_free_threshold" value.

rain_free_threshold

integer

yes

Number of hours to look ahead in forecast for rain free period. Chances for precipitation within the applicable timeframe results in reduced spraying suitability. Must be greater than or equal to zero.

wind_speed_threshold

integer

yes

Maximum wind speed value in mph allowed for favorable spraying conditions. Forecast wind speeds being greater than the threshold value results in reduced spraying suitability for applicable timeframes. Must be greater than or equal to zero.

inversion_risk_threshold

integer

no

This parameter defines at what point the inversion_risk is too high. Only three, four, or five thresholds are allowed. If the inversion_risk_threshold is provided and the inversion_risk is higher than the inversion_risk_threshold, the condition for that date will be set to "poor."

1 Additional coordinates are not counted against a client’s account.

Response Object (JSON)

Field Description

inversion_risk_factor

An enumerated representation of the likelihood of a thermal inversion. (3 - Low, 4 - Medium, 5 - High)

precip_suitability

An enumerated representation of the spraying suitability owing to forecast precipitation probability. (0 - Good, 1 - Marginal, 2 - Poor)

spray_suitability

An enumerated representation of the overall spraying suitability. (0 - Good, 1 - Marginal, 2 - Poor)

wind_suitability

An enumerated representation of the spraying suitability owing to forecast wind speeds. (0 - Good, 1 - Marginal, 2 - Poor)

spray_advisors

Container of enumeration value definitions. Note that only values appearing in the "data" section are defined here.

Example Request

https://ag.us.clearapis.com/v1.0/crop_health/advisors/spray_window?app_id=123
&app_key=321&location=47,-97&start=0&end=24&wind_speed_threshold=6
&rain_free_threshold=2

Example Response

{
    "data":{
        "47,-97":{
            "1471449600":{
                "inversion_risk_factor":"3",
                "precip_suitability":"0",
                "spray_suitability":"0",
                "wind_suitability":"0"
            },...
        }
    },
    "spray_advisors":{
        "0":{
            "advisor":"Good"
        },...
    }
}

Appendix

Common HTTP response codes

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

  • 200 OK - The request was successful.

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

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

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

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

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

  • 502 Bad Gateway - The service is not reachable.

Null or Empty Values

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

Epoch/Unix Timestamp

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

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

Regional-based Account Access

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

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

Feedback Information

The feedback timestamp, which is the precise time when the feedback was observed, must happen after the plant/emergence date and prior to the current date. Growth feedback is considered (confirmed) if the stage of feedback occurs before the model anticipates. If there are multiple feedbacks for a given stage, the feedback with the most recent feedback timestamp will take precedence. If more than one feedback with the same stage and the same feedback timestamp are present, then the system will use the feedback with the most recent created timestamp.

Changelog

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