revgeod - reverse-geo lookup daemon
revgeoc - lookup client for revgeod
revgeod [-v]
revgeoc stats|dump|lookup|kill|test
revgeod is a reverse Geo lookup daemon thing, accessible via HTTP and
backed via OpenCage, our geocoder of choice.
You’ll need an OpenCage API key exported into the environment, and you
can specify revgeod’s listen IP address and port which default to
127.0.0.1 and 8865 respectively.
The (curently hardcoded) geocache directory must exist and be writeable by the owner of the rungeod process; that’s where the LMDB database is stored. revgeod caches OpenCage’s responses (they explicitly permit this):
revgeoc is the client program which speaks HTTP to revgeod.
$ curl -i 'http://127.0.0.1:8865/rev?lat=48.85593&lon=2.29431'
HTTP/1.1 200 OK
Connection: Keep-Alive
Content-Length: 197
Content-type: application/json
Date: Wed, 31 Jan 2024 10:44:14 GMT
{
"address": {
"village": "4 r du Général Lambert, 75015 Paris, France",
"locality": "Paris",
"cc": "FR",
"s": "opencage",
"tzname": "Europe/Paris"
}
}
A second query for the same location would respond with lmdb instead
of opencage as the source, indicating it’s been cached.
All revgeod API endpoints are obtained via GET requests, and the client program revgeoc uses the same words as its commands.
The /rev endpoint is used to perform a reverse-geo lookup and cache
the positive result. This endpoint supports the following query
parameters:
lat=specify the latitude as a decimal (mandatory)lon=specify the longitude as a decimal (mandatory)app=specifies an “application” for which query statistics should be collected (see statistics below) (optional)
revgeod provides statistics on its /stats endpoint, and it collects
counters by application if the app query parameter is specified
during lookups:
{
"stats": {
"_whoami": "revgeod.c",
"_version": "0.1.8",
"stats": 8,
"requests": 13647,
"geocode_failed": 9,
"opencage": 13624,
"lmdb": 23
},
"apps": {
"recorder": 13,
"clitest": 5,
"jp0": 2
},
"uptime": 381258,
"uptime_s": "4 days, 9 hours, 54 mins",
"tst": 1544555424,
"db_path": "/usr/local/var/revgeod/geocache/",
"db_entries": 43756,
"db_size": 7532544
}
The /dump endpoint produces a full dump of the underling database in
JSON format as an array of objects, each containing a geohash, the
cached address information, and lat and lon elements which are the
latitude and longitude respectively which have been decoded from the
entries’ geohash. Note that this means that the values are not those
from which the entry originally resulted.
This endpoint expects geohash query parameter with a geohash of
precision 8; the key is looked up in the database and the JSON data or
HTTP status code 404 are returned.
Similarly to lookup, /kill also expects a geohash and removes it
from the database.
revgeod understands the following global options.
-v
show version information and exit
revgeo_verbose
if this variable is set when revgeoc starts, the program displays
received HTTP headers
OPENCAGE_APIKEY
this mandatory variable must be set in revgeod’s environment for it to
do reverse geo lookups.
REVGEO_IP
optionally sets the listen address for revgeod; defaults to
127.0.0.1 and we strongly recommend this is not changed to anything
other than a loopback address.
REVGEO_PORT
optionally sets the TCP listen port to something other than the default
8865.
REVGEO_HOST
optionally sets the hostname/address for revgeoc; defaults to
127.0.0.1 and REVGEO_PORT
$ pkg install curl
$ pkg install libmicrohttpd
$ pkg install lmdb
$ cat > config.mk <<EOF
# STATSDHOST= "127.0.0.1"
LMDB_DATABASE= "data/geocache/"
LISTEN_HOST= "127.0.0.1"
LISTEN_PORT= "8865"
INC = -I/usr/local/include
LIBS = -L /usr/local/lib
EOF
yum install lmdb
apt-get install liblmdb-dev lmdb-utils curl libcurl3
brew install curl
brew install jpmens/brew/revgeod
This is documented here, and the homebrew version is typically kept in sync with this version.
- libmicrohttpd
- statsd-c-client (optional)
https://github.com/jpmens/revgeod
Jan-Piet Mens https://jpmens.net