geographiclib-geodesic

2.2.0 verified Mon Apr 27 auth: no javascript

JavaScript implementation of the geodesic routines from GeographicLib for solving direct and inverse geodesic problems on an ellipsoid of revolution. Current stable version is 2.2.0, released on 2025-01-01 with monthly releases. Key differentiators: high accuracy (nanometer precision), pure JavaScript with no native dependencies, TypeScript types included, supports both ESM and CJS. Used for distance, azimuth, and destination calculations on the WGS84 ellipsoid and other reference ellipsoids. Split from monolithic geographiclib package in v2.0.0 into this and geographiclib-dms.

Common errors

error Cannot find module 'geographiclib-geodesic' ↓

cause Package not installed or incorrect import path after split from geographiclib.

fix

Run 'npm install geographiclib-geodesic' and ensure import path is correct: require('geographiclib-geodesic') or import { Geodesic } from 'geographiclib-geodesic'.

error Geodesic.WGS84 is undefined ↓

cause Using outdated import from the deprecated 'geographiclib' package where Geodesic was not available.

fix

Install 'geographiclib-geodesic' and import { Geodesic } from 'geographiclib-geodesic'.

error import { Geodesic } from 'geographiclib-geodesic' works in Node but not in browser (with webpack or parcel) ↓

cause Webpack may not resolve the package correctly if it's not configured for ESM or if there is a version mismatch.

fix

Ensure you are using a bundler that supports ESM (e.g., webpack 5 with experiments.outputModule) or use CommonJS require(). Alternatively, use the browser-ready file from 'geographiclib-geodesic/geographiclib-geodesic.min.js'.

error TypeError: geod.Inverse(...) is not a function or returns undefined ↓

cause The geod object is not a Geodesic instance but the module itself (require returns the whole module).

fix

Use const geod = require('geographiclib-geodesic').Geodesic.WGS84 or import { Geodesic } from 'geographiclib-geodesic'; const geod = Geodesic.WGS84;

error Result latitude is NaN or longitude is NaN ↓

cause Input coordinates out of range or azimuth/distance not finite.

fix

Check that latitudes are between -90 and 90, longitudes between -180 and 180, azimuth between 0 and 360, distance positive finite.

Warnings

breaking Version 2.0.0 split from monolithic geographiclib package. Imports changed from 'geographiclib' to 'geographiclib-geodesic' and 'geographiclib-dms'. ↓

fix Update imports: use 'geographiclib-geodesic' for geodesic functions and optionally 'geographiclib-dms' for DMS conversion. The old 'geographiclib' package will be deprecated after 2023-05-01.

breaking In v2.0.0, ES module support was added. The package now exports ESM by default. CommonJS require still works but may behave differently in some bundlers. ↓

fix For ESM: use import { Geodesic } from 'geographiclib-geodesic'. For CJS: use const { Geodesic } = require('geographiclib-geodesic').

deprecated The old monolithic package 'geographiclib' (which included DMS functions) is deprecated after 2023-05-01. Users should migrate to 'geographiclib-geodesic' and optionally 'geographiclib-dms'. ↓

fix Replace require('geographiclib') with require('geographiclib-geodesic') and if using DMS, add require('geographiclib-dms').

gotcha Geodesic.WGS84 is a static property on the Geodesic class, not a separate export. Trying to import { WGS84 } directly fails. ↓

fix Use Geodesic.WGS84 after importing { Geodesic }.

gotcha The Direct and Inverse methods return objects with many properties (lat2, lon2, azi1, azi2, s12, etc.). Not reading the full result may lead to missing azimuth or distance values. ↓

fix Always store the result and access the needed properties. See documentation for complete list.

gotcha Coordinates are in degrees; azimuths are in degrees from north (clockwise). Distances are in meters. No unit conversion is performed. ↓

fix Ensure inputs are in degrees and meters as expected. Convert if necessary.

Install

npm install geographiclib-geodesic

yarn add geographiclib-geodesic

pnpm add geographiclib-geodesic

Imports

Geodesic

wrong

const Geodesic = require('geographiclib-geodesic').Geodesic

correct

import { Geodesic } from 'geographiclib-geodesic'

ESM import since v2.0.0. CommonJS require works but without destructuring.

WGS84

wrong

import { WGS84 } from 'geographiclib-geodesic'

correct

const { Geodesic } = require('geographiclib-geodesic'); const geod = Geodesic.WGS84;

WGS84 is a static property, not a named export. Use Geodesic.WGS84 or new Geodesic('WGS84').

default import
```
import geographiclib from 'geographiclib-geodesic'
```
Default import gives the whole module. Not recommended; prefer named imports.

Quickstart

Solves inverse geodesic (distance & azimuth between two points) and direct geodesic (destination from point, azimuth, distance) using WGS84 ellipsoid, plus polygon area computation.

import { Geodesic } from 'geographiclib-geodesic';

const geod = Geodesic.WGS84;

// Inverse problem: distance and azimuth between two points
const r1 = geod.Inverse(-41.32, 174.81, 40.96, -5.50);
console.log(`Distance: ${r1.s12.toFixed(3)} m`);
console.log(`Azimuth from A: ${r1.azi1.toFixed(8)}°`);
console.log(`Azimuth from B: ${r1.azi2.toFixed(8)}°`);

// Direct problem: point given start point, azimuth, and distance
const r2 = geod.Direct(-32.06, 115.74, 225, 20000e3);
console.log(`Destination: (${r2.lat2.toFixed(8)}, ${r2.lon2.toFixed(8)})`);
console.log(`Final azimuth: ${r2.azi2.toFixed(8)}°`);

// Polygon area (example: simple triangle)
const geodPoly = Geodesic.WGS84;
const poly = geodPoly.Polygon(false);
poly.AddPoint(0, 0);
poly.AddPoint(1, 0);
poly.AddPoint(0, 1);
const result = poly.Compute();
console.log(`Perimeter: ${result.perimeter.toFixed(3)} m`);
console.log(`Area: ${result.area.toFixed(3)} m²`);