net.christopherschultz.util.zipcode
Class ZipCode

java.lang.Object
  extended by net.christopherschultz.util.zipcode.ZipCode
All Implemented Interfaces:
Serializable, Comparable

public class ZipCode
extends Object
implements Comparable, Serializable

A US-postal code.

Although the latitude and longitude are usually for the post office that serves each zip code, the value doesn't matter a whole lot. Zip codes are usually fairly small, so any latitude/longitude value within the zip code will work for most purposes.

See Also:
Serialized Form

Constructor Summary
ZipCode(int code, double latitude, double longitude)
          Creates a new ZipCode object.
 
Method Summary
static double arc_length(double lat1, double lon1, double lat2, double lon2)
           
 int compareTo(Object o)
          Compares the specified object to this one.
 boolean equals(Object o)
          Returns true if the specifed object is equal to this one.
 double getArcLength(ZipCode zip)
          Gets the length of the great circle arc, in radians, between this ZipCode and the specified ZipCode.
 double getDistanceInKilometers(ZipCode zip)
          Gets the distance, in kilometers, from this ZipCode to the specified ZipCode.
 double getDistanceInMiles(ZipCode zip)
          Gets the distance, in miles, from this ZipCode to the specified ZipCode.
 double getLatitude()
          Gets the latitude of the post office serving this zip code.
 double getLongitude()
          Gets the longitude of the post office serving this zip code.
 int getZipCode()
          Gets the 5-digit zip code for this ZipCode.
 String toString()
          Returns a String representation of this ZipCode (i.e.
 
Methods inherited from class java.lang.Object
getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ZipCode

public ZipCode(int code,
               double latitude,
               double longitude)

Creates a new ZipCode object.

Parameters:
code - The 5-digit zip code that the new ZipCode will represent.
latitude - The latitude, in decimal degress, of the post office serving this zip code.
longitude - The longitude, in decimal degress, of the post office serving this zip code.
Method Detail

getZipCode

public int getZipCode()

Gets the 5-digit zip code for this ZipCode.

Returns:
The 5-digit zip code for this ZipCode.

getLatitude

public double getLatitude()

Gets the latitude of the post office serving this zip code.

Returns:
The latitude of the post office serving this zip code.

getLongitude

public double getLongitude()

Gets the longitude of the post office serving this zip code.

Returns:
The longitude of the post office serving this zip code.

getDistanceInMiles

public double getDistanceInMiles(ZipCode zip)

Gets the distance, in miles, from this ZipCode to the specified ZipCode.

This method uses the getArcLength(net.christopherschultz.util.zipcode.ZipCode) method to calculate the arc distance between the latitudes and longitudes for the two zip codes, then multiplies by the radius of the Earth in miles.

Parameters:
zip - The ZipCode for which the distance to this one should be calculated.
Returns:
The distance, in miles, from this ZipCode to the specified ZipCode.
See Also:
getArcLength(net.christopherschultz.util.zipcode.ZipCode)

getDistanceInKilometers

public double getDistanceInKilometers(ZipCode zip)

Gets the distance, in kilometers, from this ZipCode to the specified ZipCode.

This method uses the getArcLength(net.christopherschultz.util.zipcode.ZipCode) method to calculate the arc distance between the latitudes and longitudes for the two zip codes, then multiplies by the radius of the Earth in kilometers.

Parameters:
zip - The ZipCode for which the distance to this one should be calculated.
Returns:
The distance, in kilometers, from this ZipCode to the specified ZipCode.
See Also:
getArcLength(net.christopherschultz.util.zipcode.ZipCode)

getArcLength

public double getArcLength(ZipCode zip)

Gets the length of the great circle arc, in radians, between this ZipCode and the specified ZipCode.

This method uses the haversine formula, which is supposed to be more accurate for small distances. Since this will likely be used for small distances, this algorithm was chosen.

References: http://mathforum.org/library/drmath/view/51879.html

Parameters:
zip - The zip code for which the arc length should be calculated.
Returns:
The length of the great circle arc, in radians, between this ZipCode and the specified ZipCode.

arc_length

public static double arc_length(double lat1,
                                double lon1,
                                double lat2,
                                double lon2)
See Also:
getArcLength(net.christopherschultz.util.zipcode.ZipCode)

toString

public String toString()

Returns a String representation of this ZipCode (i.e. "20005" or "00621").

Overrides:
toString in class Object
Returns:
A String representation of this ZipCode (i.e. "20005" or "00621").

compareTo

public int compareTo(Object o)

Compares the specified object to this one.

This allows sorting based upon numeric value of the Zip Code.

Specified by:
compareTo in interface Comparable
See Also:
Comparable.compareTo(java.lang.Object)

equals

public boolean equals(Object o)

Returns true if the specifed object is equal to this one.

Equality in this case is defined as the other object being a ZipCode and having the same zipCode as this one.

Overrides:
equals in class Object
Returns:
true if the specified object is equal to this one, false otherwise.