Skip to Content
MapsGL1.10.1
ReferenceMap Controller

MapsGL - Map Controller

A map controller acts as an adapter to a third-party mapping library and provides a consistent interface between the functionality of MapsGL and the underlying implementation of a third-party mapping library. All MapsGL-related data, such as data sources, weather layers, custom layers, and animation timeline information, is managed by the map controller.

Read more about setting up and using a map controller with third-party mapping libraries.

Example

The following example creates a Mapbox Map instance and initializes a MapsGL MapController with the map:

// Create the map instance using third-party mapping library
mapboxgl.accessToken = 'MAPBOX_TOKEN';
const map = new mapboxgl.Map({
    container: document.getElementById('map'),
    style: 'mapbox://styles/mapbox/light-v11',
    center: [-74.5, 40],
    zoom: 3
});
map.addControl(new mapboxgl.NavigationControl(), 'bottom-left');
 
// Create an Account instance with our AerisWeather account access keys
const account = new aerisweather.mapsgl.Account('CLIENT_ID', 'CLIENT_SECRET');
 
// Create a MapController instance and provide the above `map` and `account`
// instances and desired configuration options
const controller = new aerisweather.mapsgl.MapboxMapController(map, {
    account: account,
    animation: {
        repeat: true
    },
    units: {
        temperature: 'F' | 'C',
        speed: 'mph' | 'km/h' | 'm/s' | 'kts',
        pressure: 'mb' | 'inHg' | 'hPa' | 'Pa',
        distance: 'mi' | 'km' | 'ft' | 'm',
        height: 'ft' | 'm',
        precipitation: 'in' | 'mm' | 'cm' | 'm' | 'ft',
        snowfall: 'in' | 'mm' | 'cm' | 'm' | 'ft',
        direction: '°',
        time: 'hr' | 'min' | 'sec' | 'ms',
        rate: 'in/hr' | 'mm/hr' | 'mm/sec' | 'dBZ',
        concentration: 'ppm' | 'ug/m3',
        ratio: '%'
    }
});

Configuration

The following configuration options are supported when instantiating MapController instances.

OptionDescriptionDefault
accountType: Account (required)An Account instance configured with your AerisWeather client id and secret keys for the application.
animationType: Record<string, any> (optional)An object containing configuration options for the map controller’s timeline. Review the timeline reference documentation for more information about the available options.
animation.pauseWhileLoadingType: boolean (optional)Whether to pause the timeline animation while data required for animating is loading. When true, then the entire timeline will pause animation playback while any layers are loading data required for animating.false
animation.resumeOnMoveEndType: boolean (optional)Whether to resume the timeline animation after a move end event if the animation was playing before the map move started through a pan or zoom.true
slotsType: SlotRegistryOptions (optional)Layer ordering slot configuration. Slots are named bands stacked bottom → top (underlay, inlay, text, overlay). On Mapbox / MapLibre classic styles, underlay is pinned below the bottom-most admin boundary. On Mapbox Standard styles, underlay maps to the native middle band and other slots to top.
slots.slotsType: Record<string, { beforeId?: string; mapboxSlot?: 'bottom' | 'middle' | 'top'; }> (optional)Partial overrides for built-in or custom slots, keyed by slot id. beforeId pins that slot below a host style layer (classic Mapbox / MapLibre). mapboxSlot targets a Mapbox Standard band (bottom / middle / top).
slots.typeMappingType: Record<string, string> (optional)Overrides for the default layer-type → slot mapping (for example { fill: 'inlay' }). Unmapped types fall back to inlay.
slots.stackRanksType: Record<string, number> (optional)Default within-slot stack ranks keyed by weather layer code / stack key. Higher paints above siblings. Merged over built-in defaults.{ radar: 300, satellite: 200 }
slots.resolveStackRankType: (ctx: { layerId: string; stackKey?: string; type?: string; }) => number | undefined (optional)Custom rank resolver. Return a finite number to override, or undefined to fall through to stackRanks / built-in rules.
unitsType: Record<string, string> (optional)An object containing configuration options for the units used for various measurements and displayed data values on the map. This also controls the units displayed in legends for any active layers in the legend control.

See the list of possible unit values below.

Map units

The following units are supported for the map controller’s units configuration:

TypeUnit OptionsDescriptionDefault
temperatureF, CrequiredF
speedmph, km/h, m/s, ktsrequiredmph
pressuremb, inHg, hPa, ParequiredinHg
distancemi, km, ft, mrequiredmi
heightft, mrequiredft
precipitationin, mm, cm, m, ftrequiredin
snowfallin, mm, cm, m, ftrequiredin
direction°required°
timehr, min, sec, msrequiredhr
ratein/hr, mm/hr, mm/sec, dBZrequiredin/hr
concentrationppm, ug/m^3requiredug/m^3
ratio%required%

Properties

The following properties are available on MapController instances and subclasses:

OptionDescriptionDefault
accountType: Account ()The Xweather account credentials used for weather service data.
mapType: (varies) ()The underlying map instance whose type will vary depending on the mapping library being used.
containerType: “ ()The DOM element that contains the map.
contextType: Context ()The context used for managing the map’s WebGL context.
timelineType: Timeline ()The timeline used for managing animation and time series data.
sourcesType: Array<DataSource> ()Returns an array of active data sources that have been added to the map.
sourceIdsType: Array<string> ()Returns an array of identifiers for the active data sources that have been added to the map.
layersType: Array<WebGLLayer> ()Returns an array of active layers that have been added to the map.
layerIdsType: Array<string> ()Returns an array of identifiers for the active layers that have been added to the map.
controlsType: { legend: LegendControl; dataInspector: DataInspectorControl; } ()Returns the set of controls that have been added to the map.
weatherProviderType: WeatherLayerProvider ()Weather service provider for managing weather layer configurations and data. Use getSupportedLayerIds and getLayerMetadata to list layers available in this SDK build.
weatherLayerIdsType: Array<string> ()Returns an array of weather layer identifiers that have been added to the map.
isReadyType: boolean ()Returns whether the map controller has been initialized and is ready for use. If false, then the map controller is still in the process of loading and/or initializing and you will need to add an event listener for the load event before performing actions with the map or controller.
libraryInfoType: Record<string, any> ()Returns metadata and version information about the mapping library being used.

Methods

The following methods are available on MapController instances.

Map State

Managing Data

Weather Provider

Call these on controller.weatherProvider after the map has loaded. See discovering weather layers.

Layer Ordering

Built-in slots, bottom → top: underlay, inlay, text, overlay. Higher stackRank paints above siblings in the same slot. Particle layers use inlay (not a separate slot). See layer ordering for the type → slot map, built-in ranks, host-ceiling behavior, and Mapbox Standard bands.

Slot and rank methods take a MapsGL layer id, not a weather layer code. Use the instance returned by addWeatherLayer / addLayer, or getWeatherLayer / getLayer. Composite weather codes return an array of layers — iterate when moving them.

Mapbox Standard slots

These methods exist on MapboxMapController only. They pin MapsGL ordering slots into native Mapbox Standard bands (bottom / middle / top). MapLibre, Google Maps, and Leaflet do not expose these bands — MapLibre no-ops the methods. See Mapbox Standard styles.

When a slot has no explicit mapboxSlot, the adapter defaults are underlay → middle (below labels) and every other MapsGL slot → top (above labels).

Layers

Querying Features

Other

Events

The following events are triggered by MapController instances.

Layer MasksData Sources
© 2026 Xweather (opens in a new tab)Terms of Service (opens in a new tab)Privacy Policy (opens in a new tab)