File Coverage

=head1 NAME

Geo::Coder::Free - Geocoding using free, locally-hosted databases

=head1 VERSION

Version 0.51

=cut

=head1 SYNOPSIS

    use Geo::Coder::Free;

    my $geo = Geo::Coder::Free->new();
    my $pt  = $geo->geocode(location => 'Ramsgate, Kent, UK');
    printf "%.6f, %.6f\n", $pt->lat(), $pt->long();

    # With OpenAddresses/WhoOnFirst data:
    my $geo2 = Geo::Coder::Free->new(openaddr => $ENV{OPENADDR_HOME});
    my $pt2  = $geo2->geocode(location => '1600 Pennsylvania Avenue NW, Washington DC, USA');

    # Free-text scanning:
    my @hits = $geo2->geocode(scantext => 'She grew up in Ramsgate, Kent.',
                              region   => 'GB');

=head1 DESCRIPTION

C<Geo::Coder::Free> translates addresses into latitude/longitude coordinates
using local SQLite databases built from free data sources - MaxMind/GeoNames,
OpenAddresses, Who's On First, OpenStreetMap, and dr5hn's countries/states/cities
database.  It deliberately avoids paid or rate-limited online geocoding services.
The module is designed to be flexible, supporting both command-line and programmatic usage.
It also includes a sample CGI script for a web-based geocoding service.

Geocoding dispatch order depends on whether C<OPENADDR_HOME> (or C<openaddr>) is set:

B<With OpenAddresses data:>

=over 4

=item 1. C<Geo::Coder::Free::OpenAddresses> - requires C<OPENADDR_HOME>

=item 2. C<Geo::Coder::Free::Local> - user-curated CSV entries (tried as fallback)

=item 3. C<Geo::Coder::Free::MaxMind> - bundled, always available

=back

B<Without OpenAddresses data:>

=over 4

=item 1. C<Geo::Coder::Free::MaxMind> only - Local is not consulted.

=back

The C<cgi-bin> directory contains a simple DIY geo-coding website:

    cgi-bin/page.fcgi page=query q=1600+Pennsylvania+Avenue+NW+Washington+DC+USA

The sample website is currently down while a new host is sought.
When it returns, you will be able to test it with:

    curl 'https://geocode.nigelhorne.com/cgi-bin/page.fcgi?page=query&q=1600+Pennsylvania+Avenue+NW+Washington+DC+USA'

=head1 LIMITATIONS

=over 4

=item * C<scantext> mode only finds locations in OpenAddresses; it falls back
silently when C<OPENADDR_HOME> is not set (B<FIXME>: should warn).

=item * The C<__DATA__> alternatives table is hard-coded; it should live in a
user-editable config file.

=item * The address-regex scantext path misses birth-year sentences such as
C<"She was born May 21, 1937 in Noblesville, IN."> because the regex requires
a preceding capital-letter word directly before the city.

=item * C<reverse_geocode> is only partially implemented; the MaxMind path does
not return meaningful results.

=item * Without OpenAddresses data, a two-part C<"City, Country"> location is
often answered wrongly.  The MaxMind backend reads the first part as a region
when it can, and answers with the first row it finds in that region, not with
the city: C<"Berlin, Germany"> and C<"Munich, Germany"> both come back at
52.08, 7.38, and C<"Toronto, Canada"> comes back in British Columbia.  Some
others, such as C<"Paris, France">, are not found at all.  These results carry
C<< accuracy => 'region' >> and C<< confidence => 0.1 >>, so a caller that needs
a city should check L</provenance> and reject them.  Naming the region as well,
as in C<"Munich, Bavaria, Germany">, gives the right answer.

=item * Place names are matched as they are spelled in the data, with no
folding of accents: C<"ZE<uuml>rich, Switzerland"> is found and C<"Zurich, Switzerland">
is not.  Pass locations as Perl character strings (decoded, for example by
C<use utf8> or an C<:encoding(UTF-8)> layer), not as undecoded UTF-8 bytes,
since a byte string does not match the name in the data.

=back

=cut

=head1 METHODS

=head2 new

=head3 SYNOPSIS

    my $geo = Geo::Coder::Free->new();
    my $geo = Geo::Coder::Free->new(openaddr => '/data/openaddr');
    my $geo = Geo::Coder::Free->new(directory => '/data/maxmind');

=head3 DESCRIPTION

Constructor.  Accepts a hash or hashref of options.  If called without
C<openaddr>, the module checks C<$ENV{OPENADDR_HOME}> before giving up.

If called on an existing object instance (C<< $clone = $geo->new() >>), returns
a B<shallow clone>.  All scalar fields are copied by value, but reference-type
fields (C<alternatives>, C<scantext_misses>, C<maxmind>, C<openaddr>) share the
same underlying object or hashref between the original and the clone.  Mutations
to those shared references are immediately visible in both objects.

=head3 API SPECIFICATION

=head4 input

    # Input schema (Params::Validate::Strict)
    openaddr  => { type => 'scalar', optional => 1 }                          # path to OpenAddresses/WOF data dir
    directory => { type => 'scalar', optional => 1 }                          # path to MaxMind/GeoNames files
    cache     => { type => 'object', optional => 1, can => ['get', 'set'] }   # CHI-compatible cache object
    libpostal => { type => 'boolean', optional => 1, default => 1 }           # false: OpenAddresses never uses Geo::libpostal

C<libpostal> is passed to L<Geo::Coder::Free::OpenAddresses>; see its
"Optional modules" section for why you might turn it off.

=head4 output

    # Output schema (Return::Set)
    { type => 'object', isa => 'Geo::Coder::Free' }

=head3 EXAMPLE

    use Geo::Coder::Free;

    # Minimal - uses only the bundled MaxMind data:
    my $geo = Geo::Coder::Free->new();

    # Full - also searches OpenAddresses/WOF:
    my $geo = Geo::Coder::Free->new(openaddr => $ENV{OPENADDR_HOME});

=head3 MESSAGES

    use ->new() not ::new()   Called as a function; use arrow syntax.

=cut

=head2 valid_location

=head3 SYNOPSIS

    if ($geo->valid_location($row->{'place'})) {
        push @found, $geo->geocode(location => $row->{'place'});
    }

=head3 DESCRIPTION

Answers whether a string is something this module will even try to look up.
It is the public form of the rule C<geocode()> applies before it touches a
backend, so a caller working down a spreadsheet column can skip a row whose
value is a bare number - or is empty - instead of catching the croak that
would otherwise kill the whole run.  That rule is defined once, in
L<Geo::Location::Predicate>, and the backends apply it too: what
C<valid_location()> refuses is refused wherever it is looked up.

Only that cheap syntactic test is answered.  A true result means the string is
not disqualified, B<not> that a backend knows it: C<'Ramsgate, Kent'> is valid
and may still find nothing, while C<'0044'> is invalid and is never looked up.
The rule rejects a string of digits only, which is what a numeric column holds
when the wrong column has been read, so anything with a non-digit in it counts
as valid - C<'3.14'> and C<'-'> included.  C<undef>, C<''> and a reference are
not valid.

=head3 API SPECIFICATION

=head4 input

    location => { type => 'scalar', optional => 1 }  # the string to test

=head4 output

    { type => 'boolean' }  # false for undef, '' and a digit-only string

=head3 EXAMPLE

    my $geo = Geo::Coder::Free->new();

    $geo->valid_location('Ramsgate, Kent');   # true
    $geo->valid_location('0044');             # false - never a location
    $geo->valid_location('');                 # false
    $geo->valid_location(undef);              # false

Accepts the three calling conventions the rest of this module does:

    $geo->valid_location('0044');
    Geo::Coder::Free->valid_location('0044');
    Geo::Coder::Free::valid_location('0044');

=cut

=head2 geocode

=head3 SYNOPSIS

    # Standard lookup (returns a Geo::Location::Point or undef)
    my $pt = $geo->geocode(location => 'Ramsgate, Kent, UK');
    printf "lat=%.6f lon=%.6f\n", $pt->lat(), $pt->long();

    # Scantext - returns a list of Geo::Location::Point objects
    my @hits = $geo->geocode(
        scantext     => 'She lived in Ramsgate, Kent.',
        region       => 'GB',
        ignore_words => [qw(lived)],
    );

    # Invocation flexibility (all equivalent)
    $geo->geocode('Ramsgate, Kent, UK');
    $geo->geocode({ location => 'Ramsgate, Kent, UK' });
    $geo->geocode(location => 'Ramsgate, Kent, UK');

    # A batch caller with a dirty column: skip the row, do not kill the run
    for my $place (@column) {
        my $pt = $geo->geocode(location => $place, on_error => 'undef');
        next unless defined $pt;
        push @found, $pt;
    }

=head3 DESCRIPTION

A location or a scantext that is not a location at all - a bare number, such as
the C<0044> a numeric column holds - is refused before any backend is
touched.  C<valid_location()> answers the same question, so a caller can filter
first; C<on_error> chooses what happens when one gets through anyway:

=over 4

=item * C<'croak'> (the default) - C<Carp::croak>, the behaviour every existing
caller already has.

=item * C<'undef'> - return C<undef>, so one bad row in a spreadsheet column is
skipped rather than ending the run.  It changes the answer for B<only> the two
documented input errors below; an exception from a backend is still an
exception, and a malformed argument list still croaks.

=back

The option is deliberately narrow, so a batch caller wants C<valid_location()>
with it: that predicate answers false for C<undef> and C<''> as well, which are
the other two things an empty cell holds.  A call with neither a location nor a
scantext is a usage error rather than an input error - the same croak as calling
C<geocode()> with no arguments - and stays a croak on either setting.

=head3 API SPECIFICATION

=head4 input

    # Input schema (Params::Validate::Strict) - exactly one of location or scantext is required
    location     => { type => 'scalar',   optional => 1 }  # address string (exclusive with scantext)
    scantext     => { type => 'scalar',   optional => 1 }  # free text to scan for place names
    region       => { type => 'scalar',   optional => 1 }  # ISO 3166-1 alpha-2 country code hint
    ignore_words => { type => 'arrayref', optional => 1 }  # words to suppress during scantext scan
    on_error     => { type => 'scalar',   optional => 1 }  # 'croak' (default) or 'undef'

=head4 output

    # Output schema (Return::Set)
    # scalar context: { type => 'object',   isa => 'Geo::Location::Point', optional => 1 }
    # list context:   { type => 'arrayref', of  => { isa => 'Geo::Location::Point' } }

=head4 provenance

Every result carries C<geocoder>, C<database>, C<confidence> and C<accuracy>
which distribution produced
it, which backend answered, how good the match was, and how precise the
coordinate is.  C<provenance()> reads the four back.  C<location> is set by every
path but the MaxMind cities one, and C<text> only by a scantext lookup; C<lat>,
C<long> and C<lng> come from the value object itself.

=head3 MESSAGES

    Usage: ...::geocode(...)        No location or scantext argument given.
    invalid location to geocode()   location is purely numeric.
    invalid scantext to geocode()   scantext is purely numeric.
    on_error must be ...            on_error is neither 'croak' nor 'undef'.

=head3 PSEUDOCODE

    if self is not a blessed object -> delegate to new()->geocode(@args)
    normalise @_ into %params
    validate: on_error is 'croak' or 'undef' (croak if not)
    validate: location is not purely numeric; scantext is not purely numeric
              (undef instead of croaking when on_error is 'undef')
    if openaddr backend is available:
        if scantext:
            try the raw scantext string as a direct location
            build stopword set from %_COMMON_WORDS + ignore_words param
            try 3-word windows (triplets) at confidence 0.8
            try 2-word windows (duplets) at confidence 0.7
            try the address-pattern regex at confidence 0.7
            try region-specific address finders (GB / US / CA)
            mark scantext as a miss; return undef
        else:
            try openaddr backend
            try local backend
            try __DATA__ alternatives map
    try maxmind backend for location lookups
    croak if no scantext and no location

=cut

=head2 geocode_many

=head3 SYNOPSIS

    my $batch = $geo->geocode_many(\@places, region => 'GB', on_error => 'undef');

    for my $place (@places) {
        my $pt = $batch->{$place};              # a Geo::Location::Point, or undef
        next unless defined $pt;
        printf "%s is at %.4f, %.4f\n", $place, $pt->lat(), $pt->long();
    }

    printf "geocoded %d of %d places in %d lookups\n",
        $batch->{'resolved'},
        $batch->{'resolved'} + $batch->{'unresolved'},
        $batch->{'lookups'};

=head3 DESCRIPTION

The loop a batch caller writes around C<geocode()>, run for it: one lookup per
B<distinct> value, with the same options and the same results, plus the counts
that caller would otherwise keep itself - how many values made a backend read,
how many resolved, how many did not, which ones, and which backend read for them

The hashref returned holds one entry per distinct value given, keyed by the
value, plus five keys of its own:

=over 4

=item * C<< $batch->{$value} >> - the C<Geo::Location::Point> the value resolved
to, or C<undef> if nothing did.  Every distinct value in the input is keyed, so
a caller walking a column can look each row up without first asking whether the
batch covered it.  An C<undef> in the input has no key of its own and shares the
entry of the empty string, which is not a location either.

=item * C<lookups> - how many distinct values made a backend read to answer
them: one per value, however many backends looked at it.  A value the module
refuses before any backend is touched - a bare number, C<''>, C<undef>, a
reference - is not counted, and neither is a value a backend answered from a
cache or from a hand-curated entry, because nothing was read for it.  This is
what makes the count the work a caller is capping rather than the work it asked
for.  A value repeated in the batch is one lookup.  Every backend reports its
reads through C<reads()>, and a value every backend has already missed is
remembered in L<Geo::Coder::Free::MissCache>, one process-level cache that all
backends and instances share, whose entries expire after an hour and can be
emptied early with L</clear_miss_cache>.  A later batch in the same process is
answered from those caches and so reports the reads it needed, often none, in
place of the ones the first batch made.

=item * C<reads> - how many reads each backend made for the batch, keyed by the
name C<provenance()> reports that backend under: C<MaxMind>, C<Local> or
C<OpenAddresses>.  Every backend the object holds is named, at zero for one that
read nothing, so a batch answered from a cache names its backends at zero rather
than naming none.  C<lookups> counts values and this counts reads - a value that
made two backends read is one lookup and a read for each of them, so these
numbers can add up to more than C<lookups> - and the two vocabularies are the
same, so a caller can put the backend that read a value beside the backend a
result came from.

=item * C<resolved> - how many distinct values produced a point.

=item * C<unresolved> - how many produced nothing, the refused values included.

=item * C<unresolved_values> - those values, in the order they were first seen,
so that a caller can record them as tried-and-failed rather than retrying them
on every request.  Section 2.5 sketches this list under the name C<unresolved>;
here C<unresolved> is the count a "geocoded N of M" message needs and the values
themselves are C<unresolved_values>.

=back

C<resolved> and C<unresolved> always add up to the number of distinct values
given, and the five keys above are reserved: a value equal to one of them is
refused by name, before anything is looked up, rather than allowed to overwrite
a count.

C<region> and C<on_error> are handed to every lookup and mean there what they
mean in C<geocode()>, including the rule that a backend exception is still an
exception - nothing here is wrapped in an C<eval>.  C<on_error> defaults to
C<'croak'> for the same reason it does there: a batch should not quietly plot
fewer points than its column holds unless the caller asked it to, and a caller
working down a dirty column asks for C<'undef'>.  The two settings do not differ
in which values are looked up, only in what happens to a value the module
refuses: C<'croak'> dies on it with the message C<geocode()> gives for it,
C<'undef'> counts it unresolved and carries on.

A batch of no values is not an error: the counts come back zero.

The values are treated as a set.  Repeating a value in the input looks it up
once and every row is keyed to the same point object, so a column that repeats
the same handful of places thousands of times costs the handful of lookups.

=head3 API SPECIFICATION

=head4 input

    # Input schema (Params::Validate::Strict) - values required, options optional
    values   => { type => 'arrayref' }                  # location strings, one per row
    region   => { type => 'scalar', optional => 1 }     # ISO 3166-1 alpha-2 country code hint
    on_error => { type => 'scalar', optional => 1 }     # 'croak' (the default) or 'undef'

=head4 output

    # Output schema (Return::Set)
    { type => 'hashref' }
    #   $result->{$value}            => { isa => 'Geo::Location::Point', optional => 1 }
    #   $result->{lookups}           => { type => 'integer' }
    #   $result->{reads}             => { type => 'hashref' }
    #   $result->{resolved}          => { type => 'integer' }
    #   $result->{unresolved}        => { type => 'integer' }
    #   $result->{unresolved_values} => { type => 'arrayref' }

=head3 MESSAGES

    Usage: ...::geocode_many(...)   No values argument, one that is not an arrayref,
                                    or options that are neither a list nor a hashref.
    invalid location to geocode()   A value refused under on_error => 'croak', with the
                                    message geocode() gives for that value.
    on_error must be ...            on_error is neither 'croak' nor 'undef'.
    <value> is one of the keys ...  A value spelled like one of the five returned keys.

=head3 EXAMPLE

    my $geo = Geo::Coder::Free->new(openaddr => $ENV{OPENADDR_HOME});

    # A log file's place column: repeats, a few unreadable values, one empty cell.
    my @places = ('Ramsgate, Kent', '0044', 'Nowhere, Imaginary, ZZ',
                  'Ramsgate, Kent', undef);

    my $batch = $geo->geocode_many(\@places, region => 'GB', on_error => 'undef');

    printf "geocoded %d of %d distinct places in %d lookups\n",
        $batch->{'resolved'},
        $batch->{'resolved'} + $batch->{'unresolved'},
        $batch->{'lookups'};        # 4 distinct places, 2 of them looked up

    # Which backend did the reading, and which answered from a cache: a backend
    # at zero answered nothing by reading.
    while (my ($backend, $reads) = each %{$batch->{'reads'}}) {
        print "$backend read $reads times\n";
    }

    for my $place (@{$batch->{'unresolved_values'}}) {
        warn "no coordinates for '" . (defined($place) ? $place : '') . "'\n";
    }

=cut

=head2 clear_miss_cache

    Geo::Coder::Free->clear_miss_cache();
    $geo->clear_miss_cache();
    Geo::Coder::Free->clear_miss_cache('OpenAddresses');

Forgets the lookups that found nothing.  Each backend remembers a miss in
L<Geo::Coder::Free::MissCache>, one process-level cache that every backend and
every instance shares, so an address that is not in the data is searched for
once per process rather than once per call.  Entries expire after an hour; this
method empties them now, for a caller that has rebuilt a database or downloaded
a data set while the process is running.

With a scope - C<OpenAddresses>, C<Local> or C<MaxMind> - only that backend's
entries go; C<OpenAddresses> covers every OpenAddresses directory this process
has opened.  A scope that names no backend, such as
C<clear_miss_cache('Nonsense')>, forgets nothing and is not an error.  Returns
true.

=head3 API SPECIFICATION

=head4 input

    scope => { type => 'string', optional => 1 }  # OpenAddresses, Local or MaxMind

=head4 output

    { type => 'boolean', value => 1 }

=cut

=head2 provenance

    my ($dist, $backend, $confidence, $accuracy) = $geocoder->provenance($point);

or, in scalar context, the same four as a hashref:

    my $provenance = $geocoder->provenance($point);
    print $provenance->{'backend'};

Where a result came from and how good it is, so that a caller does not have to
reach for the hash keys itself:

=over 4

=item * C<$dist> - the distribution that produced the result: the C<geocoder>
key, C<Geo::Coder::Free> for a result from this distribution, or the wrapper
that passed it on, such as C<Geo::Coder::List>.

=item * C<$backend> - which backend answered, in a short vocabulary: C<Local>,
C<MaxMind>, C<OpenAddresses> or C<GeoNames>.  This is the C<database> key with
the distribution's prefix removed, so that the two spellings the backends use -
C<Geo::Coder::Free::Local> from C<Local>, and C<MaxMind> from C<MaxMind> - speak
the same vocabulary here.  B<The C<database> key itself is unchanged>, for the
consumers that already match on it.

=item * C<$confidence> - how good the match was, 0.0 to 1.0, where 1.0 is exact.

=item * C<$accuracy> - how precise the coordinate is: C<address>, C<street>,
C<postcode>, C<locality>, C<city>, C<region> or C<country>.

=back

Returns an empty list - and an empty hashref in scalar context - when handed
something that is not a result.  A key a result does not carry comes back
C<undef> rather than being guessed at, because a plain hash from another
geocoder has no provenance to report.

=head3 API SPECIFICATION

=head4 input

    point => { type => 'hashref', optional => 1 }  # a result, usually a Geo::Location::Point

=head4 output

    # list context
    { type => 'array', min => 0, max => 4 }   # dist, backend, confidence, accuracy; or ()

    # scalar context
    {
        type   => 'hashref',
        schema => {
            dist       => { type => 'string', optional => 1 },
            backend    => { type => 'string', optional => 1 },
            confidence => { type => 'number', optional => 1, min => 0, max => 1 },
            accuracy   => { type => 'string', optional => 1 },
        },
    }   # {} when handed something that is not a result

=cut

=head2 reverse_geocode

=head3 SYNOPSIS

    my $loc = $geo->reverse_geocode(latlng => '51.3341,-1.4159');

=head3 DESCRIPTION

Translates a latitude/longitude pair back to a place name.
B<Partially implemented>: the MaxMind backend does not return meaningful results.
OpenAddresses is attempted first when available.

=head3 API SPECIFICATION

=head4 input

    # Input schema (Params::Validate::Strict) - latlng required
    latlng => { type => 'scalar' }  # "$lat,$long" comma-separated decimal degrees
    # NOTE: separate lat/lon/long keys are NOT supported at the Geo::Coder::Free
    # (facade) level.  When no OpenAddresses backend is configured, passing
    # lat/lon/long instead of latlng will croak "not yet supported".
    # To use separate coordinates call Geo::Coder::Free::Local::reverse_geocode.

=head4 output

    # Output schema (Return::Set)
    { type => 'object', isa => 'Geo::Location::Point', optional => 1 }

=cut

=head2 ua

Does nothing.  Present for drop-in compatibility with other Geo::Coder::* modules.

=head3 API SPECIFICATION

=head4 input

    # Input schema (Params::Validate::Strict)
    # any arguments are accepted and ignored

=head4 output

    # Output schema (Return::Set)
    # nothing: an empty list, or undef in scalar context

=cut

=head2 run

Command-line entry point.  Use as:

    perl lib/Geo/Coder/Free.pm 1600 Pennsylvania Avenue NW, Washington DC

The arguments are joined with spaces into one location, which is geocoded with
OpenAddresses as well when C<OPENADDR_HOME> is set.  The results are printed to
standard output with L<Data::Dumper>.  It croaks C<geocoding failed> if nothing
is found.

=head3 API SPECIFICATION

=head4 input

    # Input schema (Params::Validate::Strict)
    class    => { type => 'string' }                    # Geo::Coder::Free
    location => { type => 'arrayref', of => 'string' }  # the words of the location, joined with spaces

=head4 output

    # Output schema (Return::Set)
    { type => 'boolean' }   # the return value of print; croaks if nothing was found

=cut

=head1 GETTING STARTED

To download, import and set up the local database:
before running C<make>, but after running C<perl Makefile.PL>, follow these instructions.

Optionally set C<OPENADDR_HOME> to point to an empty directory and download the data from
L<http://results.openaddresses.io> into that directory; and
optionally set C<WHOSONFIRST_HOME> to point to an empty directory and download the data using
L<https://github.com/nigelhorne/NJH-Snippets/blob/master/bin/wof-clone>.
The script C<bin/download_databases> (see below) will do those for you.
You do not need to download the MaxMind data - that is downloaded automatically.

You will need to create the database used by C<Geo::Coder::Free>.

Install L<App::csv2sqlite> and L<https://github.com/nigelhorne/NJH-Snippets>.
Run C<bin/create_sqlite> - this converts the MaxMind "cities" database from CSV to SQLite.

To use with MariaDB, set C<MARIADB_SERVER="$hostname;$port"> and
C<MARIADB_USER="$user;$password"> (TODO: username/password should be asked for interactively).
The code will use a database called C<geo_code_free>, which will be dropped and recreated if it exists.
C<$user> needs only DROP, CREATE, SELECT, INSERT, and INDEX privileges on that database.

The following optional steps download and install large databases.
This will take a long time and use a lot of disc space.

=over 4

=item 1

C<mkdir $WHOSONFIRST_HOME; cd $WHOSONFIRST_HOME> then run C<wof-clone> from NJH-Snippets.

This can take a long time because it contains many nested directories, which filesystem drivers
can be slow to navigate (particularly on EXT4 and ZFS).

=item 2

Install L<https://github.com/dr5hn/countries-states-cities-database.git> into C<$DR5HN_HOME>.
This data covers cities only, so it is not used when C<OSM_HOME> is set (OSM is far more
comprehensive).  Only Australia, Canada, and the US are imported, as the UK data is difficult
to parse.

=item 3

Run C<bin/download_databases> - this downloads the Who's On First, OpenAddr, OpenStreetMap,
and dr5hn databases.
OpenStreetMap now uses PBF files, so you will need C<apt install osmium-tool> first.
Check the values of C<OSM_HOME>, C<OPENADDR_HOME>, C<DR5HN_HOME> and C<WHOSONFIRST_HOME>
within that script and adjust them for your setup.
The C<Makefile.PL> file downloads the MaxMind database automatically, as it is not optional.

=item 4

Run C<bin/create_db> - this creates the database used by C<Geo::Coder::Free> from the data you
have just downloaded.
The database is called C<openaddr.sql> for historical reasons (before Who's On First was added);
it actually contains data from all sources above.

=back

Now you are ready to run C<make>.
See the comment at the start of C<createdatabase.PL> for further details.

=head1 MORE INFORMATION

I have written several Perl genealogy programs including
L<gedcom|https://github.com/nigelhorne/gedcom> and
L<ged2site|https://github.com/nigelhorne/ged2site>.
One of the things these do is check the validity of a family tree, including verifying place-names.
Of course places do change names and spelling becomes more consistent over the years, but the vast
majority remain the same - enough to make computerised verification worthwhile.

=head1 BUGS

Some lookups fail.  Please file a bug report at
L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Geo-Coder-Free>.

The MaxMind data contains cities only.
The OpenAddresses data does not cover the whole globe.
C<London, England> cannot be parsed yet.

=head1 SEE ALSO

=over 4

=item * L<Configure an Object at Runtime|Object::Configure>

=item * L<Test Dashboard|https://nigelhorne.github.io/Geo-Coder-Free/coverage/>

=back

L<Geo::Coder::Free::Local>, L<Geo::Coder::Free::MaxMind>,
L<Geo::Coder::Free::OpenAddresses>,
L<https://openaddresses.io/>, L<https://www.maxmind.com/>,
L<https://www.geonames.org/>, L<https://www.whosonfirst.org/>.

=head1 AUTHOR

Nigel Horne C<< <njh@nigelhorne.com> >>

=head1 FORMAL SPECIFICATION

=head2 new

    GeoCoderFreeState ::= ⟨⟨ maxmind     : MaxMind_Geocoder;
                              openaddr    : OpenAddr_Geocoder | undef;
                              alternatives: Map[STRING → STRING];
                              cache       : Cache | undef ⟩⟩

    OpenAddrState ::= ⟨⟨ openaddr  : PATH;
                          cache     : Cache | undef;
                          libpostal : BOOLEAN ⟩⟩

    Init : Params → GeoCoderFreeState
    âˆ€ p : Params •
      let oa_path == p.openaddr ∨ env.OPENADDR_HOME •
      GeoCoderFreeState.openaddr = if oa_path ≠ ∅
                                   then OpenAddresses(oa_path, p.cache, p.libpostal)
                                   else undef fi
      âˆ§ (oa_path ≠ ∅ ⟹ GeoCoderFreeState.openaddr.libpostal =
                          if p.libpostal = undef then true else p.libpostal fi)

    -- libpostal = false: Geo::libpostal is never loaded or called
    âˆ€ s : OpenAddrState • ¬ s.libpostal ⟹ Geo::libpostal ∉ loaded_by(s.geocode)

=head2 valid_location

    ValidLocation : Any → BOOLEAN
    âˆ€ x : Any •
      ValidLocation(x) = (x ≠ ∅ ∧ ¬ ref(x) ∧ x ≠ "" ∧ x ∋ non-digit)

=head2 geocode

    ErrorMode ::= "croak" | "undef"

    Geocode : Address × Region? × ErrorMode? → Point?
    âˆ€ addr : Address; r : Region?; e : ErrorMode? •
      let mode == e ∨ "croak" •
      let backends == (openaddr ≠ undef ⟹ [OpenAddresses, Local, MaxMind])
                    âˆ§ (openaddr = undef ⟹ [MaxMind]) •
      Â¬ ValidLocation(addr) ⟹ (mode = "undef" ⟹ result = ∅ | mode = "croak" ⟹ ⊥)
      âˆ§ ValidLocation(addr) ⟹
      result = first { defined } map { b.geocode(addr, r) } backends

=head2 provenance

    Provenance : Point? → (DISTRIBUTION?, BACKEND?, CONFIDENCE?, ACCURACY?)
    âˆ€ p : Point? •
      Provenance(p) = if p ≠ ∅ ∧ is_a_result(p)
                      then ⟨⟨ p.geocoder,
                              strip("Geo::Coder::Free::", p.database),
                              p.confidence,
                              p.accuracy ⟩⟩
                      else ∅ fi

=head1 LICENSE AND COPYRIGHT

Copyright 2017-2026 Nigel Horne.  Licensed under GPL2 for personal use.

This product uses GeoLite2 data created by MaxMind,
available from L<https://www.maxmind.com/>.

=cut