The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Geo-Coder-Free-0.35
River stage zero No dependents
3 ++
/ Geo::Coder::Free::MaxMind

NAME

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

VERSION

Version 0.35

SYNOPSIS

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

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

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 https://www.maxmind.com/en/free-world-cities-database; admin1.db is from http://download.geonames.org/export/dump/admin1CodesASCII.txt; admin2.db is from http://download.geonames.org/export/dump/admin2Codes.txt;

See also 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.

METHODS

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 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.

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);

reverse_geocode

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

Returns a string, or undef if it can't be found.

ua

Does nothing, here for compatibility with other geocoders

AUTHOR

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

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

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 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 limit 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.

SEE ALSO

VWF, MaxMind and geonames.

LICENSE AND COPYRIGHT

Copyright 2017-2023 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 https://www.maxmind.com/en/home. (Note that this currently gives a 403 error - I need to find the latest URL).