NAME

Geo::Code::XYZ - Encode latitude,longitude,elevation into three names and vice versa.

VERSION

Version 1.6

SYNOPSIS

        use Geo::Code::XYZ;
        my $g = Geo::Code::XYZ->new();
        my ($x,$y,$z) = (56.936650,24.088020,6);
        my $geocode = $g->geocode(lat=>$x,lon=>$y,el=>$z,geoname=>1);
        print $geocode . "\n";
                #RIGA-FRIDAY-OKEG
        
        my $xyz = $g->geocode(gc=>$geocode);
        my ($lat,$lon,$el) = @$xyz;
        print "The latitude,longitude,elevation of $geocode is $lat,$lon,$el\n";
                #56.936650,24.088020,6
                            
        
        # geoname: 0 => Alphanumeric, 1 => three geonames, 2 => hybrid string (one geoname and a string), 3 => numeric code.
                     

DESCRIPTION

Geo::Code::XYZ is the 3d version of the perl5 module Geo::Code. It produces location codes for latitude,longitude,elevation triplets with a resolution of 1 meter for an elevation of up/down to +- 17576 metres (in the three geoname version, geoname => 1, all other options default to elevation = 0).

A set of 146300 geonames has been selected from geonames.org and other open sources with certain requirements such as: every geoname has phonetic/levenstein distance of at least 2 from every other geoname, major geonames are prioritized over less known ones to make the set more memorable.

The first geoname is the name of the most prominent location name in the vicinity of the point (for eg, LONDON-ZERO-MAX is a location near London, UK.) The other two are random geonames or english words of length less than or equal to 9. If the first name is not a geoname, for eg, MAX-ZERO-LONDON, then the location is somewhere in the ocean or the poles, too far from any known geoname. (at least 200 kilometres away from the nearest geoname)

Geocodes that are close to each other will have similar names, for eg: LONDON-SHURGARD-OINK and LONDON-SHURGARD-OPEC are about 1 meter from each other, while LONDON-SHURGARD-OINK and LONDON-SHURIKEN-OINK are about 383 meters away.

There are several improvements in Geo::Code::XYZ over the original Geo::Code, in addition to the elevation feature, such as, more intuitive name choices for readability and location proximity, more evenly spread phonetic distance for reducing errors in voice transmission of geocodes, picking geoname aliases based on OSM admin boundaries (3geonames.org online version only - this module does not rely on a database and this last feature needs one.)

This module is explained in more detailed on GitHub. View on GitHub.

Online Demo. 3Geonames.org.

Also supported on Geocode.xyz.

METHODS

new

my $g = Geo::Code::XYZ->new();

geocode

my $code = $g->geocode(lat=>51.5,lon=>0.1, geoname=>1); #if geoname is omited, it defaults to Alphanumeric Geo::Code. If elevation is omited, it defaults to 0.

or

my $point = $g->geocode(gc=>'LONDON-ZERO-MAX');

#$point is an array reference containing latitude,longitude,elevation

EXPORT

geocode

REQUIREMENTS

Math::BigInt # lib => 'GMP'; # optional to make it a bit faster

SEE ALSO

3Geonames.org, Geocode.xyz

AUTHOR

Ervin Ruci, <eruci at geocode.xyz>

BUGS

Please report any bugs or feature requests to bug-geocode at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Geo::Code. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Geo::Code::XYZ

You can also look for information at:

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Copyright 2019 Ervin Ruci.

This program is free software; you can redistribute it and/or modify it under the terms of the the Artistic License (2.0). You may obtain a copy of the full license at:

http://www.perlfoundation.org/artistic_license_2_0

Any use, modification, and distribution of the Standard or Modified Versions is governed by this Artistic License. By using, modifying or distributing the Package, you accept this license. Do not use, modify, or distribute the Package, if you do not accept this license.

If your Modified Version has been derived from a Modified Version made by someone other than you, you are nevertheless required to ensure that your Modified Version complies with the requirements of this license.

This license does not grant you the right to use any trademark, service mark, tradename, or logo of the Copyright Holder.

This license includes the non-exclusive, worldwide, free-of-charge patent license to make, have made, use, offer to sell, sell, import and otherwise transfer the Package with respect to any patent claims licensable by the Copyright Holder that are necessarily infringed by the Package. If you institute patent litigation (including a cross-claim or counterclaim) against any party alleging that the Package constitutes direct or contributory patent infringement, then this Artistic License to you shall terminate on the date that such litigation is filed.

Disclaimer of Warranty: THE PACKAGE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS "AS IS' AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES. THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT ARE DISCLAIMED TO THE EXTENT PERMITTED BY YOUR LOCAL LAW. UNLESS REQUIRED BY LAW, NO COPYRIGHT HOLDER OR CONTRIBUTOR WILL BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING IN ANY WAY OUT OF THE USE OF THE PACKAGE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

SEE ALSO

Similar Modules

Geo::Code, Geo::OLC, Geohash, Geo::What3Words