ClearAg

Soil Conditions API

Utilizing Iteris’ proprietary Land Surface Modeling, ClearAg Soil Conditions API provides users with soil moisture and temperature at varying depths.

Soil Conditions

last updated 5/13/19

This bundle provides users with soil moisture and temperature data at varying depths as estimated by Iteris' proprietary Land Surface Modeling. This bundle is best-suited for users who only need generalized information on unirrigated land, lacking user-provided specific soil texture class information and thus relying on various public sources of geospatial soil characteristics. All of these endpoints provide data for any location in the world. Hourly conditions are available for any period beginning January 1 of the previous calendar year through nine days into the future. Daily values are available for any period beginning January 1, 1980 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.

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, such as details on supported unit sets and API behavior, is available in the Appendix.

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.

URL Description

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

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

start

timestamp

yes

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

end

timestamp

yes

End time of the data returned in the form of a 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 coordinates,1 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.

Response Object (JSON)

The response may vary based on unit code selected.

Field Description

abs_scaled_paw_soil_moisture_ 0to10cm

Moisture content of the layer between the surface and the 10-cm depth expressed as a scaled value between field capacity (1.0) and wilting point (0.0) for the soil type at the chosen location. Values near 0.0 (1.0) indicate very dry (very wet) soils at the chosen location and time with minimal (plentiful) plant available water.

abs_scaled_paw_soil_moisture_ 0to200cm

Moisture content of the layer between the surface and the 200-cm depth expressed as a scaled value between field capacity (1.0) and wilting point (0.0) for the soil type at the chosen location. Values near 0.0 (1.0) indicate very dry (very wet) soils at the chosen location and time with minimal (plentiful) plant available water.

abs_scaled_soil_moisture_ 0to10cm

Moisture content of the layer between the surface and the 10-cm depth expressed as a scaled value between saturation (1.0) and wilting point (0.0) for the soil type at the chosen location. Values near 0.0 (1.0) 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 expressed as a scaled value between saturation (1.0) and wilting point (0.0) for the soil type at the chosen location. Values near 0.0 (1.0) indicate very dry (very wet) soils at the chosen location and time.

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 for the hourly period, in the form of a Unix timestamp.

valid_time_start

Valid start time for the hourly period, in the form of a Unix timestamp.

Example Request

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

Example Response

{
    "46.77,-100.75":{
        "hourly_historical_soil:1341532800":{
            "abs_scaled_paw_soil_moisture_0to10cm":{
                "unit":"n/a",
                "value":0.15
            },
            "abs_scaled_paw_soil_moisture_0to200cm":{
                "unit":"n/a",
                "value":0.35
            },
            "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
        },...
    }
}

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.

URL Description

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

Request Parameters

Parameter Type Required Description

app_id

string

yes

API ID provided by Iteris.

app_key

string

yes

API key provided by Iteris.

start

timestamp

yes

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

end

timestamp

yes

End time of the data returned in the form of a 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 coordinates,1 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.

Response Object (JSON)

The response may vary based on unit code selected.

Field Description

abs_scaled_paw_soil_moisture_ 0to10cm

Moisture content of the layer between the surface and the 10-cm depth expressed as a scaled value between field capacity (1.0) and wilting point (0.0) for the soil type at the chosen location. Values near 0.0 (1.0) indicate very dry (very wet) soils at the chosen location and time with minimal (plentiful) plant available water.

abs_scaled_paw_soil_moisture_ 0to200cm

Moisture content of the layer between the surface and the 200-cm depth expressed as a scaled value between field capacity (1.0) and wilting point (0.0) for the soil type at the chosen location. Values near 0.0 (1.0) indicate very dry (very wet) soils at the chosen location and time with minimal (plentiful) plant available water.

abs_scaled_soil_moisture_ 0to10cm

Moisture content of the layer between the surface and the 10-cm depth expressed as a scaled value between saturation (1.0) and wilting point (0.0) for the soil type at the chosen location. Values near 0.0 (1.0) 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 expressed as a scaled value between saturation (1.0) and wilting point (0.0) for the soil type at the chosen location. Values near 0.0 (1.0) indicate very dry (very wet) soils at the chosen location and time.

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.

Example Request

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

Example Response

{
    "46.77,-100.75":{
        "2012-07-06":{
            "abs_scaled_paw_soil_moisture_0to10cm":{
                "unit":"n/a",
                "value":0.42
            },
            "abs_scaled_paw_soil_moisture_0to200cm":{
                "unit":"n/a",
                "value":0.4
            },
            "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
            }
        }
    }
}

Daily Soil Moisture Flux - v1.0

The Daily Soil Moisture Flux endpoint provides up to 366 days of soil moisture flux data, indicating the amount of water expected to pass through multiple soil depths, via either downwards percolation or upwards as a result of capillary action.

Data are valid from midnight to 11:59 p.m. in the timezone of the location queried, and available globally from January 1, 1980 through up to 9 days into the future.

URL Description

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

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 returned in the form of a Unix timestamp.

end

timestamp

yes

End time of the data returned in the form of a 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>)]."

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.

net_flux

flag

no

Include negative (upward) daily moisture fluxes in calculation of flux accumulations. Default behavior is to ignore negative daily values in these calculations.

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

Response Object (JSON)

Field Description

soil_moisture_accflux_100cm

Total amount of water passing through a depth of 100 cm in the soil column, accumulated from the beginning of the response.2

soil_moisture_accflux_10cm

Total amount of water passing through a depth of 10 cm in the soil column, accumulated from the beginning of the response.2

soil_moisture_accflux_200cm

Total amount of water passing through a depth of 200 cm in the soil column, accumulated from the beginning of the response.2

soil_moisture_accflux_20cm

Total amount of water passing through a depth of 20 cm in the soil column, accumulated from the beginning of the response.2

soil_moisture_accflux_2cm

Total amount of water passing through a depth of 2 cm in the soil column, accumulated from the beginning of the response.2

soil_moisture_accflux_40cm

Total amount of water passing through a depth of 40 cm in the soil column, accumulated from the beginning of the response.2

soil_moisture_accflux_5cm

Total amount of water passing through a depth of 5 cm in the soil column, accumulated from the beginning of the response.2

soil_moisture_accflux_70cm

Total amount of water passing through a depth of 70 cm in the soil column, accumulated from the beginning of the response.2

soil_moisture_accflux_sfc

Total amount of water infiltration at the soil surface, accumulated from the beginning of the response.2

soil_moisture_flux_100cm

Amount of water passing through a depth of 100 cm in the soil column.2

soil_moisture_flux_10cm

Amount of water passing through a depth of 10 cm in the soil column.2

soil_moisture_flux_200cm

Amount of water passing through a depth of 200 cm in the soil column.2

soil_moisture_flux_20cm

Amount of water passing through a depth of 20 cm in the soil column.2

soil_moisture_flux_2cm

Amount of water passing through a depth of 2 cm in the soil column.2

soil_moisture_flux_40cm

Amount of water passing through a depth of 40 cm in the soil column.2

soil_moisture_flux_5cm

Amount of water passing through a depth of 5 cm in the soil column.2

soil_moisture_flux_70cm

Amount of water passing through a depth of 70 cm in the soil column.2

soil_moisture_flux_sfc

Amount of water infiltration at the soil surface.2

2 Note that water-soluble nutrients within the soil may migrate vertically through the soil profile over time in proportion to the amount of moisture transport. Positive values indicate downward percolation; negative values indicate upward flow due to capillary action, occurring when lower soil layers are wetter than layers above them.

Example Request

https://ag.us.clearapis.com/v1.0/daily/soil/moistureflux?
app_id=123&app_key=321&location=43,-103&start=1388534400&end=1388707200

Example Response

{
    "43,-103":{
        "2014-01-01":{
            "soil_moisture_accflux_100cm":{
                "unit":"in",
                "value":0.006
            },
            "soil_moisture_accflux_10cm":{
                "unit":"in",
                "value":0.0
            },
            "soil_moisture_accflux_200cm":{
                "unit":"in",
                "value":0.0
            },
            "soil_moisture_accflux_20cm":{
                "unit":"in",
                "value":0.002
            },
            "soil_moisture_accflux_2cm":{
                "unit":"in",
                "value":0.0
            },
            "soil_moisture_accflux_40cm":{
                "unit":"in",
                "value":0.004
            },
            "soil_moisture_accflux_5cm":{
                "unit":"in",
                "value":0.0
            },
            "soil_moisture_accflux_70cm":{
                "unit":"in",
                "value":0.005
            },
            "soil_moisture_accflux_sfc":{
                "unit":"in",
                "value":0.0
            },
            "soil_moisture_flux_100cm":{
                "unit":"in",
                "value":0.006
            },
            "soil_moisture_flux_10cm":{
                "unit":"in",
                "value":-0.005
            },
            "soil_moisture_flux_200cm":{
                "unit":"in",
                "value":0.0
            },
            "soil_moisture_flux_20cm":{
                "unit":"in",
                "value":0.002
            },
            "soil_moisture_flux_2cm":{
                "unit":"in",
                "value":-0.014
            },
            "soil_moisture_flux_40cm":{
                "unit":"in",
                "value":0.004
            },
            "soil_moisture_flux_5cm":{
                "unit":"in",
                "value":-0.012
            },
            "soil_moisture_flux_70cm":{
                "unit":"in",
                "value":0.005
            },
            "soil_moisture_flux_sfc":{
                "unit":"in",
                "value":0.0
            }
        },...
    }
}

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

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

Changelog

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

5/13/19

Added the new 'paw' soil moisture parameters to the hourly and daily soil endpoints.

4/1/19

Text updates to introductory section.