NAME

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

SYNOPSIS

  use Geo::PostalCode;

  my $gp = Geo::PostalCode->new(db_dir => ".");

  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->find_nearby_postal_codes($lat, $lon,
                                                   miles => 50);

DESCRIPTION

Geo::Postalcode 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.

The data is from the 1999 US Census database of U.S. Postal Codes, available from http://www.census.gov/geo/www/tiger/zip1999.html.

To access the data, it uses Berkeley DB, which is fast and portable (most Linux/Unix servers have it pre-installed.)

METHODS

$gp = Geo::PostalCode->new(db_dir => $db_dir);

Returns a new Geo::PostalCode object using the postalcode.db, latlon.db, and city.db Berkeley Database files in $db_dir.

$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, miles => $miles );

Returns an array reference containing postal codes with $miles miles of ($lat, $lon).

$postal_codes = $gp->query_postal_codes(lat => $lat, lon => $lon, miles => $miles, select => \@select, order_by => $order_by );

Returns an array reference of hash references with $miles 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

Copyright (c) 2001, T.J. Mather, tjmather@tjmather.com

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

SEE ALSO

Geo::IP - Look up country by IP Address

zipdy - Free Zip Code Distance Calculator