or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

factory.mdformatters.mdgeocoding.mdindex.mdproviders.md
tile.json

tessl/npm-node-geocoder

Node.js geocoding library supporting multiple providers for converting addresses to coordinates and vice versa

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/node-geocoder@4.4.x

To install, run

npx @tessl/cli install tessl/npm-node-geocoder@4.4.0

index.mddocs/

Node Geocoder

Node Geocoder is a comprehensive geocoding library for Node.js that supports over 20 different geocoding providers. It enables developers to convert addresses to coordinates (geocoding) and coordinates to addresses (reverse geocoding) using a unified API interface.

Package Information

  • Package Name: node-geocoder
  • Package Type: npm
  • Language: JavaScript (CommonJS)
  • Installation: npm install node-geocoder

Core Imports

const NodeGeocoder = require('node-geocoder');

Basic Usage

const NodeGeocoder = require('node-geocoder');

// Create geocoder instance with default Google provider
const geocoder = NodeGeocoder();

// Geocode an address
geocoder.geocode('29 champs elysée paris')
  .then((res) => {
    console.log(res);
  })
  .catch((err) => {
    console.log(err);
  });

// Reverse geocode coordinates
geocoder.reverse({ lat: 45.767, lon: 4.833 })
  .then((res) => {
    console.log(res);
  })
  .catch((err) => {
    console.log(err);
  });

Architecture

Node Geocoder follows a factory pattern with these key components:

  • GeocoderFactory: Main factory that creates geocoder instances and manages providers
  • Geocoder: Unified wrapper that provides consistent API across all providers
  • Provider Classes: Individual geocoding service implementations (Google, HERE, etc.)
  • HTTP Adapter: Handles HTTP requests using node-fetch
  • Formatters: Transform results into different output formats (GPX, string templates)
  • Error Classes: Standardized error types for HTTP and validation errors

Capabilities

Factory Function

Main entry point for creating geocoder instances with provider and configuration options.

/**
 * Creates a geocoder instance with specified provider and options
 * @param {string|object} provider - Provider name or options object (if object, treated as options with provider inside)
 * @param {object} options - Configuration options for the provider (optional if provider is object)
 * @returns {Geocoder} Configured geocoder instance
 */
function NodeGeocoder(provider?, options?);

Factory and Configuration

Geocoding Operations

Core functionality for converting addresses to coordinates and vice versa.

/**
 * Geocode an address or IP to coordinates
 * @param {string|object} value - Address string or query object
 * @param {function} callback - Optional callback function
 * @returns {Promise<GeocodeResult[]>} Array of geocoding results
 */
geocode(value, callback);

/**
 * Reverse geocode coordinates to address
 * @param {object} query - Coordinates object with lat/lon properties
 * @param {function} callback - Optional callback function  
 * @returns {Promise<GeocodeResult[]>} Array of reverse geocoding results
 */
reverse(query, callback);

/**
 * Batch geocode multiple addresses (native batch support: aplace, here, tomtom; others use individual calls)
 * @param {string[]|object[]} values - Array of addresses or query objects
 * @param {function} callback - Optional callback function
 * @returns {Promise<BatchResult[]>} Array of batch geocoding results
 */
batchGeocode(values, callback);

Geocoding Operations

Geocoding Providers

Support for 23 geocoding service providers with provider-specific configuration options.

// Supported provider names
type ProviderName = 
  | 'google' | 'here' | 'agol' | 'freegeoip' | 'datasciencetoolkit'
  | 'openstreetmap' | 'pickpoint' | 'locationiq' | 'mapquest' | 'mapzen'
  | 'openmapquest' | 'yandex' | 'geocodio' | 'opencage' | 'nominatimmapquest'
  | 'tomtom' | 'virtualearth' | 'smartystreets' | 'teleport' | 'opendatafrance'
  | 'mapbox' | 'aplace';

Geocoding Providers

Result Formatting

Transform geocoding results into different output formats including GPX and custom string templates.

/**
 * GPX formatter for converting results to GPX XML format
 */
interface GpxFormatter {
  format(data: GeocodeResult[]): string;
}

/**
 * String formatter using pattern templates
 */
interface StringFormatter {
  constructor(pattern: string);
  format(data: GeocodeResult[]): string[];
}

Result Formatting

Types

/**
 * Standard geocoding result format returned by all providers
 */
interface GeocodeResult {
  /** Full formatted address */
  formattedAddress: string;
  /** Latitude coordinate */
  latitude: number;
  /** Longitude coordinate */
  longitude: number;
  /** Country name */
  country?: string;
  /** ISO country code */
  countryCode?: string;
  /** City name */
  city?: string;
  /** Postal/ZIP code */
  zipcode?: string;
  /** Street name */
  streetName?: string;
  /** Street number */
  streetNumber?: string;
  /** Administrative divisions */
  administrativeLevels?: {
    level1long?: string;
    level1short?: string;
    level2long?: string;
    level2short?: string;
    level3long?: string;
    level3short?: string;
    level4long?: string;
    level4short?: string;
    level5long?: string;
    level5short?: string;
  };
  /** Provider-specific additional data */
  extra?: {
    /** Confidence score (0-1) */
    confidence?: number;
    /** Provider-specific fields */
    [key: string]: any;
  };
  /** Provider name that generated this result */
  provider: string;
}

/**
 * Batch geocoding result with error handling
 */
interface BatchResult {
  /** Error if geocoding failed */
  error?: Error;
  /** Geocoding result if successful */
  value?: GeocodeResult[];
}

/**
 * Coordinate query object for reverse geocoding
 */
interface ReverseQuery {
  /** Latitude */
  lat: number;
  /** Longitude */
  lon: number;
  /** Optional language preference */
  language?: string;
  /** Provider-specific options */
  [key: string]: any;
}

/**
 * Address query object for enhanced geocoding
 */
interface AddressQuery {
  /** Address string */
  address: string;
  /** Country filter */
  country?: string;
  /** ZIP/postal code filter */
  zipcode?: string;
  /** Minimum confidence threshold */
  minConfidence?: number;
  /** Language preference */
  language?: string;
  /** Provider-specific options */
  [key: string]: any;
}