@aashari/nodejs-geocoding


Overview

A lightweight TypeScript/Node.js library for geocoding and reverse geocoding operations with multilingual support. This library provides a simple, dependency-free solution for converting between addresses and geographic coordinates.

> ⚠️ Disclaimer: This library is intended for non-commercial, low-volume applications. For production or commercial use, please use the official Google Maps API.

Features

- Zero External Dependencies: Lightweight implementation with no third-party dependencies
- TypeScript Support: Full TypeScript definitions included for type safety
- Promise-based API: Modern async/await compatible interface
- Multilingual Support: Get results in different languages (e.g., English, Indonesian, French, etc.)
- Forward Geocoding: Convert addresses to coordinates (latitude/longitude)
- Reverse Geocoding: Convert coordinates to formatted addresses
- Google Plus Codes: Get Google Plus Codes for locations
- Simple Integration: Easy to integrate with any Node.js project

Installation

``bash
npm install @aashari/nodejs-geocoding
`

Quick Start

$3

`javascript
const geocoding = require('@aashari/nodejs-geocoding');

// Convert address to coordinates
geocoding
.encode('Empire State Building, New York')
.then((locations) => console.log(locations))
.catch((error) => console.error(error));
`

$3

`javascript
const geocoding = require('@aashari/nodejs-geocoding');

// Convert coordinates to address
geocoding
.decode(40.7484, -73.9857)
.then((location) => console.log(location))
.catch((error) => console.error(error));
`

API Reference

$3

Converts an address string to geographic coordinates.

`typescript
function encode(
formattedAddress: string,
language?: string = 'en',
): Promise;
`

Returns: Array of location objects with coordinates and formatted address.

$3

Converts geographic coordinates to an address.

`typescript
function decode(
latitude: number,
longitude: number,
language?: string = 'en',
): Promise;
`

Returns: Location object with formatted address and Google Plus Code, or null if not found.

$3

`typescript
interface Location {
latitude?: number;
longitude?: number;
google_plus_code?: string;
formatted_address?: string;
}
`

Language Support

Specify a language code as the last parameter to get results in different languages:

`javascript
// Get results in French
geocoding
.encode('Tour Eiffel, Paris', 'fr')
.then((locations) => console.log(locations));

// Get results in Japanese
geocoding
.decode(35.6895, 139.6917, 'ja')
.then((location) => console.log(location));
`

Supports all language codes that Google Maps supports (e.g., en, fr, de, ja, zh-CN, es, etc.)

Example Output

$3

`javascript
[
{
formatted_address:
'Empire State Building, 20 W 34th St, New York, NY 10001, United States',
latitude: 40.7484405,
longitude: -73.9856644,
},
];
`

$3

`javascript
{
latitude: 40.7484,
longitude: -73.9857,
formatted_address: 'Empire State Building, 20 W 34th St, New York, NY 10001, United States',
google_plus_code: '87G8Q2M4+96'
}
`

Using with TypeScript

`typescript
import { encode, decode, Location } from '@aashari/nodejs-geocoding';

async function getLocationData(): Promise {
try {
// Forward geocoding
const locations: Location[] = await encode('Tokyo Tower, Japan');

// Reverse geocoding
if (locations.length > 0) {
const { latitude, longitude } = locations[0];
const address: Location | null = await decode(latitude, longitude);
console.log(address);
}
} catch (error) {
console.error('Error:', error);
}
}
`

Advanced Usage Examples

$3

`javascript
async function getLocationInfo() {
try {
// Geocoding
const coordinates = await geocoding.encode('Colosseum, Rome');
console.log('Coordinates:', coordinates);

// Reverse Geocoding using the first result
if (coordinates && coordinates.length > 0) {
const { latitude, longitude } = coordinates[0];
const address = await geocoding.decode(latitude, longitude);
console.log('Address:', address);
}
} catch (error) {
console.error('Error:', error);
}
}
`

$3

`javascript
async function safeGeocode(address) {
try {
const results = await geocoding.encode(address);
if (!results || results.length === 0) {
console.log(No results found for address: ${address});
return null;
}
return results;
} catch (error) {
console.error(Error geocoding address "${address}":, error);
return null;
}
}
``

License

This project is licensed under the MIT License.

---

Made with ❤️ by aashari