Weather Data

The AerisWeather MapsGL SDK includes a variety of pre-configured and pre-styled weather layers for you to include in your maps, such as radar, satellite, earthquakes and storm cells. Additionally, you have complete control over their styling and can fully customize them for your needs.

Built-in weather layers are referenced by their weather layer code. Refer to our list of supported weather layers and their codes when using them within the MapsGL SDK.

Adding weather layers

To add a weather layer to your map, just use the addWeatherLayer(code: string) method on your map controller instance:

controller.addWeatherLayer('temperatures');

It's also easy to add multiple weather layers at once:

// adding each layer code separately
controller.addWeatherLayer('dew-points');
controller.addWeatherLayer('wind-dir');
 
// or iterating an array of weather layer codes
['dew-points', 'wind-dir'].forEach((code) => {
    controller.addWeatherLayer(code);
});

Using this simple method will use the default styling and configuration for each layer provided by the SDK. However, since layers are fully customizable with MapsGL, you may decide you want to change the visual appearance of one or more weather layer when adding it to your map.

Review our weather layer styling guide for complete details regarding weather layer customizations.

Getting active weather layers

Weather layers are given a unique layer identifier internally when added to a map that takes into account any customizations that may have been provided. Therefore, you cannot use getLayer(:id) to retrieve a weather layer using its weather layer code. Instead, use the getWeatherLayer(:code) method to retrieve a weather layer by its weather layer code:

const temperaturesLayer = controller.getWeatherLayer('temperatures');

If the layer already exists on the map, the above will return the existing layer instance which you can then use to get additional information about the layer itself, such as its generated unique identifier to use when adding another layer relative to its position in the layer stack:

const tempLayerId = temperaturesLayer.id;
controller.addWeatherLayer('wind-particles', null, tempLayerId);

Removing weather layers

Removing weather layers from the map is similar to adding them. To remove a weather layer from your map, just use removeWeatherLayer():

controller.removeWeatherLayer('temperatures');

Similarly, you can also remove multiple weather layers easily:

// adding each layer code separately
controller.removeWeatherLayer('temperatures');
controller.removeWeatherLayer('wind-dir');
 
// or iterating an array of weather layer codes
['temperatures', 'wind-dir'].forEach((code) => {
    controller.removeWeatherLayer(code);
});

Overriding defaults

While we have provided some default styling for built-in weather layers, you may want to fully customize them to fit the identity and style of your application or to tell a different story with the same data. Our weather layers are fully customizable simply by providing your desired configuration overrides.

You can override the default configuration for weather layers by providing a second argument to addWeatherLayer containing an object with the desired property overrides. This object should be provided in the following structure:

{
    type: LayerType;
    data: Partial<{
        quality: DataQuality;
        bounds: { north: number; south: number; west: number; east: number; };
        minZoom: number;
        maxZoom: number;
        params: Record<string, any>;
        evaluator: {
            title: string;
            fn: (value: number | Record<string, number>) => string;
        };
    }>;
    timing: Partial<{
        intervals: number;
        clamp: 'past' | 'future' | never;
        range: { start: Date; end: Date; };
    }>;
    filter: ExpressionSpecification;
    paint: Partial<PaintStyleSpec>;
    legend: Partial<LegendOptions>;
}

You can choose to override one or more elements associated with a weather layer depending on which of the above properties you provide.

For example, the following example uses the temperatures weather layer but using a lower data resolution instead:

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

Refer to our weather layer styling documentation for more details and examples on overriding default weather layers styles.

Getting layer metadata

You can retrieve useful metadata about all available weather layers that MapsGL supports. This metadata includes the layer's name, description, and other details that can be useful when building your application. To get this metadata, use the getLayerMetadata() method on your map controller's weatherProvider instance which will return a Promise that resolves with the metadata JSON object:

controller.weatherProvider.getLayerMetadata().then((data) => {
    console.log('metadata', data)
});

The metadata for each weather layer includes much of the same information as our weather layers reference documentation.