File Coverage

=head1 NAME

Geo::Coder::Free::OpenAddresses -
Provides a geocoding functionality to a local SQLite database containing geo-coding data.

=head1 VERSION

Version 0.51

=cut

=head1 SYNOPSIS

    use Geo::Coder::Free::OpenAddresses;

    # Use a local download of http://results.openaddresses.io/
    my $geocoder;
    if(my $openaddr = $ENV{'OPENADDR_HOME'}) {
        $geocoder = Geo::Coder::Free::OpenAddresses->new(openaddr => $openaddr);
    } else {
        $geocoder = Geo::Coder::Free::OpenAddresses->new(openaddr => '/usr/share/geo-coder-free/data');
    }
    my $location = $geocoder->geocode(location => '1600 Pennsylvania Avenue NW, Washington DC, USA');

    my @matches = $geocoder->geocode({ scantext => 'arbitrary text', region => 'GB' });

=head1 DESCRIPTION

Geo::Coder::Free::OpenAddresses provides an interface to the free geolocation databases at
L<http://results.openaddresses.io>,
L<https://github.com/whosonfirst-data>,
L<https://github.com/dr5hn/countries-states-cities-database.git> and
L<https://download.geofabrik.de/europe-latest.osm.bz2>.
The SQLite database is in a file held in $OPENADDR_HOME/openaddresses.sql.

Refer to the source URL for licencing information for these files.

To install,
run the createdatabases.PL script which imports the data into an SQLite database.
This process will take some time.

=head2 Optional modules

Two modules are used to parse an address when they are installed, and the
lookup goes on without them when they are not:

=over 4

=item * L<Geo::Address::Parser> splits a US address into its fields before the
database is searched for them.

=item * L<Geo::libpostal> is tried last, for US and Canadian addresses the
other steps could not parse.  The first call to it in a process loads
libpostal's model, which is several gigabytes, so that call can take several
seconds and the process then holds that memory.  Pass C<< libpostal => 0 >> to
C<new()> to leave it unused, for example in a short-lived or memory-constrained
process, or in a test with a time limit.

=back

=head1 METHODS

=head2 new

    $geocoder = Geo::Coder::Free::OpenAddresses->new(openaddr => $ENV{'OPENADDR_HOME'});

Takes an optional parameter "openaddr", which is the directory of the file
openaddresses.sql.

Takes an optional parameter cache, which points to an object that understands get() and set() messages to store data in

Takes an optional parameter libpostal.  When it is false, L<Geo::libpostal> is
never loaded or called, even if it is installed; see L</Optional modules>.
It defaults to true.

=head3 API SPECIFICATION

=head4 input

    # Input schema (Params::Validate::Strict)
    openaddr  => { type => 'scalar' }                                          # path to the directory containing openaddresses.sql
    cache     => { type => 'object', optional => 1, can => ['get', 'set'] }   # CHI-compatible cache object
    libpostal => { type => 'boolean', optional => 1, default => 1 }           # false: never use Geo::libpostal

=head4 output

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

=cut

=head2 reads

    my $count = $geocoder->reads();

How many times this backend has read its database since the object was created.
A lookup answered from the result cache or from the shared miss cache does not
increase it, so C<geocode_many()> can take the count before and after a value to
tell a lookup that cost a read from one that was answered from a cache.

=head3 API SPECIFICATION

=head4 input

    # Input schema (Params::Validate::Strict)
    # none

=head4 output

    # Output schema (Return::Set)
    { type => 'integer', min => 0 }   # 0 for a new object

=cut

=head2 geocode

    $location = $geocoder->geocode(location => $location);

    print 'Latitude: ', $location->lat(), "\n";
    print 'Longitude: ', $location->long(), "\n";

    # TODO:
    # @locations = $geocoder->geocode('Portland, USA');
    # diag 'There are Portlands in ', join (', ', map { $_->{'state'} } @locations);

    @locations = $geo_coder->geocode(scantext => 'arbitrary text', region => 'US', ignore_words => [ 'foo', 'bar' ]);

When looking for a house number in a street, if that address isn't found but that
street is found, a place in the street is given.
So "106 Wells Street, Fort Wayne, Allen, Indiana, USA" isn't found, a match for
"Wells Street, Fort Wayne, Allen, Indiana, USA" will be given instead.
Arguably that's incorrect, but it is the behaviour I want.
If "exact" is not given,
it will go on to look just for the town if the street isn't found.

The word "county" is removed from US county searches,
that either C<Leesburg, Loudoun County, Virginia, US> or C<Leesburg, Loudoun, Virginia, US> will work.

=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
    exact        => { type => 'scalar',   optional => 1 }  # if set, do not fall back to town-only match

=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>
(section 2.1 of F<BI-Phase6-Dependency-Specs.md>).  This backend reports
C<database> as C<OpenAddresses>, and C<accuracy> is C<address> when the database
answered for the address itself and C<locality> when a hand-curated
C<%known_locations> entry did, since that entry's coordinate is a town's.

=cut