ClearAg

ClearAg Indices

The ClearAg Indices form a suite of APIs that leverage big data and robust weather, soil, and agronomic modeling to provide a simple yet powerful analysis of environmental conditions impacting things such as crop yield, disease risk, and crop chemical applications.

ClearAg Indices

last updated 10/29/19

Welcome to the ClearAg Indices API guide. The ClearAg Indices form a suite of APIs that leverage big data and robust weather, soil, and agronomic modeling to provide a simple yet powerful analysis of environmental conditions impacting things such as crop yield, disease risk, and crop chemical applications. All of the Index APIs are documented below.

Most of the Index API endpoints require Account API integration. To use such endpoints, clients must first contact an Iteris account representative to set up an account, and then set up a user and field with the Account API, and a growth with the applicable Growth Creation endpoint as necessary.

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.

Emergence Risk - v1.0

The Emergence Risk index is a 0-100 rating of environmental conditions impacting emergence of a user-specified growth, where 0 represents a very low risk of challenging conditions and 100 represents a very high risk. Risks of imbibitional chilling, cold soil temperatures, large swings in soil temperatures, seedling disease, and crusting are independently assessed in order to generate an overall score.

URL Description

https://ag.us.clearapis.com/v1.0/indices/emergence_risk/{crop}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}

Request Parameters

Parameter Type Required Description

crop

string

yes

Crop type for which to generate results. Supported values: "corn".

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 your Iteris account representative.

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.

growth_id

string

yes

Growth ID provided by the Growth Creation endpoint. The growth must be consistent with the chosen crop type. The plant_date growth property must be defined in order for the algorithm to identify conditions occurring between planting and the simulated emergence date.

Response Object (JSON)

Field Description

auxiliary_info

Container for supporting information or data.

auxiliary_info/
emergence_date

Date that the crop began to emerge from the soil as estimated by the simulation.

auxiliary_info/
plant_date

User-provided date that the crop was planted.

index

Overall risk to emergence on a scale of 0 to 100, with 0 representing a very low risk of challenging conditions and 100 representing a very high risk.

subindex

Container for subindices.

subindex/
crusting

Crusting subindex. This represents the risk of crusting at the soil surface due to rainfall events between planting and emergence.

subindex/
imbibitional_chilling

Imbibitional chilling subindex. This represents the risk associated with a seed imbibing cold water.

subindex/
seedling_disease

Seedling disease subindex. This represents the risk associated with the length of time between planting and emergence, with longer time to emergence resulting in a higher risk of seedling disease.

subindex/
soil_temperature

Soil temperature subindex. This represents the risk that soil temperatures are too cold for optimal emergence.

subindex/
temperature_swing

Temperature swing subindex. This represents the risk associated with dramatic swings in soil temperature during the period between planting and emergence.

errors

Container for any errors encountered.

Example Request

https://ag.us.clearapis.com/v1.0/indices/emergence_risk/corn?app_id=123&app_key=321
&account_id=abc&user_id=xyz-123&growth_id=abc-def

Example Response

{
    "data":{
        "47,-97":{
            "auxiliary_info":{
                "emergence_date":"2019-05-22",
                "plant_date":"2019-05-01"
            },
            "index":95.0
            "subindex":{
                "crusting":0.0,
                "imbibitional_chilling":81.0,
                "seedling_disease":36.0,
                "soil_temperature":46.0,
                "temperature_swing":25.0
            }
        }
    },
    "errors":{}
}

Environmental Conditions - v1.0

The Environmental Conditions index indicates the extent to which environmental conditions deviate from historical norms for a selected time period on a scale of 0 to 100, with 50 indicating conditions are about average, 100 indicating conditions are significantly above average, and 0 indicating conditions are significantly below average. This index can be calculated for things such as air temperature, dew point, wind speed, soil temperature, and precipitation. (See the complete list here.)

URL Description

https://ag.us.clearapis.com/v1.0/indices/environmental_conditions?
app_id={string}&app_key={string}&location={lat, lon coordinates}
&start_date={string}&end_date={string}&reference_start_year={string}
&reference_end_year={string}&variable={string}&unitcode={string}&verbose

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

Lat-lon coordinates in decimal degrees. Only one location may be provided.

start_date

string

yes

Start of date range to compare against a climatological average. Format is: YYYY-MM-DD. Earliest allowed is 1980-01-01; latest allowed is <current date> - 1 day. Date range cannot exceed 100 days.

end_date

string

yes

End of date range to compare against a climatological average. Format is: YYYY-MM-DD. Earliest allowed is 1980-01-01; latest allowed is <current date> - 1 day. Date range cannot exceed 100 days.

reference_start_year

string

yes

Start of year range for calculating a climatological average. Range must be at least 5 years in length but cannot exceed 30 years. May not predate 1980. Actual date range used for each year begins with the month and day as defined by the start date argument, and may not exceed <current date> - 1 day.

reference_end_year

string

yes

End of year range for calculating a climatological average. Range must be at least 5 years in length but cannot exceed 30 years. May not predate 1980. Actual date range used for each year begins with the month and day as defined by the start date argument, and may not exceed <current date> - 1 day.

variable

string

yes

The environmental variable for which to calculate results. Supported values are listed in the Variable Enumerations section of the Appendix.

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." When "precise" is not set, the output will be rounded to an appropriate level of precision for the parameter. See the listing of US and SI units for each variable in the Variable Enumerations section.

verbose

flag

no

Display detailed response, including yearly values.

Response Object (JSON)

Field Description

auxiliary_info

Container for supporting information or data.

auxiliary_info/
environmental_data

Container for data from all years in reference and target periods. Only appears if verbose option is set.

environmental_data/
accumulation

Period sum of daily values. Filled with data for variables "13" (daily total precipitation), "29" (daily total reference evapotranspiration), and "40" through "48" (daily total soil moisture flux).

environmental_data/
average

Period average of daily values. Filled with data for all variables except "13", "29", and "40" through "48".

environmental_data/
end_date

Period end date.

environmental_data/
maximum

Period maximum of daily values.

environmental_data/
minimum

Period minimum of daily values.

environmental_data/
start_date

Period start date.

auxiliary_info/
reference_period

Container for reference period data.

reference_period/
average

Reference period average. This is the average of the sums or averages from all of the reference period years in the "environmental_data" section.

reference_period/
stddev

Reference period standard deviation. This is the standard deviation of the sums or averages from all of the reference period years in the "environmental_data" section.

auxiliary_info/
target_period

Container for target period data.

target_period/
accumulation

Target period sum of daily values. Filled with data for variables "13" (daily total precipitation), "29" (daily total reference evapotranspiration), and "40" through "48" (daily total soil moisture flux).

target_period/
average

Target period average of daily values. Filled with data for all variables except "13", "29", and "40" through "48".

target_period/
maximum

Target period maximum of daily values.

target_period/
minimum

Target period minimum of daily values.

target_period/
z-score

Z-score of target period average or accumulation. Indicates the number of standard deviations away that the target period value is from the reference period average.

index

Indicates how similar the target period average or accumulation is to the reference period average, with 50 indicating that the target period value is about the same, 100 indicating it is significantly greater, and 0 indicating it is significantly less.

errors

Container for any errors encountered.

Example Request

https://ag.us.clearapis.com/v1.0/indices/environmental_conditions?
app_id=123&app_key=321&location=47,-97&start_date=2019-05-01&end_date=2019-05-31
&reference_start_year=1980&reference_end_year=2009&verbose&variable=0

Example Response

{
    "data":{
        "47,-97":{
            "auxiliary_info":{
                "environmental_data":{
                    "1980":{
                        "accumulation":"n/a",
                        "average":63.0,
                        "end_date":"1980-05-31",
                        "maximum":77.0,
                        "minimum":38.0,
                        "start_date":"1980-05-01"
                    }, ...
                },
                "reference_period":{
                    "average":58.0,
                    "stddev":3.2
                },
                "target_period":{
                    "accumulation":"n/a",
                    "average":53.0,
                    "maximum":75.0,
                    "minimum":40.0,
                    "z-score":-1.41
                }
            },
            "index":22.0
        }
    },
    "errors":{}
}

Field Accessibility - v1.0

The Field Accessibility endpoint leverages Iteris' weather and soil data to simulate field conditions for the next hour and quantify field accessibility on a 0-100 scale, with 0 indicating very poor conditions and the field likely inaccessible to equipment, and 100 indicating very good conditions.

URL Description

https://ag.us.clearapis.com/v1.0/indices/field_accessibility?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&field_id={string}&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

A unique account ID provided by your Iteris account representative.

user_id

string

yes

User ID provided by the Account API.

field_id

string

yes

Field ID provided by the Account API.

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." When "precise" is not set, the output will be rounded to an appropriate level of precision for the parameter.

Response Object (JSON)

Field Description

auxiliary_info

Container for supporting information or data.

auxiliary_info/
environmental_data

Container for environmental conditions impacting field accessibility.

environmental_data/
pet_last_24hr

Total reference evapotranspiration of the last 24 hours, calculated using the FAO-56 grass formulation. Reference evapotranspiration is the amount of water that would transpire and evaporate from a hypothetical reference crop, assuming ample water is available. US unit: inches. SI unit: millimeters.

environmental_data/
pet_last_48hr

Total reference evapotranspiration of the last 48 hours. US unit: inches. SI unit: millimeters.

environmental_data/
precip_acc_last_24hr

Total liquid-equivalent precipitation of the last 24 hours. US unit: inches. SI unit: millimeters.

environmental_data/
precip_acc_last_48hr

Total liquid-equivalent precipitation of the last 48 hours. US unit: inches. SI unit: millimeters.

environmental_data/
soil_temp_0to2cm

Temperature of the soil between the surface and the 2-cm depth. US unit: degrees Fahrenheit. SI unit: degrees Celsius.

environmental_data/
soil_temp_2to5cm

Temperature of the soil between the 2- and 5-cm depths. US unit: degrees Fahrenheit. SI unit: degrees Celsius.

environmental_data/
soil_temp_5to10cm

Temperature of the soil between the 5- and 10-cm depths. US unit: degrees Fahrenheit. SI unit: degrees Celsius.

environmental_data/
soil_temp_10to20cm

Temperature of the soil between the 10- and 20-cm depths. US unit: degrees Fahrenheit. SI unit: degrees Celsius.

environmental_data/
soil_temp_20to40cm

Temperature of the soil between the 20- and 40-cm depths. US unit: degrees Fahrenheit. SI unit: degrees Celsius.

environmental_data/
soil_temp_40to70cm

Temperature of the soil between the 40- and 70-cm depths. US unit: degrees Fahrenheit. SI unit: degrees Celsius.

environmental_data/
soil_temp_70to100cm

Temperature of the soil between the 70- and 100-cm depths. US unit: degrees Fahrenheit. SI unit: degrees Celsius.

environmental_data/
soil_temp_100to200cm

Temperature of the soil between the 100- and 200-cm depths. US unit: degrees Fahrenheit. SI unit: degrees Celsius.

index

Field accessibility on a scale of 0 to 100, with 0 representing poor field conditions and 100 representing good conditions.

errors

Container for any errors encountered.

Example Request

https://ag.us.clearapis.com/v1.0/indices/field_accessibility?app_id=123&app_key=321
&account_id=abc&user_id=xyz-123&field_id=aaa-111

Example Response

{
    "data":{
        "47,-97":{
            "auxiliary_info":{
                "environmental_data":{
                    "1571850000":{
                        "pet_last_24hr":0.04,
                        "pet_last_48hr":0.07,
                        "precip_acc_last_24hr":0.0,
                        "precip_acc_last_48hr":0.04,
                        "soil_temp_0to2cm":39.0,
                        "soil_temp_2to5cm":38.0,
                        "soil_temp_5to10cm":38.0,
                        "soil_temp_10to20cm":40.0,
                        "soil_temp_20to40cm":44.0,
                        "soil_temp_40to70cm":48.0,
                        "soil_temp_70to100cm":50.0,
                        "soil_temp_100to200cm":54.0
                    }
                }
            },
            "index":44.0
        }
    },
    "errors":{}
}

Fusarium Head Blight Risk - v1.0

The Fusarium Head Blight Risk index quantifies the risk of fusarium head blight (FHB) in wheat based on environmental conditions around the time of flowering. Resistance of the wheat variety to FHB may also be specified and used in the calculation. The risk index is given on a 0-100 scale, with 0 indicating minimal risk of FHB and 100 indicating high risk.

URL Description

https://ag.us.clearapis.com/v1.0/indices/fhb_risk/{crop}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&resistance={string}&unitcode={string}

Request Parameters

Parameter Type Required Description

crop

string

yes

Crop type for which to generate results. Supported values: "springwheat", "winter_wheat".

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 your Iteris account representative.

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.

growth_id

string

yes

Growth ID provided by the Growth Creation endpoint. The growth must be consistent with the chosen crop type.

resistance

string

no

Resistance to FHB. Valid values include "0" (very susceptible), "1" (susceptible), "2" (moderately susceptible), and "3" (moderately resistant). Default is "0".

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." When "precise" is not set, the output will be rounded to an appropriate level of precision for the parameter.

Response Object (JSON)

Field Description

auxiliary_info

Container for supporting information or data.

auxiliary_info/
emergence_date

Date that the crop began to emerge from the soil.

auxiliary_info/
environmental_data

Container for a timeseries of weather data used to compute the index value.

environmental_data/
relative_humidity_avg

Daily average relative humidity, in percent.

auxiliary_info/
flowering_date

Date that the flowering stage is reached. (This corresponds to stage "117" for spring wheat and "10" for winter wheat.)

auxiliary_info/
plant_date

Date that the crop was planted.

index

Overall risk of fusarium head blight on a scale of 0 to 100, with 0 representing a very low risk and 100 representing a very high risk.

errors

Container for any errors encountered.

Example Request

https://ag.us.clearapis.com/v1.0/indices/fhb_risk/springwheat?app_id=123&app_key=321
&account_id=abc&user_id=xyz-123&growth_id=abc-def

Example Response

{
    "data":{
        "47,-97":{
            "auxiliary_info":{
                "emergence_date":"2019-05-18",
                "environmental_data":{
                    "2019-06-17":{
                        "relative_humidity_avg":77.0
                    }, ...
                },
                "flowering_date":"2019-07-05",
                "plant_date":"2019-05-01"
            },
            "index":49.0
        }
    },
    "errors":{}
}

Grain-fill Stress - v1.0

The Grain-fill Stress index is a 0-100 rating of stress on a crop during grain-fill, where 0 indicates minimal stress and 100 indicates very high stress. Damaging drought, heat, and frost stresses are independently assessed in order to generate an overall score.

The time period when grain-fill is expected to occur varies by crop. For corn, this is typically the period between the "R2" and "R6" stages.

URL Description

https://ag.us.clearapis.com/v1.0/indices/grainfill_stress/{crop}?
app_id={string}&app_key={string}&account_id={string}&user_id={string}
&growth_id={string}&unitcode={string}

Request Parameters

Parameter Type Required Description

crop

string

yes

Crop type for which to generate results. Supported values: "corn".

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 your Iteris account representative.

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.

growth_id

string

yes

Growth ID provided by the Growth Creation endpoint. The growth must be consistent with the chosen crop type.

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." When "precise" is not set, the output will be rounded to an appropriate level of precision for the parameter.

Response Object (JSON)

Field Description

auxiliary_info

Container for supporting information or data.

auxiliary_info/
grainfill_period

Container for environmental conditions during grain-fill.

grainfill_period/
abs_scaled_paw_soil_moisture_avg

Grain-fill period average of daily average soil moisture in the root zone, expressed as a scaled value between wilting point (0.0) and field capacity (1.0).

grainfill_period/
abs_scaled_paw_soil_moisture_max

Grain-fill period maximum of daily average soil moisture in the root zone, expressed as a scaled value between wilting point (0.0) and field capacity (1.0).

grainfill_period/
abs_scaled_paw_soil_moisture_min

Grain-fill period minimum of daily average soil moisture in the root zone, expressed as a scaled value between wilting point (0.0) and field capacity (1.0).

grainfill_period/
air_temp_max

Grain-fill period maximum of daily maximum air temperature. US unit: degrees Fahrenheit. SI unit: degrees Celsius.

grainfill_period/
air_temp_max_avg

Grain-fill period average of daily maximum air temperature. US unit: degrees Fahrenheit. SI unit: degrees Celsius.

grainfill_period/
air_temp_min

Grain-fill period minimum of daily minimum air temperature. US unit: degrees Fahrenheit. SI unit: degrees Celsius.

grainfill_period/
air_temp_min_avg

Grain-fill period average of daily minimum air temperature. US unit: degrees Fahrenheit. SI unit: degrees Celsius.

grainfill_period/
end_date

Grain-fill period end date.

grainfill_period/
pet_period_avg

Grain-fill period average of daily total reference evapotranspiration, calculated using the FAO-56 grass formulation. Reference evapotranspiration is the amount of water that would transpire and evaporate from a hypothetical reference crop, assuming ample water is available. US unit: inches. SI unit: millimeters.

grainfill_period/
start_date

Grain-fill period start date.

index

Overall amount of stress on the crop during grain-fill on a scale of 0 to 100, with 0 representing minimally stressful conditions and 100 representing highly stressful conditions.

subindex

Container for subindices.

subindex/
drought_stress

Drought stress subindex. This represents the amount of stress on the crop owing to dry conditions.

subindex/
frost_stress

Frost stress subindex. This represents the amount of stress on the crop owing to cold conditions.

subindex/
heat_stress

Heat stress subindex. This represents the amount of stress on the crop owing to hot conditions.

errors

Container for any errors encountered.

Example Request

https://ag.us.clearapis.com/v1.0/indices/grainfill_stress/corn?
app_id=123&app_key=321&account_id=abc&user_id=xyz-123&growth_id=abc-def

Example Response

{
    "data":{
        "47,-97":{
            "auxiliary_info":{
                "grainfill_period":{
                    "abs_scaled_paw_soil_moisture_avg":0.83,
                    "abs_scaled_paw_soil_moisture_max":1.0,
                    "abs_scaled_paw_soil_moisture_min":0.68,
                    "air_temp_max":88.0,
                    "air_temp_max_avg":73.0,
                    "air_temp_min":44.0,
                    "air_temp_min_avg":55.0,
                    "end_date":"2019-09-22",
                    "pet_period_avg":0.11,
                    "start_date":"2019-08-05"
                 }
            },
            "index":0.0,
            "subindex":{
                "drought_stress":0.0,
                "frost_stress":0.0,
                "heat_stress":0.0
            }
        }
    },
    "errors":{}
}

Hourly Desiccant Application Suitability - v1.0

The Hourly Desiccant Application Suitability endpoint provides an hourly 0-100 rating of conditions impacting desiccant application, where 0 indicates very unsuitable conditions, and 100 indicates ideal conditions. Weather conditions during and after a potential application, and suitability with respect to growth stage are independently assessed in order to generate an overall score.

URL Description

https://ag.us.clearapis.com/v1.0/indices/desiccant_application_suitability/
hourly/{crop}?app_id={string}&app_key={string}&account_id={string}
&user_id={string}&growth_id={string}&start_time={timestamp}
&end_time={timestamp}&desiccant={string}

Request Parameters

Parameter Type Required Description

crop

string

yes

Crop type for which to generate results. Supported values: "soybean".

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 your Iteris account representative.

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.

growth_id

string

yes

Growth ID provided by the Growth Creation endpoint. The growth must be consistent with the chosen crop type.

start_time

timestamp

yes

Start of desiccant application time window in the form of a Unix timestamp. May not precede January 1 00:00 UTC of the previous year and may not be more than 72 hours into the future. Time window may not exceed 240 hours.

end_time

timestamp

yes

End of desiccant application time window in the form of a Unix timestamp. May not precede January 1 00:00 UTC of the previous year and may not be more than 72 hours into the future. Time window may not exceed 240 hours.

desiccant

string

no

Brand of desiccant to apply. Currently, only "gramoxone" is supported.

Response Object (JSON)

Field Description

index

Overall suitability of conditions for desiccant application on a scale of 0 to 100, with 0 representing very unsuitable conditions and 100 representing ideal conditions.

subindex

Container for subindices.

subindex/
current_weather_suitability

Current weather suitability subindex. This represents suitability for desiccant application based on weather conditions at the time of application.

subindex/
future_weather_suitability

Future weather suitability subindex. This represents suitability for desiccant application based on weather conditions for up to 15 days following application.

subindex/
growth_stage_suitability

Growth stage suitability subindex. This represents suitability for desiccant application based on growth stage. For soybean, the ideal time to apply a desiccant is halfway between the "R6" and "R7" stages.

errors

Container for any errors encountered.

Example Request

https://ag.us.clearapis.com/v1.0/indices/desiccant_application_suitability/
hourly/soybean?app_id=123&app_key=321&account_id=abc&user_id=xyz-123
&growth_id=abc-def&start_time=1569628800&end_time=1569628800

Example Response

{
    "data":{
        "47,-97":{
            "1569628800":{
                "index":1.0,
                "subindex":{
                    "current_weather_suitability":50.0,
                    "future_weather_suitability":2.0,
                    "growth_stage_suitability":100.0
                }
            }, ...
        }
    },
    "errors":{}
}

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>

Variable Enumerations

The following is the list of variables supported in the Environmental Conditions endpoint.

Variable Enum Description US Unit SI Unit

0

Daily average 2m air temperature

°F

°C

1

Daily maximum 2m air temperature

°F

°C

2

Daily minimum 2m air temperature

°F

°C

3

Daily average 0-2cm soil temperature

°F

°C

4

Daily average 2-5cm soil temperature

°F

°C

5

Daily average 5-10cm soil temperature

°F

°C

10

Daily average 10m wind speed

mph

km/hr

11

Daily maximum 10m wind speed

mph

km/hr

12

Daily average shortwave radiation

W/m^2

W/m^2

13

Daily total liquid-equivalent precipitation

inches

mm

14

Daily total hours of canopy wetness

hours

hours

15

Daily average 5cm air temperature

°F

°C

16

Daily maximum 5cm air temperature

°F

°C

17

Daily minimum 5cm air temperature

°F

°C

18

Daily average 2m dew point temperature

°F

°C

19

Daily maximum 2m dew point temperature

°F

°C

20

Daily minimum 2m dew point temperature

°F

°C

21

Daily average 2m relative humidity

%

%

22

Daily maximum 2m relative humidity

%

%

23

Daily minimum 2m relative humidity

%

%

24

Daily minimum 10m wind speed

mph

km/hr

25

Daily maximum shortwave radiation

W/m^2

W/m^2

26

Daily average longwave radiation

W/m^2

W/m^2

27

Daily maximum longwave radiation

W/m^2

W/m^2

28

Daily minimum longwave radiation

W/m^2

W/m^2

29

Daily total reference evapotranspiration

inches

mm

30

Daily average 10-20cm soil temperature

°F

°C

31

Daily average 20-40cm soil temperature

°F

°C

32

Daily average 40-70cm soil temperature

°F

°C

33

Daily average 70-100cm soil temperature

°F

°C

34

Daily average 100-200cm soil temperature

°F

°C

40

Daily total surface soil moisture flux

inches

mm

41

Daily total 2cm soil moisture flux

inches

mm

42

Daily total 5cm soil moisture flux

inches

mm

43

Daily total 10cm soil moisture flux

inches

mm

44

Daily total 20cm soil moisture flux

inches

mm

45

Daily total 40cm soil moisture flux

inches

mm

46

Daily total 70cm soil moisture flux

inches

mm

47

Daily total 100cm soil moisture flux

inches

mm

48

Daily total 200cm soil moisture flux

inches

mm

Changelog

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

10/29/19

Created initial version of the guide.