Distance and Bearing

Overview

This page documents Turf.js modules for calculating distances and bearings between geographic points, plus related operations like along, destination, and midpoint. These modules form Tier 2 primitive operations in the dependency hierarchy (see page 2.3) and are used extensively by higher-level geometric operations.

All distance and bearing calculations support two mathematical approaches:

Approach	Path Type	Use Case	Modules
Great Circle (Geodesic)	Shortest path on sphere	Most distance/navigation calculations	@turf/distance, @turf/bearing, @turf/destination
Rhumb Line (Loxodrome)	Constant compass bearing	Marine/aviation navigation, Mercator maps	@turf/rhumb-distance, @turf/rhumb-bearing, @turf/rhumb-destination

Composite operations like @turf/along and @turf/midpoint build on these primitives by combining distance, bearing, and destination calculations.

Module Dependency Structure

The distance and bearing modules follow a clear dependency hierarchy:

100%

Rhumb line modules (@turf/rhumb-distance, @turf/rhumb-bearing, @turf/rhumb-destination) follow the same dependency pattern but implement constant-bearing calculations.

Great Circle Distance

@turf/distance Module

The distance function calculates the shortest distance between two points on a sphere using the Haversine formula. This is the most commonly used distance calculation in Turf.js.

Function Signature:

function distance(
  from: Coord,
  to: Coord,
  options?: { units?: Units }
): number

Algorithm Overview:

100%

The Haversine formula handles coordinate differences correctly across the anti-meridian and works for all latitude/longitude combinations. It uses the formula:

a = sin²(Δφ/2) + cos(φ1) * cos(φ2) * sin²(Δλ/2)
c = 2 * atan2(√a, √(1−a))
distance = R * c

Where φ is latitude, λ is longitude, and R is Earth's radius.

Great Circle Bearing

@turf/bearing Module

The bearing function calculates the compass direction from one point to another along a great circle path.

Function Signature:

function bearing(
  start: Coord,
  end: Coord,
  options?: { final?: boolean }
): number

Bearing Calculation Flow:

100%

The bearing is returned in the range -180 to +180 degrees. A bearing of 0° points north, 90° points east, 180° or -180° points south, and -90° points west.

Great Circle Destination

@turf/destination Module

The destination function calculates the endpoint of travel from an origin point along a great circle path for a given distance and bearing.

Function Signature:

function destination(
  origin: Coord,
  distance: number,
  bearing: number,
  options?: { units?: Units; properties?: Properties }
): Feature<Point>

Destination Calculation:

100%

The calculation uses spherical trigonometry to accurately compute the destination point on the Earth's surface. The distance is converted to radians (angular distance) for internal calculations.

Rhumb Line Distance

@turf/rhumb-distance Module

The rhumbDistance function calculates the distance between two points along a constant bearing path. Unlike great circle calculations, rhumb lines appear as straight lines on Mercator projections.

100%

The core calculation uses Mercator projection mathematics with a stretch factor q to handle longitude compression at different latitudes:

Variable	Purpose	Formula
DeltaPhi	Latitude difference	phi2 - phi1
DeltaPsi	Mercator projection factor	log(tan(phi2/2 + PI/4) / tan(phi1/2 + PI/4))
q	Stretch factor	DeltaPhi / DeltaPsi when DeltaPsi > 10e-12
delta	Angular distance	sqrt(DeltaPhi² + q² * DeltaLambda²)

Rhumb Line Bearing

@turf/rhumb-bearing Module

The rhumbBearing function determines the constant compass heading between two points. The calculation handles both initial and final bearings through the final option parameter.

100%

The bearing calculation uses the arctangent of the coordinate differences in Mercator space, handling anti-meridian crossings through longitude normalization.

Rhumb Line Destination

@turf/rhumb-destination Module

The rhumbDestination function computes the endpoint of travel along a rhumb line given a starting point, distance, and bearing.

100%

The destination calculation involves several key mathematical steps:

1. Angular distance calculation: delta = distance / radius
2. Coordinate projections: Convert to radians and apply trigonometric functions
3. Bearing application: DeltaPhi = delta * cos(theta), DeltaLambda = delta * sin(theta) / q
4. Result normalization: Ensure longitude stays within -180 to +180 degrees

Composite Operations

@turf/along Module

The along module calculates a point at a specified distance along a LineString. It combines distance calculations with coordinate interpolation to find the exact position.

Function Signature:

function along(
  line: Feature<LineString | MultiLineString> | LineString | MultiLineString,
  distance: number,
  options?: { units?: Units }
): Feature<Point>

Along Algorithm:

100%

The algorithm walks along the line segments, accumulating distances until it reaches or exceeds the target distance. When the target is within a segment, it uses bearing and destination to interpolate the exact point.

@turf/midpoint Module

The midpoint module calculates the geodesic midpoint between two points. Unlike a simple average of coordinates, this finds the true midpoint along the great circle path.

Function Signature:

function midpoint(
  point1: Coord,
  point2: Coord
): Feature<Point>

Midpoint Calculation Flow:

100%

This approach ensures the midpoint lies on the great circle path between the two points, which differs from the arithmetic mean of coordinates except when the points lie on the equator or share the same longitude.

Implementation Details

Unit Conversion System

All distance-related modules integrate with the unified unit system provided by @turf/helpers:

Unit	Conversion Factor to Meters	Common Use
meters	1	Scientific, metric
kilometers	1000	Default for most operations
miles	1609.344	US measurements
nauticalmiles	1852	Marine/aviation
feet	0.3048	Imperial measurements
radians	6371008.8 (Earth radius)	Angular distance
degrees	111319.49 (at equator)	Angular measurements

The convertLength() function from @turf/helpers handles conversions:

convertLength(distance: number, originalUnit: Units, finalUnit: Units): number

Module-Specific Defaults:

• @turf/distance: Default output is kilometers
• @turf/destination: Default input is kilometers
• @turf/along: Default input is kilometers

Coordinate System Handling

180th Meridian Management

All rhumb line calculations implement consistent handling of the 180th meridian (International Date Line) to prevent coordinate system errors:

100%

This normalization appears in all three rhumb functions using identical logic patterns, ensuring consistent coordinate handling across the library.

Common Dependencies

All distance and bearing modules depend on foundation modules for coordinate handling and validation:

@turf/invariant Functions:

• getCoord(coord): Extracts [longitude, latitude] array from Point features, coordinates, or coordinate arrays
• getCoords(feature): Extracts coordinate arrays from LineString and other geometries

@turf/helpers Functions:

• convertLength(): Unit conversion for distances
• point(): Creates GeoJSON Point features with optional properties
• radiansToLength(): Converts angular distance (radians) to linear distance
• lengthToRadians(): Converts linear distance to angular distance (radians)
• degreesToRadians(): Angle conversion for trigonometric calculations
• radiansToDegrees(): Converts results back to degrees

These foundation functions ensure consistent input validation and coordinate handling across all distance/bearing modules.

Error Handling and Edge Cases

Numerical Stability

The rhumb line implementations include several numerical stability measures:

100%

These stability measures handle:

• East-West courses: When DeltaPsi approaches zero (ill-conditioned calculation)
• Polar crossings: When latitude exceeds ±90 degrees
• Anti-meridian crossings: Longitude normalization for international date line