Geolocation Utilities

1.2.6 · active · verified Sun Apr 19

geolocation-utils is a JavaScript/TypeScript library designed for performing various calculations and conversions related to geographical locations. As of its latest stable release, version 1.2.6, published approximately a year ago, the library focuses on providing utility functions rather than direct device geolocation access. It enables conversion between common location formats like `[lon, lat]`, `{lat, lon}`, `{lat, lng}`, and `{latitude, longitude}`. Key functionalities include calculating distances and headings between points, moving a specified distance to a new location, determining bounding boxes around a list of locations, and checking if a location falls within a given polygon, circle, or bounding box. The library differentiates itself by using plain JavaScript objects for locations, which simplifies serialization and interoperability with other libraries and REST APIs. While there isn't a strict major release cadence, development appears active on GitHub with periodic updates.

Common errors

```
TypeError: Cannot read properties of undefined (reading '1') or incorrect geographic results when using array inputs.
```
cause This usually occurs when a `LonLatTuple` (array) is provided with coordinates in the wrong order, i.e., `[latitude, longitude]` instead of the expected `[longitude, latitude]`. The library specifically expects `[lon, lat]` for array inputs, which can lead to misinterpretation of geographical points or errors if the array indices are accessed out of bounds for an object that was not an array.

fix Verify that `LonLatTuple` inputs are strictly in `[longitude, latitude]` order. For example, use `[4, 51]` for 4° Longitude, 51° Latitude. If possible, refactor to use object literals like `{ lat: 51, lon: 4 }` for clearer intent and to prevent this common pitfall.

Warnings

gotcha Be extremely careful with coordinate order when using array-based location formats (`LonLatTuple`). The library *expects* `[longitude, latitude]` for these tuples, which is contrary to some other common GIS standards that use `[latitude, longitude]`. To avoid issues, using object-based formats like `{lat: number, lon: number}` is strongly recommended.
Fix: Always double-check the expected order of coordinates for input arrays. Prefer using object-based location formats (e.g., `{lat, lon}`) which are less ambiguous.
gotcha The library supports multiple object-based formats, including `{lat, lon}`, `{lat, lng}`, and `{latitude, longitude}`. While flexible, ensure consistency in your application's data structures to prevent unexpected behavior. Functions that return a `Location` will typically maintain the input format if possible, but conversions can lead to different property names.
Fix: Standardize on one object format (e.g., `{lat, lon}`) within your application or use the provided conversion utilities (`toLatLon`, `toLatLng`, etc.) explicitly when interacting with external APIs or different data sources.

Install

npm install geolocation-utils npm
yarn add geolocation-utils yarn
pnpm add geolocation-utils pnpm

Imports

toLatLon
wrong:
```
const { toLatLon } = require('geolocation-utils')
```
correct:
```
import { toLatLon } from 'geolocation-utils'
```
The library primarily uses ES Module syntax. CommonJS `require` might work via transpilation but ESM is recommended. Ships with TypeScript types.

headingDistanceTo

wrong:

const headingDistanceTo = require('geolocation-utils').headingDistanceTo

correct:

import { headingDistanceTo } from 'geolocation-utils'

Named export for calculating heading and distance between two locations.

insidePolygon
wrong:
```
import insidePolygon from 'geolocation-utils'
```
correct:
```
import { insidePolygon } from 'geolocation-utils'
```
All utility functions are named exports, there is no default export.
createLocation
```
import { createLocation } from 'geolocation-utils'
```
Useful for programmatically creating location objects in a specific format.

Quickstart

Demonstrates basic usage including format conversion, distance calculation, moving to a new point, and checking if a point is within a polygon.

import { 
  toLatLon, headingDistanceTo, moveTo, insidePolygon 
} from 'geolocation-utils';

// Convert various location formats
console.log(toLatLon([4, 51]));                        
// { lat: 51, lon: 4 }

// Calculate distance and heading, then move to a new location
const location1 = {lat: 51, lon: 4};
const location2 = {lat: 51.001, lon: 4.001 };
const { heading, distance } = headingDistanceTo(location1, location2);
console.log({ heading, distance }); 
// { heading: 32.18..., distance: 131.52... }

const newLocation = moveTo(location1, {heading, distance});
console.log(newLocation);
// { lat: 51.001000..., lon: 4.000997... }

// Check if a location is inside a polygon
const polygon = [
  [4.03146, 51.9644],
  [4.03151, 51.9643],
  [4.03048, 51.9627],
  [4.04550, 51.9600],
  [4.05279, 51.9605],
  [4.05215, 51.9619],
  [4.04528, 51.9614],
  [4.03146, 51.9644]
];
console.log(insidePolygon([4.03324, 51.9632], polygon)); // true

view raw JSON →