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/path or url:.... 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' looks Accomack up as Accomack, 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_dir through Object::Configure (or the environment variable Database__BI__Model__Geocode__cache_dir), then $ENV{CACHEDIR}, then $ENV{CACHE_DIR}, then cache_dir in database_bi.conf (the file MOJO_CONFIG names, 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 US or GB.

--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.