From b2bb70e0a13f459e6b50c075e1be44309ba48918 Mon Sep 17 00:00:00 2001
From: Nick White <git@njw.name>
Date: Fri, 5 Feb 2021 15:12:14 +0000
Subject: Add README and usage

---
 README     | 44 ++++++++++++++++++++++++++++++++++++++++++++
 weather.go | 11 ++++++++++-
 2 files changed, 54 insertions(+), 1 deletion(-)
 create mode 100644 README

diff --git a/README b/README
new file mode 100644
index 0000000..1c706ac
--- /dev/null
+++ b/README
@@ -0,0 +1,44 @@
+# Weather - a simple tool to look up weather forecasts
+
+Weather is far faster than any browser based forecast request;
+the weather websites nowadays are so full of surveillance
+that each forecast takes around 650KB for Met Office or
+8MB for BBC. Much better to just make a single request for the
+forecast data in JSON format and display it, which is what this
+tool does.
+
+Weather currently requires a location ID for the location to look
+up. The defaults are hardcoded at the top of weather.go (bbcdefid
+and metdefid), and I encourage you to set them to your own home
+location. Otherwise, you can set the location ID with an argument
+to the program.
+
+## Finding your location ID
+
+The Met Office and BBC weather providers each use different IDs,
+but each are easy to discover.
+
+For the BBC, go to the forecast page for your location and the
+ID is the final part of the page URL, for example 2653266 is the
+location ID for Chelmsford, which has this page on the BBC website:
+https://www.bbc.com/weather/2653266. You could also look it up with
+their JSON location service, using the 'containerId' field from a
+request like this:
+https://open.live.bbc.co.uk/locator/locations?s=chelmsford&format=json
+
+For the Met Office, look up your location and use the ID from the
+'nearestSspaId' field from this URL, substituting "Chelmsford"
+for the location you want:
+https://www.metoffice.gov.uk/plain-rest-services/location-search/Chelmsford/?max=5
+
+## Notes
+
+It only makes one HTTPS request to a provider's json, using the
+same URL structures that they use on their websites.
+
+Weather doesn't use any API keys or anything silly like that,
+instead relying on the URLs the organisations use with their own
+Javascript.
+
+The Met Office unfortunately forbids requests through tor, but BBC
+allow them.
diff --git a/weather.go b/weather.go
index 1510e60..284c7ff 100644
--- a/weather.go
+++ b/weather.go
@@ -17,6 +17,12 @@ const bbcdefid = "2654675"
 const meturl = "https://www.metoffice.gov.uk/public/data/PWSCache/BestForecast/Forecast/%s.json?concise=true"
 const bbcurl = "https://weather-broker-cdn.api.bbci.co.uk/en/forecast/aggregated/%s"
 
+const usage = `Usage: weather [-s source] [-v] [locationid]
+
+weather shows the weather forecast for a location. Read the README
+for instructions on finding your location ID.
+`
+
 const mpsToMphMultiplier = 2.23693629
 
 // BBC structures
@@ -143,7 +149,6 @@ type Weather struct {
 
 var (
 	src     = flag.String("s", "bbc", "data source provider (valid options: 'bbc', 'metoffice')")
-	numdays = flag.Int("n", 2, "number of days to show")
 	verbose = flag.Bool("v", false, "verbose: show all weather details")
 )
 
@@ -217,6 +222,10 @@ func main() {
 	var resp *http.Response
 	var weather []Weather
 
+	flag.Usage = func() {
+		fmt.Fprintf(flag.CommandLine.Output(), usage)
+		flag.PrintDefaults()
+	}
 	flag.Parse()
 
 	switch *src {
-- 
cgit v1.2.3