MapsGL - Forecast Model Layers

Starting with MapsGL 1.10.0, built-in weather layers are available for individual forecast models. Each model layer is a clone of a corresponding conditions or radar layer — same paint, legend, and data inspector behavior — backed by that model’s own encoded tile source instead of the blended observation/forecast feed.

Use model layers when you want a specific model’s output on the map, such as GFS temperatures, ECMWF wind particles, or NBM CONUS radar. See the forecast model temperatures example to toggle models over the United States.

Layer codes

Model layer codes follow {model}-{variable}:

controller.addWeatherLayer('gfs-temperatures');
controller.addWeatherLayer('ecmwf-hres-wind-particles');
controller.addWeatherLayer('nbm-conus-radar');

{model} is the model code from the supported models table. {variable} is the same identifier used by the base weather layer, such as temperatures, wind-particles, or radar.

Not every model publishes every variable. A code that is not available in the current SDK build is ignored. See discovering available layers to list what this build actually includes.

Adding a model layer

Add model layers the same way as any other weather layer, after the map controller has loaded. Because these sources are forecast data, set the timeline into the future so there are valid times to display:

controller.on('load', () => {
    controller.timeline.setStartDateUsingRelativeTime('now');
    controller.timeline.setEndDateUsingRelativeTime('+2 days');
 
    controller.addWeatherLayer('gfs-temperatures');
});

You can still override paint, legends, quality, and other options with the second argument:

controller.addWeatherLayer('gfs-temperatures', {
    paint: {
        sample: {
            opacity: 0.75
        }
    }
});

Remove or hide them with the same methods used for other weather layers: removeWeatherLayer('gfs-temperatures') or setWeatherLayerVisibility('gfs-temperatures', false).

Supported models

Supported variables

Each model layer clones one of the following base weather layers when that model provides the required datasets:

Prefix any of those base ids with a model code to get the model-specific layer, for example nbm-conus-wind-particles or ndfd-hawaii-precip-accum.

Coverage clipping

Global models such as GFS and ECMWF HRES render worldwide. Regional models are clipped to their native model grid so data is not stretched into empty areas outside the model’s domain.

You do not add a coverage layer yourself. MapsGL applies the clip automatically for regional models that include a known grid projection (for example NBM and NDFD domains). Out-of-coverage areas are treated as nodata.

City text layers

Sample-type model layers also register a companion city-text layer, using the same pattern as temperatures / temperatures-text:

controller.addWeatherLayer('gfs-temperatures');
controller.addWeatherLayer('gfs-temperatures-text');

The text layer samples the parent model layer and is hidden until you add it. Radar and weather model layers do not get a text companion.

Use data.cities on the text layer if you need to control whether city labels are included, the same as other data query text layers.

Data quality

Model sample layers always use DataQuality.exact so model output is requested 1:1 with the map zoom. That matches the SDK default for unspecified sample quality and uses more bandwidth than blended layers that opt into high or low.

On constrained devices or connections, lower the quality when adding the layer:

controller.addWeatherLayer('gfs-temperatures', {
    data: {
        quality: aerisweather.mapsgl.DataQuality.low
    }
});

See managing data level-of-detail for the available DataQuality values.

Data inspector

When observation and model layers of the same variable are both visible, the data inspector qualifies colliding titles by model family so rows stay distinguishable — for example Temperature next to GFS Temperature.

Otherwise, model layers use the same evaluators, units, and legends as the base layer they clone. Add a data inspector control as usual.

Discovering available layers

Because availability depends on both the SDK build and each model’s datasets, do not assume every {model}-{variable} combination exists. Enumerate what this build supports from the weather provider:

const ids = controller.weatherProvider.getSupportedLayerIds();
const modelLayers = ids.filter((id) => id.startsWith('gfs-'));

For titles, categories, and other catalog metadata, use getLayerMetadata(), which also includes an optional imageUrl thumbnail per layer:

controller.weatherProvider.getLayerMetadata().then((layers) => {
    layers
        .filter((layer) => layer.id.startsWith('nbm-conus-'))
        .forEach((layer) => {
            console.log(layer.id, layer.title, layer.imageUrl);
        });
});

The weather layers listing is the published catalog, including model layers once they are listed for the release. See discovering weather layers for getSupportedLayerIds and imageUrl details.