nodejs-geolocation is a Node.js library that bundles all the most important geolocation tools and services, simplifying geolocation tasks and calculations.
- Supported Providers
- Installation
- Loading and configuration
- Usage
- License
nodejs-geolocation supports the following IP geolocation providers:
nodejs-geolocation supports the following geocoding providers:
You can install this library with npm:
npm install nodejs-geolocationnodejs-geolocation supports both CommonJS and ES Modules.
import NodeGeolocation from 'nodejs-geolocation';
const geo = new NodeGeolocation('<ApplicationName>');const NodeGeolocation = require('nodejs-geolocation').default;
const geo = new NodeGeolocation('<ApplicationName>');nodejs-geolocation supports IPInfo and IP2Location as geolocation providers.
The examples are written in TypeScript, but the same methods are available in JavaScript.
IPInfo Get your API key
import NodeGeolocation from 'nodejs-geolocation';
const geo = new NodeGeolocation('MyApp');
// Set ipGeolocationOptions
geo.ipGeolocationOptions = {
service: 'ipinfo',
key: 'mySecretApiKeyFromIPInfo'
};
// Get geolocation data from IP address
geo.getLocation('111.6.105.201')
.then((data) => {
console.log(data);
})
.catch((err) => {
console.log(err);
});IP2Location Get your API key
import NodeGeolocation from 'nodejs-geolocation';
const geo = new NodeGeolocation('MyApp');
// Set ipGeolocationOptions
geo.ipGeolocationOptions = {
service: 'ip2location',
key: 'mySecretApiKeyFromIP2Location'
};
// Get geolocation data from IP address
geo.getLocation('111.6.105.201')
.then((data) => {
console.log(data);
})
.catch((err) => {
console.log(err);
});The result data is automatically formatted in a standard format, regardless of the provider used.
{
ip: string;
city: string;
region: string;
countryCode: string;
timezone: string;
position: {
lat: number;
lon: number;
}
org: string;
asn: string;
postal: string;
raw: any; // Raw data from provider for advanced usage
}nodejs-geolocation supports OpenStreetMap Nominatim API and Here Location API as geocoding provider.
import NodeGeolocation from 'nodejs-geolocation';
const geo = new NodeGeolocation('MyApp');
// Set geocodingOptions
geo.geocodingOptions = {
service: 'Nominatim',
key: '' // Not required
};
// Get geocoding data from address
geo.getGeocoding('Rome, Italy')
.then((data) => {
console.log(data);
})
.catch((err) => {
console.log(err);
});Here Location API Get your API key
import NodeGeolocation from 'nodejs-geolocation';
const geo = new NodeGeolocation('MyApp');
// Set geocodingOptions
geo.geocodingOptions = {
service: 'Here',
key: 'mySecretApiKeyFromHere'
};
// Get geocoding data from address
geo.getGeocoding('Rome, Italy')
.then((data) => {
console.log(data);
})
.catch((err) => {
console.log(err);
});The result data is automatically formatted in a standard format, regardless of the provider used.
{
id: string;
position: {
lat: number;
lon: number;
}
address: {
city: string;
county: string;
state: string;
country: string;
countryCode: string;
}
displayName: string;
boundingBox: {
north: number;
south: number;
east: number;
west: number;
}
raw: any; // Raw data from provider for advanced usage
}nodejs-geolocation supports OpenStreetMap Nominatim API and Here Location API as reverse geocoding provider.
import NodeGeolocation from 'nodejs-geolocation';
const geo = new NodeGeolocation('MyApp');
// Set geocodingOptions
geo.geocodingOptions = {
service: 'Nominatim',
key: '' // Not required
};
const position = { lat: 41.8933203, lon: 12.4829321 };
// Get reverse geocoding data from coordinates
geo.getReverseGeocoding(position)
.then((data) => {
console.log(data);
})
.catch((err) => {
console.log(err);
});Here Location API Get your API key
import NodeGeolocation from 'nodejs-geolocation';
const geo = new NodeGeolocation('MyApp');
// Set geocodingOptions
geo.geocodingOptions = {
service: 'Here',
key: 'mySecretApiKeyFromHere'
};
const position = { lat: 41.8933203, lon: 12.4829321 };
// Get reverse geocoding data from coordinates
geo.getReverseGeocoding(position)
.then((data) => {
console.log(data);
})
.catch((err) => {
console.log(err);
});The result data of reverse geocoding is not formatted by nodejs-geolocation for more accuracy and flexibility. The result data is the raw data from the provider used.
nodejs-geolocation has a built-in geofencing system that allows you to check if a point is inside a polygon.
import { Geofencing } from 'nodejs-geolocation';
const geofencing = new Geofencing();
// Add a geofence
// addGeofence(id: string, position: Position, radius: number, metadataObject?: any)
geofencing.addGeofence('home', { lat: 40.7128, lon: -74.006 }, 1000, { description: 'Home sweet home' });
// Check if a point is inside a geofence
// isInsideGeofence(id: string, position: Position)
const isInside = geofencing.isInsideGeofence('home', { lat: 40.7128, lon: -74.006 });
console.log(isInside); // true
// Get all geofences
const geofences = geofencing.getGeofences();
// Remove a geofence
// removeGeofence(id: string)
geofencing.removeGeofence('home');
// Remove all geofences
geofencing.clearGeofences();You can even use the geofencing system with events. With the updateLocation() method, you can update the position of an object and if that enters or leaves a geofence, an event will be triggered.
import { Geofencing } from 'nodejs-geolcation';
const geofencing = new Geofencing();
// Add a geofence
geofencing.addGeofence('home', { lat: 40.7128, lon: -74.006 }, 1000, { description: 'Home sweet home' });
// Add the event listeners
geofencing.on('enter', (geofence) => {
console.log(`Entered geofence ${geofence.id}`);
});
geofencing.on('exit', (geofence) => {
console.log(`Exited geofence ${geofence.id}`);
});
// Update location method
// updateLocation(position: Position)
geofencing.updateLocation({ latitude: 40.712, longitude: -74.0065 }); // trigger 'enter' event for geofence 'home'nodejs-geolocation uses the Haversine formula to calculate the distance between two points on earth, based on their coordinates.
import NodeGeolocation from 'nodejs-geolocation';
const geo = new NodeGeolocation('MyApp');
/**
* Accepted position formats:
* { lat: number, lon: number }
* { latitude: number, longitude: number }
* { x: number, y: number }
*/
// Rome, Italy
const pos1 = { lat: 41.902782, lon: 12.496366 };
// Tokyo, Japan
const pos2 = { latitude: 35.685013, longitude: 139.7514 };
const distance = geo.calculateDistance(pos1, pos2);
console.log(distance); // 9857
/**
* Options object
* unit?: 'km' | 'yd' | 'mi' | 'm' | 'ft'
* format?: boolean
* exact?: boolean
*/
// Result:
console.log(geo.calculateDistance(pos1, pos2, { unit: 'mi' })); // 6125
console.log(geo.calculateDistance(pos1, pos2, { format: true })); // "9857 kilometers"
console.log(geo.calculateDistance(pos1, pos2, { unit: 'mi', exact: true })); // 6124.860370167203Converting timezones is usually tough, but nodejs-geolocation makes it easy with an integrated timezone converter.
import NodeGeolocation from 'nodejs-geolocation';
const geo = new NodeGeolocation('MyApp');
const from = 'PST';
const to = 'UTC+3';
const datePST = new Date('2022-01-01T00:00:00Z');
const dateUTC3 = geo.timeZoneConvert(date, from, to);
console.log(dateUTC3.toISOString()); // "2022-01-01T11:00:00.000Z"type Timezone =
| 'GMT'
| 'UTC'
| `UTC${'+' | '-'}${number}`
| `UTC${'+' | '-'}${number}:${number}`
| 'EST'
| 'CST'
| 'PST'
| 'ChinaST'
| 'IST'
| 'EET'
| 'CET'
| 'AEST`;nodejs-geolocation comes with a built-in unit conversion method.
import NodeGeolocation from 'nodejs-geolocation';
const geo = new NodeGeolocation('MyApp');
/**
* Accepted unit formats:
* km | yd | mi | m | ft
*/
// Convert 1500 meters to kilometers
const km = geo.convertUnit(1500, 'm', 'km');
console.log(km); // 1.5You can import the interfaces from the package to use them in your project.
// Import interfaces (example)
import { Position, Unit, DistanceCalculationOptions } from 'nodejs-geolocation';
const pos: Position = { lat: 41.8933203, lon: 12.4829321 };
const myUnit: Unit = 'yd';
const options: DistanceCalculationOptions = {
unit: myUnit,
format: true,
exact: true
};