V2.5 docs

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
@@ -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.
@@ -112,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:
@@ -775,7 +843,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.

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,71 @@ 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. 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
 ```
 	GET https://api.pirateweather.net/forecast/1234567890abcdefghijklmnopqrstuvwxyz/45.42,-74.30?&units=ca
@@ -244,7 +309,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"
 	   }
 	}
 ```
@@ -553,27 +618,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).

docs/changelog.md

@@ -2,7 +2,14 @@
 
 For a RSS feed of these changes, subscribe using this link: <https://github.com/alexander0042/pirateweather/commits/main.atom>.
 
-???+ note "Version 2.4"
+???+ note "Version 2.5"
+
+	* January, 2025, API Version 2.5
+		* 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)
+
+??? 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).

docs/index.md

@@ -43,14 +43,12 @@ Alternatively, I also have a GitHub Sponsorship page set up on my [profile](http
 
 <iframe src="https://github.com/sponsors/alexander0042/card" title="Sponsor alexander0042" height="225" width="600" style="border: 0;"></iframe>
 
-## Recent Updates- Fall 2024
-Up to version 2.4! 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).
+## 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 (<https://orcid.org/0000-0003-4725-3251>). 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 (<http://alexanderrey.ca/>), and I had been looking for a project to learn Python on, so this seemed like the perfect opportunity!

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.