No description, website, or topics provided.
Perl
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
data
lib/Geo/PostalCode
script
t
Changes
MANIFEST
MANIFEST.SKIP
META.yml
Makefile.PL
README

README

NAME
    Geo::PostalCode::NoBD - Find closest zipcodes, distance, latitude, and
    longitude; no Berkeley DB.

SYNOPSIS
      use Geo::PostalCode::NoBD;

      my $gp = Geo::PostalCode::NoBD->new(csvfile => "us_zip_codes.csv");

      my $record = $gp->lookup_postal_code(postal_code => '07302');
      my $lat   = $record->{lat};
      my $lon   = $record->{lon};
      my $city  = $record->{city};
      my $state = $record->{state};

      my $distance = $gp->calculate_distance(postal_codes => ['07302','10004']);

      my $record = $gp->lookup_city_state(city => "Jersey City",state => "NJ");
      my $lat          = $record->{lat};
      my $lon          = $record->{lon};
      my $postal_codes = $record->{postal_codes};

      my $postal_codes = $gp->nearby_postal_codes(lat => $lat, lon => $lon,
                                                       distance => 50);

DESCRIPTION
    Geo::PostalCode::NoBD is almost the same as Geo::PostalCode, except that
    all Berkeley DB support has been removed in favor of loading the entire
    CSV database into memory.

ORIGINAL DESCRIPTION
    This is a module for calculating the distance between two postal codes.
    It can find the postal codes within a specified distance of another
    postal code or city and state. It can lookup the city, state, latitude
    and longitude by postal code.

RATIONALE BEHIND NO BERKELEY DB
    On a busy day at work, I couldn't get Geo::PostalCode to work with newer
    data (the data source TJMATHER points to is no longer available), so the
    tests shippsed with his module pass, but trying to use real data no
    longer seems to work. DB_File marked the Geo::PostalCode::InstallDB
    output file as invalid type or format. If you don't run into that issue
    by not wanting to use this module, please drop me a note! I would love
    to learn how other people made it work.

    So, in order to get my shit done, I decided to create this module.
    Loading the whole data into memory from the class constructor has been
    proven to be enough for massive usage (citation needed) on a Dancer
    application where this module is instantiated only once.

DATA
    I have mirrored working data at:

    http://damog.net/files/misc/zipcodes-csv-10-Aug-2004.zip

    Take a minute to go through its README to learn where this data comes
    from and potentially send a thank you note to those who made it
    available.

METHODS
    $gp = Geo::PostalCode::NoDB->new(csvfile => $csv_file_path, [units => mi
    | km ,] [earth_radius => earth_radius_in_desired_units ,] );
        Returns a new Geo::PostalCode::NoDB object.

        You can control the distance units used by providing a `units'
        option, which can be `mi' for miles (the default) or `km' for
        kilometers, or by providing a `earth_radius' option set to the
        radius of the Earth in your desired unit. The Earth's radius is
        approximately 3956 miles.

    $record = $gp->lookup_postal_code(postal_code => $postal_code);
        Returns a hash reference containing four keys:

          * lat - Latitude
          * lon - Longitude
          * city - City
          * state - State two-letter abbreviation.

    $record = $gp->lookup_city_state(city => $city, state => $state);
        Returns a hash reference containing three keys:

          * lat - Latitude (Average over postal codes in city)
          * lon - Longitude (Average over postal codes in city)
          * postal_codes - Array reference of postal codes in city

    $miles = $gp->calculate_distance(postal_codes => \@postal_codes);
        Returns the distance in miles between the two postal codes in
        @postal_codes.

    $postal_codes = $gp->nearby_postal_codes(lat => $lat, lon => $lon,
    distance => $distance );
        Returns an array reference containing postal codes with $distance
        miles of ($lat, $lon).

    $postal_codes = $gp->query_postal_codes(lat => $lat, lon => $lon,
    distance => $distance, select => \@select, order_by => $order_by );
        Returns an array reference of hash references with $distance miles
        of ($lat, $lon). Each hash reference contains the following fields:

          * postal_code - Postal Code
          * lat - Latitude (If included in @select)
          * lon - Longitude (If included in @select)
          * city - City (If included in @select)
          * state - State two-letter abbreviation (If included in @select)

        If $order_by is specified, then the records are sorted by the
        $order_by field.

NOTES
    This module is in early alpha stage. It is suggested that you look over
    the source code and test cases before using the module. In addition, the
    API is subject to change.

    The distance routine is based in the distance routine in Zipdy. Zipdy is
    another free zipcode distance calculator, which supports PostgreSQL. It
    is available from http://www.cryptnet.net/fsp/zipdy/

AUTHOR
    Geo::PostalCode::NoDB module:

    Copyright (c) 2012, David Moreno `david@axiombox.com'.

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

    Geo::PostalCode module:

    Copyright (c) 2006, MaxMind LLC, http://www.maxmind.com/

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

CREDITS
    Thanks to Scott Gifford of http://homesurfusa.com/ for contributing
    multiple bug fixes and code cleanup.

SEE ALSO
        Geo::PostalCode - Find closest zipcodes, distance, latitude, and
        longitude

        Geo::IP - Look up country and city by IP Address

        zipdy - Free Zip Code Distance Calculator