---
name: "Geo::Hash::XS"
section: "3pm"
platform: "linux"
package: "libgeo-hash-xs-perl"
version: "0.00015-2+b5"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Geo::Hash::XS"
---

# Geo::Hash::XS(3pm)

Geo::Hash in XS

## NAME

Geo::Hash::XS - Geo::Hash in XS

## SYNOPSIS

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

## DESCRIPTION

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.

## LICENSE

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

See http://www.perl.com/perl/misc/Artistic.html

## AUTHOR

Copyright (c) 2010 Daisuke Maki \<daisuke@endeworks.jp\>