revgeod.1

.\" Automatically generated by Pandoc 3.0.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "REVGEOD" "8)/REVGEOC(1" "" "User Manuals" ""
.hy
.SH NAME
.PP
revgeod - reverse-geo lookup daemon
.PP
revgeoc - lookup client for revgeod
.SH SYNOPSIS
.PP
revgeod [-v]
.PP
revgeoc stats|dump|lookup|kill|test
.SH DESCRIPTION
.PP
\f[I]revgeod\f[R] is a reverse Geo lookup daemon thing, accessible via
HTTP and backed via OpenCage (https://opencagedata.com), our geocoder of
choice.
You\[cq]ll need an OpenCage API key exported into the environment, and
you can specify \f[I]revgeod\f[R]\[cq]s listen IP address and port which
default to \f[V]127.0.0.1\f[R] and \f[V]8865\f[R] respectively.
.PP
The (curently hardcoded) \f[I]geocache\f[R] directory must exist and be
writeable by the owner of the \f[I]rungeod\f[R] process; that\[cq]s
where the LMDB database is stored.
\f[I]revgeod\f[R] caches OpenCage\[cq]s responses (they explicitly
permit this):
.PP
\f[I]revgeoc\f[R] is the client program which speaks HTTP to
\f[I]revgeod\f[R].
.SH EXAMPLE
.IP
.nf
\f[C]
$ curl -i \[aq]http://127.0.0.1:8865/rev?lat=48.85593&lon=2.29431\[aq]
HTTP/1.1 200 OK
Connection: Keep-Alive
Content-Length: 197
Content-type: application/json
Date: Wed, 31 Jan 2024 10:44:14 GMT

{
    \[dq]address\[dq]: {
    \[dq]village\[dq]: \[dq]4 r du Général Lambert, 75015 Paris, France\[dq],
    \[dq]locality\[dq]: \[dq]Paris\[dq],
    \[dq]cc\[dq]: \[dq]FR\[dq],
    \[dq]s\[dq]: \[dq]opencage\[dq],
    \[dq]tzname\[dq]: \[dq]Europe/Paris\[dq]
    }
}
\f[R]
.fi
.PP
A second query for the same location would respond with \f[V]lmdb\f[R]
instead of \f[V]opencage\f[R] as the source, indicating it\[cq]s been
cached.
.SH ENDPOINTS
.PP
All \f[I]revgeod\f[R] API endpoints are obtained via GET requests, and
the client program \f[I]revgeoc\f[R] uses the same words as its
commands.
.SS \f[V]rev\f[R]
.PP
The \f[V]/rev\f[R] endpoint is used to perform a reverse-geo lookup and
cache the positive result.
This endpoint supports the following query parameters:
.IP \[bu] 2
\f[V]lat=\f[R] specify the latitude as a decimal (mandatory)
.IP \[bu] 2
\f[V]lon=\f[R] specify the longitude as a decimal (mandatory)
.IP \[bu] 2
\f[V]app=\f[R] specifies an \[lq]application\[rq] for which query
statistics should be collected (see \f[I]statistics\f[R] below)
(optional)
.SS \f[V]stats\f[R]
.PP
\f[I]revgeod\f[R] provides statistics on its \f[V]/stats\f[R] endpoint,
and it collects counters by \f[I]application\f[R] if the \f[V]app\f[R]
query parameter is specified during lookups:
.IP
.nf
\f[C]
{
   \[dq]stats\[dq]: {
      \[dq]_whoami\[dq]: \[dq]revgeod.c\[dq],
      \[dq]_version\[dq]: \[dq]0.1.8\[dq],
      \[dq]stats\[dq]: 8,
      \[dq]requests\[dq]: 13647,
      \[dq]geocode_failed\[dq]: 9,
      \[dq]opencage\[dq]: 13624,
      \[dq]lmdb\[dq]: 23
   },
   \[dq]apps\[dq]: {
      \[dq]recorder\[dq]: 13,
      \[dq]clitest\[dq]: 5,
      \[dq]jp0\[dq]: 2
   },
   \[dq]uptime\[dq]: 381258,
   \[dq]uptime_s\[dq]: \[dq]4 days, 9 hours, 54 mins\[dq],
   \[dq]tst\[dq]: 1544555424,
   \[dq]db_path\[dq]: \[dq]/usr/local/var/revgeod/geocache/\[dq],
   \[dq]db_entries\[dq]: 43756,
   \[dq]db_size\[dq]: 7532544
}
\f[R]
.fi
.SS \f[V]dump\f[R]
.PP
The \f[V]/dump\f[R] endpoint produces a full dump of the underling
database in JSON format as an array of objects, each containing a
\f[I]geohash\f[R], the cached address information, and \f[I]lat\f[R] and
\f[I]lon\f[R] elements which are the latitude and longitude respectively
which have been decoded from the entries\[cq] \f[I]geohash\f[R].
Note that this means that the values are not those from which the entry
originally resulted.
.SS \f[V]lookup\f[R]
.PP
This endpoint expects \f[V]geohash\f[R] query parameter with a
\f[I]geohash\f[R] of precision 8; the key is looked up in the database
and the JSON data or HTTP status code 404 are returned.
.SS \f[V]kill\f[R]
.PP
Similarly to \f[V]lookup\f[R], \f[V]/kill\f[R] also expects a
\f[I]geohash\f[R] and removes it from the database.
.SH OPTIONS
.PP
\f[I]revgeod\f[R] understands the following global options.
.TP
-v
show version information and exit
.SH ENVIRONMENT
.TP
\f[V]revgeo_verbose\f[R]
if this variable is set when \f[I]revgeoc\f[R] starts, the program
displays received HTTP headers
.TP
\f[V]OPENCAGE_APIKEY\f[R]
this mandatory variable must be set in \f[I]revgeod\f[R]\[cq]s
environment for it to do reverse geo lookups.
.TP
\f[V]REVGEO_IP\f[R]
optionally sets the listen address for \f[I]revgeod\f[R]; defaults to
\f[V]127.0.0.1\f[R] and we strongly recommend this is not changed to
anything other than a loopback address.
.TP
\f[V]REVGEO_PORT\f[R]
optionally sets the TCP listen port to something other than the default
\f[V]8865\f[R].
.TP
\f[V]REVGEO_HOST\f[R]
optionally sets the hostname/address for \f[I]revgeoc\f[R]; defaults to
\f[V]127.0.0.1\f[R] and \f[V]REVGEO_PORT\f[R]
.SH REQUIREMENTS
.SS freebsd
.IP
.nf
\f[C]
$ pkg install curl
$ pkg install libmicrohttpd
$ pkg install lmdb

$ cat > config.mk <<EOF
# STATSDHOST=           \[dq]127.0.0.1\[dq]
LMDB_DATABASE= \[dq]data/geocache/\[dq]
LISTEN_HOST=   \[dq]127.0.0.1\[dq]
LISTEN_PORT=   \[dq]8865\[dq]
INC =           -I/usr/local/include
LIBS =          -L /usr/local/lib
EOF
\f[R]
.fi
.SS rhel/centos
.IP
.nf
\f[C]
yum install lmdb
\f[R]
.fi
.SS debian
.IP
.nf
\f[C]
apt-get install  liblmdb-dev lmdb-utils curl libcurl3
\f[R]
.fi
.SS macos
.IP
.nf
\f[C]
brew install curl
brew install jpmens/brew/revgeod
\f[R]
.fi
.PP
This is documented here (https://github.com/jpmens/homebrew-brew), and
the homebrew version is typically kept in sync with this version.
.SS all
.IP \[bu] 2
libmicrohttpd (https://www.gnu.org/software/libmicrohttpd/)
.IP \[bu] 2
statsd-c-client (https://github.com/romanbsd/statsd-c-client) (optional)
.SH CREDITS
.IP \[bu] 2
\f[V]json.[ch]\f[R] by Joseph A.
Adams.
.IP \[bu] 2
uthash (https://troydhanson.github.io/uthash/), by Troy D.
Hanson.
.IP \[bu] 2
utstring (https://troydhanson.github.io/uthash/utstring.html), by Troy
D.
Hanson.
.SH AVAILABILITY
.PP
<https://github.com/jpmens/revgeod>
.SH AUTHOR
.PP
Jan-Piet Mens <https://jpmens.net>