Geo::Hash::XS(3pm)

Usage

    my $gh = Geo::Hash::XS->new();
    my $hash = $gh->encode( $lat, $lon );  # default precision = 32
    my $hash = $gh->encode( $lat, $lon, $precision ); 
    my ($lat, $lon) = $gh->decode( $hash );

Overview

Geo::Hash::XS encodes and decodes geohash strings, fast.

Currently this module is alpha quality (especially the adjacent() and negihbors() methods, which I just kind of copied the logic from elsewhere). Please submit tests and patches!

Methods

$gh = Geo::Hash::XS->new()

$hash = $gh->encode($lat, $lon[, $precision])

Encodes the given $lat and $lon to a geohash. If $precision is not given, automatically adjusts the precision according the the given $lat and $lon values.

If you do not want Geo::Hash::XS to spend time calculating this, explicitly specify $precision.

($lat, $lon) = $gh->decode( $hash )

Decodes $hash to $lat and $lon

($lat_range, $lon_range) = $gh->decode_to_interval( $hash )

Like decode() but decode_to_interval() decodes $hash to $lat_range and $lon_range. Each range is a reference to two element arrays which contains the upper and lower bounds.

$adjacent_hash = $gh->adjacent($hash, $where)

Returns the adjacent geohash. $where denotes the direction, so if you want the block to the right of $hash, you say:

    use Geo::Hash::XS qw(ADJ_RIGHT);
    my $gh = Geo::Hash::XS->new();
    my $adjacent = $gh->adjacent( $hash, ADJ_RIGHT );

@list_of_geohashes = $gh->neighbors($hash, $around, $offset)

Returns the list of neighbors (the blocks surrounding $hash)

$precision = $gh->precision($lat, $lon)

Returns the apparent required precision to describe the given latitude and longitude.

Constants

Adj_left, adj_right, adj_top, adj_bottom

Used to specify the direction in adjacent()

Performance

Here's the output from running benchmark/encode.pl:

    Geo::Hash: 0.02
    Geo::Hash::XS: 0.00014
    precision = auto...
             Rate  perl    xs
    perl  18332/s    --  -98%
    xs   964744/s 5163%    --
    
    precision = 5...
              Rate  perl    xs
    perl   16500/s    --  -98%
    xs   1011557/s 6030%    --
    
    precision = 10...
             Rate   perl     xs
    perl   8650/s     --   -99%
    xs   980236/s 11232%     --
    
    precision = 20...
             Rate   perl     xs
    perl   4736/s     --   -99%
    xs   858875/s 18035%     --
    
    precision = 30...
             Rate   perl     xs
    perl   3050/s     --  -100%
    xs   712136/s 23252%     --

Obviously, the benefit of doing this calculation in XS becomes larger with higher precision, but generaly you don't need precision > 10.

Releases

2 releases since Debian 12 (Bookworm); the text changed 1 time.

12
13