meteo-lt-sdk

TypeScript SDK for the Meteo.lt API - Lithuanian Hydrometeorological Service (LHMT).

Features

• 🎯 Full Type Safety - Strict TypeScript types with branded types for coordinates
• ✅ Runtime Validation - Zod schemas validate all API responses
• 🌳 Tree-shakeable - Modular design for optimal bundle size
• 📚 Comprehensive TSDoc - IntelliSense-friendly documentation
• 🔒 Error Handling - Custom error classes for different failure modes

Installation

npm install meteo-lt-sdk

Quick Start

import { MeteoClient } from "meteo-lt-sdk";

const client = new MeteoClient();

// Get weather forecast for Vilnius
const forecast = await client.places.getForecast("vilnius", "long-term");
console.log(`Temperature: ${forecast.forecastTimestamps[0]?.airTemperature}°C`);

// Get latest observations from a weather station
const observations = await client.stations.getObservations(
  "vilniaus-ams",
  "latest"
);

// Get water level data
const hydroData = await client.hydroStations.getMeasuredObservations(
  "nemajunu-vms",
  "latest"
);

API Reference

MeteoClient

Main entry point for the SDK.

const client = new MeteoClient({
  timeout: 10000, // Optional: request timeout in ms (default: 30000)
  throttle: true, // Optional: enable rate limiting (default: false)
  headers: { "X-Custom-Header": "value" }, // Optional: custom headers
});

Rate Limiting

The API limits requests to 180 per minute per IP. Enable automatic rate limiting to prevent hitting this limit:

const client = new MeteoClient({ throttle: true });

// Multiple client instances share the same global rate limiter
const client1 = new MeteoClient({ throttle: true });
const client2 = new MeteoClient({ throttle: true });
// Both clients share the same 180 req/min budget

How it works:

• Uses a 60-second sliding window - each request "reserves" a slot for 60 seconds
• Time-based, not completion-based - slots are used when requests start, not when they finish
• Queuing, not dropping - excess requests wait in a queue until slots are available

Example: If you fire 200 requests at once at t=0:

• 180 start immediately (parallel execution)
• 20 queue and wait for slots to expire
• At t=60s, all 180 slots expire → 20 queued requests proceed

Places API

Access weather forecasts for Lithuanian cities and towns.

// List all available places
const places = await client.places.getAll();

// Get place details
const place = await client.places.get("vilnius");

// Get available forecast types
const forecastTypes = await client.places.getForecastTypes("vilnius");

// Get weather forecast
const forecast = await client.places.getForecast("vilnius", "long-term");

Forecast Data

Each forecast timestamp includes:

• airTemperature - Air temperature (°C)
• feelsLikeTemperature - Feels-like temperature (°C)
• windSpeed - Wind speed (m/s)
• windGust - Wind gust (m/s)
• windDirection - Wind direction (0° = north, 180° = south)
• cloudCover - Cloud cover (0-100%)
• seaLevelPressure - Pressure at sea level (hPa)
• relativeHumidity - Relative humidity (%)
• totalPrecipitation - Precipitation amount (mm)
• conditionCode - Weather condition code

Stations API

Access meteorological observation data from weather stations.

// List all stations
const stations = await client.stations.getAll();

// Get station details
const station = await client.stations.get("vilniaus-ams");

// Get data availability info
const info = await client.stations.getObservationsInfo("vilniaus-ams");

// Get observations for a specific date
const observations = await client.stations.getObservations(
  "vilniaus-ams",
  "2024-01-15"
);

// Get latest 24-hour observations
const latest = await client.stations.getObservations("vilniaus-ams", "latest");

Hydro Stations API

Access hydrological observation data from water monitoring stations.

// List all hydro stations
const stations = await client.hydroStations.getAll();

// Get station details
const station = await client.hydroStations.get("nemajunu-vms");

// Get current year (measured) observations
const measured = await client.hydroStations.getMeasuredObservations(
  "nemajunu-vms",
  "latest"
);

// Get historical observations
const historical = await client.hydroStations.getHistoricalObservations(
  "nemajunu-vms",
  "2024-06"
);

Error Handling

The SDK provides specific error classes for different failure scenarios:

import {
  MeteoNotFoundError,
  MeteoRateLimitError,
  MeteoNetworkError,
  MeteoTimeoutError,
  MeteoValidationError,
} from "meteo-lt-sdk";

try {
  const forecast = await client.places.getForecast(
    "invalid-place",
    "long-term"
  );
} catch (error) {
  if (error instanceof MeteoNotFoundError) {
    console.log("Place not found:", error.resource);
  } else if (error instanceof MeteoRateLimitError) {
    console.log("Rate limited, retry after:", error.retryAfterSeconds);
  } else if (error instanceof MeteoNetworkError) {
    console.log("Network error:", error.message);
  } else if (error instanceof MeteoTimeoutError) {
    console.log("Request timed out after:", error.timeoutMs, "ms");
  } else if (error instanceof MeteoValidationError) {
    console.log("Invalid response:", error.validationErrors);
  }
}

Weather Condition Codes

The SDK exports condition code utilities:

import {
  FORECAST_CONDITION_CODES,
  OBSERVATION_CONDITION_CODES,
  getConditionDescription,
  isForecastConditionCode,
} from "meteo-lt-sdk";

// Get human-readable description
const description = getConditionDescription("partly-cloudy"); // 'Partly cloudy'

// Type guard
if (isForecastConditionCode(value)) {
  // value is ForecastConditionCode
}

Types

All types are exported for use in your application:

import type {
  PlaceSummary,
  PlaceDetails,
  Forecast,
  ForecastTimestamp,
  StationSummary,
  Observation,
  HydroStationSummary,
  MeasuredHydroObservation,
  Coordinates,
} from "meteo-lt-sdk";

Advanced Usage

Custom Fetch Implementation

const client = new MeteoClient({
  fetch: customFetch, // Custom fetch function
});

Direct Schema Access

For advanced validation needs, schemas are exported:

import { schemas } from "meteo-lt-sdk";

const result = schemas.forecastSchema.safeParse(data);

Subpath Imports

For tree-shaking, you can import from subpaths:

import { MeteoClient } from "meteo-lt-sdk/client";
import type { Forecast } from "meteo-lt-sdk/types";

Rate Limits

The API has the following limits:

• 180 requests per minute per IP address
• 20,000 requests per day recommended maximum per IP

Exceeding these limits may result in temporary IP blocking. Enable throttle: true to stay within the per-minute limit. The daily limit is not enforced by the SDK.

License

MIT

Credits

Data provided by the Lithuanian Hydrometeorological Service (LHMT) under CC BY-SA 4.0.

Support

If you found this SDK useful for your project, consider buying me a coffee! It helps me keep the reverse-engineering efforts going.