Growth

Weather Data API

Iteris’ comprehensive weather data solutions combine the vast knowledge and experience of Iteris’ in-house meteorological team. ClearAg’s continuously-updating forecast system leverages the best available data for any location globally.

Sensor Integration

last updated 2/25/20

ClearAg virtual sensor data is generated in part by a robust observational network of physical sensors around the world. As part of our comprehensive environmental platform, the ClearAg API suite includes the capability to deliver physical sensor data for select sensor types.

The weather station API gives users the ability to retrieve physical weather station data for locations around the world. There are currently two options available for this API service:

  1. Public weather stations — Provides users access to all publicly available weather station sites around the world. This option is open to all subscribers of the Weather Station API and provides standard surface weather parameters at regular intervals, depending on the station observing frequency.

  2. Private weather stations — Provides users access to private weather station data for accounts with such permissions. Applications who have users that own weather stations may find this option quite useful if the weather station type is from a third party vendor with which ClearAg has integrated. Currently ClearAg is integrated with Davis and Pessl weather stations with more partner integration to come.

Please see the Appendix for supplemental API details.

Query for Available Weather Station Sites - v1.0

This endpoint is to be used to query for available weather station sites. Sites from publicly available providers will be returned. If your account has access to privately operated sites, information for those will be returned as well. Privately operated weather station support is currently provided for Davis and Pessl weather stations. Please note that not all stations report the same types of sensor readings, and frequency of readings will vary by device and provider.

Please note that API responses are currently only provided in English.

Iteris requires the use of HTTPS when working within the ClearAg APIs.

URL Description

https://ag.us.clearapis.com/v1.0/sensors/wx_station/meta?app_key={string}&app_id={string}&account_id={string}&location={string}&unitcode={string}&radius={float}&radius_unit={string}&float={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

no

A unique account ID provided by your Iteris account representative. Must be provided in order to retrieve information for privately shared devices for which you are authorized.

location

string

yes

Comma delimited latitude,longitude representing center point of selection circle.

unitcode

string

no

Either "us-std" or "si-std." Default of "us-std." Additional information is available in the Parameter Units section of the Appendix.

radius

float

no

Float value greater than zero. Maximum value of 100 mi or 160.934 km. Search radius from provided location. Default of 50 mi.

radius_unit

string

no

Either "mi" or "km." Default of "mi." Only valid if radius is also provided.

format

string

no

Either "json" or "geojson."

Response Object (JSON)

Field Description

latitude, longitude

Key and value pairs representing site location.

site_provider

Name of site owner/provider.

site_provider_id

ID of site as it is known by the provider.

site_name

Name or description as set by the provider or as set by Iteris by combining one or more available properties.

site_id

Unique ID (UUID) used by Iteris to identify the site. This ID should be used for subsequent queries to retrieve time series of device readings for a site.

elevation

Site’s height above mean sea level, as reported by the provider. Unit of measure is determined by selected unitcode. Additional information is available in the Parameter Units section of the Appendix.

other_info

Other information that may have been provided for a site. Keys and values within this section are not expected to be consistent between providers.

units

Will contain current unit of measure for numeric values that may be present in the response.

Example Request

https://ag.us.clearapis.com/v1.0/sensors/wx_station/meta?app_id=123&app_key=321&account_id=abc-123&location=47.94771241878954,-97.17523097991943&radius=90&radius_unit=mi&unitcode=us-std

Example Response

The following JSON response is provided as an example, the length and content of individual users’ JSON responses will vary based on user input.

{
	"data":[{
		"elevation":843.17,
		"latitude":-97.17611,
		"longitude":47.94925,
		"other_info":{
			"country":"US",
			"priority":"2",
			"state":"ND",
			"station":"GRAND FORKS",
			"type":"A"
		},
		"site_id":"1c5d1dba-ca5f-4d85-a107-3f9e6ab56460",
		"site_name":"KGFK",
		"site_provider":”public”,
		"site_provider_id":"KGFK"
	}],
	"errors":{},
	"units":{
		"elevation":"ft"
	}
}

Retrieve Device Readings for a Site - v1.1

This endpoint can be used for retrieving time series of readings for one or more devices present at a target site. Currently, a maximum of 240 hours can be retrieved per retrieval operation. Frequency of time series intervals returned is not guaranteed to be evenly spaced or consistent, and will vary by both site and device.

URL Description

https://ag.us.clearapis.com/v1.1/sensors/wx_station/data?app_id={string}&app_key={string}&account_id={string}&site_ids={string}&start_time={integer}&end_time={integer}&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.

start_time

integer

yes

Unix timestamp representing beginning of time series range. Must be less than end_time.

end_time

integer

yes

Unix timestamp representing end of time series range. Must be greater than end_time.

site_ids

string

yes

Target site_id as obtained from site metadata endpoint. Currently limited to one site.

unitcode

string

no

Either "us-std" or "si-std." Default value of "us-std." Additional information is available in the Parameter Units section of the Appendix.

Response Object (JSON)

The available keys and values in a time series is not guaranteed to be consistent, even for the same device, and are subject to what is received from the provider. Known key names provided by users are normalized to those common to Iteris APIs (particularly the ClearAg Weather API). There may be keys and associated values returned which will not be normalized or subject to unit conversion and validation features. These will be handled on a case-by-case basis.

Field Description

data

Data is arranged by site ID at the root depth, and one or more device ID’s associated with that site at the following depth.

device_readings

Available sensor readings for each device will be present in this section, hashed by Unix timestamp.

units

Will contain current unit of measure for known sensor reading key and values which have been normalized. Unit of measure is determined by chosen unitcode. Additional information is available in the Parameter Units section of the Appendix.

qc_index

When the QC Index is included it provides an integer score from zero to 100, representing a percentage of the possible individual component scores. For those device readings that do not receive a QC_index score, a value of 'null' is returned. Please refer to the Quality Control (QC) Indicators section of the Appendix for additional explanation.

Example Request

https://ag.us.clearapis.com/v1.1/sensors/wx_station/data?app_id=456&app_key=789&account_id=abc-123&site_ids=1c5d1dba-ca5f-4d85-a107-3f9e6ab56460&start_time=1557853200&end_time=1557856560&unitcode=si-std

Example Response

The following JSON response is provided as an example, the length and content of individual users’ JSON responses will vary based on user input.

{
	"data":{
		"1c5d1dba-ca5f-4d85-a107-3f9e6ab56460":{
			"cc846ae1-9d8a-4d24-abfe-ab97360c1e12":{
				"1557856380":{
					"air_temp":{
						"qc_index":93,
						"value":19.39
					},
					"dew_point":{
						"qc_index":88,
						"value":5.59
					},
					"relative_humidity":{
						"qc_index":88,
						"value":40.38
					},
					"visibility":{
						"qc_index":null,
						"value":16.09
					},
					"wind_direction":{
						"qc_index":null,
						"value":40
					},
					"wind_speed":{
						"qc_index":98,
						"value":20.37
					}
				}
			}
		}
	},
	"errors":{},
	"units":{
		"air_temp":"C",
		"dew_point":"C",
		"relative_humidity":"%",
		"visibility":"km",
		"wind_direction":"degrees",
		"wind_gust":"kph",
		"wind_speed":"kph"
	}
}

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.

Error Handling

Validation errors will result in a status 400 and JSON response with the following format. Other errors or warnings will appear in the “errors: {}” key and value present in responses. These should be status 200 responses. Error keys/identifiers will be unique, with the represented context or meaning being permanent.

Enumeration values and possible errors that may be encountered are still being determined.

Example:

{
	"data":[],
	"errors":={
		"05x004":"Unsupported endpoint version.",
		"05x015":"Non-numeric location coordinate pair provided."
	}
}

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.

Parameter Units

Below is a listing of weather parameter units, 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, dew point temperature

SI-std

C

Degrees Celsius

temperature, dew point temperature

US-std & SI-std

%

Percent

cloud cover, forecast confidence, relative humidity

US-std

In

Inch

precipitation accumulation, potential evapotranspiration

SI-std

mm

Millimeter

precipitation accumulation

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

Supported Readings

This table contains the list of possible key names that can appear in a weather station report from the Sensor Integration API response.

API Response Key Name Description

air_temp

Shelter (two meters above ground) air temperature.

air_temp_max_24hr

Maximum air temperature within the past 24 hours, at two meters above ground level in degrees Fahrenheit.

air_temp_max_6hr

Maximum air temperature within the past 6 hours, at two meters above ground level in degrees Fahrenheit.

air_temp_min_24hr

Minimum air temperature within the past 24 hours, at two meters above ground level in degrees Fahrenheit.

air_temp_min_6hr

Minimum air temperature within the past 6 hours, at two meters above ground level in degrees Fahrenheit.

dew_point

Dew point temperature data. Dew point temperature is defined as the temperature to which the air must be cooled for saturation and condensation to occur.

msl_pressure

Current mean sea level pressure data.

precip_acc_15min

Amount of precipitation accumulating within the past 15 minutes, in addition to precipitation occurring during the current hour.

precip_acc_1hr

Amount of precipitation accumulating within the past hour, in addition to precipitation occurring during the current hour.

precip_acc_24hr

Amount of precipitation accumulating within the past full 24 hours, in addition to precipitation occurring during the current hour.

precip_acc_3hr

Amount of precipitation accumulating within the past 3 hours, in addition to precipitation occurring during the current hour.

precip_acc_1hr

Amount of precipitation accumulating within the past hour, in addition to precipitation occurring during the current hour.

precip_acc_6hr

Amount of precipitation accumulating within the past 6 hours, in addition to precipitation occurring during the current hour.

precip_acc_year_to_date

Precipitation accumulation since January 1st of the current year.

precip_acc_today

Precipitation accumulation since midnight today in the time zone of the location queried.

precip_rate

Rate of precipitation accumulation, representing the liquid-equivalent precipitation total.

precip_acc_month_to_date

Precipitation accumulation data over the course of the previous month, representing the liquid-equivalent precipitation total.

precip_acc_event

The amount of precipitation that has accumulated during the duration of a ongoing precipitation event (i.e. a storm).

pressure

Current station pressure data. Station pressure is the barometric pressure at a specific elevation and is the true barometric pressure at the observing location.

relative_humidity

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

short_wave_radiation

Current downwelling shortwave radiation flux data. Shortwave radiation is the high-energy solar radiation that reaches Earth’s surface.

station_pressure

Current station pressure data. Station pressure is the barometric pressure at a specific elevation and is the true barometric pressure at the observing location.

visibility

Current 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 at ten meters above ground level, measured with respect to true north. A wind direction from true north corresponds to a value of zero degrees, which increases to 360 degrees with corresponding clockwise shifts in wind direction.

wind_gust

Wind gust at ten meters above ground level.

wind_speed

Wind speed at ten meters above ground level.

Quality Control (QC) Indicators

QC Index

When the QC Index is included, the key name is "qc_index" and it provides an integer score from zero to 100, representing a percentage of the possible individual component scores. If the qc_index cannot be computed for something normally receiving QC tests, a value of -1 will be reported. In cases where the test execution failed, a value of -2 will be reported. For those device readings that do not receive a QC_index score, a value of 'null' is returned.

Only selected readings undergo QC and report a QC index. For those that do, detailed information describing the results of individual tests from which the composite index is derived are optionally included. This table shows which reading types undergo QC and which tests are performed. Tests are described further down. Please note that QC data is not guaranteed for observations prior to January 2020.

QC Checks by Reading Type

Please note that this information is provided as high-level understanding of how the QC_index is generated.

Reading Type I V T B S Q

air_temp

X

X

X

X

X

X

dew_point

X

X

X

X

X

X

relative_humidity

X

X

X

X

X

X

pressure

X

X

X

X

X

wind_speed*

X

X

X

X

X

X

wind_gust*

X

X

X

X

X

X

precip_rate

X

X

X

X

precip_accumulation*

X

shortwave_radiation

X

X

X

*Includes variations of these

Individual QC Tests

Test ID Test Description

I

Internal Consistency — checks whether the reading has a value that is physically consistent with related values. For example, dew point cannot exceed temperature.

V

Validity — a pass fail test of whether the value is meteorologically possible.

T

Temporal — tests that monitor the change of values over time. For example, stuck sensors that are reporting the same value repeatedly in an unrealistic manner or a jump in the reading not consistent with previous valid readings.

B

Background — consistency check against and independent estimate (short-range forecast) at the same time and location.

S

Spatial — checks against other devices that are nearby.

Q

Quality — check of the overall qc_index results of preceding observations. This has no direct relation to the particular value of the current observation, but is a percentage of the possible qc_index scores of the observations leading up to this one. Meaning, if the QC results have not previously been good for the variable for the device, suspicion is cast on subsequent observations.

Changelog

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

2/25/20

Added Pessl Weather Station as an integrated partner.

1/8/20

Updated the Retrieve Device Readings for a Site endpoint as well as added new QC-related appendix sections.