@soblend/windy
Advanced tools
Professional TypeScript library for fetching meteorological data from Windy.com with API and scraping support
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.
Please read carefully before using this library:
robots.txt by defaultBy using this library, you agree to use it ethically and responsibly.
npm install @soblend/windy
If using scraping mode, Playwright will be installed automatically:
npx playwright install chromium
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();
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();
new WindyClient(config?)Creates a new Windy client instance.
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
}
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 timeoutskipCache?: boolean - Skip cache for this requestmode?: ClientMode - Force specific mode for this requestsignal?: AbortSignal - Abort signal for cancellationgetAreaData(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();
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
});
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);
}
}
}
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');
}
}
# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Watch mode
npm run test:watch
# Install dependencies
npm install
# Build
npm run build
# Lint
npm run lint
# Format
npm run format
# Type check
npm run type-check
See the /examples directory for complete working examples:
examples/basic.ts)examples/area.ts)examples/screenshot.ts)examples/redis-cache.ts)Contributions are welcome! Please read CONTRIBUTING.md for guidelines.
MIT © soblend
See LICENSE for details.
Made with ❤️ by soblend
FAQs
Professional TypeScript library for fetching meteorological data from Windy.com with API and scraping support
We found that @soblend/windy demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.