new(...)

$index = Geo::Index->new();
Create a new empty index using default options: radius and circumferences are those of Earth, levels is set to 20 (~40 m index resolution).

$index = Geo::Index->new( \@points );
Create a new index using default options and populate it with the given points. The points in the array can be in either hash or array notation.

$index = Geo::Index->new( \%options );
Create a new empty index using specified options.

$index = Geo::Index->new( \@points, \%options );
Create a new index using specified options and populate it with the given points. The points in the array can be in either hash or array notation.

---

Important: If you're running Geo::Index in a server environment see the notes on using Inline::C at the bottom of this page.

---

The @points array

Optional list of points to populate the initial index

Each point in the list is either a reference to a hash containing at a minimum a lat and a lon value (both in degrees) or a reference to an array giving the point. See the Points section for details.

The options hash

When a Geo::Index object is created, one can optionally specify various options to fine-tune its behavior. The default values are suitable for a high-resolution index of Earth.

• radius
  Average planetary radius (in meters). (default: 6371230)

  If a radius is specified but polar_circumference or equatorial_circumference are not given then they will be calculated from the radius ( 2 * pi * radius )

• polar_circumference
  Polar (meridional) circumference of the object the points lie on (in meters). (default: 40007863)

• equatorial_circumference
  Circumference at the equator of the object the points lie on (in meters). (default: 40075017)

• levels
  Depth of index. (valid: >0, <30; default: 20)
  Note that the levels parameter specefies the number of non-full-globe levels to generate and NOT the deepest index level. (Level -1, covering the entire globe, is always generated) For example, setting levels to 20 generates indices at levels 0 through 19 (plus level -1).

  A summary of typical tile levels is shown below. To choose a value for the levels option using the table add 1 to the 'Level' shown for the desired maximum level of detail. The 'Grid' column shows the north-south size of each tile in meters at a each level. The 'Size' column shows the initial amount of RAM needed for an indexed set of 1 million random points using numeric keys on a 64-bit system when that level is the most detailed one (sizes may grow moderately once searches are run).

   Level    Grid      Size              Level   Grid     Size  
   -----  ---------  ---------------    -----  -------  -------
    -1    ~40000 km  (entire planet)     12      ~5 km  ~2.4 GB
     0    ~20000 km                      13    ~2.5 km  ~2.7 GB
     1    ~10000 km  ~1.0 GB             14    ~1.2 km  ~3.1 GB
     2     ~5000 km  ~1.0 GB             15    ~600 m   ~3.3 GB
     3     ~2500 km  ~1.1 GB             16    ~300 m   ~3.6 GB
     4     ~1250 km  ~1.2 GB             17    ~150 m   ~3.8 GB
     5      ~625 km  ~1.3 GB             18     ~75 m   ~4.1 GB
     6      ~315 km  ~1.4 GB             19     ~40 m   ~4.4 GB
     7      ~155 km  ~1.5 GB             20     ~20 m   ~4.6 GB
     8       ~80 km  ~1.6 GB             21     ~10 m   ~4.9 GB
     9       ~40 km  ~1.7 GB             22      ~5 m   ~5.1 GB
    10       ~20 km  ~1.9 GB             23      ~2 m   ~5.4 GB
    11       ~10 km  ~2.1 GB             24      ~1 m   ~5.6 GB
  

  For reference, the memory usage of the array of 1 million random, unindexed points is about 440 MB, growing to about 540 MB with index use (about 100 bytes per point); the former amount is included in the index memory usage shown above.

• function_type
  Choose the type of low-level functions to use. (default: 'double' if available, 'perl' otherwise)

  Geo::Index will attempt to use compiled C code to speed up certain calculations.
  If the compilation fails then equivalent (but slower) Perl code will be used.

  This option can be used to explictly request the type of code to use. When set to 'float' then compiled C code using single-precision floating point will be requested. When set to 'double' then compiled C code using double-precision floating point will be requested. When set to 'perl' then Perl code will be used. If compilation failed then Perl code will be used regardless of what was requested.

  Perl natively uses double-precision floating point. On modern hardware double-precision is slightly faster than single-precision. On certain platforms, however, it may be preferable to use single-precision instead of double-precision floating point. When needed, using single-precision should not be an issue since the minor errors introduced from loss of precision are drowned out by the errors inherent in the haversine function that is used for distance calculations.

  Prior to v0.0.4, Geo::Index used Inline::C to compile code. If you are running v0.0.3 or earlier and your program is running on a server then read this page for server-specific notes.