$twcweather.alerts

As of March 8th, 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)

Legend

Here is a quick list to show what each color represents on this page...

Headers for each table

Warnings / Reminders

Duplicates

Code found in a 2016 document that needs to be verified

---

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, and the occasional flood dataPoints. 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.disclaimer	null	Disclaimer for data
$twcweather.alerts.eventTrackingNumber	0003	4 digit number or a checksum

Unverified dataPoints

The following responses are not returned with $twcweather.alerts, but there is a chance that they exist if a direct query is made. Further testing is required.

(Unverified) Expression	(Unverified) Sample value	Notes
$twcweather.alerts.synopsis	null	(Brief summary)
$twcweather.alerts.texts.description	"...Flood Warning extended until Monday morning...The Flood Warning\ncontinues for the Guadalupe River Near Bloomington.\n* until Monday morning...or until the warning is cancelled.\n* At 8:00 AM Friday the stage was 25.2 feet.\n* Moderate flooding is occurring and Moderate flooding is forecast.\n* Flood stage is 20.0 feet.\n* Forecast: The river has crested overnight and will continue to fall\nand is expected to go below flood stage by Sunday afternoon.\n* At 26.0 feet Irrigation and oil well pumps, tank batteries, and\nequipment in the lower flood plain below Victoria flood. Livestock\nare cut off, may have to be fed by boat, and could drown. Homes\ndownstream above Highway 35 on the left bank are cut off.\n\n&&\n\nBelow are the latest river stages and stage forecasts:\n\nFLD LATEST FORECAST 6 AM LST\nLOCATION STG STG DAY TIME Sat Sun Mon Tue Wed\n\nGuadalupe River\nBloomington 20 25.2 Fri 08 AM 23.8 21.1 18.7 17.8 17.6\n\n&&\n\n\n"	??
$twcweather.alerts.texts.instruction	null	??
$twcweather.alerts.texts.languageCode	en-US	??
$twcweather.alerts.texts.overview	"...The Flood Warning continues for the following river in Texas...\n\nGuadalupe River Near Bloomington affecting Calhoun...Refugio and\nVictoria Counties\n\n.Recent rainfall upstream and over the area will keep the aforementioned\nriver above flood stage for the next few days.\n\nPRECAUTIONARY/PREPAREDNESS ACTIONS...\n\nStay tuned to NOAA Weather Radio, local TV and radio\nstations, or cable TV outlets, for the latest weather\ninformation, as additional rainfall could affect crest\nforecasts.\n\nFor the latest river stages and forecasts visit our AHPS page at:\nhttp://water.weather.gov/ahps2/index.php?wfo=crp\n\n&&\n\n"	??

I recommend testing these commands shortly after you receive a weather alert, and share your findings here.

So far, we have testing (and failed) with:

.

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 (Phenomena code of an event)
2. productIdentifier (Refer Inbound PIL/Event Tab)
3. eventTrackingNumber (4 digit number or a checksum)

NOTE: No patterns have been seen for eventTrackingNumber yet... What is this number really??

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	0002	Coastal Flood Advisory	Coastal Flood Advisory from SAT 5:00 AM EST until SAT 8:00 AM EST
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	0090, 0156, 0169	Flood Advisory	Flood Advisory from THU 5:21 PM EDT until THU 7:15 PM EDT
FA	FLW	0011	Flood Warning	Flood Warning from THU 9:03 AM EST until THU 3:00 PM EST
??	???	0004	Flood Watch	Flood Watch until TUE 7:00 AM EST	Needs more info
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
GL	MWW	0024	Gale Warning	Gale Warning from TUE 10:26 AM EST until WED 6:00 AM EST
GL	MWW	0030	Gale Watch	Gale Watch from WED 6:00 PM EST until THU 6:00 AM EST
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
??	???	0001	High Wind Watch	High Wind Watch from SUN 1:00 PM EST until MON 7:00 AM EST	Needs more info
LW	NPW	0001	Lake Wind Advisory	Lake Wind Advisory from SAT 8:58 AM EST until SAT 7:00 PM EST
MA	MWS	1	Marine Weather Statement	Marine Weather Statement until TUE 2:30 PM AST
FW	RFW	0001	Red Flag Warning	Red Flag Warning from SAT 12:00 PM EST until SAT 7:00 PM EST	Potential Fire
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
MA	SMW	0005	Special Marine Warning	Special Marine Warning from TUE 10:34 PM EST until TUE 11:15 PM EST
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
TO	TOR	0006	Tornado Warning	Tornado Warning from TUE 4:35 AM EST until TUE 5:00 AM EST
TO	WCN	0015	Tornado Watch	Tornado Watch until SAT 9:00 PM EST
TTP	HLS	0000	Tropical Weather Statement	Tropical Weather Statement until TUE 4:15 AM AST
WI	NPW	0003	Wind Advisory	Wind Advisory from SAT 10:00 AM EST until SUN 12:00 AM EST
??	???	0001	Wind Chill Advisory	Wind Chill Advisory from TUE 10:00 PM EST until WED 9:00 AM EST	Needs more info
WW	WSW	0005, 0025, 0038	Winter Weather Advisory	Winter Weather Advisory from MON 4:00 PM EST until TUE 7:00 PM EST

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

phenomena Patterns

Some of the results for phenomena shown above aligns with more than one eventDescrition... Here is educated guesses as to their meaning:

phenomena	Likely?	Seen during
CF	Coastal Flood?	Coastal Flood Advisory, Coastal Flood Statement
FF	Flash Flood?	Flash Flood Warning, Flash Flood Watch
FA	Flood?	Flood Advisory, Flood Warning
GL	Gale?	Gale Warning, Gale Watch
MA	Marine?	Marine Weather Statement, Special Marine Warning
SV	Severe?	Severe Thunderstorm Warning, Severe Thunderstorm Watch

productIdentifier Patterns

Some of the results for productIdentifier shown above aligns with more than one eventDescrition... Here is educated guesses as to their meaning:

productIdentifier	Likely?	Seen during
CFW	Coastal Flood Watch/Warning?	Beach Hazard Statement, Coastal Flood Advisory, Coastal Flood Statement, Rip Tide Statement
FLS	Flood Statement?	Flood Advisory, River Flood Advisory
MWW	Marine Weather Watch/Warning?	Gale Warning, Gale Watch, Small Craft Advisory
NPW	Non-Precipitation Warning?	Dense Fog Advisory, Freeze Warning, Frost Advisory, Heat Advisory, High Wind Warning, Lake Wind Advisory, Wind Advisory
SPS	Special Statement??	Significant Weather Advisory, Special Weather Statement
WCN	Watch County Notification?	Severe Thunderstorm Watch, Tornado Watch

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%)
(Likely never seen) --> 4?	Unlikely	Not expected to occur (p ~ 0)
5	Unknown	Certainty unknown
messageTypeCode	messageType	Notes
1	New	Initial information
2	Update	Updates existing message
(Likely never seen) --> 3?	Cancel	Cancels the earlier message
responseTypes.responseTypeCode	responseTypes.responseType	Notes
1	Shelter	Take shelter in place or per instruction
2?	Evacuate	Relocate as instructed in the instruction
3	Prepare	Make preparations per the instruction
4	Execute	Execute a pre-planned activity identified in instruction
5	Avoid	Avoid the subject event as per the instruction
6	Monitor	Attend to information sources as described in instruction
(Likely never seen) --> 7?	Assess	Evaluate the information in this message. (This value SHOULD NOT be used in public warning applications.)
(Likely never seen) --> 8?	AllClear	The subject event no longer poses a threat or concern and any follow on action is described in <instruction>
(Likely never seen) --> 9?	None	No action recommended
severityCode	severity	Notes
1	Extreme	Extraordinary threat to life or property
2	Severe	Significant threat to life or property
3	Moderate	Possible threat to life or property
4	Minor	Minimal to no known threat to life or property
5?	Unknown	Severity unknown
urgencyCode	urgency	Notes
1	Immediate	Responsive action SHOULD be taken immediately
2	Expected	Responsive action SHOULD be taken soon (within next hour)
3	Future	Responsive action SHOULD be taken in the near future
(Likely never seen) --> 4?	Past	Responsive action is no longer required
5	Unknown	Urgency not known

(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, Gale Watch, Severe Thunderstorm Watch, Tornado Watch, Tropical Storm Watch
B	Bulletin	??
E	Extreme	??
L	Local Alerts	Air Quality Alert, Child Abduction Emergency
M	Message	Civil Emergency Message
O	Outlook	??
R	Report	??
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, Flood Warning, Freeze Warning, Gale Warning, High Wind Warning, Red Flag Warning, Severe Thunderstorm Warning, Special Marine Warning, Tornado Warning
Y	Advisory	Coastal Flood Advisory, Dense Fog Advisory, Flood Advisory, Frost Advisory, Heat Advisory, Lake Wind Advisory, River Flood Advisory, Significant Weather Advisory, Small Craft Advisory, Wind Advisory, Winter Weather Advisory

Times

These seem to be the most helpful times listed.

Expression	Sample value	Notes	Seems to be...
$twcweather.alerts.processTimeUTC	1564471315	Valid unix time UTC	Alert process time in SUN
$twcweather.alerts.expireTimeUTC	1564534800	Valid Epoch time	Expire date and time in UTC
$twcweather.alerts.issueTimeLocal	2019-07-30T03:21:00-04:00		Alert issuance time
$twcweather.alerts.expireTimeLocal	2019-07-30T21:00:00-04:00		Expire date & time of the information in the alert message
$twcweather.alerts.onsetTimeLocal	2019-07-30T10:00:00-04:00	Usually returns null.	Onset date & time of the information in the alert message. (Canada only)
$twcweather.alerts.effectiveTimeLocal	2019-07-30T10:00:00-04:00	Usually returns null.	Effective date & time of the information in the alert message

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)
$twcweather.alerts.latitude	40.01	Centroid latitude of a location where the event occurs
$twcweather.alerts.longitude	-75.01	Centroid longitude of a location where the event occurs

Category

The category description of the subject event of the alert message.

Each dataPoint below must begin with $twcweather.alerts.categories. (Such as: $twcweather.alerts.categories.categoryCode although $twcweather.alerts.categories[0].categoryCode may work as well)

categoryCode	category	More Details	Notes
1	Geo	Geophysical (inc. landslide)	??
2	Met	Meteorological (inc. flood)	94% of responses seen
3	Safety	General emergency and public safety	??
4	Security	Law enforcement, military, homeland and local/private security	??
5	Rescue	Rescue and recovery	??
6	Fire	Fire suppression and rescue	??
7	Health	Medical and public health	??
8	Env	Pollution and other environmental	??
9	Transport	Public and private transportation	??
10	Infra	Utility, telecommunication, other non-transport infrastructure	??
11	CBRNE	Chemical, Biological, Radiological, Nuclear or High-Yield Explosive threat or attack	??
12	Other	Other events	Civil Emergency, Child Abduction

.

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, 2017-10-07T21:30:00-05:00	??
$twcweather.alerts.flood.floodCrestTimeLocalTimeZone	null, EDT	??
$twcweather.alerts.flood.floodEndTimeLocal	null, 2017-10-07T23:30:00-05:00	??
$twcweather.alerts.flood.floodEndTimeLocalTimeZone	null, EDT	??
$twcweather.alerts.flood.floodLocationId	00000, AFBI2	Any valid NWS flood location identifier
$twcweather.alerts.flood.floodLocationName	"N/A", "White River at Apache Tailwater"	Any valid NWS flood location identifier
$twcweather.alerts.flood.floodStartTimeLocal	null, 2017-10-07T20:30:00-05:00	Flood start date time
$twcweather.alerts.flood.floodStartTimeLocalTimeZone	null, EDT	Flood start date time zone abbreviation

floodImmediateCause

When there is an alert for possible flooding, then these extra dataPoints may appear:

Column 1 represents $twcweather.alerts.flood.floodImmediateCauseCode

1	$twcweather.alerts.flood.floodImmediateCause	Notes
ER	Excessive Rainfall	Only response seen so far
SM	Snowmelt	??
RS	Rain and Snowmelt	??
DM	Dam or Levee Failure	??
IJ	Ice Jam	??
GO	Glacier-Dammed Lake Outburst	??
IC	Rain and/or Snowmelt and/or Ice Jam	??
FS	Upstream Flooding plus Storm Surge	??
FT	Upstream Flooding plus Tidal Effects	??
ET	Elevated Upstream Flow plus Tidal Effects	??
WT	Wind and/or Tidal Effects	??
DR	Upstream Dam or Reservoir Release	??
MC	Other Multiple Causes	??
OT	Other Effects	??
UU	Unknown	??

floodRecordStatus

When there is an alert for possible flooding, then these extra dataPoints may appear:

Column 1 represents $twcweather.alerts.flood.floodRecordStatusCode

1	$twcweather.alerts.flood.floodRecordStatus	Notes
OO	N/A	For areal flood warnings, areal flash flood products, and flood advisories (point & areal)
NO	??	A record flood is not expected
NR	??	Near record or record flood expected
UU	??	Flood without a period of record to compare

floodSeverity

When there is an alert for possible flooding, then these extra dataPoints may appear:

Column 1 represents $twcweather.alerts.flood.floodSeverityCode

1	$twcweather.alerts.flood.floodSeverity	Notes
N	None
0	N/A
1	Minor	??
2	Moderate	??
3	Major	??
U	Unknown	??

.

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). IE: EDT in the Summer becomes EST in the Winter

Expression	Sample value	Notes
$twcweather.alerts.expireTimeLocalTimeZone	EDT	Time Zone Abbreviation for expire time
$twcweather.alerts.effectiveTimeLocalTimeZone	EDT	Time Zone Abbreviation for effective time
$twcweather.alerts.issueTimeLocalTimeZone	EDT	Time Zone Abbreviation for issue time
$twcweather.alerts.onsetTimeLocalTimeZone	EDT, null	Time Zone Abbreviation for onset time (Canada only??)

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.officeAdminDistrict	"New York", null
$twcweather.alerts.officeAdminDistrictCode	"NY"
$twcweather.alerts.officeCode	"KOKX", "CWTO"	Issuing Office code
$twcweather.alerts.officeCountryCode	"US", "CA"	Issuing Office Country Code
$twcweather.alerts.officeName	"New York City"	Issuing Office Name
$twcweather.alerts.source	"National Weather Service", "Meteorological Service of Canada"	Originating source of alert

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"	Checksum value uniquely identifies a bulletin (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...

Note to self: Check out $twcweather.alerts.synopsis

Observations

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

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

OR

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.

.