Ends vs. expires in alerts endpoint

[netbymatt]

Can you please describe how to evaluate the effective and ends fields in the /alerts endpoints? If we look at this winter weather advisory https://api.weather.gov/alerts/NWS-IDP-PROD-3907973-3326361 the expires time appears to be roughly when the snow is expected to start falling, and the ends time is the end of the alert which matches the text in the description field.

Looking at a flood warning https://api.weather.gov/alerts/NWS-IDP-PROD-3907292-3326007 there is no ends time, only an expires time.

Ultimately, I'm looking for a set of rules by which to determine what alerts to show to a user and which are no longer relevant. Note that I'm pulling the list of alerts to parse from https://api.weather.gov/alerts?status=actual&point=x,y
I understand that I could use /alerts/active to filter these automatically, but I feel that someone following a fast moving supercell would appreciate the recent history of warnings that have been issued in the area as a way to better understand the storm as it moves through their area. Those "recent history" would be marked differently in the user interface.

[StephenClouse]

expires and ends correspond to the Product Expiration Time and Event Ending Time, respectively, as defined in NWS Directive 10-1701 § 3.9.2.

Product Expiration Time is when the product message expires and a message containing updated information about the event should be expected before this time. This is generally only applicable to long-duration products.

Event Ending Time is when the event is no longer valid (when the warned conditions are no longer expected to occur).

In your example of the winter weather advisory, the event may be expected to last 48 hours (the event ending time) but there will be multiple messages across this period with updates to the situation. The product expiration time indicates when these messages should be considered out-of-date.

In the case of the flood warning these are often issued "until further notice"; these will have a null ending time since they are indefinite warnings for long-term flooding.

The /alerts/active endpoint automatically removes out-of-date products once an updated one has been issued. This is indicated by the references property of the alert in the CAP XML and JSON (an update product will refer to the older product it replaces). We additionally expose a replacedBy property in JSON to show the reciprocal of this link. If you are wanting to trace the complete chain of history of an event, these are the properties to go exploring through.

[netbymatt]

That's exactly the information I was looking for. Can you add a link to NWS Directive 10-1701 somewhere in the FAQ or other documents on this site? Browsing though it has cleared up a lot of other questions that I've had regarding the data in the API. I'm sure it would benefit others too.

[jfbauer432]

This morning, when doing an /alerts/active status=actual, point=mylat,mylon and I am getting 3 freeze watches.

https://api.weather.gov/alerts/NWS-IDP-PROD-4200437-3550625
https://api.weather.gov/alerts/NWS-IDP-PROD-4200438-3550626
https://api.weather.gov/alerts/NWS-IDP-PROD-4200438-3550627

The first (..625) seems to be a bit outside the area. The lat/lon of the query is in zone MDZ503. Do you know why this one got included when the alert doesn't mention that zone? The county is split between MDZ503 and MDZ504. Does that have something to do with it?

---

The second two (...626 and ...627) are mostly identical: one being an update of the other. The update does have references, but they refer to yet other freeze watches. The referred alerts do have replacedBy fields as mentioned in the Nov 12 response above, but NWS-IDP-PROD-4200438-3550626 does not. Should that old one (626) have even been included?

Diff of the 2nd and 3rd alerts

-            "id": "https://api.weather.gov/alerts/NWS-IDP-PROD-4200438-3550626",
+            "id": "https://api.weather.gov/alerts/NWS-IDP-PROD-4200438-3550627",
             "type": "Feature",
             "geometry": null,
             "properties": {
                 "@id": "https://api.weather.gov/alerts/NWS-IDP-PROD-4200438-3550
-626",
+627",
                 "@type": "wx:Alert",
-                "id": "NWS-IDP-PROD-4200438-3550626",
+                "id": "NWS-IDP-PROD-4200438-3550627",
                 "areaDesc": "Frederick; Nelson; Western Loudoun; Albemarle; Carr
 oll; Greene; Northern Fauquier; Madison; Eastern Loudoun; Northwest Montgomery; 
 Southern Fauquier; Northwest Howard; Orange; Rappahannock; Culpeper",
@@ -61,14 +60,28 @@
                     "https://api.weather.gov/zones/forecast/VAZ040",
                     "https://api.weather.gov/zones/forecast/VAZ051"
                 ],
-                "references": [],
+                "references": [
+                    {
+                        "@id": "https://api.weather.gov/alerts/NWS-IDP-PROD-4199
+415-3549828",
+                        "identifier": "NWS-IDP-PROD-4199415-3549828",
+                        "sender": "w-nws.webmaster@noaa.gov",
+                        "sent": "2020-05-07T14:16:00-04:00"
+                    },
+                    {
+                        "@id": "https://api.weather.gov/alerts/NWS-IDP-PROD-4200167-3550378",
+                        "identifier": "NWS-IDP-PROD-4200167-3550378",
+                        "sender": "w-nws.webmaster@noaa.gov",
+                        "sent": "2020-05-07T22:59:00-04:00"
+                    }
+                ],
                 "sent": "2020-05-08T03:30:00-04:00",
                 "effective": "2020-05-08T03:30:00-04:00",
-                "onset": "2020-05-10T00:00:00-04:00",
+                "onset": "2020-05-09T00:00:00-04:00",
                 "expires": "2020-05-08T11:30:00-04:00",
-                "ends": "2020-05-10T10:00:00-04:00",
+                "ends": "2020-05-09T10:00:00-04:00",
                 "status": "Actual",
-                "messageType": "Alert",
+                "messageType": "Update",
                 "category": "Met",
                 "severity": "Severe",
                 "certainty": "Possible",
@@ -76,7 +89,7 @@
                 "event": "Freeze Watch",
                 "sender": "w-nws.webmaster@noaa.gov",
                 "senderName": "NWS Baltimore MD/Washington DC",
-                "headline": "Freeze Watch issued May 8 at 3:30AM EDT until May 10 at 10:00AM EDT by NWS Baltimore MD/Washington DC",
+                "headline": "Freeze Watch issued May 8 at 3:30AM EDT until May 9 at 10:00AM EDT by NWS Baltimore MD/Washington DC",
                 "description": "* WHAT...For the first Freeze Watch, sub-freezing temperatures\nas low as 31 possible. For the second Freeze Watch, sub-\nfreezing temperatures as low as 31 possible.\n\n* WHERE...Portions of central and north central Maryland and\ncentral, northern and northwest Virginia.\n\n* WHEN...For the first Freeze Watch, from late tonight through\nSaturday morning. For the second Freeze Watch, from late\nSaturday night through Sunday morning.\n\n* IMPACTS...Frost and freeze conditions could kill crops, other\nsensitive vegetation and possibly damage unprotected outdoor\nplumbing.",
                 "instruction": "Take steps now to protect tender plants from the cold. To prevent\nfreezing and possible bursting of outdoor water pipes they should\nbe wrapped, drained, or allowed to drip slowly. Those that have\nin-ground sprinkler systems should drain them and cover above-\nground pipes to protect them from freezing.",
                 "response": "Prepare",
@@ -85,7 +98,7 @@
                         "FREEZE WATCH REMAINS IN EFFECT FROM LATE TONIGHT THROUGH SATURDAY MORNING... ...FREEZE WATCH IN EFFECT FROM LATE SATURDAY NIGHT THROUGH SUNDAY MORNING"
                     ],
                     "VTEC": [
-                        "/O.NEW.KLWX.FZ.A.0007.200510T0400Z-200510T1400Z/"
+                        "/O.CON.KLWX.FZ.A.0006.200509T0400Z-200509T1400Z/"
                     ],
                     "PIL": [
                         "LWXNPWLWX"
@@ -96,8 +109,8 @@
                         "NWEM"
                     ],
                     "eventEndingTime": [
-                        "2020-05-10T10:00:00-04:00"
+                        "2020-05-09T10:00:00-04:00"
                     ]
                 }
             }

[jfbauer432]

Ah, I think I see what is happening for the two alerts (...626 and ...627). They are NOT related, just different watches issued for different dates. The fact the one was marked as an update made me think it was related to the other as they were so similar.