File Coverage

=head1 NAME

Geo::Coder::Free::MaxMind - Provides a geocoding functionality using the MaxMind and GeoNames databases

=head1 VERSION

Version 0.51

=cut

=head1 SYNOPSIS

    use Geo::Coder::Free::MaxMind;

    my $geocoder = Geo::Coder::Free::MaxMind->new();
    my $location = $geocoder->geocode(location => 'Ramsgate, Kent, UK');

=head1 DESCRIPTION

Geo::Coder::Free::MaxMind provides an interface to free databases.

Refer to the source URL for licencing information for these files:
cities.csv is from L<https://www.maxmind.com/en/free-world-cities-database>;
admin1.db is from L<http://download.geonames.org/export/dump/admin1CodesASCII.txt>;
admin2.db is from L<http://download.geonames.org/export/dump/admin2Codes.txt>;

See also L<http://download.geonames.org/export/dump/allCountries.zip>

To significantly speed this up,
gunzip cities.csv and run it through the db2sql script to create an SQLite file.

=head1 METHODS

=head2 new

    $geocoder = Geo::Coder::Free::MaxMind->new();

Takes one optional parameter, directory,
which tells the library where to find the files admin1db, admin2.db and cities.[sql|csv.gz].
If that parameter isn't given, the module will attempt to find the databases, but that can't be guaranteed

There are 3 levels to the Maxmind database.
Here's the method to find the location of Sittingbourne, Kent, England:
1) admin1.db contains admin areas such as counties, states and provinces
   A typical line is:
     US.MD      Maryland        Maryland        4361885
   So a look-up of 'Maryland' will get the concatenated code 'US.MD'
   Note that GB has England, Scotland and Wales at this level, not the counties
     GB.ENG     England England 6269131
   So a look-up of England will give the concatenated code of GB.ENG for use in admin2.db
2) admin2.db contains admin areas drilled down from the admin1 database such as US counties
   Note that GB has counties
   A typical line is:
    GB.ENG.G5   Kent    Kent    3333158
   So a look-up of 'Kent' with a concatenated code to start with 'GB.ENG' will code the region G5 for use in cities.sql
3) cities.sql contains the latitude and longitude of the place we want, so a search for 'sittingbourne' in the
   region 'g5' will give
     gb,sittingbourne,Sittingbourne,G5,41148,51.333333,.75

The admin2.db is far from comprehensive, see Makefile.PL for some entries that are added manually.

Called on an object, it returns a shallow copy with the arguments merged in.
It croaks if the directory doesn't exist.  Other arguments are passed to
L<Database::Abstraction>.

=head3 API SPECIFICATION

=head4 input

    # Input schema (Params::Validate::Strict)
    directory => { type => 'string', optional => 1 }                           # holds databases/; defaults to beside this module
    cache     => { type => 'object', optional => 1, can => ['get', 'set'] }   # CHI-compatible; defaults to a global memory cache

=head4 output

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

=cut

=head2 reads

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

How many times this backend has read its databases since the object was
created - a query on cities, admin1 or admin2.  A lookup answered without
reading anything - from the result cache, or from a hand-curated
C<%known_locations> entry - does not increase it.  C<geocode_many()> takes 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);

    # This will return one place in New Brunwsick, not them all
    # TODO: Arguably it should get them all from the database (or at least say the first 100) and return the central location
    my @locations = $geocoder->geocode({ location => 'New Brunswick, Canada' });
    die if(scalar(@locations) != 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<MaxMind>.  C<accuracy> is C<city> when the row was chosen by
city name, C<region> when the lookup named only a region or a country - the row
is then the first match in that region, not a city the caller asked for - and
C<locality> for a hand-curated C<%known_locations> entry, whose coordinate is a
town's.

=head3 API SPECIFICATION

=head4 input

    # Input schema (Params::Validate::Strict) - also accepts a hashref or a bare location string
    location => { type => 'string' }                 # must contain a comma unless region is given
    region   => { type => 'string', optional => 1 }  # ISO 3166-1 alpha-2 country code hint

=head4 output

    # Output schema (Return::Set)
    { type => 'object', isa => 'Geo::Location::Point', optional => 1 }   # at most one, in any context

Returns nothing when the location has no comma and no region is given, when it
is not found, or when it was already remembered as a miss.  It croaks on a
missing location, on a reference other than a hashref, and on a location that
fails L<Geo::Location::Predicate>'s rule, such as one made only of digits.

=cut

=head2  reverse_geocode

    $location = $geocoder->reverse_geocode(latlng => '37.778907,-122.39732');

Returns a string, or undef if it can't be found.
The nearest place within 0.01 degrees is chosen; in list context every place
within that distance is returned.  Separate C<lat> and C<lon> (or C<long>) are
accepted instead of C<latlng>.  It croaks if a coordinate is missing or is not
a decimal number.

=head3 API SPECIFICATION

=head4 input

    # Input schema (Params::Validate::Strict) - also accepts a hashref or a bare "lat,long" string
    latlng => { type => 'string', optional => 1 }   # "lat,long"
    lat    => { type => 'number', optional => 1 }   # with lon or long, when latlng isn't given
    lon    => { type => 'number', optional => 1 }
    long   => { type => 'number', optional => 1 }

=head4 output

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

=cut

=head2  ua

Does nothing, here for compatibility with other geocoders

=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

=head1 AUTHOR

Nigel Horne, C<< <njh@bandsman.co.uk> >>

This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.

=head1 BUGS

Lots of lookups fail at the moment.

The MaxMind data only contains cities.

Can't parse and handle "London, England".

The database contains Canadian cities, but not provinces, so a search for "New Brunswick, Canada" won't work

The GeoNames admin databases are in this class, they should be in Geo::Coder::GeoNames.

The data at
L<https://github.com/apache/commons-csv/blob/master/src/test/resources/org/apache/commons/csv/perf/worldcitiespop.txt.gz?raw=true>
are 7 years out of date,
and are inconsistent with the Geonames database.

If you search for something like "Sheppy, Kent, England" in list context,
it returns them all.
That's a lot!
It should be limited to,
say 10 results (that number should be tuneable, and be a LIMIT in DB.pm),
and as the correct spelling in Sheppey, arguably it should return nothing.

=head1 SEE ALSO

VWF, MaxMind and geonames.

=head1 LICENSE AND COPYRIGHT

Copyright 2017-2025 Nigel Horne.

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

This product includes GeoLite2 data created by MaxMind, available from
L<https://www.maxmind.com/en/home>.
(Note that this currently gives a 403 error - I need to find the latest URL).

=cut