Click here to Skip to main content
11,409,854 members (63,455 online)
Click here to Skip to main content
Articles » Languages » C# » Utilities » Downloads
Add your own
alternative version

ZIP Code Utility

, 2 Jan 2005 CPOL
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.
#region FILE HEADER
/// <project>ZipCodeUtil</project>
/// <assembly>SagaraSoftware.ZipCodeUtil.dll</assembly>
/// <filename>ZipCodeUtil.cs</filename>
/// <creator>Jon Sagara</creator>
/// <description>
/// Contains the ZipCodeUtil class.  The user will use this class to perform ZIP Code and City/State
///  lookups.
/// </description>
/// <copyright>
/// Copyright (c) 2004 Sagara Software.  All rights reserved.
/// </copyright>
/// <disclaimer>
/// This file is provided "as is" with no expressed or implied warranty.  The author accepts no 
///  liability for any damage/loss of business that this product may cause.
/// </disclaimer>
/// <history>
///	<change date="12/29/2004" changedby="Jon Sagara">File created.</changed>
/// </history>
#endregion

using System;
using System.Diagnostics;

namespace SagaraSoftware.ZipCodeUtil
{
	/// <summary>
	/// The ZipCodeUtil class provides methods to lookup City/State by ZIP Code, or ZIP Code by 
	/// City/State.
	/// </summary>
	/// <remarks>
	/// <para>Note that when looking up a ZIP Code by City/State, it is quite possible that more 
	/// than one <see cref="SagaraSoftware.ZipCodeUtil.Location" /> will be returned.</para>
	/// <para>When looking up a City/State by ZIP Code, only one <see cref="SagaraSoftware.ZipCodeUtil.Location" /> 
	/// will be returned.  ZIP Code is the Primary Key in the database.</para>
	///	</remarks>
	public class ZipCodeUtil
	{
		/// <summary>
		/// Queries the database for a City/State whose ZIP Code matches inZipCode.
		/// </summary>
		/// <param name="inZipCode">The ZIP Code to search by.</param>
		/// <returns>If a matching ZIP Code was found in the database, a <see cref="SagaraSoftware.ZipCodeUtil.Location" />
		///  object containing information about that ZIP Code.  Otherwise, returns null.</returns>
		public static Location LookupByZipCode (String inZipCode)
		{
			Debug.Assert (null != inZipCode);
			Debug.Assert (String.Empty != inZipCode);

			if (null == inZipCode)
				throw new ArgumentNullException ("inZipCode");
			if (String.Empty == inZipCode)
				throw new ArgumentException ("You must specify a ZIP Code when calling this method.", "inZipCode");

			Location loc = null;
			IDataProvider db = null;

			try
			{
				db = DataProvider.GetDataProvider ();

				if (null != db)
					loc = db.DoLookupByZipCode (inZipCode);
			}
			catch (Exception e)
			{
				// JonJon: Need to implement logging.
				throw new ApplicationException ("Rethrowing exception", e);
			}

			return loc;
		}


		/// <summary>
		/// Looks up a City/State by City/State.  It is possible for more than one <see cref="SagaraSoftware.ZipCodeUtil.Location" />
		///  to be returned since there are City/State combos that contain more than one ZIP Code.
		/// </summary>
		/// <param name="inCity">The search city.</param>
		/// <param name="inState">The search state.</param>
		/// <returns>If any matches were found, an array of <see cref="SagaraSoftware.ZipCodeUtil.Location" /> objects.  Otherwise, null.</returns>
		public static Location[] LookupByCityState (String inCity, String inState)
		{
			Debug.Assert (null != inCity);
			Debug.Assert (String.Empty != inCity);
			Debug.Assert (null != inState);
			Debug.Assert (String.Empty != inState);

			if (null == inCity)
				throw new ArgumentNullException ("inCity");
			if (String.Empty == inCity)
				throw new ArgumentException ("You must specify a City when calling this method.", "inCity");
			if (null == inState)
				throw new ArgumentNullException ("inState");
			if (String.Empty == inState)
				throw new ArgumentException ("You must specify a State when calling this method.", "inState");

			Location[] locs = null;
			IDataProvider db = null;

			try
			{
				db = DataProvider.GetDataProvider ();

				if (null != db)
					locs = db.DoLookupByCityState (inCity, inState);
			}
			catch (Exception e)
			{
				// JonJon: Need to implement logging.
				throw new ApplicationException ("Rethrowing exception", e);
			}

			return locs;
		}


		/// <summary>
		/// Looks up a City/State by City/State/ZIP.
		/// </summary>
		/// <param name="inCity">The search city.</param>
		/// <param name="inState">The search state.</param>
		/// <param name="inZipCode">The search ZIP Code.</param>
		/// <returns>If a match is found, then a <see cref="SagaraSoftware.ZipCodeUtil.Location" /> objectd.
		///  Otherwise, null.</returns>
		public static Location LookupByCityStateZip (String inCity, String inState, String inZipCode)
		{
			Debug.Assert (null != inCity);
			Debug.Assert (String.Empty != inCity);
			Debug.Assert (null != inState);
			Debug.Assert (String.Empty != inState);
			Debug.Assert (null != inZipCode);
			Debug.Assert (String.Empty != inZipCode);

			if (null == inCity)
				throw new ArgumentNullException ("inCity");
			if (String.Empty == inCity)
				throw new ArgumentException ("You must specify a City when calling this method.", "inCity");
			if (null == inState)
				throw new ArgumentNullException ("inState");
			if (String.Empty == inState)
				throw new ArgumentException ("You must specify a State when calling this method.", "inState");
			if (null == inZipCode)
				throw new ArgumentNullException ("inZipCode");
			if (String.Empty == inZipCode)
				throw new ArgumentException ("You must specify a ZIP Code when calling this method.", "inZipCode");

			Location loc = LookupByZipCode (inZipCode);
			if (null != loc)
			{
				if (inCity.ToUpper () != loc.City.ToUpper () || inState.ToUpper () != loc.State.ToUpper ())
					throw new ApplicationException (string.Format ("The City/State you specified does not match the City/State associated with ZIP Code {0}", inZipCode));
			}

			return loc;
		}
	}
}

By viewing downloads associated with this article you agree to the Terms of Service and the article's licence.

If a file you wish to view isn't highlighted, and is a text file (not binary), please let us know and we'll add colourisation support for it.

License

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

Share

About the Author

Jon Sagara
Software Developer (Senior) Sagara Software, Inc.
United States 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   Twitter

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