Map Controller

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.

Supported Mapping Libraries

MapsGL current supports integration with the following third-party mapping libraries:

KeyLibrary + VersionController
mapboxMapbox GL (opens in a new tab), version 2.0.0+MapboxMapController
maplibreMapLibre (opens in a new tab), version 2.0.0+MaplibreMapController
googleGoogle Maps (opens in a new tab), version 3.50.9+GoogleMapController
leafletLeaflet (opens in a new tab), version 1.6.0+LeafletMapController

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


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: '%'


The following configuration options are supported when instantiating MapController instances.

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.
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
timehr, min, sec, msrequiredhr
ratein/hr, mm/hr, mm/sec, dBZrequiredin/hr
concentrationppm, ug/m^3requiredug/m^3


The following properties are available on MapController instances and subclasses:

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.
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.


The following methods are available on MapController instances.

Map State

Managing Data


Querying Features



The following events are triggered by MapController instances.