@soblend/windy

Professional TypeScript library for fetching meteorological data from Windy.com

A robust, well-documented library that provides a programmatic API to obtain weather data (wind, temperature, pressure, layers, forecasts, etc.) from Windy.com. Supports both official API and ethical web scraping with comprehensive rate limiting, caching, retries, and error handling.

⚠️ Important Legal Notice

Please read carefully before using this library:

• API Mode (Recommended): If you have access to Windy's official API, this library will use it as the primary method. This is the recommended and fully legal approach.
• Scraping Mode: When no API key is provided, the library can fall back to web scraping. This mode:
  • Respects robots.txt by default
  • Implements conservative rate limiting
  • Should only be used for personal, non-commercial projects
  • You are responsible for compliance with Windy's Terms of Service
• Not for Production Abuse: Do not use scraping mode to bypass API restrictions, overload Windy's servers, or violate their terms
• Check Windy's Terms: Always review Windy's Terms of Service before use

By using this library, you agree to use it ethically and responsibly.

✨ Features

• 🔑 Dual Mode: Official API support (preferred) and ethical web scraping fallback
• 🎯 TypeScript First: Full type safety and IntelliSense support
• 🚀 Production Ready: Rate limiting, retries, circuit breaker, caching
• 🌐 Flexible: Works in Node.js and browser environments
• 📦 Zero Config: Works out of the box with sensible defaults
• 🧪 Well Tested: Comprehensive unit and E2E test coverage
• 📖 Documented: Complete API documentation and examples

📦 Installation

npm install @soblend/windy

Peer Dependencies

If using scraping mode, Playwright will be installed automatically:

npx playwright install chromium

🚀 Quick Start

With Official API (Recommended)

import { WindyClient } from '@soblend/windy';

const client = new WindyClient({
  windyApiKey: 'YOUR_API_KEY', // Get from Windy
  mode: 'api'
});

// Get weather data for a point
const data = await client.getPointData(50.0, 14.5);
console.log(`Wind: ${data.wind.speed} m/s, Temp: ${data.temperature}°C`);

await client.close();

With Scraping (Use Responsibly)

import { WindyClient } from '@soblend/windy';

const client = new WindyClient({
  mode: 'scrape',
  checkRobotsTxt: true, // Respect robots.txt
  rateLimit: {
    maxRequests: 5,
    interval: 1000 // 5 requests per second
  }
});

const data = await client.getPointData(40.7128, -74.0060); // NYC
console.log(data);

await client.close();

📚 API Documentation

new WindyClient(config?)

Creates a new Windy client instance.

Configuration Options

interface WindyClientConfig {
  // API key for official Windy API
  windyApiKey?: string;
  
  // Operation mode: 'api', 'scrape', or 'auto'
  // 'auto' uses API if key provided, otherwise scraping
  mode?: 'api' | 'scrape' | 'auto';
  
  // Rate limiting
  rateLimit?: {
    maxRequests: number;  // Default: 10
    interval: number;     // In ms, default: 1000
  };
  
  // Retry configuration
  retry?: {
    maxRetries: number;        // Default: 3
    initialDelay: number;      // In ms, default: 1000
    maxDelay: number;          // In ms, default: 10000
    backoffMultiplier: number; // Default: 2
  };
  
  // Circuit breaker
  circuitBreaker?: {
    failureThreshold: number;  // Default: 5
    successThreshold: number;  // Default: 2
    timeout: number;           // In ms, default: 60000
  };
  
  // Browser pool (scraping mode)
  browserPool?: {
    maxInstances: number;       // Default: 3
    maxPagesPerInstance: number; // Default: 5
    idleTimeout: number;        // In ms, default: 60000
  };
  
  // Caching
  cache?: CacheAdapter;  // Default: LRU in-memory cache
  cacheTTL?: number;     // In seconds, default: 300
  
  // Other
  timeout?: number;           // Request timeout in ms, default: 30000
  logLevel?: 'none' | 'info' | 'debug'; // Default: 'info'
  checkRobotsTxt?: boolean;   // Check robots.txt, default: true
}

Methods

getPointData(lat, lon, options?)

Get meteorological data for a specific geographic point.

const data = await client.getPointData(50.0, 14.5);

// Returns:
interface WindyPointData {
  lat: number;
  lon: number;
  timestamp: string;
  wind: {
    speed: number;      // m/s
    direction: number;  // degrees 0-360
    gust?: number;      // m/s
  };
  temperature: number;  // °C
  pressure: number;     // hPa
  layerUrls?: Record<string, string>;
  raw?: any;
}

Options:

• timeout?: number - Override default timeout
• skipCache?: boolean - Skip cache for this request
• mode?: ClientMode - Force specific mode for this request
• signal?: AbortSignal - Abort signal for cancellation

getAreaData(bbox, options?)

Get meteorological data for a geographic area.

// BBox format: [minLon, minLat, maxLon, maxLat]
const bbox: BBox = [14.0, 49.0, 15.0, 50.0];
const data = await client.getAreaData(bbox);

// Returns:
interface WindyAreaData {
  bbox: BBox;
  timestamp: string;
  points: WindyPointData[];
  stats?: {
    avgWind: number;
    maxWind: number;
    avgTemp: number;
    avgPressure: number;
  };
  raw?: any;
}

getLayer(name, timestamp?, bbox?, options?)

Get layer data (wind, clouds, precipitation, etc.).

const layer = await client.getLayer('wind', undefined, bbox);

// Returns:
interface LayerData {
  name: string;
  timestamp: string;
  bbox?: BBox;
  url?: string;
  data?: any;
  raw?: any;
}

screenshotMap(options?)

Take a screenshot of the Windy map (scraping mode only).

const buffer = await client.screenshotMap({
  layer: 'wind',
  bbox: [14.0, 49.0, 15.0, 50.0],
  width: 1920,
  height: 1080,
  format: 'png'
});

// Save to file
import fs from 'fs';
fs.writeFileSync('map.png', buffer);

close()

Close all resources (browser instances, cache, etc.).

await client.close();

getCircuitBreakerState()

Get current circuit breaker state ('CLOSED', 'OPEN', or 'HALF_OPEN').

console.log(client.getCircuitBreakerState());

resetCircuitBreaker()

Manually reset the circuit breaker.

client.resetCircuitBreaker();

🔧 Advanced Usage

Custom Cache Adapter

Implement custom caching (e.g., Redis):

import { CacheAdapter } from '@soblend/windy';
import Redis from 'ioredis';

class RedisCache implements CacheAdapter {
  private redis: Redis;
  
  constructor() {
    this.redis = new Redis();
  }
  
  async get(key: string) {
    const value = await this.redis.get(key);
    return value ? JSON.parse(value) : null;
  }
  
  async set(key: string, value: any, ttlSeconds = 300) {
    await this.redis.setex(key, ttlSeconds, JSON.stringify(value));
  }
  
  async delete(key: string) {
    await this.redis.del(key);
  }
  
  async clear() {
    await this.redis.flushdb();
  }
}

const client = new WindyClient({
  cache: new RedisCache(),
  cacheTTL: 600 // 10 minutes
});

Error Handling

import { WindyError, WindyErrorCode } from '@soblend/windy';

try {
  const data = await client.getPointData(50, 14);
} catch (error) {
  if (error instanceof WindyError) {
    switch (error.code) {
      case WindyErrorCode.RATE_LIMIT_EXCEEDED:
        console.error('Rate limit hit, wait before retrying');
        break;
      case WindyErrorCode.ROBOTS_TXT_DISALLOWED:
        console.error('Scraping not allowed by robots.txt');
        break;
      case WindyErrorCode.CIRCUIT_BREAKER_OPEN:
        console.error('Service temporarily unavailable');
        break;
      default:
        console.error('Error:', error.message);
    }
  }
}

Request Cancellation

const controller = new AbortController();

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  const data = await client.getPointData(50, 14, {
    signal: controller.signal
  });
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Request cancelled');
  }
}

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Watch mode
npm run test:watch

🛠️ Development

# Install dependencies
npm install

# Build
npm run build

# Lint
npm run lint

# Format
npm run format

# Type check
npm run type-check

📝 Examples

See the /examples directory for complete working examples:

• Basic Usage (examples/basic.ts)
• Area Data (examples/area.ts)
• Screenshots (examples/screenshot.ts)
• Custom Cache (examples/redis-cache.ts)

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

📄 License

MIT © soblend

See LICENSE for details.

🙏 Acknowledgments

• Weather data provided by Windy.com
• Built with Playwright for browser automation
• Powered by TypeScript

⚡ Performance Tips

1. Use API mode when possible - Much faster and more reliable
2. Enable caching - Reduces redundant requests
3. Tune rate limits - Balance between speed and respect for service
4. Reuse client instances - Browser pool initialization is expensive
5. Use AbortSignal - Cancel slow requests to free resources

📞 Support

• 🐛 Issues: GitHub Issues
• 📖 Documentation: This README and inline JSDoc
• 💬 Discussions: GitHub Discussions

🗺️ Roadmap

• [ ] Support for more Windy layers
• [ ] Batch operations for multiple points
• [ ] Stream API for real-time updates
• [ ] CLI tool
• [ ] Docker container with pre-configured browser

Made with ❤️ by soblend