11,412,833 members (74,708 online)

# ZIP Code Utility

, 2 Jan 2005 CPOL
 Rate this:
Please Sign up or sign in to vote.
This article provides an easy method to lookup a U.S. City/State by ZIP Code, or one or more ZIP Codes by City/State. It also describes a method to calculate the distance between two ZIP Codes and find all other ZIP Codes within a radius of X miles of a specified ZIP Code.

## Introduction

Intrigued by Ben Fry's zipdecode [^] applet, I decided to write a little ZIP Code utility that allows lookups of U.S. locations by ZIP Code, City/State, or all three. Since the data were already in the database in the form of latitude/longitude pairs, I added the capability to find the distance between two points, and to find all other ZIP Codes within a radius of X miles from the original location.

## Background

### Database

The MS Access database contains the following fields:

Field Name Description
ZIP The ZIP Code
LATITUDE Latitude coordinate (decimal degrees)
LONGITUDE Longitude coordinate (decimal degrees)
CITY City name
STATE State abbreviation
COUNTY County name
ZIP_CLASS ZIP Code class

### ZIP Code — City/State lookups

The lookups are straightforward database queries using the `OleDb*` classes.

### Distance calculation

To calculate the distance between two points, I used the Haversine Formula, which I found on the Ask Dr. Math web site.

### ZIP Codes within a radius of X miles

Most ZIP Codes in the database contain latitude/longitude coordinates. To make the SQL query as simple as possible, I used a square of size 2Rx2R (where R is the radius of the circle) to encompass the search area as shown in the figure below.

This has the unfortunate side effect of searching an area ~22% larger than needed, but these "outliers" are filtered out of the result set on the client side before being returned to the calling application. I could have added a stored procedure to perform the distance calculation, but I didn't want to modify the database in any way. That way, if the author decides to update the data, (hopefully) all the users of this library will have to replace the old database file with the new one.

Now, using this approximation, the SQL query becomes as simple as this:

```SELECT *
FROM ZIP_CODES
WHERE
LATITUDE >= <Southern Latitude Line> AND
LATITUDE <= <Northern Latitude Line> AND
LONGITUDE >= <Western Longitude Line> AND
LONGITUDE <= <Eastern Longitude Line>```

To calculate the Northern/Southern Latitude and Western/Eastern Longitude lines, I again turned to Ask Dr. Math.

### Important classes

Class Name Description
`ZipCodeUtil` The `ZipCodeUtil` class provides methods to lookup City/State by ZIP Code, or ZIP Code by City/State.
`Location` A `Location` represents a City, State, ZIP Code, County, Latitude, Longitude, and ZIP Class. This just so happens to correspond to the columns of the ZIP_CODES table.
`LocationInRadius` Derives from `Location`, and adds the `DistanceToCenter` property.
`Distance` The `Distance` class' `static` `GetDistance` method takes two `Location` objects and uses their Latitudes and Longitudes to determine the distance between them.
`Radius` Provides a `static` method that takes a `Location` and a radius (in miles), and returns the `LocationInRadius`es that fall within that radius.

## Using the code

Using the code is very straightforward.

1. Download the ZIP Codes database (see link at top of article).
2. Compile the ZipCodeUtil library in VS.NET.
3. Add a reference to the new DLL (SagaraSoftware.ZipCodeUtil.dll) to your application.
4. Add the following `appSettings` to your application's config file (you'll need to add a config file if one doesn't already exist):
`<add key="ZipCodeProviderType" value="Access" />`
```<add key="ZipCodeConnString" value=
"Provider=Microsoft.Jet.OLEDB.4.0;Data Source=
D:\Example\Path\To\Database\zipbase.mdb" />```
5. Add code to use the ZIP Code Utility library.

Here is the sample code from the example application:

(Note that in order to run the sample application, you'll first need to download the database and modify the config file to point to the database on your hard disk.)

```//    Location by ZIP Code.
Location location = ZipCodeUtil.LookupByZipCode ("93275");
if (null != location)
Console.WriteLine (location.ToString ());

//    Location(s) by City/State.
Location[] locs = ZipCodeUtil.LookupByCityState ("Tulare", "CA");
if (null != locs && locs.Length > 0)
{
foreach (Location loc in locs)
{
Console.WriteLine (loc.ToString ());
}
}

//    Location by City/State/Zip
location = ZipCodeUtil.LookupByCityStateZip ("Tulare", "CA", "93275");
if (null != location)
Console.WriteLine (location.ToString ());

//    Distance between two locations.
Location sf = ZipCodeUtil.LookupByZipCode ("94175");
Location la = ZipCodeUtil.LookupByZipCode ("90185");
Double dDistance = sf.DistanceFrom (la);
Console.WriteLine ("{0} is {1} miles from {2}", sf.City, dDistance, la.City);

//    Other Locations within an X-mile radius of a specific location.
locs = sf.LocationsWithinRadius (5.0);
if (null != locs && locs.Length > 0)
{
foreach (Location loc in locs)
{
Console.WriteLine (loc.ToString ());
}
}```

## Limitations

This library relies on data from a free database that doesn't look like it has been updated since September 2001. I cannot vouch for the accuracy of this data. If you plan on using this in a production environment, you may want to invest in a commercial ZIP Codes database that is guaranteed by its maker and that is updated regularly.

## To do List

• Pending approval from the creator of the database, provide MS SQL and MySQL versions.

## History

• 2nd Jan 2005 - Version 1.0.0
• Initial release.

## License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)

## About the Author

Software Developer (Senior) Sagara Software, Inc.
United States
Jon graduated from Cal Poly with a B.S. Computer Engineering. He is currently building a Silverlight-based report scheduling interface for a pharmaceutical reporting company.

When he's not fooling around with computers or reading, he's busy spending time with his super wife, Kelly, his two boys, and their rambunctious dog, Homer.

Visit my blog
Follow on

## Comments and Discussions

 First Prev Next
 My vote of 5 manoj kumar choubey at 13-May-13 0:32 manoj kumar choubey 13-May-13 0:32
 zip code radius Peter Hammer at 7-May-13 1:56 Peter Hammer 7-May-13 1:56
 Re: zip code radius Member 2233844 at 28-Feb-14 5:38 Member 2233844 28-Feb-14 5:38
 Message Automatically Removed at 30-Aug-08 17:51 DotNetGuts 30-Aug-08 17:51
 Zip Code Radius Search Solution codezilla94 at 12-Nov-07 15:13 codezilla94 12-Nov-07 15:13
 Re: Zip Code Radius Search Solution Jon Sagara at 12-Nov-07 16:31 Jon Sagara 12-Nov-07 16:31
 Missing Database ellios at 5-Dec-06 2:55 ellios 5-Dec-06 2:55
 Re: Missing Database [modified] Jon Sagara at 5-Dec-06 5:11 Jon Sagara 5-Dec-06 5:11
 Re: Missing Database marsh wiggle at 5-Dec-12 11:43 marsh wiggle 5-Dec-12 11:43
 GUI, GUI, GUI Bassam Abdul-Baki at 9-May-06 4:34 Bassam Abdul-Baki 9-May-06 4:34
 Stuffing data in a DLL? HyperX at 15-Feb-06 7:32 HyperX 15-Feb-06 7:32
 Re: Stuffing data in a DLL? Jon Sagara at 15-Feb-06 7:51 Jon Sagara 15-Feb-06 7:51
 Re: Stuffing data in a DLL? Spiff Dog at 7-Dec-11 8:39 Spiff Dog 7-Dec-11 8:39
 Missing dlls mtone at 1-Feb-06 12:13 mtone 1-Feb-06 12:13
 THis looks great and I really need this. It appears to be missing the AcccesPrvider and IDataProvider files Do you have them? Thanks
 Re: Missing dlls Jon Sagara at 1-Feb-06 12:17 Jon Sagara 1-Feb-06 12:17
 Re: Missing dlls mtone at 1-Feb-06 12:26 mtone 1-Feb-06 12:26
 Filtering "Outliers" eanderson at 12-Jan-05 11:04 eanderson 12-Jan-05 11:04
 I knew I shoulda written! eanderson at 12-Jan-05 9:46 eanderson 12-Jan-05 9:46
 Re: I knew I shoulda written! DavidCrow at 12-Jan-05 10:55 DavidCrow 12-Jan-05 10:55
 Re: I knew I shoulda written! Jon Sagara at 12-Jan-05 10:57 Jon Sagara 12-Jan-05 10:57
 Re: I knew I shoulda written! eanderson at 12-Jan-05 11:00 eanderson 12-Jan-05 11:00
 Re: I knew I shoulda written! ethanselzer at 10-Feb-05 15:45 ethanselzer 10-Feb-05 15:45
 Re: I knew I shoulda written! renzea at 1-May-06 12:59 renzea 1-May-06 12:59
 Last Visit: 31-Dec-99 19:00     Last Update: 26-Apr-15 19:06 Refresh 1

General    News    Suggestion    Question    Bug    Answer    Joke    Rant    Admin

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Terms of Use | Mobile
Web01 | 2.8.150427.1 | Last Updated 2 Jan 2005
Article Copyright 2005 by Jon Sagara
Everything else Copyright © CodeProject, 1999-2015
Layout: fixed | fluid