File Coverage

=head1 NAME

Geo::Coder::List - Call many Geo-Coders

=head1 VERSION

Version 0.37

=cut

=head1 SYNOPSIS

L<Geo::Coder::All> and L<Geo::Coder::Many> are great modules but neither
quite does what I want.

C<Geo::Coder::List> aggregates multiple geocoding services into a single,
unified interface.  It chains and prioritizes backends based on regex routing
and per-geocoder query limits, caches results at two levels (L1 in-memory
always; optional L2 via CHI or a plain HASH), and normalizes every provider's
idiosyncratic response into the common structure expected by
L<HTML::GoogleMaps::V3> and L<HTML::OSM>:

    $result->{geometry}{location}{lat}   # canonical latitude
    $result->{geometry}{location}{lng}   # canonical longitude
    $result->{geocoder}                  # source object (or 'cache')

    use Geo::Coder::List;
    use Geo::Coder::OSM;
    use Geo::Coder::CA;

    my $list = Geo::Coder::List->new()
        ->push({ regex => qr/(Canada|USA)$/, geocoder => Geo::Coder::CA->new() })
        ->push(Geo::Coder::OSM->new());

    my $loc = $list->geocode('10 Downing St, London, UK');
    printf "lat=%.4f lng=%.4f\n",
        $loc->{geometry}{location}{lat},
        $loc->{geometry}{location}{lng};

=head1 SUBROUTINES/METHODS

=head2 new

Creates a new C<Geo::Coder::List> object.  When called on an existing object
it returns a clone of that object merged with the supplied arguments.

The constructor reads configuration from environment variables via
L<Object::Configure>; for example, setting
C<GEO__CODER__LIST__carp_on_warn=1> causes warnings to use L<Carp>.

    use Geo::Coder::List;
    use CHI;

    # With an optional L2 cache (any CHI driver works)
    my $geocoder = Geo::Coder::List->new(
        cache => CHI->new(driver => 'Memory', global => 1),
        debug => 0,
    );

    # Clone an existing object with a higher debug level
    my $verbose = $geocoder->new(debug => 2);

=head3 API SPECIFICATION

=head4 INPUT

    # Params::Validate::Strict schema
    {
        cache => {
            type     => [ 'hashref', 'object' ],     # OBJECT must implement get($key) and set($key, $value, $ttl)
            optional => 1,
        },
        debug => {
            type     => 'boolean',
            optional => 1,
            default  => 0,
        },
        # Any additional key is forwarded to Object::Configure
    }

=head4 OUTPUT

    # Return::Set schema
    OBJECT blessed into Geo::Coder::List

=cut

=head2 push

Appends a geocoder to the chain.  Geocoders are tried in the order they
were pushed.  Returns C<$self> so calls can be chained.

A plain geocoder object is tried for every location.  A hashref with
C<regex>, C<geocoder>, and optional C<limit> keys restricts the geocoder to
locations matching the regex and caps total queries at C<limit>.

    my $list = Geo::Coder::List->new()
        ->push({ regex => qr/USA$/, geocoder => Geo::Coder::CA->new(), limit => 100 })
        ->push(Geo::Coder::OSM->new());

=head3 API SPECIFICATION

=head4 INPUT

    # Params::Validate::Strict schema
    {
        geocoder => {
            type     => OBJECT | HASHREF,
            required => 1,
            # HASHREF must contain:  geocoder => OBJECT
            # HASHREF may contain:   regex    => Regexp
            #                        limit    => SCALAR (positive integer)
        },
    }

=head4 OUTPUT

    # Return::Set schema
    OBJECT blessed into Geo::Coder::List   # $self, for chaining

=cut

=head2 geocode

Resolves a location string to geographic coordinates by trying each geocoder
in turn.  The first successful result is returned and cached.

In scalar context returns a single hashref (or C<undef> on failure).
In list context returns all results from the winning geocoder.

The C<geocoder> field of the returned hashref holds the geocoder object that
supplied the result; it is set to the string C<'cache'> when the result was
served from cache.

See L<Geo::Coder::GooglePlaces::V3> for the canonical result structure.

    my $result = $list->geocode(location => 'Paris, France');
    if($result) {
        printf "lat=%.4f lng=%.4f via %s\n",
            $result->{geometry}{location}{lat},
            $result->{geometry}{location}{lng},
            ref($result->{geocoder}) || $result->{geocoder};
    }

    # List context returns all candidates from the winning geocoder
    my @results = $list->geocode('London, UK');

=head3 API SPECIFICATION

=head4 INPUT

    # Params::Validate::Strict schema
    {
        location => {
            type     => SCALAR,
            required => 1,
            # Must contain at least one non-digit character
        },
    }

=head4 OUTPUT

    # Return::Set schema (scalar context)
    HASHREF | undef
    {
        geometry => { location => { lat => Num, lng => Num } },
        geocoder => OBJECT | 'cache',
        lat      => Num,   # convenience alias
        lng      => Num,   # convenience alias
        lon      => Num,   # compatibility alias for lng
        debug    => Int,   # source line of the normalisation branch taken
        # ... provider-specific keys are preserved
    }

    # Return::Set schema (list context)
    ARRAY of the above HASHREFs

=cut

=head2 ua

Sets the L<LWP::UserAgent> (or compatible) object on every geocoder in the
chain.  Useful when you need proxy support or custom timeouts across all
backends at once.

There is intentionally no read accessor since that would be meaningless
(each geocoder could have a different UA).

    use LWP::UserAgent;
    my $ua = LWP::UserAgent->new();
    $ua->env_proxy(1);
    $list->ua($ua);

=head3 API SPECIFICATION

=head4 INPUT

    # Params::Validate::Strict schema
    {
        ua => {
            type     => OBJECT,
            optional => 1,
        },
    }

=head4 OUTPUT

    # Return::Set schema
    OBJECT   # the same $ua that was passed in

=cut

=head2 reverse_geocode

Converts a latitude/longitude pair into a human-readable address string.

In scalar context returns a single address string (or C<undef>).
In list context returns all address strings from the winning geocoder.

    my $address = $list->reverse_geocode(latlng => '51.5074,-0.1278');
    print "Address: $address\n" if $address;

    my @addresses = $list->reverse_geocode(latlng => '51.5074,-0.1278');

=head3 API SPECIFICATION

=head4 INPUT

    # Params::Validate::Strict schema
    {
        latlng => {
            type    => SCALAR,
            required => 1,
            regex   => qr/^\s*[-+]?(?:\d*\.?\d+|\d+\.?\d*)
                              \s*,\s*
                          [-+]?(?:\d*\.?\d+|\d+\.?\d*)\s*$/x,
        },
    }

=head4 OUTPUT

    # Return::Set schema (scalar context)
    SCALAR (address string) | undef

    # Return::Set schema (list context)
    ARRAY of SCALAR

=cut

=head2 log

Returns an arrayref of log entries accumulated since the last C<flush()>.
Each entry is a hashref with the keys: C<line>, C<location>, C<timetaken>,
C<geocoder>, C<wantarray>, and either C<result> or C<error>.

    foreach my $entry (@{ $list->log() }) {
        printf "%s: %.3fs via %s\n",
            $entry->{location},
            $entry->{timetaken},
            $entry->{geocoder};
    }

=head3 API SPECIFICATION

=head4 INPUT

    # No parameters accepted

=head4 OUTPUT

    # Return::Set schema
    ARRAYREF of HASHREF
    [
        {
            line      => Int,
            location  => Str,
            timetaken => Num,
            geocoder  => Str | 'cache',
            wantarray => Bool,
            result    => HASHREF | ARRAYREF | Str,   # on success
            error     => Str,                        # on failure
        },
        ...
    ]

=cut

=head2 flush

Clears all accumulated log entries and returns C<$self> to allow chaining.

    $list->geocode('Paris, France');
    my $entries = $list->log();
    $list->flush()->geocode('London, UK');   # chained

=head3 API SPECIFICATION

=head4 INPUT

    # No parameters accepted

=head4 OUTPUT

    # Return::Set schema
    OBJECT blessed into Geo::Coder::List   # $self, for chaining

=cut