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


  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);


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

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


$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, 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.


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


Copyright (c) 2002, T.J. Mather,

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


Thanks to Scott Gifford for contributing multiple bug fixes and code cleanup.


    Geo::IP - Look up country by IP Address

    zipdy - Free Zip Code Distance Calculator