/ 
Geo-PostalCode-NoDB-0.01
River stage zero No dependents
/ Geo::PostalCode::NoDB

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