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 11/4/19

Query for Available Weather Station Sites

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. Note that not all stations report all of the same parameters, so as such there may be differences in the number of reported quantities returned between stations.

Please note that certain limitations, such as maximum selection radius, have yet to be determined. Argument limitations are subject to change.

URL Description

https://ag.us.clearapis.com/v1.0/sensors/wx_stationmeta?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 0. 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_stationmeta?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 (JSON)

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

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.0/sensors/wx_stationdata?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.

Example Request

https://ag.us.clearapis.com/v1.0/sensors/wx_stationdata?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":{
				"device_readings":{
					"1557856380":{
						"air_temp":19.39,
						"dew_point":5.59,
						"relative_humidity":40.38,
						"visibility":16.09,
						"wind_direction":40,
						"wind_gust":null,
						"wind_speed":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).

Changelog

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