$twcweather.alerts

From webCoRE Wiki - Web-enabled Community's own Rule Engine
Revision as of 21:36, 4 November 2019 by WCmore (talk | contribs) (Unique dataPoints)
Jump to: navigation, search
Share on FacebookShare on TwitterShare on Google+Share on LinkedInShare on DiggShare on deliciousShare on redditShare on StumbleUpon

As of November 5th, we have been unable to locate an official document listing the weather alerts available to SmartThings, with complete syntax and responses. Since most of us would rather not have to wait for that documentation to start programming, a bunch of us have been gathering data the old fashioned way, and combining our findings on this page.

If you see a unique alert for your location, please contribute your observations in this thread, and I will keep the wiki updated.

If you are interested in standard weather data that is not an alert, try: TWC Weather.

Introduction

Everything on this page focuses on $twcweather.alerts. This query will usually return [] unless there is an alert for your location. When that happens, up to 62 different dataPoints may be returned. Every one of them begins with $twcweather.alerts followed by a period, and ending with the dataPoint listed below. (such as: $twcweather.alerts.eventDescription) There are a couple of tables below that got a bit crowded, so some of them will not list the beginning portion, but it is important to remember that every single command on this page begins with $twcweather.alerts.

Accessing the data

It is unfortunate, but a weather alert cannot be used as a trigger. To get alerts for your area, you can program a piston to periodically make a query. (mine is set to run every 15 minutes, but other triggers can work as well, such as right before you go to work) Please program strategically so we don't hammer the weather server too frequently. Any more often than 4 times an hour is a waste of resources and pointless for alerts. We don't want to encourage SmartThings to start charging us for this data. (since they are billed for each query)


Anyways, for the most part, the "unknown dataPoints" are listed first, so they get the most exposure & hopefully more contributions. These will be followed by the dataPoints that are likely the most useful. The final category will be the dataPoints that are probably the least useful.


.

Needs More Information Gathered

We really need more data responses for this section. Please add any unique observations to this thread.

Unknown dataPoints

Expression Sample value Notes
$twcweather.alerts.categories.category "Met", "Other" Meteorology??
$twcweather.alerts.categories.categoryCode "2", "12"  ??
$twcweather.alerts.disclaimer null  ??
$twcweather.alerts.eventTrackingNumber 0003  ??

Flood

The dataPoint $twcweather.alerts.flood is usually null, but when there is an alert for possible flooding, then these extra dataPoints may appear:

Expression Sample value Notes
$twcweather.alerts.flood.floodCrestTimeLocal null  ??
$twcweather.alerts.flood.floodCrestTimeLocalTimeZone null  ??
$twcweather.alerts.flood.floodEndTimeLocal null  ??
$twcweather.alerts.flood.floodEndTimeLocalTimeZone null  ??
$twcweather.alerts.flood.floodImmediateCause "Excessive Rainfall" Needs more examples
$twcweather.alerts.flood.floodImmediateCauseCode "ER" Needs more examples
$twcweather.alerts.flood.floodLocationId 00000, AFBI2  ??
$twcweather.alerts.flood.floodLocationName "N/A", "White River at Apache Tailwater"  ??
$twcweather.alerts.flood.floodRecordStatus "N/A"  ??
$twcweather.alerts.flood.floodRecordStatusCode "OO"  ??
$twcweather.alerts.flood.floodSeverity "N/A", "None"  ??
$twcweather.alerts.flood.floodSeverityCode "N", "0"  ??
$twcweather.alerts.flood.floodStartTimeLocal null  ??
$twcweather.alerts.flood.floodStartTimeLocalTimeZone null  ??


.

Important & Useful

Most of our coding will likely use the data found in this section.
If you discovery any data not listed here, please let us know here.

Alerts

It appears that these next 5 dataPoints are mostly connected, so this table is shown a bit differently than the above tables.
To conserve space, the first three columns are marked with numbers that align with:

  1. phenomena
  2. productIdentifier
  3. eventTrackingNumber
Each dataPoint below must begin with $twcweather.alerts. (Such as: $twcweather.alerts.phenomena)
1 2 3 eventDescription headlineText Notes
TAW AWW 0000 Airport Weather Warning Airport Weather Warning until FRI 2:15 PM CDT
TAQ AQA 0000 Air Quality Alert Air Quality Alert until THU 11:00 PM EDT
BH CFW 0014 Beach Hazard Statement Beach Hazard Statement from SAT 10:00 AM EDT until SAT 10:00 PM EDT
TCA CAE 0000 Child Abduction Emergency Child Abduction Emergency until FRI 9:59 PM EDT
TCE CEM 0000 Civil Emergency Message Civil Emergency Message until WED 7:15 PM EDT
CF CFW 0024 Coastal Flood Statement Coastal Flood Statement from FRI 8:00 PM EDT until SAT 12:00 AM EDT
FG NPW 0003 Dense Fog Advisory Dense Fog Advisory from SAT 5:40 AM EDT until SAT 10:00 AM EDT
FF FFW 0076 Flash Flood Warning Flash Flood Warning from WED 7:47 PM CDT until WED 11:45 PM CDT
FF FFA 1, 0015 Flash Flood Watch Flash Flood Watch until WED 9:00 PM AST
FA FLS 0156, 0169 Flood Advisory Flood Advisory from THU 5:21 PM EDT until THU 7:15 PM EDT
FZ NPW 0003 Freeze Warning Freeze Warning from FRI 2:00 AM EDT until FRI 10:00 AM EDT
FR NPW 0003 Frost Advisory Frost Advisory until FRI 9:00 AM EDT
HT NPW 0003 Heat Advisory Heat Advisory from TUE 10:00 AM EDT until TUE 9:00 PM EDT
HW NPW 0002 High Wind Warning High Wind Warning from THU 3:09 PM EDT until FRI 6:00 AM EDT
MA MWS 1 Marine Weather Statement Marine Weather Statement until TUE 2:30 PM AST
RP CFW 0008 Rip Tide Statement Rip Tide Statement from WED 6:00 AM EDT until WED 9:00 PM EDT
FL FLS 0065 River Flood Advisory River Flood Advisory until SUN 7:00 AM CDT
SV SVR, SVS 0106, 0333 Severe Thunderstorm Warning Severe Thunderstorm Warning from WED 6:14 PM CDT until WED 6:45 PM CDT
SV WCN 0547 Severe Thunderstorm Watch Severe Thunderstorm Watch until WED 9:00 PM EDT US
thunderstorm ECA 0000 Severe Thunderstorm Watch Severe Thunderstorm Watch is in effect Canada
TSG SPS 0000 Significant Weather Advisory Significant Weather Advisory until FRI 4:15 PM EDT
SC MWW 0093 Small Craft Advisory Small Craft Advisory from FRI 12:00 PM EDT until FRI 8:00 PM EDT
TSL SPS 0000 Special Weather Statement Special Weather Statement until SUN 9:00 AM CDT
TR TCV 1005 Tropical Storm Watch Tropical Storm Watch is in effect
TTP HLS 0000 Tropical Weather Statement Tropical Weather Statement until TUE 4:15 AM AST

(the known "Sample values" are shown in the grey boxes above)

Descriptions

It appears that the following dataPoints are paired up, so this table is shown a bit differently than the above tables.

Each dataPoint below must begin with $twcweather.alerts. (Such as: $twcweather.alerts.certaintyCode)
certaintyCode certainty Notes
1 Observed Determined to have occurred or to be ongoing
2 Likely Likely (p > ~50%)
3 Possible Possible but not likely (p <= ~50%)
4? Unlikely Not expected to occur (p ~ 0)
5 Unknown Certainty unknown
messageTypeCode messageType Notes
1 New
2 Update
3? ??  ??
responseTypes.responseTypeCode responseTypes.responseType Notes
1 Shelter
2? ??  ??
3 Prepare
4 Execute
5 Avoid
6 Monitor
severityCode severity Notes
1? ??  ??
2 Severe
3 Moderate
4 Minor
5? ??  ??
urgencyCode urgency Notes
1 Immediate
2 Expected
3 Future
4? ??  ??
5 Unknown

(the known "Sample values" are shown in the grey boxes above)

Significance

The code $twcweather.alerts.significance returns a single letter, as seen in the "Sample value" column below.
The second column contains educated guesses based on the alerts I have seen so far.

Sample value Likely? Seen during
A Watch Flash Flood Watch, Severe Thunderstorm Watch, Tropical Storm Watch
L Alert/Emergency Air Quality Alert, Child Abduction Emergency
M Message Civil Emergency Message
S Statement Beach Hazard Statement, Coastal Flood Statement, Marine Weather Statement, Rip Tide Statement, Special Weather Statement, Tropical Weather Statement
W Warning Airport Weather Warning, Freeze Warning, High Wind Warning, Severe Thunderstorm Warning
Y Advisory Dense Fog Advisory, Flood Advisory, Frost Advisory, Heat Advisory, River Flood Advisory, Significant Weather Advisory, Small Craft Advisory

Times

These seem to be the most helpful times listed.

Expression Sample value Notes Seems to be...
$twcweather.alerts.processTimeUTC 1564471315
$twcweather.alerts.expireTimeUTC 1564534800 Time the alert expires
$twcweather.alerts.issueTimeLocal 2019-07-30T03:21:00-04:00 Time the alert was posted
$twcweather.alerts.expireTimeLocal 2019-07-30T21:00:00-04:00 Time the alert expires
$twcweather.alerts.onsetTimeLocal 2019-07-30T10:00:00-04:00 Usually returns null. Time the event is expected to occur
$twcweather.alerts.effectiveTimeLocal 2019-07-30T10:00:00-04:00 Usually returns null. Time the event is expected to occur

Location

These seem to be the only helpful locations, that may change based on the precise location of the alert.

Expression Sample value Notes
$twcweather.alerts.areaId "NYZ179", "ANZ335" Code for a location where the event occurs
$twcweather.alerts.areaName "Northern Nassau County",

"Long Island Sound East of New Haven CT/Port Jefferson NY",
"Coastal Waters of Southern Puerto Rico out 10 NM"

Mixed case location name
$twcweather.alerts.areaTypeCode "C" = County,

"Z" = Zone,
"CLC" = Canada Location

Type of location
(Usually returns Z)


.

Not Very Useful

The following dataPoints seem mostly useless, but we are still gathering data.
If any of these dataPoints are found to be helpful, I will relocate it to the appropriate section above.

Times

I suspect these dataPoints will only change twice a year (when we change our clocks).

Expression Sample value
$twcweather.alerts.expireTimeLocalTimeZone EDT
$twcweather.alerts.effectiveTimeLocalTimeZone EDT
$twcweather.alerts.issueTimeLocalTimeZone EDT
$twcweather.alerts.onsetTimeLocalTimeZone EDT, null

Locations

I suspect these dataPoints may never change.

Expression Sample value Notes
$twcweather.alerts.adminDistrict "New York", "Alberta"
$twcweather.alerts.adminDistrictCode "NY", "AB"
$twcweather.alerts.countryCode "US", "CA" country code of the location
$twcweather.alerts.countryName "UNITED STATES OF AMERICA", "CANADA"
$twcweather.alerts.ianaTimeZone "America/New_York", "America/Edmonton"
$twcweather.alerts.latitude 40.01
$twcweather.alerts.longitude -75.01
$twcweather.alerts.officeAdminDistrict "New York", null
$twcweather.alerts.officeAdminDistrictCode "NY"
$twcweather.alerts.officeCode "KOKX", "CWTO"
$twcweather.alerts.officeCountryCode "US", "CA"
$twcweather.alerts.officeName "New York City"
$twcweather.alerts.source "National Weather Service", "Meteorological Service of Canada"

I am hoping this last one changes occasionally... It'd be nice to see multiple sources merging for important alerts

In the 15 alerts I have seen so far, none of these locations changed between alerts. I think the best way for us to confirm this, is if each of us observes our own alerts. You'll see patterns after a handful of alerts, and can report your findings here. (Please do not share your real longitude & latitude)

Unique dataPoints

Not sure of the relevance here... They change at almost every alert.

Expression Sample value Notes
$twcweather.alerts.detailKey "8db0a39f-2c26-39c9-862b-37f7256f3d45",
"681e5182-53c2-394e-9440-c4a426680f82"
Detail record key (36 characters)
Might linger if the alerts are similar
$twcweather.alerts.identifier "f1bac66b482866c05c82fc3462978a17",
"6e39ac945ef3c7be4593d528be6388d4"
32 characters
Might linger if the alerts are identical


.

Conclusion

The data gathering phase is still in progress, so this page will be updated whenever new data is posted to this thread.

I am excited to see what kind of pistons we can create for these weather alerts! Don't forget to share your creations on the forum...


.

Future Projects

I think we also need to monitor $twcweather.alerts.length, because
that dataPoint does not return when querying $twcweather.alerts

This makes me wonder what other hidden dataPoints are available...

Observations

Normally, on a clear day, the responses are usually:

caption

Unfortuunately, it seems that $twcweather.alerts.length will also count nulls.

caption

OR

caption

I have had about 15 of these the past few days. Each time, the weather was only slightly bad. (not worthy of an alert, IMO)


If you'd like to help me understand what $twcweather.alerts.length represents, here is a piston that is ready for import.


.