OpenWeather Maps SDK v0.0.0 docs

Getting Started

Prerequisites

  • Node.js 20+
  • pnpm 9 (this repo pins its version in the root package.json)
  • An OpenWeather Maps API key

Install

Install the packages from npm:

pnpm add @openweather/maps-maplibre maplibre-gl@^5
# optional, for the React renderer
pnpm add @openweather/maps-react react react-dom

@openweather/maps-maplibre depends on @openweather/maps-core and @openweather/maps-gl internally via regular npm dependencies — you don't install those yourself. @openweather/maps-react peer-depends on react/react-dom ≥ 18 and, only if you import its ./maplibre subpath, on @openweather/maps-maplibre + maplibre-gl 5.x (6.x removed the default export this SDK relies on).

Vanilla — createWeatherMap

The fastest path to a working map:

import { createWeatherMap } from '@openweather/maps-maplibre';
import 'maplibre-gl/dist/maplibre-gl.css';

const map = await createWeatherMap({
  apiKey: 'YOUR_KEY',
  container: '#map',
  center: [10, 50],
  zoom: 3,
  defaultLayer: 'temperature',
});

await map.setLayer('windSpeed');
await map.toggleParticlesOverlay(true);
await map.setDate(new Date());

map.on('layer:locked', ({ code, entitlementKey }) => {
  console.warn('Locked layer', code, entitlementKey);
});

// map.destroy() when you're done with it.

map is a WeatherMapHandle — see the Vanilla (MapLibre) guide for its full method/event surface, and @openweather/maps-maplibre for constructor options.

Want the simple UI kit's demo chrome (layer panel, legend, timeline, search, point-query box, zoom) around that map instead of building your own? See createSimpleMapUI.

React — <WeatherMap> / <SimpleMapUI>

import {
  WeatherMap,
  useMapController,
  useLayers,
} from '@openweather/maps-react/maplibre';
import 'maplibre-gl/dist/maplibre-gl.css';

function App() {
  return (
    <WeatherMap apiKey="YOUR_KEY" center={[10, 50]} zoom={3} defaultLayer="temperature">
      {({ handle, error }) =>
        error ? <p>{error.message}</p> : handle ? <MapChrome /> : <p>Loading…</p>
      }
    </WeatherMap>
  );
}

function MapChrome() {
  const controller = useMapController();
  const { active } = useLayers();
  return <p>Active layer: {active}</p>;
}

Or skip straight to the simple UI kit with <SimpleMapUI> — see the React guide and Providers & Hooks. Want OpenWeather's own fuller look instead (fan-out rail, day-axis timeline, expanding search)? Use <WeatherMapUI>/createWeatherMapUI from the same ./maplibre subpath, paired with @openweather/maps-theme for the styling.

Core-only (headless / custom renderer)

No MapLibre, no DOM — just the engine and its stores, for a fully custom renderer:

import { createCoreMapController } from '@openweather/maps-core';

const controller = createCoreMapController({
  apiKey: 'YOUR_KEY',
  defaultLayer: 'temperature',
});

await controller.engine.initialize();
await controller.setActiveLayer('pressure');
await controller.engine.setDate(new Date());

const asset = controller.engine.getSnapshot().resolvedAsset;
// hand `asset` to your own renderer

See Core-only / Custom Renderer for the full pattern.

Run the example apps

Standalone, runnable examples live in the public owm-maps-sdk-examples repository. They install the SDK from npm (@openweather/maps-* 0.1.0), so no SDK source checkout is needed:

git clone https://github.com/openweathermap/owm-maps-sdk-examples.git
cd owm-maps-sdk-examples/vanilla   # or ../react
npm install
cp .env.example .env.local         # set VITE_OWM_API_KEY
npm run dev

Alternatively append ?appid=YOUR_KEY to the dev server's URL. See Examples for what each app demonstrates and how they compare.

Next steps