Skip to content

Haversine Distance

Geospatial Distance Analysis for Retail Location Intelligence.

This module provides efficient geospatial distance calculations that power location-based retail analytics and strategic decision-making.

Technical Features

  • Ibis-Based Computation: Scalable processing within existing data pipelines
  • Database Integration: Calculations performed in SQL databases for efficiency
  • Haversine Formula: Accurate great-circle distance computation
  • Backend Agnostic: Works with multiple database and processing engines

Limitations

  • Spherical Earth Assumption: Minor inaccuracies due to Earth's actual oblate shape
  • Straight-Line Distance: Measures "as the crow flies", not driving distances
  • Requires Trigonometric Functions: Backend must support mathematical functions

haversine_distance(lat_col, lon_col, target_lat_col, target_lon_col, radius=6371.0)

Computes the Haversine distance between two sets of latitude and longitude columns.

Parameters:

Name Type Description Default
lat_col Column

Column containing source latitudes.

 required
lon_col Column

Column containing source longitudes.

 required
target_lat_col Column

Column containing target latitudes.

 required
target_lon_col Column

Column containing target longitudes.

 required
radius float

Earth's radius in kilometers (default: 6371 km).

 6371.0

Returns:

Type Description
Column

ibis.expr.types.Column: An Ibis expression representing the computed distances.
Source code in pyretailscience/analysis/haversine.py 
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
def haversine_distance(
    lat_col: ibis.expr.types.Column,
    lon_col: ibis.expr.types.Column,
    target_lat_col: ibis.expr.types.Column,
    target_lon_col: ibis.expr.types.Column,
    radius: float = 6371.0,
) -> ibis.expr.types.Column:
    """Computes the Haversine distance between two sets of latitude and longitude columns.

    Parameters:
        lat_col (ibis.expr.types.Column): Column containing source latitudes.
        lon_col (ibis.expr.types.Column): Column containing source longitudes.
        target_lat_col (ibis.expr.types.Column): Column containing target latitudes.
        target_lon_col (ibis.expr.types.Column): Column containing target longitudes.
        radius (float, optional): Earth's radius in kilometers (default: 6371 km).

    Returns:
        ibis.expr.types.Column: An Ibis expression representing the computed distances.
    """
    lat1_rad = lat_col.radians()
    lat2_rad = target_lat_col.radians()
    delta_lat = (target_lat_col - lat_col).radians()
    delta_lon = (target_lon_col - lon_col).radians()

    a = (delta_lat / 2).sin().pow(2) + lat1_rad.cos() * lat2_rad.cos() * (delta_lon / 2).sin().pow(2)
    c = 2 * a.sqrt().asin()

    return radius * c