OpenWeather Maps SDK v0.0.0 docs

Examples

Two example apps live in the public owm-maps-sdk-examples repository (also mirrored under examples/ in the SDK repo), both thin consumers of the same libraries — the DOM one is @openweather/maps-ui over @openweather/maps-core + @openweather/maps-ui-core, the React one is @openweather/maps-react over the same core + view-models — sharing one stylesheet keyed by the data-owm-part contract. Everything either one renders is fully covered by the Simple UI Kit pages; each example is the simple kit (createSimpleMapUI() / <SimpleMapUI>) plus a compact "API tour" that logs the rest of the controller surface (engine events, timeline, search, point query, particle/waves/raster config) to the console, so the examples stay a complete tour of the SDK, not just of the simple kit.

vanilla

git clone https://github.com/openweathermap/owm-maps-sdk-examples.git
cd owm-maps-sdk-examples/vanilla
npm install
npm run dev

Opens on a local Vite URL (http://localhost:5173 by default). Set VITE_OWM_API_KEY in .env.local (copy .env.example) or append ?appid=YOUR_KEY to the URL. The entire app is createWeatherMap() → createSimpleMapUI(), plus main.ts's logApiSurface() — see the Vanilla guide.

react

cd owm-maps-sdk-examples/react
npm install
npm run dev

Same ?appid= override. The entire app is one <SimpleMapUI> with ApiTour.tsx mounted as its children — see the React guide.

Both depend on @openweather/maps-*@^0.1.0 from npm. To run the in-repo copies against local SDK source instead, see Development.

Parity

Both apps are checked, row by row, against one behavior checklist (examples/PARITY.md in the repo) — the layer panel's flat grouped list, per-layer timeline windows, play/pause, legend unit cycling, all four overlay toggles, point query on map click, search + geolocate, pin reuse, zoom, and locked-layer (403) status. Where a row has measurable geometry (getBoundingClientRect() on every data-owm-part element), it's diffed numerically rather than eyeballed.

The structural half of that guarantee — that both renderers stamp the identical set of data-owm-part values for equivalent state — is enforced continuously in CI by packages/maps-react/src/ui/parity.test.tsx, which mounts each DOM factory and its React counterpart side by side and asserts the attribute sets match. A drift between renderers fails CI immediately, rather than waiting to be caught by eye later.

OpenWeather's own fuller designed UI — a fan-out layer rail, a day-axis timeline, per-overlay config panels, and an expanding search pill — is a second tier in this SDK (./designed on both renderers), with its own structural parity test (packages/maps-react/src/designed/parity.test.tsx), but neither example app demonstrates it — both stay scoped to the simple kit, so none of that is covered by examples/PARITY.md above. The One Call detail panel that appears alongside the designed UI on OpenWeather's own site is a separate addon (@openweather/maps-addon-onecall-detail), not part of this SDK.

Building your own example

Both apps follow the same shape and are a reasonable starting point to fork:

  1. Resolve an API key (query string override, .env, or hardcode for a private prototype).
  2. createWeatherMap() / <WeatherMap> for the map.
  3. createSimpleMapUI() / <SimpleMapUI> for the simple kit's chrome, or build your own UI on the hooks/compounds/view-models — see Getting Started for both paths.
  4. Wire layer:locked / error (see Events & State) to your own upgrade-prompt / error-banner UI if you don't want the simple kit's status-text defaults.