@erexstudio/geo-span-measure/README.md

A simple npm package for calculating distance between two coordinates using the Haversine formula.

![Logo](https://res.cloudinary.com/dtwvobf3j/image/upload/v1706284707/geo-span-measure_cikupf.png)

## @erexstudio/geo-span-measure

A simple npm package for calculating distance between two coordinates using the Haversine formula.

![NPM Version](https://img.shields.io/npm/v/%40erexstudio%2Fgeo-span-measure)
![NPM Downloads](https://img.shields.io/npm/dt/%40erexstudio%2Fgeo-span-measure)
![npm bundle size](https://img.shields.io/bundlephobia/min/%40erexstudio%2Fgeo-span-measure)
![NPM License](https://img.shields.io/npm/l/%40erexstudio%2Fgeo-span-measure)

## Installation

This is a **<span style="color: #CB3837;">Node.js</span>** module available through the **<span style="color: #CB3837;">npm registry</span>**.

Before installing, **<span style="color: #CB3837;">download and install Node.js</span>**. Node.js 0.10 or higher is required.

If this is a brand new project, make sure to create a `package.json` first with the **<span style="color: #CB3837;">npm init</span>** command.

Installation is done using the **<span style="color: #CB3837;">npm install</span>** command:

```bash
  $ npm install @erexstudio/geo-span-measure
```

## Features

- Simple npm installation for quick integration.
- Accepts latitude and longitude coordinates as arrays.
- Calculates distances in kilometers, miles, or meters.
- Robust error handling for smooth user experience.
- Returns distance with two decimal places.
- Uses the Haversine formula for accurate results.
- Suitable for **Node.js**, **React.js**, **Next.js**, and various **JavaScript** applications.

## Usage

- **<span style="color: #CB3837;">Back-End</span>** ( Node JS )

```javascript
const haversineDistance = require("@erexstudio/geo-span-measure");

const coord1 = [latitude1, longitude1]; // Replace with actual coordinates
const coord2 = [latitude2, longitude2]; // Replace with actual coordinates

// Calculate distance in kilometers (default)
const distanceInKilometers = haversineDistance(coord1, coord2);
console.log(`Distance in kilometers: ${distanceInKilometers} km`);

// Calculate distance in miles
const distanceInMiles = haversineDistance(coord1, coord2, "miles");
console.log(`Distance in miles: ${distanceInMiles} miles`);

// Calculate distance in meters
const distanceInMeters = haversineDistance(coord1, coord2, "meters");
console.log(`Distance in meters: ${distanceInMeters} meters`);
```

- **<span style="color: #CB3837;">Front-End</span>** ( React JS, Next JS, etc )

```javascript
import haversineDistance from "@erexstudio/geo-span-measure";

// Example coordinates
const coord1 = [latitude1, longitude1]; // Replace with actual coordinates
const coord2 = [latitude2, longitude2]; // Replace with actual coordinates

// Calculate distance in kilometers (default)
const distanceInKilometers = haversineDistance(coord1, coord2);

// Calculate distance in miles
const distanceInMiles = haversineDistance(coord1, coord2, "miles");

// Calculate distance in meters
const distanceInMeters = haversineDistance(coord1, coord2, "meters");
```

## Function Explanation

The **<span style="color: #CB3837;">@erexstudio/geo-span-measure</span>** package takes two sets of coordinates and an optional unit parameter (defaulting to **kilometers** if not specified). It uses the Haversine formula to calculate the distance between the two points on the Earth's surface.

## Parameters

- `coord1` : Array containing the **latitude** and **longitude** of the first coordinate.
- `coord2` : Array containing the **latitude** and **longitude** of the second coordinate.
- `unit` : Optional string parameter specifying the desired **unit** for the output distance (**'kilometers'**, **'miles'**, or **'meters'**).

## Return Value

The function returns the calculated distance between the **two coordinates** in the specified **unit**.

## Example

```js
const distanceInKilometers = haversineDistance(
  [37.7749, -122.4194],
  [34.0522, -118.2437]
);
console.log(`Distance in kilometers: ${distanceInKilometers} km`);
```

## Earth Radius

The function uses the following **Earth radius** for different **units**:

- `Kilometers` : 6357 km
- `Miles` : 3950 miles
- `Meters` : 6371000 meters

Users can specify the **unit** according to their preference.

## License

This project is licensed under the **<span style="color: #CB3837;">ISC License</span>** - see the LICENSE file for details.

This README includes explanations for the parameters, return value, example usage, a note about distance formatting, and details about Earth radius for different units. Adjustments can be made based on your specific requirements and preferences.