File Coverage

=head1 NAME

Geo::Location::Point - Location information

=head1 VERSION

Version 0.19

=cut

=head1 SYNOPSIS

Geo::Location::Point encapsulates geographical point data with latitude and longitude.
It supports distance calculations,
comparison between points,
and provides various convenience methods for attributes like latitude, longitude, and related string representations.

    use Geo::Location::Point;

    my $location = Geo::Location::Point->new(latitude => 0.01, longitude => -71);

=head1 SUBROUTINES/METHODS

=head2 new

Initialise a new object, accepting latitude and longitude via a hash or hash reference.
Takes one optional argument 'key' which is an API key for L<https://timezonedb.com> for looking up timezone data.

    $location = Geo::Location::Point->new({ latitude => 0.01, longitude => -71 });

=cut

=head2 lat

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

=cut

=head2 latitude

Synonym for lat().

=cut

=head2 long

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

=cut

=head2  lng

Synonym for long().

=cut

=head2 longitude

Synonym for long().

=cut

=head2  distance

Determine the distance between two geographical points,
returns a L<Class::Measure::Length> object.

=cut

=head2  equal

Check if two points are identical within a small tolerance.

    my $loc1 = Geo::Location::Point->new(lat => 2, long => 2);
    my $loc2 = Geo::Location::Point->new(lat => 2, long => 2);
    print ($loc1 == $loc2), "\n";     # Prints 1

=cut

=head2  not_equal

Are two points different?

    my $loc1 = Geo::Location::Point->new(lat => 2, long => 2);
    my $loc2 = Geo::Location::Point->new(lat => 2, long => 2);
    print ($loc1 != $loc2), "\n";     # Prints 0

=cut

=head2  tz

Returns the timezone of the location.
Needs L<TimeZone::TimeZoneDB>.

=cut

=head2  timezone

Synonym for tz().

=cut

=head2  as_string

Generate a human-readable string describing the point,
incorporating additional attributes like city or country if available.

=cut

=head2  as_uri

Convert the point to a Geo URI scheme string (geo:latitude,longitude).
See L<https://en.wikipedia.org/wiki/Geo_URI_scheme>.
Arguably it should return a L<URI> object instead.

=cut

=head2  attr

Get or set arbitrary attributes, such as city or country.
A call with an argument sets the attribute and returns the value that was set;
a call without one reads it back and returns C<undef> if it was never set.

    $location->city('London');
    $location->country('UK');
    print $location->as_string(), "\n";
    print "$location\n";      # Calls as_string

It is the argument list, not the value, that decides whether a call is a read or a write,
so false values are attributes like any other and are stored and returned unchanged:

    $location->confidence(0);
    print 'matched: ', defined($location->confidence()) && $location->confidence(), "\n";

The upper case variant of the key is consulted
(but not overwritten) when the key as given has never been set,
which is how the MaxMind field names are read. An attribute that has been set,
however false, takes precedence over it.

=cut

=head2  geocoder

The distribution that produced the point, such as C<Geo::Coder::Free>.

    $location->geocoder('Geo::Coder::Free');

=cut

=head2  database

The database the distribution answered from, such as C<OpenAddresses>, C<Local>
or C<MaxMind>.

    $location->database('OpenAddresses');

=cut

=head2  confidence

How good the match is, from C<0> to C<1> inclusive, where C<1> is an exact
match. A confidence that is not a number, or that falls outside that range, is
rejected rather than stored.

    $location->confidence(0);                # Tried and rejected
    $location->confidence(0.8);              # A good match

=cut

=head2  ACCURACY_LEVELS

The accuracy levels a point may claim, most precise first: C<address> (a house
number), C<street>, C<postcode>, C<locality>, C<city>, C<region> and
C<country>.

This is the vocabulary, written down once here and read from here by
L<Geo::Coder::Free::Provenance> rather than copied, so the levels a point
accepts and the levels a backend reports cannot drift apart.  C<accuracy()>
accepts these and refuses anything else.

The rule that turns the fields a backend matched into one of these levels is
L</accuracy_for>, beside the list it returns a level from.

The list is read-only, and a caller that tries to add to it is refused, because
it is the list C<accuracy()> checks against: were it writable, a level pushed
into it would be published to every reader of this list while the module went on
refusing it.

    my $levels = Geo::Location::Point::ACCURACY_LEVELS();

=cut

=head2  accuracy_for

The accuracy a match can claim, from the fields that made it.  The most precise
field present decides: a house number makes it an C<address>, a road a
C<street>, a postcode a C<postcode>, a name or a city a C<locality>, a state or
region a C<region>, and a country a C<country>.  So a dataset row carrying only
a city, state and country is a C<locality>: a named place, not an address.

    my $level = Geo::Location::Point::accuracy_for(qw(house_number road city));

Always returns one of the L</ACCURACY_LEVELS>: a match on a row with none of the
fields above is still a named place, so it is reported as a C<locality> rather
than left unsaid, because every result promises an accuracy.

It is a function, not a method - the fields are what a backend matched, not
something a point carries - and it lives beside the vocabulary it returns a
level from, so the levels a point accepts and the rules that choose one of them
have a single home.

=cut

=head2  accuracy

How precise the coordinates behind a match can claim to be.  The levels are
those in L</ACCURACY_LEVELS>; anything else is rejected, because a reader
deciding what a point may claim about itself has to be able to trust the
value.

    $location->accuracy('city');

=cut

=head2  country

The country of the point, as the data spells it: C<GB>, C<US>, C<Canada>. It
is stored as given rather than normalised, so it is whatever the backend
matched.

    $location->country('GB');

=cut

=head2  city

The city, town or similar locality of the point.

    $location->city('London');

=cut

=head2  state

The state, province or region of the point.

    $location->state('KY');

=cut

=head1 SUPPORT

This module is provided as-is without any warranty.

=head1 AUTHOR

Nigel Horne, C<< <njh at nigelhorne.com> >>

=head1 BUGS

There is no validation on the attribute in the AUTOLOAD method,
so typos such as "citty" will not be caught.
C<geocoder>, C<database>, C<confidence>, C<accuracy>, C<country>, C<city> and
C<state> have documented accessors of their own that do check what they are
given,
but they are the only attributes that do,
and C<new()> stores whatever it is handed without checking it,
so a provenance field set through the constructor can still be any value.

=head1 SEE ALSO

=over 4

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

=back

L<GIS::Distance>,
L<Geo::Point>,
L<TimeZone::TimeZoneDB>.

=head1 LICENSE AND COPYRIGHT

Copyright 2019-2026 Nigel Horne.

Usage is subject to the GPL2 licence terms.
If you use it,
please let me know.

=cut