OpenWeather Maps SDK v0.0.0 docs
API Reference

@openweather/maps-core

Engine, layer registry, providers, timeline, search, point-query, and settings — the whole SDK's business state, with no MapLibre, React, or WebGL dependency. Isolation is checked in CI (pnpm verify:core-isolation).

createCoreMapController(options)

See Core-only / Custom Renderer for the full walkthrough. Returns a CoreMapController: engine, settings, layers, timeline, plus addWeatherLayer, removeWeatherLayer, getWeatherLayer, getLayerMetadata, listLayers, setLayerModel, setActiveLayer, destroy.

WeatherEngine

The event bus and resolve pipeline — active layer + date state, provider resolution with abortable in-flight requests, adjacent-frame prefetch, particles/waves/cyclone/lightning/contours toggle state. getSnapshot() / subscribe() (see Events & State); events.on(name, listener) for the event table.

Layers

  • LayerRegistry — active-layer set, catalog lookup (getLayerMetadata, listLayers)
  • DEFAULT_LAYER_CATALOG — the shipped, hardcoded catalog (see Layer Catalog)
  • DEFAULT_WIND_PARTICLE_CONFIG, DEFAULT_WAVES_CONFIG — default overlay configs
  • mergeCatalogWithMetadata — compose a local catalog with extra/override entries (not used by the engine itself)

Timeline

TimelineController — currentTime, play()/pause(), scrub() (snap-to-frame aware), setFrameStepMs(). Drives datetime engine events when wired (wireTimelineToEngine, on by default in createCoreMapController).

SearchController — debounced query/results/loading/error state, SearchOptions (limit, language), FlyToOptions. See GeocodingResult (id, name, localName?, country, state?, lat, lon).

Point query

PointQueryController — renderer-agnostic; takes a sample(request) => Promise<PointQueryLayerValue[]> function supplied by the adapter (@openweather/maps-maplibre's PointQuerySampler for MapLibre). See Architecture — Point query.

Providers

ProviderRegistry and the tile | raster | geojson provider implementations that each return a ResolvedLayerAsset. On a locked layer (403), providers throw LayerLockedError ({ layerCode, entitlementKey, status: 403 }); on an invalid key (401), LayerAuthError ({ layerCode, status: 401 }) — both re-exported from the main barrel.

Settings

SettingsStore (createSettingsStore) — MapSettings (apiKey, locale, theme, units), getSnapshot()/subscribe()/patch(). The single source of truth for unit preferences, shared by the legend, point-query panel, and pressure isolines.

Camera

controls/camera — FlyToOptions, camera helper functions used by both useFlyTo() (React) and Search.Item's default fly-to-result behavior.

Units

units/convert — unit conversion helpers backing the legend/point-query's unit-cycling behavior.

Internal subpath

@openweather/maps-core/internal exports implementation detail shared only with sibling SDK packages — tile/mercator math, multi-tile canvas assembly (TileImageCache, assembleTileSelection), the HEAD-probe pipeline (probeLayerAsset, LayerAuthError, LayerLockedError), scalar-config mapping, and small date/cache utilities (cacheSetLimited, isAbortError). Not part of the semver contract — only @openweather/maps-maplibre currently consumes it. See the repo's docs/API_CONVENTIONS.md for the public-vs-internal policy.