0
# Spatial Measurement
1

2
Functions for calculating distances, areas, lengths, angles, and bearings between geographic features using geodesic calculations. All measurements account for the Earth's curvature using appropriate mathematical models.
3

4
## Capabilities
5

6
### Distance Calculation
7

8
Calculate distances between coordinate points using the Haversine formula.
9

10
```typescript { .api }
11
/**
12
 * Calculates the distance between two coordinates in degrees, radians, miles, or kilometers.
13
 * This uses the Haversine formula to account for global curvature.
14
 */
15
function distance(
16
  from: Coord,
17
  to: Coord,
18
  options?: { units?: Units }
19
): number;
20
```
21

22
**Usage Examples:**
23

24
```typescript
25
import { distance, point } from "@turf/turf";
26

27
const from = point([-75.343, 39.984]);
28
const to = point([-75.534, 39.123]);
29

30
// Calculate distance in different units
31
const distKm = distance(from, to, { units: 'kilometers' });
32
const distMiles = distance(from, to, { units: 'miles' });
33
const distMeters = distance(from, to, { units: 'meters' });
34

35
console.log(`Distance: ${distKm} km, ${distMiles} miles, ${distMeters} meters`);
36
```
37

38
### Area Calculation
39

40
Calculate the geodesic area of polygons in square meters.
41

42
```typescript { .api }
43
/**
44
 * Calculates the geodesic area in square meters of one or more polygons.
45
 */
46
function area(geojson: Feature<any> | FeatureCollection<any> | Geometry): number;
47
```
48

49
**Usage Examples:**
50

51
```typescript
52
import { area, polygon } from "@turf/turf";
53

54
const poly = polygon([[[125, -15], [113, -22], [154, -27], [144, -15], [125, -15]]]);
55
const areaSquareMeters = area(poly);
56
const areaSquareKm = areaSquareMeters / 1000000;
57

58
console.log(`Area: ${areaSquareMeters} m², ${areaSquareKm} km²`);
59
```
60

61
### Length Calculation
62

63
Calculate the length of line features.
64

65
```typescript { .api }
66
/**
67
 * Takes a GeoJSON and measures its length in the specified units (by default in kilometers).
68
 */
69
function length(
70
  geojson: Feature<LineString | MultiLineString | Polygon | MultiPolygon>,
71
  options?: { units?: Units }
72
): number;
73
```
74

75
**Usage Examples:**
76

77
```typescript
78
import { length, lineString, polygon } from "@turf/turf";
79

80
const line = lineString([[-77.031669, 38.878605], [-77.029609, 38.881946], [-77.020339, 38.884084]]);
81
const lengthKm = length(line, { units: 'kilometers' });
82
const lengthMiles = length(line, { units: 'miles' });
83

84
// Length also works with polygons (perimeter)
85
const poly = polygon([[[0, 0], [0, 1], [1, 1], [1, 0], [0, 0]]]);
86
const perimeter = length(poly, { units: 'kilometers' });
87

88
console.log(`Line length: ${lengthKm} km, ${lengthMiles} miles`);
89
console.log(`Polygon perimeter: ${perimeter} km`);
90
```
91

92
### Bearing Calculation
93

94
Calculate the geographic bearing between two points.
95

96
```typescript { .api }
97
/**
98
 * Takes two points and finds the geographic bearing between them,
99
 * i.e. the angle measured in degrees from the north line (0 degrees)
100
 */
101
function bearing(
102
  start: Coord,
103
  end: Coord,
104
  options?: { final?: boolean }
105
): number;
106
```
107

108
**Usage Examples:**
109

110
```typescript
111
import { bearing, point } from "@turf/turf";
112

113
const point1 = point([-75.343, 39.984]);
114
const point2 = point([-75.534, 39.123]);
115

116
// Calculate initial bearing
117
const initialBearing = bearing(point1, point2);
118

119
// Calculate final bearing (bearing when arriving at destination)
120
const finalBearing = bearing(point1, point2, { final: true });
121

122
console.log(`Initial bearing: ${initialBearing}°`);
123
console.log(`Final bearing: ${finalBearing}°`);
124
```
125

126
### Angle Calculation
127

128
Calculate the angle between three points.
129

130
```typescript { .api }
131
/**
132
 * Finds the angle formed by three points.
133
 */
134
function angle(
135
  start: Coord,
136
  vertex: Coord,
137
  end: Coord,
138
  options?: { explementary?: boolean; mercator?: boolean }
139
): number;
140
```
141

142
**Usage Examples:**
143

144
```typescript
145
import { angle, point } from "@turf/turf";
146

147
const start = point([5, 5]);
148
const vertex = point([0, 0]);
149
const end = point([0, 5]);
150

151
// Calculate angle at vertex
152
const angleValue = angle(start, vertex, end);
153

154
// Calculate explementary angle (360° - angle)
155
const explementaryAngle = angle(start, vertex, end, { explementary: true });
156

157
console.log(`Angle: ${angleValue}°`);
158
console.log(`Explementary angle: ${explementaryAngle}°`);
159
```
160

161
### Point Along Line
162

163
Calculate a point at a specified distance along a line.
164

165
```typescript { .api }
166
/**
167
 * Takes a LineString and returns a Point at a specified distance along the line.
168
 */
169
function along(
170
  line: Feature<LineString> | LineString,
171
  distance: number,
172
  options?: { units?: Units }
173
): Feature<Point>;
174
```
175

176
**Usage Examples:**
177

178
```typescript
179
import { along, lineString } from "@turf/turf";
180

181
const line = lineString([[-83, 30], [-84, 36], [-78, 41]]);
182

183
// Get point 200 km along the line
184
const pointAlong = along(line, 200, { units: 'kilometers' });
185

186
// Get point halfway along the line
187
const totalLength = length(line, { units: 'kilometers' });
188
const midpoint = along(line, totalLength / 2, { units: 'kilometers' });
189

190
console.log('Point 200km along:', pointAlong.geometry.coordinates);
191
console.log('Midpoint:', midpoint.geometry.coordinates);
192
```
193

194
### Rhumb Line Calculations
195

196
Calculate distances, bearings, and destinations using rhumb lines (lines of constant bearing).
197

198
```typescript { .api }
199
/**
200
 * Calculates the distance along a rhumb line between two points in degrees, radians,
201
 * miles, or kilometers.
202
 */
203
function rhumbDistance(
204
  from: Coord,
205
  to: Coord,
206
  options?: { units?: Units }
207
): number;
208

209
/**
210
 * Takes two points and finds the bearing angle between them along a Rhumb line
211
 * i.e. the angle measured in degrees start the north line (0 degrees).
212
 */
213
function rhumbBearing(start: Coord, end: Coord, options?: { final?: boolean }): number;
214

215
/**
216
 * Returns the destination Point having travelled the given distance along a Rhumb line
217
 * from the origin Point with the (varant) given bearing.
218
 */
219
function rhumbDestination(
220
  origin: Coord,
221
  distance: number,
222
  bearing: number,
223
  options?: { units?: Units; properties?: GeoJsonProperties }
224
): Feature<Point>;
225
```
226

227
**Usage Examples:**
228

229
```typescript
230
import { rhumbDistance, rhumbBearing, rhumbDestination, point } from "@turf/turf";
231

232
const from = point([-75.343, 39.984]);
233
const to = point([-75.534, 39.123]);
234

235
// Rhumb line calculations
236
const rhumbDist = rhumbDistance(from, to, { units: 'kilometers' });
237
const rhumbBear = rhumbBearing(from, to);
238

239
// Find destination along rhumb line
240
const destination = rhumbDestination(from, 100, 45, { 
241
  units: 'kilometers' 
242
});
243

244
console.log(`Rhumb distance: ${rhumbDist} km`);
245
console.log(`Rhumb bearing: ${rhumbBear}°`);
246
console.log('Destination:', destination.geometry.coordinates);
247
```
248

249
### Destination Point Calculation
250

251
Calculate a destination point given a starting point, distance, and bearing.
252

253
```typescript { .api }
254
/**
255
 * Takes a Point and calculates the location of a destination point given a distance
256
 * in degrees, radians, miles, or kilometers; and bearing in degrees.
257
 */
258
function destination(
259
  origin: Coord,
260
  distance: number,
261
  bearing: number,
262
  options?: { units?: Units; properties?: GeoJsonProperties }
263
): Feature<Point>;
264
```
265

266
**Usage Examples:**
267

268
```typescript
269
import { destination, point } from "@turf/turf";
270

271
const origin = point([-75.343, 39.984]);
272

273
// Calculate destination 50km northeast
274
const dest1 = destination(origin, 50, 45, { units: 'kilometers' });
275

276
// Calculate destination 100 miles due north
277
const dest2 = destination(origin, 100, 0, { units: 'miles' });
278

279
console.log('50km NE destination:', dest1.geometry.coordinates);
280
console.log('100mi N destination:', dest2.geometry.coordinates);
281
```
282

283
### Midpoint Calculation
284

285
Calculate the midpoint between two coordinates.
286

287
```typescript { .api }
288
/**
289
 * Takes two points and returns a point midway between them.
290
 * The midpoint is calculated geodesically, meaning the curvature of the earth is taken into account.
291
 */
292
function midpoint(point1: Coord, point2: Coord): Feature<Point>;
293
```
294

295
**Usage Examples:**
296

297
```typescript
298
import { midpoint, point } from "@turf/turf";
299

300
const pt1 = point([144.834823, -37.771257]);
301
const pt2 = point([145.14244, -37.830937]);
302

303
const mid = midpoint(pt1, pt2);
304

305
console.log('Midpoint:', mid.geometry.coordinates);
306
```
307

308
### Bounding Box Calculation
309

310
Calculate the bounding box (extent) of any GeoJSON object.
311

312
```typescript { .api }
313
/**
314
 * Calculates the bounding box for any GeoJSON object, including FeatureCollection.
315
 */
316
function bbox(
317
  geojson: AllGeoJSON,
318
  options?: { recompute?: boolean }
319
): BBox;
320
```
321

322
**Usage Examples:**
323

324
```typescript
325
import { bbox, lineString, bboxPolygon } from "@turf/turf";
326

327
const line = lineString([[-74, 40], [-78, 42], [-82, 35]]);
328
const bounds = bbox(line);
329

330
// Create polygon from bounding box
331
const bboxPoly = bboxPolygon(bounds);
332

333
console.log('Bounding box:', bounds); // [minX, minY, maxX, maxY]
334
```
335

336
### Center Point Calculations
337

338
Calculate various types of center points for feature collections.
339

340
```typescript { .api }
341
/**
342
 * Takes a Feature or FeatureCollection and returns the mean center. Can be weighted.
343
 */
344
function centerMean<P>(
345
  geojson: any,
346
  options?: { properties?: P; bbox?: BBox; id?: Id; weight?: string }
347
): Feature<Point, P>;
348

349
/**
350
 * Takes a Feature or FeatureCollection and returns the median center.
351
 */
352
function centerMedian<P>(
353
  geojson: any,
354
  options?: { properties?: P; bbox?: BBox; id?: Id; weight?: string }
355
): Feature<Point, P>;
356

357
/**
358
 * Takes a Feature or FeatureCollection of Point, LineString, or Polygon features
359
 * and returns the center of mass using this formula: Centroid of Polygon.
360
 */
361
function centerOfMass<P>(
362
  geojson: any,
363
  options?: { properties?: P }
364
): Feature<Point, P>;
365
```
366

367
**Usage Examples:**
368

369
```typescript
370
import { centerMean, centerMedian, centerOfMass, featureCollection, point } from "@turf/turf";
371

372
const features = featureCollection([
373
  point([-97.522259, 35.4691], { value: 10 }),
374
  point([-97.502754, 35.463455], { value: 3 }),
375
  point([-97.508269, 35.463245], { value: 5 })
376
]);
377

378
// Calculate different center types
379
const meanCenter = centerMean(features);
380
const weightedMeanCenter = centerMean(features, { weight: "value" });
381
const medianCenter = centerMedian(features);
382
const massCenter = centerOfMass(features);
383

384
console.log('Mean center:', meanCenter.geometry.coordinates);
385
console.log('Weighted mean center:', weightedMeanCenter.geometry.coordinates);
386
console.log('Median center:', medianCenter.geometry.coordinates);
387
console.log('Center of mass:', massCenter.geometry.coordinates);
388
```
389

390
### Geometric Center
391

392
Calculate the centroid of a feature.
393

394
```typescript { .api }
395
/**
396
 * Takes a Feature or FeatureCollection and returns the centroid using 
397
 * the mean of all vertices.
398
 */
399
function centroid<P>(
400
  geojson: AllGeoJSON,
401
  options?: { properties?: P }
402
): Feature<Point, P>;
403

404
/**
405
 * Takes one or more features and returns their geometric center (centroid).
406
 */
407
function center<P>(
408
  geojson: AllGeoJSON,
409
  options?: { properties?: P }
410
): Feature<Point, P>;
411
```
412

413
**Usage Examples:**
414

415
```typescript
416
import { centroid, center, polygon } from "@turf/turf";
417

418
const poly = polygon([[[0, 0], [0, 10], [10, 10], [10, 0], [0, 0]]]);
419

420
const centroidPt = centroid(poly);
421
const centerPt = center(poly);
422

423
console.log('Centroid:', centroidPt.geometry.coordinates);
424
console.log('Center:', centerPt.geometry.coordinates);
425
```