haversine-ts

About

Typescript library for distance calculation on a sphere surface with both decimal degrees (DD) or degrees minutes seconds (DMS) coordinates.

Main package features:

• Allows calculating distances between to points in metres, kilometres or miles.
• Allows using decimal degree (DD) or degrees minutes seconds (DMS) coordinates.
• Allows calculating start and end bearings of a path between two points.
• Allows calculating the end point of a path given its start point, start bearing and distance.
• Allows sorting points by distance from a reference point.
• Allows finding points within a specific distance range from a reference point.

At a glance

Calculate the distance, in kilometres, between two decimal degrees coordinates

import { DDPoint, Haversine } from "haversine-ts";

// New York decimal degrees (DD) coordinates are:
// latitude 40.730610 N,
// longitude 73.935242 W
const newYork = new DDPoint(40.73061, -73.935242);

// Madrid decimal degrees (DD) coordinates are:
// latitude 40.416775 N,
// longitude 3.703790 W
const madrid = new DDPoint(40.416775, -3.70379);

const haversine = new Haversine();
const distance = haversine.getDistance(newYork, madrid);

console.log(`The distance from New York to Madrid is ${distance} kilometres.`);

Calculate the distance, in miles, between two degrees minutes seconds (DMS) coordinates

import {
  DMSCoordinate,
  DMSPoint,
  Haversine,
  UnitOfDistance
} from "haversine-ts";

// New York DMS coordinates are
// latitude 40° 43' 50.1960'' N,
// longitude 73° 56' 6.8712'' W
const newYork = new DMSPoint(
  new DMSCoordinate(40, 43, 50.196),
  new DMSCoordinate(-73, 56, 6.8712)
);

// Madrid DMS coordinates are
// latitude 40° 25' 0.3900'' N,
// longitude 3° 42' 13.6440'' W
const madrid = new DMSPoint(
  new DMSCoordinate(40, 25, 0.39),
  new DMSCoordinate(-3, 42, 13.644)
);

const haversine = new Haversine(UnitOfDistance.Mile);
const distance = haversine.getDistance(newYork.toDDPoint(), madrid.toDDPoint());

console.log(`The distance from New York to Madrid is ${distance} miles.`);

Calculate the bearing between two points

import { DDPoint, Haversine } from "haversine-ts";

const newYork = new DDPoint(40.73061, -73.935242);
const madrid = new DDPoint(40.416775, -3.70379);

const haversine = new Haversine();
const bearing = haversine.getBearing(newYork, madrid);

console.log(
  `The start bearing of the path from New York to Madrid is ${bearing.start} degrees, and the end bearing is ${bearing.end} degrees.`
);

Calculate the endpoint of a path

import { DDPoint, Haversine } from "haversine-ts";

const newYork = new DDPoint(40.73061, -73.935242);
const bearing = 65.71472;
const distance = 5762;

const haversine = new Haversine();
const madrid = haversine.getPoint(newYork, bearing, distance);

console.log(
  `Madrid is the endpoint of the path starting in New York with a bearing of ${bearing} degrees at a distance of ${distance} kilometers`
);

Sort points by distance from a reference point

import { DDPoint, Haversine, Sorting } from "haversine-ts";

const madrid = new DDPoint(40.416775, -3.70379);
const cities = [
  new DDPoint(52.5200, 13.4050),     // Berlin
  new DDPoint(40.73061, -73.935242), // New York
  new DDPoint(48.8566, 2.3522),      // Paris
  new DDPoint(35.6762, 139.6503)     // Tokyo
];

const haversine = new Haversine();
const sortedCities = haversine.sortByDistance(madrid, cities);

console.log(
  `The cities sorted by distance from Madrid (nearest to farthest) are:`
);
sortedCities.forEach((point, index) => {
  console.log(`${index + 1}. Latitude ${point.latitude}, Longitude ${point.longitude}`);
});

Find points within a specific distance range

import { DDPoint, Haversine } from "haversine-ts";

const madrid = new DDPoint(40.416775, -3.70379);
const cities = [
  new DDPoint(52.5200, 13.4050),     // Berlin
  new DDPoint(40.73061, -73.935242), // New York
  new DDPoint(48.8566, 2.3522),      // Paris
  new DDPoint(35.6762, 139.6503)     // Tokyo
];

const haversine = new Haversine();
// Find cities within 2000 kilometers of Madrid
const citiesInRange = haversine.getInRange(madrid, cities, 2000);

console.log(
  `The cities within 2000 kilometers from Madrid are:`
);
citiesInRange.forEach((point, index) => {
  console.log(`${index + 1}. Latitude ${point.latitude}, Longitude ${point.longitude}`);
});

Installation

To install the package using nmp simply run this command in the root folder of your node project:

npm install haversine-ts

Usage

Overview

The Haversine class supports the implementation of the sphere path resolvers (distance and bearing between two points, end point given start point, bearing and distance).

It uses as input decimal degrees (DD) coordinates defined as DDPoint class object instances, that can be converted into degrees minutes seconds (DMS) coordinates as instances of the DMSPoint class. Each DMSPoint object instance is composed by two DMSCoordinate class object instances.

The SphereBearing class represents a tuple with the start and end bearings of a sphere path (orthodrome) between two points.

DDPoint class

Sphere point defined by a latitude and a longitude in decimal degrees (DD)

• Constructors:
  • new DDPoint(latitude, longitude)
• Properties:
  • latitude
  • longitude
• Methods:
  • .toDMSPoint() ⇒ DMSPoint

new DDPoint(latitude, longitude)

Creates a sphere point object instance.

import { DDPoint } from "haversine-ts";

const newYork = new DDPoint(40.73061, -73.935242);

console.log(
  `The coordinates of New York, in decimal notation, are latitude ${newYork.latitude}, longitude ${newYork.longitude}`
);

ddPoint.latitude ⇒ number

Returns the point latitude set in the object instance constructor.

ddPoint.longitude ⇒ number

Returns the point longitude set in the object instance constructor.

ddPoint.toDMSPoint() ⇒ DMSPoint

Gets the equivalent point in degrees minutes seconds (DMS) notation.

import { DDPoint } from "haversine-ts";

const newYork = new DDPoint(40.73061, -73.935242);
const newYorkDMS = newYork.toDMSPoint();

console.log(
  `The coordinates of New York, in DMS notation, are ${newYorkDMS.degrees} degrees, ${newYorkDMS.minutes} minutes, ${newYorkDMS.seconds} seconds`
);

• Returns:
  • DMSPoint - Equivalent sphere point defined in degrees minutes seconds (DMS) notation

DMSCoordinate

Latitude/Longitude coordinate defined in degrees minutes seconds (DMS).

• Constructors:
  • new DMSCoordinate(degrees, minutes, seconds)
• Properties:
  • degrees
  • minutes
  • seconds

new DMSCoordinate(degrees, minutes, seconds)

Initializes a DMSCoordinate object instance.

import { DMSCoordinate } from "haversine-ts";

const newYorkLatitude = new DMSCoordinate(40, 43, 50.196);

console.log(
  `The New York latitude, in DMS notation, is ${newYorkLatitude.degrees} degrees, ${newYorkLatitude.minutes} minutes, ${newYorkLatitude.seconds} seconds,`
);

• Parameters
  • degrees (number): Coordinate degrees, from -180 to 180.
  • minutes (number): Coordinate minutes, from 0 to <60.
  • seconds (number): Coordinate seconds, from 0 to <60.
• Throws:
  • Error if degrees, minutes or seconds are out of range.

dmsCoordinate.degrees ⇒ number

Returns the coordinate degrees set in the constructor.

dmsCoordinate.minutes ⇒ number

Returns the coordinate minutes set in the constructor.

dmsCoordinate.seconds ⇒ number

Returns the coordinate seconds set in the constructor.

DMSPoint class

Sphere point defined by a latitude and a longitude in degrees minutes seconds (DMS).

• Constructors:
  • new DMSPoint(latitude, longitude)
• Properties
  • latitude
  • longitude
• Methods:
  • .toDDPoint() ⇒ DDPoint

new DMSPoint(latitude, longitude)

Creates a sphere point object instance in DMS notation.

import { DMSPoint } from "haversine-ts";

const newYork = new DMSPoint(
  new DMSCoordinate(40, 43, 50.196),
  new DMSCoordinate(-73, 56, 6.8712)
);

const newYorkLatitude = newYork.latitude;
const newYorkLongitude = newYork.longitude;

console.log(
  `The New York coordinates, in DMS notation, are latitude ${newYorkLatitude.degrees} degrees ${newYorkLatitude.minutes} minutes, ${newYorkLatitude.seconds} seconds, longitude ${newYorkLongitude.degrees} degrees ${newYorkLongitude.minutes} minutes, ${newYorkLongitude.seconds} seconds`
);

• Parameters
  • latitude (DMSCoordinate): Latitude coordinate in degrees minutes seconds.
  • longitude (DMSCoordinate): Longitude coordinate in degrees minutes seconds.
• Throws:
  • Error if latitude degrees are out of range (-90 to 90).

dmsPoint.latitude ⇒ DMSCoordinate

Returns the point latitude set in the constructor.

dmsPoint.longitude ⇒ DMSCoordinate

Returns the point longitude set in the constructor.

dmsPoint.toDDPoint() ⇒ DDPoint

Gets the equivalent point in decimal degrees notation.

import { DMSPoint } from "haversine-ts";

const newYork = new DMSPoint(
  new DMSCoordinate(40, 43, 50.196),
  new DMSCoordinate(-73, 56, 6.8712)
);
const newYorkDD = newYork.toDDPoint();

console.log(
  `The coordinates of New York, in DD notation, are latitude ${newYorkDD.latitude}, longitude ${newYorkDD.longitude}`
);

• Returns:
  • DDPoint - Equivalent sphere point defined in decimal degrees (DD) notation.

Haversine class

Haversine formula resolver.

• Constructors:
  • new Haversine([uod], [sphereRadius])
• Methods:
  • .getBearing(startPoint, endPoint) ⇒ SphereBearing
  • .getDistance(pointA, pointB) ⇒ number
  • .getPoint(startPoint, bearing, distance) ⇒ DDPoint
  • .sortByDistance(referencePoint, points, [sorting]) ⇒ DDPoint[]
  • .getInRange(referencePoint, points, distance) ⇒ DDPoint[]

new Haversine([uod], [sphereRadius])

Initializes the Haversine resolver.

import { Haversine, UnitOfDistance } from "haversine-ts";

const haversine = new Haversine(UnitOfDistance.Mile);

• Parameters:
  • uod (UnitOfDistance, optional): Unit of distance (default: UnitOfDistance.Kilometre)
  • sphereRadius (number, optional): Custom sphere radius in uod units (default: equatorial Earth radius).

haversine.getBearing(startPoint, endPoint) ⇒ SphereBearing

Calculates the sphere bearing, or start and end bearings, of the path between two points in a sphere.

import { DDPoint, Haversine } from "haversine-ts";

const newYork = new DDPoint(40.73061, -73.935242);
const madrid = new DDPoint(40.416775, -3.70379);

const haversine = new Haversine();
const bearing = haversine.getBearing(newYork, madrid);

console.log(
  `The start bearing of the path from New York to Madrid is ${bearing.start} degrees, and the end bearing is ${bearing.end} degrees.`
);

• Parameters:
  • startPoint (DDPoint): Start point, in decimal degrees coordinates.
  • endPoint (DDPoint): End point, in decimal degrees coordinates.
• Returns:
  • SphereBearing - Bearings of the path from startPoint to endPoint, in degrees (0 to 360, clockwise from North).

haversine.getDistance(pointA, pointB) ⇒ number

Calculates the distance between to sphere points defined as decimal degrees (DD) coordinates.

import { DDPoint, Haversine } from "haversine-ts";

const newYork = new DDPoint(40.73061, -73.935242);
const madrid = new DDPoint(40.416775, -3.70379);

const haversine = new Haversine();

const distance = haversine.getDistance(newYork, madrid);

console.log(`The distance from New York to Madrid is ${distance} kilometres.`);

• Parameters:
  • pointA (DDPoint): Point A, in decimal degrees coordinates.
  • pointB (DDPoint): Point B, in decimal degrees coordinates.
• Returns:
  • number - Distance between the points, in the unit of distance set in the class constructor.

haversine.getInRange(referencePoint, points, distance) ⇒ DDPoint[]

Finds points that are within a specified distance range from a reference point.

import { DDPoint, Haversine } from "haversine-ts";

const madrid = new DDPoint(40.416775, -3.70379);
const cities = [
  new DDPoint(52.5200, 13.4050),     // Berlin
  new DDPoint(40.73061, -73.935242), // New York
  new DDPoint(48.8566, 2.3522),      // Paris
  new DDPoint(35.6762, 139.6503)     // Tokyo
];

const haversine = new Haversine();
// Find cities within 2000 kilometers of Madrid
const nearCities = haversine.getInRange(madrid, cities, 2000);
// Find cities within 10000 kilometers of Madrid
const farCities = haversine.getInRange(madrid, cities, 10000);

console.log("Cities within 2000km from Madrid:", nearCities);
console.log("Cities within 10000km from Madrid:", farCities);

• Parameters:
  • referencePoint (DDPoint): The reference point to calculate distances from.
  • points (DDPoint[]): The array of points to be filtered.
  • distance (number): The maximum distance from the reference point.
• Returns:
  • DDPoint[] - A new array containing only the points within the specified distance.

haversine.getPoint(startPoint, bearing, distance) ⇒ DDPoint

Calculates the coordinates of the end point of a path given its start point, start bearing and distance.

import { DDPoint, Haversine } from "haversine-ts";

const newYork = new DDPoint(40.73061, -73.935242);
const bearing = 65.71472;
const distance = 5762;

const haversine = new Haversine();
const madrid = haversine.getPoint(newYork, bearing, distance);

console.log(
  `Madrid is the endpoint of the path starting in New York with a bearing of ${bearing} degrees at a distance of ${distance} kilometers`
);

• Parameters:
  • startPoint (DDPoint): Start point, in decimal degrees coordinates.
  • bearing (number): Bearing to the end point, in degrees (0 to 360, clockwise from North).
  • distance (number): Distance from the start point to the targetted point, using as unit of measure that set in the class constructor (metres, kilometres or miles).
• Returns:.
  • DDPoint - End point, in decimal degrees coordinates.

haversine.sortByDistance(referencePoint, points, [sorting]) ⇒ DDPoint[]

Sorts an array of points by their distance to a reference point.

import { DDPoint, Haversine, Sorting } from "haversine-ts";

const madrid = new DDPoint(40.416775, -3.70379);
const cities = [
  new DDPoint(52.5200, 13.4050),     // Berlin
  new DDPoint(40.73061, -73.935242), // New York
  new DDPoint(48.8566, 2.3522),      // Paris
  new DDPoint(35.6762, 139.6503)     // Tokyo
];

const haversine = new Haversine();
const nearestCities = haversine.sortByDistance(madrid, cities);
const farthestCities = haversine.sortByDistance(madrid, cities, Sorting.Descending);

console.log("Cities sorted by distance from Madrid (nearest to farthest):", nearestCities);
console.log("Cities sorted by distance from Madrid (farthest to nearest):", farthestCities);

SphereBearing

Sphere bearing as a tuple of start and end bearings of a sphere path (orthodrome) between two points.

• Constructors:
  • new SphereBearing(start, end)
• Properties:
  • start
  • end

new SphereBearing(start, end)

Initializes a sphere bearing object instance.

import { SphereBearing } from "haversine-ts";

const bearing = new SphereBearing(60.5, 181);

console.log(
  `The start bearing of the path from A to B is ${bearing.start} degrees, and the end bearing is ${bearing.end} degrees.`
);

• Parameters
  • start (number): Start bearing, from 0 to <360 clockwise from North.
  • end (number): End bearing, from 0 to <360 clockwise from North.
• Throws:
  • Error if start or end bearings are out of range.

sphereBearing.start ⇒ number

Start bearing set in the constructor.

sphereBearing.end ⇒ number

End bearing set in the constructor.

UnitOfDistance enum

Enum	Value	Description
Metre	0	Distance in metres
Kilometre	1	Distance in kilometres
Mile	2	Distance in miles

Sorting enum

Enum	Value	Description
Ascending	0	Sort points from nearest to farthest
Descending	1	Sort points from farthest to nearest

Support

In order to notify some problem or suggest an improvement or new feature, submit an issue in the GitHub repository issues section.

License

This package is licensed under the MIT terms of use.

Contact

You can contact the package creator via email, GitHub or LinkedIn.