File Coverage

=head1 NAME

Geo::Coder::Free::Local - Geocode using user-curated local data

=head1 VERSION

Version 0.51

=cut

=head1 SYNOPSIS

    use Geo::Coder::Free::Local;

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

=head1 DESCRIPTION

Provides geocoding via a user-curated CSV dataset embedded in the module's
C<__DATA__> section.  Locations in the data were verified by GPS and by
inspecting geotagged photographs.  The data is read once at construction time
and indexed for fast lookup.

This is the highest-priority backend tried by C<Geo::Coder::Free>.

=head1 LIMITATIONS

=over 4

=item * The embedded C<__DATA__> dataset covers only a small set of hand-picked locations.
There is no mechanism for non-authors to contribute data without patching the module.

=item * Canadian and Australian address parsing is not yet implemented; those queries return C<undef>.

=item * C<_search> performs an O(n) linear scan through all rows.  The hash-based
index in C<new()> handles exact string matches; no index exists for partial field matches.

=item * C<our %alternatives> duplicates mappings in C<Geo::Coder::Free::__DATA__>.
Both should be consolidated into a shared external config file.

=item * C<$libpostal_is_installed> is a module-level (effectively global) flag.
Not thread-safe in a forking or threaded Perl deployment.

=item * The C<__DATA__> filehandle is a one-shot resource.  The first call to
C<new()> exhausts it with C<my @data = E<lt>DATAE<gt>>; every subsequent
C<new()> in the same process reads zero rows and builds an empty index.
Construct exactly one C<Local> object per process and share it.

=item * The hash-index key is C<lc(Geo::Location::Point-E<gt>new($row)-E<gt>as_string())>,
which B<includes the C<name> field>.  To get a direct index hit the caller must
supply the full string with the venue/place name as the leading component;
an address that omits the name falls through to the slower O(n) C<_search> path.

=back

=cut

=head1 METHODS

=head2 new

=head3 SYNOPSIS

    my $geocoder = Geo::Coder::Free::Local->new();
    my $geocoder = Geo::Coder::Free::Local->new(cache => $chi_cache);

=head3 DESCRIPTION

Constructor.  Reads the C<__DATA__> CSV block, builds a hash-based lookup
index, and derives the geographic centre of any city/state/country cluster
containing three or more data points.

B<One-shot filehandle>: the C<DATA> handle is consumed on the first call to
C<new()>.  Any subsequent call to C<new()> returns an object whose dataset and
index are both empty.  In code that constructs multiple C<Local> objects (e.g.
in tests) construct B<exactly one> instance and reuse it across all callers.

=head3 API SPECIFICATION

=head4 input

    # Input schema (Params::Validate::Strict)
    cache => { type => 'object', optional => 1, can => ['get', 'set'] }  # CHI-compatible cache object

=head4 output

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

=head3 FORMAL SPECIFICATION

    LocalState ::= ⟨⟨ data  : seq Row;
                       index : Map[STRING → Row];
                       cache : Map[STRING → Point] ⟩⟩

    Init : Params → LocalState
    âˆ€ p : Params •
      let rows    == parse_csv(__DATA__) ∪ geographic_centres(__DATA__) •
      let idx_key == λ r • lc(Point(r).as_string()) •
      LocalState.index = { idx_key(r) ↦ r | r ∈ rows }

=cut

=head2 reads

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

How many times this backend has searched its dataset since the object was
created.  A lookup answered from the index, 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 search 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

=head3 SYNOPSIS

    my $pt = $geocoder->geocode(location => '203 E Chatsworth Rd, Reisterstown, Baltimore, MD, US');
    print $pt->lat(), "\n";

    # All calling forms are accepted:
    $geocoder->geocode('203 E Chatsworth Rd, Reisterstown, MD, US');
    $geocoder->geocode({ location => '203 E Chatsworth Rd, Reisterstown, MD, US' });

=head3 API SPECIFICATION

=head4 input

    # Input schema (Params::Validate::Strict)
    location => { type => 'scalar' }  # address string; must contain at least two commas

=head4 output

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

=head3 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<Geo::Coder::Free::Local>, and C<accuracy> is what the matched
columns justify: a house number makes it an C<address>, a road a C<street>, a
name or city a C<locality>, a state a C<region> and a country a C<country>.  A
lookup answered from the index, which matches a whole row, is an exact match
(C<confidence> of 1.0) whose accuracy comes from the row's own fields - so a
derived geographic centre, which carries a city, state and country and nothing
narrower, is a C<locality>.

=head3 MESSAGES

    Usage: ...::geocode(...)   No location argument given.

=head3 FORMAL SPECIFICATION

    Geocode : STRING → Point?
    âˆ€ addr : STRING •
      let norm == lc(replace_usa(addr)) •
      (norm ∈ cache ⟹ result = cache[norm]) ∧
      (norm ∈ index ⟹ result = index[norm]) ∧
      (¬ result ⟹ result = parse_and_search(addr))

=head3 PSEUDOCODE

    normalise @_ into %params
    reject if location does not contain two or more commas (not a full address)
    check cache; return hit
    check hash index; return hit and cache it
    # index key includes the 'name' field; supply the venue/place name as the
    # leading address component to guarantee an index hit
    attempt country-specific parser (US, GB; skip CA/AU pending implementation)
    attempt Geo::StreetAddress::US for "..., USA" addresses
    attempt Geo::Address::Parser
    attempt Geo::libpostal (large memory footprint; loaded lazily)
    attempt 4-part regex decomposition (name/road/city/state/country)
    attempt %alternatives mapping
    return undef

=cut

=head2 reverse_geocode

=head3 SYNOPSIS

    my $loc = $geocoder->reverse_geocode(latlng => '51.3341,-1.4159');
    # Returns the location string(s) for that lat/lon pair.

=head3 API SPECIFICATION

=head4 input

    # Input schema (Params::Validate::Strict) - latlng or lat+lon required
    latlng => { type => 'scalar', optional => 1 }  # "$lat,$long" comma-separated decimal degrees
    lat    => { type => 'scalar', optional => 1 }  # latitude  (alternative to latlng)
    lon    => { type => 'scalar', optional => 1 }  # longitude (alternative to latlng)
    long   => { type => 'scalar', optional => 1 }  # alias for lon

=head4 output

    # Output schema (Return::Set)
    # scalar context: { type => 'scalar',   optional => 1 }  # location string
    # list context:   { type => 'arrayref', of => { type => 'scalar' } }

=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 _result_for

Build the result for a dataset row that the index matched.  The index holds the
rows themselves - the same hashrefs C<_search> scans - so the object is built
as a copy rather than blessed in place, and the provenance keys every result
carries (section 2.1 of F<BI-Phase6-Dependency-Specs.md>) are added where the
row does not already record them.

An index hit is an exact match on the row's string, so the confidence is
C<$CONF_EXACT>, and the accuracy is what the row's own fields justify, through
C<Geo::Location::Point::accuracy_for()>.

=cut

=head1 AUTHOR

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

=head1 BUGS

The data are stored in the module source and must be maintained by the author.
A future version should load them from an external file to allow community contributions.

See also: L<https://rt.cpan.org/NoAuth/Bugs.html?Dist=Geo-Coder-Free>

=head1 SEE ALSO

L<Geo::Coder::Free>, L<Geo::Coder::Free::OpenAddresses>, L<Geo::Coder::Free::MaxMind>

=head1 LICENSE AND COPYRIGHT

Copyright 2020-2026 Nigel Horne.

The program code is released under the following licence: GPL2 for personal use on a single computer.
All other users (including Commercial, Charity, Educational, and Government)
must apply in writing for a licence for use from Nigel Horne at C<< <njh at nigelhorne.com> >>.

=cut