Skip to content
/ where Public

Geographical utilities for location-based Node.js applications

Notifications You must be signed in to change notification settings

bergie/where

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Geographical utilities for Node.js Build Status Coverage Status

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)
  • 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