README.md

Geographical utilities for Node.js

This library provides some basic utilities for building location-based applications.

Some features

Start by importing where:

const where = require('where');

Given two points, the Helsinki-Malmi and Helsinki-Vantaa airports:

const malmi = new where.Point(60.254558, 25.042828);
const vantaa = new where.Point(60.317222, 24.963333);

Calculating distances between points (in kilometers):

malmi.distanceTo(vantaa); // 8.2

Calculating bearing and direction from a point to another:

malmi.bearingTo(vantaa);   // 329
malmi.directionTo(vantaa); // NW

Pretty printing to human-readable coordinates:

malmi.toString(); // 60°15′16″N 25°2′34″E

Converting human-readable addresses to coordinates (geocoding, powered by OpenStreetMap Nominatim):

const geocoder = new where.Geocoder;
geocoder.toPoint({
  display_name: 'Helsinki',
  country: 'fi'
})
  .then((points) => {
    points[0].lat; // 60.1666277
    points[0].lon; // 24.9435079
  });

Converting coordinates to human-readable addresses (reverse geocoding, powered by OpenStreetMap Nominatim):

geocoder.fromPoint(malmi)
  .then((location) => {
    location.address.road; // Malminkaari
    location.address.city; // Helsinki
  });

Creating bounding boxes for a given radius (coming soon):

// 20km bounding box
const bbox = malmi.getBBox(20);
malmi.directionTo(bbox.sw); // SW

Installation

$ npm install where --save

Running tests

$ npm install --dev
$ npm test

Development

This library is provided under the MIT license. Contributions to the project are welcome on GitHub.

Initially this has been a Node.js port of my earlier PHP library.

Changes

• 0.4.2 (February 16 2023)
  • Release to update dependencies due to security issues
• 0.4.1 (August 19 2020)
  • distanceTo method now returns distances rounded to one meter accuracy instead of 100 meter accuracy
• 0.4.0 (October 01 2019)
  • Removed legacy NodeXT support
• 0.3.2 (October 01 2019)
  • Also available on GitHub Package Registry
• 0.3.1 (November 03 2018)
  • Switched from request to the fetch library for browser compat
• 0.3.0 (October 16 2017)
  • Switched asynchronous geocoding methods to return a promise instead of using a callback