0
# @turf/distance
1

2
@turf/distance calculates the distance between two geographic coordinates using the Haversine formula to account for Earth's curvature. It supports multiple units of measurement and accepts coordinates in various formats.
3

4
## Package Information
5

6
- **Package Name**: @turf/distance
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @turf/distance`
10

11
## Core Imports
12

13
```typescript
14
import { distance } from "@turf/distance";
15
```
16

17
For default import:
18

19
```typescript
20
import distance from "@turf/distance";
21
```
22

23
For CommonJS:
24

25
```javascript
26
const { distance } = require("@turf/distance");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { distance } from "@turf/distance";
33
import { point } from "@turf/helpers";
34

35
// Using Point Features
36
const from = point([-75.343, 39.984]);
37
const to = point([-75.534, 39.123]);
38
const distanceInKm = distance(from, to);
39
console.log(distanceInKm); // ~97.15 kilometers
40

41
// Using coordinate arrays
42
const distanceInMiles = distance(
43
  [-75.343, 39.984],
44
  [-75.534, 39.123],
45
  { units: "miles" }
46
);
47
console.log(distanceInMiles); // ~60.35 miles
48
```
49

50
## Capabilities
51

52
### Distance Calculation
53

54
Calculates the distance between two coordinates using the Haversine formula.
55

56
```typescript { .api }
57
/**
58
 * Calculates the distance between two coordinates in degrees, radians, miles, or kilometers.
59
 * This uses the Haversine formula to account for global curvature.
60
 * @param from - Origin coordinate
61
 * @param to - Destination coordinate  
62
 * @param options - Optional parameters (defaults to empty object)
63
 * @returns Distance between the two coordinates
64
 */
65
function distance(
66
  from: Coord,
67
  to: Coord,
68
  options: {
69
    units?: Units;
70
  } = {}
71
): number;
72

73
// Also available as default export
74
export default distance;
75
export { distance };
76
```
77

78
**Parameters:**
79
- `from: Coord` - Origin coordinate (Point Feature, Point geometry, or Position array)
80
- `to: Coord` - Destination coordinate (Point Feature, Point geometry, or Position array)
81
- `options: Object` - Optional parameters object (defaults to empty object)
82
  - `options.units?: Units` - Unit of measurement for distance calculation (default: "kilometers")
83

84
**Returns:** `number` - Distance between the two coordinates in the specified units
85

86
**Usage Examples:**
87

88
```typescript
89
import { distance } from "@turf/distance";
90
import { point } from "@turf/helpers";
91

92
// Different coordinate input formats
93
const pointFeature = point([0, 0]);
94
const pointGeometry = { type: "Point", coordinates: [1, 1] };
95
const positionArray = [2, 2];
96

97
// All these work as coordinate inputs
98
const dist1 = distance(pointFeature, pointGeometry);
99
const dist2 = distance(positionArray, [3, 3]);
100
const dist3 = distance([0, 0], [1, 1], { units: "miles" });
101

102
// Different units
103
const kilometers = distance([0, 0], [1, 1]); // default
104
const miles = distance([0, 0], [1, 1], { units: "miles" });
105
const meters = distance([0, 0], [1, 1], { units: "meters" });
106
const degrees = distance([0, 0], [1, 1], { units: "degrees" });
107
const radians = distance([0, 0], [1, 1], { units: "radians" });
108
const nauticalMiles = distance([0, 0], [1, 1], { units: "nauticalmiles" });
109
```
110

111
## Types
112

113
```typescript { .api }
114
/**
115
 * Coordinate input type - accepts Point Features, Point geometries, or coordinate arrays
116
 */
117
type Coord = Feature<Point> | Point | Position;
118

119
/**
120
 * Point Feature from GeoJSON
121
 */
122
interface Feature<Point> {
123
  type: "Feature";
124
  geometry: Point;
125
  properties?: GeoJsonProperties;
126
}
127

128
/**
129
 * Point geometry from GeoJSON
130
 */
131
interface Point {
132
  type: "Point";
133
  coordinates: Position;
134
}
135

136
/**
137
 * Position array representing [longitude, latitude]
138
 */
139
type Position = [number, number];
140

141
/**
142
 * GeoJSON properties object (can be any object or null)
143
 */
144
type GeoJsonProperties = { [name: string]: any } | null;
145

146
/**
147
 * Supported distance measurement units
148
 */
149
type Units =
150
  | "meters"
151
  | "metres" 
152
  | "millimeters"
153
  | "millimetres"
154
  | "centimeters"
155
  | "centimetres"
156
  | "kilometers"
157
  | "kilometres"
158
  | "miles"
159
  | "nauticalmiles"
160
  | "inches"
161
  | "yards"
162
  | "feet"
163
  | "radians"
164
  | "degrees";
165
```
166

167
## Error Handling
168

169
The function throws errors in the following cases:
170

171
- **Invalid coordinates**: When coordinate inputs cannot be parsed (handled by `getCoord` from @turf/invariant)
172
- **Invalid units**: When an unsupported unit string is provided (handled by `radiansToLength` from @turf/helpers)
173

174
```typescript
175
import { distance } from "@turf/distance";
176
import { point } from "@turf/helpers";
177

178
try {
179
  // This will throw an error due to invalid units
180
  const result = distance(
181
    point([0, 0]), 
182
    point([1, 1]), 
183
    { units: "invalid-unit" as any }
184
  );
185
} catch (error) {
186
  console.error("Invalid units provided:", error.message);
187
}
188
```