@atombrenner/openmeteo

OpenMeteo

This is a typesafe client for the Open-Meteo Weather Forecast API. The Open-Meteo API gives you unified access to high-precision weather forecast data from many national weather services. The client is designed to utilize TypeScript for maximum type safety and flatbuffers for best performance.

Usage

npm install @atombrenner/openmeteo

Import the fetchWeatherData function. It needs a runtime that implements a basic Fetch API.

import { fetchWeatherData } from '@atombrenner/openmeteo'

Fetch forecast data. The function accepts an object of type WeatherDataParams that mimics the parameters of the Open-Meteo API as closely as possible. File an issue if you find something missing. Fetching data for multiple locations in one request is not supported.

const data = await fetchWeatherData({
  latitude: 49.0699764,
  longitude: 11.614277,
  timezone: 'Europe/Berlin',
  forecast_days: 5,
  hourly: ['temperature_2m', 'rain'],
  daily: ['temperature_2m_max', 'sunrise', 'sunset'],
  current: ['apparent_temperature'],
})

All hourly, daily and current parameters documented by DWD ICON are currently supported. The weather variables arrays for hourly, daily and current data are typed with string literals, so autocompletion just works.

Access the returned data. Note that daily and hourly are time series and return an array of values. All values are of type number. Duration and timestamps are returned as seconds.

console.log(data.hourly.temperature_2m[0]) // temperature in the first hour
console.log(data.current.apparent_temperature)

The returned data is typed depending on the parameters, which means that only requested variables are part of the return type. If you have requested hourly: ['rain'] and try to access data.hourly.temperature_2m, TypeScript will raise a 'Property does not exist' error. Without the WeatherData type depending on WeatherDataParams all properties would need to be present and the user would need to do null checks all the time.

If you need to construct the parameter object dynamically, you need the as const or the weatherDataParams utility function to prevent type widening to string. See examples.

The returned data is modeled very closely to the JSON response of the Open-Meteo API. There are a few caveats to be aware of:

• durations and timestamps are returned in seconds (type number)
• timestamps are always in UTC
• data contains utc_offset_seconds property for easy conversion to local time:

  const localTime = (ts: number) => new Date((ts + data.utc_offset_seconds) * 1000)
  

Notes

• The flatbuffers optimization idea was borrowed from the openmeteo package. Flatbuffers indeed reduce the size of the transferred data but the absolute saving is rather small unless you request a lot of variables for many intervals. Anyway, it was fun to learn flatbuffers, and using a performant code just feels good 😁.
• Uses Bun for development and running tests.
• If you want retries on network errors use something like retry.

Publish

Useful commands

• npm version <major|minor|patch>
• git push --tags starts the workflow for publishing an new package
• npm pack creates a package, useful for local testing
• npm publish --dry-run check package before publishing
• npm publish --access public