Language Filter: Display content for

ZIPCodeDownload.com Distance Wizard API

DISTANCE WIZARD API

Click for larger view
Click to see a larger representation
of Distance and Boundary Wizards.

(This is the same documentation which ships with the product.)

ZIP Code Download's Distance Wizard provides functionality for calculating the distance between two points on Earth's surface. Combined with a database of ZIP/postal code coordinates, Distance Wizard can help perform many practical tasks, such as locating nearby storefronts or presenting geo-targeted ads to visitors.

Standard Edition is faster than competitors' products and easy to use. Professional Edition boasts ultra-high performance and is bundled with smart boundary technology to greatly enhance the speed of your database queries.

For example, to find all the postal codes in North America (US, Canada, Mexico) within 10 miles of 58271 (Pembina, North Dakota, USA, located a few miles from the Canadian border), your application would query over a million rows of data and process several calculations for each row to find maybe a dozen postal codes that are within 10 miles.

The Professional Edition calculates smart boundaries and exponentially reduces the number of rows involved from millions to just dozens, making it dramatically faster. View the complete examples to see how it works with some sample data.

These tools comprise a small code library of two main parts:

  1. Distance Wizard - to calculate the distance between two coordinates.
  2. Boundary Wizard - to find geolocational boundaries of a certain radius from a coordinate of origin. (Professional Edition only)

The ZIP Code Download Distance Wizard can be utilized in 14 different languages and platforms including:

  • ASP
  • C
  • C#
  • C++
  • ColdFusion
  • Java
  • MS SQL 2000 (or later)
  • MySQL 5 (or later)
  • Oracle 9 (or later)
  • Perl
  • PHP
  • VB.NET
  • Visual Basic 6
  • VBA (Microsoft Access and Microsoft Excel)

This documentation explains how to use the language of your choice to work with the API. It also includes usable sample source code.

There is a language filter at the top to display content for your specific platform.

Feature Matrix

Below is an overall comparison of the Standard and Professional editions of Distance Wizard.

Feature Comparison

Distance Wizard
Standard Edition		 Distance Wizard
Professional Edition
Calculates distance between two coordinates on Earth YES YES
Integrates with ZIP Code Download's ZIP Code Databases YES YES
Integrates with my own table of location data YES YES
Enables faster database queries with smart boundary technology NO YES
Ultra-high performance NO YES
Recommended for high-volume websites and applications NO YES
Execution time ZCD's Professional Package is exponentially faster

Below is a technical comparison, showing which API features are available (classes, functions, etc) in each edition.

Code Package Comparison

Distance Wizard
Standard Edition		 Distance Wizard
Professional Edition
DistanceWizard class
To calculate distance		 YES YES
BoundaryWizard class
For fast database queries		 NO YES
Boundary class
To improve performance		 NO YES
Coordinate class
To represent location		 YES YES
Measurement enum
For miles/kilometers		 YES YES

Standard Edition Library

NOTICE: Standard Edition lacks the speed-enhancing smart boundaries. Running database queries to determine distances will require tens of thousands of queries and calculations. However, with the Professional Edition, only a few dozen queries are performed. For large-scale applications, consider upgrading to Distance Wizard Professional.

Distance Wizard Standard is comprised of three classes/concepts:

  1. DistanceWizard - The distance calculator service class. Finds distance between two points.
  2. Measurement - A support class (or enum) to represent different units of measure.
  3. Coordinate - A convenient way to manage points of latitude and longitude.

Since this library deals with coordinates on Earth's surface, the wizard make calculations based on the surface of a sphere.

Professional Edition Library

In general, there are two main portions of this API: one that calculates four boundaries around an original coordinate given a radius, and one that calculates the distance between two coordinates.

These portions are represented by the following two classes:

  1. BoundaryWizard class
  2. DistanceWizard class

Once constructed, these objects have methods to perform their calculations.

BoundaryWizard exists to make quick and efficient database queries by setting certain limitations on what should be queried. DistanceWizard performs calculations between two geolocational points.

Since this library deals with coordinates on Earth's surface, the wizards make calculations based on the surface of a sphere.

Coordinate

Overview

The Coordinate class eases grouping of a set of latitude and longitude values.

Latitude and longitude can be thought of as x,y values:

(latitude, longitude)

Remarks

When set, a coordinate's latitude and longitude are assumed to be in decimal degrees. Also, latitude and longitude must be within ±180°. Any value out of these bounds will throw an exception or cause the code to fail at execution.

There is no Coordinate class or concept in this API for database query languages. Individual latitude/longitude values are passed in as arguments instead of relying on Coordinate objects like in most programming languages. For examples, see DistanceWizard and BoundaryWizard pages.

Constructor

ASP/VBA/VB6 Construction of a Coordinate Dim myCoordinate: Set myCoordinate = New Coordinate
myCoordinate.Initialize 37.332418, -122.030039
Using the Coordinate struct in C Coordinate coord;
coord.Latitude = 37.332418;
coord.Longitude = -122.030039;
Initializing a Coordinate component in ColdFusion <cfobject name="coord" component="cfcs.Coordinate">
<cfset coord1.init(37.332418, -122.030039)>
Constructor Syntax new Coordinate(double LatitudeDegrees, double LongitudeDegrees)

Properties

double Latitude

The latitude (x-value) of the coordinate.

double Longitude

The longitude (y-value) of the coordinate.

Accessor Methods

double Latitude()

Gets the latitude (x-value) of the coordinate.

Returns

The latitude value of the coordinate in degrees as a double.
double Longitude()

Gets the longitude (y-value) of the coordinate.

Returns

The longitude value of the coordinate in degrees as a double.

Methods

boolean Equals(Coordinate coordinate)

Compares this coordinate object with the argument, based on whether its latitude and longitude values are the same.

Parameters

Type Name Description
Coordinate coordinate The other coordinate to compare this coordinate with.

Returns

Boolean TRUE if the coordinates have the same latitude and longitude. Returns boolean FALSE otherwise.

Methods

int Equals(Coordinate coordinate)

Compares this coordinate object with the argument, based on whether its latitude and longitude values are the same.

Parameters

Type Name Description
Coordinate coordinate The other coordinate to compare this coordinate with.

Returns

1, as true, if the coordinates have the same latitude and longitude. Returns 0, as false, otherwise.

Methods

boolean EqualTo(Coordinate coordinate)

Compares this coordinate object with the argument, based on whether its latitude and longitude values are the same.

Parameters

Type Name Description
Coordinate coordinate The other coordinate to compare this coordinate with.

Returns

Boolean TRUE if the coordinates have the same latitude and longitude. Returns boolean FALSE otherwise.

Methods

int Equals(Coordinate coordinate1, Coordinate coordinate2)

Compares this coordinate object with the argument, based on whether its latitude and longitude values are the same.

Parameters

Type Name Description
Coordinate coordinate1 The first coordinate to compare.
Coordinate coordinate2 The other coordinate to compare.

Returns

1 if the coordinates have the same latitude and longitude. Returns 0 otherwise.
void Initialize [latitude], [longitude] This is a Sub routine and only exists in ASP, VBA, and VB6. It merely assigns values to the object.

Sets the values of latitude and longitude for this coordinate to represent. Since constructors in ASP, VBA, and VB6 cannot accept arguments, this is the preferred alternative. This is a Sub and should not have parenthasees or assignment operators.

Parameters

Type Name Description
double latitude The latitude value to represent. Must be between -180 and +180.
double longitude The longitude value to represent. Must be between -180 and +180.

Returns

void
void init(numeric latitude, numeric longitude) This initialization function exists only in ColdFusion and should be called just once to set its values.

Sets the values of latitude and longitude for this coordinate to represent. Since constructors in ColdFusion do not accept parameters, this is the conventional alternative.

Parameters

Type Name Description
numeric latitude The latitude value to represent. Must be between -180 and +180.
numeric longitude The longitude value to represent. Must be between -180 and +180.

Returns

void

Remarks

When set, a coordinate's latitude and longitude are assumed to be in decimal degrees. Also, latitude and longitude must be within ±180°. Any value out of these bounds will throw an exception or cause the code to fail at execution.

Measurement

Overview

The Measurement enumeration is used to represent two different units of measure:

  1. Miles
  2. Kilometers

Usage Sample

ASP Dim Measure: Set Measure = New Measurement
Dim unit1: unit1 = Measure.Miles
Dim unit2: unit2 = Measure.Kilometers

Remarks

ASP does not support true enumerations, so a class with public read-only properties is used instead.
You will need to include the Measurement.asp file to use the Measurement class.
C Measurement unit1 = Miles;
Measurement unit2 = Kilometers;

Remarks

You will need to include the Measurement.h file to use the Measurement enum. If you include BoundaryWizard.h or DistanceWizard.h into your code, then it has already been included for you.
C# var unit1 = Measurement.Miles;
var unit2 = Measurement.Kilometers;
C++ Measurement unit1 = Measurement::Miles;
Measurement unit2 = Measurement::Kilometers;

Remarks

You will need to make sure Measurement.h is included. If you include BoundaryWizard.h or DistanceWizard.h into your code, then it has already been included for you.
ColdFusion <cfobject name="measure" component="cfcs.Measurement">
<cfset unit1 = measure.Miles>
<cfset unit2 = measure.Kilometers>
Java Measurement unit1 = Measurement.Miles;
Measurement unit2 = Measurement.Kilometers;

Remarks

You'll have to import the Measurement.java file. However, generally, a simple import wizards.*; line will suffice to import all the packaged classes.
MS SQL Server DECLARE @unit1 varchar(12), @unit2 varchar(12);
SELECT @unit1 = 'Miles';
SELECT @unit2 = 'Kilometers';

Remarks

If you're just passing a unit of measure as an argument statically, it's more efficient to just use the string literals 'Miles' and 'Kilometers'.
MySQL 5.0+ SET @unit1 = 'Miles';
SET @unit2 = 'Kilometers';

Remarks

If you're just passing a unit of measure as an argument statically, it's more efficient to just use the string literals 'Miles' and 'Kilometers' instead of setting variables like this. This is just an example on how use the Measurement constants.
Oracle 9+ DECLARE unit1 VARCHAR2(12) := 'Miles';
        unit2 VARCHAR2(12) := 'Kilometers';
BEGIN
   NULL;
END;
/

Remarks

If you're just passing a unit of measure as an argument statically, it's more efficient to just use the string literals 'Miles' and 'Kilometers' instead of setting variables like this. This is just an example on how use the Measurement constants.
Perl my $measure = new Measurement();
my $unit1 = $measure->{Miles};
my $unit2 = $measure->{Kilometers};

Remarks

Be sure to have a "use Measurement;" line somewhere at the beginning of your file or Perl will complain that it can't find the Measurement package.
PHP $unit1 = Measurement::MILES;
$unit2 = Measurement::KILOMETERS;

Remarks

PHP does not support true enumerations, so a class with static fields is used instead. You'll probably want to use require_once() to be able to use the Measurement class.
VB.NET Dim unit1 As Measurement = Measurement.Miles;
Dim unit2 As Measurement = Measurement.Kilometers;
Visual Basic 6 Dim unit1 As Measurement: unit1 = Measurement.Miles
Dim unit2 As Measurement: unit2 = Measurement.Kilometers
VBA Dim unit1 As Measurement: unit1 = Measurement.Miles
Dim unit2 As Measurement: unit2 = Measurement.Kilometers

Remarks

Ensure that the Measure.cls file is listed as part of your macro.

Boundary

Overview

The Boundary class is a very simple value class which holds four geolocational lines: two lines of latitude, and two lines of longitude. They are figured by a BoundaryWizard object.

A Boundary looks like the representation below.

RadiusAssistant Visualization

Properties

double North

Gets the northern-most boundary line (a line of latitude).

double South

Gets the southern-most boundary line (a line of latitude).

double East

Gets the eastern-most boundary line (a line of longitude).

double West

Gets the western-most boundary line (a line of longitude).

Accessor Methods

double North()

Gets the northern-most boundary line (a line of latitude).

Returns

The northern-most boundary line.
double South()

Gets the southern-most boundary line (a line of latitude).

Returns

The southern-most boundary line.
double East()

Gets the eastern-most boundary line (a line of longitude).

Returns

The eastern-most boundary line.
double West()

Gets the western-most boundary line (a line of longitude).

Returns

The western-most boundary line.
In MS SQL Server and MySQL, a table containing a boundary's values is returned from the CalculateBoundary function in the BoundaryWizard.sql file.

Remarks

All lines of latitude and longitude are expressed in decimal degrees.

You shouldn't ever need to create a Boundary. Use the BoundaryWizard's method CalculateBoundary() to obtain a Boundary.

BoundaryWizard

Overview

The BoundaryWizard class is used to find four geolocational lines around an origin given a certain radius.

RadiusAssistant Visualization

Constructor

General Constructor Syntax new BoundaryWizard

Functions

CalculateBoundary(@latitude, @longitude, @distance, @measure)

Finds the boundary around a coordinate or point of origin given a latitude, longitude, radius, and unit of measure.

Parameters

Type Name Description
decimal(18, 15) latitude The specific latitude value around which the boundary should be computed.
decimal(18, 15) longitude The specific longitude value around which the boundary should be computed.
decimal(18, 10) distance The distance, in the specified unit of measure, around which the boundary will be computed.
varchar(12) measure The unit of measure for distance provided using a Measurement value.

Returns

A table containing the four values of the boundary around the given origin: "north", "south", "east", "west". The north and south lines are the upper and lower lines of latitude in decimal degrees. The east and west lines are the left and right lines of longitude in decimal degrees.

Usage Example

Procedures

CalculateBoundary(latitude, longitude, distance, measure)

Finds the boundary around a coordinate or point of origin given a latitude, longitude, radius, and unit of measure.

Parameters

Type Name Description
decimal(18, 15) latitude The specific latitude value around which the boundary should be computed.
decimal(18, 15) longitude The specific longitude value around which the boundary should be computed.
decimal(18, 10) distance The distance, in the specified unit of measure, around which the boundary will be computed.
varchar(12) measure The unit of measure for distance provided using a Measurement value.

Returns

A table containing the four values of the boundary around the given origin: "north", "south", "east", "west". The north and south lines are the upper and lower lines of latitude in decimal degrees. The east and west lines are the left and right lines of longitude in decimal degrees.

Usage Example

Procedures

CalculateBoundary(latitude, longitude, distance, measure)

Finds the boundary around a coordinate or point of origin given a latitude, longitude, radius, and unit of measure.

Parameters

Type Name Description
NUMBER latitude The specific latitude value around which the boundary should be computed.
NUMBER longitude The specific longitude value around which the boundary should be computed.
NUMBER distance The distance, in the specified unit of measure, around which the boundary will be computed.
VARCHAR2(12) measure The unit of measure for distance provided using a Measurement value.

Returns

A Boundary type object that holds the four geolocational boundaries. See the documentation page for Boundary to view its member functions.

Usage Example

Methods / Functions

Boundary CalculateBoundary(Coordinate origin, double distance, int measure)

Finds the boundary around a coordinate or point of origin.

Parameters

Type Name Description
Coordinate origin The specific coordinate or location around which the boundary should be computed.
double distance The distance, in the specified unit of measure, around which the boundary will be computed.
Measurement measure The unit of measure for distance provided using a Measurement value.

Returns

The boundary around the origin coordinate.

Usage Example

ASP Basic Usage <!--#include file="UnitConverter.asp" -->
<!--#include file="Boundary.asp" -->
<!--#include file="Measurement.asp" -->
<!--#include file="Coordinate.asp" -->

<!--#include file="BoundaryWizard.asp" -->
<%
' Set up our coordinates
Dim originCoord: Set originCoord = New Coordinate
originCoord.Initialize 37.332418, -122.030039

' Sample radius (boundary) calculation
Dim boundCalc: Set boundCalc = New BoundaryWizard
Dim Measure: Set Measure = New Measurement

Dim radius
Set radius = boundCalc.CalculateBoundary(originCoord, 25, Measure.Miles)

Response.Write("Northern boundary: " & radius.North & "<br />")
Response.Write("Southern boundary: " & radius.South & "<br />")
Response.Write("Eastern boundary: " & radius.East & "<br />")
Response.Write("Western boundary: " & radius.West & "<br />")
%>
C Basic Usage #include <stdlib.h>
#include "BoundaryWizard.h"

int main()
{
   // Set up; simulate data entry.
   Coordinate originCoord;
   originCoord.Latitude = 37.332418;
   originCoord.Longitude = -122.030039;
   
   // SAMPLE USAGE OF BOUNDARY CALCULATOR
   Boundary radius = CalculateBoundary(originCoord, 25, Miles);

   printf("Northern boundary: %f\n", radius.North);
   printf("Southern boundary: %f\n", radius.South);
   printf("Eastern boundary: %f\n", radius.East);
   printf("Western boundary: %f\n\n", radius.West);

   getch();
   return 0;
}
C# Basic Usage using System;
using ZipCodeDownload.Wizards;

public sealed class Program
{
   private static void Main(string[] args)
   {
      BoundaryWizard boundCalc = new BoundaryWizard();

      // Radius calculation
      Boundary radius = boundCalc.CalculateBoundary(new Coordinate(37.332418, -122.030039),
         25.0,
         Measurement.Miles);

      Console.WriteLine("Northern boundary: " + radius.North);
      Console.WriteLine("Southern boundary: " + radius.South);
      Console.WriteLine("Eastern boundary: " + radius.East);
      Console.WriteLine("Western boundary: " + radius.West);

      Console.ReadLine();
   }
}
C++ Basic Usage #include <iostream>
#include <stdlib.h>
#include "BoundaryWizard.h"

using namespace std;
using namespace ZipCodeDownload::Wizards;

int main()
{
   // Set up
   Coordinate originCoord = Coordinate(37.332418, -122.030039);
   
   // Actual usage of class
   BoundaryWizard boundCalc = BoundaryWizard();
   Boundary radius = boundCalc.CalculateBoundary(originCoord, 25, Measurement::Miles);

   // Example output
   cout << "Northern boundary: " << radius.North() << endl;
   cout << "Southern boundary: " << radius.South() << endl;
   cout << "Eastern boundary: " << radius.East() << endl;
   cout << "Western boundary: " << radius.West() << endl << endl;
   
   system("PAUSE");

   return 0;
}
ColdFusion Basic Usage <!-- Simulate data entry; establish our coordinate origin. -->
<cfobject name="coord" component="cfcs.Coordinate">
<cfset coord.init(37.332418, -122.030039)>

<!-- Create our service object. -->
<cfobject component="cfcs.BoundaryWizard" name="boundcalc">

<!-- Calculate the boundary. -->
<cfset bounds = boundcalc.CalculateBoundary(coord1, 25.0, measure.Miles)>

<cfoutput>
   Northern boundary: #bounds.North()#<br />
   Southern boundary: #bounds.South()#<br />
   Eastern boundary: #bounds.East()#<br />
   Western boundary: #bounds.West()#
</cfoutput>
Java Basic Usage import wizards.*;

public class Sample {
   public static void main(String[] args)
   {
      BoundaryWizard boundCalc = new BoundaryWizard();
     
      // Set up sample coordinate
      Coordinate originCoord = new Coordinate(37.332418, -122.030039);
     
      // Sample radius calculation
      Boundary radius = boundCalc.CalculateBoundary(originCoord, 25.0, Measurement.Miles);
     
      System.out.println("Northern boundary: " + radius.North());
      System.out.println("Southern boundary: " + radius.South());
      System.out.println("Eastern boundary: " + radius.East());
      System.out.println("Western boundary: " + radius.West());
    }
}
Basic Usage for MS SQL SELECT * FROM dbo.CalculateBoundary(37.332418, -122.030039, 25, 'Miles');
Basic Usage for MySQL 5.0+ CALL CalculateBoundary(37.332418, -122.030039, 25, 'Miles');
Oracle 9+ DECLARE bound Boundary;
BEGIN
    bound := CalculateBoundary(37.332418, -122.030039, 25.0, 'Miles');
    dbms_output.put_line('Northern boundary: ' || bound.North());
    dbms_output.put_line('Southern boundary: ' || bound.South());
    dbms_output.put_line('Eastern boundary: ' || bound.East());
    dbms_output.put_line('Western boundary: ' || bound.West());
END;
/
 
Perl Basic Usage #!/usr/bin/perl
package main;

use Coordinate;
use Measurement;
use BoundaryWizard;

# Simulate data entry by setting up coordinate
my $coord = new Coordinate(37.332418, -122.030039);

# Represent our units of measure
my $measure = new Measurement();

# Create the Boundary Wizard
my $boundWizard = new BoundaryWizard();

# Calculate the actual boundary
my $boundary = $boundWizard->CalculateBoundary($coord1, 25.0, $measure->{Miles});

print "Northern boundary: ".$boundary->North()."\n";
print "Southern boundary: ".$boundary->South()."\n";
print "Eastern boundary: ".$boundary->East()."\n";
print "Western boundary: ".$boundary->West();

exit;
PHP Basic Usage <?php
require_once("BoundaryWizard.php");

$boundCalc = new BoundaryWizard();

// Simulate data entry
$latitude = 37.332418;
$longitude = -122.030039;
// Desired radius (in miles)
$radius = 25.0;

$coord = new Coordinate($latitude, $longitude);

$boundary = $boundCalc->CalculateBoundary($coord, $radius, Measurement::MILES);

echo "Northern boundary: " . $boundary->North() . "<br />";
echo "Southern boundary: " . $boundary->South() . "<br />";
echo "Eastern boundary: " . $boundary->East() . "<br />";
echo "Western boundary: " . $boundary->West();
?>
VB.NET Basic Usage Imports System
Imports ZipCodeDownload.Wizards

Public NotInheritable Class Program
   Public Shared Sub Main()

      Dim boundCalc As New BoundaryWizard()

      ' Sample radius calculation
      Dim radius As Boundary = boundCalc.CalculateBoundary( _
         New Coordinate(37.332418, -122.030039), _
         25, _
         Measurement.Miles)

      ' Sample usage of results
      Console.WriteLine("Northern boundary: " & radius.North)
      Console.WriteLine("Southern boundary: " & radius.South)
      Console.WriteLine("Eastern boundary: " & radius.East)
      Console.WriteLine("Western boundary: " & radius.West)

      Console.ReadLine()

   End Sub
End Class
Usage in Visual Basic 6 Sub Sample()
    ' Set up our coordinate
    Dim originCoord As Coordinate
    Set originCoord = New Coordinate
    originCoord.Initialize 37.332418, -122.030039
   
    ' Sample radius (boundary) calculation
    Dim boundCalc: Set boundCalc = New BoundaryWizard
   
    Dim radius: Set radius = boundCalc.CalculateBoundary(originCoord, 25, Measurement.Miles)
   
    Debug.Print "Northern boundary: " & radius.north
    Debug.Print "Southern boundary: " & radius.south
    Debug.Print "Eastern boundary: " & radius.east
    Debug.Print "Western boundary: " & radius.west
End Sub
VBA Basic Usage Sub Program()
    ' Set up our coordinate
    Dim originCoord As Coordinate
    Set originCoord = New Coordinate
    originCoord.Initialize 37.332418, -122.030039
   
    ' Sample radius (boundary) calculation
    Dim boundCalc: Set boundCalc = New BoundaryWizard
   
    Dim radius: Set radius = boundCalc.CalculateBoundary(originCoord, 25, Measurement.Miles)
   
    Debug.Print "Northern boundary: " & radius.north
    Debug.Print "Southern boundary: " & radius.south
    Debug.Print "Eastern boundary: " & radius.east
    Debug.Print "Western boundary: " & radius.west
End Sub

Output

The example above should output these numeric values (exact formatting and precision varies per platform):

OUTPUT Northern boundary: 37.6938359147632
Southern boundary: 36.9710000852368
Eastern boundary: -121.575490873859
Western boundary: -122.484587126141

Remarks

A Boundary object is returned from the CalculateBoundary method. It contains two lines of latitude and two lines of longitude. See the documentation for the Boundary class for more information.

DistanceWizard

Overview

The DistanceWizard performs a calculation to determine the distance in a desired unit of measure between two given Coordinates on a sphere.

RadiusAssistant Visualization

Constructor

Constructor Syntax new DistanceWizard

Functions

CalculateDistance(@latitude1, @longitude1, @latitude2, @longitude2, @measure)

Calculates the distance between two geolocational points given those points and a unit of measure.

Parameters

Type Name Description
decimal(18, 15) latitude1 The latitude value of the first/origin coordinate.
decimal(18, 15) longitude1 The longitude value of the first/origin coordinate.
decimal(18, 15) latitude2 The latitude value of the second/relative coordinate.
decimal(18, 15) longitude2 The longitude value of the second/relative coordinate.
varchar(12) measure The unit of measure for distance provided using a Measurement value.

Returns

A distance between the two coordinates in decimal degrees.

Usage Example

Functions

CalculateDistance(latitude1, longitude1, latitude2, longitude2, measure)

Calculates the distance between two geolocational points given those points and a unit of measure.

Parameters

Type Name Description
decimal(18, 15) latitude1 The latitude value of the first/origin coordinate.
decimal(18, 15) longitude1 The longitude value of the first/origin coordinate.
decimal(18, 15) latitude2 The latitude value of the second/relative coordinate.
decimal(18, 15) longitude2 The longitude value of the second/relative coordinate.
varchar(12) measure The unit of measure for distance provided using a Measurement value.

Returns

A distance between the two coordinates in decimal degrees.

Usage Example

Functions

CalculateDistance(latitude1, longitude1, latitude2, longitude2, measure)

Calculates the distance between two geolocational points given those points and a unit of measure.

Parameters

Type Name Description
NUMBER latitude1 The latitude value of the first/origin coordinate.
NUMBER longitude1 The longitude value of the first/origin coordinate.
NUMBER latitude2 The latitude value of the second/relative coordinate.
NUMBER longitude2 The longitude value of the second/relative coordinate.
VARCHAR2(12) measure The unit of measure for distance provided using a Measurement value.

Returns

A distance between the two coordinates in decimal degrees as a NUMBER.

Usage Example

Methods / Functions

double CalculateDistance(Coordinate origin, Coordinate relative, int measure)

Finds the distance on a sphere from the Coordinate origin to the Coordinate relative.

Parameters

Type Name Description
Coordinate origin The first, or starting, coordinate from which to compute distance.
Coordinate relative The second, or ending, coordinate to which to compute distance.
int measure The unit of measure for distance using a Measurement value.

Returns

The distance between the two coordinates on a sphere as a double (a numeric value).

Usage Example

ASP Basic Usage <!--#include file="UnitConverter.asp" -->
<!--#include file="Measurement.asp" -->
<!--#include file="Coordinate.asp" -->

<!--#include file="DistanceWizard.asp" -->
<%
' Set up our coordinates
Dim originCoord, relativeCoord
Set originCoord = New Coordinate
originCoord.Initialize 37.332418, -122.030039
Set relativeCoord = New Coordinate
relativeCoord.Initialize 30.41922, -97.656097

' Used to represent units of measure
Dim Measure: Set Measure = New Measurement

' Sample distance calculation
Dim distCalc: Set distCalc = New DistanceWizard

Dim distance
distance = distCalc.CalculateDistance(originCoord, relativeCoord, Measure.Miles)

Response.Write("<br /><br />Distance: " & distance)
%>
C Basic Usage #include <stdlib.h>
#include "DistanceWizard.h"

int main()
{
   // Set up; simulate data entry.
   Coordinate originCoord, relativeCoord;
   originCoord.Latitude = 37.332418;
   originCoord.Longitude = -122.030039;
   relativeCoord.Latitude = 30.41922;
   relativeCoord.Longitude = -97.656097;
   
   // SAMPLE USAGE OF DISTANCE CALCULATOR
   double distance = CalculateDistance(originCoord, relativeCoord, Miles);

   printf("Distance: %f", distance);

   getch();
   return 0;
}
C# Basic Usage using System;
using ZipCodeDownload.Wizards;

public sealed class Program
{
    private static void Main(string[] args)
    {      
        // Sample distance calculation
        DistanceWizard distCalc = new DistanceWizard();

        double distance = distCalc.CalculateDistance(
        new Coordinate(37.332418, -122.030039),
        new Coordinate(30.41922, -97.656097),
        Measurement.Miles);

        Console.WriteLine("Distance: " + distance);
    }
}
C++ Basic Usage #include <iostream>
#include <stdlib.h>
#include "DistanceWizard.h"

using namespace std;
using namespace ZipCodeDownload::Wizards;

int main()
{
   // Set up
   Coordinate originCoord = Coordinate(37.332418, -122.030039);
   Coordinate relativeCoord = Coordinate(30.41922, -97.656097);
   
   DistanceWizard distCalc = DistanceWizard();

   // Perform calculation
   double distance = distCalc.CalculateDistance(originCoord, relativeCoord, Measurement::Miles);

   cout << "Distance in Miles: " << distance << endl;

   system("PAUSE");
   return 0;
}
ColdFusion Basic Usage <!-- Set up our utility/service components. -->
<cfobject name="distcalc" component="cfcs.DistanceWizard">
<cfobject name="measure" component="cfcs.Measurement">

<!-- Create our coordinates. -->
<cfobject name="coord1" component="cfcs.Coordinate">
<cfobject name="coord2" component="cfcs.Coordinate">
<cfset coord1.init(