====== Distance Between (Expression Function) ======

===== Purpose =====
The **Distance Between** function (DISTANCE_BETWEEN) calculates the distance between two points on Earth using the decimal longitude and latitude for each point.  The distance is a calculation of the great-circle distance or "as the crow flies" using the "Spherical Law of Cosines"

{{:distance_between_initial.png?direct&600|}}

===== Parameters =====
The **Distance Between** function has five parameters, four of which are required:

==== Start Latitude ====

Allowed Inputs: [[Field|field]] value or number

The first required parameter is the decimal number that represents the latitude of the start point.  The maximum and minimum values are 90 to -90.  The value for this is usually the latitude [[Field Type - Address#Field parts|field part]] of an [[Field Type - Address|address]] [[Field|field]] with [[Field Setting - Geolocation|geolocation]] enabled.

==== Start Longitude ====

Allowed Inputs: [[Field|field]] value or a number

The second required parameter is the decimal number that represents the longitude of the start point.  The maximum and minimum values are 180 to -180.  The value for this is usually the longitude [[Field Type - Address#Field parts|field part]] of an [[Field Type - Address|address]] [[Field|field]] with [[Field Setting - Geolocation|geolocation]] enabled.
==== End Latitude ====

Allowed Inputs: [[Field|field]] value or a number

The third required parameter is the decimal number that represents the latitude of the end point.  The maximum and minimum values are 90 to -90.  The value for this is usually the latitude [[Field Type - Address#Field parts|field part]] of an [[Field Type - Address|address]] [[Field|field]] with [[Field Setting - Geolocation|geolocation]] enabled.
==== End Longitude ====

Allowed Inputs: [[Field|field]] value or a text string

The fourth required parameter is the decimal number that represents the longitude of the edit point.  The maximum and minimum values are 180 to -180.  The value for this is usually the longitude [[Field Type - Address#Field parts|field part]] of an [[Field Type - Address|address]] [[Field|field]] with [[Field Setting - Geolocation|geolocation]] enabled.
==== Units ====

Allowed Inputs: omitted, mi, or km

The fifth parameter is optional and determines the units returned for the distance calculation.  If this parameter is omitted the miles will be used.

===== Output =====

The output of the **Distance Between** function is number representing the distance between two points in the units requested.

===== Example =====

For example the distance between 304 Market St. Harrisburg, PA and 304 Market St. San Francisco CA would be calculated by  DISTANCE_BETWEEN(40.261081,-76.880648,37.792335,-122.397622) will result in 2422.34723361 and DISTANCE_BETWEEN(40.261081,-76.880648,37.792335,-122.397622,"km") will result in 3898.14958963.