v0.1.0

@simoko/geo-distance

Lightweight, zero-dependency library for geographic distance calculations.
Haversine formula, bearing, midpoint, bounding box, and more.

Interactive Playground API Reference

npm install @simoko/geo-distance

Distance

Haversine formula for accurate great-circle distance

Bearing

Initial bearing / forward azimuth between points

Midpoint

Geographic midpoint along the great circle

Bounding Box

Rectangular bounds around a center + radius

Nearest / Filter

Find closest points or filter by radius

Zero Dependencies

Tiny bundle, tree-shakeable ESM + CJS

Quick Start

import { between, bearing, midpoint } from '@simoko/geo-distance'

const taipei = { lat: 25.085, lng: 121.397 }
const kenting = { lat: 21.958, lng: 120.779 }

between(taipei, kenting)          // 348.5263 km
bearing(taipei, kenting)          // 190.6121 degrees
midpoint(taipei, kenting)         // { lat: 23.518, lng: 121.075 }

Types

Coord

interface Coord {
  name?: string
  lat: number
  lng: number
}

BoundingBox

interface BoundingBox {
  minLat: number
  maxLat: number
  minLng: number
  maxLng: number
}

Unit

type Unit = 'km' | 'm' | 'ft'

// Earth's radius:
// km: 6378.137
// m:  6378137
// ft: 20902231.52

API Reference

`between(a, b, unit?, digits?)`

returns number

Calculate distance between two coordinates using the Haversine formula.

Param	Type	Description
`a`	`Coord`	First coordinate
`b`	`Coord`	Second coordinate
`unit`	`'km' \| 'm' \| 'ft'`	Unit of measurement (default: 'km')
`digits`	`number`	Decimal places (default: 4)

between(
  { lat: 25.085, lng: 121.397 },
  { lat: 21.958, lng: 120.779 }
)
// => 348.5263

`bearing(a, b, digits?)`

returns number (0-360)

Calculate the initial bearing (forward azimuth) from A to B.

Param	Type	Description
`a`	`Coord`	Origin coordinate
`b`	`Coord`	Destination coordinate
`digits`	`number`	Decimal places (default: 4)

bearing(
  { lat: 25.08, lng: 121.39 },
  { lat: 21.95, lng: 120.77 }
)
// => 190.6121

`midpoint(a, b, digits?)`

returns Coord

Calculate the geographic midpoint between two coordinates.

Param	Type	Description
`a`	`Coord`	First coordinate
`b`	`Coord`	Second coordinate
`digits`	`number`	Decimal places (default: 6)

midpoint(
  { lat: 25.08, lng: 121.39 },
  { lat: 21.95, lng: 120.77 }
)
// => { lat: 23.518, lng: 121.075 }

`destination(origin, distance, bearing, unit?, digits?)`

returns Coord

Calculate the destination given a start point, distance, and bearing.

Param	Type	Description
`origin`	`Coord`	Starting coordinate
`distance`	`number`	Distance to travel
`bearing`	`number`	Bearing in degrees (0-360)
`unit`	`'km' \| 'm' \| 'ft'`	Unit (default: 'km')
`digits`	`number`	Decimal places (default: 6)

destination(
  { lat: 25.08, lng: 121.39 },
  100, 180
)
// => { lat: 24.173, lng: 121.39 }

`boundingBox(center, radius, unit?, digits?)`

returns BoundingBox

Calculate a bounding box around a center with a given radius.

Param	Type	Description
`center`	`Coord`	Center coordinate
`radius`	`number`	Radius distance
`unit`	`'km' \| 'm' \| 'ft'`	Unit (default: 'km')
`digits`	`number`	Decimal places (default: 6)

boundingBox(
  { lat: 25.08, lng: 121.39 },
  10
)
// => { minLat: 24.99, maxLat: 25.17, ... }

`isWithin(a, b, radius, unit?)`

returns boolean

Check if two coordinates are within a given distance.

Param	Type	Description
`a`	`Coord`	First coordinate
`b`	`Coord`	Second coordinate
`radius`	`number`	Maximum distance
`unit`	`'km' \| 'm' \| 'ft'`	Unit (default: 'km')

isWithin(
  { lat: 25.08, lng: 121.39 },
  { lat: 25.04, lng: 121.56 },
  20
)
// => true

`nearest(target, coords, unit?)`

returns Coord

Find the nearest coordinate to the target from an array.

Param	Type	Description
`target`	`Coord`	Target coordinate
`coords`	`Coord[]`	Array of candidates
`unit`	`'km' \| 'm' \| 'ft'`	Unit (default: 'km')

nearest(
  { lat: 23.15, lng: 120.17 },
  [taipei, taichung, kenting]
)
// => taichung

`filterWithin(target, coords, radius, unit?)`

returns Coord[]

Filter coordinates within a given radius from the target.

Param	Type	Description
`target`	`Coord`	Target coordinate
`coords`	`Coord[]`	Array of coordinates
`radius`	`number`	Maximum distance
`unit`	`'km' \| 'm' \| 'ft'`	Unit (default: 'km')

filterWithin(
  { lat: 23.15, lng: 120.17 },
  coords, 150
)
// => [taichung, kenting]

`nearSort(target, coords, unit?)`

returns Coord[]

Sort coordinates by distance from the target, nearest first.

Param	Type	Description
`target`	`Coord`	Target coordinate
`coords`	`Coord[]`	Array of coordinates
`unit`	`'km' \| 'm' \| 'ft'`	Unit (default: 'km')

nearSort(
  { lat: 23.15, lng: 120.17 },
  [taipei, taichung, kenting]
)
// => [taichung, kenting, taipei]