Geocoding Operations

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

const NodeGeocoder = require('node-geocoder');
const geocoder = NodeGeocoder('google', { apiKey: 'YOUR_API_KEY' });

// Simple address geocoding
const results = await geocoder.geocode('1600 Amphitheatre Parkway, Mountain View, CA');
console.log(results[0].latitude, results[0].longitude);

// IP address geocoding (provider dependent)
const ipResults = await geocoder.geocode('8.8.8.8');

// Structured address query
const structuredResults = await geocoder.geocode({
  address: '1600 Amphitheatre Parkway',
  country: 'US',
  zipcode: '94043'
});

// With callback style
geocoder.geocode('Paris, France', (err, results) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(results);
});

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

// Basic reverse geocoding
const results = await geocoder.reverse({ lat: 45.767, lon: 4.833 });
console.log(results[0].formattedAddress);

// With language preference
const frenchResults = await geocoder.reverse({
  lat: 45.767,
  lon: 4.833,
  language: 'fr'
});

// Provider-specific options (Google example)
const detailedResults = await geocoder.reverse({
  lat: 45.767,
  lon: 4.833,
  result_type: 'street_address',
  location_type: 'ROOFTOP'
});

// With callback style
geocoder.reverse({ lat: 45.767, lon: 4.833 }, (err, results) => {
  if (err) {
    console.error(err);
    return;
  }
  console.log(results[0].city);
});

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

// Works with all providers (aplace, here, tomtom have native batch; others use individual calls)
const geocoder = NodeGeocoder('here', { apiKey: 'YOUR_API_KEY' });

// Batch geocoding with strings
const addresses = [
  '1600 Amphitheatre Parkway, Mountain View, CA',
  'Eiffel Tower, Paris, France',
  'Times Square, New York, NY'
];

const batchResults = await geocoder.batchGeocode(addresses);

// Process results with error handling
batchResults.forEach((result, index) => {
  if (result.error) {
    console.error(`Failed to geocode ${addresses[index]}:`, result.error);
  } else {
    console.log(`${addresses[index]}:`, result.value[0]);
  }
});

// Batch geocoding with query objects
const queries = [
  { address: '1600 Amphitheatre Parkway', country: 'US' },
  { address: 'Eiffel Tower', country: 'FR' },
  { address: 'Times Square', country: 'US' }
];

const queryResults = await geocoder.batchGeocode(queries);

/**
 * Query object with confidence filtering
 */
interface ConfidenceQuery {
  /** Address to geocode */
  address: string;
  /** Minimum confidence threshold (0-1) */
  minConfidence: number;
  /** Other query parameters */
  [key: string]: any;
}

// Filter results by confidence level
const highConfidenceResults = await geocoder.geocode({
  address: 'ambiguous street name',
  minConfidence: 0.8  // Only return results with 80%+ confidence
});

// Confidence is provider-dependent
const geocoder = NodeGeocoder('google', { apiKey: 'YOUR_API_KEY' });
const results = await geocoder.geocode('123 Main Street');

// Check confidence in results
results.forEach(result => {
  if (result.extra && result.extra.confidence) {
    console.log(`Confidence: ${result.extra.confidence}`);
  }
});

/**
 * Google-specific query options
 */
interface GoogleQuery {
  address?: string;
  /** Google Place ID for direct lookup */
  googlePlaceId?: string;
  /** Language override */
  language?: string;
  /** Region biasing override */
  region?: string;
  /** Country filter */
  country?: string;
  /** ZIP code filter */
  zipcode?: string;
}

/**
 * General address query structure
 */
interface AddressQuery {
  /** Main address string */
  address: string;
  /** Country filter/preference */
  country?: string;
  /** ZIP/postal code filter */
  zipcode?: string;
  /** Language preference */
  language?: string;
  /** Minimum confidence level */
  minConfidence?: number;
}

// Google Place ID lookup
const placeResults = await geocoder.geocode({
  googlePlaceId: 'ChIJN1t_tDeuEmsRUsoyG83frY4'
});

// Country and ZIP filtering
const filteredResults = await geocoder.geocode({
  address: 'Main Street',
  country: 'US',
  zipcode: '90210'
});

// Language-specific results
const germanResults = await geocoder.geocode({
  address: 'Brandenburger Tor',
  language: 'de'
});

/**
 * Common geocoding errors
 */
interface GeocodingError extends Error {
  /** Error message */
  message: string;
  /** HTTP status code if applicable */
  code?: number;
  /** Raw response data */
  raw?: any;
}

try {
  const results = await geocoder.geocode('invalid address');
  if (results.length === 0) {
    console.log('No results found');
  }
} catch (error) {
  if (error.message.includes('OVER_QUERY_LIMIT')) {
    console.error('API quota exceeded');
  } else if (error.message.includes('REQUEST_DENIED')) {
    console.error('Invalid API key or permissions');
  } else if (error.code) {
    console.error(`HTTP Error ${error.code}: ${error.message}`);
  } else {
    console.error('Geocoding failed:', error.message);
  }
}

// Provider-specific error handling
geocoder.geocode('test address')
  .then(results => {
    // Handle zero results
    if (results.length === 0) {
      console.log('Address not found');
      return;
    }
    console.log('Found:', results[0].formattedAddress);
  })
  .catch(error => {
    console.error('Geocoding error:', error);
  });