PHP Zip Code Range and Distance Calculation

This class has been replaced by a new class using PHP 5 style class syntax with numerous bug fixes and speed improvements. See: PHP 5 Zip Code Range and Distance Calculation.

This is a PHP class to do various calculations with zip codes. It's primary purposes are to calculate the distance between two zip codes and to extract all the zip codes that are within a range of a given zip code. All calculations are based on lattitude and longitude coordinates stored in the database. Included is a class file, demonstration file, and the sql files required to create and populate the MySQL tables.

Planet Source Code Superior Code Winner!

Download: Download Zip Code Range and Distance Script

Here is a Postgresql port of the zip code database to contributed by max:

Version History
  • v1.2.0 [Oct 22, 2006] - Using a completely new database based on user contributions which resolves many data bugs. Added sorting to get_zips_in_range(), added ability to include/exclude the base zip from get_zips_in_range()
  • v1.1.0 [Apr 30, 2005] - Added Jeff Bearer''s code to make it MUCH faster!
  • v1.0.1 [Apr 22, 2005] - Fixed a typo :)
  • v1.0.0 [Apr 12, 2005] - Initial Version
Screenshot of the MySQL database class in action

Setting up the Database

There are 6 files in the /sql directory which contain SQL statements intended for a MySQL database (though they should work just fine for any SQL database). The zip code database consists of over 40,000 records which would be too large a file for many configurations of phpMyAdmin. Therefore, I have broken the data into records of 10,000 resulting in 5 files. In phpMyAdmin, you can import these 6 files 1 at a time using the ''Import'' tab. You MUST import the ''create_table.sql'' file first, then each of the data files. create_table.sql
data_5.sql The database has changed since the last version. The data itself is comprised of data from multiple sources starting with the 2000 and 2004 US Census data. Unlike version 1.x of this class, the database is no longer comprised of a state AND zip_code table, but a single zip_code table. Additionally, the table is created with an index on the zip_code column.

The Class: zipcode.class.php


// constants for setting the $units data member
define(''_UNIT_MILES'', ''m'');
define(''_UNIT_KILOMETERS'', ''k'');

// constants for passing $sort to get_zips_in_range()
define(''_ZIPS_SORT_BY_DISTANCE_ASC'', 1);
define(''_ZIPS_SORT_BY_ZIP_ASC'', 3);
define(''_ZIPS_SORT_BY_ZIP_DESC'', 4);

// constant for miles to kilometers conversion
define(''_M2KM_FACTOR'', 1.609344);

Data Members

decimals Read/Write. When returning distance values, this variable determines how many decimal places the result should be rounded to.
last_error Read-only. Holds a string value of the last error that occured. This can be used should a method return an error value to get a human readable version of the error.
last_time Read-only. Holds the last method execution time used to debug the efficiency of the get_zips_in_range() method.
units Read/Write. Holds the type of units to show results in. Must be either _UNITS_MILES or _UNITS_KILOMETERS


calculate_mileage($lat1, $lat2, $lon1, $lon2) Calculates the mileage between the two lattitude/longitude points: $lat1/$lon1 and $lat2/$lon2.
chronometer() Chronometer function from PHP manual used to time execution of get_distance() and get_zips_in_range() methods.
get_distance($zip1, $zip2) Returns the distance between the two zip codes: $zip1 and $zip2. If there is an error, false is returned. Since the function can return 0 when 2 zips are the same, you must evaluate for an error condition using: if (get_distance($zip1, $zip2) === false) // error condition
get_zip_details($zip) Returns the details about the zip code: $zip. Details are in the form of a keyed array. The keys are: latitude, longitude, city, county, state_prefix, state_name, area_code, and time_zone. All are pretty self-explanitory. Returns false on error.
get_zip_point($zip) Gets the lattitude and longitude coordinates of the given zip code as a keyed array. The keys are: lat and lon. Returns false on error.
get_zips_in_range($zip, $range, $sort,$include_base) Finds all zip codes within $range from $zip as a keyed array sorted by $sort. If $include_base is set to true or not specified, then $zip is included in the results. If it is set to false, then $zip is excluded from results. Possible values for $sort are: _ZIPS_SORT_BY_DISTANCE_ASC (default), _ZIPS_SORT_BY_DISTANCE_DESC, _ZIPS_SORT_BY_ZIP_ASC, _ZIPS_SORT_BY_ZIP_DESC. The return value is a keyed array where the key is the zip code and the value is the distance from the base zip $zip. Returns false on error.
Did you enjoy PHP Zip Code Range and Distance Calculation? If you would like to help support my work, A donation of a buck or two would be very much appreciated.
blog comments powered by Disqus
Linux Servers on the Cloud IN MINUTES