Geocoding Providers

/**
 * Supported provider names for use with NodeGeocoder factory
 */
type ProviderName = 
  | 'google'              // Google Maps Geocoding API (default)
  | 'here'                // HERE Geocoding API
  | 'agol'                // ArcGIS Online Geocoding Service
  | 'freegeoip'           // FreeGeoIP service
  | 'datasciencetoolkit'  // Data Science Toolkit
  | 'openstreetmap'       // OpenStreetMap Nominatim
  | 'pickpoint'           // PickPoint API
  | 'locationiq'          // LocationIQ API
  | 'mapquest'            // MapQuest API
  | 'mapzen'              // Mapzen Search API
  | 'openmapquest'        // Open MapQuest API
  | 'yandex'              // Yandex Maps API
  | 'geocodio'            // Geocodio API
  | 'opencage'            // OpenCage Data API
  | 'nominatimmapquest'   // Nominatim MapQuest
  | 'tomtom'              // TomTom API
  | 'virtualearth'        // Microsoft Bing Maps
  | 'smartystreets'       // SmartyStreets API
  | 'teleport'            // Teleport API
  | 'opendatafrance'      // OpenData France
  | 'mapbox'              // Mapbox Geocoding API
  | 'aplace'              // A-Place API

/**
 * Google Maps provider configuration
 */
interface GoogleOptions {
  /** Google API key */
  apiKey?: string;
  /** Google client ID for business accounts */
  clientId?: string;
  /** Language code for results (e.g., 'en', 'fr', 'de') */
  language?: string;
  /** Region biasing (e.g., 'us', 'uk', 'fr') */
  region?: string;
  /** Exclude partial matches from results */
  excludePartialMatches?: boolean;
  /** Channel for premium plan tracking */
  channel?: string;
}

// Basic Google configuration
const geocoder = NodeGeocoder('google', {
  apiKey: 'YOUR_GOOGLE_API_KEY'
});

// Advanced Google configuration
const geocoder = NodeGeocoder('google', {
  apiKey: 'YOUR_API_KEY',
  language: 'fr',
  region: 'fr',
  excludePartialMatches: true
});

// Business account with client ID
const geocoder = NodeGeocoder('google', {
  clientId: 'your-client-id',
  apiKey: 'your-private-key',
  channel: 'your-channel'
});

/**
 * HERE provider configuration
 */
interface HereOptions {
  /** HERE API key (current authentication method) */
  apiKey?: string;
  /** HERE app ID (legacy authentication) */
  appId?: string;
  /** HERE app code (legacy authentication) */
  appCode?: string;
  /** Language preference */
  language?: string;
  /** Political view setting */
  politicalView?: string;
  /** Country preference */
  country?: string;
  /** State preference */
  state?: string;
  /** Use production environment */
  production?: boolean;
  /** Maximum number of results */
  limit?: number;
}

// HERE with API key (recommended)
const geocoder = NodeGeocoder('here', {
  apiKey: 'YOUR_HERE_API_KEY',
  language: 'en-US'
});

// HERE with legacy app credentials
const geocoder = NodeGeocoder('here', {
  appId: 'YOUR_APP_ID',
  appCode: 'YOUR_APP_CODE',
  production: true
});

/**
 * OpenStreetMap provider configuration
 */
interface OpenStreetMapOptions {
  /** Language preference */
  language?: string;
  /** Custom Nominatim server URL */
  osmServer?: string;
}

// Basic OpenStreetMap (no API key needed)
const geocoder = NodeGeocoder('openstreetmap');

// Custom language and server
const geocoder = NodeGeocoder('openstreetmap', {
  language: 'en',
  osmServer: 'https://your-nominatim-server.com'
});

/**
 * Mapbox provider configuration
 */
interface MapboxOptions {
  /** Mapbox access token */
  apiKey: string;
  /** Additional mapbox-specific options */
  [key: string]: any;
}

const geocoder = NodeGeocoder('mapbox', {
  apiKey: 'YOUR_MAPBOX_ACCESS_TOKEN'
});

/**
 * TomTom provider configuration
 */
interface TomTomOptions {
  /** TomTom API key */
  apiKey: string;
  /** Country preference */
  country?: string;
  /** Maximum number of results */
  limit?: number;
}

const geocoder = NodeGeocoder('tomtom', {
  apiKey: 'YOUR_TOMTOM_API_KEY',
  country: 'US',
  limit: 5
});

/**
 * Yandex provider configuration
 */
interface YandexOptions {
  /** Yandex API key */
  apiKey?: string;
  /** Language preference */
  language?: string;
  /** Maximum number of results */
  results?: number;
  /** Number of results to skip */
  skip?: number;
  /** Kind of toponym to search */
  kind?: string;
  /** Bounding box for search area */
  bbox?: string;
  /** Restrict search to bbox */
  rspn?: boolean;
}

const geocoder = NodeGeocoder('yandex', {
  apiKey: 'YOUR_YANDEX_API_KEY',
  language: 'ru_RU',
  results: 10
});

/**
 * Free provider configurations
 */
interface FreeProviders {
  /** OpenStreetMap Nominatim - completely free */
  openstreetmap: {};
  /** FreeGeoIP - IP geocoding only */
  freegeoip: {};
  /** OpenData France - French addresses */
  opendatafrance: {};
  /** Data Science Toolkit - custom host option */
  datasciencetoolkit: { host?: string };
}

// Free providers requiring no configuration
const osmGeocoder = NodeGeocoder('openstreetmap');
const ipGeocoder = NodeGeocoder('freegeoip');
const franceGeocoder = NodeGeocoder('opendatafrance');

// Data Science Toolkit with custom host
const dstkGeocoder = NodeGeocoder('datasciencetoolkit', {
  host: 'localhost:8080'
});

/**
 * API key required provider configurations
 */
interface ApiKeyProviders {
  google: GoogleOptions;
  here: HereOptions;
  mapquest: { apiKey: string };
  geocodio: { apiKey: string };
  opencage: { apiKey: string; [key: string]: any };
  locationiq: { apiKey: string };
  pickpoint: { apiKey: string; language?: string };
  virtualearth: { apiKey: string };
  tomtom: TomTomOptions;
  mapbox: MapboxOptions;
  yandex: YandexOptions;
  smartystreets: { auth_id: string; auth_token: string };
  teleport: { apiKey?: string; [key: string]: any };
  nominatimmapquest: { apiKey: string; language?: string };
  agol: { client_id: string; client_secret: string };
  aplace: { [key: string]: any };
}

/**
 * Provider capability information
 */
interface ProviderCapabilities {
  /** Supports forward geocoding (address to coordinates) */
  geocoding: boolean;
  /** Supports reverse geocoding (coordinates to address) */
  reverseGeocoding: boolean;
  /** Supports batch operations */
  batchGeocoding: boolean;
  /** Supports IPv4 address geocoding */
  ipv4Support: boolean;
  /** Supports IPv6 address geocoding */
  ipv6Support: boolean;
  /** Provides confidence scores */
  confidenceScores: boolean;
  /** Geographic coverage areas */
  coverage: string[];
}

// Global coverage providers
const globalProviders = ['google', 'here', 'mapbox', 'opencage'];

// Regional specialists
const usProviders = ['smartystreets', 'geocodio'];  // US-focused
const franceProvider = ['opendatafrance'];           // France-focused

// IP geocoding specialists
const ipProviders = ['freegeoip'];

// Choose provider based on needs
const geocoder = globalProviders.includes(preferredProvider) 
  ? NodeGeocoder(preferredProvider, { apiKey: 'key' })
  : NodeGeocoder('openstreetmap');  // fallback to free option