Google Weather API v2.0.2

[Opus4]

Weather data in SageTV is now provided via the Google Weather plugin, version 2.0.1. To assist anyone updating the weather display in a customization, here are the available API calls that can be used directly in Studio:

/*
 *	Version History:
 *
 *	2.0.0
 *		- Initial inclusion of W.U. data in the GoogleWeather plugin.
 *	2.0.1	Oct 16, 2012
 *		- Changed default icon set to 'c' instead of 'k'.
 *		- Clear data for each section when WU data is updated & section is encountered.
 *		- Check for Not Available data and substitute with appropriate N/A value.
 *		- Added call to retrieve text used to indicate Not Available.
 *		- Added call to get a unique ID (hash code) for the current set of alerts. If the ID changes, then the alerts changed.
 *		- Added local weather stations to search results list when available.
 *
 */

/*
 * Usage of version updated for SageTV integration in the Studio:
 *
 *	The version of this class can be obtained from:
 * sage_google_weather_WeatherUnderground_getWeatherVersion()
 *
 *	The text used to indicate data is Not Available can be obtained from:
 * sage_google_weather_WeatherUnderground_getNotAvailableText()
 *
 *
 *  First get an instance of this class using:
 * Weather = sage_google_weather_WeatherUnderground_getInstance()
 *
 *	Or, to get an instance of this class for an alternate weather locale:
 *	Note: the AltLocName string must contain valid filename characters only.
 * Weather = sage_google_weather_WeatherUnderground_getInstance("AltLocName")
 *
 *
 *	To get a list of alternate weather locales, including the primary "" locale:
 * sage_google_weather_WeatherUnderground_getAllWeatherLocales() returns a Vector
 *
 *	To get a list of alternate weather locales, not including the "" locale:
 * sage_google_weather_WeatherUnderground_getAlternateWeatherLocales() returns a Vector
 *
 *  To remove an alternate locale by removing its weather cache properties file:
 * sage_google_weather_WeatherUnderground_removeLocale(Weather) returns boolean
 *
 *
 *	Searching for a locale's location:
 *		Params:
 *			Weather: The weather class instance.
 *			query: The name of the location to search for.
 *			lang: The 2-letter code for the language to use in the search results.
 *		Returns:
 *			a Vector of location Maps
 * sage_google_weather_WeatherUnderground_ java.util.Vector searchLocations( Weather, query) returns a Vector
 * sage_google_weather_WeatherUnderground_ java.util.Vector searchLocations( Weather, query, lang) returns a Vector
 *
 *	To get information about a location Map:
 *		Params:
 *			Weather: The weather class instance.
 *			LocationMap: The Map of the location info.
 * sage_google_weather_WeatherUnderground_getLocationCity( Weather, LocationMap ) returns String
 * sage_google_weather_WeatherUnderground_getLocationState( Weather, LocationMap ) returns String
 * sage_google_weather_WeatherUnderground_getLocationCountry( Weather, LocationMap ) returns String
 * sage_google_weather_WeatherUnderground_getLocationNeighborhood( Weather, LocationMap ) returns String
 * sage_google_weather_WeatherUnderground_getLocationCode( Weather, LocationMap ) returns String
 *
 *	To set the location for a locale's Weather instance:
 * sage_google_weather_WeatherUnderground_setWeatherLoc( Weather, LocationMap ) Returns nothing 
 *
 *	To get a locale's Weather instance's current LocationMap setting: 
 * sage_google_weather_WeatherUnderground_getWeatherLoc( Weather ) returns a Map
 *
 *	To clear a locale's Weather instance's current location, use:  
 * sage_google_weather_WeatherUnderground_removeWeatherLoc( Weather ) returns nothing
 *
 *
 *  To get & set the current units setting:
 *		Params:
 *			Weather: The weather class instance.
 *			Units: The units string, (must be "s" or "m", for standard/english or metric, respectively; default: "s") 
 * sage_google_weather_WeatherUnderground_setUnits(Weather, Units ) returns nothing
 * sage_google_weather_WeatherUnderground_getUnits(Weather ) returns String
 *
 *
 *  To handle updating the weather data (Data is cached and updates only actually occure after time limits expire):
 *		Params:
 *			Weather: The weather class instance.
 *			lang: The 2-letter code for the language to use in the search results.
 * sage_google_weather_WeatherUnderground_updateNow(Weather) returns boolean
 * sage_google_weather_WeatherUnderground_updateNow( Weather, lang ) returns boolean
 * sage_google_weather_WeatherUnderground_isCurrentlyUpdating(Weather) returns boolean
 * sage_google_weather_WeatherUnderground_getLastUpdateTime(Weather) returns long
 *
 *
 *	To get information about weather condition icons:
 *		Retrieve a list of all icon condition names:
 * sage_google_weather_WeatherUnderground_getAllWeatherIconConditions() returns Vector
 *		Retrieve a reduced list of icon condition names:
 * sage_google_weather_WeatherUnderground_getReplacementWeatherIconConditions() returns Vector
 *		Get the reduced icon style replacement icon name for a single icon condition:  
 * sage_google_weather_WeatherUnderground_getIconReplacementString(IconName) returns String
 *
 *	Support for multiple sets of condition icons: 
 *		Params:
 *			Weather: The weather class instance.
 *			IconSet: The icon set to use; must be one from the list returned by getAllWeatherIconSets()  
 * sage_google_weather_WeatherUnderground_getAllWeatherIconSets(Weather) returns Vector
 * sage_google_weather_WeatherUnderground_getIconSet(Weather) returns String
 * sage_google_weather_WeatherUnderground_setIconSet( Weather, IconSet ) returns nothing
 *
 *	To get icon URLs for weather conditions:
 *		Params:
 *			Weather: The weather class instance.
 *			IconName: The icon condition name. 
 *			IconSet: The icon set to use; must be one from the list returned by getAllWeatherIconSets()  
 *
 *		Get an icon URL for the given icon condition name:
 * sage_google_weather_WeatherUnderground_getIconURL( Weather, IconName ) returns String
 * sage_google_weather_WeatherUnderground_getIconURL( Weather, IconName, IconSet ) returns String
 *
 *		Get an icon URL for reduced set replacement name for an icon condition name:
 * sage_google_weather_WeatherUnderground_getIconReplacementURL( Weather, IconName ) returns String
 * sage_google_weather_WeatherUnderground_getIconReplacementURL( Weather, IconName, IconSet ) returns String
 *
 *
 *	Misc info calls:
 *		Params:
 *			Weather: The weather class instance.
 *			Units: The units string, (must be "s" or "m", for standard/english or metric, respectively; default: "s") 
 * sage_google_weather_WeatherUnderground_getLastError(Weather) returns String
 *
 * sage_google_weather_WeatherUnderground_getTempSymbol(Weather) returns String
 * sage_google_weather_WeatherUnderground_getTempUnit(Weather) returns String
 * sage_google_weather_WeatherUnderground_getTempUnit( Weather, Units ) returns String
 *
 * sage_google_weather_WeatherUnderground_getDistUnit(Weather) returns String
 * sage_google_weather_WeatherUnderground_getDistUnit( Weather, Units ) returns String
 *
 * sage_google_weather_WeatherUnderground_getSpeedUnit(Weather) returns String
 * sage_google_weather_WeatherUnderground_getSpeedUnit( Weather, Units ) returns String
 *
 * sage_google_weather_WeatherUnderground_getPressureUnit(Weather) returns String
 * sage_google_weather_WeatherUnderground_getPressureUnit( Weather, Units ) returns String
 *
 * sage_google_weather_WeatherUnderground_getRainUnit(Weather) returns String
 * sage_google_weather_WeatherUnderground_getRainUnit( Weather, Units ) returns String
 *
 * sage_google_weather_WeatherUnderground_getSnowUnit(Weather) returns String
 * sage_google_weather_WeatherUnderground_getSnowUnit( Weather, Units ) returns String
 *
 *
 *	Once the weather data has been updated, retrieve data via these calls:
 *		Params:
 *			Weather: The weather class instance.
 *
 *		Get the location place names:
 * sage_google_weather_WeatherUnderground_getCityName(Weather) returns String
 * sage_google_weather_WeatherUnderground_getStateName(Weather) returns String
 * sage_google_weather_WeatherUnderground_getCountryName(Weather) returns String
 *
 *		Get current condition info for these property names:
 *			Description
 *			Dewpoint
 *			DisplayLocFull
 *			FeelsLike
 *			HeatIndex
 *			Humidity
 *			IconName
 *			ObservationLocCity
 *			ObservationLocCountry
 *			ObservationLocState
 *			ObservationTime
 *			Precip1Hr
 *			PrecipToday
 *			Pressure
 *			PressureTrend		returns: -, 0, or +
 *			Temp
 *			UV
 *			Visibility
 *			WindChill
 *			WindDir
 *			WindGust
 *			WindSpeed
 * sage_google_weather_WeatherUnderground_getCurrentCondition( Weather, propName ) returns String
 * sage_google_weather_WeatherUnderground_getCurConditionProperties(Weather) returns Map
 *
 *		Get 12 hour forecast for period number for these property names:
 *		Note: Days have even period numbers; nights have odd period numbers
 *			ChancePrecip
 *			FCText
 *			IconName
 *			PeriodName
 * sage_google_weather_WeatherUnderground_get12hrForecastStartPeriod(Weather) returns int
 * sage_google_weather_WeatherUnderground_get12hrForecastEndPeriod(Weather) returns int
 * sage_google_weather_WeatherUnderground_get12hrForecast( Weather, periodNum, propName ) returns String
 * sage_google_weather_WeatherUnderground_get12hrForecastProperties( Weather, periodNum ) returns Map
 *
 *
 *		Get 24 hour forecast for period number for these property names:
 *			ChancePrecip
 *			Conditions
 *			DateDayNum
 *			DateMonthName
 *			DateMonthNum
 *			DateWeekDay
 *			DateWeekDayShort
 *			DateYear
 *			High
 *			HumidAvg
 *			HumidMax
 *			HumidMin
 *			IconName
 *			Low
 *			RainAllDay
 *			RainDay
 *			RainNight
 *			SnowAllDay
 *			SnowDay
 *			SnowNight
 *			WindAvgDir
 *			WindAvgSpeed
 *			WindMaxDir
 *			WindMaxSpeed
 * sage_google_weather_WeatherUnderground_get24hrForecastStartPeriod(Weather) returns int
 * sage_google_weather_WeatherUnderground_get24hrForecastEndPeriod(Weather) returns int
 * sage_google_weather_WeatherUnderground_get24hrForecast( Weather, periodNum, propName) returns String
 * sage_google_weather_WeatherUnderground_get24hrForecastProperties( Weather, periodNum) returns Map
 *
 *
 *		Get weather alert information properties for an alert number:
 *			StartTime
 *			ExpireTime
 *			Title1
 *			Title2
 *			Message1
 *			Message2
 *			Message3
 * sage_google_weather_WeatherUnderground_getAlertCount(Weather) returns int
 * sage_google_weather_WeatherUnderground_getAlertUniqueID(Weather) returns int
 * sage_google_weather_WeatherUnderground_getAlertInfo( Weather, AlertNum, propName) returns String
 * sage_google_weather_WeatherUnderground_getAlertInfoProperties( Weather, AlertNum) returns Map
 *
 * 		Get Astronomy information for these property names:
 *			SunriseHour
 *			SunriseMinute
 *			SunsetHour
 *			SunsetMinute
 *			MoonPercentIlluminated
 *			MoonAge
 * sage_google_weather_WeatherUnderground_getAstronomyInfo( Weather, propName) returns String
 * sage_google_weather_WeatherUnderground_getAstronomyInfoProperties( Weather, AlertNum) returns Map
 *
 *		Get the moon image URL for the current moon age:
 * sage_google_weather_WeatherUnderground_getMoonImageURL(Weather) returns String
 *		Get the moon image URL for a specified moon age, in number of days:
 * sage_google_weather_WeatherUnderground_getMoonImageURL( Weather, MoonAge) returns String
 *
 *
 *		Get radar image URLs:
 * sage_google_weather_WeatherUnderground_getRadarNewestFrameNum(Weather) returns int
 * sage_google_weather_WeatherUnderground_getRadarOldestFrameNum(Weather) returns int
 *
 *		Get a radar image URL, using the following parameters:
 *			Params
 *				Weather 	The weather class instance.
 *				radius		The radius from the location, in miles.
 *				width		Width of image, in pixels
 *				height		Height of image, in pixels
 *				frameNum	The frame number, from getRadarOldestFrameNum() to getRadarNewestFrameNum() (5 - 0) 
 * sage_google_weather_WeatherUnderground_getRadarURL( Weather, radius, width, height, frameNum ) returns String
 *
 */

Notes:
If anyone implements the animated radar maps in a customization, please be sure to refer to the code I wrote which unloads the older radar images that are being replaced with new radar images and unloads all radar images in the ApplicationExiting hook - this was put in to help prevent the radar images from pushing out most other graphics, which could otherwise occur if you just sat on the radar screen. (The radar images automatically update after a while to keep the radar current.)


The NWS related calls in the v1 Google Weather API should still function. The reference for those calls can be found here:
Google Weather API v1

[Opus4]

The weather condition and moon phase icons can be themed. If any of the images are included in a theme, they will be used instead of the downloaded versions. Any icons not in the theme will be downloaded instead.

All weather icons should be placed in the directory defined by this existing theme line:

# Define the location of the weather icons, as a path relative to the STV directory:
String/gWeatherRelPath=WeatherIcons

Directly under that path, be sure to keep or replace the falling.png and rising.png icons used for falling/rising barometric pressure. The condition & moon icons should be placed in a subdirectory named Images. The icons will need to have an extension of .png.

For a list of all weather condition icons, call:

sage_google_weather_WeatherUnderground_getAllWeatherIconConditions()

Alternately, you could theme only a portion of the icons and use some for multiple conditions. For a list of the reduced set of weather condition icons, call:

sage_google_weather_WeatherUnderground_getReplacementWeatherIconConditions()

The moon phase icons are a series of icons named MoonN.png, where N is a number from 0 to 30.

- Andy

[Skirge01]

Who says SageTV is dead?

[waynedunham]

Thanks Opus4!! It is good to see accurate WX data again.

Also thanks for posting the API's so other WX plugins can access the data.

We need some optional icons for the online and main menu displays. I didn't find any of the icon sets built in to my liking. They were all too "cartoony" for my taste. Hopefully someone can get a set of icons similar to the original WX Channel ones.

Please don't take that as a slam on your efforts, they are MASSIVELY appreciated!

[Opus4]

Originally Posted by waynedunham

Hopefully someone can get a set of icons similar to the original WX Channel ones.

That's easy -- all you have to do is copy & renamed the icons you want to use from the original weather.com set., then reload the theme that references the directory they are in. That's what I did to test this.

Here are the icon condition names retrieved using the above-mentioned calls in Studio:

Found 40 total weather icon conditions: [chanceflurries, chancerain, chancesleet, chancesnow, chancetstorms, clear, cloudy, flurries, fog, hazy, mostlycloudy, mostlysunny, partlycloudy, partlysunny, sleet, rain, snow, sunny, tstorms, unknown, nt_chanceflurries, nt_chancerain, nt_chancesleet, nt_chancesnow, nt_chancetstorms, nt_clear, nt_cloudy, nt_flurries, nt_fog, nt_hazy, nt_mostlycloudy, nt_mostlysunny, nt_partlycloudy, nt_partlysunny, nt_sleet, nt_rain, nt_snow, nt_sunny, nt_tstorms, nt_unknown]

Found 12 replacement weather icon conditions: [flurries, rain, sleet, snow, tstorms, sunny, cloudy, fog, partlysunny, nt_clear, nt_partlycloudy, nt_unknown]

- Andy

[waynedunham]

Originally Posted by Opus4

That's easy -- all you have to do is copy & renamed the icons you want to use from the original weather.com set., then reload the theme that references the directory they are in. That's what I did to test this.

Here are the icon condition names retrieved using the above-mentioned calls in Studio:

Found 38 total weather icon conditions: [chanceflurries, chancerain, chancesleet, chancesnow, chancetstorms, clear, cloudy, flurries, fog, hazy, mostlycloudy, mostlysunny, partlycloudy, partlysunny, sleet, snow, sunny, tstorms, unknown, nt_chanceflurries, nt_chancerain, nt_chancesleet, nt_chancesnow, nt_chancetstorms, nt_clear, nt_cloudy, nt_flurries, nt_fog, nt_hazy, nt_mostlycloudy, nt_mostlysunny, nt_partlycloudy, nt_partlysunny, nt_sleet, nt_snow, nt_sunny, nt_tstorms, nt_unknown]

Found 12 replacement weather icon conditions: [flurries, rain, sleet, snow, tstorms, sunny, cloudy, fog, partlysunny, nt_clear, nt_partlycloudy, nt_unknown]

- Andy

Thanks Andy. I've printed this out and will take a look when I get a chance. Truthfully I am more interested in the icons on the main menu, I don't go to the online WX page all that often.

I do appreciate the attention you still find time to give to us and our petty needs.

[Opus4]

Another thought: If anyone implements the animated radar maps in a customization, please be sure to refer to the code I wrote which unloads the older radar images that are being replaced with new radar images and unloads all radar images in the ApplicationExiting hook - this was put in to help prevent the radar images from pushing out most other graphics, which could otherwise occur if you just sat on the radar screen. (The radar images automatically update after a while to keep the radar current.)

- Andy

[jjstok]

Awesome! Thanks for the work!

[wayner]

Is the Icon set user customizable? The icons that are in the \SageTV\SageTV7\WeatherIcons\Images folder don't appear to be used but they look much better than the ones that I can select from in Options.

* merged; see above *

[Opus4]

The first post has been updated for the v2.0.1 Google Weather API.

- Andy

[spacecadet]

Originally Posted by Opus4

That's easy -- all you have to do is copy & renamed the icons you want to use from the original weather.com set., then reload the theme that references the directory they are in. That's what I did to test this.

Here are the icon condition names retrieved using the above-mentioned calls in Studio:

Found 38 total weather icon conditions: [chanceflurries, chancerain, chancesleet, chancesnow, chancetstorms, clear, cloudy, flurries, fog, hazy, mostlycloudy, mostlysunny, partlycloudy, partlysunny, sleet, snow, sunny, tstorms, unknown, nt_chanceflurries, nt_chancerain, nt_chancesleet, nt_chancesnow, nt_chancetstorms, nt_clear, nt_cloudy, nt_flurries, nt_fog, nt_hazy, nt_mostlycloudy, nt_mostlysunny, nt_partlycloudy, nt_partlysunny, nt_sleet, nt_snow, nt_sunny, nt_tstorms, nt_unknown]

Should "rain" and "nt_rain" be included in the list above? I themed my icons and I notice that I am getting the default icon for rain and not the one in my theme directory named rain.png.

If I inspect the results of calling the weather underground api it appears that "rain" is a valid condition.

Am I missing something?

Thanks!

Brian

[Opus4]

Originally Posted by spacecadet

Should "rain" and "nt_rain" be included in the list above?

Yes, somehow I missed those. I'll double check the entire list.

- Andy

[spacecadet]

Originally Posted by Opus4

Yes, somehow I missed those. I'll double check the entire list.

- Andy

Thanks!

[Opus4]

Originally Posted by spacecadet

Should "rain" and "nt_rain" be included in the list above?

The plugin has been updated to v2.0.2 to include the rain icon names -- those were the only ones I found to be missing. I have no idea how they got left out, since rain shouldn't be a new weather condition... although for my area they need to update the icon to show the rain going sideways instead of almost straight down.

No functionality changed -- just the list of possible icon names has changed.

- Andy

[Skirge01]

Originally Posted by Opus4

The plugin has been updated to v2.0.2 to include the rain icon names -- those were the only ones I found to be missing. I have no idea how they got left out, since rain shouldn't be a new weather condition... although for my area they need to update the icon to show the rain going sideways instead of almost straight down.

No functionality changed -- just the list of possible icon names has changed.

- Andy

Once again, Andy, thanks for the continued work on fixing things for us. I was actually glad to see you posted as I recalled you being from NJ, as well, and was wondering how you fared. This is my first time back online since last Monday when the storm obliterated anything near water in NJ. We made it through with our house intact and are very thankful for that.

[Opus4]

Originally Posted by Skirge01

Once again, Andy, thanks for the continued work on fixing things for us. I was actually glad to see you posted as I recalled you being from NJ, as well, and was wondering how you fared. This is my first time back online since last Monday when the storm obliterated anything near water in NJ. We made it through with our house intact and are very thankful for that.

Our neighborhood was out of power several times - the longest for 11 hours. However, after last year's storms, we put in a natural gas whole house backup generator, so the longest we were out of power at any one time was about 10+ seconds. So, we are fine except for a 1.5 ft piece of siding, but large parts of our town, including some schools, still have no power.

- Andy