Recently, a client wanted a member search for his website that included a search by zip code. The ‘easy’ solution would be to implement the search as a LIKE statement in SQL, but the solution is inaccurate, and I like the ‘good’ solutions over the ‘easy’ ones. I looked for a CodeIgniter library that would give me the functionality for which I wanted to implement, but no such thing existed. Then, I came across Micah Carrick’s native PHP library which gave the exact functionality I was looking for. I did end up using his library, but not without modification: I’ve ported the native library to a CodeIgniter library. This is where you can get it, but first you should look at the demo.

Demo

The Code

First, you’ll need to create your database. You can use this MySQL script to create the table.

CREATE TABLE `zip_code` (
  `id` int(11) unsigned NOT NULL auto_increment,
  `zip_code` varchar(5) collate utf8_bin NOT NULL,
  `city` varchar(50) collate utf8_bin default NULL,
  `county` varchar(50) collate utf8_bin default NULL,
  `state_name` varchar(50) collate utf8_bin default NULL,
  `state_prefix` varchar(2) collate utf8_bin default NULL,
  `area_code` varchar(3) collate utf8_bin default NULL,
  `time_zone` varchar(50) collate utf8_bin default NULL,
  `lat` float NOT NULL,
  `lon` float NOT NULL,
  PRIMARY KEY  (`id`),
  KEY `zip_code` (`zip_code`)

You will need to populate the table, of course, and you will do so with the MySQL scripts included in the project.

Download the project.

Now, for the meat and potatoes. Here is the library itself. It is GPL Version 3 licensed so keep that in mind if you decide to use it.

How to use

The library supports 3 main features right now: get zip details, get distance between 2 zip codes, and get a list of zip codes in a given radius of another zip code. The library supports miles and kilometers as distance units. I’ll demonstrate how to use each of these functions, and how to change the units.

Copy the code above into a file named geozip.php and place it in the application/libraries folder in your CodeIgniter installation. Then, in whatever controller you want to use it in, load it like you would any other library.

$this->load->library("geozip");

Getting and displaying the zip’s details are simple. In the controller, you would do

$zip_details = $this->geozip->get_zip_details($this->input->post("zip"));
$data['zip_details'] = $zip_details;

and then in the view, you could access the following variables:

echo $zip_details->lattitude;
echo $zip_details->longitude;
echo $zip_details->city;
echo $zip_details->county;
echo $zip_details->state_prefix;
echo $zip_details->state_name;
echo $zip_details->area_code;
echo $zip_details->time_zone;

Getting the distance between 2 zips is equally as easy.

$distance = $this->geozip->get_distance("90210", "60601");

Doing a radial search is only slightly more complicated, but only because you have some options when you call the function. The function accepts 4 parameters: the zip code, the range to cover, sort order, and whether or not to include the original zip in the result set. The default sort order is sorted by distance ascending, and the default ‘include base’ is true. You can change the default sort order using the following defines, and you can change the ‘include base’ by setting it to boolean false.

// constants for passing $sort to get_zips_in_range()
define('SORT_BY_DISTANCE_ASC', 1);
define('SORT_BY_DISTANCE_DESC', 2);
define('SORT_BY_ZIP_ASC', 3);
define('SORT_BY_ZIP_DESC', 4);

Here is how you could find all the zips in a 20 mile radius of Beverly Hills sorted by zip ascending, but not including Beverly Hills.

$zips = $this->geozip->get_zips_in_range("90210", 20, SORT_BY_ZIP_ASC, false);
$data['zips'] = $zips;

$zips will be an associative array with the zip code as the key and the distance from the origin zip as the value. You can process this in your controller or view as you see fit.

foreach($zips as $zip => $distance)
{
    echo "$zip is $distance miles away from the origin.";
	//or other processing you wish to do with these zips.
}

I did say that the library supports miles and kilometers. To change between them, simply do

$this->geozip->set_units("kilos"); //only accepts "miles" or "kilos"

And any function that returns a distance will return whichever unit you’ve specified.

Things to remember

The biggest problem with this approach is the database. As stated in the original blog by Micah, the database was derived from a variety of sources and may be out of date. Depending on how critical this feature is to your application, the current database may or may not work. If you want an up to date database, you’ll probably have to purchase and import it yourself.

You can download an example application that is ready to deploy, but it is likely to become outdated as time passes and I make feature and bug changes. You can always get the latest version in the BitBucket repo.

If you have any questions or comments, post them here and I’ll be sure to answer them! You can also contact me if your issues should remain private. Happy coding!