Support for OpenCage via Lua

addresses #202

README.md

@@ -261,7 +261,7 @@ This section lists the most important options of the Recorder with their long na
 
 `--precision` overrides the compiled-in default. (See "Precision" later.)
 
-`--geokey` sets the Google API key for reverse geo lookups.  If you do more than 2500 (currently) reverse-geo requests per day, you'll need an API key for Google's geocoding service. Specify that here.
+`--geokey` sets the Google API key for reverse geo lookups.  If you do more than 2500 (currently) reverse-geo requests per day, you'll need an API key for Google's geocoding service. Specify that here. (Note: these limits have changed in May 2018; make sure to check Google's Map Project documentation before using this; we recommend using [OpenCage](doc/OPENCAGE.md) as reverse geo-encoder.)
 
 `--debug` enables a bit of additional debugging on stderr.
 

contrib/opencage.lua

@@ -0,0 +1,35 @@
+-- https://github.com/nmdguerreiro/lua-opencage-geocoder
+-- luarocks install lua-opencage-geocoder
+local geocoder = require "opencage.geocoder"
+local gc = geocoder.new({
+	key = os.getenv("OPENCAGE_APIKEY")
+})
+
+function otr_init()
+end
+
+function otr_exit()
+end
+
+function otr_hook(topic, _type, data)
+end
+
+function otr_revgeo(topic, user, device, lat, lon)
+	print("OpenCAge lookup for " .. lat .. ", " .. lon)
+
+	local d = {}
+
+	params = {
+		abbrv = 1,
+		no_record = 1
+	}
+	local res, status, err = gc:reverse_geocode(lat, lon, params)
+	if status == 200 then
+		d['addr'] = res.results[1].formatted
+	else
+		print("OpenCage lookup returned status=" .. status)
+	end
+
+	d['_rec']       = true		-- store in .REC file
+	return d
+end

doc/OPENCAGE.md

@@ -0,0 +1,22 @@
+# OpenCage
+
+We now (since May 2018) recommend using [OpenCage](https://geocoder.opencagedata.com) as reverse geo-coding provider: their [pricing](https://geocoder.opencagedata.com/pricing) is attractive and they currently offer a free tier which allows up to 2,500 requests per day.
+
+In order to use OpenCage with the Recorder, proceed as follows:
+
+1. Make sure you've built the Recorder with support for Lua
+1. Install the required Lua modules:
+```bash
+luarocks install lua-opencage-geocoder
+```
+2. Obtain an [OpenCage API key](https://geocoder.opencagedata.com/pricing), and make careful note of that.
+3. Before launching the Recorder, export the API key to the Recorder's environment
+```bash
+export OPENCAGE_APIKEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+```
+4. Add a Lua script for the Recorder, which looks like [our example OpenCage Lua script](contrib/opencage.lua)
+5. Launch the Recorder using something along these lines:
+```bash
+ot-recorder --lua-script opencage.lua 'owntracks/#'
+```
+6. Note that you'll currently still require a Google Maps browser API key for the actual maps.