add README.md

1 files changed, 44 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..95e9bc3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,44 @@
+meteor.py
+=========
+
+A simple script written in about 4 hours that gets the weather. wttr.in was giving somewhat inaccurate results and
+we found the [National Weather Service API](https://www.weather.gov/documentation/services-web-api) one day, so we
+figured that we ought as well spend a little bit of time and have some fun with it.
+
+Usage
+-----
+
+`meteor.py lat lon`
+
+`lat` and `lon` are the latitude & longitude of a particular point in the United States (e.g. 38.57 -121.48 is within Sacramento, California)
+
+TODO / Issues
+-------------
+
+- Geocoding would make this a little more usable. [NWS lists several potential services](https://weather-gov.github.io/api/general-faqs#geocoding)
+- Round decimals to 4 places ourselves to avoid errors
+- Cache responses appropriately (the API uses HTTP caching headers correctly, TBA if we want to drop in requests-cache or do it ourselves)
+- Use the /gridpoints/gridId/gridX,gridY endpoint to generate our own forecast with things like probabilityOfPrecipitation
+- Fancy output like wttr.in
+- Display the names of the zones (requires extra API calls - cacheable for a long duration, though)
+- Shorter alert descriptions (`parameters.NWSheadline[0]` instead of `description`)
+- Work around known issues in the NWS API:
+    - retry when gridpoints 500s
+    - reduce gridX and gridY by 1 for AFC (AER/ALU), AFG, AJK, BOX, CAE, DLH, FSD, HGX, HNX, LIX, LWX, MAF, MFR, MLB, MRX, MTR, PIH offices/gridIds
+- Gracefully handle cache keys that include '/'
+
+Reference
+---------
+
+- [National Weather Service API Documentation](https://www.weather.gov/documentation/services-web-api)
+- [NWS OpenAPI](https://api.weather.gov/openapi.json)
+
+License
+-------
+
+(c) 2022 Starfall. All rights reserved.
+
+- "It shall be permissible to make quotations from a work ... provided that their making is
+  compatible with fair practice." - Berne Convention
+- Information wants to be free.
+- Be gay, do crimes.