Introduction

Welcome to the Iteris ClearAg Soil Conditions API. Utilizing Iteris’ proprietary land surface models that have been specially adapted to the unique needs of the agricultural community, the Soil Conditions API delivers actionable intelligence about soil moisture and temperature at multiple depths, as well as an hourly field accessibility prediction service — a decision aid for determining when conditions will be favorable for field activity.

Please note that before users can access the ClearAg Soil Conditions API, an active account and license key is required. These credentials will be provided for each service request. To obtain your API key, contact your Iteris account representative.

API Services

The ClearAg Soil Conditions API places historical and forecast soil data at the users’ fingertips. This API provides soil moisture and temperature data valid at varying depths beneath the ground surface, as estimated by in-house soil computer models. The endpoints provided through this service include Hourly Soil, Daily Soil, and Hourly Field Accessibility.

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). Data resolution and availability vary by region, and each region requires a unique set of credentials. Please contact your account representative for account creation or data coverage information.

Additional API information, such as details on supported unit sets and API behavior, is available in the Supplementary API Information section of the Appendix.

1. Hourly Soil - v1.1

Through the Hourly Soil endpoint, users have the ability to obtain hourly soil temperature and moisture data valid for a user-defined time range and location. These values not only give temperature and moisture levels, but also show how they compare to soil climatology at the chosen location and time.

The Hourly Soil endpoint’s dataset is valid from the beginning of the previous year and up to 240 hours into the future, and is available globally.

1.1. URL Description

http://ag.us.clearapis.com/v1.1/hourly/soil?app_id={string}&app_key={string}
&location={lat, lon coordinates}&start={timestamp}&end={timestamp}&unitcode={string}

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

Start time of the data returned2.

end

timestamp

yes

End time of the data returned2.

location

lat, lon coordinates

yes

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

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.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

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

1.3. Response Object (JSON)

The response may vary based on unit code selected.

Field Description

abs_scaled_soil_moisture_ 0to10cm

Moisture content of the layer between the surface and the 10-cm depth, relative to saturation and “wilting point” thresholds for the soil type at the chosen 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.

abs_scaled_soil_moisture_ 0to200cm

Moisture content of the layer between the surface and the 200-cm depth, relative to saturation and “wilting point” thresholds for the soil type at the chosen location. Valid values range from 0 to 1.

normalized_soil_moisture_ 0to10cm

Provides an estimate of how the soil moisture level compares with the location’s climatological average value in the layer between the surface and the 10-cm depth. Positive values indicate above-normal moisture content, negative values indicate below-normal moisture content, and value magnitudes denote how much they vary from normal in this layer. For example, a value of 0.5 (-0.5) indicates that the moisture level at the indicated time and location is 0.5 standard deviations above (below) the normal soil moisture level for the same layer, location, and time.

normalized_soil_moisture_ 0to200cm

Provides an estimate of how the soil moisture level compares with the location’s climatological average value in the layer between the surface and the 200-cm depth. Positive values indicate above-normal moisture content, negative values indicate below-normal moisture content, and value magnitudes denote how much they vary from normal in this layer.

scaled_soil_moisture_0to10cm

Moisture content of the layer between the surface and the 10-cm depth, relative to the location’s soil moisture climatology. Valid values range from 0 to 1, where 0 means that the estimated moisture level is the lowest, 0.5 means the level is at the average, and 1 means the level is the highest it has historically been at the chosen location and day of year. Therefore, values less than (greater than) 0.5 indicate drier (wetter) than normal conditions, and the degree of deviation from normal is represented by how close values come to either 0 or 1.

scaled_soil_moisture_ 0to200cm

Moisture content of the layer between the surface and the 200-cm depth, relative to the location’s soil moisture climatology. Valid values range from 0 to 1.

soil_moisture_0to10cm

Total moisture content of the layer between the surface and the 10-cm depth.

soil_moisture_0to200cm

Total moisture content of the layer between the surface and the 200-cm depth.

soil_temp_0to10cm

Average temperature of the layer between the surface and the 10-cm depth.

valid_time_end

Valid end time (Epoch time) for the hourly period2.

valid_time_start

Valid start time (Epoch time) for the hourly period2.

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

1.4. Example Request

http://ag.us.clearapis.com/v1.1/hourly/soil?app_id=123&app_key=321
&location=46.77,-100.75&start=1341532800&end=1341619200

1.5. Example Response

{
    "46.77,-100.75":{
        "hourly_historical_soil:1341532800":{
            "abs_scaled_soil_moisture_ 0to10cm":{
                "unit":"n/a",
                "value":"0.07"
            }
            "abs_scaled_soil_moisture_ 0to200cm":{
                "unit":"n/a",
                "value":"0.27"
            }
            "normalized_soil_moisture_0to10cm":{
                "unit":"n/a",
                "value":-2.2
            },
            "normalized_soil_moisture_0to200cm":{
                "unit":"n/a",
                "value":-1.13
            },
            "scaled_soil_moisture_0to10cm":{
                "unit":"n/a",
                "value":0.0
            },
            "scaled_soil_moisture_0to200cm":{
                "unit":"n/a",
                "value":0.18
            },
            "soil_moisture_0to10cm":{
                "unit":"in",
                "value":0.33
            },
            "soil_moisture_0to200cm":{
                "unit":"in",
                "value":13.06
            },
            "soil_temp_0to10cm":{
                "unit":"F",
                "value":87.0
            },
            "valid_time_end":1341536400,
            "valid_time_start":1341532800
        },...
    }
}

2. Daily Soil - v1.1

Through the Daily Soil endpoint users can obtain daily soil temperature and moisture data valid for a user-defined time range and location. These values not only give estimates of actual temperature and moisture levels, but also show how they compare to soil climatology at the chosen location and time.

The Daily Soil endpoint’s dataset is valid from January 1, 1980 and up to 9 days into the future, and is available globally.

2.1. URL Description

http://ag.us.clearapis.com/v1.1/daily/soil?app_id={string}&app_key={string}
&location={lat, lon coordinates}&start={timestamp}&end={timestamp}&unitcode={string}

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

Start time of the data returned2.

end

timestamp

yes

End time of the data returned2.

location

lat, lon coordinates

yes

User-provided latitude and longitude coordinates in decimal degrees. Users are allowed a maximum of five coordinates1, formatted as “&location=[(<lat_1>,<lon_1>),(<lat_2>,<lon_2>)].”

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.

1 Additional coordinates are not counted against a client’s account, but will count as additional requests in the future.

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

2.3. Response Object (JSON)

The response may vary based on unit code selected.

Field Description

abs_scaled_soil_moisture_ 0to10cm

Moisture content of the layer between the surface and the 10-cm depth, relative to saturation and “wilting point” thresholds for the soil type at the chosen 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.

abs_scaled_soil_moisture_ 0to200cm

Moisture content of the layer between the surface and the 200-cm depth, relative to saturation and “wilting point” thresholds for the soil type at the chosen location. Valid values range from 0 to 1.

normalized_soil_moisture_ 0to10cm

Provides an estimate of how the soil moisture level compares with the location’s climatological average value in the layer between the surface and the 10-cm depth. Positive values indicate above-normal moisture content, negative values indicate below-normal moisture content, and value magnitudes denote how much they vary from normal in this layer. For example, a value of 0.5 (-0.5) indicates that the moisture level at the indicated time and location is 0.5 standard deviations above (below) the normal soil moisture level for the same layer, location, and time.

normalized_soil_moisture_ 0to200cm

Provides an estimate of how the soil moisture level compares with the location’s climatological average value in the layer between the surface and the 200-cm depth. Positive values indicate above-normal moisture content, negative values indicate below-normal moisture content, and value magnitudes denote how much they vary from normal in this layer.

scaled_soil_moisture_0to10cm

Moisture content of the layer between the surface and the 10-cm depth, relative to the location’s soil moisture climatology. Valid values range from 0 to 1, where 0 means that the estimated moisture level is the lowest, 0.5 means the level is at the average, and 1 means the level is the highest it has historically been at the chosen location and day of year. Therefore, values less than (greater than) 0.5 indicate drier (wetter) than normal conditions, and the degree of deviation from normal is represented by how close values come to either 0 or 1.

scaled_soil_moisture_ 0to200cm

Moisture content of the layer between the surface and the 200-cm depth, relative to the location’s soil moisture climatology. Valid values range from 0 to 1.

soil_moisture_0to10cm

24-hour average moisture content of the layer between the surface and the 10-cm depth.

soil_moisture_0to200cm

24-hour average moisture content of the layer between the surface and the 200-cm depth.

soil_temp_0to10cm

Average temperature of the layer between the surface and the 10-cm depth.

soil_temp_max_0to10cm

Maximum temperature of the layer between the surface and the 10-cm depth.

soil_temp_min_0to10cm

Minimum temperature of the layer between the surface and the 10-cm depth.

2.4. Example Request

http://ag.us.clearapis.com/v1.1/daily/soil?app_id=123&app_key=321
&location=46.77,-100.75&start=1341532800&end=1341619200

2.5. Example Response

{
    "46.77,-100.75":{
        "2012-07-06":{
            "abs_scaled_soil_moisture_ 0to10cm":{
                "unit":"n/a",
                "value":"0.3"
            }
            "abs_scaled_soil_moisture_ 0to200cm":{
                "unit":"n/a",
                "value":"0.28"
            },
            "normalized_soil_moisture_0to10cm":{
                "unit":"n/a",
                "value":0.18
            },
            "normalized_soil_moisture_0to200cm":{
                "unit":"n/a",
                "value":-0.89
            },
            "scaled_soil_moisture_0to10cm":{
                "unit":"n/a",
                "value":0.54
            },
            "scaled_soil_moisture_0to200cm":{
                "unit":"n/a",
                "value":0.25
            },
            "soil_moisture_0to10cm":{
                "unit":"in",
                "value":0.7
            },
            "soil_moisture_0to200cm":{
                "unit":"in",
                "value":13.54
            },
            "soil_temp_0to10cm":{
                "unit":"F",
                "value":69.0
           },
            "soil_temp_max_0to10cm":{
                "unit":"F",
                "value":76.0
           },
            "soil_temp_min_0to10cm":{
                "unit":"F",
                "value":69.0
            }
        }
    }
}

3. Hourly Field Accessibility - v1.2

The field accessibility service offers estimates of current and forecasted field conditions. The field accessibility classification provides an estimate of whether or not the field conditions are favorable to perform field operations. A "Good" classification means the field conditions are favorable for field operations; a "Marginal" classification means the field may not be appropriate for field operations; and a "Poor" classification rating means the field conditions are inappropriate for field operations.

3.1. URL Description

http://ag.us.clearapis.com/v1.2/field_accessibility/hourly?app_id={string}
&app_key={string}&account_id={string}&user_id={string}&field_id={string}
&start={integer}&end={integer}

3.2. Request Parameters

Parameter Type Required Description

end

integer

yes

End hour of time range. Supported values range from 0 to 240.

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 provided field_id.

field_id

string

yes

Field ID provided by and used with the Accounts API. This ID is given when a field is successfully registered through the Accounts API.

start

integer

yes

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

3.3. Response Object (JSON)

Field Description

field_accessibility/ accessibility_id

An enumerated representation of the field conditions. This is passed to the Field Accessibility Feedback endpoints.

field_accessibility/ classification

A textual representation of the field conditions. Possible values include "Poor," "Marginal," or "Good."

field_accessibility/ value

A numerical representation of the field conditions. Possible values range from -1 to 1, with small negative or positive values indicating marginal field conditions, values closer to -1 indicating poor conditions, and values closer to 1 indicating good conditions.

field_metadata/ field_id

Field ID provided by the Accounts API.

field_metadata/ growth_id

Growth ID provided by the Accounts API.

field_metadata/ latitude

Latitude coordinate of the field location obtained from the Accounts API.

field_metadata/ longitude

Longitude coordinate of the field location obtained from the Accounts API.

field_metadata/ model_id

An identification of the numerical model that produced the result. This is passed to the Field Accessibility Feedback endpoints.

field_metadata/ user_id

User ID provided by the Accounts API.

3.4. Example Request

http://ag.us.clearapis.com/v1.2/field_accessibility/hourly?app_id=123&app_key=321
&account_id=abc&user_id=xyz-123&field_id=321-abc&start=0&end=240

3.5. Example Response

{
    "data":{
        "321-abc":{
            "field_data":{
                "1463601600":{
                    "field_accessibility":{
                        "accessibility_id":2,
                        "classification":"Poor",
                        "value":-1
                    }
                },...
            },
            "field_metadata":{
                "field_id":"321-abc",
                "growth_id":null,
                "latitude":"47",
                "longitude":"-97",
                "model_id":"987-lmn",
                "user_id":"xyz-123"
            }
        }
    }
}

Appendix

Appendix A: Supplementary API Information

A.1. 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.

A.2. 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.

A.3. Parameter Units

Below is a listing of weather parameter units that appear in the API endpoints, including a description of each and a listing of the associated parameter types.

System of units Parameter unit What it stands for Associated parameters

US-std

F

Degrees Fahrenheit

temperature

SI-std

C

Degrees Celsius

temperature

US-std

In

Inch

soil moisture content

SI-std

mm

Millimeter

soil moisture content

A.4. Epoch/Unix Timestamp

Iteris employs Epoch/Unix timestamps for time-based parameters. This system works by defining situations in time by the number of seconds since 1970-01-01 00:00 Coordinated Universal Time (UTC).