$twcweather.alerts
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.
Contents
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.disclaimer
|
null
|
Disclaimer for data |
$twcweather.alerts.eventTrackingNumber
|
0003
|
4 digit number or a checksum |
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
|
2017-10-07T21:30:00-05:00
|
?? |
$twcweather.alerts.flood.floodCrestTimeLocalTimeZone
|
EDT
|
?? |
$twcweather.alerts.flood.floodEndTimeLocal
|
2017-10-07T23:30:00-05:00
|
?? |
$twcweather.alerts.flood.floodEndTimeLocalTimeZone
|
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
|
2017-10-07T20:30:00-05:00
|
Flood start date time |
$twcweather.alerts.flood.floodStartTimeLocalTimeZone
|
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
|
Most common response |
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 |
|---|---|---|
NO
|
A record flood is not expected
|
?? |
NR
|
Near record or record flood expected
|
?? |
UU
|
Flood without a period of record to compare
|
?? |
OO
|
For areal flood warnings, areal flash flood products, and flood advisories (point and areal)
|
?? |
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
|
?? |
.
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:
- phenomena (Phenomena code of an event)
- productIdentifier (Refer Inbound PIL/Event Tab)
- eventTrackingNumber (4 digit number or a checksum)
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?
|
Cancel
|
?? |
| 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 |
7?
|
Assess
|
Evaluate the information in this message. (This value SHOULD NOT be used in public warning applications.) |
8?
|
AllClear
|
The subject event no longer poses a threat or concern and any follow on action is described in <instruction> |
9?
|
None
|
No action recommended |
| severityCode | severity | Notes |
1?
|
Extreme
|
?? |
2
|
Severe
|
|
3
|
Moderate
|
|
4
|
Minor
|
|
5?
|
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 |
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, 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
|
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",
|
Mixed case location name |
$twcweather.alerts.areaTypeCode
|
"C" = County,
|
Type of location (Usually returns Z) |
Category
The category description of the subject event of the alert message.
| categoryCode | category | Notes |
|---|---|---|
1
|
Geo
|
Geophysical (inc. landslide) |
2
|
Met | Meteorological (inc. flood) ... The most common response |
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 |
.
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 | 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.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 |
$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.
Note to self:
Check out:
$twcweather.alerts.synopsis (Brief summary)
$twcweather.alerts.instruction
.
