NAME
bi-geocode - fill Database::BI's geocode cache for a column of places
SYNOPSIS
bi-geocode --spec <spec> --col <column> [--col <column> ...]
[--text <text>] [--data-dir <dir>] [--model-dir <dir>]
[--openaddr <path>] [--region <CC>]
[--offline] [--online-max <n>]
[--dry-run] [--verbose]
DESCRIPTION
Opens a dataset, looks up every distinct value of the named column (or of several, --col repeated, joined with ", ": an address, then its country), with --text added to the end of each place, and writes the coordinates into the shared geocode cache in the model store. Map pages for the dataset then draw from the cache without asking a geocoder.
Places are looked up in Geo::Coder::Free's local data first, then on OpenStreetMap (Nominatim) at one a second, with no limit unless --online-max sets one: the map page asks Nominatim for at most map_geocode_online_max places, and this is how the rest are found. --offline keeps every lookup local. A second run on a warm cache looks up nothing more, and says so. Geocoding needs Geo::Coder::Free and Geo::Coder::List, which are recommended rather than required.
0 2 * * * cd /opt/myapp && bi-geocode --spec table:customers --col city --region US
OPTIONS
- --spec, -s spec
-
The dataset:
table:name,path:/abs/pathorurl:.... Required. - --col, -c column
-
A column holding place names. Required; repeat it for a place spread across columns (
--col Address --col Country). - --text, -t text
-
Text added to the end of each place, after
", ", for places the cells do not name fully:--col County --text 'Virginia, USA'looksAccomackup asAccomack, Virginia, USA. It is the map panel's Add to each place (loc_text=), tidied the same way (spaces trimmed, a leading comma dropped), so the map finds what this caches. A row with no place is not given the text. At most 200 characters, on one line. - --data-dir, -d dir
-
The data folder (default: data).
- --model-dir, -m dir
-
The model store folder (default: .bi). Places OpenStreetMap found are kept in <model-dir>/geocode-cache unless another cache directory is set:
cache_dirthrough Object::Configure (or the environment variableDatabase__BI__Model__Geocode__cache_dir), then$ENV{CACHEDIR}, then$ENV{CACHE_DIR}, thencache_dirin database_bi.conf (the fileMOJO_CONFIGnames, else the one in the current folder). - --openaddr, -o path
-
An OpenAddresses data folder for Geo::Coder::Free.
- --region, -r CC
-
An ISO 3166-1 alpha-2 region hint, such as
USorGB. - --offline
-
Use the local data only, never OpenStreetMap.
- --online-max n
-
Look up at most n places on OpenStreetMap.
- --dry-run, -n
-
Look places up but do not write the cache.
- --verbose, -v
-
Print progress to STDERR.
- --help, -h
-
Show the usage.
EXIT STATUS
0 on success, 1 when the column is not found or there are no rows, 2 for bad arguments or a data source that cannot be read.
AUTHOR
Nigel Horne <njh@nigelhorne.com>
LICENCE AND COPYRIGHT
Copyright 2026 Nigel Horne.
Usage is subject to the GPL2 licence terms. If you use it, please let me know.