@eliware/openweathermap

A simple, modern, Node.js client for the OpenWeatherMap API. Fetch current weather, 24-hour forecast, and sunrise/sunset times with a clean, promise-based API.

Table of Contents

• Features
• Installation
• Usage
• API
• TypeScript
• License

Features

• Fetch current weather for any coordinates
• Fetch 24-hour forecast (3-hour intervals)
• Fetch sunrise and sunset times (adjusted to local timezone)
• Fully typed (TypeScript definitions included)
• Supports dependency injection for fetch, clock, and API key
• Validates coordinates and units before requests
• Configurable timeouts, retries, and structured errors
• Backward-compatible null/[] failure results by default

Requirements

• Node.js 26 or newer
• An OpenWeatherMap API key

Installation

npm install @eliware/openweathermap

Usage

import { getCurrent, get24hForecast, getSun } from '@eliware/openweathermap';

const lat = 40.7128;
const lon = -74.0060;
const apiKey = 'your_api_key_here';

(async () => {
  const current = await getCurrent(lat, lon, { apiKey, units: 'F' });
  console.log('Current:', current);

  const forecast = await get24hForecast(lat, lon, { apiKey, units: 'F' });
  console.log('24h Forecast:', forecast);

  const sun = await getSun(lat, lon, { apiKey, units: 'F' });
  console.log('Sunrise/Sunset:', sun);
})();

API

Options

All methods accept apiKey, units (C, F, K, or OpenWeatherMap unit names), fetchImpl, timeout, retries, and now. Set throwOnError: true to throw an OpenWeatherMapError containing HTTP status and URL metadata; otherwise request failures retain the compatibility behavior of returning null or [].

getCurrent(lat, lon, options?)

Fetches current weather for the given latitude and longitude.

• lat (number): Latitude
• lon (number): Longitude
• options (object):
  • apiKey (string, required): Your OpenWeatherMap API key
  • units (string, optional): 'F' for Fahrenheit, 'C' for Celsius (default 'C')
  • fetchImpl (function, optional): Custom fetch implementation (for testing/mocks)
• Returns: Promise resolving to the current weather object (see OpenWeatherMap docs)

get24hForecast(lat, lon, options?)

Fetches the next 24 hours of forecast data (3-hour intervals, up to 8 items).

• Same parameters as getCurrent
• Returns: Promise resolving to an array of forecast objects

getSun(lat, lon, options?)

Fetches sunrise and sunset times for the given coordinates, returning both UTC and local times.

• Same parameters as getCurrent

• Returns: Promise resolving to:

  {
    sunriseUtc: number,    // Sunrise time (UTC, Unix timestamp)
    sunsetUtc: number,     // Sunset time (UTC, Unix timestamp)
    sunriseLocal: number,  // Sunrise time (local, Unix timestamp)
    sunsetLocal: number,   // Sunset time (local, Unix timestamp)
    offset: number       // Timezone offset in seconds (from UTC)
  }

Errors / Troubleshooting

Coordinates and units are validated before requests. By default, request failures return null or [] for compatibility. Set throwOnError: true to receive OpenWeatherMapError with status and URL metadata. Configure timeout and retries for unreliable networks.

Development

npm test
npm run test:gaps
npm run lint
npm run typecheck
npm run pack

Security

Treat OpenWeatherMap API keys as secrets. Use OWM_API_KEY or a secret manager; never commit .env files, keys, or credential-bearing URLs.

TypeScript

Type definitions are included and will be picked up automatically. Example:

import { getCurrent, get24hForecast, getSun } from '@eliware/openweathermap';

const weather = await getCurrent(40.7128, -74.0060, { apiKey: 'your_api_key_here' });
// weather: object (see OpenWeatherMap API docs)

Support

For help, questions, or to chat with the author and community, visit:

eliware.org on Discord

License

MIT © 2025 Eli Sterling, eliware.org

Links

• Home Page
• GitHub
• npm
• Discord