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 5/13/19

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.

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

Unix timestamp valid near the starting time for the requested canopy wetness.

end

timestamp

yes

Unix timestamp valid near the ending time for the requested canopy wetness.

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

Unix timestamp of the end of the hour being returned for the requested canopy wetness.

valid_time_start

Unix timestamp of the start of the hour being returned for the requested canopy wetness.

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 in the form of a Unix timestamp. Maximum is 240 hours into the future.

end

timestamp

yes

Query end time in the form of a Unix timestamp. Maximum is 240 hours into the future.

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." Please refer to the Language section of the Appendix for additional details.

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.

valid_time_start

Start time of the period, expressed as a 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. "n/a" if wind speed is less than 1 mph.

wind_gust

Wind gust at two meters above ground level. "n/a" if either wind speed is less than 5 mph, or the difference between the wind gust and wind speed is less than 5 mph.

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.

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>

Language

Entry Language

de

German

en-us

English (US localization. This is the default if lang not set)

es-es

Spanish (Spain localization)

es-mx

Spanish (Mexico localization)

fr

French

fr-ca

French (Canadian localization)

ja

Japanese

it

Italian

it-it

Italian (Italy localization)

nl

Dutch

pl

Polish

pl-pl

Polish (Poland)

ro

Romanian

ro-ro

Romanian (Romania)

ru

Russian

uk

Ukrainian

Changelog

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

5/13/19

The descriptions of wind gust and direction have been updated.

4/4/19

Added the "language" parameter to applicable endpoints and an associated language listing section in the Appendix.