Historical and Climatological Weather

last updated 11/7/18

Historical information consists of an archive of past current conditions as a series of individual times or dates. Climatological data refers to long-term statistical values by combining multiple years of data for the same date, time, and location. This information is valuable for organizations that need to analyze or compare past environmental conditions to evaluate product performance, as well as product nutrient or chemical application strategies for optimum crop growth and health.

All of the following endpoints provide data for any location in the world. Hourly data are available for any time frame spanning the previous calendar year to the previous hour. Daily data are available from January 1, 1980 through the previous day, and the daily values represent midnight to midnight local time for the location’s timezone.

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.

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.

Daily Historical 5-Year Climatology - v1.0

The Daily Historical 5-Year Climatology endpoint provides daily weather climatology of the past five complete years. Data are valid from midnight to 11:59 p.m. in the time zone of the location queried.

URL Description

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_date

string

yes

String representing the start date of data to be returned, which must be formatted as MM-DD or YYYY-MM-DD. If a year is not specified, only dates valid for the current year will be returned. If an additional date resulting from a leap year is desired, specify a year in which a leap year occurs. If a date range spanning beyond a single contiguous year is desired, a year must be specified.

end_date

string

yes

String representing the end date of data to be returned, which must be formatted as MM-DD or YYYY-MM-DD. Year must be specified if start_date contains a year.

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 the unit code selected.

Field

Description

air_temp_avg

Average of daily average air temperature values.

air_temp_stddev

Standard deviation of daily average air temperature values.

dew_point_avg

Average of daily average dew point temperature values. Dew point temperature is defined as the temperature to which the air must be cooled for saturation and condensation to occur.

dew_point_stddev

Standard deviation of daily average dew point temperature values.

long_wave_radiation_avg

Average of daily average downwelling longwave radiation flux values. Longwave radiation is the energy emitted from non-solar radiation sources.

long_wave_radiation_stddev

Standard deviation of daily average longwave radiation flux values.

air_temp_max_avg

Average of daily maximum air temperature values.

air_temp_max_stddev

Standard deviation of daily maximum air temperature values.

air_temp_min_avg

Average of daily minimum air temperature values.

air_temp_min_stddev

Standard deviation of daily minimum air temperature values.

pet_avg

Average of daily reference evapotranspiration values. Reference evapotranspiration is the amount of water that would transpire and evaporate from a hypothetical reference crop, assuming that ample water is available. In this case, short green grass is used as the reference crop.

precip_acc_avg

Average of daily accumulated liquid-equivalent precipitation values.

short_wave_radiation_avg

Average of daily average downwelling shortwave radiation flux values. Shortwave radiation is the high-energy solar radiation that reaches Earth’s surface.

URL Description

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_date

string

yes

String representing the start date of data to be returned, which must be formatted as MM-DD or YYYY-MM-DD. If a year is not specified, only dates valid for the current year will be returned. If an additional date resulting from a leap year is desired, specify a year in which a leap year occurs. If a date range spanning beyond a single contiguous year is desired, a year must be specified.

end_date

string

yes

String representing the end date of data to be returned, which must be formatted as MM-DD or YYYY-MM-DD. Year must be specified if start_date contains a year.

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 the unit code selected.

Field

Description

air_temp_avg

Average of daily average air temperature values.

air_temp_stddev

Standard deviation of daily average air temperature values.

dew_point_avg

Average of daily average dew point temperature values. Dew point temperature is defined as the temperature to which the air must be cooled for saturation and condensation to occur.

dew_point_stddev

Standard deviation of daily average dew point temperature values.

long_wave_radiation_avg

Average of daily average downwelling longwave radiation flux values. Longwave radiation is the energy emitted from non-solar radiation sources.

long_wave_radiation_stddev

Standard deviation of daily average longwave radiation flux values.

air_temp_max_avg

Average of daily maximum air temperature values.

air_temp_max_stddev

Standard deviation of daily maximum air temperature values.

air_temp_min_avg

Average of daily minimum air temperature values.

air_temp_min_stddev

Standard deviation of daily minimum air temperature values.

pet_avg

Average of daily reference evapotranspiration values. Reference evapotranspiration is the amount of water that would transpire and evaporate from a hypothetical reference crop, assuming that ample water is available. In this case, short green grass is used as the reference crop.

precip_acc_avg

Average of daily accumulated liquid-equivalent precipitation values.

short_wave_radiation_avg

Average of daily average downwelling shortwave radiation flux values. Shortwave radiation is the high-energy solar radiation that reaches Earth’s surface.

URL Description

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_date

string

yes

String representing the start date of data to be returned, which must be formatted as MM-DD or YYYY-MM-DD. If a year is not specified, only dates valid for the current year will be returned. If an additional date resulting from a leap year is desired, specify a year in which a leap year occurs. If a date range spanning beyond a single contiguous year is desired, a year must be specified.

end_date

string

yes

String representing the end date of data to be returned, which must be formatted as MM-DD or YYYY-MM-DD. Year must be specified if start_date contains a year.

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 the unit code selected.

Field

Description

air_temp_avg

Average of daily average air temperature values.

air_temp_stddev

Standard deviation of daily average air temperature values.

dew_point_avg

Average of daily average dew point temperature values. Dew point temperature is defined as the temperature to which the air must be cooled for saturation and condensation to occur.

dew_point_stddev

Standard deviation of daily average dew point temperature values.

long_wave_radiation_avg

Average of daily average downwelling longwave radiation flux values. Longwave radiation is the energy emitted from non-solar radiation sources.

long_wave_radiation_stddev

Standard deviation of daily average longwave radiation flux values.

air_temp_max_avg

Average of daily maximum air temperature values.

air_temp_max_stddev

Standard deviation of daily maximum air temperature values.

air_temp_min_avg

Average of daily minimum air temperature values.

air_temp_min_stddev

Standard deviation of daily minimum air temperature values.

pet_avg

Average of daily reference evapotranspiration values. Reference evapotranspiration is the amount of water that would transpire and evaporate from a hypothetical reference crop, assuming that ample water is available. In this case, short green grass is used as the reference crop.

precip_acc_avg

Average of daily accumulated liquid-equivalent precipitation values.

short_wave_radiation_avg

Average of daily average downwelling shortwave radiation flux values. Shortwave radiation is the high-energy solar radiation that reaches Earth’s surface.

Request Parameters

Start time of the data returned. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

end

timestamp

yes

End time of the data returned. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

location

lat, lon coordinates

yes

User-provided latitude and longitude coordinates in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field. Users are allowed a maximum of five 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.

lang

string

no

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

24-hr accumulated reference evapotranspiration data. Reference evapotranspiration is the amount of water that would transpire and evaporate from a hypothetical reference crop, assuming that ample water is available. In this case, short green grass is used as the reference crop.

precip_acc_period

Best estimate of liquid-equivalent precipitation. Matches the precip_acc_period_adjusted value if available, or the precip_acc_period_raw value if the adjusted value is not available.

precip_acc_period_adjusted

Liquid-equivalent precipitation accumulation, fundamentally derived from the raw precipitation product, but then adjusted to more closely match available ground truth observations. Due to the delays in receiving these ground truth data, accumulation adjustment typically lags real-time by a day or more.

precip_acc_period_raw

Liquid-equivalent precipitation accumulation, estimated from multiple sources of data that may include any or all of the following: weather radar, satellite, computer model, and surface observation data.

relative_humidity_avg

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

Number of hours that the amount of downwelling shortwave radiation flux exceeds 120 W/m^2, which is dictated by the time of day and local weather conditions. Note that hours are not necessarily consecutive.

visibility_avg

Average visibility data. Visibility is a measure of the lateral distance one can see before one’s line of sight is obstructed due to weather conditions.

Daily Historical Ag Weather - v1.0

The Daily Historical Ag Weather endpoint provides up to 366 days of historical weather data geared toward agricultural applications. Data are valid from midnight to 11:59 p.m. in the time zone of the location queried.

Request Parameters

Start time of the data returned. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

end

timestamp

yes

End time of the data returned. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

location

lat, lon coordinates

yes

User-provided latitude and longitude coordinates in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field. Users are allowed a maximum of five 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.

lang

string

no

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

24-hr accumulated reference evapotranspiration data. Reference evapotranspiration is the amount of water that would transpire and evaporate from a hypothetical reference crop, assuming that ample water is available. In this case, short green grass is used as the reference crop.

precip_acc_period

Best estimate of liquid-equivalent precipitation. Matches the precip_acc_period_adjusted value if available, or the precip_acc_period_raw value if the adjusted value is not available.

precip_acc_period_adjusted

Amount of liquid-equivalent precipitation, fundamentally derived from the raw precipitation product, but then adjusted to more closely match available ground truth observations. Due to the delays in receiving these ground truth data, accumulation adjustment typically lags real-time by a day or more.

precip_acc_period_raw

Amount of liquid-equivalent precipitation, estimated from multiple sources of data that may include any or all of the following: weather radar, satellite, computer model, and surface observation data.

precip_duration

Number of hours that the best estimate of liquid-equivalent precipitation exceeds 0.1 mm. Note that hours are not necessarily consecutive.

relative_humidity_avg

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

Number of hours that the amount of downwelling shortwave radiation flux exceeds 120 W/m^2, which is dictated by the time of day and local weather conditions. Note that hours are not necessarily consecutive.

visibility_avg

Average visibility data. Visibility is a measure of the lateral distance one can see before one’s line of sight is obstructed due to weather conditions.

Daily Historical Air Temperature - v1.2

The Daily Historical Air Temperature service provides up to 366 days of historical air temperature data for a specified location. Data are valid from midnight to 11:59 p.m. in the time zone of the location queried.

Request Parameters

Start time of the data being returned. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

end

timestamp

yes

End time of the data being returned. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

location

lat, lon coordinates

yes

User-provided latitude and longitude coordinates in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field. Users are allowed a maximum of five 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.

Example Response

Daily Historical Precipitation - v1.1

The Daily Historical Precipitation endpoint provides up to 366 days of daily historical precipitation totals for a specified location. Data are valid from midnight to 11:59 p.m. in the time zone of the location queried.

Request Parameters

Start time of the data returned. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

end

timestamp

yes

End time of the data returned. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

location

lat, lon coordinates

yes

User-provided latitude and longitude coordinates in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field. Users are allowed a maximum of five 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.

URL Description

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_date

string

yes

String representing the start date of data to be returned, which must be formatted as MM-DD or YYYY-MM-DD. If a year is not specified, only dates valid for the current year will be returned. If an additional date resulting from a leap year is desired, specify a year in which a leap year occurs. If a date range spanning beyond a single contiguous year is desired, a year must be specified.

end_date

string

yes

String representing the end date of data to be returned, which must be formatted as MM-DD or YYYY-MM-DD. Year must be specified if start_date contains a year.

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)

Field

Description

frost_probability_cumulative

Cumulative percent probability of frost. Calculated by stepping forward or backward in time from the day of the year having the climatologically warmest minimum daily air temperature and taking a ratio of the cumulative number of years a given date experienced a minimum temperature less than or equal to freezing, to the total number of years of the climatology (30).

Request Parameters

Start time of the data returned. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

end

timestamp

yes

End time of the data returned. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

location

lat, lon coordinates

yes

User-provided latitude and longitude coordinates in decimal degrees. Please verify that latitude/longitude coordinates are over soil representative of your field. Users are allowed a maximum of five 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.

lang

string

no

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

Precipitation descriptor data. Precipitation descriptor includes information about precipitation type, probability, and intensity when applicable. Please refer to the Textual Form of Numerical Outputs section of the Appendix for additional information on descriptor codes.

visibility_obstruction_descriptor

Visibility obstruction descriptor data. Visibility obstruction is the obscuration of one’s line of sight by some meteorological phenomenon. Please refer to the Textual Form of Numerical Outputs section of the Appendix for additional information on descriptor codes.

weather_descriptor

General weather descriptor data. Weather descriptor contains information about the prevailing weather conditions, which may include cloud cover, precipitation, visibility obstruction, or wind information. Please refer to the Textual Form of Numerical Outputs section of the Appendix for additional information on descriptor codes.

Best estimate of liquid-equivalent precipitation. Matches the precip_acc_period_adjusted value if available, or the precip_acc_period_raw value if the adjusted value is not available.

precip_acc_period_adjusted

Liquid-equivalent precipitation accumulation, fundamentally derived from the raw precipitation product, but then adjusted to more closely match available ground truth observations. Due to the delays in receiving these ground truth data, accumulation adjustment typically lags real-time by a day or more.

precip_acc_period_raw

Liquid-equivalent precipitation accumulation, estimated from multiple sources of data that may include any or all of the following: weather radar, satellite, computer model, and surface observation data.

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.

"U" wind speed at 10 meters above ground level. Note that "U" wind speed is the east-west-oriented component of the wind. If positive, the "U" wind component is blowing from the west; if negative, it is blowing from the east.

v_wind_speed

"V" wind speed at 10 meters above ground level. Note that "V" wind speed is the north-south-oriented component of the wind. If positive, the "V" wind component is blowing from the south; if negative, it is blowing from the north.

valid_time_end

Valid end time (Epoch time) for the hourly period. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

valid_time_start

Valid start time (Epoch time) for the hourly period. Please refer to the Epoch/Unix Timestamp section of the Appendix for Iteris' definition of Epoch/Unix timestamp.

visibility

Visibility data. Visibility is a measure of the lateral distance one can see before one’s line of sight is obstructed due to weather conditions.

wind_direction

Wind direction data, measured with respect to true north. A wind direction from true north corresponds to a value of 0 degrees, which increases to 360 degrees with corresponding clockwise shifts in wind direction.

wind_gust

Wind gust at 10 meters above ground level. The wind gust value is reported as "n/a" if the difference between the wind gust and wind speed is less than 5.0 mph. Note that this difference is actually determined in the raw units (m/s) before conversion to specified units.

Null or Empty Values

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

Epoch/Unix Timestamp

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

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

Regional-based Account Access

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

Textual Form of Numerical Outputs

This section outlines what numerical outputs represent in textual form. When reviewing data outputs, the last number in the numerical sequence ("code") correlates to the given text description ("qualifier").