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->nearby_postal_codes(lat => $lat, lon => $lon,
                                                   distance => 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, [cachesize => btree_cache_size | max ,] [units => mi | km ,] [earth_radius => earth_radius_in_desired_units ,] );

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

You can override the cache used by the BTree in DB_File by setting the cachesize parameter to the desired size of the cache, in bytes. You can set it to max to set it to the size of the largest of the databases used.

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

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::IP - Look up country and city by IP Address

zipdy - Free Zip Code Distance Calculator