Package: Open Weather Map Class

Author: HCA Central
Version: 12
Added to Library: 10-Nov-23
HCAVersion needed: 18.0.3
Keywords: Class

Requirements: Before using some setup is required. See technical note #604 on the support website technical notes area.
Extra Info Link: Here

Package Description:
What's new?

- Corrected the programs called "Day End", "Day Start", and "Noon" used by the weather tiles

What's new?

- Added Forecast and Forecast Analysis programs

- Added History and History Analysis programs

- Added collection of text weather description and icon during execution of class program

Program: Class Program

Program Description:
reads data from the open weather map provider and saves the data where the hca _weatherget() function and weather-test element can operate upon it.

stored as tags on this program after execution is the current weather description

several tags on this program help to configure it:

keephistory:

0 or 1: if 1 then a file is appended to with the observation data in a csv format

historyfolder

the path to the folder where the weather log files are stored

Global Variable Use:

Name Description
OWAppId application id used by open weather class
OWUnits open weather units for temperature. set as "imperial" or "metric"
OWLocation open weather location. set in the form of zip=,us

Program: Day End

Program Description:
generates a time for the end of the day a number of days from now. this is useful when reporting on a max or mion on a gven day in the future.

Parameters:

Name Type Description Default
DaysInTheFuture Value Number of days in the future. 0 = todaay, 1 = tomorrow, 2 = day after that, etc.  

Program: Day Start

Program Description:
generates a time for the start of the day a number of days from now. this is useful when reporting on a max or mion on a gven day in the future.

Parameters:

Name Type Description Default
DaysInTheFuture Value Number of days in the future. 0 = todaay, 1 = tomorrow, 2 = day after that, etc.  

Program: Forecast

Program Description:
gets a value from a weather forecast for a time in the future. the data to retrieve is specified as the second argument string value

"temp"

"pressure"

"humidity"

"wind-speed"

"wind-deg"

"wind-gust"

"pop" (probability of precipitation)

"rain-3h" (rain over 3-hours)

"weather-main" (text description of general weather condition)

"weather-description"(text description of general weather condition)

"weather-icon" (icon for the weather condition)

if there is an error in retrieving the data, a bool value is returned. use _isbool to check for an error return before using the return value.

saves all the forecast result as tags on this program

if this function is called again with the same time in the future and the data last retrieved from ow isn't too old, then the result is fast. if you get, for example, the temperature in 12 hours, getting the humidity in 12 hours will be very quick as it only accesses the program tags

"too old" is determined by the number of *minutes* specified in the "requestttl" tag on this program. ttl = "time to live". a ttl value of zero will cause the forecast data to be re-fetched each time.

Return value: the data from the forecast

Parameters:

Name Type Description Default
TimeInTheFuture Value Time in the future to find forecast data for  
WhatData Value "temp", "pressure", "humidity", "wind-speed", "wind-deg", "wind-gust", "pop", "rain-3h","weather-main", "weather-description", "weather-icon"  

Global Variable Use:

Name Description
OWAppId application id used by open weather class
OWUnits open weather units for temperature. set as "imperial" or "metric"
OWLocation open weather location. set in the form of zip=,us

Program: Forecast Analysis

Program Description:
looks at forecast data for data between a range of date-time. computes the max, min, or average of one observation data item during that time period. for rain amount you can also total the amount over the time period.

the data items are specified as a string:

"temp"

"pressure"

"humidity"

"wind-speed"

"wind-deg"

"wind-gust"

"pop" (probability of precipitation)

"rain-3h" (rain over 3-hours)

the operations are specified as a string "max", "min", "avg", "total"

if there is an error in retrieving the data, a bool value is returned. use _isbool to check for an error return before using the return value.

saves the aggregated data for all forecast items in tags on this program.

if this function is called again with the same time range, and the data last retrieved from ow isn't too old, then the result is fast. if you get, for example, the avg temperature between two times, getting the max humidity in that same time range be very quick as it only access the pre-computed and saved values.

Parameters:

Name Type Description Default
StartDateTime Value Time in the future to start aggregation  
EndDateTime Value Time in the future to end aggregation  
Op Value Operations are: "max", "min", "avg", "total". Note that total only applies to "rain-3h"  
WhatData Value Data to get: "temp", "pressure", "humidity", "wind-speed", "wind-deg", "wind-gust", "pop", "rain-3h"  

Global Variable Use:

Name Description
OWAppId application id used by open weather class
OWUnits open weather units for temperature. set as "imperial" or "metric"
OWLocation open weather location. set in the form of zip=,us

Program: Forecast Extract

Program Description:
helper function to extract data from json providing a path

Parameters:

Name Type Description Default
hJson Value Handle to json  
ArraySection Value Array section index 0-120  
NamePath Value Path to data. Path items separated by dash character. If the item has a # prepended it is used as a number to _JSON  

Program: History

Program Description:
gets a value from historical weather data from a specified date-time. the data to retrieve is specified as the second argument as a string:

"temp"

"pressure"

"humidity"

"wind-speed"

"wind-deg"

"wind-gust"

"pop" (probability of precipitation)

"rain-3h" (rain over 3-hours)

"weather-main" (text description of general weather condition)

"weather-description"(text description of general weather condition)

"weather-icon" (icon for the weather condition)

if there is an error in retrieving the data, a bool value is returned. use _isbool to check for an error return before using the return value.

if this function is called again with the same requested date-time, the result is fast. if you get, for example, the temperature 12 hours ago, getting the humidity 12 hours ago will be quick as it doesn't access the weather log files.

Parameters:

Name Type Description Default
TimeInThePast Value Time in the past to find historic data for  
WhatData Value "temp", "pressure", "humidity", "wind-speed", "wind-deg", "wind-gust", "pop", "rain-3h","weather-main", "weather-description", "weather-icon"  

Program: History Analysis

Program Description:
looks at historical data between two dates and computes the max, min, or average of one observation data item during that time period. for rain amount you can also total the amount over the time period.

"temp"

"pressure"

"humidity"

"wind-speed"

"wind-deg"

"wind-gust"

"pop" (probability of precipitation)

"rain-3h" (rain over 3-hours)

the operations are specified as a string "max", "min", "avg", "total"

if there is an error in retrieving the data, a bool value is returned. use _isbool to check for an error return before using the return value.

saves the aggregated data for all data items in tags on this program.

if this function is called again with the same time range then the result is fast. if you get, for example, the avg temperature between two times, getting the max humidity in that same time range is very quick as it only accesses the pre-computed values.

Parameters:

Name Type Description Default
StartDateTime Value Time in the past to start aggregation  
EndDateTime Value Time in the past to end aggregation  
Op Value Operations are: "max", "min", "avg", "total". Note that total only applies to "rain-3h"  
WhatData Value Data to get: "temp", "pressure", "humidity", "wind-speed", "wind-deg", "wind-gust", "pop", "rain-3h"  

Program: List Extract

Program Description:
helper function for the open weather package

Parameters:

Name Type Description Default
ItemName Value Name of the item to extract  
Data Value CSV data containing the item data  
ItemNameList Value CSV list of item names  
ItemPositionList Value CSV list of item positions in the data  

Program: Noon

Program Description:
generates a time for noon on a given day. this is useful when reporting forecast info for a day in the future as you probably want to know the weather is on that day. not +72 hours from your current time (should you be asking at 5 in the morning) but rather at noon that day.

Parameters:

Name Type Description Default
DaysInTheFuture Value Number of days in the future. 0 = todaay, 1 = tomorrow, 2 = day after that, etc.