recorder/doc/OPENCAGE.md

OpenCage

We now (since May 2018) recommend using OpenCage as reverse geo-coding provider: their pricing is attractive and they currently offer a free tier which allows up to 2,500 requests per day.

Use the OpenCage API in Recorder simply by setting the --geokey option to the string "opencage:" with your API key concatenated to it. (Without the substring opencage: the Recorder falls back to using Google in order to maintain backwards-compatibility.)

--geokey "opencage:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Be aware that the Recorder uses the following settings: no_record=1&limit=1. OpenCage documents the first as meaning it will not log the request, and that protects your privacy.

With Lua

There was experimental Lua support for OpenCage, but this is no longer necessary; we keep the following for historic purposes only.

In order to use OpenCage with the Recorder using Lua, proceed as follows:

1. Make sure you've built the Recorder with support for Lua
2. Install the required Lua modules:

luarocks install lua-opencage-geocoder

2. Obtain an OpenCage API key, and make careful note of that.
3. Before launching the Recorder, export the API key to the Recorder's environment

export OPENCAGE_APIKEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

4. Add a Lua script for the Recorder, which looks like our example OpenCage Lua script
5. Launch the Recorder using something along these lines:

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.