Node Geocoder

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

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);
  });

/**
 * 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?);

/**
 * 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);

// 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';

/**
 * 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[];
}

/**
 * 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;
}