@dangahagan/weather-mcp 0.2.0 → 1.0.0

package/dist/services/openmeteo.js

@@ -1,28 +1,81 @@
 /**
- * Service for interacting with the Open-Meteo Historical Weather API
- * Documentation: https://open-meteo.com/en/docs/historical-weather-api
+ * Service for interacting with the Open-Meteo APIs
+ * Documentation:
+ * - Historical Weather: https://open-meteo.com/en/docs/historical-weather-api
+ * - Forecast: https://open-meteo.com/en/docs
+ * - Geocoding: https://open-meteo.com/en/docs/geocoding-api
+ * - Air Quality: https://open-meteo.com/en/docs/air-quality-api
+ * - Marine: https://open-meteo.com/en/docs/marine-weather-api
  */
 import axios from 'axios';
 import { Cache } from '../utils/cache.js';
 import { CacheConfig, getHistoricalDataTTL } from '../config/cache.js';
+import { validateLatitude, validateLongitude } from '../utils/validation.js';
+import { logger } from '../utils/logger.js';
+import { RateLimitError, ServiceUnavailableError, InvalidLocationError, DataNotFoundError, ApiError } from '../errors/ApiError.js';
 export class OpenMeteoService {
     client;
+    geocodingClient;
+    forecastClient;
+    airQualityClient;
+    marineClient;
     maxRetries;
     cache;
     constructor(config = {}) {
-        const { baseURL = 'https://archive-api.open-meteo.com/v1', timeout = 30000, maxRetries = 3 } = config;
+        const { baseURL = 'https://archive-api.open-meteo.com/v1', geocodingURL = 'https://geocoding-api.open-meteo.com/v1', forecastURL = 'https://api.open-meteo.com/v1', airQualityURL = 'https://air-quality-api.open-meteo.com/v1', marineURL = 'https://marine-api.open-meteo.com/v1', timeout = CacheConfig.apiTimeoutMs, maxRetries = 3 } = config;
         this.maxRetries = maxRetries;
         this.cache = new Cache(CacheConfig.maxSize);
+        // Historical weather client
         this.client = axios.create({
             baseURL,
             timeout,
             headers: {
                 'Accept': 'application/json',
-                'User-Agent': 'weather-mcp/0.1.0'
+                'User-Agent': 'weather-mcp/0.6.0'
+            }
+        });
+        // Geocoding client
+        this.geocodingClient = axios.create({
+            baseURL: geocodingURL,
+            timeout,
+            headers: {
+                'Accept': 'application/json',
+                'User-Agent': 'weather-mcp/0.6.0'
+            }
+        });
+        // Forecast client
+        this.forecastClient = axios.create({
+            baseURL: forecastURL,
+            timeout,
+            headers: {
+                'Accept': 'application/json',
+                'User-Agent': 'weather-mcp/0.6.0'
+            }
+        });
+        // Air quality client
+        this.airQualityClient = axios.create({
+            baseURL: airQualityURL,
+            timeout,
+            headers: {
+                'Accept': 'application/json',
+                'User-Agent': 'weather-mcp/0.6.0'
+            }
+        });
+        // Marine client
+        this.marineClient = axios.create({
+            baseURL: marineURL,
+            timeout,
+            headers: {
+                'Accept': 'application/json',
+                'User-Agent': 'weather-mcp/0.6.0'
             }
         });
         // Add response interceptor for error handling
         this.client.interceptors.response.use(response => response, error => this.handleError(error));
+        this.geocodingClient.interceptors.response.use(response => response, error => this.handleError(error));
+        this.forecastClient.interceptors.response.use(response => response, error => this.handleError(error));
+        this.airQualityClient.interceptors.response.use(response => response, error => this.handleError(error));
+        this.marineClient.interceptors.response.use(response => response, error => this.handleError(error));
     }
     /**
      * Handle API errors with helpful status information
@@ -34,58 +87,46 @@ export class OpenMeteoService {
             // Bad request
             if (status === 400) {
                 const reason = data.reason || 'Invalid request parameters';
-                throw new Error(`Open-Meteo API error: ${reason}\n\n` +
-                    `Please verify:\n` +
+                logger.warn('Invalid request parameters', {
+                    service: 'OpenMeteo',
+                    reason,
+                    securityEvent: true
+                });
+                throw new InvalidLocationError('OpenMeteo', `${reason}\n\nPlease verify:\n` +
                     `- Coordinates are valid (latitude: -90 to 90, longitude: -180 to 180)\n` +
                     `- Date range is valid (1940 to 5 days ago)\n` +
-                    `- Parameters are correctly formatted\n\n` +
-                    `API documentation: https://open-meteo.com/en/docs/historical-weather-api`);
+                    `- Parameters are correctly formatted`);
             }
             // Rate limit error
             if (status === 429) {
-                throw new Error(`Open-Meteo API rate limit exceeded (10,000 requests/day for non-commercial use).\n\n` +
-                    `Please retry later or consider:\n` +
-                    `- Reducing request frequency\n` +
-                    `- Using daily instead of hourly data for longer periods\n` +
-                    `- Upgrading to a commercial plan for higher limits\n\n` +
-                    `More info: https://open-meteo.com/en/pricing`);
+                logger.warn('Rate limit exceeded', {
+                    service: 'OpenMeteo',
+                    securityEvent: true
+                });
+                throw new RateLimitError('OpenMeteo');
             }
             // Server errors
             if (status >= 500) {
-                throw new Error(`Open-Meteo API server error: Service temporarily unavailable\n\n` +
-                    `The Open-Meteo API may be experiencing an outage.\n\n` +
-                    `Check service status:\n` +
-                    `- Production status: https://open-meteo.com/en/docs/model-updates\n` +
-                    `- GitHub issues: https://github.com/open-meteo/open-meteo/issues`);
+                throw new ServiceUnavailableError('OpenMeteo', error);
             }
             // Other errors
-            throw new Error(`Open-Meteo API error (${status}): ${data.reason || 'Request failed'}\n\n` +
-                `For assistance, visit:\n` +
-                `- API documentation: https://open-meteo.com/en/docs\n` +
-                `- GitHub issues: https://github.com/open-meteo/open-meteo/issues`);
+            throw new ApiError(`Open-Meteo API error (${status})`, status, 'OpenMeteo', data.reason || 'Request failed', [
+                'https://open-meteo.com/en/docs',
+                'https://github.com/open-meteo/open-meteo/issues'
+            ]);
         }
         // Network errors
         if (error.code === 'ECONNABORTED') {
-            throw new Error(`Request to Open-Meteo API timed out. Please try again.\n\n` +
-                `If timeouts persist, check:\n` +
-                `- Your internet connection\n` +
-                `- Service status: https://open-meteo.com/en/docs/model-updates`);
+            throw new ServiceUnavailableError('OpenMeteo', error);
         }
         if (error.code === 'ENOTFOUND' || error.code === 'ECONNREFUSED') {
-            throw new Error(`Unable to connect to Open-Meteo API.\n\n` +
-                `Possible causes:\n` +
-                `- Internet connection issues\n` +
-                `- Open-Meteo API service outage\n` +
-                `- DNS resolution problems\n\n` +
-                `Check:\n` +
-                `- Your internet connection\n` +
-                `- Service status: https://open-meteo.com/en/docs/model-updates`);
+            throw new ServiceUnavailableError('OpenMeteo', error);
         }
         // Generic error
-        throw new Error(`Open-Meteo API request failed: ${error.message}\n\n` +
-            `For assistance, visit:\n` +
-            `- GitHub issues: https://github.com/open-meteo/open-meteo/issues\n` +
-            `- Documentation: https://open-meteo.com/en/docs`);
+        throw new ApiError(`Open-Meteo API request failed: ${error.message}`, 500, 'OpenMeteo', `Request failed: ${error.message}`, [
+            'https://github.com/open-meteo/open-meteo/issues',
+            'https://open-meteo.com/en/docs'
+        ], true);
     }
     /**
      * Make request with retry logic
@@ -102,7 +143,9 @@ export class OpenMeteoService {
                     error.message.includes('server error') ||
                     error.message.includes('timed out');
                 if (shouldRetry) {
-                    const delay = Math.pow(2, retries) * 1000; // Exponential backoff
+                    // Exponential backoff with jitter to prevent thundering herd
+                    const baseDelay = Math.pow(2, retries) * 1000;
+                    const delay = baseDelay * (0.5 + Math.random() * 0.5);
                     await new Promise(resolve => setTimeout(resolve, delay));
                     return this.makeRequest(url, params, retries + 1);
                 }
@@ -203,13 +246,11 @@ export class OpenMeteoService {
      * @returns Historical weather data
      */
     async getHistoricalWeather(latitude, longitude, startDate, endDate, useHourly = true) {
-        // Validate coordinates
-        if (latitude < -90 || latitude > 90) {
-            throw new Error(`Invalid latitude: ${latitude}. Must be between -90 and 90.`);
-        }
-        if (longitude < -180 || longitude > 180) {
-            throw new Error(`Invalid longitude: ${longitude}. Must be between -180 and 180.`);
-        }
+        // Validate coordinates (checks for NaN, Infinity, and range)
+        validateLatitude(latitude);
+        validateLongitude(longitude);
+        // Build parameters once
+        const params = this.buildHistoricalParams(latitude, longitude, startDate, endDate, useHourly);
         // Check cache first (if enabled)
         if (CacheConfig.enabled) {
             const cacheKey = Cache.generateKey('openmeteo-historical', latitude, longitude, startDate, endDate, useHourly);
@@ -217,74 +258,23 @@ export class OpenMeteoService {
             if (cached) {
                 return cached;
             }
-            // Build request parameters
-            const params = {
-                latitude,
-                longitude,
-                start_date: startDate,
-                end_date: endDate,
-                temperature_unit: 'fahrenheit',
-                wind_speed_unit: 'mph',
-                precipitation_unit: 'inch',
-                timezone: 'auto'
-            };
-            // Request appropriate data granularity
-            if (useHourly) {
-                // Hourly data for detailed observations
-                params.hourly = [
-                    'temperature_2m',
-                    'relative_humidity_2m',
-                    'dewpoint_2m',
-                    'apparent_temperature',
-                    'precipitation',
-                    'rain',
-                    'snowfall',
-                    'weather_code',
-                    'pressure_msl',
-                    'cloud_cover',
-                    'wind_speed_10m',
-                    'wind_direction_10m',
-                    'wind_gusts_10m'
-                ].join(',');
-            }
-            else {
-                // Daily summaries for longer time periods
-                params.daily = [
-                    'temperature_2m_max',
-                    'temperature_2m_min',
-                    'temperature_2m_mean',
-                    'apparent_temperature_max',
-                    'apparent_temperature_min',
-                    'precipitation_sum',
-                    'rain_sum',
-                    'snowfall_sum',
-                    'precipitation_hours',
-                    'weather_code',
-                    'wind_speed_10m_max',
-                    'wind_gusts_10m_max',
-                    'wind_direction_10m_dominant'
-                ].join(',');
-            }
             const response = await this.makeRequest('/archive', params);
-            // Validate response has data
-            if (useHourly && (!response.hourly || !response.hourly.time || response.hourly.time.length === 0)) {
-                throw new Error(`No historical weather data available for the specified date range (${startDate} to ${endDate}).\n\n` +
-                    'This may occur because:\n' +
-                    '- The dates are too recent (data has a 5-day delay for most models)\n' +
-                    '- The dates are before 1940 (earliest available data)\n\n' +
-                    'Please try adjusting your date range.');
-            }
-            if (!useHourly && (!response.daily || !response.daily.time || response.daily.time.length === 0)) {
-                throw new Error(`No historical weather data available for the specified date range (${startDate} to ${endDate}).\n\n` +
-                    'Please try adjusting your date range.');
-            }
+            this.validateResponse(response, startDate, endDate, useHourly);
             // Use smart TTL based on date range
             const ttl = getHistoricalDataTTL(startDate);
             this.cache.set(cacheKey, response, ttl);
             return response;
         }
-        // No caching - original logic
-        // Build request parameters
+        // No caching
+        const response = await this.makeRequest('/archive', params);
+        this.validateResponse(response, startDate, endDate, useHourly);
+        return response;
+    }
+    /**
+     * Build request parameters for historical weather data
+     * @private
+     */
+    buildHistoricalParams(latitude, longitude, startDate, endDate, useHourly) {
         const params = {
             latitude,
             longitude,
@@ -332,8 +322,13 @@ export class OpenMeteoService {
                 'wind_direction_10m_dominant'
             ].join(',');
         }
-        const response = await this.makeRequest('/archive', params);
-        // Validate response has data
+        return params;
+    }
+    /**
+     * Validate that the response contains the expected data
+     * @private
+     */
+    validateResponse(response, startDate, endDate, useHourly) {
         if (useHourly && (!response.hourly || !response.hourly.time || response.hourly.time.length === 0)) {
             throw new Error(`No historical weather data available for the specified date range (${startDate} to ${endDate}).\n\n` +
                 'This may occur because:\n' +
@@ -345,7 +340,6 @@ export class OpenMeteoService {
             throw new Error(`No historical weather data available for the specified date range (${startDate} to ${endDate}).\n\n` +
                 'Please try adjusting your date range.');
         }
-        return response;
     }
     /**
      * Get weather description from WMO weather code
@@ -384,5 +378,467 @@ export class OpenMeteoService {
         };
         return weatherCodes[code] || `Unknown (code: ${code})`;
     }
+    /**
+     * Search for locations by name using the Open-Meteo Geocoding API
+     *
+     * @param query - Location name to search for (e.g., "Paris", "New York, NY", "Tokyo")
+     * @param limit - Maximum number of results to return (default: 5, max: 100)
+     * @param language - Language for results (default: 'en')
+     * @returns Geocoding results with coordinates and metadata
+     */
+    async searchLocation(query, limit = 5, language = 'en') {
+        if (!query || query.trim().length === 0) {
+            throw new InvalidLocationError('OpenMeteo', 'Search query cannot be empty');
+        }
+        if (query.trim().length === 1) {
+            throw new InvalidLocationError('OpenMeteo', 'Search query must be at least 2 characters long');
+        }
+        // Validate limit
+        if (limit < 1 || limit > 100) {
+            throw new InvalidLocationError('OpenMeteo', 'Limit must be between 1 and 100');
+        }
+        // Check cache first (locations don't move, so cache indefinitely)
+        if (CacheConfig.enabled) {
+            const cacheKey = Cache.generateKey('openmeteo-geocoding', query, limit, language);
+            const cached = this.cache.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+            const params = {
+                name: query.trim(),
+                count: limit,
+                language,
+                format: 'json'
+            };
+            const response = await this.geocodingClient.get('/search', { params });
+            // Cache indefinitely (locations don't change)
+            // Using 30 days as TTL to keep cache from growing unbounded
+            this.cache.set(cacheKey, response.data, 30 * 24 * 60 * 60 * 1000);
+            return response.data;
+        }
+        // No caching
+        const params = {
+            name: query.trim(),
+            count: limit,
+            language,
+            format: 'json'
+        };
+        const response = await this.geocodingClient.get('/search', { params });
+        return response.data;
+    }
+    /**
+     * Get weather forecast from Open-Meteo Forecast API
+     *
+     * @param latitude - Latitude coordinate (-90 to 90)
+     * @param longitude - Longitude coordinate (-180 to 180)
+     * @param days - Number of forecast days (1-16, default: 7)
+     * @param hourly - Whether to include hourly data (default: false)
+     * @returns Weather forecast data
+     */
+    async getForecast(latitude, longitude, days = 7, hourly = false) {
+        // Validate coordinates
+        validateLatitude(latitude);
+        validateLongitude(longitude);
+        // Validate days
+        if (days < 1 || days > 16) {
+            throw new InvalidLocationError('OpenMeteo', 'Forecast days must be between 1 and 16');
+        }
+        // Build parameters
+        const params = this.buildForecastParams(latitude, longitude, days, hourly);
+        // Check cache first
+        if (CacheConfig.enabled) {
+            const cacheKey = Cache.generateKey('openmeteo-forecast', latitude, longitude, days, hourly);
+            const cached = this.cache.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+            const response = await this.makeRequestToForecast('/forecast', params);
+            this.validateForecastResponse(response, hourly);
+            // Cache for 2 hours (forecasts update regularly)
+            this.cache.set(cacheKey, response, 2 * 60 * 60 * 1000);
+            return response;
+        }
+        // No caching
+        const response = await this.makeRequestToForecast('/forecast', params);
+        this.validateForecastResponse(response, hourly);
+        return response;
+    }
+    /**
+     * Build request parameters for forecast data
+     * @private
+     */
+    buildForecastParams(latitude, longitude, days, hourly) {
+        const params = {
+            latitude,
+            longitude,
+            forecast_days: days,
+            temperature_unit: 'fahrenheit',
+            wind_speed_unit: 'mph',
+            precipitation_unit: 'inch',
+            timezone: 'auto'
+        };
+        // Always include daily data with sunrise/sunset
+        params.daily = [
+            'weather_code',
+            'temperature_2m_max',
+            'temperature_2m_min',
+            'apparent_temperature_max',
+            'apparent_temperature_min',
+            'sunrise',
+            'sunset',
+            'daylight_duration',
+            'sunshine_duration',
+            'uv_index_max',
+            'precipitation_sum',
+            'rain_sum',
+            'showers_sum',
+            'snowfall_sum',
+            'precipitation_hours',
+            'precipitation_probability_max',
+            'wind_speed_10m_max',
+            'wind_gusts_10m_max',
+            'wind_direction_10m_dominant'
+        ].join(',');
+        // Optionally include hourly data
+        if (hourly) {
+            params.hourly = [
+                'temperature_2m',
+                'relative_humidity_2m',
+                'dewpoint_2m',
+                'apparent_temperature',
+                'precipitation_probability',
+                'precipitation',
+                'rain',
+                'showers',
+                'snowfall',
+                'snow_depth',
+                'weather_code',
+                'pressure_msl',
+                'cloud_cover',
+                'visibility',
+                'wind_speed_10m',
+                'wind_direction_10m',
+                'wind_gusts_10m',
+                'uv_index',
+                'is_day'
+            ].join(',');
+        }
+        return params;
+    }
+    /**
+     * Make request to forecast API with retry logic
+     * @private
+     */
+    async makeRequestToForecast(url, params, retries = 0) {
+        try {
+            const response = await this.forecastClient.get(url, { params });
+            return response.data;
+        }
+        catch (error) {
+            // Retry on rate limit or server errors
+            if (retries < this.maxRetries) {
+                const shouldRetry = error.message.includes('rate limit') ||
+                    error.message.includes('server error') ||
+                    error.message.includes('timed out');
+                if (shouldRetry) {
+                    const baseDelay = Math.pow(2, retries) * 1000;
+                    const delay = baseDelay * (0.5 + Math.random() * 0.5);
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                    return this.makeRequestToForecast(url, params, retries + 1);
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * Validate that the forecast response contains the expected data
+     * @private
+     */
+    validateForecastResponse(response, hourly) {
+        if (hourly && (!response.hourly || !response.hourly.time || response.hourly.time.length === 0)) {
+            throw new DataNotFoundError('OpenMeteo', 'No hourly forecast data available for the specified location');
+        }
+        if (!response.daily || !response.daily.time || response.daily.time.length === 0) {
+            throw new DataNotFoundError('OpenMeteo', 'No daily forecast data available for the specified location');
+        }
+    }
+    /**
+     * Get air quality data from Open-Meteo Air Quality API
+     *
+     * @param latitude - Latitude coordinate (-90 to 90)
+     * @param longitude - Longitude coordinate (-180 to 180)
+     * @param forecast - Whether to include hourly forecast (default: false, returns current only)
+     * @param forecastDays - Number of forecast days (1-7, default: 5)
+     * @returns Air quality data including AQI, pollutants, and UV index
+     */
+    async getAirQuality(latitude, longitude, forecast = false, forecastDays = 5) {
+        // Validate coordinates
+        validateLatitude(latitude);
+        validateLongitude(longitude);
+        // Validate forecast days
+        if (forecastDays < 1 || forecastDays > 7) {
+            throw new InvalidLocationError('OpenMeteo', 'Air quality forecast days must be between 1 and 7');
+        }
+        // Build parameters
+        const params = this.buildAirQualityParams(latitude, longitude, forecast, forecastDays);
+        // Check cache first
+        if (CacheConfig.enabled) {
+            const cacheKey = Cache.generateKey('openmeteo-airquality', latitude, longitude, forecast, forecastDays);
+            const cached = this.cache.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+            const response = await this.makeRequestToAirQuality('/air-quality', params);
+            this.validateAirQualityResponse(response, forecast);
+            // Cache for 1 hour (air quality updates hourly)
+            this.cache.set(cacheKey, response, 60 * 60 * 1000);
+            return response;
+        }
+        // No caching
+        const response = await this.makeRequestToAirQuality('/air-quality', params);
+        this.validateAirQualityResponse(response, forecast);
+        return response;
+    }
+    /**
+     * Build request parameters for air quality data
+     * @private
+     */
+    buildAirQualityParams(latitude, longitude, forecast, forecastDays) {
+        const params = {
+            latitude,
+            longitude,
+            timezone: 'auto'
+        };
+        // Always include current data
+        params.current = [
+            'pm10',
+            'pm2_5',
+            'carbon_monoxide',
+            'nitrogen_dioxide',
+            'sulphur_dioxide',
+            'ozone',
+            'aerosol_optical_depth',
+            'dust',
+            'uv_index',
+            'uv_index_clear_sky',
+            'ammonia',
+            'european_aqi',
+            'european_aqi_pm2_5',
+            'european_aqi_pm10',
+            'european_aqi_nitrogen_dioxide',
+            'european_aqi_ozone',
+            'european_aqi_sulphur_dioxide',
+            'us_aqi',
+            'us_aqi_pm2_5',
+            'us_aqi_pm10',
+            'us_aqi_nitrogen_dioxide',
+            'us_aqi_ozone',
+            'us_aqi_sulphur_dioxide',
+            'us_aqi_carbon_monoxide'
+        ].join(',');
+        // Optionally include hourly forecast data
+        if (forecast) {
+            params.forecast_days = forecastDays;
+            params.hourly = [
+                'pm10',
+                'pm2_5',
+                'carbon_monoxide',
+                'nitrogen_dioxide',
+                'sulphur_dioxide',
+                'ozone',
+                'aerosol_optical_depth',
+                'dust',
+                'uv_index',
+                'uv_index_clear_sky',
+                'ammonia',
+                'european_aqi',
+                'european_aqi_pm2_5',
+                'european_aqi_pm10',
+                'european_aqi_nitrogen_dioxide',
+                'european_aqi_ozone',
+                'european_aqi_sulphur_dioxide',
+                'us_aqi',
+                'us_aqi_pm2_5',
+                'us_aqi_pm10',
+                'us_aqi_nitrogen_dioxide',
+                'us_aqi_ozone',
+                'us_aqi_sulphur_dioxide',
+                'us_aqi_carbon_monoxide'
+            ].join(',');
+        }
+        return params;
+    }
+    /**
+     * Make request to air quality API with retry logic
+     * @private
+     */
+    async makeRequestToAirQuality(url, params, retries = 0) {
+        try {
+            const response = await this.airQualityClient.get(url, { params });
+            return response.data;
+        }
+        catch (error) {
+            // Retry on rate limit or server errors
+            if (retries < this.maxRetries) {
+                const shouldRetry = error.message.includes('rate limit') ||
+                    error.message.includes('server error') ||
+                    error.message.includes('timed out');
+                if (shouldRetry) {
+                    const baseDelay = Math.pow(2, retries) * 1000;
+                    const delay = baseDelay * (0.5 + Math.random() * 0.5);
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                    return this.makeRequestToAirQuality(url, params, retries + 1);
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * Validate that the air quality response contains the expected data
+     * @private
+     */
+    validateAirQualityResponse(response, forecast) {
+        if (!response.current || !response.current.time) {
+            throw new DataNotFoundError('OpenMeteo', 'No current air quality data available for the specified location');
+        }
+        if (forecast && (!response.hourly || !response.hourly.time || response.hourly.time.length === 0)) {
+            throw new DataNotFoundError('OpenMeteo', 'No hourly air quality forecast data available for the specified location');
+        }
+    }
+    /**
+     * Get marine conditions data from Open-Meteo Marine API
+     *
+     * @param latitude - Latitude coordinate (-90 to 90)
+     * @param longitude - Longitude coordinate (-180 to 180)
+     * @param forecast - Whether to include hourly forecast (default: false, returns current only)
+     * @param forecastDays - Number of forecast days (1-7, default: 5)
+     * @returns Marine conditions including waves, swell, and currents
+     */
+    async getMarine(latitude, longitude, forecast = false, forecastDays = 5) {
+        // Validate coordinates
+        validateLatitude(latitude);
+        validateLongitude(longitude);
+        // Validate forecast days
+        if (forecastDays < 1 || forecastDays > 7) {
+            throw new InvalidLocationError('OpenMeteo', 'Marine forecast days must be between 1 and 7');
+        }
+        // Build parameters
+        const params = this.buildMarineParams(latitude, longitude, forecast, forecastDays);
+        // Check cache first
+        if (CacheConfig.enabled) {
+            const cacheKey = Cache.generateKey('openmeteo-marine', latitude, longitude, forecast, forecastDays);
+            const cached = this.cache.get(cacheKey);
+            if (cached) {
+                return cached;
+            }
+            const response = await this.makeRequestToMarine('/marine', params);
+            this.validateMarineResponse(response, forecast);
+            // Cache for 1 hour (marine conditions update hourly)
+            this.cache.set(cacheKey, response, 60 * 60 * 1000);
+            return response;
+        }
+        // No caching
+        const response = await this.makeRequestToMarine('/marine', params);
+        this.validateMarineResponse(response, forecast);
+        return response;
+    }
+    /**
+     * Build request parameters for marine data
+     * @private
+     */
+    buildMarineParams(latitude, longitude, forecast, forecastDays) {
+        const params = {
+            latitude,
+            longitude,
+            timezone: 'auto'
+        };
+        // Always include current data
+        params.current = [
+            'wave_height',
+            'wave_direction',
+            'wave_period',
+            'wind_wave_height',
+            'wind_wave_direction',
+            'wind_wave_period',
+            'wind_wave_peak_period',
+            'swell_wave_height',
+            'swell_wave_direction',
+            'swell_wave_period',
+            'swell_wave_peak_period',
+            'ocean_current_velocity',
+            'ocean_current_direction'
+        ].join(',');
+        // Optionally include hourly forecast data
+        if (forecast) {
+            params.forecast_days = forecastDays;
+            params.hourly = [
+                'wave_height',
+                'wave_direction',
+                'wave_period',
+                'wind_wave_height',
+                'wind_wave_direction',
+                'wind_wave_period',
+                'wind_wave_peak_period',
+                'swell_wave_height',
+                'swell_wave_direction',
+                'swell_wave_period',
+                'swell_wave_peak_period',
+                'ocean_current_velocity',
+                'ocean_current_direction'
+            ].join(',');
+            // Also include daily aggregates
+            params.daily = [
+                'wave_height_max',
+                'wave_direction_dominant',
+                'wave_period_max',
+                'wind_wave_height_max',
+                'wind_wave_direction_dominant',
+                'wind_wave_period_max',
+                'wind_wave_peak_period_max',
+                'swell_wave_height_max',
+                'swell_wave_direction_dominant',
+                'swell_wave_period_max',
+                'swell_wave_peak_period_max'
+            ].join(',');
+        }
+        return params;
+    }
+    /**
+     * Make request to marine API with retry logic
+     * @private
+     */
+    async makeRequestToMarine(url, params, retries = 0) {
+        try {
+            const response = await this.marineClient.get(url, { params });
+            return response.data;
+        }
+        catch (error) {
+            // Retry on rate limit or server errors
+            if (retries < this.maxRetries) {
+                const shouldRetry = error.message.includes('rate limit') ||
+                    error.message.includes('server error') ||
+                    error.message.includes('timed out');
+                if (shouldRetry) {
+                    const baseDelay = Math.pow(2, retries) * 1000;
+                    const delay = baseDelay * (0.5 + Math.random() * 0.5);
+                    await new Promise(resolve => setTimeout(resolve, delay));
+                    return this.makeRequestToMarine(url, params, retries + 1);
+                }
+            }
+            throw error;
+        }
+    }
+    /**
+     * Validate that the marine response contains the expected data
+     * @private
+     */
+    validateMarineResponse(response, forecast) {
+        if (!response.current || !response.current.time) {
+            throw new DataNotFoundError('OpenMeteo', 'No current marine conditions data available for the specified location');
+        }
+        if (forecast && (!response.hourly || !response.hourly.time || response.hourly.time.length === 0)) {
+            throw new DataNotFoundError('OpenMeteo', 'No hourly marine forecast data available for the specified location');
+        }
+    }
 }
 //# sourceMappingURL=openmeteo.js.map