tessl/npm-node-geocoder

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Factory and Configuration

Name: tessl/npm-node-geocoder
Author: tessl

Factory functionality for creating and configuring geocoder instances with different providers and options.

Capabilities

Main Factory Function

Creates a geocoder instance with the specified provider and configuration options.

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

Usage Examples:

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

// Default Google provider
const geocoder = NodeGeocoder();

// Specify provider by name
const geocoder = NodeGeocoder('google');

// Provider with options
const geocoder = NodeGeocoder('google', {
  apiKey: 'YOUR_API_KEY',
  language: 'en',
  region: 'us'
});

// Options object only (provider in options)
const geocoder = NodeGeocoder({
  provider: 'google',
  apiKey: 'YOUR_API_KEY',
  language: 'en'
});

HTTP Adapter Configuration

Configure the HTTP client used for API requests.

/**
 * HTTP adapter options for customizing request behavior
 */
interface HttpAdapterOptions {
  /** Custom fetch implementation */
  fetch?: Function;
  /** Request timeout in milliseconds */
  timeout?: number;
  /** Custom headers to include in requests */
  headers?: { [key: string]: string };
  /** Proxy configuration */
  proxy?: string;
  /** Additional options passed to fetch */
  [key: string]: any;
}

Usage Examples:

// Custom headers and timeout
const geocoder = NodeGeocoder('google', {
  apiKey: 'YOUR_API_KEY',
  timeout: 10000,
  headers: {
    'User-Agent': 'MyApp/1.0'
  }
});

// Proxy configuration
const geocoder = NodeGeocoder('google', {
  apiKey: 'YOUR_API_KEY',
  proxy: 'http://proxy.example.com:8080'
});

Formatter Configuration

Configure output formatters to transform geocoding results.

/**
 * Formatter configuration options
 */
interface FormatterOptions {
  /** Formatter type: 'gpx' or 'string' */
  formatter: 'gpx' | 'string';
  /** Pattern for string formatter (required if formatter is 'string') */
  formatterPattern?: string;
}

Usage Examples:

// GPX formatter
const geocoder = NodeGeocoder('google', {
  apiKey: 'YOUR_API_KEY',
  formatter: 'gpx'
});

// String formatter with custom pattern
const geocoder = NodeGeocoder('google', {
  apiKey: 'YOUR_API_KEY',
  formatter: 'string',
  formatterPattern: '%S %n, %c, %P %z'  // Street, Number, City, Country, ZIP
});

Provider-Specific Options

Each provider supports specific configuration options for API keys, language settings, and service-specific parameters.

/**
 * Common provider options supported by most providers
 */
interface CommonProviderOptions {
  /** API key for the geocoding service */
  apiKey?: string;
  /** Language code for localized results */
  language?: string;
  /** Country/region preference */
  country?: string;
  /** Maximum number of results to return */
  limit?: number;
}

/**
 * Google-specific options
 */
interface GoogleOptions extends CommonProviderOptions {
  /** Google client ID for business accounts */
  clientId?: string;
  /** Region biasing */
  region?: string;
  /** Exclude partial matches */
  excludePartialMatches?: boolean;
  /** Channel for premium accounts */
  channel?: string;
}

/**
 * HERE-specific options
 */
interface HereOptions extends CommonProviderOptions {
  /** HERE app ID (legacy) */
  appId?: string;
  /** HERE app code (legacy) */
  appCode?: string;
  /** Political view setting */
  politicalView?: string;
  /** State preference */
  state?: string;
  /** Production environment flag */
  production?: boolean;
}

Error Handling

The factory validates configuration and throws errors for invalid setups.

/**
 * Configuration validation errors
 */
class ValueError extends Error {
  constructor(message: string);
  name: 'ValueError';
}

/**
 * HTTP-related errors
 */
class HttpError extends Error {
  constructor(message: string, options?: { code?: number });
  name: 'HttpError';
  code?: number;
}

Common Configuration Errors:

// Missing API key for Google business client
try {
  const geocoder = NodeGeocoder('google', { clientId: 'client123' });
} catch (error) {
  // Throws: "You must specify a apiKey (privateKey)"
}

// HTTPS required for API key
try {
  const geocoder = NodeGeocoder('google', {
    apiKey: 'key123',
    // Using HTTP adapter would cause error
  });
} catch (error) {
  // Throws: "You must use https http adapter"
}

// Invalid provider name
try {
  const geocoder = NodeGeocoder('invalidprovider');
} catch (error) {
  // Throws: "No geocoder provider find for : invalidprovider"
}