From 0ea420aa578f89cfd7e398bbc4340eeafb3a21f3 Mon Sep 17 00:00:00 2001 From: Kev Date: Wed, 4 Dec 2024 14:56:11 -0500 Subject: [PATCH 1/6] Start V2.5 docs --- PW_OpenAPI.yaml | 4 ++-- docs/API.md | 23 +++++++++++++---------- docs/changelog.md | 7 ++++++- docs/index.md | 8 ++------ docs/roadmap.md | 2 +- 5 files changed, 24 insertions(+), 20 deletions(-) diff --git a/PW_OpenAPI.yaml b/PW_OpenAPI.yaml index 6c15b31..6775343 100644 --- a/PW_OpenAPI.yaml +++ b/PW_OpenAPI.yaml @@ -1,6 +1,6 @@ openapi: 3.1.0 info: - version: "2.4.1" + version: "2.5.0" title: Pirate Weather API description: Pirate Weather provides an open, free, and documented source of government weather data. termsOfService: https://pirate-weather.apiable.io/terms @@ -775,7 +775,7 @@ components: version: type: string description: The version of Pirate Weather used to generate the forecast. - example: V2.4.1 + example: V2.5.0 sourceIDX: type: object description: The X, Y coordinate and the lat/long coordinate for each model used to generate the forecast. Only returned when version>2. diff --git a/docs/API.md b/docs/API.md index 2785dbb..084e9b1 100644 --- a/docs/API.md +++ b/docs/API.md @@ -244,7 +244,7 @@ If `version=2` is included fields which were not part of the Dark Sky API will b }, "nearest-station": 0, "units": "ca", - "version": "V2.4.1" + "version": "V2.5.0" } } ``` @@ -335,6 +335,9 @@ Added as part of the V1.0 release, this parameter removes some of the data block * `daily` * `alerts` +### Language +Added as part of the V2.5 release, this parameter allows you to sepecify what language the text summaries use. + ## Response ``` GET https://timemachine.pirateweather.net/forecast/1234567890abcdefghijklmnopqrstuvwxyz/45.42,-74.30,1654056000?&units=ca @@ -553,27 +556,27 @@ The daily icon is calculated between 4:00 am and 4:00 am local time. The algorit * If precipitation accumulation is greater than 0.02 mm, then the precipitation type. * If visibility is less than 1 km, then `fog`. -* If winds are greater than 10 m/s, then `wind`. +* If winds are greater than 6.7056 m/s, then `wind`. * If cloud cover is greater than 75%, then `cloudy`. -* If cloud cover is greater than 37.5% and less than 75%, then `partly-cloudy-day` or `partly-cloudy-night`. -* If cloud cover is less than 37.5%, then `clear`. +* If cloud cover is greater than 37.5% and less than 87.5%, then `partly-cloudy-day` or `partly-cloudy-night`. +* If cloud cover is less than 87.5%, then `clear`. ##### Hourly: * If precipitation probability is greater than 30% and accumulation is greater than 0.02 mm, then the precipitation type. * If visibility is less than 1 km, then `fog`. -* If winds are greater than 10 m/s, then `wind`. -* If cloud cover is greater than 75%, then `cloudy`. -* If cloud cover is greater than 37.5% and less than 75%, then `partly-cloudy-day` or `partly-cloudy-night`. +* If winds are greater than 6.7056 m/s, then `wind`. +* If cloud cover is greater than 87.5%, then `cloudy`. +* If cloud cover is greater than 37.5% and less than 87.5%, then `partly-cloudy-day` or `partly-cloudy-night`. * If cloud cover is less than 37.5%, then `clear`. ##### Daily: * If max probability is greater than 30% in any hour and total accumulation is greater than 1 mm, then precipitation type. * Type is based on the most common (modal) precipitation type. * If average visibility is less than 1 km, then `fog`. -* If average wind speed is greater than 10 m/s, then `wind`. -* If average cloud cover is greater than 75%, then `cloudy`. -* If average cloud cover is greater than 37.5% and less than 75%, then `partly-cloudy-day`. +* If average wind speed is greater than 6.7056 m/s, then `wind`. +* If average cloud cover is greater than 87.5%, then `cloudy`. +* If average cloud cover is greater than 37.5% and less than 87.5%, then `partly-cloudy-day`. * If average cloud cover is less than 37.5%, then `clear`. For additional details, see [issue #3](https://github.com/alexander0042/pirateweather/issues/3). diff --git a/docs/changelog.md b/docs/changelog.md index 6a8aab8..8511f05 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -2,7 +2,12 @@ For a RSS feed of these changes, subscribe using this link: . -???+ note "Version 2.4" +???+ note "Version 2.5" + + * December 5, 2024, API Version 2.5 + * Added support for the Dark Sky translation module as per [issue #152](https://github.com/Pirate-Weather/pirateweather/issues/152). + +??? note "Version 2.4" * November 26, 2024, API Version 2.4.1 * Fixed unit issues that occured when fixing the data point value issue as per [issue #360](https://github.com/Pirate-Weather/pirateweather/issues/360). diff --git a/docs/index.md b/docs/index.md index 6a29fb7..971dc29 100644 --- a/docs/index.md +++ b/docs/index.md @@ -44,13 +44,9 @@ Alternatively, I also have a GitHub Sponsorship page set up on my [profile](http ## Recent Updates- Fall 2024 -Up to version 2.4! As always, details are available in the [changelog](https://pirateweather.net/en/latest/changelog/). +Up to version 2.5! As always, details are available in the [changelog](https://pirateweather.net/en/latest/changelog/). -* First Official Open Source Release! Details in the new [Pirate Weather Code](https://github.com/Pirate-Weather/pirate-weather-code) repository, but starting today, you can see exactly how the data is processed, and even host your own instance of Pirate Weather! Contributions are welcome, so come check it out. Addresses the second oldest outstanding [issue #11](https://github.com/Pirate-Weather/pirateweather/issues/11). -* Fixed a datetime bug per [issue #330](https://github.com/Pirate-Weather/pirate-weather-ha/issues/330). -* Corrects the Apparent Temperature calculation per [issue #363](https://github.com/Pirate-Weather/pirateweather/issues/363). -* Changed the behaviour of new lines in NWS per [issue #367](https://github.com/Pirate-Weather/pirateweather/issues/367). -* Fixed issues where data points could return values outside of expected range as per [issue #360](https://github.com/Pirate-Weather/pirateweather/issues/360). +* Added support for the Dark Sky translation module as per [issue #152](https://github.com/Pirate-Weather/pirateweather/issues/152). ## Background This project started from two points: as part of my [PhD](https://coastlines.engineering.queensu.ca/dunexrt), I had to become very familiar with working with NOAA forecast results (). Separately, an old tablet set up as a "Magic Mirror,” and was using a [weather module](https://github.com/jclarke0000/MMM-DarkSkyForecast) that relied on the Dark Sky API, as well as my [Home Assistant](https://www.home-assistant.io/) setup. So when I heard that it was [shutting down](https://blog.darksky.net/dark-sky-has-a-new-home/), I thought, "I wonder if I could do this.” Plus, I love learning new things (), and I had been looking for a project to learn Python on, so this seemed like the perfect opportunity! diff --git a/docs/roadmap.md b/docs/roadmap.md index d291390..616945b 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -1,5 +1,5 @@ # Roadmap -1. Text summaries and translations +1. Text summaries * Based on the [existing repository](https://github.com/alexander0042/translations). 2. Weather maps from new Zarr datafiles. 3. Add in alerts for Canada/ EU/ other. From 8500581ce69ac77022a32912b9bc91746018d1f2 Mon Sep 17 00:00:00 2001 From: Kev Date: Wed, 4 Dec 2024 15:00:56 -0500 Subject: [PATCH 2/6] Move the lang parameter --- docs/API.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/API.md b/docs/API.md index 084e9b1..641f7e6 100644 --- a/docs/API.md +++ b/docs/API.md @@ -14,7 +14,7 @@ All request attributes are contained within the URL. Request headers are not par ### Request Parameters The forecast request can be extended in several ways by adding parameters to the URL. The full set of URL options is: ``` -https://api.pirateweather.net/forecast/[apikey]/[latitude],[longitude],[time]?exclude=[excluded]&units=[unit]&extend=[hourly]&version=[2] +https://api.pirateweather.net/forecast/[apikey]/[latitude],[longitude],[time]?exclude=[excluded]&units=[unit]&extend=[hourly]&version=[2]&lang=[lang] ``` #### API Key @@ -94,6 +94,9 @@ If `extend=hourly` is included, hourly data for the next 168 hours will be inclu #### Version If `version=2` is included fields which were not part of the Dark Sky API will be included. These fields are `smoke`, `smokeMax`, `smokeMaxTime`, `fireIndex`, `fireIndexMax`, `fireIndexMaxTime`, `liquidAccumulation`, `snowAccumulation`, `iceAccumulation`, `dawnTime` and `duskTime`. It also includes `nearestStormDistance` and `nearestStormBearing` to each of the hourly blocks and `sourceIDX` where you can see the X/Y and lat/long coordinate for each returned model. +### Language +Added as part of the V2.5 release, this parameter allows you to sepecify what language the text summaries use. + ### Example ``` GET https://api.pirateweather.net/forecast/1234567890abcdefghijklmnopqrstuvwxyz/45.42,-74.30?&units=ca @@ -335,9 +338,6 @@ Added as part of the V1.0 release, this parameter removes some of the data block * `daily` * `alerts` -### Language -Added as part of the V2.5 release, this parameter allows you to sepecify what language the text summaries use. - ## Response ``` GET https://timemachine.pirateweather.net/forecast/1234567890abcdefghijklmnopqrstuvwxyz/45.42,-74.30,1654056000?&units=ca From 5c9f56d54133d8dafa3d4336c3a4ed368f8ce10b Mon Sep 17 00:00:00 2001 From: Kev Date: Thu, 5 Dec 2024 18:56:27 -0500 Subject: [PATCH 3/6] Add available languages to docs/OpenAPI --- PW_OpenAPI.yaml | 60 +++++++++++++++++++++++++++++++++++++++++++++- docs/API.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 122 insertions(+), 2 deletions(-) diff --git a/PW_OpenAPI.yaml b/PW_OpenAPI.yaml index 6775343..96e87b7 100644 --- a/PW_OpenAPI.yaml +++ b/PW_OpenAPI.yaml @@ -49,9 +49,67 @@ paths: type: string - name: lang in: query - description: Not presently implemented. Change the forecast language. + description: Returns the forecast summaries in the desired language. schema: type: string + enum: + - ar + - az + - be + - bg + - bn + - bs + - ca + - cs + - cy + - da + - de + - el + - en + - eo + - es + - et + - fa + - fi + - fr + - ga + - gd + - he + - hi + - hr + - hu + - id + - is + - it + - ja + - ka + - kn + - ko + - kw + - lv + - ml + - mr + - nl + - no + - pa + - pl + - pt + - ro + - ru + - sk + - sl + - sr + - sv + - ta + - te + - tet + - tr + - uk + - ur + - vi + - x-pig-latin + - zh + - zh-tw - name: units in: query description: Return the weather forecast data in the requested unit system. diff --git a/docs/API.md b/docs/API.md index 641f7e6..c2f4a50 100644 --- a/docs/API.md +++ b/docs/API.md @@ -95,7 +95,69 @@ If `extend=hourly` is included, hourly data for the next 168 hours will be inclu If `version=2` is included fields which were not part of the Dark Sky API will be included. These fields are `smoke`, `smokeMax`, `smokeMaxTime`, `fireIndex`, `fireIndexMax`, `fireIndexMaxTime`, `liquidAccumulation`, `snowAccumulation`, `iceAccumulation`, `dawnTime` and `duskTime`. It also includes `nearestStormDistance` and `nearestStormBearing` to each of the hourly blocks and `sourceIDX` where you can see the X/Y and lat/long coordinate for each returned model. ### Language -Added as part of the V2.5 release, this parameter allows you to sepecify what language the text summaries use. +Added as part of the V2.5 release, this parameter allows you to sepecify what language the text summaries use. The possible values for language may be: + +??? note "Language" + + * `ar`: Arabic + * `az`: Azerbaijani + * `be`: Belarusian + * `bg`: Bulgarian + * `bn`: Bengali + * `bs`: Bosnian + * `ca`: Catalan + * `cs`: Czech + * `cy`: Welsh + * `da`: Danish + * `de`: German + * `el`: Greek + * `en`: English (which is the default) + * `eo`: Esperanto + * `es`: Spanish + * `et`: Estonian + * `fa`: Persian + * `fi`: Finnish + * `fr`: French + * `ga`: Irish + * `gd`: Gaelic + * `he`: Hebrew + * `hi`: Hindi + * `hr`: Croatian + * `hu`: Hungarian + * `id`: Indonesian + * `is`: Icelandic + * `it`: Italian + * `ja`: Japanese + * `ka`: Georgian + * `kn`: Kannada + * `ko`: Korean + * `kw`: Cornish + * `lv`: Latvian + * `ml`: Malayam + * `mr`: Marathi + * `nl`: Dutch + * `no`: Norwegian Bokmål + * `pa`: Punjabi + * `pl`: Polish + * `pt`: Portuguese + * `ro`: Romanian + * `ru`: Russian + * `sk`: Slovak + * `sl`: Slovenian + * `sr`: Serbian + * `sv`: Swedish + * `ta`: Tamil + * `te`: Telugu + * `tet: Tetum + * `tr`: Turkish + * `uk`: Ukrainian + * `ur`: Urdu + * `vi`: Vietnamese + * `x-pig-latin`: Igpay Atinlay + * `zh`: simplified Chinese + * `zh-tw`: traditional Chinese + +If you require a language not listed above, please consider contributing to the [API translation module](https://github.com/Pirate-Weather/translations). ### Example ``` From 16dc0d37287e81281b36b107a72006cf7879ef0c Mon Sep 17 00:00:00 2001 From: Kev Date: Mon, 16 Dec 2024 11:41:51 -0500 Subject: [PATCH 4/6] Add 502 Error code to OpenAPI spec --- PW_OpenAPI.yaml | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/PW_OpenAPI.yaml b/PW_OpenAPI.yaml index 96e87b7..6b3c27e 100644 --- a/PW_OpenAPI.yaml +++ b/PW_OpenAPI.yaml @@ -170,6 +170,16 @@ paths: type: string description: The error message. example: "Internal Server Error" + "502": + description: "Bad Gateway." + content: + application/json: + schema: + properties: + message: + type: string + description: The error message. + example: "An invalid response was received from the upstream server" "200": description: Success content: From 90f15edd1cfce0349de2d684fa45da38de49e641 Mon Sep 17 00:00:00 2001 From: Kev Date: Thu, 19 Dec 2024 11:52:46 -0500 Subject: [PATCH 5/6] Update V2.5 release notes/date --- docs/changelog.md | 4 +++- docs/index.md | 4 +++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/docs/changelog.md b/docs/changelog.md index 8511f05..776e302 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -4,8 +4,10 @@ For a RSS feed of these changes, subscribe using this link: -## Recent Updates- Fall 2024 +## Recent Updates- Winter 2024 Up to version 2.5! As always, details are available in the [changelog](https://pirateweather.net/en/latest/changelog/). * Added support for the Dark Sky translation module as per [issue #152](https://github.com/Pirate-Weather/pirateweather/issues/152). +* Correct 10:1 liquid snow ratio in intensity +* Zero intensity when pop==0 (https://github.com/Pirate-Weather/pirate-weather-code/issues/30) ## Background This project started from two points: as part of my [PhD](https://coastlines.engineering.queensu.ca/dunexrt), I had to become very familiar with working with NOAA forecast results (). Separately, an old tablet set up as a "Magic Mirror,” and was using a [weather module](https://github.com/jclarke0000/MMM-DarkSkyForecast) that relied on the Dark Sky API, as well as my [Home Assistant](https://www.home-assistant.io/) setup. So when I heard that it was [shutting down](https://blog.darksky.net/dark-sky-has-a-new-home/), I thought, "I wonder if I could do this.” Plus, I love learning new things (), and I had been looking for a project to learn Python on, so this seemed like the perfect opportunity! From 793f2a42ea524ef2d281f276bb5776aadc99ab4c Mon Sep 17 00:00:00 2001 From: Kev Date: Tue, 31 Dec 2024 15:13:46 -0500 Subject: [PATCH 6/6] Change release date to January --- docs/changelog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/changelog.md b/docs/changelog.md index 776e302..cef49f2 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -4,7 +4,7 @@ For a RSS feed of these changes, subscribe using this link: