search

jdemaeyer / brightsky

JSON API for DWD's open weather data.
https://brightsky.dev/
MIT License
299 stars 18 forks source link

DWD Alerts #106

Closed jwillmer closed 1 year ago

jwillmer commented 3 years ago

Is there a way to also get the DWD weather alerts? I found many services that offer an API to the weather or the alerts from DWD but none of them are offering both. Any specific reason this project does not offer it (or I don't find it)?

jdemaeyer commented 3 years ago

Heyho @jwillmer!

There is no specific reason other than that those warnings were out-of-scope for our initial release and no one has expressed interest in them since (plus now that the funding period is over I have limited time to work on Bright Sky).

Could you post an example request/response from one of those APIs that offer warnings? Judging from https://www.dwd.de/DWD/warnungen/warnapp/json/warnings.json it seems that they wouldn't fit too well into our existing timestamp-focused database/API structure and will require coming up with new tables and API endpoints (but maybe we can get away with just adding a new key to our weather response...), and with a way to figure out whether the requested location falls into a warning region (instead to just grabbing the nearest available measurement like we do for weather).

jwillmer commented 3 years ago

Request/response for this API is very basic. As you can see in the link they support different formats (CAP, SMS, TXT). They also offer filters for locations (areas) but I'm not sure how they work. Documentation is not very good 😞 Additionally they also offer German or English alert text. So this would be something to keep in mind when using the endpoint (filter, additional option).

I found the following repositories that work with alerts and might be the best location to get more information about the API:

jwillmer commented 3 years ago

@jdemaeyer I was thinking about it and came to the following conclusion:

I think you should not try to add the alerts in the current API. It is anyway a bad design to pull for alerts. I think the appropriate implementation would be an API to subscribe to alerts from an area. And then get notified (POST request) when an alert, matching the area.

API could look like this:

/// <summary>
/// Webhook endpoint for alerts
/// </summary>
/// <param name="point">Geo location to monitor</param>
/// <param name="webhook">Url to call when an alert was received</param>
/// <param name="km">Alert radius to include</param>
/// <returns>Webhook id</returns>
[HttpPost]
string SubscribeToAlerts(GeoPoint point, Uri webhook, int km = 10);

/// <summary>
/// Unsubscribe from alerts
/// </summary>
/// <param name="id">The subscription id</param>
[HttpDelete]
void UnsubscribeFromAlerts(string id);

Additionally I would add some rules to auto unsubscribe inactive subscribers. Determining inactive could be done by:

Months and alert count needs some additional logic in case we did not get any alerts in the last 6 months we should not remove a subscription. Or if we send 50 alerts in the last week we might like to remove the endpoint earlier.

jwillmer commented 3 years ago

Referencing repo with similar intentions: https://github.com/earthobservations/wetterdienst/issues/342

jdemaeyer commented 3 years ago

Thanks for all the input! I think the alerts would definitely be a great feature for Bright Sky.

IMHO a webhook-based approach would add too much new complexity (like the user/subscription management you outline above, post-update hooks inside Bright Sky, and making sure alerts are sent out reliably) and exclude a lot of users (anyone who can't supply a publicly available endpoint), so I'm very reluctant to go down that route. Such a big departure from our current architecture seems better suited for a separate project which internally polls the alerts from Bright Sky.

Even staying within our polling structure leaves us with the other big (and computation-heavy) problem of determining if a requested lat/lon is inside an alert area. However, we may get away with simply assigning any alert to the center of its area, and then using the distance-based approach that we also use for weather records. (I have no doubt people who know more about geocomputation than I do are throwing their hands up in horror right now. :))

Our roadmap could then be roughly as follows:

That being said, I can't promise anything concerning when I'll find time to tackle this :/

jwillmer commented 3 years ago

As far as I know the alerts are already assigned to a region. They are not location based. And another good thing to know is that the system will also receive preplaned alerts. Like: "Glazed frost between 5 and 10 AM" that will be issued the evening before (with start/end timestamp).

ubergesundheit commented 3 years ago

Check out https://dwd.api.bund.dev/

MartinHennrich commented 2 years ago

It would be really convenient to send a ZIP code to the API and receive warnings for it.

jdemaeyer commented 1 year ago

Weather alerts landed in Bright Sky with v2.0.6! :tada:

This is currently in experimental feature and subject to change, below is a quick-n-dirty documentation while I work on the proper one.

Endpoint

https://api.brightsky.dev/alerts

Parameters

There are currently four parameters:

You must supply either warn_cell_id or both lat and lon.

Example

Current alerts for Göttingen: https://api.brightsky.dev/alerts?lat=51.55&lon=9.9

Response:

{
  "alerts": [
    {
      "id": 75,
      "alert_id": "2.49.0.0.276.0.DWD.PVW.1687514160000.20999218-5d5e-4761-b271-6c243f695568",
      "effective": "2023-06-23T09:56:00+00:00",
      "onset": "2023-06-23T09:56:00+00:00",
      "expires": "2023-06-23T12:00:00+00:00",
      "category": "met",
      "response_type": "prepare",
      "urgency": "immediate",
      "severity": "moderate",
      "certainty": "likely",
      "event_code": 61,
      "event_en": "heavy rain",
      "event_de": "STARKREGEN",
      "headline_en": "Official WARNING of HEAVY RAIN",
      "headline_de": "Amtliche WARNUNG vor STARKREGEN",
      "description_en": "There is a risk of heavy rain (Level 2 of 4).\nPrecipitation amounts: 20-35 l/mÂČ/6h",
      "description_de": "Es tritt Starkregen auf. Dabei werden Niederschlagsmengen zwischen 20 l/mÂČ und 35 l/mÂČ in 6 Stunden erwartet.",
      "instruction_en": "NOTE: Be aware of the following possible dangers: The downpours can cause temporary traffic disruption.",
      "instruction_de": "ACHTUNG! Hinweis auf mögliche Gefahren: WÀhrend des Platzregens sind kurzzeitig Verkehrsbehinderungen möglich."
    },
    {
      "id": 28,
      "alert_id": "2.49.0.0.276.0.DWD.PVW.1687470000000.fe90b61b-3755-4efb-8eda-b161251da9f7",
      "effective": "2023-06-22T21:40:00+00:00",
      "onset": "2023-06-23T06:00:00+00:00",
      "expires": "2023-06-23T14:00:00+00:00",
      "category": "met",
      "response_type": "prepare",
      "urgency": "immediate",
      "severity": "minor",
      "certainty": "likely",
      "event_code": 51,
      "event_en": "wind gusts",
      "event_de": "WINDBÖEN",
      "headline_en": "Official WARNING of WIND GUSTS",
      "headline_de": "Amtliche WARNUNG vor WINDBÖEN",
      "description_en": "There is a risk of wind gusts (level 1 of 4).\nMax. gusts: ~ 55 km/h; Wind direction: west then north-west; Increased gusts: in exposed locations ~ 65 km/h",
      "description_de": "Es treten Windböen mit Geschwindigkeiten um 55 km/h (15 m/s, 30 kn, Bft 7) anfangs aus westlicher, spÀter aus nordwestlicher Richtung auf. In exponierten Lagen muss mit Sturmböen um 65 km/h (18 m/s, 35 kn, Bft 8) gerechnet werden.",
      "instruction_en": null,
      "instruction_de": null
    }
  ],
  "location": {
    "warn_cell_id": 803159016,
    "name": "Stadt Göttingen",
    "name_short": "Göttingen",
    "district": "Göttingen",
    "state": "Niedersachsen",
    "state_short": "NI"
  }
}
Notes
Additional resources
 

/cc @krystofbe

jdemaeyer commented 1 year ago

Closing as this is now officially part of the API :)

jdemaeyer commented 1 year ago

Demo of an interactive alerts map: live demo, source