@cdeshpande/geo-utils/readme.md

A lightweight, blazing-fast TypeScript library for calculating distances (Haversine) and geospatial math with support for kilometers and miles.

# geo-utils

A lightweight and extensible TypeScript utility library for geospatial calculations such as:

-   🌍 Haversine distance between two coordinates
-   📍 Midpoint between two geographic points
-   🌍 Vincenty distance
-   🌍 Bearing (also called forward azimuth)
-   🌍 DestinationPoint — Compute Destination from Distance & Bearing

Supports **kilometers** and **miles**, with built-in input validation.

vincentyDistance calculates the geodesic distance between two geographic coordinates using the Vincenty inverse formula on the WGS-84 ellipsoid. It provides high-precision results suitable for long-distance measurements and real-world applications like aviation and GPS.

Calculates the initial bearing (also called forward azimuth) between two geographic coordinates. The result is the angle in degrees from North (0°) to the direction of the destination point, moving along the great-circle path.

Calculates the initial bearing (also called forward azimuth) between two geographic coordinates. The result is the angle in degrees from North (0°) to the direction of the destination point, moving along the great-circle path.

Calculate the destination point given: - a starting latitude/longitude, - a distance (in kilometers or miles), - and a bearing (angle from true north in degrees).

## 📦 Installation

`npm install @cdeshpande/geo-utils`

## 🚀 Haversine Usage

```
import { haversineDistance } from '@cdeshpande/geo-utils';

// Define coordinates
const start = {
  latitude: 30.849635,
  longitude: -83.24559
};

const end = {
  latitude: 27.950575,
  longitude: -82.457178
};

// Calculate distance in kilometers (default)
console.log(haversineDistance(start.latitude, start.longitude, end.latitude, end.longitude));
// → 403.28 (km)

// Calculate distance in miles
console.log(haversineDistance(start.latitude, start.longitude, end.latitude, end.longitude, 'miles'));
// → 250.47 (miles)
```

## 🚀 Midpoint Usage

```
// Midpoint
const mid = midpoint(start.latitude, start.longitude, end.latitude, end.longitude);
console.log(mid); // → { latitude: 29.41499, longitude: -82.851384 }
```

## 🚀 Vincenty Usage

```
import { vincentyDistance } from '@cdeshpande/geo-utils';

// Define two geographic points (latitude, longitude)
const paris = { lat: 48.8566, lon: 2.3522 };
const nyc = { lat: 40.7128, lon: -74.006 };

// Get distance in meters
const distance = vincentyDistance(paris.lat, paris.lon, nyc.lat, nyc.lon);
console.log(`Distance: ${(distance / 1000).toFixed(2)} km`);
// Output: Distance: 5853.00 km
```

## 🚀 Bearing Usage

```
import { initialBearing } from '@cdeshpande/geo-utils';
const bearing = initialBearing(30, -90, 40, -80);
console.log(`Initial Bearing: ${bearing.toFixed(2)}°`); // → Initial Bearing: 37.23°
```

## 🚀 DestinationPoint Usage

```
import { destinationPoint } from '@cdeshpande/geo-utils';

const start = { latitude: 0, longitude: 0 };
const distance = 100; // in kilometers
const bearing = 90;   // due east

const destination = destinationPoint(
  start.latitude,
  start.longitude,
  distance,
  bearing
);

console.log(destination);
// → { latitude: ~0.0, longitude: ~0.899 }
```

## 📘 API

### haversineDistance(lat1: number, lon1: number, lat2: number, lon2: number, unit?: string): number

| Param | Type              | Required | Description                          |
| ----- | ----------------- | -------- | ------------------------------------ |
| lat1  | `number`          | ✅       | Latitude of the first point          |
| lon1  | `number`          | ✅       | Longitude of the first point         |
| lat2  | `number`          | ✅       | Latitude of the second point         |
| lon2  | `number`          | ✅       | Longitude of the second point        |
| unit  | `'km' \| 'miles'` | ❌       | Unit of distance (default is `'km'`) |

### midpoint(lat1: number, lon1: number, lat2: number, lon2: number): { latitude: number, longitude: number }

| Param | Type     | Required | Description                   |
| ----- | -------- | -------- | ----------------------------- |
| lat1  | `number` | ✅       | Latitude of the first point   |
| lon1  | `number` | ✅       | Longitude of the first point  |
| lat2  | `number` | ✅       | Latitude of the second point  |
| lon2  | `number` | ✅       | Longitude of the second point |

### vincentyDistance(lat1: number, lon1: number, lat2: number, lon2: number): number

| Param | Type     | Required | Description                   |
| ----- | -------- | -------- | ----------------------------- |
| lat1  | `number` | ✅       | Latitude of the first point   |
| lon1  | `number` | ✅       | Longitude of the first point  |
| lat2  | `number` | ✅       | Latitude of the second point  |
| lon2  | `number` | ✅       | Longitude of the second point |

### initialBearing(lat1, lon1, lat2, lon2): number

| Param | Type     | Required | Description                   |
| ----- | -------- | -------- | ----------------------------- |
| lat1  | `number` | ✅       | Latitude of the first point   |
| lon1  | `number` | ✅       | Longitude of the first point  |
| lat2  | `number` | ✅       | Latitude of the second point  |
| lon2  | `number` | ✅       | Longitude of the second point |

### destinationPoint( lat: number, lon: number, distance: number, bearing: number, unit: 'km' | 'miles'): { latitude: number; longitude: number }

| Param   | Type              | Required | Description                                      |
| ------- | ----------------- | -------- | ------------------------------------------------ |
| lat1    | `number`          | ✅       | Latitude of the first point                      |
| lon1    | `number`          | ✅       | Longitude of the first point                     |
| lat2    | `number`          | ✅       | Latitude of the second point                     |
| lon2    | `number`          | ✅       | Longitude of the second point                    |
| bearing | `number`          | ✅       | Direction to travel (in degrees from true north) |
| unit    | `'km' \| 'miles'` | ❌       | Unit of distance (default is `'km'`)             |

## 🔒 Validations

-   Throws `TypeError` if latitude/longitude is not a number.
-   Throws `RangeError` if coordinates are out of bounds.
-   Throws `Error` if unit is not `'km'` or `'miles'`.

## 🧾 License

MIT © Chaitanya Deshpande